Integrate jVectorMap with SharePoint 2010 by Stephan Bren

Inttegrate jVecttorMap with h SharePointt 2010

Inttegra ate jVec j ctorM Map p wiith Sha areP Poin nt 20 010 In a few w easy Step s This book k provides steps s and tip ps for integra ating the ligh ht-weight veector-mappiing tool, jVectorM Map, with Sh harePoint Serrver 2010. By B working th through the steps in thiss book, you w will learn how w integrate and a implement common n capabilitiess, such as: building the v virtual librarries, displayin ng a vector map, m custom mizing region n popups, an nd integratin ng SharePoin nt list data.

About This Book Integrate jVectorMap with SharePoint 2010 for Fun and Profit This book is dedicated to the entry-level person interested in quickly gaining an understanding of the essential processes involved with integrating the light-weight jVectorMap vectormapping tool with the SharePoint Server 2010 framework. Published by Stephan Albert Bren November 5, 2013 Copyright ÂŠ by Stephan Albert Bren

TABLE OF CONTENTS Introduction ................................................................................................................................................ 1 Create the Package ..................................................................................................................................... 3 Create the Initial Site Page ........................................................................................................................ 5 Add a Modal Popup .................................................................................................................................. 9 Customize Region Popups...................................................................................................................... 13 Add Country Flags to Region Popups .................................................................................................. 15 Add Data to Region Popups ................................................................................................................... 17 Integrate with List Data using REST Services ...................................................................................... 19 Integrate with List Data using the List Web Service ........................................................................... 23 Summary ................................................................................................................................................... 27 References ................................................................................................................................................. 29

iii

This page intentionally blank

Integrate jVectorMap with SharePoint 2010

INTRODUCTION jVectorMap is a light-weight JavaScript-based vector mapping library developed by Kirill Lebedev. It supports the development of interactive maps that run on the client. As it is JavaScript-based, it is fully compatible with all browsers supporting JavaScript. In this article, we'll explore how to integrate jVectorMap with SharePoint Server 2010. By working through this article, you will gain experience implementing basic jVectorMap capabilities on the SharePoint platform. You'll be using SharePoint Designer 2010 as the primary development environment. We'll begin by reviewing the file and folder structure of the downloaded package, and then modifying its structure and pruning as needed. Next, we'll upload the cleaned up package to a convenient site using SharePoint Designer 2010. Then, we'll create and edit a page, adding the necessary library references and markup to present a simple map on a site page. We'll then do a few cleanup tasks and even implement a modal popup dialog. Later, we will customize the region popups and also add country flags to the popup. Next, we'll remove the embedded JSON array and instead use REST to pull the data from SharePoint list containing the region data. Finally, we'll revise the script to explore using two types of web services, REST and SOAP, to bind jVectorMap to SharePoint list data.

Introduction

Integrate jVectorMap with SharePoint 2010

1 CREATE THE PACKAGE 1) From the jVectorMap download page, download the Full Project . 2) Extract the folder, and then double-click on the index.html file in order to gain a sense of how the functioning map appears. 3) Create a new folder named jVectorMap having the following subfolders and contents: • • •

• •

•

css o jquery-jvectormap.css images o Nothing for now. This will be populated later. jQuery: o jquery-1.8.2.js o jquery-jvectormap.js o jquery-mousewheel.js js: o This will be empty for now. lib: o Leave all of the files originally in this folder unchanged.There should be a total of 24. maps: o jquery-jvectormap-map.js o jquery-jvectormap-us-aea-en.js o jquery-jvectormap-us-lcc-en.js o jquery-jvectormap-us-merc-en.js o jquery-jvectormap-us-mill-en.js o jquery-jvectormap-world-mill-en.js [root] o index.html

All other files can be deleted.

Create the Package After making these changes, you will see something like this:

You don't need to organize the jVectorMap, jQuery and other files this way. It isn't required. However, I have found this organization useful and convenient in planning for future maintenance and modification. 4) Launch SharePoint Designer 2010, and then Import the folder package to the Site Pages folder on the site.

Integrate jVectorMap with SharePoint 2010

