Introduction to the Geolocation Field

I’ll showcase what the Geolocation field can do for us in a SharePoint list. In the sample below I’ve used a list called “Scandinavian Microsoft Offices” which contains a few office names (Sweden, Denmark, Finland and Norway). What I want to do in my list is to display the location visually to my users, not only the name and address of the location. With the new Geolocation field you can display an actual map, as I’ll show you through right now – skip down to the “Adding a Geolocation Field to your list” section if you want to know how to get the same results yourself.

A plain SharePoint list before I’ve added my Geolocation field

As you can see, no modifications or extra awesomeness exist in this list view – it’s a vanilla SharePoint 2013 list view.

The same list, with the Geolocation field added to it

When we’ve added the Geolocation field to support our Bing Maps, you can see that a new column is displayed in the list view and you can interact with it. In my sample here I’ve filled in the coordinates for the four Microsoft offices I’ve listed in my list.

Pressing the small globe icon will bring up a nice hover card kind of dialog with the actual map, with options to view the entire map on Bing Maps as well (which is essentially just a link that’ll take you onwards to the actual bing map):

Viewing an actual list item looks like this, with the map fully integrated by default into the display form:

And should you want to Add or Edit a list item with the Geolocation field, you can click either “Specify location” or “Use my location“. If you browser supports the usage and tracking of your location, you can use the latter alternative to have SharePoint automagically fill in your coordinates for you. Compare it with how you check in at Facebook and it recognizes your current location and can put a pin on the map for you.

In my current setup I don’t have support for “Use my location” so I’ll have to go with the “Specify location” option – giving me this pretty dull dialog:

As you can see, you don’t have an option for searching for your office on Bing Maps and then selecting the search result and have it automatically insert the correct Lat/Long coordinates. But, that’s where developers come in handy.

Create a new Map View

Let’s not forget about this awesome feature – you can create a new View in your list now, called a “Map View”, which will give you a pretty nice map layout of your tagged locations with pins on the map. Check these steps out:
1) Head on up to “List” -> “Create View” in your List Ribbon Menu:

2) Select the new “Map View”

3) Enter a name, choose your fields and hit “Ok”

4) Enjoy your newly created out of the box view in SharePoint. AWESOME

Adding a Geolocation Field to your list

Right, let’s move on to the fun part of actually adding the field to our list. I’m not sure if it’s possible to add the field through the UI in SharePoint but you can definitely add it using code and scripts, which is my preferred way to add stuff anyway.

Adding a Geolocation field using PowerShell

With the following PowerShell snippet you can easily add a new Geolocation field to your list:

Add-PSSnapin Microsoft.SharePoint.PowerShell

$web = Get-SPWeb "http://tozit-sp:2015"

$list = $web.Lists["Scandinavian Microsoft Offices"]

$list.Fields.AddFieldAsXml(

    "",

    $true,

    [Microsoft.SharePoint.SPAddFieldOptions]::AddFieldToDefaultView)

Adding a Geolocation field using the .NET Client Object Model

With the following code snippet for the CSOM you can add a new Geolocation field to your list:

// Hardcoded sample, you may want to use a different approach if you're planning to use this code :-)

var webUrl = "http://tozit-sp:2015";

ClientContext ctx = new ClientContext(webUrl);

List officeLocationList = ctx.Web.Lists.GetByTitle("Scandinavian Microsoft Offices");

officeLocationList.Fields.AddFieldAsXml(

    "", 

    true, 

    AddFieldOptions.AddToAllContentTypes);

officeLocationList.Update();

ctx.ExecuteQuery();

Adding a Geolocation field using the Javascript Client Object Model

With the following code snippet for the JS Client Object Model you can add a new Geolocation field to your list:

function AddGeolocationFieldSample()

{

    var clientContext = new SP.ClientContext();

    var targetList = clientContext.get_web().get_lists().getByTitle('Scandinavian Microsoft Offices');

    fields = targetList.get_fields();

    fields.addFieldAsXml(

        "",

        true,

        SP.AddFieldOptions.addToDefaultContentType);

    clientContext.load(fields);

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onContextQuerySuccess), Function.createDelegate(this, this.onContextQueryFailure));

}

Adding a Geolocation field using the Server Side Object Model

With the following code snippet of server-side code you can add a new Geolocation field to your list:

// Assumes you've got an SPSite object called 'site'

SPWeb web = site.RootWeb;

