Notes From Talk:

Sanely Edit an HTML Doc in a Browser with Ember.StateManager`

Presentation app code in referenced in the talk https://github.com/pixelhandler/ember-slide-deck

Let's Think About it...

Bruce Wants More Cowbell

Gene Frenkle: ...if Bruce Dickinson wants more cowbell, we should probably give him more cowbell!

Bruce Dickinson: Guess what? I got a fever! And the only prescription.. is more cowbell!

For some laughs… read the more cowbell transcript or watch the video.

What Should Our State Machine Do?

Perhaps we consider a few examples first…

What is a Finite-State Machine?

Illustration from Wikipedia -

It is conceived as an abstract machine that can be in one of a finite number of states. The machine is in only one state at a time; the state it is in at any given time is called the current state. It can change from one state to another when initiated by a triggering event or condition; this is called a transition. A particular FSM is defined by a list of its states, and the triggering condition for each transition.

An example of a very simple mechanism that can be modeled by a state machine is a turnstile.

A turnstile, used to control access to subways and amusement park rides, is a gate with three rotating arms at waist height, one across the entryway. Initially the arms are locked, barring the entry, preventing customers from passing through. Depositing a coin or token in a slot on the turnstile unlocks the arms, allowing them to rotate by one-third of a complete turn, allowing a single customer to push through. After the customer passes through, the arms are locked again until another coin is inserted.

The turnstile has two states: Locked and Unlocked. There are two inputs that affect its state: putting a coin in the slot (coin) and pushing the arm (push). In the locked state, pushing on the arm has no effect; no matter how many times the input push is given it stays in the locked state. Putting a coin in, that is giving the machine a coin input, shifts the state from Locked to Unlocked. In the unlocked state, putting additional coins in has no effect; that is, giving additional coin inputs does not change the state. However, a customer pushing through the arms, giving a push input, shifts the state back to Locked.

A Game analogy

Let's say we wanted to write a game like PAC-MAN®: The most successful coin operated game (24Kb).

Ember Routing

The `Ember.Router` class manages the application state and URLs. Refer to
    the [routing guide](http://emberjs.com/guides/routing/) for documentation.

There some good articles on this version of the router which illustrate a state machine.

Links / History on the Router

Updates.md - Yehuda Katz
Ember Routing - Tom Dale
StateManager and friends
Enable logging in the new Ember.js router

https://github.com/emberjs/ember.js/blob/v1.0.0-rc.6/packages/ember-routing/lib/system/route.js

Ember Models (Ember Data)

Model Lifecycle - Record States

Loading
Loaded/Clean
Dirty
in-Flight
Invalid
Error

model/states.js encapsulates the various states that a record can transition through during its lifecycle

...hierarchy like this:
   * created
     * start <-- currentState
   * inFlight
     * updated
     * inFlight

Ember Views

Views have states and state properties, e.g. "perRender", "inBuffer", "hasElement" "inDOM" to which are also used to keep track of state. (Ember.View states not using Ember.StateManager).

Explore Ember.StateManger with Turnstile example

Example Turnstile application built with Ember see in working at jsbin, source code at: github

Closing

Ember has some awesome tools baked into the framework. The StateManager is an example of an object to mange the state of objects like models, routes, or any object that needs to behave according to it's state.

I few things I noticed when using Ember.State objects:

Action handlers for enter and exit may not have the currentState.name in the state that you expect, these events happen during transition to/from a state.
The setup method does have the currentState you would expect and receives the manager and context objects as arguments, while enter and exit only receive manager.
A state's methods for enter and exit are good for handling common behaviors when transitioning to sub-states. The setup method can be defined in a base state class as the default setup action for states and thier child states as well.
Methods defined on a parent state are shared with sub-states.
Utilize the state pattern by defining the same action methods with varying outcomes depending on the state's required behaviors.
Reading the 'ember-states' test suite (state_manager_test.js & state_test.js) reveals everthing you want to know about the Ember.StateManager.

The objective of this talk on the use of the Ember.StateManager to wrangle loads of events when editing an HTML document in a browser app was to discover more about using Ember.js objects: Router, Model and StateManager.

A state machine may be useful for:

An interstitial ad (e.g. in a checkout flow) that requires user to act on something in order to continue.
A gate preventing users form continuing to a url or action, e.g. user must agree/opt-in first.
Interactions that don't need to be persisted and represented via a URL.
- Let user interact then choose when to persist the state. For example, editing many elements in various states; yet only interacting with one element at a time.
- Workflow, e.g. multiple steps to accomplish an objective.

See the State Pattern for another example of a state objects used to handle various behaviors of mouse activity.

Ember.js Test Suite: ember-states (v1.0.0-rc.6)

Run the ember testing suite to view list of specification for Ember.State and Ember.StateManager http://localhost:9292/?package=ember-states

Tests completed in 380 milliseconds. 142 assertions of 142 passed, 0 failed.

ember-states/state: should pass jshint 
ember-states/state_manager: should pass jshint 
Ember.StateManager: it exists 
Ember.StateManager: it discovers states set in its state property 
Ember.StateManager: it discovers states that are properties of the state manager 
Ember.StateManager: it reports its current state 
Ember.StateManager: it reports its current state path 
Ember.StateManager: it sends enter and exit events during state transitions 
Ember.StateManager: it accepts absolute paths when changing states 
Ember.StateManager: it does not enter an infinite loop in transitionTo 
Ember.StateManager: it automatically transitions to a default state 
Ember.StateManager: it automatically transitions to a default state that is an instance 
Ember.StateManager: on a state manager, it automatically transitions to a default state that is an instance 
Ember.StateManager: it automatically transitions to a default state specified using the initialState property 
Ember.StateManager: it automatically transitions to a default substate specified using the initialState property 
Ember.StateManager: it automatically synchronously transitions into initialState in an event 
Ember.StateManager: it automatically transitions to multiple substates specified using either start or initialState property 
Ember.StateManager: it triggers setup on initialSubstate 
Ember.StateManager: it throws an assertion error when the initialState does not exist 
Ember.StateManager - Transitions on Complex State Managers: it sends exit events to nested states when changing to a top-level state 
Ember.StateManager - Transitions on Complex State Managers: it sends exit events in the correct order when changing to a top-level state 
Ember.StateManager - Transitions on Complex State Managers: it sends exit events in the correct order when changing to a state multiple times 
Ember.StateManager - Event Dispatching: it dispatches events to the current state 
Ember.StateManager - Event Dispatching: it dispatches events to a parent state if the child state does not respond to it 
Ember.StateManager - Event Dispatching: it does not dispatch events to parents if the child responds to it 
Ember.StateManager - Event Dispatching: it supports arguments to events 
Ember.StateManager - Event Dispatching: it supports multiple arguments to events 
Ember.StateManager - Event Dispatching: it throws an exception if an event is dispatched that is unhandled 
Ember.StateManager - Event Dispatching: it looks for unhandledEvent handler in the currentState if event is not handled by named handler 
Ember.StateManager - Event Dispatching: it looks for unhandledEvent handler in the stateManager if event is not handled by named handler 
Ember.Statemanager - Pivot states: transitionTo triggers all enter states 
Ember.Statemanager - Pivot states: transitionTo with current state does not trigger enter or exit 
Transition contexts: if a context is passed to a transition, the state's setup event is triggered after the transition has completed 
Transition contexts: if a context is passed to a transition and the path is to the current state, the state's setup event is triggered again 
Transition contexts: if no context is provided, setup is triggered with an undefined context 
Transition contexts: multiple contexts can be provided in a single transitionTo 
Transition contexts: multiple contexts only apply to states that need them 
Transition contexts: transitionEvent is called for each nested state 
Transition contexts: transitionEvent is called for each nested state with context 
Transition contexts: nothing happens if transitioning to a parent state when the current state is also the initial state 
Transition contexts: StateManagers can use `create`d states from mixins 
ember-states/~tests/state_manager_test: should pass jshint 
Ember.State: exists 
Ember.State: creating a state with substates sets the parentState property 
Ember.State: a state is passed its state manager when receiving an enter event 
Ember.State: a state can have listeners that are fired when the state is entered 
Ember.State: a state finds properties that are states and copies them to the states hash 
Ember.State: a state finds properties that are state classes and instantiates them 
Ember.State: states set up proper names on their children 
Ember.State: states with child instances set up proper names on their children 
Ember.State: the isLeaf property is false when a state has child states 
Ember.State: propagates its container to its child states 
Ember.State.transitionTo: sets the transition target 
Ember.State.transitionTo: passes no context arguments when there are no contexts 
Ember.State.transitionTo: passes through a single context 
Ember.State.transitionTo: passes through multiple contexts as additional arguments 
Ember.State.transitionTo: does not mutate the event contexts value 
Ember.State.transitionTo: passes no context arguments when called with no context or event 
Ember.State.transitionTo: handles contexts without an event 
ember-states/~tests/state_test: should pass jshint

pixelhandler/notes-ember-sc-state-manager-talk.md