Classes

Improv

Improv parses message templates at runtime with data from user attributes, pre-populated data and/or custom extensions.

e.g. "hello ${ this.user.name }" will render with the value at the user.name path in current data.

Message strings containing expressions are automatically rendered by Improv middleware and can be merged with data from any source, including a Transcript search for instance.

Note:

• The data object is applied as 'this' in the scope where the template is rendered, e.g. this.user.name is the value at user.name path.
• Don't use back-ticks when declaring strings, or it will render immediately.
• Improv uses a singleton pattern to parse templates from a central middleware. It should be initialised with a robot via .use.
• Calling .reset() will clear everything (for testing).

Functions

use(robot) ⇒ Improv

Setup middleware and improv data collection in the brain.

This is the main interface to get either a new or existing instance. If the robot is new but an instance exists (e.g. in tests) then Improv will attach the new robot but keep existing config and extensions.

configure([options]) ⇒ Object

Configure the Improv instance

extend(dataFunc, [dataPath]) ⇒ Improv

Add function to extend current data when rendering a template. Should return key/values to merge and/or override keys of existing data.

If given a path argument, the extension function will only be called when the template string being rendered contains that path. This can prevent slow or expensive requests from running when their data isn't required.

Extensions can set properties within current data model or return a new object, the keys and values will be deep merged so either will work.

matchPaths(strings) ⇒ array

Search an array of strings for template expressions with this. data path.

mergeData(context, [paths]) ⇒ Object

Provdies current data to messages merged with response context any extra data returned by added extensions.

parse(context) ⇒ array

Replace expressions in sent string if they match the format of a data at a path bound to 'this', with the data at that path after collecting from all sources.

render(string, match, callData) ⇒ string

Convert string containing expression to an interpolation template and call with supplied data bound to 'this'.

Pre-renders expressions to catch and replace any unknowns. Failed expressions will be replaced with fallback unless a full replacement is configured, to replace the entire string.

middleware(context, next, done)

Middleware parses template expressions, replacing with data if required.

remember(path, value) ⇒ Object

Add data to context on the fly

rememberForUser(id, path, value) ⇒ Object

Add data to context specific for a given user's ID

forget(path) ⇒ Object

Remove data from data on the fly

forgetForUser(id, path) ⇒ Object

Remove data from data for a given user's ID

reset()

Wipte slate for tests to reinitialise without existing instance or context

Improv

Improv parses message templates at runtime with data from user attributes, pre-populated data and/or custom extensions.

e.g. “hello ${ this.user.name }” will render with the value at the user.name path in current data.

Message strings containing expressions are automatically rendered by Improv middleware and can be merged with data from any source, including a Transcript search for instance.

Note:

• The data object is applied as ‘this’ in the scope where the template is rendered, e.g. this.user.name is the value at user.name path.
• Don’t use back-ticks when declaring strings, or it will render immediately.
• Improv uses a singleton pattern to parse templates from a central middleware. It should be initialised with a robot via .use.
• Calling .reset() will clear everything (for testing).

Kind: global class

---

new Improv(robot)

Returns: Improv - New or prior existing (singleton) instance

Param	Type	Description
robot	Robot	Hubot Robot instance

---

use(robot) ⇒ Improv

Setup middleware and improv data collection in the brain.

This is the main interface to get either a new or existing instance. If the robot is new but an instance exists (e.g. in tests) then Improv will attach the new robot but keep existing config and extensions.

Kind: global function
Returns: Improv - The instance - really only accessed by tests

Param	Type	Description
robot	Robot	The robot to use, usually existing from constructor

---

configure([options]) ⇒ Object

Configure the Improv instance

Kind: global function
Returns: Object - The module exports for chaining

Param	Type	Description
[options]	Object	Key/val options for config
[options.save]	boolean	Keep data collection in hubot brain
[options.fallback]	string	Fallback content replace any unknowns within messages
[options.replacement]	string	Replace all messages containing unknowns, overrides fallback
[options.admins]	array	Array of usernames authorised to populate data

