Selector

Selector describes a set of controls to specify dashboard chart parameters.

The chart parses the parameter and applies a filter based on the field the parameter is linked with (see the example below). When supplying numeric parameter values to the selector, convert them to a string or an array of strings. This will prevent data presentation inconsistencies in different widget states, e.g., when it is simply displayed on the dashboard or opened for editing.

As a result of executing the Controls tab, the chart controls rendering data should be exported. This tab is available for all visualization types.

The controls are mainly designed for updating the parameters and re-rendering the chart. See the Params tab description for details on the chart parameters.

Structure on the Controls tabStructure on the Controls tab

You need to create a structure on the Controls tab in module.exports:

module.exports = {
    controls: [
        {
            // single control structure
        },
        ...
    ],
};

The structure depends on control type.

Fields common to all controlsFields common to all controls

There are fields common to all control types:

• type: Control type. Required field; string value type from these available values: input, textarea, datepicker, range-datepicker, select, checkbox, line-break, button.

• param: Name of the linked parameter. Required field; string value type. This option is available for all control types except line-break. If you change the value of such a control, the same value will be assigned to the linked parameter the next time the chart is re-rendered.

• updateOnChange: Property to initiate an update and re-rendering of the chart. You can set a value for each control to re-render it on change or only for a button, in which case all the changes made to the controls will be applied in one go once the button is clicked. Optional field; boolean value type. This option is available for all control types except line-break.

• updateControlsOnChange: Property to initiate re-rendering and updating the whole section of controls without re-rendering the whole chart. Optional field; boolean value type. This option is available for all control types except line-break.

  Note

  On the Sources tab, only sources with the ui: true property set will be requested. Invoking the Editor.getLoadedData() method after such a re-render will return data only for the re-requested sources.

• width: Control width. Optional field; string or number value type from the possible CSS property values. This option is available for all control types except button and line-break.

• hidden: To hide or not to hide the control from the page. Optional field; boolean value type.

• label: External selector header. Optional field; string value type. This option is available for all control types except line-break.

• labelPlacement: Location of external selector header. Optional field; string value type from these possible values: top or left. This option is available for all control types except checkbox, button, and line-break.

• innerLabel: Internal header. Optional field; string value type. This option is available for all control types except checkbox, button, and line-break.

• required: Indicates a required control. In which case set the default value for the parameter linked to the control, otherwise the control will be highlighted in red, and the chart selection will use an empty value for the parameter. This option is available for all control types except line-break.

• accentType: Accentuates the control in color. Optional field; the possible value is info string. This option is available for all control types except button and line-break.

• operation: You can specify an operator for the control via the OPERATIONS dictionary. If you do that, a string defining the operator type will be added to the parameter, e.g., the __gt_42 parameter will represent a selector with GT for operator and 42 for value. This option is available for all control types except button and line-break.

Input fieldInput field

Control with type: "input" (single line) or type: "textarea" (multi-line).

In addition to the common control fields, the following is available:

placeholder: Placeholder text displayed when the field has no content. Optional field; string value type.

Calendar (single date)Calendar (single date)

Control with type: "datepicker". The value of the linked parameter must be a string with an ISO date or relative date.

In addition to the common control fields, the following is available:

• minDate: Minimum possible value in ISO. Optional field; string or null value type, e.g., '2024-09-30'.
• maxDate: Maximum possible value in ISO. Optional field; string or null value type, e.g., '2025-09-30'.

Calendar (date interval)Calendar (date interval)

Control with type: "range-datepicker". You can use either param or paramTo, and/or paramFrom. If paramTo and/or paramFrom are present, the param field will not work. The value of the linked parameter must be a string with an ISO date or relative date. If the param field is used instead of paramFrom and paramTo, its value must be an interval.

In addition to the common control fields, the following is available:

• paramFrom: Name of the linked interval start parameter (instead of the param field). Required field; ISO string or relative date value type.
• paramTo: Name of the linked interval end parameter (instead of the param field). Required field; ISO string or relative date value type.
• minDate: Maximum possible value in ISO format. Optional field; string or null value type, e.g., '2024-09-30'.
• maxDate: Maximum possible value in ISO format. Optional field; string or null value type, e.g., '2025-09-30'.

ListList

Control with type: "select".

In addition to the common control fields, the following is available:

• multiselect: Property indicating whether multiple choice is enabled. Optional field; boolean value type.

• searchable: Property indicating whether the search bar is enabled. Optional field; boolean value type.

• content: Drop-down list content. Required field; object array type:

  [
      {
          title: "<string>",
          value: "<string>",
      },
      ...
  ],
  

  Where:

  • title: Displayed option name. Required field; string value type.
  • value: Option value; when selected, it is set as the linked parameter value. Required field; string value type. value must be a string because all parameters are converted to a string (true -> 'true', 42 -> '42'). Otherwise, the parameter value will not match any of the listed ones, and it will look as if the value is not selected.

CheckboxCheckbox

Control with type: "checkbox".

Line breakLine break

Control with type: "line-break".

ButtonButton

Control with type: "button".

In addition to the common control fields, the following is available:

• theme: Button theme. This is an optional field. String value type from the possible values of the view field of the Gravity UI design system Button component. The default value is action. Example of how it may look like.

• onClick: Action on click. Required field; object type:

  {
      action: "<string>",
      mode: "<string>",
      args: <object>,
  },
  

  Where:

  • action: Action type. This is a required field, its possible values are:

    • setParams: Sets new static parameters provided to args on click, example of action description:

      onClick: {
          action: "setParams",
          args: {
              month: "May",
              region: "RU",
          }
      }
      

    • setInitialParams: Sets parameters to defaults:

      • In preview, when editing chart/selector: in the Params tab.
      • On dashboard: in the chart/selector settings.
      • Fallback: in the Params tab.

      Example of action description:

      onClick: {
         action: "setInitialParams"
      }
      

  • mode: Determines the parameter update strategy. The possible values are:

    • replace (default): Overwrites all existing parameters with new args.
    • merge: Merges new args with current existing parameters.

  • args: Static arguments. Required field, its format depends on action type.

Adding a selector to a dashboard and reportAdding a selector to a dashboard and report

Adding a JS Selector to a report is similar to adding a regular selector to a separate section with all selectors.

If required, create aliases to link your selector to other widgets on the dashboard.

Special parametersSpecial parameters

To specify a relative date in the external selector parameters settings, use the following format: __relative_<symbol><quantity><unit>.

ExamplesExamples

• Selector with possible controls
• Selector that modifies a second selector depending on the first selector value
• Example of how the button may look like (selected in the selector)
• Example with controls in chart