documentation for StateManager

[trek]

No description provided.

[wagenet]

Looks pretty good, though I'm not the expert on States. However, from what I understand, you really should only call goToState from within a state action. You generally should rely on actions to transition the manager to a different state.

[trek]

Excellent, just the sort of discussion I was hoping for. I've seen state actions mentioned several times, and always with the admonishment to always/only call them from "within a state". Sadly nobody ever provides an example of usage. I have an inkling of what they're getting – or at least suspect I do.

[wagenet]

@trek Thanks for getting this discussion going!

I think it the scenario would look something like this:

Two states: unauthenticated, authenticated. You start in unauthenticated. To go to authenticated, don't call stateManager.goToState('authenticated'). Instead, make an action on unauthenticated called authenticate and call goToState in that action. Does that make sense?

[trek]

That seems to be the go-to example, but nobody mentions where to make the call to the action. The presence of stateManager.send and parts of ActionHelper imply you'd call the send with the action name on the StateManager instance and let it handle finding the correct action function to call?

  aStateManager = Em.StateManager.create({
    initialState: 'unauthenticated',
    authenticated: Em.State.create({}),
    unauthenticated: Em.State.create({
      authenticate: function(stateManager, context){
        stateManager.goToState('authenticated')
      }
    })
  })

  aStateManager.send('authenticate')
  aStateManager.currentState.name // 'authenticated'

[wagenet]

@trek The code you have above is my understanding of the recommended way to do it.

[jgwhite]

Terrific write up of Ember’s StateManager and a nice introduction to State Machines generally.

[tomdale]

This should really be dashboard.get('navigationAreaView'), in case that property ever becomes watched for whatever reason.

[tomdale]

Thanks Trek. @wagenet nailed our current feelings on how states should be built--dispatch events using send() and have them be the ones to call goToState(). By default, state managers will throw an exception if you send an event and it is not handled by the current state or one of its parent states. We may want to cover turning this feature on or off.

The other nit-pick I had was that there a few places where you're not using the get() accessor method. It happens to work in the examples because the given properties never become watched, but I'd prefer to use the idiomatic Ember way to make sure we're consistent and don't confuse newbies.

[wonk]

Yow, delicious information!

Trek, thank you for such wonderful docs. (And thank you emberjs for such a juicy state machine.)

[trek]

@tomdale are you talking about just the calls to dashboard.contentAreaView or also the areas where I'm checking the currentState name to demonstrate state changes? dashboard.contentAreaView should defiantly change but my gut reaction on the examples for verification of state name was to isolate only StateManager related behavior. I can change them over to getPath() if you think it won't complicated the examples.

[tomdale]

@trek Yep, I'd change the state name stuff to getPath(). The reason is that I can't guarantee that a future implementation change may make some of those computed properties, in which case we'd probably forget to go back and update the documentation. :P

[rikkiloades]

Shouldn't the the target here should be App.states not App.appStates? If not then can you add a bit explaining how appStates translates to the App.states property below.

[trek]

Good catch, it's just a typo.

[tomdale]

Gonna merge this in. @trek, if you have any more changes, please submit a new PR. Thanks!