0

By Jonathan Fielding

A month ago I wrote about how to handle responsive states in JavaScript. I looked at how you could roll your own solution and also did a comparison between Enquire.js and SimpleStateManager. SimpleStateManager is a responsive state manager that allows you to run different JavaScript at different browser widths. A month on, SimpleStateManager has continued to grow in popularity so I thought it was about time I wrote about how to get started with using SimpleStateManager (SSM).

Installing SSM

There are three ways in which you can install SSM into your project.

Download manually

If you want to download the script manually visit the GitHub Repo at https://github.com/jonathan-fielding/SimpleStateManage rand click on Download Zip (at bottom of right column). If you want to use the latest stable release then before downloading please select the latest tagged release.

Use Bower

To use Bower to install SSM all you need to do is run:

bower install SimpleStateManager

Once Bower has installed SSM into your Bower components directory you can add it to the footer of your HTML.

Setting up your states

When setting up states you would typically use the same breakpoints as you have used for your CSS media queries. For SSM states, you use the upper boundry of your media query. Therefore, if you are using Twitter Bootstrap for example, your states would be 767px, 991px and 9999px.

To set up these states we need to use the .addState method of SSM to add each state.

When calling the .addState method you are able to pass a variety of options to the method, these are:

id (optional) – An ID for the method, this is only needed if you want to reference the state somewhere else in your code;

width (required) – The upper limit of your state/breakpoint;

onEnter (optional) – A method to fire when you enter the state;

onResize (optional) – A method to fire when you resize the state;

onLeave (optional) – A method to fire when you leave the state (perhaps to clean up after the state);

For each state we can pass these options to the ssm.addState method .

ssm.addState({ id: 'mobile', width: 767, onResize: function(){ console.log('resized mobiles'); }, onEnter: function(){ console.log('enter mobile'); }, onLeave: function(){ console.log('leave mobile'); } });

Alternatively, if you are looking to add several states simultaneously, you can instead opt to use the ssm.addStates method, which you can pass an array of states to.

ssm.addState([{ id: 'mobile', width: 767, onResize: function(){ console.log('resized mobile'); }, onEnter: function(){ console.log('enter mobile'); }, onLeave: function(){ console.log('leave mobile'); } }, { id: 'tablet', width: 991, onResize: function(){ console.log('resized tablet'); }, onEnter: function(){ console.log('enter tablet'); }, onLeave: function(){ console.log('leave tablet'); } }, { id: 'desktop', width: 9999, onResize: function(){ console.log('resized desktop'); }, onEnter: function(){ console.log('enter desktop'); }, onLeave: function(){ console.log('leave desktop'); } }]);

Tell SSM you are ready

Before SSM will work its magic, we need to tell it we are ready. After you have added all your states, you need to run the ssm.ready() method which will run though your states and execute any of the methods required for the current browser width/state.

Removing states

There may come the circumstances where you want to remove a state, this can be achieved using the ssm.removeState method. You are only able to remove a state if you know the ID associated with the state. For example, to remove the mobile state we setup earlier we would use:

ssm.removeState('mobile');

If you want to remove all states you may do this using ssm.removeAllStates() , this does not need any ID’s for the items you wish to remove as it simply clears the array of states.

Get the current state

One of the useful things about SSM is that it can be used in many different ways: it can handle method triggering as you move between states; it can fire the methods required for the current state when the browser loads; and it can also manage knowing what state you are in. By this last item I mean, you can simply define your states using SSM and then retrieve information about the current active state simply by using ssm.getState which returns an object representing the current state. This means that, if you have an existing JavaScript method that you want to respond differently dependent on the current state, you can just ask for the state and conditionally respond to it. An example how this could work is:

var sampleMethod = function(){ if(ssm.getState().id === "desktop"){ console.log('is desktop'); } };

In this example ssm.getState() is being called and then we are simply reading the id value and comparing it against what we expect the value to be.

Debugging your states

To help you debug your states, SSM includes a debug mode which adds a small box to the bottom corner of the window which tells you the current width of the page. To enable debug mode simply use:

ssm.enableDebug();

You can then simply resize your browser and the figure with the browser width will update, the benefit of this is that it allows you to ensure your states are firing at the points that you expect them to fire.

Summary

SimpleStateManager is still very young, so the feature set is still growing. If there are any features you feel that SimpleStateManager is missing then please raise an issue on Github.

This post was originally published at http://www.jonathanfielding.com/getting-started-with-simplestatemanager-ssm/

Responsive web design logo courtesy of http://commons.wikimedia.org/wiki/File:Responsive_Web_Design_Logo.svg