dashbuilderLogo

Welcome

1. What is Dashbuilder

Dashbuilder is a tool for creating dashboards and data visualizations for developers and non-technical users. Dashboards can be created using Java, a drag and drop web application or pure YAML and later run on a cloud native web application or in a client bundle.

dashbuilderSampleDashboard
Figure 1. Sample Dashbuilder Report

2. Concepts

In this section we explore the concepts used by Dashbuilder.

2.1. Pages

Pages is where the data visualization lives. It follows a grid approach for organizing the visualization which means that it is organized in rows, columns and components; columns can have their own rows and columns. It is also possible to modify the CSS properties of each page part.

2.2. Navigation

Navigation is an optional component and it is about the relationship between pages. When you have more than one page then a menu is displayed with all pages, you can organize this menu. Furthermore, navigation is the key for embedding pages inside each other.

2.3. Datasets

DataSets are the source of your data. The data can come from different sources, including CSV, SQL, Prometheus, Kafka Metrics and JSON. For the full client application only JSON is supported, but CSV on client is on the roadmap. More than loading from a source of data, dashbuilder datasets can be cached and later be spliced, filtered, ordered and grouped for a specific visualization.

2.4. Components

Components are the front ends for static content, data visualization or a navigation component:

  • Static components are used for visualization that does not require a dataset. Examples are HTML and forms.

  • Data Visualization components are offered natively by dashbuilder and they can be charts, filters or text that shows some aggregate information from the dataset.

    • Supported charts are bar, area, line, pie, donut and map.

Some of native dashbuilder components
Figure 2. Some of native dashbuilder components

  • Filters can be presented as labels or a drop down selector

Filter components
Figure 3. Filter Components

  • The metric component uses HTML and JS templates to show a grouped dataset information

Metric components
Figure 4. Metric Components
These components offer multiple options, such as auto refresh, title, margin and others.

  • Navigation components allow you to embed other pages using different ways: Tabs, carousel, tiles, menu and tree navigation.

Navigation components
Figure 5. Navigation Components

2.5. External Components

External components are like components, but the code used to build it will run in an isolated container (currently an iframe). It means that with external components it is possible to use any web technology to represent a dataset, users just know how to use the external components Javascript API.

External Components development
Figure 6. External Components Development

3. Authoring

There are three main ways of creating dashboards and data visualizations with Dashbuilder: Authoring Tool, Java, and YAML.

3.1. Dashbuilder Authoring

Dashbuilder Authoring is a web application which allows users to create pages using the layout editor, a drag and drop tool. It is available as a container and the result can be downloaded in ZIP format. It has three screens only: Pages, DataSets and Export/Import.

Dashbuilder Authoring
Figure 7. Dashbuilder Authoring

3.2. Java API

There’s a Java API to create and export Dashboards to ZIP format. It exposes the internal API in a DSL-ish API. The greatest advantage of using the Java API is that you can grab data to build static datasets, making high performance data visualizations integrated to Dashbuilder Runtime, which we will talk about later. Currently it only exports to ZIP, but it is our roadmap for a new Java DSL that will export YAML dashboards.

// creates a data set with pure Java code - external sources can be used as well
var dataSet = newDataSetBuilder().column("Country", ColumnType.LABEL)
                                    .column("Population", ColumnType.NUMBER)
                                    .row("China", "1439323776")
                                    .row("India", "1380004385")
                                    .row("United States", "331002651")
                                    .row("Indonesia", "273523615")
                                    .row("Pakistan", "220892340")
                                    .row("Brazil", "212559417")
                                    .row("Nigeria", "206139589")
                                    .row("Bangladesh", "164689383")
                                    .row("Russia", "145934462")
                                    .row("Mexico", "128932753")
                                    .buildDataSet();

// a bar chart configuration that is used to visualize the data set
var popBarChart = newBarChartSettings().subType_Column()
                                        .width(800)
                                        .height(600)
                                        .dataset(dataSet)
                                        .column("Country")
                                        .column("Population")
                                        .buildSettings();
// a page with a HTML header and the displayer that uses the bar chart configuration
var page = page("Countries Population",
                row("<h3> Countries Population</h3>"),
                row(displayer(popBarChart)));

// finally exports the dashboard to a local ZIP file
DashboardExporter.get().export(dashboard(asList(page)),
                                "population.zip",
                                ExportType.ZIP);

3.3. YAML and JSON

The most recent addition to Dashbuilder is the possibility to live load JSON and YAML dashboards. Different from the export ZIP dashboard, this new way of creating dashboards can be used in a client-only Dashbuilder installation accessing JSON datasets. You can try it in an online editor, which is also used to visualize the dashboards. A new YAML editor based on Monaco is in the roadmap.

Dashbuilder YAML Authoring
Figure 8. Dashbuilder YAML Editor

4. Deployment

Deploying dashbuilder content is achieved by using Dashbuilder Runtime. The ZIP files exported from the Authoring tool or from the Java DSL can be used directly with Dashbuilder and with its modes.

4.1. Cloud

