Configuring a View in YAML

In this article

Configuring a View in YAML

View parameters are defined in several blocks:

metadata — basic view settings
widgetsSetting — global widget settings
inputs — input value variables
layout — view structure
widgets — widgets in the view
filters — predefined filters
actionButtons — action buttons

The metadata Key

The table below describes keys for defining basic view settings via the metadata key.

Key	Type	Definition
cornerRadius	number	Corner radius
maxWidth	number	Maximum view width If not specified, the view width is unlimited
autoUpdate	—	Auto-update
spacing	enum	Display spacing between widgets in Browse mode
color	enum	View background color in Browse mode: - `AUTO` — auto - `BASE` — solid
apiVersion	string	View version Depends on the system version
dividersHeight	—	Height of all dividers in the report

The dividersHeight Key

The dividersHeight block defines the height for all dividers in the view.

Key	Type	Definition
mode	string	- `FIXED` — value in pixels - `PERCENT` — value in percent (to use Auto, omit the `value` key)
value	number	Value

The autoUpdate Key

The autoUpdate block accepts the values listed below.

Key	Type	Definition
enabled	boolean	Enable/disable auto-update
minutes	boolean	Value in minutes

The widgetsSetting Key

The widgetsSetting block defines global settings for all widgets in the view.

Key	Type	Definition
paddings	string	Side paddings
titleSize	number	Title size
titleColor	—	Title color: - `AUTO` — auto - `BASE` — solid
titleWeight	enum	Font weight: - `NORMAL` — normal - `BOLD` — bold
textSize	number	Text size
filterMode	enum	Filter mode: - `DEFAULT` — default - `SINGLE` — single selection - `DISABLED` — disabled
ignoreFilters	boolean	Ignore filters
stateName	string	State

The inputs Key

The table below describes keys for defining input values via the inputs key.

Key	Type	Definition
name	string	Variable name
dbDataType	enum	Variable data type: - `STRING` — string - `INTEGER` — integer - `DATE` — date - `DATETIME` — date and time
multipleChoice	boolean	Array of values in the variable
defaultValue	string	Default value Defined by formula

The widgets Key

Widgets used in the view are added under the widgets key. Widgets are separated by the - symbol.

Example:

widgets:
  - key: kpi-list
    apiVersion: "16"
    type: KPI_LIST
    settings:
      title: ""
      titleSize: 14
      titleColor:
        mode: AUTO
      titleWeight: NORMAL
      showMarkdown: false
      markdownMeasures: []
      markdownText: ""
      measures:
        - name: Number of Stores
          value:
            mode: FORMULA
            formula: 'link: "Number of Stores"'
          format: NUMBER
          formatting: AUTO
          color:
            mode: AUTO
          dbDataType: Int64
          showName: true
          displayCondition:
            mode: DISABLED
          filters: []
          onClick: []
        - name: Number of Products
          value:
            mode: TEMPLATE
            tableName: product
            columnName: Product
            templateName: countDistinct
          format: NUMBER
          formatting: AUTO
          color:
            mode: AUTO
          formattingTemplate: ""
          dbDataType: Int64
          showName: true
          displayCondition:
            mode: DISABLED
          filters: []
          onClick: []
        - name: Sales Amount
          value:
            mode: TEMPLATE
            tableName: sale
            columnName: Sales Amount
            templateName: sum
          format: NUMBER
          formatting: CUSTOM
          color:
            mode: BASE
            value: "#6636c0"
          formattingTemplate: "#,###[$]"
          dbDataType: Float64
          showName: true
          displayCondition:
            mode: DISABLED
          filters: []
          onClick: []
        - name: Profitability
          value:
            mode: FORMULA
            formula: (sum("sale"."Sales Amount") - sum("sale"."Cost")) / sum("sale"."Sales Amount") * 100
          format: NUMBER
          formatting: x.x[%]
          color:
            mode: BASE
            value: "#ff9f43"
          formattingTemplate: ""
          dbDataType: Float64
          showName: true
          displayCondition:
            mode: DISABLED
          filters: []
          onClick: []
      displaySign: HORIZONTAL
      stateName: null
      filters: []
      sorting: []
      position: TOP
      measuresTextWeight: NORMAL
      measuresTextSize: 30
      alignment: LEFT
      filterMode: DEFAULT
      ignoreFilters: false
      nameSize: 12
      maxRowsName: 1
      itemsAlignment: LEFT
      paddings: 8
      markdownTextSize: 14
    localApiVersion: "2"
  - key: filter (1)
    apiVersion: "16"
    type: FILTER
    settings:
      title: ""
      titleSize: 14
      titleColor:
        mode: AUTO
      titleWeight: NORMAL
      showMarkdown: false
      markdownMeasures: []
      markdownText: ""
      textSize: 12
      dimensionLimit: 50
      displaySign: SELECT
      dimensions:
        - name: Store
          value:
            mode: FORMULA
            formula: '"store"."Store"'
          format: STRING
          formatting: AUTO
          dbDataType: String
      filterMode: DEFAULT
      ignoreFilters: false
      stateName: null
      filters: []
      sorting: []
      paddings: 8
      markdownTextSize: 14

