Chart and dashboard definitions

When marketers or editors create charts and edit the dashboard in the Analytics app user interface, a .yaml file is generated automatically with the dashboard and chart definitions. This page explains the structure and properties of the .yaml files generated by the UI for informational purposes only.

Use the Analytics app UI to create or modify charts and configure the dashboard display.
Example of a generated .yaml file: /analytics-ui/dashboards/example-dashboard.yaml
hideMenuBarExtension: false
label: example dashboard
layoutId: "50-50"
chartDefinitions: !override
  - seriesGeneratorClass: info.magnolia.analytics.amcharts.data.DynamicSeriesGenerator
    name: Example chart
    label: Example chart
    styleName: "dashboard-flex-item-50"
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    transformerClass: info.magnolia.analytics.amcharts.data.JsonDataTransformer
    dataSupplier: dummyDataSupplier
    chartType:
      type: PieChart
      name: chartType
      class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
      legend:
        position: bottom
      series: !override
        - type: PieSeries
          name: series
          class: info.magnolia.analytics.amcharts.data.configuration.Series
          dataFields: !override
            - name: category
              jsonPath: "$.[*].city_name"
              class: info.magnolia.analytics.amcharts.data.configuration.DataField
              value: label
            - name: value
              jsonPath: "$.[*].nb_visits"
              class: info.magnolia.analytics.amcharts.data.configuration.DataField
              value: "nb_visits"

Magnolia provides integration with amCharts (info.magnolia.analytics.amcharts.data.AmChartDefinition) but you can also write your own simple charts (info.magnolia.analytics.common.SimpleChartDefinition).

Magnolia also provides info.magnolia.analytics.amcharts.data.DynamicSeriesGenerator to dynamically display values from multiple series.

Predefined amCharts chart types

The magnolia-analytics-ui submodule provides several predefined amCharts charts under /analytics-ui/chartTypes:

  • simple-line.yaml

  • trend-lines.yaml

  • line-different-colors-ups-downs.yaml

  • simple-bar.yaml

  • floating-bar.yaml

  • 3d-bar.yaml

  • simple-column.yaml

  • triangle-column.yaml

  • 3d-column.yaml

  • pie.yaml

  • 3d-pie.yaml

  • donut-with-radial-gradient.yaml

  • 3d-donut.yaml

  • candlestick.yaml

  • xy-chart-fills-axis.yaml

  • ohlc.yaml

  • timeline.yaml

You can see details of the amCharts chart types in their documentation.

You can reuse the predefined chart types when defining your chart definition using YAML includes and decorating the series provided.

Predefined chart definitions

The magnolia-analytics-ui submodule provides several predefined chart definitions under /analytics-ui/charts.

  • simple-line.yaml

  • trend-lines.yaml

  • simple-bar.yaml

  • floating-bar.yaml

  • 3d-bar.yaml

  • simple-column.yaml

  • triangle-column.yaml

  • 3d-column.yaml

  • pie.yaml

  • 3d-pie.yaml

  • donut-with-radial-gradient.yaml

  • 3d-donut.yaml

  • candlestick.yaml

  • xy-chart-fills-axis.yaml

  • ohlc.yaml

  • metric-number.yaml

  • word-cloud.yaml

The analytics-amcharts-samples submodule provides several predefined chart definitions under /analytics-amcharts-samples/charts.

  • timeline.yaml

  • pictorial.yaml

  • pyramid.yaml

  • funnel.yaml

Simple chart definition

This example shows the configuration for a simple chart that displays an icon plus the number of unique visitors to a page used to display results in the Magnolia A/B/n Testing app.

ABn testing chart

dataSupplier: dummyABTestDataSupplier
label: dashboard.chart.simpleLabel
class: info.magnolia.analytics.common.SimpleChartDefinition
icon: icon-datepicker
propertyOrJsonPath: $.uniqueVisitors

  • Adobe simple chart

  • GA4 simple chart

  • Matomo pie chart