Dashbuilder Runtime has been part of Quarkus since version 0.14.1, which makes its starts in no more than a few seconds and it is by default cloud native. A container image is published with each Kogito Tooling release, making it easy to run Dashbuilder Runtime on Openshift or Kubernetes.

4.2. Runtime Modes

It is possible to run Dashbuilder Runtime with a dedicated dashboard or run multiple dashboards in a single installation:

  • Single: Just start Dashbuilder Runtime with no dashboards and you will be able to upload a single dashboard. Bear in mind that after restart the dashboard is lost;

  • Static: Use the system property dashbuilder.runtime.import to point to the ZIP file in your file system. If the dashboard is remote then you also need to set the system property dashbuilder.runtime.allowExternal to true.

  • Multi: In this multi-mode dashbuilder looks for dashboards in the directory configured with the system property dashbuilder.import.base.dir (default is /tmp/dashbuilder/models). To turn multi mode on, set dashbuilder.runtime.multi as true and set dashbuilder.model.update as true to have dynamic model updates (new and deleted dashboards are reflected during runtime).

Dashbuilder Runtime Multi Mode
Figure 9. Dashbuilder Runtime in Multi Mode

  • Dev: In development mode dashbuilder hot reloads dashboards based on ZIP changes. Set the property dashbuilder.dev to true, start dashbuilder, place ZIPs on the dashboards directory and you should see the page auto refresh with the ZIP changes.

4.3. Client Bundle

To deploy dashboards in client:

  • Unzip Dashbuilder Client bundle;

  • Edit setup.js to list the dashboards location;

  • Host the content in some static files provider.

5. Installation

In this section we cover build and installation of Dashbuilder Authoring and Dashbuilder Runtime.

5.1. On-Premise Installation

Dashbuilder is released as part of KIE Tools. Download the file dashbuilder_dist_{version}.zip

Requirements:

  • Java 11+

Dashbuilder Authoring

Dashbuilder Authoring is distributed as a WAR that can run on JBoss EAP or Wildfly or a executable JAR.

The JAR is a "bootable server" that can executed using the following command: java -jar dashbuilder-authoring-bootable.jar

Dashbuilder assets are stored in the directory .dashbuilder. It is possible to change the directory using the system property org.dashbuilder.project.location.

Dashbuilder Authoring can also export a ZIP whenever an asset (page, dataset or navigation) is saved. To enable it set the system property dashbuilder.export.location to a valid ZIP location.

Dashbuilder Runtime

Dashbuilder Runtime is a Quarkus application that can run with the following command:

java -jar dashbuilder-runtime-app.jar

To run Dashbuilder Runtime in static mode:

java -Ddashbuilder.runtime.import=/path/to/dashboard.zip -jar dashbuilder-runtime-app.jar

Or in multi mode:

java -Ddashbuilder.runtime.multi=true -jar dashbuilder-runtime-app.jar

5.2. Container Images

Runtime

quay.io/kogito_tooling_bot/dashbuilder-runtime

You can pass Java properties using the JAVA_OPTS environment variable. For example, to run Dashbuilder Runtime in multi mode use the following command:

podman run -p 8080:8080 -e “JAVA_OPTS=-Ddashbuilder.runtime.multi=true -Ddashbuilder.runtime.allowUpload=true” -dti quay.io/kogito_tooling_bot/dashbuilder-runtime:latest

Authoring

quay.io/kogito_tooling_bot/dashbuilder-authoring

Dashbuilder Authoring image uses the WAR bits and uses as base Wildfly 23.0.2 image.

5.3. Client only

YAML definitions runs on a client side installation. Currently the way to install YAML is using Javascript:

  • Have a HTML page where dashbuilder client bundle runs on an iframe;

  • Dashbuilder sends a message to the parent frame saying that it is ready to receive content;

  • The parent frame sends a message to dashbuilder with the YML content

Here’s the sample Javascript:

// flag to indicate that dashbuilder is ready for content;
var ready = false;
window.addEventListener("message", (e) => {
  if (e.data === "ready") {
    ready = true;
  }
});

// Updates dashbuilder with the content (only if it is ready)
const send = () => {
    if (ready) {
        document.getElementById("dbFrame").contentWindow.postMessage(ymlContent, null);
    }
};

Another possible way is to open dashbuilder client bundle and import an YAML file.

6. Dashbuilder YAML Guide

This is a guide for creating dashboards and visualizations with YAML. You can run all examples with Dashbuilder YML Online Editor.

6.1. Pages

A dashbuilder YML file should contain at least one page, hence this is the smallest YML that you can create (it renders a white page):

pages:
    - name: Hello

A page can contain rows, columns and finally components. A page with a single row and column can have the rows and columns omitted. Here’s a page with a single component, which renders the text Hello:

pages:
    - components:
        - html: Hello

It is required to declare rows and columns for a more complex layout. Here’s a page with two text in separated columns:

pages:
    - rows:
        - columns:
            - span: '6'
              components:
                - html: Row 1 Column 1
            - span: '6'
              components:
                - html: Row 1 Column 2
        - columns:
            - span: '6'
              components:
                - html: Row 2 Column 1
            - span: '6'
              components:
                - html: Row 2 Column 2