The filters Key

Predefined filters can be applied to views. The filters block uses the following keys:

name — filter name
formula — formula used
dbDataType — formula data type
format — format
filteringMethod — filtering method
checkedValues — selected values
formValues — for manually entered values (values are specified in the block with numberRangekey)

Example of predefined filters:

filters:
  - dbDataType: UInt64
    format: NUMBER
    formula: '"events"."id"'
    name: id
    formValues:
      numberRange:
        - 100
        - 200
    filteringMethod: NONEMPTY
  - dbDataType: String
    format: STRING
    formula: '"events"."action"'
    name: action
    checkedValues:
      - Client Proposal Approval
      - Full Request Form Entry
    filteringMethod: INCLUDE

The actionButtons Key

Action buttons are added under the actionButtons key. For details on using action buttons, see Views.

Key	Type	Definition
name	string	Button name
buttonType	enum	Button type: - `primary` — primary - `primary-outlined` — secondary - `link` — link
type	enum	Click action type: `EXECUTE_SCRIPT` Only one action type is allowed
scriptKey	string	Script key
parameters	—	Script parameters (optional key)
autoUpdate	enum	Auto-update: - `NONE` — none - `ALL_WIDGETS` — all widgets

Configuring the View Grid in YAML

The layout Key

The view structure is a grid of rows and columns — layout. This block uses the rows key to configure and add rows.

The rows Key

The table below lists keys used in this block.

Key	Type	Definition
columns	—	Columns
widgetKey	string	Widget key to display in the column Only for `WIDGET` type
placeholder	—	Placeholder Only for `PLACEHOLDER` type
innerLayout	—	Nested layout Same structure as `layout` Only for `INNER_LAYOUT` type Available column content types: - `EMPTY` — none (empty column) - `WIDGET` — widget - `PLACEHOLDER` — placeholder
height	—	Column height
width	—	Column width Not applied to `DIVIDER` column type

The columns Key

The table below lists keys used in this block.

Key	Type	Definition
mode	enum	Column content type
alignment	enum	Column alignment within the row: - `left` — left-aligned - `center` — centered - `right` — right-aligned - `full` — full width

The height Key

The height block configures column height.

Key	Type	Definition
mode	enum	Column height calculation mode: - `FIXED` — fixed (in pixels) - `PERCENT` — dynamic (as percentage of screen height)
value	number	Height value Required in `PERCENT` mode

The width Key

The width block configures column width.

Key	Type	Definition
mode	enum	Column width calculation mode: - `FRACTION` — dynamic (as fraction of view width) - `FIXED` — fixed (in pixels)
value	number	Width value

Tabs (the tabs Key)

To add tabbed columns to a view, use the tabs block.

