States

class State(name[, handlers])

Base class for application states.

Arguments:
  • name (string) – name of the state.
  • handlers (object) – Mapping of handler names to handler functions for state events. Possible handler names are setup_state, on_enter and on_exit. Handler functions have the form func(state).
class BookletState(name[, opts])

A state for displaying paginated text.

Arguments:
  • name (string) – name of the state
  • opts.next (fn_or_str) – state that the user should visit after this state. Functions should have the form f(message_content [, done]) and return the name of the next state. If the done argument is present, f should arrange for the name of the next state to be return asynchronously using a call to done(state_name). The value of this inside f will be the calling BookletState() instance.
  • opts.pages (integer) – total number of pages.
  • opts.page_text (function) – function func(n) returning the text of page n. Pages are numbered from 0 to (pages - 1). May return a promise.
  • opts.initial_page (integer) – page number to use when the state is entered. Optional, default is 0.
  • opts.buttons (object) – map of user inputs to amounts to increment the page number by. The special value ‘exit’ triggers moving to the next state. Optional, default is: {"1": -1, "2": +1, "0": "exit"},
  • opts.footer_text (string) – text to append to every page. Optional, default is: "\n1 for prev, 2 for next, 0 to end."
  • opts.handlers (object) – object of handlers for particular events, see State().
class Choice(value, label)

An individual choice that the user can select inside a ChoiceState().

Arguments:
  • value (string) – string used when storing, processing and looking up the choice.
  • label (string) – string displayed to the user.
class ChoiceState(name, next, question, choices, error, handlers[, options])

A state which displays a list of numbered choices, then allows the user to respond by selecting one of the choices.

Arguments:
  • name (string) – name used to identify and refer to the state
  • next (fn_or_str) – state that the user should visit after this state. Functions should have the form f(choice [, done]) and return the name of the next state. If the done argument is present, f should arrange for the name of the next state to be return asynchronously using a call to done(state_name). The value of this inside f will be the calling ChoiceState() instance.
  • question (string) – text to display to the user
  • error (string) – error text to display to the user if we reach this state in error. Optional.
  • handlers (object) – object of handlers for particular events, see State().
  • options.accept_labels (boolean) – whether choice labels are accepted as the user’s responses. For eg, if accept_labels is true, the state will accepts both “1” and “Red” as responses responses if the state’s first choice is “Red”. Defaults to false.
class LanguageChoice(name, next, question, choices, error, handlers[, options])

A state for selecting a language.

It functions exactly like ChoiceState() except that it also stores the value of the selected choices as the user’s language (it is still available as an answer too).

Choice() instances passed to this state should have two-letter language codes as values, e.g.:

new LanguageChoice(
    "select_language",
    "next_state",
    "What language would you like to use?",
    [ new Choice("sw", "Swahili"), new Choice("en", "English") ]
);

See ChoiceState() for a description of the parameters to the constructor.

class PaginatedChoiceState(name, next, question, choices, error, handlers, page_opts[, options])

A sub-class of ChoiceState() that splits the list of choices given into pages.

Arguments:
  • page_opts.back (string) – Label to use for the previous page option (defaults to Back).
  • page_opts.more (string) – Label to use for the next page options (defaults to More).
  • page_opts.options_per_page (integer) – Maximum number of options per page, excluding the next and previous page options (defaults to 8).
  • page_opts.characters_per_page (interger) – If set, labels for choices will be shortened so that there are no more than this number of characters per page of text sent to the user (default is null – i.e. don’t shorten any text). Shortened choices are truncated and have ... appended to indicate to the user that the option has been shortened. The character count includes all content rendered when displaying the state (i.e. the question, the choices selected for the page and any previous or next choices added by PaginatedChoiceState()).

Other parameters are described in ChoiceState().

class EndState(name, text, next, handlers)

A state which displays a list of numbered choices, then allows the user to respond by selecting one of the choices.

Arguments:
  • name (string) – name used to identify and refer to the state
  • text (string) – text to display to the user
  • next (fn_or_str) – state that the user should visit after this state. Functions should have the form f(message_content) and return the name of the next state. The value of this will be the calling EndState() instance. If next is null, the state machine will be left in the current state.
  • handlers (object) – object of handlers for particular events, see State().
class FreeText(name, next, question, check, error, handlers)

A state which displays a text, then allows the user to respond with any text.

Arguments:
  • name (string) – name used to identify and refer to the state
  • next (fn_or_str) – state that the user should visit after this state. Functions should have the form f(message_content [, done]) and return the name of the next state. If the done argument is present, f should arrange for the name of the next state to be return asynchronously using a call to done(state_name). The value of this inside f will be the calling FreeText() instance.
  • question (string) – text to display to the user
  • check (function) – a function func(content) for validating a user’s response. Should return true if the response is considered valid, and false if otherwise.
  • error (string) – error text to display to the user if we reach this state in error. Optional.
  • handlers (object) – object of handlers for particular events, see State().