The Page State plugin is like a mini-router for a single page of your app.
Page events save data into a state object, which is serialized into your path and querystring using the HTML history API. This lets you preserve your page state across page refreshes, links state changes to the history buttons, and enables deep-linking into states.
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.
Most Adcom JavaScript plugins are bound to the element that specifies a data-control
attribute. The State plugin is slightly different. Since the page can handle only one instance, the instantiated State object and any associated data is always bound to the window
object.
Attach events to elements on the page that should change the page state. Triggers must have the data-toggle="state"
attribute, and attributes that begin with the state-
prefix, which collectively represent the new state.
You can specify just a state="{}"
attribute containing your serialized state, or specify any number of state-*
attributes. These 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. (Specify no state-* attributes with data-merge="false"
to clear the state.)
State.js will perform a deep merge on your state attributes if you add nested values to your trigger.
While state-attr="value"
will translate into a state object of {"attr": "value"}
. But using hyphen notation to nest values lets you turn state-namespace-attr="value"
into {"namespace": {"attr": "value"}}
.
The state is serialized into the querystring by default. But you can designate one attribute to function as the page's path. Instead of getting serialized to the querystring, it will replace the current window.location.pathname
when triggered.
Use the path-attr
and optionally path-base
options when initializing State.js to set that attribute and the path prefix to which your path values are related.
The purpose of routing is to bring your page from it's base state to the state described by your querystring. Generally this means altering the appearance or content of the page to match how it looked when the user left it.
How you do this depends on how your original page was structured. It's good practice to avoid duplicate logic for rendering a state on the page. Generally, the page can update it's appearance in one of two ways.
Whichever is better for your application, you should try to update your page programmatically in as similar a way as possible to how it was originally manipulated.
Configure your page to use State.js by setting data-control="state"
on an element of your page, along with any desired configuration options.
Trigger changes to the state by setting data-toggle="state"
and any number of state-*
attributes on an element.
Initialize Page State by calling .state()
on the window element with configuration options. Change the state by capping .push()
.
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-
, as in data-items=""
.
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-state | boolean | false | When using only data-api triggers with states where firing order doesn't matter, trigger-state="true" attempts to fire events on the page automatically based on the current page state. |
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 . |
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.
Append the given state object to the browser's history and reflect the change in window.location
.
Essentially window.history.back()
. Moves the history back one place.
Fire the updated
event with the current Page State, but do not remove it from the history stack.
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. |