SharePoint client side customization – use of the URL hash

Recently I came across an issue with SPServices where it is not properly removing the hash portion (everything after the ‘#’ sign) of an URL when no search parameters are present. The exchange I had with Marc (@sympmarc) led me to believe that not allot developers are using the hash to store page state. But their application design should take into consideration how storing data there can help improve the user experience (UX). Specially as more SharePoint customizations move to the client side (browser).

In my (limited) working with SharePoint I have developed single-page client side applications where the page state is manipulated to display the proper state based on user interaction – all without requiring a page post-back. All needed data is retrieved in the background using asynchronous calls and custom UI widgets are used. I use the hash portion of the URL to store the state of the page as this happens. Why, you may be asking? So that the URL can be used to directly access the specific state. Users can bookmark the page or send it to others being assured that when loaded again the page will display the same information as when the URL was initially copied. The end result is similar to filtering a list’s ‘All Items.aspx’ to show only the desired data: once done, one can bookmark that page for quick access.

Yeah, the same could be achieved by storing the data in the normal search parameters section of the URL location object (everything after the ‘?’ mark and before the ‘#’ sign if present), but you cannot set the search portion of a URL without triggering a browser post-back. The hash, on the other hand, can be manipulated and the user never even notices.

Here is a real world example on a recent project. A few weeks ago I was asked to put together a page to show different metrics across a few projects. The page needed to show a high level rollup of all the projects as well as views per project and within each project, the ability to show/hide certain metrics – thus allowing customization by the end user. After learning a little more about the audience for this page and how they would be using it, two common use cases kept coming up:

  • Once I have my view customized, I want to bookmark that view so that in don’t have to do it again
  • I will need to share reports (via URL) with other team members and upper management

The solution was to save the state of the page by adding key=value parameters to the URL’s hash. When the page is initially loaded, and before the default view is shown, the hash portion of the URL is checked for known data and if found, the state is recreated automatically. Here is an example of such a url:

You can even use SharePoint’s built in GetUrlKeyValue() function to retrieve the values, as long as you place that first ‘&’ sign after the hash

GetUrlKeyValue("release", true, location.hash) // Return 3.0

I have used this method in addition to the search parameters to pass data around between pages and trigger functionality such as:

  • Pre-pop form elements
  • Trigger background data retrieval and in some cases updates

As the future of SharePoint pushes customizations away from SharePoint designer to the browser, I will certain use this practice allot more.


2 thoughts on “SharePoint client side customization – use of the URL hash

  1. Hi Paul! Thanks for the aspiring blog post. Using hash makes even SharePoint more a SPA which provides a better user expierience. I will absolutely try it out, too. I have even heard much about sammy.js which simplifies hash handling. And what about SharePoint 2013. It uses hashes natively. Do you think we can combine our custom hash values with their?

    1. Thanks Anatoly. I have not played with SP2013 and am not sure how it is using the hash. If using with key=value’s then mixing in custom values with those of SP should be ok.
      I have to really thank you for pointing out sammy.js. This is the second time I learn of a great resource from you (the first was from a stackexchange post a few days ago – the CAML js library). This looks like a great library for using the hash with RESTFul State which is even more user friendly. I’m bookmarking and will be looking more into it. At first glance the notation is very similar to Mojolicious, a ‘modern’ perl module that builds RESTFull applications that I recently used to build an API for into an application’s database data.

      Thanks again.


Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s