Dashboard widgets syntax

Introduction to the widgets syntax

This provides you with an introduction to the widget syntax which can be useful for customizing widgets beyond the functionality provided by the JSON dashboard editor.

The basic widget syntax is as follows:

{
  "name": "Widget Title",
  "type": "WidgetType",
  "props": {}
}

Table 1. Basic widget syntax
	Description
`name`	Defines the widget title, which is displayed in the widget header.
`type`	Defines the widget type.
`props`	Defines the properties of the widget. The properties vary depending on the `type` of widget.

The basic widget syntax for widgets connected to data, such as tables and charts, is as follows:

{
  "name": "Table Cars",
  "type": "Table",
  "props": {
    "container": "",
    "data": "cars",
    "spec": {},
    "search": ""
  }
}

Table 2. Basic syntax for widgets connected to data
	Description
`data`	You usually specify `data`. `data` refers to the table from which you want to extract data.
`spec`	You usually leave `spec` empty. The Dashboard generates a default `spec` as a starting point.
`container`	Optionally specify `container`. If `container` equals `""` or `"$current-scenario"`, it references the current scenario. The latter is useful when you have multiple scenarios. `container` can reference another scenario in the same Decision Optimization model by its name: `"container":"Scenario 1"`. It can also reference a list of different scenarios: `"container":["Scenario April","Scenario June"]`. To aggregate all the scenarios contained in a Decision Optimization model, use `"container":"*"`. `container` also supports the following syntax: `"container":"/regex/"` where all the scenarios with names containing `regex` will be referenced. Add `i` after the forward slash to ignore case differences, for example `"container":"/april/i"` will reference all scenarios with names containing `april` or `April`. The rows of the listed scenarios are concatenated in a single table, with an additional column `$scenario` containing the name of the scenario.
`search`	Saves the content of the search text field.

Notes Widget specifications

The Notes Widget can be styled as a post-it note, as shown in the following code sample:

{
  "name": "Notes",
  "type": "Notes",
  "props": {
    "notes": "My post-it note",
    "style": {
      "background": "#ffe"
    },
    "headerStyle": {
      "background": "#ffe"
    }
  }
}

This style example is applicable to other widgets.

Table Widget specifications

Table widget specifications are composed of a list of columns following this syntax:

{
  "name": "Table Cars",
  "type": "Table",
  "property": "Acceleration",
  "label": "Acceleration",
  "type": "Number",
  "visible": true,
  "width": 100,
  "style": {}
}

Table 3. Table widget specifications
	Description
`property`	Key property to access data in a given row.
`type`	Required to have a proper search and filter feature as numbers are not searched like strings.
`visible`	Allows you to easily display or hide any column without completely removing its definition.
`label`	Defines the column headings.
`style`	Allows you to style tables by adding CSS properties in camelCase. For example, if you want to specify the alignment of text in a table, use `textAlign` rather than `text-align`.

You can customize the rendering of tables using the following elements:

Table 4. Table widget customization
	Description
`numbered`	Displays row numbers.
`compact`	Reduces row height.
`columnExpand`	Set `columnExpand` to `true` to expand column widths to fit into the widget.
`columnShrink`	Set `columnShrink` to `true` to shrink the column widths to fit into the widget.

There is a search and filtering feature available in tables. To search content in a table, click the search icon . You can limit your search to a specific column by adding a prefix to your search as follows: "column heading":"search", for example name:chevrolet. To search values ranging from x to x, use 10..20. You can also search values greater than x, for example 10.., and values less than x, for example ..20. For more information about table filtering, see Table search and filtering.

Charts widget

There are two types of chart widgets: Vega Charts and Charts. Different types of charts are available when you open these Chart Widget Editors.

Vega Chart Widget specifications

The Vega Chart Widget uses Vega-Lite specifications to create different types of chart (bar charts, point charts, etc.). If you leave spec empty, a simple bar chart is automatically generated with the first string column in x-axis and the first number in y-axis.

Vega-Lite enables data filtering and transformation. For example, strings can be transformed into dates.

To learn more about Vega-Lite, see Vega-Lite - A High-Level Visualization Grammar.

Below is an advanced example of a grouped bar chart based on a population data table. This example shows how to filter data and how to compute a virtual column:

{
  "name": "Population Grouped Bar Chart",
  "type": "Chart",
  "props": {
    "data": "population",
    "spec": {
      "transform": [
        {
          "filter": "datum.year == 2000"
        },
        {
          "calculate": "datum.sex == 2 ? 'Female' : 'Male'",
          "as": "gender"
        }
      ],
      "mark": "bar",
      "encoding": {
        "column": {
          "field": "age",
          "type": "ordinal"
        },
        "y": {
          "aggregate": "sum",
          "field": "people",
          "type": "quantitative",
          "axis": {
            "title": "population",
            "grid": false
          }
        },
        "x": {
          "field": "gender",
          "type": "nominal",
          "scale": {
            "rangeStep": 12
          },
          "axis": {
            "title": ""
          }
        },
        "color": {
          "field": "gender",
          "type": "nominal",
          "scale": {
            "range": [
              "#EA98D2",
              "#659CCA"
            ]
          }
        }
      },
      "config": {
        "facet": {
          "cell": {
            "strokeWidth": 0
          }
        },
        "axis": {
          "domainWidth": 1
        }
      }
      }
    }
  }
}

Gantt widget

In this release, there is no specific customization syntax for the Gantt widget. Gantt charts are only available to display the solution for scheduling problems created with the Modeling Assistant.