Adbobe chart

chartDefinitions:
  chart-1: !include:/analytics-ui/charts/column-and-bar/simple-column.yaml
    dataSupplier: adobeDataSupplier
    chartType:
      # Decorate series for mapping json data
      series:
        - name: series
          dataFields:
            - name: categoryX
              jsonPath: $.rows[*].value
            - name: valueY
              jsonPath: $.rows[*].data[0]

GA4 chart

chartDefinitions:
  line2GA: !include:/analytics-ui/charts/column-and-bar/simple-column.yaml
    label: Session by date from GA4
    chartType:
      # This is example how to decorate chart type to decorate data field mapping
      series:
        - name: series
          dataFields:
            - name: categoryX
              jsonPath: $.rows.[*].dimensionValues.[*].value # Decorate jsonPath for categoryX to map data from GA4
            - name: valueY
              jsonPath: $.rows.[*].metricValuess.[*].value # Decorate jsonPath for valueY to map data from GA4
    dataSupplier: googleSupplier

Matomo chart

chartDefinitions:
    column2Matomo: !include:/analytics-ui/charts/pie-and-donut-group/pie.yaml
    label: User country from Matomo
    chartType:
      responsive:
        enabled: true
    dataSupplier: demoMatomoSupplier

In this example, the predefined pie.yaml chart doesn’t show a decorated series because Matomo can reuse the default series directly.

Custom AmChartType configuration

If you don’t want to use a predefined chart type supplied by Magnolia, you can configure your own. There are two ways of doing so:

  • Select the amCharts type you require and provide the native JSON-based config by amCharts.

    For example:

    analytics-amcharts-samples/dashboards/treemap-sankey-gauge-chord.yaml
    chartDefinitions:
  treemap:
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    dataSupplier: dummyForceDirectedTreeDataSupplier
    nativeJsonConfig: /info/magnolia/analytics/samples/json/treemap-sunburst-sankey-chord/dummy-treemap-sunburst-config.json
    type: TreeMap

  • Write your own chart type YAML configuration.

    For example:

    analytics-ui/charts/pie-and-donut-group/pie.yaml
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
dataSupplier: dummyDataSupplier
label: dashboard.chart.pie
chartTypeConfigurationName: pie
chartType:
  class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
  type: PieChart
  series:
    - name: series
      type: PieSeries
      dataFields:
        - name: category
          value: label
          jsonPath: $.[*].city_name
        - name: value
          value: nb_visits
          jsonPath: $.[*].nb_visits
  legend:
    position: bottom

    And include it in your chart definition:

      chart2: !include:/analytics-ui/charts/pie-and-donut-group/pie.yaml
    dataSupplier: mostActiveUsersOnPageDataSupplier
    label: dashboard.chart.chart2
    chartType:
      # This is an example of how to decorate a chart type to decorate data field mapping
      series:
        - name: series
          dataFields:
            - name: category
              jsonPath: $.[*].user # Decorate jsonPath for categoryX to map data from GA
            - name: value
              jsonPath: $.[*].['number of activations']
          ticks:
            disabled: true
          labels:
            disabled: true

Example of JSON config translated to YAML

Pie chart JSON config

<script src="//www.amcharts.com/lib/4/core.js"></script>
<script src="//www.amcharts.com/lib/4/charts.js"></script>

<div id="chartdiv" style="width: 900px; height 800px;"></div>

<script>
// Create chart instance in one go
var chart = am4core.createFromConfig({
  // Create pie series
  "series": [{
    "type": "PieSeries",
    "dataFields": {
      "value": "litres",
      "category": "country"
    }
  }],

  // Add data
  "data": [{
    "country": "Lithuania",
    "litres": 501.9
  }, {
    "country": "Czech Republic",
    "litres": 301.9
  }, {
    "country": "Ireland",
    "litres": 201.1
  }, {
    "country": "Germany",
    "litres": 165.8
  }, {
    "country": "Australia",
    "litres": 139.9
  }, {
    "country": "Austria",
    "litres": 128.3
  }, {
    "country": "UK",
    "litres": 99
  }, {
    "country": "Belgium",
    "litres": 60
  }, {
    "country": "The Netherlands",
    "litres": 50
  }],

  // And, for good measure, let's add a legend
  "legend": {}

}, "chartdiv", am4charts.PieChart);
</script>

