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:

• id (optional) – An ID for the method, this is only needed if you want to reference the state somewhere else in your code, otherwise a ID will be automatically assigned to your state.
• query (required) – The media query that you want to match when this state is to be active
• 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)
• onFirstRun (optional) – A method that runs when the state is first activated

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',
        query: '(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:

• resize (default): Run the test whenever the browser is resized
• match: Run the test whenever the query attached to the state becomes matched/unmatched
• once: Run the test once on the state it has been applied to, if the value is not what is expected then the state is not added.

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

ssm.getState('mobile');

ssm.getStates([
'mobile',
'desktop'
]);

ssm.addConfigOption({
name: "minHeight",
test: function(){
return true;
}
});