State reference¶
A reference guide to all the states available in the toolkit.
-
class
State
(name, opts)¶ Base class for states in the interaction machine. States can be thought of as a single screen in a set of interactions with the user.
Arguments: - name (string) – name used to identify and refer to the state
- opts.metadata (object) – data about the state relevant to the interaction machine’s current user. Optional.
- opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Default is true. May also be a function, which may return its result via a promise.
- opts.continue_session (boolean) – whether or not this is the last state in a session. Default is
true
. May also be a function, which may return its result via a promise. - opts.helper_metadata (object) – additional helper metadata to set on the reply sent to the user. Primarily useful for setting voice metadata for messages destined to be sent as voice calls. Default is null. May also be a function, which may return its result via a promise.
- opts.check (function) – a function
func(input)
for validating a user’s response, whereinput
is the user’s input. If a string orLazyText()
is returned, the text will be taken as the error response to send back to the user. If aStateInvalidError()
is returned, itsresponse
property will be taken as the error response to send back to the user. Any other value returned will be taken as a non-error. The result may be returned via a promise. SeeState.validate()
. - opts.events (object) –
Optional event name-listener mappings to bind. For example:
{ 'state:invalid': function(e) { console.log(e); } }
-
static
display
()¶ The content to be displayed to the user. 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
input
()¶ Accepts input, invokes
State.translate.before_input()
, then emits aStateInputEvent`()
to allow input to be processed.
-
static
invalidate
(response)¶ Invalidates the user’s state, sending the given response to the user. Sets the state’s
self.error
object to an appropriate error and emits aStateInvalidEvent()
.Arguments: - response (string or
LazyText()
) – the response to send back to the user
- response (string or
-
static
invalidate
(error) Invalidates the user’s state using an error. Sets the state’s
self.error
object to an appropriate error and emits a :class:StateInvalidEvent``.Arguments: - error (StateInvalidError) – the error to invalidate the user’s state with.
-
static
save_response
(response)¶ Called by sub-classes to store accepted user responses on the user object.
Arguments: - response (string) – value to store as an answer.
-
static
setup
(im)¶ Called before any other methods on the state are called to allow the state to set itself up.
Arguments: - im (InteractionMachine) – interaction machine using the state.
-
static
show
()¶ Translates the state using
State.translators.before_display()
, then displays its text.
-
static
translate
(i18n)¶ Translate’s a state’s text using the given translator. May return a promise.
Arguments: - i18n (Translator) – the translation function to be used for translating the text.
-
State.emit.
input
(im)¶ Shortcut for emitting an input event for the state (since this is done quite often). See
StateInputEvent()
.
-
State.translators.
before_display
(i18n)¶ Translate’s a state’s text using the given translator. Invoked before text is displayed to the user. By default, just delegates to
State.translate()
. May return a promise.Arguments: - i18n (Translator) – the translation function to be used for translating the text.
-
State.translators.
before_input
(i18n)¶ Translate’s a state’s text using the given translator. Invoked before user input is processed. By default, just delegates to
State.translate()
. May return a promise.Arguments: - i18n (Translator) – the translation function to be used for translating the text.
-
State:set_next_state
(name)¶ Set the state that the user will visit after this state using the given state name.
Arguments: - name (string) – The name of the next state
-
State:set_next_state
(fn[, arg1[, arg2[, ...]]]) Use a function to set the state that the user will visit this state.
Arguments: - fn (function) – a function that returns name of the next state or an options object
with data about the next state. The value of
this
insidef
will be the calling state instance. May also return its result via a promise. - arg1, arg2, ... (arguments) – arguments to pass to
fn
- fn (function) – a function that returns name of the next state or an options object
with data about the next state. The value of
-
class
StateEnterEvent
()¶ Emitted when the state is entered by a user.
This happens when the state is switched to from another state, or when the state is created if this is the start of a new session).
Arguments: - state (State) – the state being entered.
The event type is
state:enter
.
-
class
StateEnterEvent
() Emitted when the state is exited by the user. This happens immediately before the interaction machine switches to a different state (see
StateEnterEvent()
).Arguments: - state (State) – the state being exited.
The event type is
state:exit
.
-
class
StateError
(state, message)¶ Occurs when interacting or manipulating a state causes an error.
Arguments: - state (State) – the state that caused the error.
- message (string) – the error message.
-
class
StateEvent
(name, state, data)¶ An event relating to a state.
Arguments: - name (string) – the event type’s name.
- state (State) – the state associated to the event.
-
class
StateEvent
(name, state, error) Emitted when a state becomes invalid.
Arguments: - state (State) – the state associated to the event.
- error (StateInvalidError) – the validation error that occured.
-
class
StateInputEvent
(content)¶ Emitted when the user has given input to the state.
Arguments: - state (State) – the state that the input was given to.
- content (string) – text from the user.
The event type is
state:input
.
-
class
StateInvalidError
(state, response[, opts])¶ Occurs when a state receives invalid input. Raised either by a failed validation check or by explicitly calling
State.invalidate()
.Arguments: - state (State) – the state that caused the error.
- response (string or LazyText) – the response to send back to the user.
- opts.reason (string) – the reason for the error.
- opts.input (string) – the user input that caused the error, if relevant
-
static
translate
(i18n)¶ Translate the error response.
Arguments: - i18n (Translator) – the translation function to be used for translating the text.
-
class
StateResumeEvent
()¶ Emitted when the state is resumed.
When the user enters input, the new sandbox run is started, causing the state to be re-created (or resumed) to process the user’s input. This means that when this event is emitted, the state has already been entered (see
StateEnterEvent()
) and its content has been shown to the user in a previous sandbox run (provided the session didn’t timeout when the send was attempted).Arguments: - state (State) – the state being resumed.
The event type is
state:resume
.
-
class
StateShowEvent
()¶ Emitted when a state’s is shown to a user, immediately after
State.display()
has completed.Arguments: - state (State) – the state being shown.
- content (string) – the content being shown.
The event type is
state:show
.
-
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, opts)¶ 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
- opts.question (string or LazyText) – text to display to the user
- opts.choices (Array of
Choice()
objects) – ordered list of choices to display - opts.error (string or LazyText) – error text to display to the user if bad user input was given. Optional.
- opts.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 tofalse
. - opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
- opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
- opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the
name of the next state, an options object representing the next state,
or a function of the form
f(choice)
returning either, wherechoice
is theChoice()
chosen by the user. Ifnext
isnull
or not defined, the state machine will be left in the current state. SeeState.set_next_state()
. - opts.events (object) – Optional event name-listener mappings to bind.
-
static
process_choice
(choice)¶ Return
true
if the choice has been handled completely orfalse
if the choice should be propagated to the next state handler.This allows sub-classes to provide custom processing for special choices (e.g. forward and back options for navigating through long choice lists).
Arguments: - choice (Choice) – choice to be processed.
-
static
shorten_choices
(text, choices)¶ Hook for replacing choices with shorter ones if needed.
-
class
LanguageChoice
(opts)¶ A state for selecting a language.
Arguments: - name (string) – name used to identify and refer to the state
- opts.next (fn_or_str) – state that the user should visit after this state. Functions should have
the form
f(choice)
and return the name of the next state or a promise that returns the name. The value ofthis
insidef
will be the callingChoiceState()
instance. - opts.question (string or LazyText) – text to display to the user
- opts.error (string or LazyText) – error text to display to the user if we reach this state in error. Optional.
- opts.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 tofalse
. - opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
- opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
- opts.events (object) – Optional event name-listener mappings to bind.
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: "next_state", question: "What language would you like to use?", choices: [ new Choice("sw", "Swahili"), new Choice("en", "English") ] } );
-
class
MenuState
(name, opts)¶ A
ChoiceState()
whoseChoice()
values are either state names or state options objects. SeeState.set_next_state()
for a description of the options objects.Supports the same parameters as
ChoiceState()
except thatopts.next
isn’t available.
-
class
PaginatedChoiceState
(name, opts)¶ A choice state for displaying long lists of choices by spanning the choices across multiple pages.
Arguments: - name (string) – name used to identify and refer to the state
- opts.next (fn_or_str) – state that the user should visit after this state. Functions should
have the form
f(choice)
and return the name of the next state or a promise that returns the name. The value ofthis
insidef
will be the callingChoiceState()
instance. - opts.question (string) – text to display to the user
- opts.error (string or LazyText) – error text to display to the user if we reach this state in error. Optional.
- opts.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 tofalse
. - opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
- opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
- opts.back (string) – the choice label to display to the user for going back a page. Default is “Back”.
- opts.more (string) – the choice label to display to the user for going to the next page Default is “Next”.
- opts.options_per_page (int) – maximum number of choices to display per page. Default is
8
. If this option is explicitly given asnull
,PaginatedChoiceState()
will automatically divide up the given choices to fit within the character limit given by the'characters_per_page'
option. - opts.characters_per_page (int) – maximum number of characters to display per page. Default is null (i.e. no
maximum), or
160
if the'characters_per_page'
option is explicitly given asnull
. - opts.events (object) – Optional event name-listener mappings to bind.
-
class
BookletState
(name, opts)¶ A state for displaying paginated text.
Arguments: - name (string) – name of the state
- opts.pages (integer) – total number of pages.
- opts.page_text (function) – function
func(n)
returning the text of pagen
. 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:
"1 for prev, 2 for next, 0 to end."
- opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
- opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
- opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the
name of the next state, an options object representing the next state,
or a function of the form
f(content)
returning either, wherecontent
is the input given by the user. Ifnext
isnull
or not defined, the state machine will be left in the current state. SeeState.set_next_state()
. - opts.events (object) – Optional event name-listener mappings to bind.
-
class
PaginatedState
(name, opts)¶ Add state type that divides up the given text into pages.
Arguments: - name (string) – name used to identify and refer to the state
- opts.text (string or LazyText) – the content to display to the user.
- opts.page –
The function to use to determine the text shown to the user.
The function should return the text to be displayed to the user as a
string
and take the formfn(i, text, n)
, where i` is the user’s 0-indexed current page number,``text`` is the translated text,n
is the maximum number of characters that can fit on the page (after taking into account the nagivation choices) andthis
is thePaginatedState()
instance.When the function returns a falsy value, page
i - 1
is taken as the last page to be displayed to the user. The function may also return a promise fulfilled with the value.If this option is not provided, the
PaginatedState()
will use a default function that will display the words that fit on the page based on the values ofi
and the given'characters_per_page'
option. - opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
- opts.characters_per_page (int) – maximum number of characters to display per page (including the
characters needed for the navigation choices). Default is 160.
'back'
,'more'
and'exit'
choices. - opts.back (string) – the label to display to the user for going back a page. Defaults to
'Back'
. - opts.more (string) – the label to display to the user for going to the next page. Defaults to
'More'
. - opts.exit (string) – the choice label to display to the user for going to the next state.
Defaults to
'Exit'
. - opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
- opts.next (function or string) – state that the user should visit after this state. May either be the
name of the next state, an options object representing the next state,
or a function of the form
f(content)
returning either, wherecontent
is the input given by the user when the user chooses to exit thePaginatedState()
. Ifnext
isnull
or not defined, the state machine will be left in the current state. SeeState.set_next_state()
. - opts.events (object) – Optional event name-listener mappings to bind.
-
class
EndState
(name, opts)¶ A state which displays text and then ends the session.
Arguments: - name (string) – name used to identify and refer to the state
- opts.text (string or LazyText) – text to display to the user
- opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the
name of the next state, an options object representing the next state,
or a function of the form
f(content)
returning either, wherecontent
is the input given by the user. Ifnext
isnull
or not defined, the state machine will be left in the current state. SeeState.set_next_state()
. - opts.events (object) – Optional event name-listener mappings to bind.
-
class
FreeText
(name, opts)¶ 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
- opts.question (string or LazyText) – text to display to the user.
- opts.send_reply (boolean) – whether or not a reply should be sent to the user’s message. Defaults to true.
- opts.continue_session (boolean) – whether or not this is the last state in a session. Defaults to true.
- opts.check (function) – a function
func(content)
for validating a user’s response, wherecontent
is the user’s input. If a stringLazyText()
is returned, the text will be taken as the error response to send back to the user. If aStateInvalidError()
is returned, itsresponse
property will be taken as the error response to send back to the user. Any other value returned will be taken as a non-error. The result may be returned via a promise. SeeState.validate()
. - opts.next (fn_or_str_or_obj) – state that the user should visit after this state. May either be the
name of the next state, an options object representing the next state,
or a function of the form
f(content)
returning either, wherecontent
is the input given by the user. Ifnext
isnull
or not defined, the state machine will be left in the current state. SeeState.set_next_state()
. - opts.events (object) – Optional event name-listener mappings to bind.