Pie chart YAML config

class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
type: PieChart
series:
  - name: series
    type: PieSeries
    dataFields:
      - name: value
        value: litres
        jsonPath: $.[*].litres
      - name: category
        value: country
        jsonPath: $.[*].country

Properties

Property Description

chartDefinitions

required

     <your-chart-name>

required

A name for the given chart displayed in the dashboard. For example chart1.

If you are using a predefined chart definition

Use a Magnolia-specific directive YAML include to reuse the Predefined amCharts chart types delivered by the analytics-ui module.

For example:

chart1: !include:/analytics-ui/charts/pie-and-donut-group/pie.yaml

You then override the chart type series to adjust the data to your requirements.

         dataSupplier

required

The source of the data displayed in the charts. For example, googleSupplier, adobeSupplier or matomoSupplier.

         label

required

A text label displayed as the title of the chart in the dashboard. For example Session by date from GA.

         class

required

amChart definition class: info.magnolia.analytics.amcharts.data.AmChartDefinition

Simple chart definition class: info.magnolia.analytics.common.SimpleChartDefinition

         icon

required (only available for simple chart definitions)

A Magnolia font icon such as icon-user-public.

         propertyOrJsonPath

required (only available for simple chart definitions)

Defines the values displayed in the simple chart. Because all data suppliers must return JSON, you can specify a property in that JSON or use a JSONPath expression to point to the value you want to display.

For example, to get the number of unique visitors from the JSON file:

$.get_rate[0].nb_uniq_visitors

         chartType

required if you are using predefined chart definitions and overriding chart type series to adjust the data to your requirements

For example:

chartType:
      # This is example how to decorate chart type to decorate data field mapping
      series:
        - name: series
          dataFields:
            - name: categoryX
              jsonPath: $.reports[*].data.rows[*].dimensions[*] # Decorate jsonPath for categoryX to map data from GA
            - name: valueY
              jsonPath: $.reports[*].data.rows[*].metrics[*].values[*] # Decorate jsonPath for valueY to map data from GA

             class

required

Chart type class: info.magnolia.analytics.amcharts.data.configuration.AmChartType

             series

required

Each chart type can support only relevant amCharts series. When using a predefined chart type, the correct series is included. You must override the series to adjust the data to your requirements.

You must modify the entire series. Not just parts of it.

Series have two main purposes:

  • Setting appearance and behavior of a series of chart/map items.

  • Binding individual items in series to source data.

Many amCharts series settings are available.

                 dataFields

required

Defines the connection between data item and actual properties in raw data.

The name and value properties are required for the amCharts data fields. If you need a more advanced selection of data, you can also use the jsonPath property to filter the data.

                     name

required

The name of the data field.

                     value

required

The value of the data field.

                     jsonPath

optional

The JSONPath expression filters the data you retrieve about your site from the data supplier. The syntax you use depends on your data and what you want to display in your chart.

If you use a Google Analytics data supplier, you must have a valid Google Analytics access token to be able to run API requests. Get one here.

Copy your JSON output to https://jsonformatter.curiousconcept.com/ to format it if required.

Copy your JSON output again to https://jsonpath.com/ to test out your JSONPath syntax for the jsonPath property.

Example:

jsonPath: $.reports[*].data.rows[*].dimensions[*]

             xAxes

required for most chart types

Defines the X axis data and appearance. For example, in the predefined simple-bar.yaml chart type:

xAxes:
  - name: xaxe
    type: VALUE_AXIS

See the amCharts documentation about Axes.

             yAxes

required for most chart types

