sebpiq / backbone.statemachine

Simple finite-state machine for Backbone. View states made easy. Synchronizing your application's parts with events made easy.
MIT License
177 stars 16 forks source link

Backbone.StateMachine

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

Index

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

transition options

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

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

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

0.1.0

License

Copyright (c) 2012 Sébastien Piquemal
Licensed under the MIT license.