A Solstice application is modeled as a state machine, where each state in the state machine's graph represents a page in the application.
Definitions
- state - a node in the state machine graph.
- transition - an edge in the state machine graph; also called an action.
- page flow - a set of transitions through a subset of the states.
- entrance - the initial state of a page flow.
Writing the pageflow.xml
The state machine and its page flows are defined in a file called pageflow.xml, which contains:
- A mapping from states to application controllers.
- One or more page flows that define transitions between the states.
Here is an example pageflow.xml:
XML
<?xml version="1.0"?>
<application>
<states>
<state name=
"home"
controller=
"MyApp::Controller::Application::Home"
/>
<state name=
"work"
controller=
"MyApp::Controller::Application::Workplace::Display"
/>
<state name=
"school"
controller=
"MyApp::Controller::Application::School"
/>
<state name=
"add_workplace"
controller=
"MyApp::Controller::Application::Workplace::Add"
/>
</states>
<pageflows>
<pageflow name=
"Main"
entrance=
"home"
>
<state name=
"home"
>
<transitions>
<transition action=
"stay_home"
state=
"home"
/>
<transition action=
"go_to_work"
state=
"work"
onback=
"nope"
>
<lifecycle name=
"update"
/>
</transition>
<transition action=
"go_to_school"
state=
"school"
/>
<begin action=
"add_workplace"
pageflow=
"add_workplace"
input=
"in"
output=
"out"
/>
</transitions>
</state>
<state name=
"work"
>
<transitions>
<transition action=
"go_home"
state=
"home"
>
<lifecycle name=
"revert"
/>
</transition>
</transitions>
<failovers>
<failover name=
"revert"
state=
"school"
/>
</failovers>
</state>
<state name=
"school"
>
<transitions>
<transition action=
"go_home"
state=
"home"
/>
</transitions>
</state>
</pageflow>
<pageflow name=
"add_workplace"
entrance=
"add_workplace"
>
<state name=
"add_workplace"
>
<transitions>
<transition action=
"done"
state=
"__exit__"
/>
</transitions>
</state>
</pageflow>
</pageflows>
</application>The <application> element contains a <states> section followed by a <pageflows> section.
The <states> section
The <states> section declares state names and the controllers that should be loaded when a page is generated. Thereafter, all states are referred to by the names declared. To specify a state, use <state name="statename" controller="controllername" />.
The <pageflows> section
The <pageflows> section contains one or more <pageflow> sections. There must be a page flow with the special name "Main", which denotes the initial page flow when a user enters the application. Each <pageflow> specifies an entrance state, and contains a series of <state> elements.
The <state> element
The <state> element refers to one of the declared states. It contains two sections:
<transitions>
<transitions> is a set of transitions defined by a unique action name and a target state. To define a transition to another state, use:
XML
<transition action=
"actionName"
state=
"targetState"
>
</transition>Transitions may also be to a new page flow in any installed application. You may specify an application name if the pageflow is contained an another installed application. Input and output names can be specified here to pass data in and out of the pageflow.
XML
<begin action=
"actionName"
pageflow=
"pageflowName"
application=
"applicationName"
input=
"inputName"
output=
"outputName"
>
</begin>In both types of transitions, you may specify which lifecycle stages will be executed. Inside the <transition> or <begin> element, use a <lifecycle> element to define a lifecycle function.
XML
<lifecycle name=
"validate"
/>
<lifecycle name=
"update"
/>
<lifecycle name=
"commit"
/>A special transition action named "__exit__" is reserved to exit from the current page flow. If you would like to disable the back button after a user transitions away from a state, you may specify a Solstice::LangService error key in the onback attribute. For example:
XML
<transition action=
"actionName"
state=
"targetState"
onback=
"backErrorMessage"
>
</transition>The onback attribute works similarly for the <begin> element.
<failovers>
If a lifecycle function fails, you may specify failover states to gracefully handle the error and inform the user. To specify a failover, use <failover name="lifecyclename" state="failoverstate" />, where lifecyclename is one of {"freshen", "validPreConditions", "validate", "update", "commit", "revert"}, and failoverstate is the name of the target state.