The YML renders to:

Page Layout
Figure 10. Page Layout

The page, rows, columns and components can have properties, including some CSS properties, such as width/height, background color, color and more.

pages:
    - rows:
        - properties:
            background-color: darkgray
          columns:
            - span: '6'
              properties:
                color: white
              components:
                - html: Row 1 Column 1
            - span: '6'
              properties:
                color: lightblue
              components:
                - html: Row 1 Column 2

A column can also have rows with components, this is useful for more complex layouts:

pages:
    - rows:
        - columns:
            - span: 2
              rows:
                - columns:
                    - components:
                        - html: R1CL1R1
                - columns:
                    - components:
                        - html: R1CL1R2
            - span: 2
              rows:
                - columns:
                    - components:
                        - html: R2CL1R1
                - columns:
                    - components:
                        - html: R2CL1R2
            - span: 2
              components:
                - html: R2CL1R1
Page Complex Layout
Figure 11. Page Complex Layout

6.2. Datasets

There’s a section for datasets where you declare your source of data. Dashbuilder supports multiple datasets types, but in this document we only cover JSON datasets, which does not require a backend. JSON datasets can have as a source any JSON array with a reachable URL, so the simplest dataset declaration requires the uuid and the url.

datasets:
- uuid: mydataset
  url: /datasets/population.json
pages:
- name: DataSet sample

It is possible to declare inline JSON for testing and prototyping purposes:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
pages:
- name: DataSet sample

With a pure JSON array dashbuilder will try to find the column type and give it a generic ID (Column X). You can override dashbuilder default settings using columns:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  columns:
    - id: Name
      type: LABEL
    - id: Age
      type: NUMBER
pages:
- name: DataSet sample

Most of the cases the JSON format is not an array. For these cases it is possible to use the powerful transformation language JSONAta to transform a dataset using the expression attribute. In the following example the array of objects is transformed into a JSON array:

datasets:
- uuid: mydataset
  expression: $.participants.[name, age]
  content: >-
            {
              "participants": [
                {"name": "William", "age": 33},
                {"name": "Luanda", "age": 32},
                {"name": "Anton", "age": 6}
              ]
            }
pages:
- name: DataSet sample

It is possible to use caching for non real time datasets. The cache expiration can be configured using refreshTime, otherwise the case is only invalidated when the YML runs again. Here’s a example of a dataset cached for 10seconds:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  cacheEnabled: 'true'
  refreshTime: '30second'
pages:
- name: DataSet sample

6.3. Datasets lookup

To display a dataset dashbuilder uses the concept of lookup. Imagine the dataset as a pie and lookups as a piece of the pie. With lookup it is possible to select which part of a dataset will be displayed. The lookup is part of a special component called displayer, which is covered later on this guide. For now, consider only the table displayer. The simplest use of a lookup is by simply providing the dataset uuid:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  columns:
    - id: Name
      type: LABEL
    - id: Age
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: mydataset
Basic Lookup
Figure 12. Basic Lookup

With the lookup it is possible to define the number of rows and the row offset of a dataset:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  columns:
    - id: Name
      type: LABEL
    - id: Age
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: mydataset
            rowCount: 1
            rowOffset: 2

The field order can be used to order the dataset based on a column. It is required to provide the column id and the sort order (ASCENDING or DESCENDING):

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  columns:
    - id: Name
      type: LABEL
    - id: Age
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: mydataset
            sort:
                - column: Age
                  sortOrder: ASCENDING
Lookup with order
Figure 13. Dataset Lookup with order

A powerful dataset lookup feature is filtering. To use this capability it is necessary to provide the column, the function and the args for the filter. The supported functions are (in parenthesis is the number of required parameters):

  • IS_NULL(0)

  • NOT_NULL(0)

  • EQUALS_TO(1)

  • NOT_EQUALS_TO(1)

  • LIKE_TO(2)

  • GREATER_THAN(1)

  • GREATER_OR_EQUALS_TO(1)

  • LOWER_THAN(1)

  • LOWER_OR_EQUALS_TO(1)

  • BETWEEN(2)

  • TIME_FRAME(1)

  • IN(1)

  • NOT_IN(1)

The filters TIME_FRAME and IN are applied only for DATE columns and LIKE_TO is only for TEXT or LABEL columns.

Here’s a GREATER_TO sample:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  columns:
    - id: Name
      type: LABEL
    - id: Age
      type: Number
pages:
- components:
    - settings:
        type: TABLE
        dataSetLookup:
            uuid: mydataset
            filter:
                - column: Age
                  function: GREATER_THAN
                  args:
                    - 10
Lookup with filter
Figure 14. Dataset Lookup with filter

Filters can be combined using the AND logical condition, but it is possible to use logical operators AND/OR and NOT to combine filters:

