Fork me on GitHub

SimpleStateManager 3.1.3

SimpleStateManager (SSM for short) is a javascript state manager for responsive websites. It is built to be light weight, has no dependencies, supports AMD (if thats your kinda thing) and aims to be really easy to simply drop into your project ready to use.

Download SimpleStateManager

Are you looking for the SimpleStateManager 2.x.x documentation? Visit the SimpleStageManager 2.x.x Site. »

SimpleStateManager is built around the concept of states, a state being the conditions of the browser at any given point, a condition might be whether a media query matches and/or the features the browser supports. With SimpleStateManager you can define a state and a series of conditions that must be met for it to be active. Each of these states can then have an onEnter, onLeave and onResize event.

Why should I use SSM

Getting started

To get started with SimpleStageManager the first step is to include it in your project, you can do this in three ways

Having downloaded SimpleStateManager you will next need to include the JavaScript file in your page. It is recommended that this is at the end of the body before your main JavaScript file.

<script src="bower_components/simplestatemanager/dist/ssm.min.js"></script>

Defining your first state

The next step is to add our first state using SimpleStateManager, to do this we use the ssm.addState method. This method takes a single argument which is a object containing the state configuration options.

For this example we will add a state named "mobile" which has a maximum width of 767px. To do this we will set the value of maxWidth to 767 and we will define an onEnter method which will log to the console "enter mobile" when the state is entered.

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

As soon as you have added the state, SimpleStageManager will check whether the conditions you specified have been matched, that being the case it will run the onEnter and onFirstRun methods if they have been specified.

FAQs

Why would I use SimpleStateManager rather than Media Queries?

Media Queries allow you to change the way a site looks based upon a number of conditions, in contrast, SimpleStateManager allows you to change the functionality of your site. In this way, both Media Queries and SimpleStateManager compliment one another, as in the situation where you are changing the look of your site you might also be changing functionality.

What does SimpleStateManager offer me over simply using the MatchMedia API?

The MatchMedia API is incredibly powerful as it allows us to use media queries in our JavaScript, when the media query is matched or unmatched a callback method is run. SimpleStateManager puts this functionality on steroids, providing you with a simple API to attach enter, leave and resize events to a state. In addition to using the matchMedia API it also allows you to specify additional rules your state must meet to be active.

What browsers does SimpleStateManager support?

Version 3.x of SimpleStateManager and above supports the following browsers:

The library has a suite of unit tests covering the core functionality, after every commit these are run in all browsers we support using a combination of TravisCI and BrowserStack. Aside from the unit tests, the library is also tested manually prior to each release.

If you need to support Internet Explorer 8 or below their are two options available:

Contribute

SimpleStateManager is an open source project maintained by a small group of contributors, as such we are always looking for new people who want to get involved.

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Contributors