Fork me on GitHub

API

The SimpleStateManager API enables developers to very quickly implement JavaScript that can be enabled and disabled based upon the state of the browser.

States

A state is the set of conditions of the browser at any given point, a condition might be whether a media query matches and/or the features the browser supports. Out of the box SimpleStateManager enables you to use media queries as conditions for states, you can also add your own conditions by adding custom state config options.

Adding states

With SimpleStateManager you can add multiple states based on your needs, the most simple way to add a state is to simply pass the information about your state to SSM using ssm.addState. You are able to add as many states as you need, your states are able to overlap and your states can each have their own onEnter, onLeave, onFirstRun and onResize events.

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

Example of adding states

In the below example we are adding three states, one for mobile devices, one for tablet and one for desktop. We have defined these using a media query that checks the width of the browser.

ssm.addState({
    id: 'mobile',
    query: '(max-width: 767px)',
    onEnter: function(){
        console.log('enter mobile');
    }
});

ssm.addState({
    id: 'tablet',
    query: '(min-width: 768px) and (max-width: 1023px)',
    onEnter: function(){
        console.log('enter tablet');
    }
});

ssm.addState({
    id: 'desktop',
    query: '(min-width: 1024px)',
    onEnter: function(){
        console.log('enter desktop');
    }
});

Alternatively you can add these states in a single command by passing them as an array of states to the ssm.addStates method. This same example is shown again below but using the addStates method instead.

ssm.addStates([
{
    id: 'mobile',
    query: '(max-width: 767px)',
    onEnter: function(){
        console.log('enter mobile');
    }
},
{
    id: 'tablet',
    query: '(min-width: 768px) and (max-width: 1023px)',
    onEnter: function(){
        console.log('enter tablet');
    }
},
{
    id: 'desktop',
    uery: '(min-width: 1024px)',
    onEnter: function(){
        console.log('enter desktop');
    }
}
]);

Note:

It is important to remember that the if you do not pass a media query using the query parameter the query will always match. This is useful for when you simply want to toggle whether a state should be active or not using custom config options you have added.

Remove States

Sometimes it may be necessary to remove a state, if we have the id for the state we can easily remove the state, to remove the mobile state from our above example we simply use:

ssm.removeState('mobile');

Or if you want to remove multiple at the same time

ssm.removeStates(['tablet', 'mobile']);

Custom state configuration options

Custom state configuration options enable you to add custom tests for conditions. This means you can enable your states to only be active for many different situations such as when the users browser supports a particular feature.

Add a custom config option

In SimpleStateManager options we pass to our states are called config options, we are able to add new config options to SimpleStateManager using ssm.addConfigOption

ssm.addConfigOption({
    name: "touch", 
    test: function(){
        if(typeof this.state.touch === "boolean" && this.state.touch === Modernizr.touch){
            return true;
        }
        else{
            return false;
        }
    }
});

By default the addConfigOption method will run when the browser is resized. If you want to customise this behaviour you can do so by using the when property of your config option.

The when property has the following supported values:

An example of where you might set the value of when to once would be a feature test such as determining if the users device supports touch events. An example of how this might work is below:

ssm.addConfigOption({
    name: "touch", 
    when: "once",
    test: function(){
        if(typeof this.state.touch === "boolean" && this.state.touch === Modernizr.touch){
            return true;
        }
        else{
            return false;
        }
    }
});

Full API

Method Description
ssm.addState Add a new state, expects an object literal, properties avaliable - id (optional), minWidth (optional), maxWidth (optional), onEnter (optional), onResize (optional), onLeave (optional)
ssm.addStates Add multiple new states, expects an array of object literals, properties avaliable - id (optional), minWidth (optional), maxWidth (optional), onEnter (optional), onResize (optional), onLeave (optional)
ssm.removeState Remove a state, expects one property, the id of the state to be removed.
ssm.removeStates Remove multiple states, expects an array of strings
ssm.removeAllStates Clears all states from SSM
ssm.getState ssm.getState() takes a single parameter
ssm.getState('mobile');
ssm.getStates By default ssm.getStates() will return all the states added to SSM however you optionally can pass an array of ID's of the states you want e.g
ssm.getStates([
    'mobile',
    'desktop'
]);
ssm.isActive Check if a state is active using the ID you assigned.
ssm.addConfigOption SSM allows you to define new rules by which a state can be enabled and disabled using ssm.addConfigOption. The method takes an object with 2 values as the parameter, firstly the name of the config option and secondly the method to test the option. Please note the test must return true or false to allow SSM to know if the test has passed or failed. A typical example of how you can add a test.
ssm.addConfigOption({
    name: "minHeight",
    test: function(){
        return true;
    }
});