2 CREATE THE INITIAL SITE PAGE 1) Open the original index.html file that came with jVectorMap, and review the necessary library references that will need to be added. 2) In SharePoint Designer, create a new web part page. Just one web part zone is needed. For this article, it will be named demo.aspx. 3) Checkout demo.aspx, and then open it in Advanced Mode. 4) Remove all markup between the PlaceHolderMain content tags and replace with the following: a) All of the JavaScript library references; the b) CSS reference; the c) JavaScript code; and all of the d) HTML markup between the body tags on the original page. Note: you can leave out the empty DIV tag set with height 400px. 5) Update all of the CSS and JavaScript libraries paths. 6) Open a browser, and then connect to the new page. Aside from the usual SharePoint page artifacts, you should see the map appear the same as previously:

Create the Initiate Site Page

The country shading that you see here is based upon nominal GDP in billions of US$. A link to that Wikipedia-based data is in the References section. 7) Now let's do some cleanup. We'll start by revising the button markup. Button tags cause a page reload, and this is unnecessary and distracting. Therefore, in the markup, replace all button elements with input elements, and, of course, naming them appropriately. For example, replace this markup <button id="focus-single">Focus on Australia</button>

8) with this: <input id="focus-single" name="Button1" type="button" value="Focus on Australia" />

9) Do this for the other two buttons as well. 10) After implementing this modification, clicking the Focus on Australia button should not cause a page reload. 11) Another cleanup item is the initial zoom level. Let's modify this so that the whole map is displayed when initially connecting to the page. To do this, look for the scale parameter (you'll find it in the focusOn parameter array) and set it to 1. Save the page and reload the browser to test.

Integrate jVectorMap with SharePoint 2010 12) One remaining cleanup is to implement the jQuery ready function. In demo.aspx, look for this code and comment it out or remove it: jQuery.noConflict(); jQuery(function(){ var $ = jQuery;

13) Then replace it with this single line: $(document).ready(function(){

14) This completes this procedure.

Create the Initiate Site Page

Inttegrate jVecttorMap with h SharePointt 2010

3 ADD D A MO ODAL POPU UP We'll imp plement a modal m popup p using the showModalD s Dialog meth hod of SP.UII.ModalDiallog. We'll neeed this image:

1) Add this image to the imagess folder, nam ming it help..png. ng declaratio ons to the project css filee, jquery-jveectormap.css: 2) Add the followin #help pbtn { pos sition: ab bsolute; lef ft: 5px; top p: 3px; } #help pbtn img { bor rder: 0; }

t css for th he zoom butttons to the ffollowing: 3) And then revise the .jvec ctormap-zo oomin { top p: 5px; lef ft: 55px; } .jvec ctormap-zo oomout { top p: 25px; lef ft: 55px; }

4) Closee the css file,, and then ad dd the follow wing to the demo.aspx file, just afteer the other D DIV tags in i the body section:

Add a Modal Popup <div id="helpbtn"><a href="#" class="helpDialog"><img src="image/help.png" alt="Help" /></a></div>

5) Add a simple ASP.NET page (not a Web Part page) to the Sitepages/jVectorMap folder, naming it helpdialog.aspx: 6) Open this file for editing, remove the form tags between the body tags, insert some placeholder text (e.g., lorem ipsum dolor...); and then save and close this file. 7) In demo.aspx, in the href parameter for the helpbutton, add the following: JavaScript:showHelpDialog(); 8) Then add the following JavaScript function in the same script block as the jVectorMap script: function showHelpDialog(){ var options = { title: "jVectorMap help", width: 400, height: 300, url: "helpDialog.aspx" }; SP.UI.ModalDialog.showModalDialog(options); };

9) Save and then close demo.aspx. 10) Refresh the browser, and then click on the new help button. You'll see something like this:

Integrate jVectorMap with SharePoint 2010

11) This completes this procedure.

Add a Modal Popup

Integrate jVectorMap with SharePoint 2010

4 CUSTOMIZE REGION POPUPS 1) Checkout your jVectorMap page file. 2) Open in Designer, and then click Advanced Mode. 3) In Code view, search for the series array parameter. 4) Select the opening bracket after series, right-click it, and then select Find Matching Brace. 5) Just after this matching closing brace, enter a comma (","), as you will be entering a custom event handler. 6) On a new line, after the comma, enter the following block of text: onRegionLabelShow: function(event, label, code){ label.html(' ' + label.html() + '<hr noshade="noshade" style="height: 1px"/>My text '); }

7) Save the file (but don't check it back in just yet) and then refresh the browser. 8) Move the cursor over a region, and the customized popup should appear as shown below:

Customize Region Popups

9) Just edit the text in the onRegionLabelShow event handler as desired. 10) Check the file back in. 11) This completes this procedure.

