Page State state.js

The Page State plugin reponds to events on your page by saving data into a state object, and serializing that state object into your page's url using the HTML history API. It can use that serialized state to return your page to that state when a user deep links in, or uses the browser history buttons.

Examples

Enable State.js by adding data-control="state" to an element on your page. The <html> tag is a good convention, but it can be placed on any element.

{% highlight html %} {% endhighlight %}

Attach event triggers to elements on the page that should change the page state. Triggers must have the data-toggle="state" attribute, and zero or more attributes that begin with the state- prefix.

The state-* attributes are converted into an object, and merged into the page state (unless data-merge="false", which causes the specified state to replace the current state).

{% highlight html %}
{% endhighlight %}

Changing the path

All state parameters are serialized into one or more querystring attributes by default. But you can designate a single attribute to function as the page's path. Instead of getting serialized to the querystring, it will replace the current pathname in the url when triggered.

{% highlight html %}
{% endhighlight %}

Usage

Via data attributes

Configure your page to use State.js by setting data-control="state" on an element of your page, along with any desired configuration options.

{% highlight html %} ... {% endhighlight %}

Trigger changes to the state by setting data-toggle="state" and any number of state-* attributes on an element.

{% highlight html %}{% endhighlight %}

Via JavaScript

Initialize Page State by calling .state() on the window element with configuration options. Change the state by capping .push().

{% highlight js %} $(window).state({initialState: {key: "value"}}); $(window).state('push', {key: "updated value"}[, options]); {% endhighlight %}

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-items="".

The state container / window

Name type default description
format humanize, condense humanize Format the serialized state parameters into the querystring either as a single variable (condense) or as a direct translation from the Page State's attributes into querystring attributes.
initial-state native or serialized object Initialize the Page State to a known object.
path-attr string Treat one top-level attribute of the state as the page's path, which will be reflected in the pathname sent to the HTML history API. That attribute will not be rendered as a querystring.
path-base string A prefix that will be ignored when deserializing the path attribute from the current window location, and remove when serializing it.
condense-attr string q When format="condense", the state hash will be serialized into this top-level querystring attribute.
allow-repeats boolean true Sequential duplicate states will never be saved in the window history stack. However, if this is set to true then the updated.adcom.state event will still fire whenever a state pushed is attempted, regardless of whether it's new.

Trigger elements

Name type default description
trigger string click Event that will trigger the state change.
merge boolean true Whether the state specified on this element will be merged into the existing state, rather than replace the current state.
action push, replace push Push will append the specific state onto the end of the window's history using window.history.pushState.. Replace will update the current page state without moving the browser history forward using winow.history.replaceState.

Methods

All of these public JavaScript API methods add, remove to examine the window's history stack. They should not directly lead to changes on the page; instead, listen for the updated.adcom.state event and launch changes from it.

.state('push', object)

Append the given state object to the browser's history and reflect the change in window.location.

{% highlight js %}$(window).state('push', {"key": "value"});{% endhighlight %}

.state('pop')

Essentially window.history.back(). Moves the history back one place.

{% highlight js %}$(window).state('pop');{% endhighlight %}

.state('peek')

Fire the updated event with the current Page State, but do not remove it from the history stack.

{% highlight js %}$(window).state('peek');{% endhighlight %}

Events

Event Type Description
update.adcom.state This event is fired immediately when the update method is called, which will precede an updating of the page due to a push trigger or browser history action. The new state is available as the state property of the event. The changes may not be reflected on the page, but the window's url will have been updated when this event fires.
updated.adcom.state This event is fired after the Page State has been updated due to a user push trigger, or a browser history action. The new state is available as the state property of the event.
push.adcom.state This event is fired when a user push trigger has occurred, but before the window's URL or Page State have been updated. The new state and any update options are available as the state and options properties of the event.
pushed.adcom.state This event is fired after a user push trigger has occurred, and after the window's URL and Page State have been updated, and after the updated.adcom.state event has fired. The new state and any update options are available as the state and options properties of the event.
{% highlight js %} $(window).on('updated.adcom.state', function (e) { // do something... }) {% endhighlight %}