Skip to main content

Custom Chart properties

Chart definition properties

Type CustomChart {
fields {
field (multiple) {
label (optional): String
type: 'dimension' | 'measure'
sort (optional) {
apply_order (optional): Number
direction: 'asc' | 'desc'
}
data_type (optional): 'string' | 'number' | 'boolean' | 'date'
}
}

options (optional) {
option (multiple) {
label (optional): String
type: 'input' | 'number-input' | 'toggle' | 'radio' | 'select' | 'color-picker'
options (optional): List
default_value (optional): String | Number | Boolean
}
}

template: @vgl {
// Vega Lite JSON Specifications
};;
}

Field definition properties

field <field_name>

  • type (string) (required)

    Value: “dimension”, “measure”

    Specify if the field is a dimension or measure. If you set “measure”, any field dragged in this section will be aggregated.

    Note: Example charts from Vega-Lite library usually define aggregation within their codes, therefore you do not need to aggregate once more in Holistics. If you reuse those codes, it’s recommended to use the type “dimension” for all fields.

  • label (string) (optional)

    The field name, displayed in visualization settings to help users understand what it means.

  • sort (string) (optional)

    sort has two properties:

    • direction: Specify the direction that the field should be sorted.
    • apply_order: Specify the order that the field should be sorted, relative to other fields
  • data_type (string) (optional)

    Value: “string”, ”number”, “boolean”, “date”

    Limit the type of data that users can drag into in the exploration screen.

Option definition properties

option <option_name>

  • type (string) (required)

    Value: "input", "number-input", "toggle", "radio", "select", "color-picker" This property also determines how the option will be displayed in the STYLE tab.

  • options (string) (optional/required)

    If you set type as “select”, you are required to specify the option values users can choose from by this property. Otherwise this property is optional.

  • label (string) (optional)

    The option name, displayed in visualization settings to help users understand what it means

  • default_value (string/number/boolean) (optional)

    The value the option will take by default

Runtime data

Runtime data is the data generated while the code is running. It is not possible to pre-define any value for this type of data. You can use runtime data in the Template definition of Custom Chart.

field <name>

  • name

    Refer to the current field with all of its pre-defined properties.

  • format

    Refer to the current field’s format

  • type

    Refer to the current field’s data type

option <name>

  • value

    Refer to the current option with all of its pre-defined properties

Example

Suppose we have a Custom Chart definition as below:

CustomChart {
fields {
field a { // "a" is the field name
type: "dimension"
label: "field a" // displayed in Visualization Settings
sort {
apply_order: 1 // this field will be sorted first
direction: "asc" // sort direction: ascending
}
}
field b {
type: "measure" // any field dragged here will be aggregated
label: "field b"
sort {
apply_order: 2 // this field will be sorted second
direction: "desc"
}
}
}

options {
option tooltip {
type: 'toggle'
label: 'Show tooltip'
default_value: true
}
}

template: @vgl {
"data": {
"values": @{values}
},
"mark": {
"type": "bar",
"tooltip": @{options.tooltip.value},
},
"encoding": {
"x": {
"field": @{fields.a.name},
"type": "nominal",
},
"y": {
"field": @{fields.b.name},
"type": "quantitative"
}
}
};;
}

Suppose the user drags Created_at field into field a and Revenue field into field b. During runtime, the data is returned as below:

{
"data": {
"values": [
{"a": "01/01/2022", "b": 28},
{"a": "01/02/2022", "b": 55},
{"a": "01/03/2022", "b": 43},
]
},

fields: {
a: {
name: "Created_at" // see @{fields.a.name} in the definition
type: "date" // data type of the field user drags in field a
format: "mm/dd/yyyy" // format of the field user drags in field a
}

b: {
name: "Sum of Revenue" // because the field is aggregated
type: "number"
format: "Number (rounded)"
}
},
options: {
tooltip: {
value: true // see @{options.tooltip.value} in the definition
},
}
}

Let us know what you think about this document :)