Key	Type	Definition
label	string	Tab label
displayCondition	—	Display condition
innerLayout	—	Nested layout Available column component types: `EMPTY` — empty column `WIDGET` — widget `PLACEHOLDER` — placeholder
likeViewBackground	boolean	View-like background Available only if view spacing is disabled in Browse mode
alignment	enum	Alignment: Options: `left` — left-aligned `center` — centered `right` — right-aligned
textSize	number	Font size
displayOneTab	boolean	Display single tab in view

Example of tabs usage:

layout:
  rows:
    - columns:
        - mode: TABS
          tabs:
            - label: Tab (1)
              displayCondition:
                mode: DISABLED
              innerLayout:
                rows:
                  - columns:
                      - mode: EMPTY
                        width:
                          mode: FRACTION
                          value: 1
            - label: Tab (2)
              displayCondition:
                mode: DISABLED
              innerLayout:
                rows:
                  - columns:
                      - mode: EMPTY
                        width:
                          mode: FRACTION
                          value: 1
          width:
            mode: FRACTION
            value: 1
    - columns:
        - mode: EMPTY
          width:
            mode: FRACTION
            value: 1

Example of a widget in a tab:

layout:
  rows:
    - columns:
        - mode: WIDGET
          widgetKey: barchart-140c3362
          width:
            mode: FRACTION
            value: 1
    - columns:
        - mode: EMPTY
          width:
            mode: FRACTION
            value: 1

Example of a placeholder in a tab:

layout:
  rows:
    - columns:
        - mode: PLACEHOLDER
          placeholder:
            name: Placeholder
            mode: EXISTED_VIEW
            viewKey: view-140c3362
          width:
            mode: FRACTION
            value: 1
    - columns:
        - mode: EMPTY
          width:
            mode: FRACTION
            value: 1

Example of nested layout:

layout:
  rows:
    - columns:
        - mode: INNER_LAYOUT
          innerLayout:
            rows:
              - columns:
                  - mode: EMPTY
                    width:
                      mode: FRACTION
                      value: 1
              - columns:
                  - mode: EMPTY
                    width:
                      mode: FRACTION
                      value: 1
          width:
            mode: FRACTION
            value: 1

Display Condition

To define a tab display condition, use the displayCondition block.

Key	Type	Definition
mode	enum	Display mode: `DISABLED` — always `VARIABLE` — by variable `FORMULA` — by formula
variableName	string	Variable name (only for `VARIABLE` mode)
variableValue	string	Variable value (only for `VARIABLE` mode)
formula	string	Formula (only for `FORMULA` mode)

Example of widget display by variable:

displayCondition:
  mode: VARIABLE
  variableName: variable_1
  variableValue: "value_1"

Example of widget display by formula:

displayCondition:
  mode: FORMULA
  formula: if(quantile(0.75)("p1"."TTCR") > 10, true, false)

Configuring a Placeholder in YAML

To add a placeholder to a view, use the placeholder block after the mode: PLACEHOLDER key-value pair. Example:

layout:
  rows:
    - columns:
        - mode: PLACEHOLDER
          placeholder:
            # Additional key-value pairs

The tables below list keys available for placeholder configuration.

Key	Type	Definition
name	string	Unique placeholder name
mode	enum	Mode: - `EMPTY` — none (empty) - `EXISTED_VIEW` — existing view - `GENERATED_BY_SCRIPT` — script-generated view
viewKey	string	View key to display in the column Only for `EXISTED_VIEW` mode
scriptKey	string	Script key Only for `GENERATED_BY_SCRIPT` mode
parameters	—	Script parameters Only for `GENERATED_BY_SCRIPT` mode

The parameters Key

The parameters block configures parameters for a script-generated view.

Key	Type	Definition
name	string	Parameter name
sourceVariable	string	Variable name
inputMethod	enum	Input method: - `VARIABLE` — variable - `AGGREGATION` — set by aggregation
considerFilters	boolean	Consider Filters switch: - `true` — enabled - `false` — disabled

Was the article helpful?

Yes

YAML Editor

Widget Configuration in YAML

.css-wsrjzs{display:inline;margin-right:12px;}@media screen and (max-width: 691px){.css-wsrjzs{display:inline-block;margin-right:0;}}Configuring a View in YAML