Create a custom chart from Vega-Lite library

Before you start

For the concepts behind a custom chart definition (how fields, options, and the template fit together), see Understand Custom Chart. For the full syntax, see the AML Custom Chart reference.

This tutorial walks you through the steps to create a Simple Bar Chart from Vega-Lite library. This is our expected result:

Vega-Lite spec

{
  "data": {
    "values": [
      {"a": "A", "b": 28},
      {"a": "B", "b": 55},
      {"a": "C", "b": 43}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {
      "field": "a",
      "type": "nominal"
    },
    "y": {
      "field": "b",
      "type": "quantitative"
    }
  }
}

Holistics custom chart definition

CustomChartDef simple_bar_chart {
  label: 'Simple Bar Chart'

  fields {
    field a {
      type: 'dimension'
      label: 'Category'
    }
    field b {
      type: 'measure'
      label: 'Value'
    }
  }

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

Step 1: Create a new template file

Go to Development > Library > Custom Charts and create a new .chart.aml file. Inside it, define your chart using a CustomChartDef block.

A definition is a reusable template. It does not hold any data itself. It has three parts: fields (required), options (optional), and a template (required). For a Simple Bar Chart, we only need fields and template.

Step 2: Declare the fields

The fields are the slots users drag dataset fields into. To work out how many you need, look at the encoding of the Vega-Lite example: this bar chart maps one field to the x-axis and one to the y-axis, so we declare two.

CustomChartDef simple_bar_chart {
  label: 'Simple Bar Chart'

  fields {
    field a {
      type: 'dimension'
      label: 'Category'    // shown next to the field slot in Visualization Settings
    }
    field b {
      type: 'measure'      // fields marked 'measure' are aggregated automatically
      label: 'Value'
    }
  }
}

For everything fields accepts, see the fields reference.

Step 3: Write the template

The template holds the Vega-Lite specification that renders the chart. Since the Vega team already wrote this spec, we can copy it from the example and wire it up to Holistics data.

Two changes turn a static Vega-Lite spec into a dynamic Holistics chart:

• Replace the hard-coded data with @{values}, which receives the rows from the dataset at runtime.
• Replace each hard-coded field name with a @{fields.<name>.name} placeholder, so the chart uses whatever field the user drags in.

CustomChartDef simple_bar_chart {
  label: 'Simple Bar Chart'

  fields {
    field a {
      type: 'dimension'
      label: 'Category'
    }
    field b {
      type: 'measure'
      label: 'Value'
    }
  }

  template: @vgl {
    "data": {
      "values": @{values}   // receives the queried data from Holistics
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "field": @{fields.a.name},   // refers to the field dragged into slot a
        "type": "nominal",
        "axis": { "labelAngle": -45 }
      },
      "y": {
        "field": @{fields.b.name},   // refers to the field dragged into slot b
        "type": "quantitative"
      }
    }
  };;
}

Save the file. The new chart type now appears in the chart picker alongside the built-in charts, ready for anyone in your organization to use.

tip

The @{...} syntax is string interpolation. It is how the template reads data and user input at runtime. For the full list of placeholders, see Runtime variables.

Step 4: Build a report with the chart

Add a visualization, then pick your new Simple Bar Chart from the chart picker. Drag a dimension into the Category slot and a measure into the Value slot, and the chart renders:

note

Editing the CustomChartDef updates every report that uses this chart type, so changes to the definition propagate everywhere at once.

Where to find chart examples

Most custom charts start from an existing example rather than a blank template. These galleries are the best places to browse for a spec to adapt:

• Vega-Lite Example Gallery: the catalog to start with. Each example links to an editable spec you can copy into a @vgl template, as we did above.
• Vega Example Gallery: lower-level and more flexible than Vega-Lite. Use these when you need fine-grained control and write your template with @vg instead of @vgl.
• Vega Online Editor: paste a spec to preview and tweak it live before bringing it into Holistics. Handy for getting the visualization right first, then wiring in @{values} and field placeholders.
• Holistics Custom Chart Library: ready-made CustomChartDef examples that are already wired up to Holistics data, so you can copy a full definition instead of porting a raw Vega-Lite spec. The source also lives on GitHub.

When you copy a Vega-Lite spec, remember the two changes from Step 3: swap the hard-coded data for @{values}, and replace each field name with a @{fields.<name>.name} placeholder.

Next steps

• Make your chart match your built-in charts in Style a custom chart.
• Make a custom chart interactive so users can click and drag to filter.
• Add user-configurable styling controls with options.