Defines the Y axis data and appearance. For example, in the predefined simple-bar.yaml chart type:

yAxes:
  - name: yaxe
    type: CATEGORY_AXIS
    renderer:
      minGridDistance: 10
      grid:
        location: 0
    dataFields:
      category: city_name
See the amCharts documentation about Axes.

         nativeJsonConfig

required If you are not using a predefined chart definition

Path to the native JSON-based config custom configuration you created.

For example:

chartDefinitions:
  treemap:
    label: treemap
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    dataSupplier: treeMapDataSupplier
    nativeJsonConfig: /info/magnolia/analytics/samples/json/treemap/treemap-config.json
    type: TreeMap

See Custom AmChartType configuration.

         type

required If you are not using a predefined chart definition

The chart type for the native JSON-based config custom configuration you created.

For example: TreeMap

Dynamic chart type configuration

If you need to dynamically display values from multiple series, you must use the following properties in your chartType:

Property Description

chartType

required

info.magnolia.analytics.amcharts.data.configuration.DynamicSeriesAmChartType

prefixRootJsonPath

required

The root of the variants in your JSON data.

seriesTemplate

required

Configure like the series property.

We currently support two types of dynamic series: LineSeries and ColumnSeries.

jsonPath

required

Specify the data value to be displayed.

The jsonPath configuration here does not need to contain the root path. At runtime, it’s combined: prefixRootJsonPath + indexOfSeries + jsonPath.

For example:

chartDefinitions:
  dynamic-lines:
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    label: dashboard.chart.dynamic-lines
    dataSupplier: dummyABTestDataSupplier
    chartType:
      class: info.magnolia.analytics.amcharts.data.configuration.DynamicSeriesAmChartType
      type: XYChart
      prefixRootJsonPath: $..variantsDailyResults
      seriesTemplate:
        type: LineSeries
        dataFields:
          - name: valueY
            value: value
            jsonPath: ..conversionRates..conversionRate
          - name: dateX
            value: date
            jsonPath: ..conversionRates..date
        tooltipText: '"{dateX}\n[bold font-size: 17px]value: {valueY}[/]"'
        strokeWidth: 3
      xAxes:
        - name: xaxe
          type: DATE_AXIS
          renderer:
            minGridDistance: 10
            grid:
              location: 0
      yAxes:
        - name: yaxe
          type: VALUE_AXIS
      cursor:
        type: XYCursor

Configuring dashboard definitions

Use the Analytics app to change the dashboard layout.

When a dashboard is created or edited, layoutId and styleName properties are added to the dashboard definition. By default, the dashboard is set to two equal-sized columns (layoutId: "50-50").

Charts are positioned automatically on a first come, first served basis in the columns from left to right on as many rows as are necessary for the number of charts you add.

Example: /analytics-ui/dashboards/test.yaml.
hideMenuBarExtension: false
label: dashboard-test
layoutId: "50-50"
chartDefinitions: !override
  - seriesGeneratorClass: info.magnolia.analytics.amcharts.data.DynamicSeriesGenerator
    name: test chart
    label: test chart
    styleName: "dashboard-flex-item-50"
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    transformerClass: info.magnolia.analytics.amcharts.data.JsonDataTransformer
    dataSupplier: dummyDataSupplier
    chartType:
Property Description

     layoutId

required, default is `"50-50"`

Defines the layout of your dashboard. For example, with a "25-25-25-25" layout, there are 4 equal columns in the dashboard.

Values possible:

  • "100"

  • "50-50"

  • "70-30"

  • "30-70"

  • "30-30-30"

  • "25-25-25-25"

         stylename

required, default is `"dashboard-flex-item-50"`

Defines the style of the chart corresponding to the layout.

Values possible:

  • `"dashboard-flex-item-100"`

  • `"dashboard-flex-item-70"`

  • `"dashboard-flex-item-50"`

  • `"dashboard-flex-item-30"`

  • `"dashboard-flex-item-25"`
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules