Creating a Custom Panel in s-Dashboard Using Chart_js

s-Dashboard lets you customize panels using Chart.js or Vega. We recommend trying to use Chart.js. In most cases, Chart.js will provide more functionality and will be easier to use. If you’re going to write a custom s-Dashboard panel we recommend Chart.js as a more straightforward approach than Vega. However, Chart.js is limited to a few chart types, while you can use Vega to draw just about anything. Panels that use Chart.js find all the numerical columns in the incoming stream and create a Chart.js* data specification for each one.

s-Dashboard provides a generic Chart.js panel that allows you to customize it completely by writing a Chart.js specification. See http://www.chartjs.org for more details on Chart.js. Many of the pre-built panels also use Chart.js, and you can consult these as examples.

Chart.js and Panel Preferences

Each panel has panel preferences tailored to that chart type. For example, the bar chart panel has a preference bar border width* that specifies the border width to use when drawing the bars.

These properties can be a single value, such as 2*, or a comma-separated list, like *2,3,2*. Single values apply to all the data columns, while a list is applied to each data column in turn. So if there are columns alpha, beta, gamma, and delta, and the bar border width is _2,3,2,2_ the bar corresponding to the beta column would have a border width of 3 while the other bars would have a border width of 2.

This feature is most useful for properties that specify a color. You almost always want different data columns shown in different colors. You can specify a list of colors explicitly, such as red,green,blue, or rgba(255,0,0,1.0),rgba(0,255,0,1.0),rgba(0,0,255,1.0). You may also access the palettes provided by Rickshaw https://github.com/shutterstock/rickshaw by entering a value like palette(colorwheel,1.0). colorwheel can be any of the Rickshaw palettes: classic9, colorwheel, cool, munin, spectrum14, spectrum2000, spectrum2001. 1.0 is the alpha value to apply to the colors. A list of colors long enough to match each of the incoming data columns will be generated.

Using the panel preferences and the list of incoming columns, a Chart.js panel will generate the data portion of the Chart.js spec. If you enable the advanced options in the panel preferences you’ll see that you can edit the options portion of the Chart.js spec as a JSON object. See the Chart.js documentation for all of the options that can be set this way.

Custom Chart.js Panel

The Chart.js Customizable panel gives you full control over the panel’s visualization. You specify the full Chart.js JSON spec by writing a JavaScript template. Use the template markers <%= … %>* to insert the value of a variable or expression and <% … %>* to insert JavaScript code.

The panel preferences include a View JSON button that you can use to see the result of evaluating the JavaScript template.

These variables are available:

  • allColumnsArray. A JavaScript array listing the names of all of the columns in the input
  • numberColumnsArray. A JavaScript array listing the names of all the numerical columns in the input
  • columns. The list of numerical columns. This is a string, the JSON representation of the array of names (i.e., <%= columns %> is the same as <%= JSON.stringify(numberColumnsArray) %>)
  • row. JSON representation of an array of the numerical values from the most recent row

These functions are available:

  • column(columnName). Returns the data for a column, given the column’s name.
  • hasColumn(columnName). Returns true if the input stream contains a column with the given name.
  • palette(paletteName). Selects the color palette, or resets it if it’s already the current palette.
  • paletteName may be one of “classic9”, “colorwheel”, “cool”, “munin”, “spectrum14”, “spectrum2000”, “spectrum2001”
  • color(alpha). Returns the next color from the color palette, with the given alpha value.

In addition, all of Underscore underscorejs.org is available

When you create a Chart.js Customizable panel, the preferences are filled in with a template that generates a bar chart of the current row, using the columns and row variables and the palette() and color() functions. This is a good starting point for a custom panel that visualizes a single row. In the Examples section of the Select Panel list there is a Chart.js custom panel that shows a bar chart over time. This demonstrates displaying multiple rows, using the column() function to insert the data from named columns into the Chart.js data specification.

Creating a Custom Panel with Chart.js

To create a custom panel:

  1. In s-Server or StreamLab, either create a View on existing data or confirm that a stream exists that you can use to display.
  2. Select this stream as input.
  3. Click Select Panel.
  4. Choose Customizable Panels > Chart.js Custom
  5. Click Panel Preferences.
  6. Copy the code block in ChartJS Specification to a text editor.
  7. Make changes, using the documentation at http://www.chartjs.org, http://underscorejs.org, and https://github.com/shutterstock/rickshaw.
  8. Paste changes back into the ChartJS Specification box.
  9. Click Update. The panel appears with your updates. s-Dashboard will display an error if your code doesn’t work. Repeat steps 4-7 until display works to your satisfaction.