Outlines are a conversation modelling schema / handler, with collections of attributes for setting up scenes, dialogues, paths and directors, for interactions defined as “bits”.
Define a key and condition to execute each bit, either consecutively off a prior bit, or with a listen attribute to become effectively a global entry point to a scene.
A subsequent bit can even lead back to it’s own parent or any other bit, creating a mesh of possible conversational pathways.
The setupScenes option is provided to disable (set to false) automatically
adding listeners for bits that enter scenes, in case there’s a need to
manipulate the bits first, then call .setupScenes() when ready.
Kind: global class
ObjectRegExpOutlineDialoguePromisePromise| Param | Type | Description |
|---|---|---|
| bits | Array.<Object> |
Array of objects with attributes to setup bits |
| bits[].key | string |
Key for scene and/or dialogue running the bit (required) |
| [bits[].send] | array |
String/s to send when doing bit (minimum requirement) |
| [bits[].catch] | string |
To send if response unmatched by listeners |
| [bits[].condition] | string |
Converted to regex for listener to trigger bit |
| [bits[].listen] | string |
Type of listener (hear/respond) for scene entry bit |
| [bits[].scope] | string |
Scope type for scene (only used if it has a listen type) |
| [bits[].next] | array |
Key/s (strings) for consequitive bits |
| [bits[].options] | Object |
Key/val options for scene and/or dialogue config |
| [options] | Object |
Key/val options for outline config |
| [options.setupScenes] | boolean |
Optionally set up scene listeners on load (default true) |
| [key] | string |
Key name for this instance |
ObjectHelper, finds a bit with a given key.
Kind: instance method of Outline
Returns: Object - Bit attributes
| Param | Type | Description |
|---|---|---|
| key | string |
Key name for required bit |
RegExpHelper, converts a mixed type condition into a regex.
Utility for loading regex properties from a file which cast them as strings or simply convert a single word to a regular expression.
Kind: instance method of Outline
Returns: RegExp - A valid expression for the given condition
| Param | Type | Description |
|---|---|---|
| condition | * |
RegExp to check or string to ccnvert |
OutlineSetup scene listeners for all “global” bits in the outline via Playbook.
Calling through Playbook (if available) allows it to keep a reference of all created scenes that may be interacted with via other modules, like directors and transcripts.
Only applicable to bits with a listen attribute (hear or respond).
Subsequent bits will play out within the same scene so their listen type is
irrelevant because all responses from an engaged audience will be routed
to the current dialogue.
Bits only require a .listen and .condition property to setup a scene
listener and will use defaults if .type and .options are undefined.
Kind: instance method of Outline
Returns: Outline - Self, for chaining
DialogueConfigure a dialogue with options from the executing bit (may be null).
Dialogue is already open from the scene being triggered and should have bit property already added by its callback.
This is unnecessary for the initial bit’s callback, because it inherits the bit options from the scene, but subsequent dialogue’s options must be overwritten for each executing bit.
Kind: instance method of Outline
Returns: Dialogue - The dialogue instance with bit config
| Param | Type | Description |
|---|---|---|
| res | Response |
Hubot Response object |
PromiseCallback for listener executing a bit. Called with ‘this’ bound to outline.
Send messages and setup any following listeners for a bit. May be on entering the scene or continuing from a prior bit. Adds the bit as response property.
The bit argument is provided from binding when setting up the listener, in the context of the listener firing, it will only call with res argument.
Kind: instance method of Outline
Returns: Promise - Resolves with addPath result (when sends completed)
or immediately if there’s no following bits.
| Param | Type | Description |
|---|---|---|
| bit | Object |
The bit being executed |
| res | Response |
Hubot Response object |
PromiseAdd path, options and branches to dialogue (within listener callback).
Response object must already be populated with bit and dialogue.
Here the bit’s catch property shorthand is converted to the path’s catchMessage config.
Kind: instance method of Outline
Returns: Promise - Resolves with addPath result (when sends completed)
| Param | Type | Description |
|---|---|---|
| res | Response |
Hubot Response object |