Integrate jVectorMap with SharePoint 2010

5 ADD COUNTRY FLAGS TO REGION POPUPS 1) Checkout your jVectorMap page file. 2) Create a new asset library on the target site, naming it CountryFlags. 3) Build a library of country flag images, and then rename the image files according to their digraph values. PNG image format works best. Thus, for example, Germany's flag image would be DE.PNG. If you're uncertain what digraphs to use, open the jquery-jvectormapworld-mill-en.js file. Each region entry begins with its diagraph and you'll find the country name embedded in each entry. Note that not all regions have approved digraphs, and you'll find that this JS file uses some custom digraph codes for some regions. 4) Add the library to the CountryFlag's asset library on the target site. The relative URL (with respect to the web application) to any image might be: /[yoursite]/CountryFlags/DE.PNG. 5) Revise the onRegionLabelShow event handler as follows: onRegionLabelShow: function(event, label, code){ var imgString = '<img src="/test/CountryFlags/' + code.toString() + '.png" /> ' label.html(imgString + label.html() + '<hr noshade="noshade" style="height: 1px"/>My text '); }

6) Save the file (but don't check it back in just yet) and then refresh the browser. 7) Move the cursor over a region, and the customized popup will now display with the appropriate country flag as shown below:

Add Country Flags to Region Popups

8) Check the file back in. 9) This completes this procedure.

Integrate jVectorMap with SharePoint 2010

6 ADD DATA TO REGION POPUPS 1) In SharePoint Designer, checkout your jVectorMap page file. 2) Open the target page in Code view. 3) Revise the onRegionLabelShow event handler as follows: onRegionLabelShow: function(event, label, code){ label.html('<img src="/test/CountryFlags/' + code.toString() + '.png" /> ' + label.html() + '+

'<hr noshade="noshade" style="height: 1px"/>Nominal GDP (Billions US$): chkValue(cdata[code]));

}

4) Save the file (but don't check it back in just yet) and then refresh the browser. 5) Move the cursor over a region, and the customized popup will now display with the appropriate country flag as shown below.

Add Data to Region Popups

6) Check the file back in. 7) This completes this procedure.

Integrate jVectorMap with SharePoint 2010

7 INTEGRATE WITH LIST DATA USING REST SERVICES 1) Create a new list on the target site, naming it RegionData. It has two fields: Title and GDP, both configured as text. 2) Add to this list the region data provided in the original jVectorMap package (182 regions with data). 3) Add the following to the base site URL: _vti_bin/listdata.svc. Thus, for a server-name spdev12 and site test, the REST list service URL would be: http://spdev12/test/_vti_bin/listdata.svc 4) Connect to this URL to see the list of services available. 5) Add the following to this URL: /RegionData()?$select=Title,GDP. Thus, the new URL will be: http://spdev12/test/_vti_bin/listdata.svc/RegionData()?$select=Title,GDP 6) Checkout the target page displaying the jVectorMap. 7) Open the page in Code view. 8) Remove (or comment out) this statement: $(document).ready(function(){

9) And then replace with these statements: var qryWCFUrl = "http://spdev12/test/_vti_bin/listdata.svc/RegionData()?$select=Title,GDP" ; $.getJSON(qryWCFUrl, function (results) {

Integrate with List Data using REST Services 10) Add the following block of JavaScript code just after the statements added above: var mycdata; var myString = "{"; $.each(results.d.results, function (i, item) { myString = myString + '"' + item.Title + '":"' + item.GDP + '",'; }); myString = myString.substring(0, myString.length-1) + '}'; mycdata = JSON.parse(myString);

11) Look for the values parameter in the series array. You'll find the long list of region digraph/value pairs here. This is the JSON array.

12) Remove everything between the brackets, "{" and "}", including the brackets themselves, and then replace with mycdata.

13) Also, replace cdata with mycdata in the region popup script. 14) Save the file (but don't check it back in just yet) and then refresh the browser. 15) The map displays exactly the same:

Integrate jVectorMap with SharePoint 2010

16) Check the file back in. 17) This completes this procedure.

Integrate with List Data using REST Services

Integrate jVectorMap with SharePoint 2010

8 INTEGRATE WITH LIST DATA USING THE LIST WEB SERVICE 1) Open a browser and navigate to the target site. In this instance, the target site is /Test. 2) Append the following to this URL: _vti_bin/lists.asmx in order to verify available services:

