nSPTiles

nSPTiles is an easy to use JavaScript library for Windows style live tiles for SharePoint with numerous styling options and an admin GUI.

Table of Contents

Overview

You know those live tiles that Windows 8 has? nSPTiles is a library that lets you create something like them in SharePoint.

nSPTiles is my my own version of (and wouldn't have been possible without) SPJS-Tiles by Alexander Bautz. You can find his at http://spjsblog.com/2013/11/13/sharepoint-2013-style-tiles/.

After I started using SPJS-Tiles more and more I had a need for some enhancements and additional features -- specifically a DVWP way to render the tiles so they load faster and a GUI to make it easier to add tiles. And so I set out to address my needs and ended up with nSPTiles.

How It Works

The first time you use nSPTiles a SharePoint list called nSPTiles#_# is created. The list will be used to hold the tile data. It has numerous fields/columns for the various tile options/settings. There are also numerous calculated columns that are used internally by nSPTiles.

After the list is created you can add items to the list. Each item in the list is a different tile. Tiles can be grouped by using the same group name . This way you can render different tiles on different pages/sections.

It is important that you do not change any of the list settings, especially the calculated columns.

Features

nSPTiles is self-contained and does not need any additional JavaScript libraries like jQuery

is self-contained and does not need any additional JavaScript libraries like jQuery uses SharePoint's built-in list system

GUI to help with tile placement

CEWP/JavaScript or DVWP for rendering

each tile can have: a link a background color a tile image a Font-Awesome icon (*requires FA be configured) a tile heading slider text that slides up on hover different color/image/FA/heading when the mouse is over a tile (hovering) unique permissions to control who can see what tiles (new in 1.5)

quickly specify placement for tile image, Font-Awesome icon, heading text and slider text without custom CSS

numerous pre-set styling options

additional styling can be applied with custom CSS

three tile animation options (slide, bounce and elastic)

version 1.5 will import tiles from version 1.4

Screenshots

Screenshot Description On first use nSPTiles will ask you to create the list used to store all tile data. The list has been created. If you have access to add items to the list then when you hover your mouse over the tiles it will let you use a GUI to add, move, edit or delete tiles. The GUI to add a new tile... The GUI to add a new tile... The added tile.

How To Use

These instructions assume you know your way around SharePoint (how to upload files and edit them, add CEWPs or DVWPs and edit their configuration options, call JavaScript functions, etc...)

The very first time you use nSPTiles follow the CEWP instructions.

Download / Files

Download the latest nSPTiles.#.#.zip file from https://github.com/imthenachoman/nSPTiles/releases. It consists of:

File Name Description Destination nSPTiles.js nSPTiles javascript (packed using http://dean.edwards.name/packer/) upload to your SharePoint site; you will need it's path dvwp.webpart DVWP WebPart save on your computer

Installation

Upload the nSPTiles.js file to a document library in your SharePoint site. You will need to know it's path later.

First Time Use / Use A CEWP To Render Tiles

*** The first time you use nSPTiles you will see a message like this. Follow the instructions to create the nSPTiles#_# list. ***

A CEWP uses client-side JavaScript to pull information from the nSPTiles#_# list using SharePoint's REST API. The code is configured to run on page load which means the tiles should be visible before the page is drawn, however, this does add a slight delay to the page load.

add a CEWP to a WebPart page and add code like below (either directly in the CEWP source code editor or link to an HTML file) < script src = " nSPTiles.js " type = " text/javascript " ></ script > < link rel = " stylesheet " href = " font-awesome.min.css " > < div id = " nachoTiles " ></ div > < script type = " text/javascript " > nSPTiles. init ( " nachoTiles " , " group one " ); </ script > make sure to provide the correct path to nSPTiles.js (optional) update the path to the Font-Awesome CSS if you want to use Font-Awesome update the id of the div where you want the tiles to be rendered in ( nachoTiles in the above example) in the nSPTiles.init call update the parameters as necessary (check below for details) save everything and reload the page

Now you can use the GUI to add/move/edit/delete tiles.

CEWP JavaScript Reference

The nSPTiles.init function takes three parameters:

nSPTiles.init(holderID, groupNameOrUrlKey)

-- OR --

nSPTiles.init(holderID, groupNameOrUrlKey, configOptions)

Paramater Reference:

parameter required explanation holderID yes the ID of the div where you want the tiles to be created in ( nachoTiles in the above example) groupNameOrUrlKey yes the name of the tiles group to use ( group one in the above example) or the name of a URL key from which to get the group name configOptions optional a configuration object with the following options:



animationTime number the number of milliseconds tile animations should take animationTypeOn string the type of animation to use when the mouse enters a tile (for zooming and sliding)



options are:



slide

bounce

elastic animationTypeOff string the type of animation to use when the mouse leaves a tile; same options as above webURL string URL of the web where the nSPTiles list is (or should be created) (e.g. '/' , '/subsite1' , '/subsite1/subsite2' ) onclick function function to call on tile clicks. can be used to run custom code like you would need for Piwik's click tracking. the function will be passed three paramaters:



the url

the type of link the tile is

`holderID`

the tiles group name

the tile HTML ID

the tile SharePoint list ID example:

function(url, type, holderID, groupName, tileID, ID){...} oninit function function to call before tiles are loaded. the function will be passed two paramaters:



`holderID`

the tiles group name example:

function(holderID, groupName){...} oncomplete function function to call after tiles are done loading. the function will be passed two paramaters:



`holderID`

the tiles group name example:

function(holderID, groupName){...}

Examples:

nSPTiles.init("nachoTiles", "group 1", {animationTime: 250}); nSPTiles.init("nachoTiles", "group 2", {animationTypeOn: "bounce"}); nSPTiles.init("nachoTiles", "group 3", {animationTypeOff: "slide"}); nSPTiles.init("nachoTiles", "group 4", { animationTime: 250, animationTypeOn: "bounce", animationTypeOff: "elastic" }); nSPTiles.init("nachoTiles", "group 4", { webURL: "/subsite" }); nSPTiles.init("nachoTiles", "group 4", { webURL: "/subsite/subsite", onclick: function(url, type, holderID, groupName, tileID, ID) { // register a click event in Piwik _paq.push(['trackLink', url, 'link']); } }); // in the below example // if groupName is a paramater passed in the URL // then it will use that parameter's value // i.e. for the url "http://sp/home.aspx?groupName=homepage%20tiles" the groupName will be"homepage tiles" nSPTiles.init("nachoTiles", "groupName");

GUI

If you have permissions to add items to the nSPTiles#_# list then when you hover over the area where the tiles are (or should/would be) then you'll see admin links that will let you add, move, clone, edit, or delete tiles or get info about a tile. The add, move, and clone options will let you use a GUI to draw where you want the tile to be within the container. The move, clone, edit, delete, and info options will let you select a tile you want to work on.

Use a DVWP To Render Tiles

****** IMPORTANT ******

DO NOT add the DVWP WebPart to a page until you've used a CEWP at least once so the nSPTiles#_# list has been created.

****** IMPORTANT ******

A DVWP pulls the tile data on the server side in an XML format then passes it through an XSL transformation before it it sends to the browser for rendering. Because it is done server-side the page load should be slightly faster.

NOTE: Because of deficiencies in how SharePoint manages DVWP WebParts, if you need to use a nSPTiles#_# list that is on a different SharePoint site then you need to edit the file before you can upload it to a WebPart page. Open the file in any text editor, search for the string <asp:Parameter DefaultValue="/" Name="WebURL"></asp:Parameter> (should be line 296) and change the value inside the "" for the DefaultValue attribute to the site URL and then save the file. For example: /subsite , /sites/teamSite , etc...

To add the DVWP to a WebPart page:

add a WebPart like you normally would to the page use the upload option to upload and then add the DVWP file you want: dvwp.webpart or dvwp_webURL.webpart use the Parameters Editor option to change the parameters to your needs.

DVWP Paramater Reference

DVWP paramaters look like this:

< ParameterBinding Name = " nSPTilesJSPath " Location = " None " DefaultValue = " nSPTiles.js " /> < ParameterBinding Name = " FontAwesomeCSSPath " Location = " None " DefaultValue = " font-awesome.min.css " /> < ParameterBinding Name = " GroupName " Location = " None " DefaultValue = " group one " /> < ParameterBinding Name = " AnimationSpeedInMillisecond " Location = " None " DefaultValue = " 100 " /> < ParameterBinding Name = " AnimationTypeOn " Location = " None " DefaultValue = " slide " /> < ParameterBinding Name = " AnimationTypeOff " Location = " None " DefaultValue = " bounce " /> < ParameterBinding Name = " TileOnClick " Location = " None " DefaultValue = " function(url,type){} " />

Change the DefaultValue as you need.

Check CEWP JavaScript Reference for details on each parameter. The DVWP parameters match the respective JavaScript paramaters:

DVWP paramater name CEWP paramater name Note nSPTilesJSPath n/a the path to the nSPTiles.js file FontAwesoeCSSPath n/a optional path to the Font-Awesome CSS GroupName n/a in the DVWP it is not possible to get this value from a URL paramater AnimationSpeedInMillisecond animationTime AnimationTypeOn animationTypeOn AnimationTypeOff animationTypeOff TileOnClick onclick the string value of TileOnClick can be a function string or a function name (i.e. "function(url, type){}" or "someFunction" )

nSPTiles List Reference

Here are all the tile options and what they mean. Each one maps to a column/field in the nSPTiles#_# list. Not all fields are required and not all fields are relevant depending on other settings.

option

(field/column name) description group name the group this tile belongs to active can be used hide a tile without having to remove this entry heading and slider content heading content can use HTML heading content on hover slider body content can use HTML layout tile width the width of the tile in px tile height the height of the tile in px tile left offset the left offset of the tile in px tile top offset the top offset of the tile in px tile border width the empty space around the tile in px tile zoom on hover zoom effect for the tile by making the tile border width 0 when the mouse is over the tile is heading heading tiles have no slider link tile link type the type of link to make

none

current window - open link in the current window

- open link in the current window new window - open link in a new window

- open link in a new window mailto - open mail

- open mail dialog - open link in a dialog

- open link in a dialog dialog (refresh window after save) - open link in a dialog and refresh the window if the user saves

- open link in a dialog and refresh the window if the user saves dialog (refresh tiles after save) - open link in a dialog and refresh the tiles if the user saves

- open link in a dialog and refresh the tiles if the user saves sub-group - open a sub tile group

- open a sub tile group javascript - execute javascript tile link URL the URL for the link image tile image URL URL of image to use in tile (must be less then 255 characters) tile image width width of tile image. use just a number to specify in px or end with a % (e.g. 50 or 75%)



helpful if the image is larger then the icon tile image height height of tile image. use just a number to specify in px or end with a % (e.g. 50 or 75%)



helpful if the image is larger then the icon tile image opacity opacity from 0 (transparent) to 100 (solid)



leave blank for none tile image padding how far from the edge of the tile should the image be in px tile image style css style to apply to the tile image (overrides above tile image options) tile image position position of the image in the tile tile image URL on hover tile image style on hover Font Awesome tile FA class Font Awesome icon class name tile FA color HTML/CSS friendly color or .className (e.g.: red, #0099ff, rgb(0,150,255), .color1) tile FA opacity opacity from 0 (transparent) to 100 (solid)



leave blank for none tile FA padding how far from the edge of the tile should the icon be in px tile FA style css style to apply to the FA icon (overrides above tile FA options) tile FA position position of the icon in the tile tile FA class on hover tile FA style on hover tile FA HTML override custom HTML to override the tile Font-Awesome icon class, color, opacity, padding, and style.



can be used to do custom things like stacked icons and animations background tile background color HTML/CSS friendly color or .className (e.g.: red, #0099ff, rgb(0,150,255), .color1) tile background opacity opacity from 0 (transparent) to 100 (solid)



leave blank for none tile background color on hover tile background opacity on hover heading style heading bolded should the heading text be bold heading font color HTML/CSS friendly color or .className (e.g.: red, #0099ff, rgb(0,150,255), .color1) heading font size font size for the heading in px heading padding padding for the heading in px heading style css style to apply to heading (overrides above heading options) heading position position of the heading in the tile or slider heading heading style on hover slider style slider heading height height of the header for the slider in px slider body font color HTML/CSS friendly color or .className (e.g.: red, #0099ff, rgb(0,150,255), .color1) slider body font size font size for the slider body in px slider body padding padding of the slider body in px slider body style css style to apply to slider body (overrides above slider body options) slider body position position of the slider body in the slider slider background color HTML/CSS friendly color or .className (e.g.: red, #0099ff, rgb(0,150,255), .color1) slider background opacity opacity from 0 (transparent) to 100 (solid)



leave blank for none slider background color on hover slider background opacity on hover misc tile image and FA slider heading push if the tile image and/or FA are positioned on the bottom then push them on top of the slider heading tile custom ID custom ID to use for the tile



default is nTile_[ID] where ID is the ID of the entry in the list tile custom class(es) custom class(s) to add to the tile tile HTML override override all header and slider settings and use this HTML for the tile content instead view permissions tile view permissions who should be able to see this tile



leave blank for everyone



note: this only controls if a tile is drawn or not -- it does not prevent the user from seeing this list item in the list tile not rendered check only show this tile if the tile with this ID is not rendered

Position Options

The various options that have a related position option allow you to have control of placement within the tile. The choices are:

top left

top center

top right

middle left

middle center

middle right

bottom left

bottom center

bottom right

Color Options

For the various options that have a color option you can specify a color using an HTML/CSS friendly color name or a CSS class name prefixed with a . .

Using a class name makes it easier if you have pre-defined CSS classes in a style-sheet with the colors you want. Keep in mind CSS class definitions that apply other non-color settings could have undesirable effects.

Examples:

#ff00ff , #f0f0f0

, #f0f , #ff0

, rgb(0, 100, 200)

yellow

.themeColor1 , .themeColor2 , .themeColor2 (notice the . before the class name)

Compatibility

I have tested nSPTiles in the following environments as these are all I have access to.

SharePoint Version IE Chrome FireFox 2010 Foundation IE 11 Chrome 44 Firefox 39 2010 Server IE 11 Chrome 44 - 2013 Online IE 11 Chrome FIrefox 45 2013 Server IE 11 Chrome FIrefox 45

If anyone is able to test on other SharePoint installations and/or browsers, or knows where I can access/test on other SharePoint installations, I would appreciate feedback.

Change Log

version updates 1.0 initial release 1.1 fixed a bug where when cloning a tile the info tile still said "New"

for the admin menu, hovering over the tiles now shows "..." until the mouse is over the "..." 1.2 added a handler for mailto links

fixed an issue where commas are used for decimal in certain regions but CSS expects a period for the opacity value 1.3 fixed an issue where commas are used for decimal in certain regions but CSS expects a period for the opacity value (for real this time) 1.4 fixed issue 2 - mailto links (https://github.com/imthenachoman/nSPTiles/issues/2)

fixed issue 3 - spaces in links (https://github.com/imthenachoman/nSPTiles/issues/3) 1.5 issue 4 - run javascript on tile click

added a tile HTML override option

added a tile FA HTML override option

added a tile view permissions

added ability to add/move/clone tiles in bulk 1.5.1 pure javascript update; does not create a new list

fixed issue #5 - fixed bug with IE 11 not reading XPATH

fixed issue #6 - fixed bug where SITE_URL would not take the websites port into account

added issue #7 - load tiles based on URL paramater

added issue #11 - added two links two new/edit form

added issue #12 - added `oninit` and `oncomplete` functions

included a modified version of randPrttyClrs, a JavaScript library to generate random, pretty colors (https://github.com/dsmagic12/randPrttyClrs) by Daniel Schauer, for the new tile background colors

To Do / Enhancement Requests

publish initial 1.0 release allow an alternate WebURL to use nSPTiles#_# from a different SP site allow running a custom function on tile click (can be used to run custom code to do things like Piwik click tracking) real-time preview of tiles in the data sheet view of the nSPTiles#_# list so you can see the effect of your changes immediately allow stacking of Font-Awesome icons (added November 2015 by request from J. Mayo) allow for custom dialog dimensions/options (added August 2016 by request from J. Mayo) provide spreadsheet of sample data (including all scenarios but specifically FA samples) for testing purposes (added August 2016 by request from nyalex) custom tile permissions (not sure how????) (added August 2016 by request from Randy) ... ... ...waiting for ideas/enhancement from users

Support / Issues / Contact / Help

If you are familiar with GitHub and know how to submit issues then please do so at https://github.com/imthenachoman/nSPTiles/issues. Or if you prefer you can e-mail me at imthenachoman (at) gmail (dot) com. You may also leave comments here.

References, Acknowledgement, and Gratitude

License

MIT License - https://github.com/imthenachoman/nSPTiles/blob/master/LICENSE

Disqus

Please enable JavaScript to view the comments powered by Disqus.

Disqus

jump to TOC