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:

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 via add.creator (or via add for either), or completely dynamically defined by overriding create.

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 uses App.creators.__error__() instead.