Plugin Helpers

Each plugin can provide helper functions to make it easy for you and others to work with your plugin and prevent code duplication. An example would be a function named renderChart() which will display the results of your plugin as a chart, which can be directly called from the plugin or Insight API jsx code.

Helper functions are exposed on your plugin's result object, making it possible to access them within your plugin's js, jsx as well as on the plugin results object itself, so that you or third-parties can call them from the Insights API.

When creating a third-party plugin, it's recommended to document the helper functions so that others know which functions are available and how they are used. More on this below in the helper documentation section.

Creating helpers

Helpers are defined by adding a JS text with an anonymous class definition in the plugin JSON results format under the helper key in the root of the JSON object.

Here is a simple example showing all possible variations:

{
...,
"data": {
"score": 7
},
"jsx": '''
<Insight>
{ results.helpers.renderScore() }
</Insight>
''',
"helper": '''
class {
constructor(results) {
this.calculatedScore = 1 * results.data.score;
}
renderScore() {
return (
<div>{ this.getScore() }</div>
);
}
getScore() {
return this.calculatedScore;
}
multiplyScore(factor) {
return factor * this.getScore();
}
getOriginalScore() {
return this.results.data.score;
}
}
'''
}

Defining a constructor is optional. this.results will always be available even without a constructor. The constructor should only be used when you want to do some pre-calculations that are shared among multiple helper functions.

Within the helper code, you can access this to call another helper function. Because all helpers are pre-initialized with this.results, you can access the data or metadata object for example like this: this.results.data.xyz or this.results.metadata.features.xyz.

Because helpers can return JSX directly, they can be called in the plugin's jsx or Insight API's JSX code to display things such as charts or other visual element.

Using helpers

Standalone

When a plugin runs as stand-alone, it first evaluates the js context and then jsx to display the visualizations — each of which can call any optionally defined helpers.
A good pattern is to keep the js unusued and in jsx only have a single call to some kind of render function, just as in the example above.

Insight API

Plugins can also be executed in the Insight API. The difference with stand-alone plugin runs is that the js and jsx contexts are not evaluated when in the Insight API. This is the reason to provide a single render helper function, so that from within the Insight API the plugin results can be displayed similarly to how it was done plugin example above under the jsx key.

Here's an example how it would look like in the Insight API:

Insight JS looks like:

const scoreResults = await PluginData.get("scorePlugin", {
data: new Intelligence({
goal: {event: "event_xyz"}
})
});
return {pluginResults: scoreResults};

Insight JSX looks like:

<Insight>
{ data.pluginResults.helpers.renderScore() }
</Insight>

Helper documentation

The helper functions can be documented with a JSON format as shown below. When making your plugin available to third-parties, this allows them to copy-paste fully ready code examples such as shown in the example below.

When creating a new plugin proider under the section "Documentation on helpers" a JSON object describing helper functions in your plugin.

Below is a full JSON helper documentation example showing most options.

First create an empty {}. Then for each helper function name, use that as a key on the object. Under each function name as key, the following keys can be specified:

  • title: Required — A short text description of what the function does. For example: "Calculates the sum of two numbers".
  • optional: Optional — A text to indicate in which cases this helper function is not available, or has some limitations. For example: "Works only if more than a year of data is available".
  • return: Optional — Used if the helper function has a return value. If used, should have an object of at least the format: {"type": "number", "title": "The sum of two values."}. type can be array, object, number, string, boolean, etc. Return type can be jsx to indicate that valid JSX is returned, and data to indicate that valid chart/table data is returned — the result can be supplied directly to <Chart data={data}/>.
  • args: Optional — Used if the helper function has one or more arguments. If used, should have an array with an element corresponding to the argument position. Each array element should be an object of at least the format: {"type": "number", "title": "The first number", "required": true, "default": 1}. type specifies the argument type such as type can be array, object, number, string, boolean. title is used to describe the argument, but also to indicate all possible argument values. required indicates if this argument can be skipped or not. default is also required and displays a valid argument value as example to the end-user — can be anything that is valid JSON (["item1", "item2", "item3"], true, 1.33, "predict", etc).

A full example below:

{
"chartData": {
"title": "Charted data.",
"return": {
"type": "data",
"title": "Presentations for line, bar and tables."
}
},
"chartDataYears": {
"title": "Charted data comparing years.",
"optional": "Only available if more than a year of data available.",
"return": {
"type": "data",
"title": "Presentations for line, bar and tables comparing different years."
}
},
"calculate": {
"title": "An easy way to calculate a result based on two numbers",
"return": {
"type": "number",
"title": "The calculated result"
},
"args": [
{
"type": "number",
"title": "The first number",
"required": true,
"default": 1
},
{
"type": "number",
"title": "The second number",
"required": true,
"default": 2
},
{
"type": "string",
"title": "The operation to apply on the two numbers, can be 'sum' or 'product'",
"required": false,
"default": "sum"
}
]
},
"displayItems": {
"title": "Displays all items",
"return": {
"type": "jsx",
"title": "A list of items"
},
"args": [
{
"type": "array",
"title": "An array of items to display",
"required": true,
"default": ["item1", "item2", "item3"]
}
]
}
}

This is displayed to the end-user as:

Plugin Helper Documentation