States¶
States are the building blocks of sandbox applications.
What are states?¶
A state corresponds to a small piece of an application. It might represent a single question in a survey, a menu, a greeting to send or a small booklet of text for someone to page through on their phone.
Each state has a name and a function to construct it, called its
creator. The creator takes the name of a state and options and should
return an instance of State().
Each state should transfer control to the next state once it is done.
States often have text to be displayed (to a person on their phone) and validation functions to parse input received.
How are applications built from states?¶
An application is a set of state creators collected into an
App(). An App() is controlled by an
InteractionMachine() which manages states and links an
application to the low-level sandbox API.
An InteractionMachine() receives messages from people (via the
sandbox API) and directs those messages to the current state. It also
tracks what state a person is interacting with and manages transitions
to new states.
Last but not least, an InteractionMachine() provides a set of
high-level interfaces to the sandbox API’s resources. These allow an
application to perform actions such as looking up or modifying a
contact, logging errors or warnings, making HTTP requests or storing
persistent data in a key-value store.
Delegation and virtual states¶
Some state creators represent virtual states. Instead of returning a state with the name associated with them, they return a state with a different name. Virtual creators are said to delegate to another state.
Delegators usually select between one of a set of other states and help structure applications cleanly and avoid repetition of logic for selecting which state to go to next.
What kinds of states are available?¶
An overview of the states available in the toolkit can be found in the Overview of States.
Reference¶
A complete reference guide to the available states can be found in the State reference.