3) In SharePoint Designer, checkout your jVectorMap page file (or copy it). 4) Open the file in Code view. 5) Remove everything between the JavaScript tags, and replace with this: 23

Integrate with List Data Using the List Web Service function showHelpDialog(){ var options = { title: "jVectorMap help", width: 400, height: 300, url: "helpDialog.aspx" }; SP.UI.ModalDialog.showModalDialog(options); }; $(document).ready(function(){ //Define the SOAP envelope var soapEnv = "<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'> \ <soap:Body> \ <GetListItems xmlns='http://schemas.microsoft.com/sharepoint/soap/'> \ <listName>RegionData</listName> \ <query> \ <Query> \ </Query> \ </query> \ <viewFields> \ <ViewFields> \ <FieldRef Name='Title' /> \ <FieldRef Name='GDP' /> \ </ViewFields> \ </viewFields> \ <rowLimit>99999</rowLimit> \ <queryOptions xmlns:SOAPSDK9='http://schemas.microsoft.com/sharepoint/soap/' > \ <QueryOptions/> \ </queryOptions> \ </GetListItems> \ </soap:Body> \ </soap:Envelope>"; //Get the data via the web service call jQuery.ajax({ url: "/test/_vti_bin/lists.asmx", type: "POST", dataType: "xml", data: soapEnv, complete: ProcessListItems, contentType: "text/xml; charset=\"utf-8\"" }); //Extract the desired data from the response and build the data string function ProcessListItems(xData, status) { var myString = "{"; var mycdata; jQuery(xData.responseXML).find("z\\:row").each(function () {

Integrate jVectorMap with SharePoint 2010 myString = myString + '"' + $(this).attr("ows_Title") + '":"' + $(this).attr("ows_GDP") + '",'; }); //Final cleanup of the string and convert to JSON array object myString = myString.substring(0, myString.length-1) + '}'; mycdata = JSON.parse(myString) //Utility function to check variable contents function chkValue(val){ if (typeof val ==="undefined"){ x = 0; } else{ x = val; } return x; }; //Define event handlers $('#focus-single').click(function(){ $('#map1').vectorMap('set', 'focus', 'AU'); }); $('#focus-multiple').click(function(){ $('#map1').vectorMap('set', 'focus', ['AU', 'JP']); }); $('#focus-init').click(function(){ $('#map1').vectorMap('set', 'focus', 1, 0, 0); }); $('#get-data').click(function(){ alert(JSON.stringify(mycdata)); }); //Instantiate jVectorMap object $('#map1').vectorMap({ map: 'world_mill_en', focusOn: { x: 0.5, y: 0.5, scale: 1 }, series: { regions: [{ scale: ['#C8EEFF', '#0071A4'], normalizeFunction: 'polynomial', values: mycdata }] }, onRegionLabelShow: function(event, label, code){ label.html('<img src="/test/CountryFlags/' + code.toString() + '.png" /> ' + label.html() + '<hr noshade="noshade" style="height: 1px"/>Nominal GDP (Billions US$): ' +

Integrate with List Data Using the List Web Service chkValue(mycdata[code])); } //closes onRegionLabelShow }); //Closes jVectorMap }; //Closes ProcessListItems }); //Closes document.ready

6) Save the file (but don't check it back in just yet). 7) On the SharePoint Designer 2010 Page ribbon, click Preview in Browser.

8) The map displays exactly the same, which it should. 9) Check the file back in and close SharePoint Designer. 10) This completes this procedure.

Integrate jVectorMap with SharePoint 2010

SUMMARY This article has presented one method for integrating the light-weight jVectorMap vectormapping client with SharePoint Server 2010. It presents a simple walkthrough to expose interested readers to some of the basic features and capabilities of jVectorMap and their implementation on the SharePoint Server 2010 framework. The final SharePoint Designer 2010 page script/markup developed in this article are available in the Microsoft TechNet Gallery.

Summary

Integrate jVectorMap with SharePoint 2010

REFERENCES •

jVectorMap

•

SP.UI.ModalDialog.showModalDialog(options) Method

•

List of countries by GDP (nominal)

•

jVectorMap / SharePoint 2010 Integration Script

•

MSDN: Using the REST Interface from JavaScript

•

MSDN: Accessing the SOAP API

•

Microsoft Office Dev Center: Introduction to Collaborative Application Markup Language (CAML)

References