datasets:
- uuid: mydataset
  content: >-
            [
              ["William", 33],
              ["Luanda", 32],
              ["Anton", 6]
            ]
  columns:
    - id: Name
      type: LABEL
    - id: Age
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: mydataset
            filter:
                - function: OR
                  args:
                    - column: Name
                      function: LIKE_TO
                      args:
                        - "L%"
                    - column: Age
                      function: LOWER_THAN
                      args:
                        - 10
Lookup with combined filter
Figure 15. Dataset Lookup with combined filter

Dataset lookups also allow grouping. The group section is where the column group and the group functions are provided. The columnGroup is used to specify the grouping column and the “groupFunctions” is used to specify the group function for each selected column. In the example below the dataset lookup sums the number of products per section:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Name
      type: LABEL
    - id: Quantity
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: products
            group:
                - columnGroup:
                    source: Section
                  groupFunctions:
                    - source: Section
                    - source: Quantity
                      function: SUM
                      column: Total Products
Lookup with group
Figure 16. Dataset Lookup with group

The supported group functions are SUM, MAX, MIN and AVERAGE for numbers. For label columns the supported functions are DISTINCT and COUNT. By default it uses the column name itself, it is also possible to give another name to the grouped column. If a column is not specific in columnGroup, but used with other columns in columnFunctions, then the error Error during dataset lookup: No aggregation function specified for the column is displayed.

However, it is possible to omit the column group section and use no function for columns under columnGroup, this way the columns will just be passed to the displayer

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Name
      type: LABEL
    - id: Quantity
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: products
            group:
                - groupFunctions:
                    - source: Name
                    - source: Quantity

6.4. Displayers

Displayers are visual components that can show data. Dashbuilder supports by default all the popular charts types, tables, metrics with customized structure and style, data selectors to filter the whole visualization and finally external displayers, which are custom applications used to display data.

Dashbuilder consider as displayer every component with a settings, so when the settings is declared then the type must be declared as well:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Name
      type: LABEL
    - id: Quantity
      type: Number
pages:
- components:
    - settings:
        dataSetLookup:
            uuid: products

User data filtering

All displayers can filter itself and filter others using filter capabilities. This is done using the “filter” attribute, the filter must be enabled and components that will be filtered must have notification on. Components can filter itself, here’s a table filtering itself:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
pages:
- components:
    - settings:
        filter:
            enabled: 'true'
            selfapply: 'true'
        dataSetLookup:
            uuid: products
Displayer with self filtering
Figure 17. Displayer with self filtering

To filter other components notification must be true and other components receiving the filter should have listening as true. Here’s a table filtering each other:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
pages:
- components:
    - settings:
        filter:
            enabled: 'true'
            notification: 'true'
        dataSetLookup:
            uuid: products
    - settings:
        filter:
            enabled: 'true'
            listening: 'true'
        dataSetLookup:
            uuid: products
Displayer with filter notification
Figure 18. Displayer with filter notification

Refreshing data

It is possible to constantly refresh a Displayer with data. In this case just declare a refresh with interval and the dataset will be retrieved each X seconds.

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
pages:
- components:
    - settings:
        refresh:
            interval: '30'
        dataSetLookup:
            uuid: products
Bear in mind that smaller refresh intervals in multiple Displayers will impact the visualization performance.

Columns formatting

Displayers individually support dataset columns formatting. The field “columns” accept an array of columns where the id is provided, with it it is possible to change the column name, apply a number pattern and use Javascript to transform the column value. In the following example the column 0 is transformed to be upper case and the number column is formatted to use no decimal places

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
pages:
- components:
    - settings:
        columns:
            - id: Column 0
              name: Section
              expression: value.toUpperCase()
            - id: Column 1
              name: Product
            - id: Column 2
              name: Quantity
              pattern: '#'
        dataSetLookup:
            uuid: products
Displayer with conlumns configuration
Figure 19. Displayer with columns configurations

Table Settings

When using the table displayer there are specific settings that can be used:

  • pageSize: the quantity of items displayed per page;

  • show_column_picker: When false the column picker is not displayed

Here’s an example of these two properties:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
pages:
- components:
    - settings:
        table:
            pageSize: '3'
            show_column_picker: 'false'
        dataSetLookup:
            uuid: products

The table sort can be configured using the sort object. Sort support the following settings:

  • enabled: if true users can sort the table by clicking on the column name;

  • columnId: The id of the column used to sort the table;

  • order: The order that can be ASCENDING or DESCENDING.

Here’s a table sorted by Column 2 in descending order.

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5],
              ["Computers", "Printer", 7],
              ["Computers", "Laptop", 3],
              ["Electronics", "Camera", 10],
              ["Electronics", "Headphones", 5]
            ]
pages:
- components:
    - settings:
        table:
            show_column_picker: 'false'
            sort:
                enabled: 'false'
                columnId: Column 2
                order: DESCENDING
        dataSetLookup:
            uuid: products
Table with order configuration
Figure 20. Table with order configuration

6.5. Using Charts

