Custom JavaScript Visuals
When no built-in chart fits, a JS visual lets you draw it yourself from the visual's data, as HTML or as an ECharts chart.
What your code receives
Your code is the body of a function. It gets one argument, data, with the visual's query result:
| Field | What it holds |
|---|---|
data.data | The rows, each an array of values in column order. |
data.columnDetails | One entry per column, with its name and column_type. |
Returning HTML
Return a string of HTML. It replaces the visual's body. For example:
return '<div class="row">' +
data.data.map((row) => '<div class="col">' + row[0] + '</div>').join('') +
'</div>';
Returning an ECharts chart
Return an ECharts option object instead of a string, and the visual draws it as an interactive chart, with tooltips and legend toggling working as ECharts provides them. The object must have series, dataset or graphic (or a timeline's baseOption and options). For example, a bar for each measure column, with the first column along the axis:
return {
tooltip: { trigger: 'item' },
legend: { top: 0 },
xAxis: { type: 'category', data: data.data.map((row) => String(row[0])) },
yAxis: { type: 'value' },
series: data.columnDetails.slice(1).map((column, i) => ({
name: column.name,
type: 'bar',
data: data.data.map((row) => row[i + 1])
}))
};
- No functions in the object. A formatter written as a function can't be returned and shows an error. Use ECharts' text templates instead, such as
formatter: '{b}: {c}'. - The chart resizes with its tile. It uses the default chart colours unless the option sets its own
color. - Clicking it does not drill down or filter other visuals, as built-in charts do. Number formats set in the visual's configuration don't apply; format numbers in the option.
- An object that isn't an ECharts option shows an error in the visual, as does an option ECharts can't draw.
Click handlers
When your code returns HTML, an onclick="…" you write into it works when someone clicks the element, with
this as the element and event as the click, and return false cancelling it as usual.
A common use is a row that expands or collapses the rows under it.
onclick=, it is shown but never run, so data can't add behaviour to your visual.
Limits
- The code runs in the background, away from the page, and must finish within
5 seconds (an administrator can change this with
JS_CUSTOM_VISUAL_EXECUTION_TIMEOUT). - It cannot use
document,window,localStorage,fetch,XMLHttpRequest, timers,evalorFunction, even in a comment. Build the result as a string or an object instead.
