Skip to content

Template Parameters

Michal Töpfer edited this page Apr 4, 2021 · 5 revisions

Template parameters are described by a JSON snippet which contains an array of parameter specifier objects, one per template parameter.

The following specifier fields are mandatory for all parameter types:

  • id: string, represents the parameter identifier and the field name through which the parameter value will be accessible in the panel configuration object (see below)
  • type: string, specifies the parameter type, which determines both how the framework renders the parameter editor in the panel configuration UI, as well as the type of the value in the panel configuration object

The following specifier fields are optional for all parameter types:

  • label: string, represents a label presented next to the parameter value editor in the panel configuration UI
  • help: string, represents a short description of the parameter value presented close to the parameter value editor in the panel configuration UI

Simple types

Most parameter types supported by the framework represent simple value types (with the corresponding JavaScript type in parentheses). The type names are case sensitive:

  • boolean (boolean), holds true or false, default determined by the value of the default field in the parameter specifier, rendered as a checkbox
  • number, integer (number), holds an integer value, defaults to 0, rendered as an input field, parsed as an integer
  • float (number), holds a floating point number, defaults to 0, rendered as an input field, parsed as a float
  • string (string), holds a string value, defaults to "", rendered as an input field
  • text (string), holds a string value, defaults to "", rendered as a text area
  • html (string), holds a string value, defaults to "", rendered as a HTML editor
  • json (string), holds a string value, defaults to "", rendered as a JSON editor
  • color (d3-color.color), holds a color, defaults to rgb(0,0,0,1), rendered as color picker
  • option (string), holds a string value from predefined list of possible values, rendered as dropdown

The following specifier field is only supported for the boolean type:

  • default: boolean, represents the default value of a boolean parameter. If unset, the parameter will not be defined in the panel configuration object unless it is set to true.

The following specifier field is only supported for the number type:

  • isRequired: boolean, if set to true, the input field must contain a parsable number.

The following specifier field is only supported for the json and html types:

  • height: number, represents the height of the HTML or JSON editor (in lines of text).

The following specifier field is only supported for the option type:

  • options: { key, value }[], allowed values of the parameter. The key is the value of the parameter, the label is rendered to the user in the dropdown.

Special types

In addition to simple value types, the framework also supports several special types. These can be used to pass (sequences of) structured parameters, and to select signal sets and signals to be used by a template. These parameters support additional parameter specifier fields:-

  • signalSet (string), holds a signal set name, rendered as a selection from a table of available signal sets. The framework tracks parameters of this type and adds the selected signal set to the set of signal sets a template is authorized to access. A template without elevated access will only be able to access signal sets that are passed to it via template parameters.
  • signal (string | string[])
  • fieldset (object | object[]), represents either a single structured value object or an array of such objects, depending on the value of the cardinality specifier (see below).

The following (optional) specifier field is only supported for the fieldset and signal types:

  • cardinality: string, represents the cardinality of the parameter value, specified as a range in the form "[<min> .. ]<max|n>", where 0 <= min and min <= max.
    • If max is equal to literal "n", the upper bound is considered unrestricted and the lower bound defaults to 0 (if unspecified).
    • If max is an actual number, the upper bound is restricted and the lower bound defaults to max (if unspecified).
    • If the upper bound of the cardinality is greater than 1, the associated parameter value in the panel configuration object is an array (which can be empty if the lower bound of the cardinality equals 0)
    • If the upper bound of the cardinality equals 1, the parameter value in the panel configuration object is a single object (which can be null if the lower bound of the cardinality equals 0).
    • Defaults to "1 .. 1" if unspecified.
    • Use "0 .. 1" for optional parameters.

The following (optional) specifier fields are only supported for the signal type:

  • signalSet: string, contains the name of the signal set to pick signal names from.
  • signalSetRef: string, contains the id of a parameter of type signalSet which is used to find the signal set from which to choose signal names. The id can be either relative to the signal parameter (in the same fieldset), or an absolute one (looks in the top-level parameters) which has to start with a / character.
  • signalType: string | string[], allows to filter the signals and display only signals of certain type(s) in the selection table.

The following specifier fields are only supported for the fieldset type:

  • children: object[], contains parameter specifiers which define the structure of a value object. Depending on the cardinality of the corresponding fieldset parameter, accessing the parameter in the panel configuration object yields either a single value object, or an array of value objects. The specification of the child fields uses the same parameter specifiers as the top-level template parameters, but cannot include another fieldset.
  • flat: boolean, if set to true, the parameter will be rendered without label and without a border encapsulating the field set.

Accessing Parameters

The values of template parameters are stored in a panel configuration object. To make this object accessible to the template code, the template component needs to use the @withPanelConfig mixin from the ivis package. The component then provides a getPanelConfig() method which can be used to obtain the configuration object with panel-specific parameter values. The simplest way to display external configuration is to create a template which displays a JSON representation of the configuration object:

'use strict';
import React, { Component } from "react";
import { withPanelConfig } from "ivis";
 
@withPanelConfig
export default class Panel extends Component {
  render() {
    const config = this.getPanelConfig();
    return <pre>{ JSON.stringify(config, null, 2) }</pre>;
  }
}

Allowing viewer to (temporarily) change the parameters

The Legend component can display an UI similar to the panel configuration UI that allows the viewer to change the parameters for the currently viewed visualization. See the page of the Legend component for more details.

Example

With template parameters, even the simplest of templates (the “Hello World” example) can be made into a parametric template that displays a given message in a given color. To create a parametric template, we describe the template parameters using a JSON snippet which provides an array containing two parameter descriptors—one for the message to display, and one for the color to use:

[
  {
    "id": "message",
    "type": "string",
    "label": "Message",
    "help": "The message to display"
  },
  {
    "id": "color",
    "type": "color",
    "label": "Color",
    "help": "The color to use"        
  }
]

Then we provide template code which actually uses the external parameters. Note the correspondence between identifiers in the parameter descriptors and the field names used to access the parameter values in the panel configuration object, as well as the correspondence between the name of the function which renders a single message and the name of the JSX component returned by the render() method of the Panel component:

'use strict';
import React, { Component } from "react";
import { withPanelConfig } from "ivis";
 
@withPanelConfig
export default class Panel extends Component {
  render() {
    const config = this.getPanelConfig();
    return <Message { ...config }/>;
  };
}
 
function Message(props) {
  const style = { "color": props.color.hex() };
  return <p style={ style }>{ props.message }</p>;
}
Clone this wiki locally