A Worldmap list visualization for SharePoint (Online)

worldmap

I really like the way you can use SharePoint’s Client Side Rendering to alter the way list data is viewed. Earlier posts featured a notice board and jQuery DataTables, but this time I’d like to present my SharePoint list data in yet another non-standard way: as a World Map.

This particular view is known as a choropleth and is powered by a simple SharePoint list with two columns. One column holds the country code and one column the key (High 1-3, Mid 1-3, Low 1-3) that corresponds to the color on the map:

list

Apart from a SharePoint list that functions as a data backend, we need some JavaScript to create this particular data visualization. Most of this is taken care of by Datamaps (by Mark DiMarco) that provides visualizations based on geographical data. It’s SVG-based, can scale to any screen size, and includes everything inside of 1 script file. On its part, that script heavily relies on the amazing D3.js library.

  • d3.min.js: a library for manipulating documents based on data using HTML, SVG, and CSS.
  • topojson.min.js: support library for representing geometries using JSON.
  • datamaps.world.min.js: DataMaps Worldmap in JSON.
  • worldmapListView.js : the actual JSLink file which we will create in the next step.
Creating the listview

First thing we need to setup is our template registration. This registration is fairly simple as it basically only contains the container HTML structure and the ID of the List Type we are operating on. To make this work correctly with the Minimal Download Strategy (MDS), I follow the guidance in Wictor Wilen’s excellent post on MDS: “The correct way to execute JavaScript functions in SharePoint 2013 MDS enabled sites

The important part is the function that is added as part of the registration and executed on Post Render. This function takes care of creating the actual Datamap visualization:

Type.registerNamespace('Demo')
Demo.WorldMap = Demo.WorldMap || {};
Demo.WorldMap.Functions = Demo.WorldMap.Functions || {};
    
Demo.WorldMap.Functions.RegisterTemplate = function () {
    var itemCtx = {};
    Demo.WorldMap.mapData = {};

    itemCtx.Templates = {};
    itemCtx.Templates.Header = "<div id='worldMapListView' style='position: relative; width: 690px; height: 480px;' >"
    itemCtx.Templates.Item = Demo.WorldMap.Functions.ItemOverrideItems;
    itemCtx.Templates.Footer = "</div>";
    itemCtx.ListTemplateType = 100;
    itemCtx.OnPostRender = [];

	itemCtx.OnPostRender.push(function () {
        var map = new Datamap({
            element: document.getElementById('worldMapListView'),
            projection: 'mercator',
            fills: {
				L1: '#fff5f0',
				L2: '#fee0d2',
				L3: '#fcbba1',
				M1: '#fc9272',
				M2: '#fb6a4a',
				M3: '#ef3b2c',
				H1: '#cb181d',
				H2: '#a50f15',
				H3: '#67000d',
                UNKNOWN: '#C0C0C0',
                defaultFill: '#C0C0C0'
            }, 
            data: Demo.WorldMap.mapData,
			done: function(datamap) {
			   datamap.svg.call(d3.behavior.zoom().on("zoom", redraw));

			   function redraw() {
					datamap.svg.selectAll("g").attr("transform", "translate(" + d3.event.translate + ")scale(" + d3.event.scale + ")");
			   }
			}
        });
    });
	
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(itemCtx);
}

Color codes are rated as 10 levels (Low 1-3, Mid 1-3, High 1-3 and Unknown) and hardcoded as part of this example. The actual data needed for the map is constructed during the list item override function:

Demo.WorldMap.Functions.ItemOverrideItems = function (ctx) {
    var countryData = {};

    countryData.fillKey = ctx.CurrentItem.fillKey;
    Demo.WorldMap.mapData[ctx.CurrentItem.Title] = countryData;
    return "";
}

We save all of this code to a separate JSLink JavaScript file so we can reference it from our Web Part properties.

Setting it up

The setup of the solution is easy since you just need to copy the files to a shared location (for instance the Style Library, Asset Library or Master Page gallery. The key is to have the support files loaded on the page you enable this view on. As mentioned earlier, there are multiple ways to achieve this, but personally I like to use Custom Actions for this and I included some example PowerShell in the download file.

Just remember, you only need the support files pre-loaded on the page and not the actual JSLink file. We reference that from our Web Part properties:

js

To be able to color the map, we need the “fillKey” field and we should include it in the view:

viewprops

Once saved and published, the page should show the world map in all its glory. Furthermore, DataMaps has tons of options for you to play with, so you might want to try a couple of configurations yourself.

Download the sample files here: Blog.Examples.Worldmap

/Y.

Advertisements

5 comments

  • great post. new at this and would like to apply this to my sharepoint site. What would be the name of the Custom List to create those two columns. Where in the JS files do I let the script know to get the data from the SharePoint list?

    thanks

    • Thanks for trying this out Mark. The list can be any custom list, you just need to configure the JS Link property to point to your JS file. See the first screenshot in the “Setting it up” section. The JS files can be stored in a document library (e.g. Style Library or Site Assets). /Y

  • So basically I am placing the Content Editor webpart on the View Page of the list, or do I point the default Web Part for the list on the view page to the JSfile?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s