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);
})();
