New to Version 1.1

This version simply adds more relaxed checking on computating variable names. Previously, the underlying check was a bit too strict, not allowing space characaters or hyphen - characters. These are technically ok and are now allowed, though often not preferred.

Overview

The Data Table plugin provides a configurable tabular interface for rendering data. This plugin subscribes to, computes, and displays data from any number of other plugins in a table. A convenient layout syntax allows for specifying the values and style for each cell. Cells can be styled with options for italics, bold, background color, text color, cell width, cell height, font name, and font size. Cells can also update dynamically from incoming data using variables and expressions. In particular, the cell value / text can be made dynamic, as well as the cell background color and text color.

The ability to dynamically update the cell background and text colors allows the table to act as an alarm interface as well. For example, you may make the background color of a cell red when a value exceeds a specified threshold, as shown above. Many other attributes of the table can be configured, such as row/col headers, whether to show scrollbars, whether to display vertical/horizontal lines, or whether to autosize row heights to display multiline content.

Notably, the table updates at a specified sample period using values / computations from a VAR variable container. Here’s how the computations work in this plugin:

1. An “initializations” configurution section writes initial values to the VAR container
2. As subscription data arrives, it is optionally computed - as specified on a per subscriber basis - and stored into the VAR variable container
3. Then, each time the specified sample period for the Data Table expires, any specified (optional) “intermediate” computations are performed which further populate the VAR container.
4. Immdiately thereafter, any dynamic table values and styles are computed, updated, and displayed.

In other words, the table can be generally initialized with values and styles and then dynamically updated as a function of incoming data.

Example

Let’s see how the configuration makes defining a dynamic data table flexible and easy. Suppose our Data Table instance subscribes to a single publisher which publishes a voltage, and that we know the current is always twice the voltage. So our subscribesTo configuration may look like:

    "subscribesTo": ["Voltage Publisher"] // just the one publisher named: Voltage Publisher

Then, we can capture and store the published voltage value and timestamp, and compute a voltageExceedsLimit boolean using the computations configuration as shown below. Note that we put the voltageExceedsLimit in the intermediates computation section (not in the subscriptions) to ensure it occurs after the voltage variable has been stored. Also notice that the intermediates option is defined as an array so that we could, if helpful, perform multiple staged computations.

    "computations": {
        "initializations": {},
        "subscriptions": {
            "Voltage Publisher": {
                "timestamp": "@SUB{timestamp}",
                "voltage": "@SUB{value}"
            }
        },
        "intermediates": [
            {
                "voltageExceedsLimit": "Boolean:( @VAR{voltage} > 0.5 )"
            }
        ]
    }

With our variables computed, we can now shift our thinking to the table itself. In particular, under the table configuration options include the many features noted above. Let’s focus on our column headers for a moment, where we see the use of the {{{style}}} syntax. This syntax does not render in the header, but rather only serves to defined the style to apply to a given header.

    "columnHeaders": ["Measurement{{{bold=true,bgColor=gold,width=150}}}", "Value{{{bold=true,bgColor=gold,width=2000}}}"]

Also in the table section of configuration we find the layout which is a 2-dimensional array representing the main body of the table. Here we can use the same {{{style}}} syntax but we an also use a dynamic cell syntax such as :::voltageCell:::. This kind of dynamic cell syntax tells us that there is a section in the dymanicCells configuration which holds the definition of that cell.

    "layout": [
        ["Voltage{{{bold=false}}}", ":::voltageCell:::{{{italic=true}}}"],
        ["Current{{{bold=false}}}", ":::currentCell:::{{{italic=true}}}"]
    ]

We see two cells defined as dynamic in the layout above, with names voltageCell and currentCell. As an aside, we see our {{{style}}} syntax here again which simply initializes the cells with the corresponding styles. As noted, we expect to find voltageCell and currentCell sections under the dynamicCells configuration which will allow us to define expressions for:

1. value - the value to display in the cell
2. defaultValue - the value to assigned when any variables used in the value aren’t yet available
3. bgColor - the background color to display for the cell
4. textColor - the text color to display for the cell

Here’s how the configuration might look for the dynamicCells section corresponding to the above layout:

    "dynamicCells": {
        "voltageCell": {
            "value": "@VAR{voltage} V",
            "defaultValue": "waiting...",
            "bgColor": "String:Map( @VAR{voltageExceedsLimit}, {\"true\": \"red\"}, \"white\")",
            "textColor": "String:Map( @VAR{voltageExceedsLimit}, {\"true\": \"white\"}, \"black\")"
        },
        "currentCell": {
            "value": "EXPR(2*@VAR{voltage}) mA",
            "defaultValue": "waiting...",
            "bgColor": null,
            "textColor": null
        }
    }

Notice that we use the variable @VAR{voltage} to assign the value, while also specifying the units (V for volts). We also use the Map function here to give the voltageCell a red background with white text if the voltage exceeds a specified limit. We do similarly for defining the currentCell but we don’t define expressions for the bgColor or textColor.

Before the published data arrives, the defaultValue will render as defined for the two otherwise dynamic cells:

After data arrives, the data table will apply the dynamic cell definitions accordingly:

Finally, it’s worth noting that while the plugin provides several colors out-of-the-box which can be assigned (), you may also define custom colors using the customColors configuration. Below we show two custom colors defined for “orange” and “gold”:

    "customColors": {
        "orange": {
            "r": 255,
            "g": 165,
            "b": 0
        }, 
        "gold": {
            "r": 255,
            "g": 215,
            "b": 0
        }
    }

Configuration Example

Configuration Details

[]

[
    "workerName",
    "instanceName"
]

{
    "exmapleVar1": 10,
    "exmapleVar2": "kitty"
}

{
    "My Plugin Instance": {}
}

[]

[]

[]

[]

[]

{}

{
    "orange": {
        "r": 255,
        "g": 165,
        "b": 0
    }
}