States & FSMs

Many applications are state-oriented — appearing and behaving differently in different states. ConstraintJS includes a syntax for creating finite-state machines (FSMs) to make creating these applications easier. cjs.fsm(...state_names) creates a new FSM:

var my_fsm = cjs.fsm();

###Adding States .addState(state_name) adds a state to the FSM:

my_fsm.addState("idle");

.addState returns the original FSM (my_fsm in the above example.) .startsAt(state_name) specifies the initial state of the FSM.

my_fsm.startsAt("idle");

#####Transition Events Transition events — or events on which transitions occur — are created with the cjs.on(event_name, dom_element) function. event_name is a standard JavaScript DOM event and dom_element is the DOM element to which that event is occurring. For example: cjs.on("mousedown", my_div)

#####Guards

.guard(condition_func) specifies the conditions on which the transition event may occur. For example: cjs.on("mousedown", my_div).guard(function(event) { return false;}) would never fire because the guard always returns false.

Transition events are functions that accept a parameter to perform the transition, allowing custom transition events to be created. For example, cjs.on("mousedown", my_div) is equivalent to:

function(do_transition) {
    my_div.addEventListener("mousedown", do_transition);
}

###Switching States & Adding Transitions Although states may be set manually with ._setState(state_name), the encouraged way of transitioning between states is with transitions — pre-defined state changes that take place after some event. fsm.addTransition(event, to_state) adds a transition from the last state added to to_state (string) when the event transition event (described above) occurs:

var my_fsm = cjs.fsm()
                .add_state("idle");

my_fsm.addTransition(cjs.on("mouseover", block_a));

.addTransition returns the original FSM (my_fsm in the above example.)

###Chaining ConstraintJS's FSM syntax is designed to support "chaining," a convention in JavaScript where an object property performs an operation on that object and returns the object back. For instance:

var my_fsm = cjs.fsm()
                .addState("idle")
                .addTransition(cjs.on("mouseover", block_a), "myhover")        
                .addState("myhover")
                .addTransition(cjs.on("mouseout", block_a), "idle")
                .startsAt("idle");

###FSM Constraints Constraint variables may depend on FSMs. To create an FSM-dependent constraint, pass the FSM as the first parameter to cjs.inFSM(fsm, values) and an object with states and their values as the second parameter:

var color = cjs.inFSM(my_fsm, {
           idle:    "black", 
           myhover: "yellow"
        });

---

Next: Templates

Previous: Array & Map Constraints