In dashbuilder the following charts are supported:

  • BARCHART: with subtypes COLUMN (default) and BAR. It is also possible to use STACKED (COLUMN_STACKED and BAR_STACKED)

  • LINECHART: with subtypes LINE (default) and SMOOTH

  • AREACHART: with subtypes AREA (default) and AREA_STACKED

  • PIECHART: with subtypes PIE (default) and DONUT

All these types support one column for categories (X axis) and at least one column for Y axis. If this is respected, then simply changing the type will change the visualization. In another words, the following YAML will renders a BARCHART:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5, 3],
              ["Computers", "Printer", 7, 4],
              ["Computers", "Laptop", 3, 2],
              ["Electronics", "Camera", 10, 7],
              ["Electronics", "Headphones", 5, 9]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Product
      type: LABEL
    - id: Quantity
      type: NUMBER
pages:
- components:
    - settings:
        type: BARCHART
        dataSetLookup:
            uuid: products
            group:
                - columnGroup:
                    source: Product
                  groupFunctions:
                    - source: Product
                    - source: Quantity
                      function: SUM
                    - source: Column 3
                      function: SUM
Bar Chart
Figure 21. Bar Chart

Then simply adding the subtype property with value COLUMN_STACKED it renders the following chart:

Stacked Bar Chart
Figure 22. Stacked Bar Chart

A line chart is simply a matter of changing the type to LINE:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Scanner", 5, 3],
              ["Computers", "Printer", 7, 4],
              ["Computers", "Laptop", 3, 2],
              ["Electronics", "Camera", 10, 7],
              ["Electronics", "Headphones", 5, 9]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Product
      type: LABEL
    - id: Quantity
      type: NUMBER
pages:
- components:
    - settings:
        type: LINECHART
        subtype: SMOOTH
        dataSetLookup:
            uuid: products
            group:
                - columnGroup:
                    source: Product
                  groupFunctions:
                    - source: Product
                    - source: Quantity
                      function: SUM
                    - source: Column 3
                      function: SUM

The same configuration could be used with AREACHART, and PIECHART (only the first column is used for the pie values).

Chart Axis configuration

It is possible to configure charts X/Y axis using the axis configuration.

Under the axis object there are two properties, x and y. Here are the supported attributes:

  • labels_show: when true the labels will be displayed

  • title: A title for the axis

  • labels_angle: The labels angle. Only works for the X axis.

Chart General Settings

All charts and most of the displayers support chart general settings. These settings are part of the chart attribute:

  • width: A number with the chart fixed width. It is not a CSS property;

  • height: A number with the chart fixed height. It is not a CSS property;

  • resizable: A boolean property that indicates that the chart should auto resize according to the screen resolution. This is the only chart property that is supported by the Table displayer;

  • bgColor: The chart background color

  • margin: An object that configures the chart margin, it has the attributes left, top, bottom and right. It is not a CSS property;

  • legend: An object that configures the chart legend. It has the attributes show, when true the legend is displayed, and position, possible values are: IN, RIGHT and BOTTOM.

  • grid: An object to show/hide the grid, it has the boolean attributes x and y;

  • zoom: When true will enable zoom on charts;

  • general: In attribute general it is possible to set a title. The title will not be displayed, for this it is required to set the attribute show as true;

Here’s an example using chart properties:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Printer", 7, 4],
              ["Computers", "Laptop", 3, 2],
              ["Electronics", "Camera", 10, 7],
              ["Electronics", "Headphones", 5, 9]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Product
      type: LABEL
    - id: Quantity1
      type: NUMBER
    - id: Quantity2
      type: NUMBER
pages:
- components:
    - settings:
        type: BARCHART
        chart:
            bgColor: DEDEDE
            width: '800'
            height: '400'
            zoom: 'true'
            margin:
                right: '50'
                top: '50'
            legend:
                show: 'true'
                position: 'bottom'
            grid:
                x: 'false'
                y: 'false'
        dataSetLookup:
            uuid: products
            group:
            - columnGroup:
                source: Product
              groupFunctions:
                - source: Product
                - source: Quantity1
                  function: SUM
                - source: Quantity2
                  function: SUM
Chart Configuration
Figure 23. Bar Chart Configuration

6.6. Selectors

Selector is a special displayer type used to filter the visualization. It has 3 subtytpes:

  • SELECTOR_LABELS: Shows the values in selectable labels;

  • SELECTOR_DROPDOWN: Shows the values in a dropdown;

  • SELECTOR_SLIDER: Shows a slider to select values. Show be used only for number and date columns. The selector object has the property multiple, when true multiple values can be selected. Bear in mind that this only works with labels selectors.

Filter must be enabled, otherwise selectors will not work.

Here’s an example of labels selector:

datasets:
- uuid: products
  content: >-
            [
              ["Computers", "Printer", 7, 4],
              ["Computers", "Laptop", 3, 2],
              ["Electronics", "Camera", 10, 7],
              ["Electronics", "Headphones", 5, 9]
            ]
  columns:
    - id: Section
      type: LABEL
    - id: Product
      type: LABEL
    - id: Quantity1
      type: NUMBER
    - id: Quantity2
      type: NUMBER
