Managing SharePoint 2013 App Context

Scot Hillier

by Scot Hillier on 9/7/2013

Share this:
Print

Article Details

Date Revised:
12/2/2015

Applies to:
Article, Content Type, EDITORIAL USE ONLY


Originally published 9/8/2013 and reproduced here for reference

When creating SharePoint 2013 apps, you often need contextual information about the app and the user. This contextual information includes things like the URL of the host web or the account claim of the current user. While it isn’t technically difficult to get much of this information, I find that I am always writing the same code, creating hidden fields, or programmatically creating query strings. I also get annoyed by the fact that I have to rebuild the context for every page in the app. What I really wanted was a simple library that maintains context throughout the current session. To solve the problem, I created 2 libraries for managing context: one for SharePoint-Hosted Apps (wingtip.context.js) and one for Cloud-Hosted Apps (wingtip.remotecontext.js).

You can download the libraries and sample apps from here.  Basic sample code appears later in this article.

Both context libraries provide the same information. The difference is that the Cloud-Hosted App library (wingtip.remotecontext.js) uses the cross-domain library to get the contextual information while the SharePoint-Hosted App library (wingtip.context.js) just uses jQuery ajax. In addition to retrieving the contextual information, the libraries also cache the values using HTML 5 Session Storage so that you can use the contextual information across page calls. The following tables list the available contextual data in three tables: Base Contextual Information, Geolocation Information, and User Information.

Basic Contextual Information

Key

Description

AppQueryString

This is the complete encoded query string stripped from the launch URL. This can be attached to subsequent URL links to maintain context if the current browser does not support Session Storage.

BaseContextStatus

A message indicating the status of the context. Possible values are “undefined”, “success”, or a serialized JSON error object.

ContextCreated

The timestamp when the current context was created.

ContextModified

The timestamp when the current contextual information was modified.

SenderId

The identifier used when requesting an App Part resize with postMessage.

SessionStorageSupport

A Boolean value indicating if the current browser supports HTML5 Session Storage.

SiteFullUrl

The Full URL of the Site Collection hosting the app.

SPAppWebUrl

The decoded value of the SPAppWebURL query string parameter.

SPClientTag

The decoded value of the SPClientTag query string parameter.

SPLanguage

The decoded value of the SPLanguage query string parameter.

SPLibraryVersion

The decoded value of the SPLibraryVersion query string parameter.

SPHostUrl

The decoded value of the SPHostUrl query string parameter.

SPProductNumber

The decoded value of the SPProductNumber query string parameter.

FormDigest

The value of the FormDigest for use with list item updates.

FormDigestTimeout

The lifetime of the FormDigest in milliseconds.

FormDigestValid

A Boolean value indicating if the current FormDigest is valid. A setTimeout function is used to invalidate the FormDigest based on the value in the FormDigestTimeout property.

WebFullUrl

The Full URL of the App Web.

 

Geolocation Information

Key

Description

GeoLocationStatus

A message indicating the status of the Geolocation context. Possible values are “undefined”, “success”, or an error message.

GeoLocationValid

A Boolean value indicating if the current Geolocation information is valid.

Latitude

The latitude of the current user.

Longitude

The longitude of the current user.

 

User Information

Key

Description

UserContextStatus

A message indicating the status of the user context information. Possible values are “undefined”, “success”, or serialized JSON error object.

LoginName

The account claim for the current user.

DisplayName

The display name of the current user.

Email

The email address of the current user.

 

Using the Libraries

In order to use one of the libraries, simply add them to your project and reference it in the standard way as shown in the following sample code.

<script type="text/javascript" src="wingtip.contextinfo.js"></script>

After referencing the desired library, the context can be initialized. The libraries support initializing the portion of the context you are interested in (init_base(), init_location(), and init_user()). The libraries utilize promises in a when…done pattern so that you can detect when the initialization is complete and move on with your app functionality. The following code shows how to fully initialize the contextual information and receive notification when it’s complete.

'use strict';

window.Wingtip = window.Wingtip || {};

 

$(document).ready(function () {

    $.when( Wingtip.ContextInfo.init_base(),

           Wingtip.ContextInfo.init_user(),

     Wingtip.ContextInfo.init_location()).done(

        function () {

//Code here will execute
//when the context is fully initialized

        }

    );

});   

Once initialized, you can access any of the properties using code similar to the following sample:

alert(Wingtip.ContextInfo.get_context().GeoLocationValid);

That’s all there is to it! Now, with just a few lines of code you can maintain critical contextual information for the duration of the current app session.

 


Topic: Article

Sign in with

Or register