Skip to content

Manage Highlight Rules

This page describes Highlight Rules which are a common property utilizing color or icon markers, or both, to notify users of value changes and are best used with real-time streaming or polling data.

Screenshot

Highlight rules in operation in a Data Grid

Supported in: Canvas Chart, ChartGL, Data Grid, Pie Chart.

Build a Rule

Screenshot

Field Description
Name Assign a name for your rule.
Target The Data Source column updated when the rule is true.
Condition Source The Data Source column monitored by the Condition Operator against the Condition Value.
Condition Operator May be a numeric comparison, but can also test for strings in text values. search — find Condition Value match; assign a View State Parameter and pair with Text Input. contains — find all instances with the Condition Value. starts with — find all instances starting with the Condition Value. ends with — find all instances ending with the Condition Value. == — exact match, e.g. client name. < — less than Condition Value. > — greater than Condition Value. <= — less than or equal to Condition Value. >= — greater than or equal to Condition Value. != — excludes Condition Value.
Condition Value Typically previous value. Can also be mapped to a View State Parameter. Can be either a numeric or text value; for example, if searching for a client name from a list of clients in a Data Grid column.
Color Text color changed by rule when true.
Background Color Data Grid cell background or Canvas Chart bar or point changed by rule when true.
Border Color Data Grid cell border or Canvas Chart bar or point border changed by rule when true.
Icon / Icon Color For Data Grid, icon appears when rule is true.

See Data Grid for further details.

Define rules as JSON

In Data Grid and ChartGL, you can define and manage highlight rules as JSON instead of building each one in the rule editor. This lets you:

  • Copy a set of rules and reuse it in other components and dashboards, without rebuilding the rules by hand.
  • Set up complex or repeated rules more quickly.
  • Keep the rules under version control alongside your other dashboard settings.

JSON rules are independent of the rules you build in the rule editor. You can use either or both in the same component. If a JSON rule and a rule from the rule editor both set the same style on the same cell, the JSON rule takes precedence.

Data Grid

Paste a JSON array of rules into the Highlight Rules (JSON) field in the Highlight Rules JSON property group. Each entry in the array is one rule.

[
  {
    "target": "price",
    "source": "price",
    "operation": ">",
    "value": 100,
    "color": "#ffffff",
    "backgroundColour": "#ff0000",
    "backgroundOpacity": 60,
    "borderColor": "#000000",
    "Icon": "fa-arrow-up",
    "iconColor": "#00ff00"
  }
]
Field Required Description
target No The column the rule applies to. If you omit it, the rule applies to all columns ("*"). Dynamic and regular expression column matching works as it does for rules built in the rule editor.
source Yes The column whose value is compared.
operation Yes The comparison to make. One of ==, <, >, <=, >=, !=, search, regexp, contains, starts with, ends with, or in. See Build a rule for what each operator does.
value Yes The string or number to compare against.
color No The text color, as a hex value.
backgroundColour No The cell background color, as a hex value. Note the spelling of the field name.
backgroundOpacity No The opacity of the background color, from 0 to 100.
borderColor No The cell border color, as a hex value.
Icon No The icon class to show, for example fa-arrow-up. The icon appears only if you also set iconColor. Note the capital I.
iconColor No The icon color, as a hex value.

You can supply any combination of the style fields.

If an entry is not valid, Dashboards skips that entry only and applies the rest. An entry is not valid if it:

  • Is missing a required field.
  • Uses an unsupported operation.
  • Has an invalid hex color.
  • Has a backgroundOpacity outside the range 0 to 100.

A warning for each skipped entry appears in the browser console. When you change the JSON, the grid redraws.

ChartGL

ChartGL has the same Highlight Rules JSON property group, with a Highlight Rules (JSON) field. Each rule uses the same fields as a Data Grid rule. The source is a column in the chart's data. For example, the following rule matches the points where the country column equals ff.N+NYS_mainTrader+Sell:

[
  {
    "target": "date",
    "source": "country",
    "operation": "==",
    "value": "ff.N+NYS_mainTrader+Sell",
    "color": "#00FFFF"
  }
]

Drive the rules from a view state

You can bind both the Highlight Rules (JSON) field and Show Highlighted Only to view states, as you can with other properties. Click the eye icon beside a property to select a view state.

This lets users control highlighting while they use the dashboard. For example, you can build the JSON from the rows a user selects in a grid, store it in a view state, and bind that view state to the Highlight Rules (JSON) field of a Data Grid and a ChartGL. When the user selects rows, both components highlight the matching data. Bind Show Highlighted Only to another view state and add a control, such as a dropdown, to switch between showing all the data and showing only the highlighted data.

Show highlighted data only

In Data Grid and ChartGL, select Show Highlighted Only in the Highlight Rules JSON property group to display only the data that matches your JSON highlight rules. Use it to focus on outliers, thresholds, and alerts without the surrounding data.

  • If you define several JSON rules, Dashboards shows the data that matches any of them and hides the rest.
  • If no JSON rule applies, because you haven't defined any or none match, all the data stays visible.
  • The option affects only rules defined in JSON. Other ways of highlighting, such as rules built in the rule editor, aren't affected.
  • By default the option is off, and all the data is shown with the highlighting applied.

In a Data Grid, the rows that don't match a JSON rule are hidden, so only the highlighted rows remain.

Highlighting also works when you apply a view state parameter range, so the display reflects the rules and the range together.

Gradient

Screenshot

Gradient highlight rule applied to bubble and bar canvas chart

Set a gradient color using Color Palette with a range defined by Rule Min and Rule Max.

See Canvas Chart for further details.