pages:
- components:
    - settings:
        type: BARCHART
        filter:
            enabled: 'true'
            listening: 'true'
        dataSetLookup:
            uuid: products
            group:
            - columnGroup:
                source: Product
              groupFunctions:
                - source: Product
                - source: Quantity1
                  function: SUM
                - source: Quantity2
                  function: SUM
    - settings:
        type: SELECTOR
        subtype: SELECTOR_LABELS
        selector:
            multiple: 'true'
            inputs_show: 'true'
        filter:
            enabled: 'true'
            notification: 'true'
        dataSetLookup:
            uuid: products
            group:
            - columnGroup:
                source: Section
              groupFunctions:
                - source: Section
Labels Selector
Figure 24. Labels Selector

6.7. Metrics

The metric component is a piece of HTML capable of showing a single value. It is possible to customize the HTML, but by default the value is displayed in a card:

datasets:
- uuid: products
  content: >-
            [
              ["Printer", 7],
              ["Laptop", 3],
              ["Camera", 10],
              ["Headphones", 5]
            ]
  columns:
    - id: Product
      type: LABEL
    - id: Quantity
      type: NUMBER
pages:
- components:
    - settings:
        type: METRIC
        chart:
            height: '100'
            width: '150'
        general:
            title: Total Products
            visible: 'true'
        dataSetLookup:
            uuid: products
            group:
            - groupFunctions:
                - source: Quantity
                  function: SUM
Default Metrics
Figure 25. Default Metrics

The HTML can be customized using the object html with the field html and javascript for javascript. Inside the HTML the variable ${value} contains the value resulted from the dataset lookup and to refer to elements in javascript give the element the id ${this} and refer to it in the javascript code. Be responsible for the javascript code used in the YAML! Here’s a basic example:

datasets:
- uuid: products
  content: >-
            [
              ["Printer", 7],
              ["Laptop", 3],
              ["Camera", 10],
              ["Headphones", 5]
            ]
  columns:
    - id: Product
      type: LABEL
    - id: Quantity
      type: NUMBER
pages:
- components:
    - settings:
        type: METRIC
        html:
            html: <h2><strong>&#10026; Total Products:</strong>&nbsp;<span id="${this}">${value}</span></h2>
            javascript: >-
                            ${this}.onmouseover = function() {
                                ${this}.style.color = "red";
                            };
                            ${this}.onmouseout = function() {
                                ${this}.style.color = "black";
                            };
        dataSetLookup:
            uuid: products
            group:
            - groupFunctions:
                - source: Quantity
                  function: SUM
Custom Metrics
Figure 26. Custom Metrics

Other variables from the displayer configuration can be used in the code (using ${variable name} template): title, width, height, marginTop, marginBottom, marginRight, marginLeft and bgColor.

6.8. Meter Chart

A special chart is the meter chart. It compares values and shows the percent of the total. To configure the values boundaries use the property meter, it supports the following attributes:

  • start: a value to start the meter

  • end: the max value value for the meter

  • critical: paints the meter as red if the value is bigger than this parameter

  • warning: paints the meter as orange if the value is bigger than this parameter

For the dataset it accepts two columns: the label and the value. Here’s an example:

datasets:
- uuid: memory_usage
  content: >-
            [
              ["Server 1", 2512],
              ["Server 2", 1900],
              ["Server 3", 3200],
              ["Server 4", 1200]
            ]
  columns:
    - id: Server
      type: LABEL
    - id: Usage
      type: NUMBER
pages:
- components:
    - properties:
        font-size: xx-large
        text-align: center
      settings:
        type: METERCHART
        general:
            title: "Memory Usage"
            visible: 'true'
        chart:
            legend:
                show: 'true'
                position: bottom
        meter:
            end: '4120'
            critical: '3000'
            warning: '2000'
        dataSetLookup:
            uuid: memory_usage
            group:
            - columnGroup:
                source: Server
              groupFunctions:
                - source: Server
                - source: Usage
                  function: SUM
Meter
Figure 27. Meter

6.9. Map

Dashbuilder provides a Map component to show geographic data. It is country based, so to use it one must provide the country identification, which could be the country name, lat, long or the country code, and provide the value for that country. It has two types: * MAP_MARKERS: which marks the country with bubbles according to the value * MAP_REGIONS: which paints the map according to the value. The only specific configuration for map is color_scheme, which could have the values red, green or blue and it is an attribute of object map. Here’s an example:

datasets:
- uuid: countries
  content: >-
            [
              ["Brazil", 2512],
              ["USA", 1900],
              ["Italy", 3200],
              ["Russia", 1200],
              ["China", 100],
              ["Australia", 1000],
            ]
  columns:
    - id: Server
      type: LABEL
    - id: Usage
      type: NUMBER
pages:
- components:
    - settings:
        type: MAP
        map:
            color_scheme: blue
        dataSetLookup:
            uuid: countries
            group:
            - columnGroup:
                source: Server
              groupFunctions:
                - source: Server
                - source: Usage
    - settings:
        type: MAP
        subtype: MAP_MARKERS
        map:
          color_scheme: red
        dataSetLookup:
            uuid: countries
            group:
            - columnGroup:
                source: Server
              groupFunctions:
                - source: Server
                - source: Usage