SPList list = web.Lists.TryGetList("Scandinavian Microsoft Offices");

if (list != null)

{

    list.Fields.AddFieldAsXml("",

        true,

        SPAddFieldOptions.AddFieldToDefaultView);

}

Be amazed, its that easy!

Bing Maps – getting and setting the credentials in SharePoint

Okay now I’ve added the fields to my lists and everything seems to be working out well, except for one little thing… The Bing Map tells me “The specified credentials are invalid. You can sign up for a free developer account at http://www.bingmapsportal.com“, which could look like this:

Get your Bing Maps keys

If you don’t have any credentials for Bing Maps, you can easily fetch them by going to the specified Url (http://www.bingmapsportal.com) and follow these few simple steps.
1) First off (after you’ve signed up or signed in), you’ll need to click on the “Create or view keys” link in the left navigation:

2) Secondly, you will have to enter some information to create a new key and then click ‘Submit’:

After you’ve clicked ‘Submit’ you’ll be presented with a list of your keys, looking something like this:

Great, you’ve got your Bing Maps keys/credentials. Now we need to let SharePoint know about this as well!

Telling SharePoint 2013 what credentials you want to use for the Bing Maps

Okay – so by this time we’ve created a Geolocation field and set up a credential for our key with Bing Maps. But how does SharePoint know what key to use?
Well that’s pretty straight forward, we have a Property Bag on the SPWeb object called “BING_MAPS_KEY” which allows us to configure our key.
Since setting a property bag is so straight forward I’ll only use one code snippet sample to explain it – it should be easily translated over to the other object models, should you have the need for it.

Setting the BING MAPS KEY using PowerShell on the Farm

If you instead want to configure one key for your entire farm, you can use the Set-SPBingMapsKey PowerShell Cmdlet.

Set-SPBingMapsKey -BingKey "FFDDuWzmanbiqeF7Ftke68y4K8vtU1vDYFEWg1J5J4o2x4LEKqJzjDajZ0XQKpFG"

Setting the BING MAPS KEY using PowerShell on a specific Web

Add-PSSnapin Microsoft.SharePoint.PowerShell

$web = Get-SPWeb "http://tozit-sp:2015"

$web.AllProperties["BING_MAPS_KEY"] = "FFDDuWzmanbiqeF7Ftke68y4K8vtU1vDYFEWg1J5J4o2x4LEKqJzjDajZ0XQKpFG"

$web.Update()

Update 2013-03-31: More examples of setting the property bag
I got a comment in the blog about having more examples for various approaches (like CSOM/JS and not only PowerShell). Sure enough, here comes some simple samples for that.

Setting the BING MAPS KEY using JavaScript Client Object Model on a specific Web

var ctx = new SP.ClientContext.get_current();

var web = ctx.get_site().get_rootWeb();

var webProperties = web.get_allProperties();

webProperties.set_item("BING_MAPS_KEY", "FFDDuWzmanbiqeF7Ftke68y4K8vtU1vDYFEWg1J5J4o2x4LEKqJzjDajZ0XQKpFG");

web.update();

ctx.load(web);

// Shoot'em queries away captain!

ctx.executeQueryAsync(function (){

    alert("Success");

},function () {

    alert("Fail.. Doh!");

});

Setting the BING MAPS KEY using .NET Client Object Model on a specific Web

// Set the Url to the site, or get the current context. Choose your own approach here..

var ctx = new ClientContext("http://tozit-sp:2015/");

var siteCollection = ctx.Site;

ctx.Load(siteCollection);

var web = siteCollection.RootWeb;

ctx.Load(web, w => w.AllProperties);

ctx.ExecuteQuery();

var allProperties = web.AllProperties;

ctx.Load(allProperties);

// Set the Bing Maps Key property

web.AllProperties["BING_MAPS_KEY"] = "FFDDuWzmanbiqeF7Ftke68y4K8vtU1vDYFEWg1J5J4o2x4LEKqJzjDajZ0XQKpFG";

web.Update();

ctx.Load(web, w => w.AllProperties);

ctx.ExecuteQuery();

So that’s pretty straight forward. Once you’ve set the Bing Maps Key, you can see that the text in your maps has disappeared and you can now start utilizing the full potential of the Geolocation field.

Share Your Thoughts

Sunday, June 22, 2014

SP 2013: Getting started with the new Geolocation field in SharePoint 2013