High-level method for state transitions

[timkindberg]

transitionTo() is a fairly low-level method in that it expects a "fully qualified" state and all parameters to be passed in. I want to add a higher-level method on top of it for everyday use where you can do stuff like

• Keep the values of existing parameters and only specify what changed
• Have some short-hand syntax for identifying parent or sibling states, maybe something like
• This syntax needs to work well from JS code and from within Angular expressions in a template -- from code having a state name (or short-hand), and a hash of parameters as two separate arguments seems fine, but I'm not sure how that would look within a directive (see next bullet point); I suppose the parameters could be a separate named attribute of the directive.

<!-- Maybe '@' could be short-hand for ($state.current.name + '.') ? -->
<button ng-click="$state.go('@edit')>Edit</button>

[timkindberg]

I like $state.go.

• Would go be able to accept an object-based state parameter? e.g. $state.go(contacts)
• For navigating to child I like '.' instead of '@' because it matches our state naming convention where as @ is being used for multiple views, so like this $state.go($state.current.parent)
• For navigating to a parent or root I would think we could do something like $state.go($state.current.parent) (or jsut $state.parent) and $state.go($state.root)
• For navigating to a sibling, who knows maybe $state.go('..siblingName'), two dots. Or '^name' or '>name'. I thought of '..' because its like navigating folders "../foldername" would get you to a sibling folder, but I didn't want to introduce the slash for fear it would start to feel like urls.

[nateabele]

As stated in #14, the traditional way to build a state machine is by defining events that specify valid state transitions. Using proper definitions, it is possible to determine which transitions are valid for each state, and preventing the state machine from reaching an unstable or unexpected state. Here's the canonical car example:

// Assume the following available states: "parked", "stalled", "idling", "firstGear", "secondGear"

.event("park", {
    from: ["idiling", "firstGear"],
    to: "parked"
})
.event("start" [
    { from: "stalled", to: "stalled" },
    { from: "parked", to: "idling" }
])
.event("idle" {
    from: "firstGear",
    to: "idling"
})
.event("shiftUp", [
    { from: "idiling", to: "firstGear" },
    { from: "firstGear", to: "secondGear" }
])
.event("shiftDown", [
    { from: "firstGear", to: "idling" },
    { from: "secondGear", to: "firstGear" }
])
.event("crash", {
    from: "*",
    to: "stalled"
]);

The events then become methods available on $state objects. Then, rather than there being any ambiguity, or possibility that the machine could transition into an unexpected state, the possibilities are clear:

// parked:
$state.start() // => "idiling"

// idling:
$state.shiftUp() // => "firstGear"

// firstGear:
$state.crash() // => "stalled"

// stalled:
$state.shiftUp() // => Error: Invalid state transition

The syntax here is just an example, the important part is the structure and semantics.

Another great feature of proper state machine events is that it makes wizard-like prev()/next() setups trivial. You just keep calling next() on each state to move to the next one.

This also solves the 'can we get there from here?' problems with transitionTo() (which would still exist in a generic 'event' like go()): you just need to do a reverse lookup to see if a valid event exists.

[timkindberg]

I think I love this! Should this a separate issue? Definitely needs to be explored!

[nateabele]

Having a separate issue is up to you. I just thought it made sense to put this here, since the events you define would be your high-level transition methods (and we can bundle parameter-passing up in them, too).

The other cool thing here, obviously, is that it takes the complication of explicit state references out of your templates.

[timkindberg]

Yeah ok, keep it here then. So would we then also do the hooks too like this?:

.event("park", {
    from: ["idiling", "firstGear"],
    to: "parked",
    before: fn(){},
    between: fn(){},
    after: fn(){}
})

[nateabele]

That could work, but you'd be more limited in how you apply them (for example, some hooks might apply over several events, so that could be pretty constraining). The syntax would at least need to be different though, because the second parameter needs to be able to be an array or an object hash.

[gregwebs]

This is not a good example for the project: it is a traditional FSM example, whereras we are dealing with application state. I found in my production application that there was no need to define transitions between states: instead the enter/exit callback hierarchy handled everything perfectly with the exception of first restricting based on login. It is probably important to this that StateTree supports concurrent sub states, which are much more difficult to figure out how to map to routes.

Defining transition events should be most useful for placing restrictions, so you might consider going back to #14 to discuss this. Either way you should make sure to use a real-world application routing example.

[timkindberg]

@gregwebs are you saying the before, between and after are not good, or the $state.event idea? I'm not quite sure how we'd use the transition hooks, but I do see how $state.event could be very helpful for high level navigation and actions (as @nateabele pointed out it could be used for prev/next actions as one example). We've heard from at least @jeme on actions as well.

[gregwebs]

I found the entire concept of event transitions ($state.event in this case) to be unnecessary. I just go to the state and the enter/exit callbacks handle things.

I don't think I understand the next/prev suggestion. That implies a linear ordering of states, but even in a traditional FSM one jumps around based on conditions & events. It seems that under an event setup a user would have to make an extra effort to define a chain of states that work based just on a next() invocation.

I think it could only be done automatically in our hierarchical setups as a way to move up & down from parent to child states when there is only one child or to move across sibling child states of a parent.

[nateabele]

I found the entire concept of event transitions ($state.event in this case) to be unnecessary. I just go to the state and the enter/exit callbacks handle things.

If you had a couple of examples handy, that might help with a point/counterpoint. I'm not committed to one way or the other right now, but in my experience having events be a separate thing helps to keep hook points DRY.

I don't think I understand the next/prev suggestion. That implies a linear ordering of states, but even in a traditional FSM one jumps around based on conditions & events.

This was just one off-the-cuff example explaining polymorphism of events and transitions, i.e. that the same event can be called in different contexts, with relevant contextual effects. In a linear wizard-like example, for one thing, it's possible to change your event definitions without having to poke through your UI bindings. Hope that makes sense.

[timkindberg]

I don't think I understand the next/prev suggestion. That implies a linear ordering of states, but even in a traditional FSM one jumps around based on conditions & events.

Yeah it wouldn't be a permanent API fixture, the next/prev events would be added by the user as needed. Similar to how the shift up/shift down events work in @nateabele's car example.

[ksperling]

I tend to agree with @gregwebs on this -- named transitions with actions associated with the transitions are obviously the bread and butter of traditional state machines, but I think those are quite different from our use case here.

I think it would really help to have some real world use cases of what sort of things you'd actually want to do in those "when going from A to B, do this" hooks. The provisioning of the UI templates / controllers is taken care of separately already.

I can't think of much myself -- even onEnter I don't see being used particularly often, and cases where i'd then additionally want to do different things based on what the previous state was seem rarer still. Happy to be convinced otherwise though.

We're still talking about web application UI's here... The idea that the same "page" in the app would behave radically different depending on how you got there seems to imply a rather odd user experience (unless you're building some game where each state represents a "room" or something like that...)