Map
Figure 28. Map

6.10. External Components

Dashbuilder also support components built externally. Components have an ID and you can either add its assets to Dashbuilder server under context /dashbuilder/component/{componentId}/ or use a property to point to a remote component:

datasets:
  - uuid: products
    content: >-
      [
        ["Computers", "Scanner", 5, 3],
        ["Computers", "Printer", 7, 4],
        ["Computers", "Laptop", 3, 2],
        ["Electronics", "Camera", 10, 7],
        ["Electronics", "Headphones", 5, 9]
      ]
    columns:
      - id: Section
        type: LABEL
      - id: Product
        type: LABEL
      - id: Quantity
        type: NUMBER
      - id: Quantity2
        type: NUMBER
pages:
  - components:
      - settings:
          component: simplest_component
          simplest_component:
            name: "John"
            age: "33"
          external:
            baseUrl: https://jesuino.github.io/components/
            width: 100%
            height: 600px
          lookup:
            uuid: products

Some components are provided for use with Dashbuilder. Check the documentation for each component to understand how to use it:

  • table: The table external component has a different look and feel and can be used with any dataset.

datasets:
  - uuid: products
    content: >-
      [
        ["Computers", "Scanner", 5, 3],
        ["Computers", "Printer", 7, 4],
        ["Computers", "Laptop", 3, 2],
        ["Electronics", "Camera", 10, 7],
        ["Electronics", "Headphones", 5, 9]
      ]
pages:
  - components:
      - settings:
          component: table
          external:
            width: 100%
          lookup:
            uuid: products

  • echarts: ECharts chart. In this component the dataset is transformed to a echarts dataset and the option parameter can be used to provide a JSON object to configure the echart. We also parse the options in YML format to JSON, so some configuration could be done using pure YML. Here’s a sample echart usage:

datasets:
  - uuid: products
    content: >-
      [
        ["Computers", "Scanner", 5, 3],
        ["Computers", "Printer", 7, 4],
        ["Computers", "Laptop", 3, 2],
        ["Electronics", "Camera", 10, 7],
        ["Electronics", "Headphones", 5, 9]
      ]
    columns:
      - id: Section
        type: LABEL
      - id: Product
        type: LABEL
      - id: Quantity
        type: NUMBER
      - id: Quantity2
        type: NUMBER
pages:
- components:
    - settings:
        component: echarts
        echarts:
            option: >-
                    {
                        "toolbox": {
                            "feature": {
                                "dataZoom": {},
                                "magicType": {
                                    "type": ["line", "bar", "stack"]
                                },
                                "restore": {}
                            }
                        },
                        "series": [

                            {
                                "type": "bar",
                                "markLine": {
                                    "data": [
                                        { "type": "average" }

                                    ]
                                }
                            },
                            {
                                "type": "bar",
                                "markLine": {
                                    "data": [
                                        { "type": "average" }
                                    ]
                                }
                            }
                        ]

                    }
            title:
                text: Products
        external:
          width: 100%
        lookup:
          uuid: products
          group:
            - columnGroup:
                source: Product
              groupFunctions:
                - source: Product
                - source: Quantity
                - source: Quantity2

  • svg-heatmap: The SVG heatmap allow users to draw heat over any SVG. The provided dataset must have two columns: SVG name or id and a value for the heat. The component can have the parameters size and blur to control the heat appearance:

datasets:
  - uuid: svg-data
    content: >-
      [
        ["svg_1", 1],
        ["svg_2", 2],
        ["svg_3", 3],
        ["svg_4", 4],
        ["svg_5", 5],
        ["svg_6", 6]
      ]
pages:
  - components:
      - settings:
          component: svg-heatmap
          external:
            width: 100%
          svg-heatmap:
            size: "3"
            blur: "0.9"
            svg: >-
              <svg xmlns="http://www.w3.org/2000/svg">
                <path id="svg_1" d="m23,23l82,0l0,51l-82,0l0,-51z" stroke-width="0" fill="#999999"/>
                <path id="svg_2" d="m133,23l82,0l0,51l-82,0l0,-51z" stroke-width="0" fill="#999999"/>
                <path id="svg_3" d="m240,23l82,0l0,51l-82,0l0,-51z" stroke-width="0" fill="#999999"/>
                <path id="svg_4" d="m350,23l82,0l0,51l-82,0l0,-51z" stroke-width="0" fill="#999999"/>
                <path id="svg_5" d="m461,24l82,0l0,51l-82,0l0,-51z" stroke-width="0" fill="#999999"/>
                <path id="svg_6" d="m566,26l82,0l0,51l-82,0l0,-51z" stroke-width="0" fill="#999999"/>
              </svg>
          datasetlookup:
            uuid: svg-data

  • timeseries: Timeseries allow users to display timeseries information and it is based on echarts, which means that it is possible to pass an option parameter as well. The accepted dataset must have a column for the series, the timestamp and value.

