Embed API

Our Embed API can be used to display interactive line charts with your measurement data on any web page. See for example the chart below, which displays real-time data from a Blockbax project. Visit our demo page for more examples of embedded line charts.

To embed a line chart on a web page, follow the instructions below. If you want to embed line charts in a Mendix project, you can use our Mendix widget instead. It will take care of all steps below, and allows you to configure the parameters in Studio Pro. Visit the Mendix Marketplace, and contact us for more information.

Using the Embed API

Step 1: Adding a container

Add a container element to the page where the chart should go. Make sure the element is given a height, for example by setting it through the style attribute.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<!-- Option 1: declare parameters on the container element -->
<div
    data-type="blockbax-chart"
    data-project-id="4cbad375-7eb9-4176-bf4e-ea0783006341"
    data-metric-ids="bafba774-ffae-4d79-888b-3a7f48bfa0f0"
    data-subject-ids="892e6c76-6fe1-4e16-9aeb-052deb1d09e4"
    data-period="1w"
    data-background-color="#ffffff"
    style="height: 400px"
></div>

<!-- Option 2: provide parameters dynamically using JavaScript -->
<div id="my-blockbax-chart" style="height: 400px"></div>

Step 2: Loading the Embed API

Add the Embed API script to the page. It is recommended to put it in the head section.

1

<script src="https://embed.blockbax.com/api.js" defer></script>

Step 3: Rendering the chart

Render the chart using the Embed API. Make sure to provide your own personal key, and replace project, subject and metric IDs with your own. They can be found in the URL of the web app.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


<script>
    window.addEventListener("DOMContentLoaded", () => {
        // Replace the key below with your own personal key.
        const blockbaxEmbedAPI = new BlockbaxEmbedAPI({
            personalKey: "fSroNkmbzZBQRT6T44F6b0tI7snOByts"
        });

        // When using option 1, call initialize to render all charts on the page:
        blockbaxEmbedAPI.initialize();

        // When using option 2, call renderChart with the container and parameters:
        const container = document.querySelector("#my-blockbax-chart");

        const params = {
            projectId: "4cbad375-7eb9-4176-bf4e-ea0783006341",
            series: [
                {
                    metricId: "bafba774-ffae-4d79-888b-3a7f48bfa0f0",
                    subjectIds: ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4"]
                }
            ],
            fromDate: new Date(2023, 0, 1),
            toDate: new Date(2023, 1, 1),
            liveUpdate: true,
            backgroundColor: "#ffffff"
        };

        blockbaxEmbedAPI.renderChart(container, params);
    });
</script>

Configuring charts

The Embed API enables you to customize your charts in various ways. Below, you will find an explanation of the parameters you can use to configure your charts. The examples demonstrate how these parameters are passed in JavaScript, but they can be set using HTML attributes as well. To see how parameters can be set as HTML attributes, refer to the examples on the demo page.

Configuring series

The series can be configured in two ways: you can either pass a list of metric IDs and subject IDs, or use the series parameter, which allows for a more advanced configuration.

Configuring series using the metricIds and subjectIds params:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// Option 1: Show one metric for multiple subjects.
const params = {
    // ...
    metricIds: ["bafba774-ffae-4d79-888b-3a7f48bfa0f0"],
    subjectIds: ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4", "bd072731-d406-4f69-8d75-33bd84343ebf"]
};

// Option 2: Show multiple metrics for one subject.
const params = {
    // ...
    metricIds: ["bafba774-ffae-4d79-888b-3a7f48bfa0f0", "624f1738-a857-45eb-b68f-ccc5ab77680c"],
    subjectIds: ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4"]
};

// Option 3: Show metric 1 for subject 1, metric 2 for subject 2, etc.
// This option requires the number of metrics and subjects to match.
const params = {
    // ...
    metricIds: ["bafba774-ffae-4d79-888b-3a7f48bfa0f0", "624f1738-a857-45eb-b68f-ccc5ab77680c"],
    subjectIds: ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4", "bd072731-d406-4f69-8d75-33bd84343ebf"]
};

Configuring series using the series param allows for more advanced configurations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


const params = {
    // ...
    series: [
        {
            metricId: "bafba774-ffae-4d79-888b-3a7f48bfa0f0",
            subjectIds: ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4", "bd072731-d406-4f69-8d75-33bd84343ebf"],
            aggregationFunction: "min"
        },
        {
            metricId: "624f1738-a857-45eb-b68f-ccc5ab77680c",
            subjectIds: ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4", "bd072731-d406-4f69-8d75-33bd84343ebf"],
            aggregationFunction: "max"
        }
    ];
}

Configuring the period

The time period can be configured in two ways: you can either specify a relative period, or provide specific “from” and “to” dates. Note that when passing a relative period, liveUpdate defaults to true, whereas when passing an absolute period, it defaults to false. You can change this behavior by explicitly passing a value for liveUpdate.

Passing a relative period of 1 week using the period param:

1
2
3
4


const params = {
    // ...
    period: "1w"
};

Passing an absolute period using the fromDate and toDate params:

1
2
3
4
5


const params = {
    // ...
    fromDate: new Date(2024, 0, 1),
    toDate: new Date(2024, 0, 7)
};

Chart parameters

Below, you will find an explanation of the parameters you can use to configure your charts.

Parameter	Value	Example
projectId	Your Blockbax project ID	`"4cbad375-7eb9-4176-bf4e-ea0783006341"`
metricIds	One or more metric IDs, see examples above	`["bafba774-ffae-4d79-888b-3a7f48bfa0f0", "624f1738-a857-45eb-b68f-ccc5ab77680c"]`
subjectIds	One or more subject IDs, see examples above	`["892e6c76-6fe1-4e16-9aeb-052deb1d09e4", "bd072731-d406-4f69-8d75-33bd84343ebf"]`
series	A list of series, having a metric ID, one or more subject IDs, and an optional aggregation function	`[ { "metricId": "bafba774-ffae-4d79-888b-3a7f48bfa0f0", "subjectIds": ["892e6c76-6fe1-4e16-9aeb-052deb1d09e4"], aggregationFunction: "avg" } ]`
period	A relative period, composed of a number and a time unit	`3h`, `2d`, `1w`, `1mo`, `1y`
fromDate	A date that is used as the start of the time period	`Mon Jan 01 2024 00:00:00 GMT+0100`
toDate	A date that is used as the end of the time period	`Thu Feb 01 2024 00:00:00 GMT+0100`
liveUpdate	Whether the time period and data should update periodically	`true`, `false`
aggregationFunction	An optional aggregation function to apply to measurement values	`avg`, `min`, `max`, `sum`, `count`
tooltipStyle	Whether the tooltip should show time and series captions or only values	`normal`, `compact`
leftAxisWidth	The width of the left axis; a width ⩽ 20 will hide the ticks and labels	`10`
rightAxisWidth	The width of the right axis; a width ⩽ 20 will hide the ticks and labels	`10`
backgroundColor	A hex color that is used as the background color of the chart	`#fafafa`
personalKey	Your Blockbax personal key	`fSroNkmbzZBQRT6T44F6b0tI7snOByts`

Documentation