App¶
-
class
App
(start_state_name[, opts])¶ The main component defining a sandbox application. To be subclassed and given application specific states and logic.
Arguments: - start_state_name (string) – name of the initial state. New users will enter this state when they first interact with the sandbox application.
- opts.AppStates (AppStates) – Optional subclass of
AppStates()
to be used for creating and managing states. - opts.events (object) –
Optional event name-listener mappings to bind. For example:
{ 'app:error': function(e) { console.log(e); }, 'im.user user:new': function(e) { console.log(e); } }
-
static
$
¶ A
LazyTranslator()
instance that can be used throughout the app to for internationalization using gettext. For example, this would send ‘Hello, goodbye!’ in the user’s language:self.states.add('states:start', function(name) { return new EndState(name, {text: self.$('Hello, goodbye!')}); });
-
static
exit
()¶ Invoked when the interaction machine has emitted an
IMShutdownEvent()
, which occurs after the interaction machine has finished processing the inbound message and has sent out a reply (if relevant). Intended to be overriden and used as a ‘teardown’ hook. May return a promise.
-
static
init
()¶ Invoked just after setup has completed, and just before ‘setup’ event is fired to provide subclasses with a setup hook. May return a promise.
-
static
remove
(name)¶ Removes an added state or state creator.
Arguments: - name (string) – name of the state or state creator
-
class
AppError
(app, message)¶ Thrown when an app-related error occurs.
Arguments: - app (App) – the app related to the error.
- message (string) – the error message.
-
class
AppErrorEvent
(app, error)¶ Emitted when an error is handled by the app, in case other entities want to know about the handled error.
Arguments: - app (App) – the app emitting the event.
- error (InteractionMachine) – the error that occured.
The event type is
app:error
.
-
class
AppEvent
(name, app)¶ An event relating to an app.
Arguments: - name (string) – the name of the event
- app (App) – the app emitting the event.
-
class
AppStateError
(app, message)¶ Thrown when an error occurs creating or accessing a state in an app.
Arguments: - app (App) – the app related to the error.
- message (string) – the error message.
-
class
AppStates
(app)¶ A set of states for a sandbox application. States may be either statically created via
add.state
, dynamically loaded viaadd.creator
(or viaadd
for either), or completely dynamically defined by overridingcreate
.Arguments: - app (App) – the application associated with this set of states.
-
static
add
(state)¶ Adds an already created state by delegating to
AppStates.add.state()
.Arguments: - state (State) – the state to add
-
static
add
(name, creator) Adds a state creator by delegating to
AppStates.add.creator()
.Arguments: - state (State) – the state to add
-
static
create
(name, opts)¶ Creates the given state represented by the given state name by delegating to the associated state creator.
Arguments: - name (string) – the name of the state to create.
- opts (object) – Options for the state creator to use. Optional.
If no creator is found for the requested state name, we create a start state instead.
This function returns a promise.
It may be overridden by
AppStates()
subclasses that wish to provide a completely dynamic set of states.
-
static
init
()¶ Invoked just after setup has completed, and just before ‘setup’ event is fired to provide subclasses with a setup hook. May return a promise.
-
AppStates.add.
creator
(name, creator)¶ - Adds a state creator. Invoked by
AppStates.create()
, or throws an error if a creator is already registered under the given state name.Arguments: - state_name (string) – name of the state
- creator (function) – A function
func(state_name)
for creating the state. This function should take the state name should return a state object either directly or via a promise.State creators can also delegate to other state creators by using
AppStates.create()
. For example, an app can do something like this:self.states.add('states:start', function() { return self.user.metadata.registered ? self.states.create('states:main_menu') : self.states.create('states:register'); });
-
AppStates.add.
state
(state)¶ Adds an already created state.
Arguments: - state (State) – the state to add
-
AppStates.creators.
__error__
(name)¶ Creates the fallback error state.
Arguments: - name (string) – the name of the state for which an error occurred.
This default implementation creates an EndState with name
name
and content “An error occurred. Please try again later”.The end state created has the next state set to the start state. If the start state does not exist, we in the error state again..
-
AppStates.creators.
__start__
(name)¶ Arguments: - name (string) – the name of the start state.
- im (InteractionMachine) – the interaction machine the start state is for.
The default implemenation looks up a creator for the state named
name
and calls that. If no such creator exists, it usesApp.creators.__error__()
instead.