HTML 5 SessionState and LocalStorage are very useful and super easy to use to manage client side state. For building rich client side or SPA style applications it's a vital feature to be able to cache user data as well as HTML content in order to swap pages in and out of
the browser's DOM. What might not be so obvious is that you can also use
the sessionState and localStorage objects even in classic server rendered HTML applications to provide caching features between pages. These APIs have been around for a long time and are supported by most relatively modern browsers and even all
the way back to IE8, so you can use them safely in your Web applications. SessionState and LocalStorage are easy
The APIs that make up sessionState and localStorage are very simple. Both object feature
the same API interface which is a simple, string based key value store that has getItem, setItem, removeitem, clear and key methods.
The objects are also pseudo array objects and so can be iterated like an array with a length property and you have array indexers to set and get values with. Basic usage for storing and retrieval looks like this (using sessionStorage, but
the syntax is
the same for localStorage - just switch
the objects):// set
var lastAccess = new Date().getTime();
if (sessionStorage)
sessionStorage.setItem("myapp_time", lastAccess.toString());
// retrieve in another page or on a refresh
var time = null;
if (sessionStorage)
time = sessionStorage.getItem("myapp_time");
if (time)
time = new Date(time * 1);
else
time = new Date();
sessionState stores data that is browser session specific and that has a liftetime of
the active browser session or window. Shut down
the browser or tab and
the storage goes away. localStorage uses
the same API interface, but
the lifetime of
the data is permanently stored in
the browsers storage area until deleted via code or by clearing out browser cookies (not
the cache). Both sessionStorage and localStorage space is limited.
The spec is ambiguous about this - supposedly sessionStorage should allow for unlimited size, but it appears that most WebKit browsers support only 2.5mb for either object. This means you have to be careful what you store especially since other applications might be running on
the same domain and also use
the storage mechanisms. That said 2.5mb worth of character data is quite a bit and would go a long way.
The easiest way to get a feel for how sessionState and localStorage work is to look at a simple example.
You can go check out
the following example online in Plunker: http://plnkr.co/edit/0ICotzkoPjHaWa70GlRZ?p=preview
which looks like this:
Plunker is an online HTML/JavaScript editor that lets you write and run Javascript code and similar to JsFiddle, but a bit cleaner to work in IMHO (thanks to John Papa for turning me on to it).
The sample has two text boxes with counts that update session/local storage every time you click
the related button.
The counts are 'cached' in Session and Local storage.
The point of these examples is that both counters survive full page reloads, and
the LocalStorage counter survives a complete browser shutdown and restart. Go ahead and try it out by clicking
the Reload button after updating both counters and then shutting down
the browser completely and going back to
the same URL (with
the same browser). What you should see is that reloads leave both counters intact at
the counted values, while a browser restart will leave only
the local storage counter intact.
The code to deal with
the SessionStorage (and LocalStorage not shown here) in
the example is isolated into a couple of wrapper methods to simplify
the code: function getSessionCount() {
var count = 0;
if (sessionStorage) {
var count = sessionStorage.getItem("ss_count");
count = !count ? 0 : count * 1;
}
$("#txtSession").val(count);
return count;
}
function setSessionCount(count) {
if (sessionStorage)
sessionStorage.setItem("ss_count", count.toString());
}
These two functions essentially load and store a session counter value.
The two key methods used here are:
sessionStorage.getItem(key);
sessionStorage.setItem(key,stringVal);
Note that
the value given to setItem and return by getItem has to be a string. If you pass another type you get an error. Don't let that limit you though - you can easily enough store JSON data in a variable so it's quite possible to pass complex objects and store them into a single sessionStorage value:var user = { name: "Rick", id="ricks", level=8 }
sessionStorage.setItem("app_user",JSON.stringify(user));
to retrieve it:var user = sessionStorage.getItem("app_user");
if (user)
user = JSON.parse(user);
Simple!
If you're using
the Chrome Developer Tools (F12) you can also check out
the session and local storage state on
the Resource tab:
You can also use this tool to refresh or remove entries from storage.
What we just looked at is a purely client side implementation where a couple of counters are stored. For rich client centric AJAX applications sessionStorage and localStorage provide a very nice and simple API to store application state while
the application is running.
But you can also use these storage mechanisms to manage server centric HTML applications when you combine server rendering with some JavaScript to perform client side data caching. You can both store some state information and data on
the client (ie. store a JSON object and carry it forth between server rendered HTML requests) or you can use it for good old HTTP based caching where some rendered HTML is saved and then restored later.
Let's look at
the latter with a real life example.
Why do I need Client-side Page Caching for Server Rendered HTML?
I don't know about you, but in a lot of my existing server driven applications I have lists that display a fair amount of data. Typically these lists contain links to then drill down into more specific data either for viewing or editing. You can then click on a link and go off to a detail page that provides more concise content.
So far so good. But now you're done with
the detail page and need to get back to
the list, so you click on a 'bread crumbs trail' or an application level 'back to list' button and…
…you end up back at
the top of
the list -
the scroll position,
the current selection in some cases even filters conditions - all gone with
the wind. You've left behind
the state of
the list and are starting from scratch in your browsing of
the list from
the top. Not cool!
Sound familiar? This a pretty common scenario with server rendered HTML content where it's so common to display lists to drill into, only to lose state in
the process of returning back to
the original list. Look at just about any traditional forums application, or even StackOverFlow to see what I mean here. Scroll down a bit to look at a post or entry, drill in then use
the bread crumbs or tab to go back…
In some cases returning to
the top of a list is not a big deal. On StackOverFlow that sort of works because content is turning around so quickly you probably want to actually look at
the top posts. Not always though - if you're browsing through a list of search topics you're interested in and drill in there's no way back to that position. Essentially anytime you're actively browsing
the items in
the list, that's when state becomes important and if it's not handled
the user experience can be really disrupting.
Content Caching
If you're building client centric SPA style applications this is a fairly easy to solve problem - you tend to render
the list once and then update
the page content to overlay
the detail content, only hiding
the list temporarily until it's used again later. It's relatively easy to accomplish this simply by hiding content on
the page and later making it visible again.
But if you use server rendered content, hanging on to all
the detail like filters, selections and scroll position is not quite as easy. Or is it???
This is where sessionStorage comes in handy. What if we just save
the rendered content of a previous page, and then restore it when we return to this page based on a special flag that tells us to use
the cached version? Let's see how we can do this.
A real World Use Case
Recently my local ISP asked me to help out with updating an ancient classifieds application. They had a very busy, local classifieds app that was originally an ASP classic application.
The old app was - wait for it: frames based - and even though I lobbied against it,
the decision was made to keep
the frames based layout to allow rapid browsing of
the hundreds of posts that are made on a daily basis.
The primary reason they wanted this was precisely for
the ability to quickly browse content item by item. While I personally hate working with Frames, I have to admit that
the UI actually works well with
the frames layout as long as you're running on a large desktop screen. You can check out
the frames based desktop site here:
http://classifieds.gorge.net/
However when I rebuilt
the app I also added a secondary view that doesn't use frames.
The main reason for this of course was for mobile displays which work horribly with frames. So there's a somewhat mobile friendly interface to
the interface, which ditches
the frames and uses some responsive design tweaking for mobile capable operation:
http://classifeds.gorge.net/mobile (or browse
the base url with your browser width under 800px)
Here's what
the mobile, non-frames view looks like:
As you can see this means that
the list of classifieds posts now is a list and there's a separate page for drilling down into
the item. And of course… originally we ran into that usability issue I mentioned earlier where
the browse, view detail, go back to
the list cycle resulted in lost list state. Originally in mobile mode you scrolled through
the list, found an item to look at and drilled in to display
the item detail. Then you clicked back to
the list and BAM - you've lost your place.
Because there are so many items added on a daily basis
the full list is never fully loaded, but rather there's a "Load Additional Listings" entry at
the button. Not only did we originally lose our place when coming back to
the list, but any 'additionally loaded' items are no longer there because
the list was now rendering as if it was
the first page hit.
The additional listings, and any filters,
the selection of an item all were lost. Major Suckage!
Using Client SessionStorage to cache Server Rendered Content
To work around this problem I decided to cache
the rendered page content from
the list in SessionStorage. Anytime
the list renders or is updated with Load Additional Listings,
the page HTML is cached and stored in Session Storage. Any back links from
the detail page or
the login or write entry forms then point back to
the list page with a back=true query string parameter. If
the server side sees this parameter it doesn't render
the part of
the page that is cached. Instead
the client side code retrieves
the data from
the sessionState cache and simply inserts it into
the page.
It sounds pretty simple, and
the overall
the process is really easy, but there are a few gotchas that I'll discuss in a minute. But first let's look at
the implementation.
Let's start with
the server side here because that'll give a quick idea of
the doc structure. As I mentioned
the server renders data from an ASP.NET MVC view. On
the list page when returning to
the list page from
the display page (or a host of other pages) looks like this:
https://classifieds.gorge.net/list?back=True
The query string value is a flag, that indicates whether
the server should render
the HTML. Here's what
the top level MVC Razor view for
the list page looks like:@model MessageListViewModel
@{
ViewBag.Title = "Classified Listing";
bool isBack = !string.IsNullOrEmpty(Request.QueryString["back"]);
}
<form method="post" action="@Url.Action("list")">
<div id="SizingContainer">
@if (!isBack)
{
@Html.Partial("List_CommandBar_Partial", Model)
<div id="PostItemContainer" class="scrollbox" xstyle="-webkit-overflow-scrolling: touch;">
@Html.Partial("List_Items_Partial", Model)
@if (Model.RequireLoadEntry)
{
<div class="postitem loadpostitems" style="padding: 15px;">
<div id="LoadProgress" class="smallprogressright"></div>
<div class="control-progress">
Load additional listings...
</div>
</div>
}
</div>
}
</div>
</form>
As you can see
the query string triggers a conditional block that if set is simply not rendered.
The content inside of #SizingContainer basically holds
the entire page's HTML sans
the headers and scripts, but including
the filter options and menu at
the top. In this case this makes good sense - in other situations
the fact that
the menu or filter options might be dynamically updated might make you only cache
the list rather than essentially
the entire page. In this particular instance all of
the content works and produces
the proper result as both
the list along with any filter conditions in
the form inputs are restored.
Ok, let's move on to
the client. On
the client there are two page level functions that deal with saving and restoring state. Like
the counter example I showed earlier, I like to wrap
the logic to save and restore values from sessionState into a separate function because they are almost always used in several places.page.saveData = function(id) {
if (!sessionStorage)
return;
var data = {
id: id,
scroll: $("#PostItemContainer").scrollTop(),
html: $("#SizingContainer").html()
};
sessionStorage.setItem("list_html",JSON.stringify(data));
};
page.restoreData = function() {
if (!sessionStorage)
return;
var data = sessionStorage.getItem("list_html");
if (!data)
return null;
return JSON.parse(data);
};
The data that is saved is an object which contains an ID which is
the selected element when
the user clicks and a scroll position. These two values are used to reset
the scroll position when
the data is used from
the cache. Finally
the html from
the #SizingContainer element is stored, which makes for
the bulk of
the document's HTML.
In this application
the HTML captured could be a substantial bit of data. If you recall, I mentioned that
the server side code renders a small chunk of data initially and then gets more data if
the user reads through
the first 50 or so items.
The rest of
the items retrieved can be rather sizable. Other than
the JSON deserialization that's Ok. Since I'm using SessionStorage
the storage space has no immediate limits.
Next is
the core logic to handle saving and restoring
the page state. At first though this would seem pretty simple, and in some cases it might be, but as
the following code demonstrates there are a few gotchas to watch out for. Here's
the relevant code I use to save and restore:$( function() {
…
var isBack = getUrlEncodedKey("back", location.href);
if (isBack) {
// remove
the back key from URL
setUrlEncodedKey("back", "", location.href);
var data = page.restoreData(); // restore from sessionState
if (!data) {
// no data - force redisplay of
the server side default list
window.location = "list";
return;
} $("#SizingContainer").html(data.html);
var el = $(".postitem[data-id=" + data.id + "]");
$(".postitem").removeClass("highlight");
el.addClass("highlight");
$("#PostItemContainer").scrollTop(data.scroll);
setTimeout(function() { el.removeClass("highlight"); }, 2500);
}
else if (window.noFrames)
page.saveData(null); // save when page loads
$("#SizingContainer").on("click", ".postitem", function() {
var id = $(this).attr("data-id");
if (!id)
return true;
if (window.noFrames)
page.saveData(id);
var contentFrame = window.parent.frames["Content"];
if (contentFrame)
contentFrame.location.href = "show/" + id;
else
window.location.href = "show/" + id;
return false;
});
…
The code starts out by checking for
the back query string flag which triggers restoring from
the client cache. If cached
the cached data structure is read from sessionStorage. It's important here to check if data was returned. If
the user had back=true on
the querystring but there is no cached data, he likely bookmarked this page or otherwise shut down
the browser and came back to this URL. In that case
the server didn't render any detail and we have no cached data, so all we can do is redirect to
the original default list view using window.location. If we continued
the page would render no data - so make sure to always check
the cache retrieval result. Always!
If there is data
the it's loaded and
the data.html data is restored back into
the document by simply injecting
the HTML back into
the document's #SizingContainer element:$("#SizingContainer").html(data.html);
It's that simple and it's quite quick even with a fully loaded list of additional items and on a phone.
The actual HTML data is stored to
the cache on every page load initially and then again when
the user clicks on an element to navigate to a particular listing.
The former ensures that
the client cache always has something in it, and
the latter updates with additional information for
the selected element.
For
the click handling I use a data-id attribute on
the list item (.postitem) in
the list and retrieve
the id from that. That id is then used to navigate to
the actual entry as well as storing that Id value in
the saved cached data.
The id is used to reset
the selection by searching for
the data-id value in
the restored elements.
The overall process of this save/restore process is pretty straight forward and it doesn't require a bunch of code, yet it yields a huge improvement in
the usability of
the site on mobile devices (or anybody who uses
the non-frames view).
Some things to watch out for
As easy as it conceptually seems to simply store and retrieve cached content, you have to be quite aware what type of content you are caching.
The code above is all that's specific to cache/restore cycle and it works, but it took a few tweaks to
the rest of
the script code and server code to make it all work. There were a few gotchas that weren't immediately obvious.
Here are a few things to pay attention to:
Event Handling Logic
Timing of manipulating DOM events
Inline Script Code
Bookmarking to
the Cache Url when no cache exists
Do you have inline script code in your HTML? That script code isn't going to run if you restore from cache and simply assign or it may not run at
the time you think it would normally in
the DOM rendering cycle.
JavaScript Event Hookups
The biggest issue I ran into with this approach almost immediately is that originally I had various static event handlers hooked up to various UI elements that are now cached. If you have an event handler like:$("#btnSearch").click( function() {…});
that works fine when
the page loads with server rendered HTML, but that code breaks when you now load
the HTML from cache. Why? Because
the elements you're trying to hook those events to may not actually be there - yet.
Luckily there's an easy workaround for this by using deferred events. With jQuery you can use
the .on() event handler instead:$("#SelectionContainer").on("click","#btnSearch", function() {…});
which monitors a parent element for
the events and checks for
the inner selector elements to handle events on. This effectively defers to runtime event binding, so as more items are added to
the document bindings still work. For any cached content use deferred events.
Timing of manipulating DOM Elements
Along
the same lines make sure that your DOM manipulation code follows
the code that loads
the cached content into
the page so that you don't manipulate DOM elements that don't exist just yet. Ideally you'll want to check for
the condition to restore cached content towards
the top of your script code, but that can be tricky if you have components or other logic that might not all run in a straight line.
Inline Script Code
Here's another small problem I ran into: I use a DateTime Picker widget I built a while back that relies on
the jQuery date time picker. I also created a helper function that allows keyboard date navigation into it that uses JavaScript logic. Because MVC's limited 'object model'
the only way to embed widget content into
the page is through inline script.
This code broken when I inserted
the cached HTML into
the page because
the script code was not available when
the component actually got injected into
the page. As
the last bullet - it's a matter of timing. There's no good work around for this - in my case I pulled out
the jQuery date picker and relied on native <input type="date" /> logic instead - a better choice these days anyway, especially since this view is meant to be primarily to serve mobile devices which actually support date input through
the browser (unlike desktop browsers of which only WebKit seems to support it).
Bookmarking Cached Urls
When you cache HTML content you have to make a decision whether you cache on
the client and also not render that same content on
the server. In
the Classifieds app I didn't render server side content so if
the user comes to
the page with back=True and there is no cached content I have to a have a Plan B. Typically this happens when somebody ends up bookmarking
the back URL.
The easiest and safest solution for this scenario is to ALWAYS check
the cache result to make sure it exists and if not have a safe URL to go back to - in this case to
the plain uncached list URL which amounts to effectively redirecting.
This seems really obvious in hindsight, but it's easy to overlook and not see a problem until much later, when it's not obvious at all why
the page is not rendering anything.
Don't use <body> to replace Content
Since we're practically replacing all
the HTML in
the page it may seem tempting to simply replace
the HTML content of
the <body> tag. Don't.
The body tag usually contains key things that should stay in
the page and be there when it loads. Specifically script tags and elements and possibly other embedded content. It's best to create a top level DOM element specifically as a placeholder container for your cached content and wrap just around
the actual content you want to replace. In
the app above
the #SizingContainer is that container.
Other Approaches
The approach I've used for this application is kind of specific to
the existing server rendered application we're running and so it's just one approach you can take with caching. However for server rendered content caching this is a pattern I've used in a few apps to retrofit some client caching into list displays. In this application I took
the path of least resistance to
the existing server rendering logic.
Here are a few other ways that come to mind:
Using Partial HTML Rendering via AJAXInstead of rendering
the page initially on
the server,
the page would load empty and
the client would render
the UI by retrieving
the respective HTML and embedding it into
the page from a Partial View. This effectively makes
the initial rendering and
the cached rendering logic identical and removes
the server having to decide whether this request needs to be rendered or not (ie. not checking for a back=true switch). All
the logic related to caching is made on
the client in this case.
Using JSON Data and Client RenderingThe hardcore client option is to do
the whole UI SPA style and pull data from
the server and then use client rendering or databinding to pull
the data down and render using templates or client side databinding with knockout/angular et al. As with
the Partial Rendering approach
the advantage is that there's no difference in
the logic between pulling
the data from cache or rendering from scratch other than
the initial check for
the cache request. Of course if
the app is a full on SPA app, then caching may not be required even -
the list could just stay in memory and be hidden and reactivated.
I'm sure there are a number of other ways this can be handled as well especially using AJAX. AJAX rendering might simplify
the logic, but it also complicates search engine optimization since there's no content loaded initially. So there are always tradeoffs and it's important to look at all angles before deciding on any sort of caching solution in general.
State of
the Session
SessionState and LocalStorage are easy to use in client code and can be integrated even with server centric applications to provide nice caching features of content and data. In this post I've shown a very specific scenario of storing HTML content for
the purpose of remembering list view data and state and making
the browsing experience for lists a bit more friendly, especially if there's dynamically loaded content involved.
If you haven't played with sessionStorage or localStorage I encourage you to give it a try. There's a lot of cool stuff that you can do with this beyond
the specific scenario I've covered here…
Resources
Overview of localStorage (also applies to sessionStorage)
Web Storage Compatibility
Modernizr Test Suite© Rick Strahl, West
Wind Technologies, 2005-2013Posted in JavaScript HTML5 ASP.NET MVC
Tweet
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
