Backbone.StateMachine

Is a small javascript library to add state machine capacities to any Backbone or non-Backbone object.

Index

Backbone.StateMachine. A module that can be mixed into any object, giving this object the super-powers of a state machine.
Backbone.StatefulView. A Backbone view, augmented with state machine capabilities.

StateMachine

Backbone.StateMachine is used as a mixin, somewhat like Backbone.Events.

Declaring a state machine

Let's declare a very simple state machine representing an HTML element that can be either hidden or visible.

This machine will have 3 states, init, hidden and visible, and 3 transitions :

init --['initialized']--> visible
hidden  --['show']--> visible
visible --['hide']--> hidden

Also, in order to actually show or hide the element, everytime the state machine enters in state visible a method doShow will be called, and everytime it leaves the state visible, a method doHide will be called.


var element = {el: $('#myElement')}

// !!! note that `StateMachine` requires the `Events` mixin
_.extend(element, Backbone.StateMachine, Backbone.Events, {
  states: {
    visible: {enter: ['doShow'], leave: ['doHide']}, // All options see: 'state options'
    hidden: {}                                       // Declaring an emtpy state is optional
  },
  transitions: {
    init: {
      initialized: 'visible'            // You can declare a transition like that
    },
    visible: {
      hide: {
        enterState: 'hidden',           // Or like this if you want to specify options
        triggers: 'nowVisible'
      }
    },
    hidden: {
      show: {
        enterState: 'visible',
        triggers: 'nowHidden'
      }
    }
  },
  doShow: function() { this.el.show() },
  doHide: function() { this.el.hide() }
})

state options

enter - array containing names of methods to call when entering the state (Optional).
leave - array containing names of methods to call when leaving the state (Optional).

transition options

enterState - arrival state of the transition.
callbacks - array containing names of methods to call when transition is crossed (Optional).
triggers - Backbone event to trigger when transition is crossed (Optional).

Note : This is not demonstrated here, but you can also define a transition from one state to itself.

Triggering transitions

The state machines are always created in init state, even if it isn't declared. Therefore, you should always declare at least one transition from state init to another state.


// !!! this method needs to be called before the state machine can be used
element.startStateMachine()

// First, let's get the machine out from 'init' state
element.trigger('initialized')

element.currentState                // 'visible'
element.trigger('hide')             // a transition is triggered, the element should disappear
element.currentState                // 'hidden'
element.trigger('hide')             // event 'hide' while in state 'hidden' -> no transition
element.trigger('show', 'quick')    // extra arguments will be passed to the callbacks

Transition events

Every time a transition is crossed, the state machine triggers a bunch of Backbone events. This way, you can setup an efficient event-based communication between the different parts of your application. Cool thing with using this method is that those different parts don't need to know each other.


element.bind('transition', function(leaveState, enterState) {
  alert('Transition from state "'+leaveState+'" to state "'+enterState+'"')
})
element.bind('leaveState:hidden', function() {
  // synchronize other objects in your application
  bla.trigger('activate')
  aView.render()
})
element.bind('enterState:hidden', function() {
  // synchronize other objects in your application
  bla.trigger('deactivate')
})

Also, if your transition defines the triggers option, for example {triggers: 'showItAll'}, an extra event 'showItAll' will be triggered when that transition is crossed :


element.bind('showItAll', function() {
  // do stuff
})

If you want to hush-up the state machine, and prevent any of those events to be triggered, just set silent to true :


element.silent = true      // next transitions will happen in silence
element.trigger('show')
element.trigger('hide')
element.silent = false     // next transitions will trigger events as described above

Matching any state with '*'

When declaring the transitions of your state machine, you can use the wildcard character '*' to match any state.


var obj = {}
_.extend(obj, Backbone.StateMachine, Backbone.Events, {
  transitions: {
    visible: { hide: 'hidden' },
    hidden: { show: 'visible' },
    // No matter the machine's state, 'panic' will always trigger a transition :
    '*': { panic: 'panicking' }
  }
})

Forcing the machine to a given state

You can use the method toState to force the machine to a particular state. In that case, no transition will occur, but the enter callbacks will be executed.

element.currentState       // 'hidden'
element.toState('visible') // the callback 'doShow' is executed.
element.currentState       // 'visible'

StatefulView

Backbone.StatefulView is a backbone view that has state machine capabilities, plus a few goodies.

A css class for each state

To each state of the machine corresponds a css class on the view's el. By default the css class name is the state.

This makes styling very easy, for example :


#myStatefulView.visible {
  display: block;
}
#myStatefulView.hidden {
  display: none;
}

Transition events as view events

It is possible to declare transition events exactly the same way as in the Backbone.View.events hash. For example :

Note : You don't need to call startStateMachine when using a StatefulView.


var MyView = Backbone.StatefulView.extend({
  transitions: {
    'init': {'loaded': 'idle'}
    // transition will occur when clicking on '.activate'
    'idle': {'click .activate': 'active'}
  }
})

state options

className - a css class added to view's el when the view is in this state.

Requirements

backbone.statemachine requires backbone (and therefore all its dependencies).

It is tested against backbone 0.9.2.

Questions, contributions ?

Any suggestion, comment, question - are welcome - contact me directly or open a ticket.

Any bug report, feature request, ... open a ticket ! To run tests, either open tests/tests.html in a browser, or run them from NodeJS (requires PhantomJS):

npm install -g grunt
grunt

More infos about state machines

http://en.wikipedia.org/wiki/Finite-state_machine

http://upload.wikimedia.org/wikipedia/commons/c/cf/Finite_state_machine_example_with_comments.svg

Release History

0.2.6

Repackaged for browserify and AMD, and available through npm

0.2.5

Callbacks can also be anonymous functions
Switched to 2-spaces indentation and removed semicolons
Now throws an error if startStateMachine is called twice

0.2.4

Added StatefulModel
Added simplified syntax for transition declaration if only the enterState if specified

0.2.3

'enterCb' and 'leaveCb' renamed to 'enter' and 'leave'
now machine always created in 'init' state.

0.2.2

added the wilcard characted '*' to match any state.

0.2.1

the states of the machine don't need to be declared anymore, the state machine can deduce it from the transitions.

0.2.0

Backbone.StateMachine now fully uses backbone's events system. Events now triggered with trigger, instead of receive previously.
in Backbone.StatefulView, transitions can now contain DOM events, using the same syntax as Backbone.View.events.

0.1.0

Initial release

sebpiq / backbone.statemachine

readme