Legend

Displays a legend with signal labels and colors. The legend can be used to enable/disable specific signals.

Properties

• label: string – the legend box label
• labelClassName string: – name of the CSS class to use for rendering the legend label, defaults to "h4"
• configPath: string[] [R] – an array of field IDs that represent the "path" to a field (through the panel configuration object) containing the value of the configuration parameter describing signals.
• structure: [ Node, ..., Node, Leaf ] – describes how to access signal properties from elements of an array referred to by configPath. The structure array can contain zero or more Node objects preceding exactly one Leaf object. The Node objects describe a path to the Leaf object, while the Leaf object describes how to get the signal label, color, and selection state from an element of the array.
  • Node:
    • childrenAttr: string – name of the attribute in the configuration that leads either to the next Node or to the Leaf element.
  • Leaf:
    • labelFn: (object) => string – function that maps a configuration entry to signal label to be shown in the legend.
    • labelAttr: string – name of the configuration attribute holding the signal label, defaults to "label". Only used if labelFn is undefined.
    • colorFn: (object) => d3-color.color – function that maps a configuration entry to signal color to be shown in the legend.
    • colorAttr: string – name of the configuration attribute holding the signal color, defaults to "color". Only used if colorFn is undefined.
    • selectionAttr: string – name of the configuration attribute holding the signal selection state, defaults to "enabled".
• withSelector: boolean – displays a checkbox next to signal color and label, which allows any signal to be selected or unselected for display. Defaults to false.
• withConfigurator: boolean – allows the editing of the part of the panel configuration related to signal selection. If set to true, the Legend component must be provided with the definition of the configuration value (configSpec), which must match the respective part in the template configuration. The configurator is only shown to the users which have edit permissions to the panel.
• withConfiguratorForAllUsers: boolean – same as withConfigurator, but the configurator is shown to all users (if they don't have the edit permission to the panel, they can still change the displayed signals, but can't save the changes).
• configSpec: object – template parameter specifier object describing signal properties such as label, color, and selection state.
• className: string – name of the CSS class to use for rendering the legend object
• rowClassName: string – name of the CSS class to use for rendering legend rows, defaults to "col-12"

How to...

...display a legend with signal enabling/disabling

See the Linechart template example. The important things:

• Signals are configured in panel parameters (see the "sensors" parameter of type "fieldset").
• The Legend component has the following properties:
  • configPath: ["sensors"] as the signal configuration is a top-level parameter with id "sensors"
  • withSelector: true
  • structure: these are the IDs of the parameters inside the "sensors" fieldset:

    [
        {
            labelAttr: 'label',
            colorAttr: 'color',
            selectionAttr: 'enabled'
        }
    ]
    

...display a legend with signal configuration (the viewer can choose the signals)

See the Scatter plot with legend template example. The important things from the previous How-To also apply here (the id of the parameter is "years" this time). Additionally:

• The Legend component also has the following properties:
  • withConfiguratorForAllUsers: true
  • configSpec: The specification of the panel parameters can be retrieved using the getPanelConfigSpec() method added by the @withPanelConfig mixin. This method returns the whole array of panel parameter specification objects, so the appropriate item of this array has to be selected. If you want to allow the user to configure only a subset of the parameters inside the fieldset specified in the panel parameters, you have to set the configSpec manually to a parameter specifier object.
• Is is usually necessary to give the template the Elevated Access as otherwise the viewer would only have permission to display the signals which have been configured in the panel properties before loading the panel.