datasets:
  - uuid: timeseries
    url: https://raw.githubusercontent.com/jesuino/dashbuilder-data/master/samples/timeseries.json
pages:
  - components:
      - settings:
          component: timeseries
          external:
            width: 100%
          datasetlookup:
            uuid: timeseries

  • uniforms: Uniforms is a component that does not use a dataset, but allow users to render forms to post data to an URL. It accepts the parameters uniforms.url, the form URL and the JSON schema for the form generation, uniforms.schema.

pages:
  - components:
      - type: EXTERNAL
        properties:
          height: 500px
          componentId: uniforms
          uniforms.url: http://acme.com
          uniforms.schema: >-
            {
               "title":"",
               "type":"object",
               "properties":{
                  "workflowdata": {
                      "title": "Sample Form",
                      "default": { "language": "English", "name": "John" },
                      "type": "object",
                      "properties": {
                          "name":{
                             "type":"string"
                          },
                          "language":{
                             "type":"string",
                             "allowedValues": ["English", "Spanish"]
                          }
                      },
                      "required":[
                         "name", "language"
                      ]
                  }

               }
            }

6.11. Navigation

It is possible to have multiple pages in a single visualization. The pages can be organized in a menu using navigation. When you don’t declare a navigation then a standard menu navigation is used:

pages:
    - name: Cats
      components:
        - html: <h1> Cats </h1>
    - name: Dogs
      components:
        - html: <h1>Dogs</h1>
    - name: Tablets
      components:
        - html: <h1>Tablets</h1>
    - name: Laptops
      components:
        - html: <h1>Laptops</h1>

The section navTree is responsible for declaring the navigation tree and the navigation groups for the pages is possible to organize the menus in navigation groups. Here’s an example:

pages:
    - name: Cats
      components:
        - html: <h1> Cats </h1>
    - name: Dogs
      components:
        - html: <h1>Dogs</h1>
    - name: Tablets
      components:
        - html: <h1>Tablets</h1>
    - name: Laptops
      components:
        - html: <h1>Laptops</h1>
navTree:
  root_items:
  - type: GROUP
    name: Animals
    children:
    - page: Cats
    - page: Dogs
  - type: GROUP
    name: Electronics
    children:
    - page: Tablets
    - page: Laptops
Menu Navigation
Figure 29. Menu Navigation
To show a default page just name it as index and it will be displayed by default, otherwise the default dashbuilder page will be displayed.

6.12. Navigation Components

It is possible to embed pages using navigation groups. To do so dashbuilder provides navigation components.

  • TILES: Displays the navigation group pages in tiles;

  • CAROUSEL: Displays the pages in a carousel;

  • TREE: Displays a tree with the pages. It requires a target DIV;

  • MENU: Displays a menu with the pages. It requires a target DIV;

  • TABS: Displays tabs with the pages. It requires a target DIV;

  • DIV: A div that shows the content for TREE, MENU and TABS components.

A property called navGroupId should be set to point to the same groupId declared in navigation. For components that require a div, then a DIV component should be placed on the page and the div ID should be referenced using the property divId. Here’s an example of navigation components:

pages:
    - name: Cats
      components:
        - html: <h1> Cats </h1>
    - name: Dogs
      components:
        - html: <h1>Dogs</h1>
    - name: index
      rows:
        - columns:
          - components:
            - type: TILES  # try CAROUSEL
              properties:
                navGroupId: animals_group
        - columns:
          - components:
            - type: TABS  # try MENU or TREE
              properties:
                navGroupId: animals_group
                targetDivId: animals_div
            - type: DIV
              properties:
                divId: animals_div
navTree:
  root_items:
  - id: animals_group
    type: GROUP
    name: Animals
    children:
    - page: Cats
    - page: Dogs
Navigation Components
Figure 30. Navigation Components

6.13. Properties

The goal of properties is to make it easier to reuse YAML definitions and let users only customize certain parts of the document. Properties can be declared with a value and later references using ${PROPERTY NAME}.

Be careful when using ${} to avoid conflict with Metric templates.

Properties are meant to be used only with field values. Here’s an example:

properties:
    My Property: <h1>Hello Properties</h1>
pages:
    - name: Cats
      components:
        - html: ${My Property}

When running on Dashbuilder you can also override the properties using query parameters. In the example above My Property could be changed using http://my.dashbuilder?My Property=New Property value.

6.14. Global

Global section was added in 0.26.0 version and it allow users to change the dashboard default mode to dark and declare a global settings for all displayers on the page:

global:
  mode: dark
  settings:
    general:
      title: Common Title
datasets:
  - uuid: test
    content: >-
      [
          ["A", 1],
          ["B", 2]
      ]
pages:
  - rows:
      - columns:
          - span: 6
            components:
              - settings:
                  type: BARCHART
                  lookup:
                    uuid: test
          - span: 6
            components:
              - settings:
                  type: LINECHART
                  lookup:
                    uuid: test
Dark Mode
Figure 31. Dark Mode