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

1. Overview
   1. How It Works
   2. Features
   3. Screenshots
2. How To Use
   1. Download / Files
   2. First Time Use / Use A CEWP To Render Tiles
   3. CEWP JavaScript Reference
   4. GUI
   5. Use a DVWP To Render Tiles
   6. DVWP Paramater Reference
   7. nSPTiles List Reference
3. Compatibility
4. Change Log
5. To Do / Enhancement Requests
6. Support / Issues / Contact / Help
7. References, Acknowledgement, and Gratitude
8. License
9. Disqus

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
• 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:

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.

1. 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>
   

2. make sure to provide the correct path to nSPTiles.js
3. (optional) update the path to the Font-Awesome CSS if you want to use Font-Awesome
4. update the id of the div where you want the tiles to be rendered in (nachoTiles in the above example)
5. in the nSPTiles.init call update the parameters as necessary (check below for details)
6. 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:

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:

1. add a WebPart like you normally would to the page
2. use the upload option to upload and then add the DVWP file you want: dvwp.webpart or dvwp_webURL.webpart
3. 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:

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.

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.

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

To Do / Enhancement Requests

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

• SPJS-Tiles (http://spjsblog.com/2013/11/13/sharepoint-2013-style-tiles/) by Alexander Bautz for creating the original tiling system for SharePoint
• cross-browser requestAnimationFrame (https://gist.github.com/paulirish/1579671) by Erik Möller
• generic animation using requestAnimationFrame (http://www.sitepoint.com/simple-animations-using-requestanimationframe/) by Dmitri Lau
• jQuery's easing functions (https://github.com/danro/jquery-easing/blob/master/jquery.easing.js) by George McGinley Smith
• JavaScript library to generate random, pretty colors (https://github.com/dsmagic12/randPrttyClrs) by Daniel Schauer

License

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

Disqus

jump to TOC