---

extend(dataFunc, [dataPath]) ⇒ Improv

Add function to extend current data when rendering a template. Should return key/values to merge and/or override keys of existing data.

If given a path argument, the extension function will only be called when the template string being rendered contains that path. This can prevent slow or expensive requests from running when their data isn’t required.

Extensions can set properties within current data model or return a new object, the keys and values will be deep merged so either will work.

Kind: global function
Returns: Improv - The instance for chaining

Param	Type	Description
dataFunc	function	Receives current data, to return more
[dataPath]	string	Scope for running the extension (optional)

Example (extend data with user transcript history)

improv.use(robot)
improv.extend((data) => {
  data.user.favColor = 'always blue'
  return data
}, 'user.favColor')
robot.send({ user: user }, 'I know your favorite color is ${ this.user.favColor }')
// ^ middleware will render template with the values and user in data
// ^ by providing the path, it will only be run when specifically required

---

matchPaths(strings) ⇒ array

Search an array of strings for template expressions with this. data path.

Kind: global function
Returns: array - Path matches objects\n

                    - [0]: expression including braces, e.g. `${ ... }`
                    - [1]: the path, e.g. this.path.to.data
                    - index: index of expression in string
                    - input: string containing the matched path  

Param	Type	Description
strings	array	Strings to search (usually from middleware)

---

mergeData(context, [paths]) ⇒ Object

Provdies current data to messages merged with response context any extra data returned by added extensions.

Kind: global function
Returns: Object - Data, middleware context and any extensions merged

Param	Type	Description
context	Object	Data provided at runtime to merge with improv data (usually from middleware)
[paths]	array	Paths required, to filter out unnecessary extensions

---

parse(context) ⇒ array

Replace expressions in sent string if they match the format of a data at a path bound to ‘this’, with the data at that path after collecting from all sources.

Kind: global function
Returns: array - Strings populated with context values

Param	Type	Description
context	object	Context object (usually from middleware)
context.strings	array	One or more strings being posted
context.response	object	Response object being replied to

---

render(string, match, callData) ⇒ string

Convert string containing expression to an interpolation template and call with supplied data bound to ‘this’.

Pre-renders expressions to catch and replace any unknowns. Failed expressions will be replaced with fallback unless a full replacement is configured, to replace the entire string.

Kind: global function
Returns: string - The result of rendering match input with given data

Param	Type	Description
string	string	The string to replace expressions within
match	object	RegExp result where string contained an expression
callData	object	Data to become ‘this’ when rendering expressions

---

middleware(context, next, done)

Middleware parses template expressions, replacing with data if required.

Kind: global function

Param	Type	Description
context	Object	Passed through middleware stack, with res
next	function	Called when all middleware is complete
done	function	Initial (final) completion callback

---

remember(path, value) ⇒ Object

Add data to context on the fly

Kind: global function
Returns: Object - The module exports for chaining

Param	Type	Description
path	array/string	The path of the property to set
value	*	The value to set

---

rememberForUser(id, path, value) ⇒ Object

Add data to context specific for a given user’s ID

Kind: global function
Returns: Object - The module exports for chaining

Param	Type	Description
id	string	The id of the user to remember for
path	array/string	The path of the property to set
value	*	The value to set

---

forget(path) ⇒ Object

Remove data from data on the fly

Kind: global function
Returns: Object - The module exports for chaining

Param	Type	Description
path	array/string	The path of the property to unset

---

forgetForUser(id, path) ⇒ Object

Remove data from data for a given user’s ID

Kind: global function
Returns: Object - The module exports for chaining

Param	Type	Description
id	string	The id of the user to remember for
path	array/string	The path of the property to unset

---

reset()

Wipte slate for tests to reinitialise without existing instance or context

Kind: global function

---