Creating your custom SVG Widget

The JSON file contains the description for how the new SVG Widget will work.

Multiple examples for the JSON file can be found with the existing widgets in the data/WebUI/widgets folder inside your installation. Some widgets, such as the traffic lights are already implementations of an SVG widget. All other widgets also follow roughly the same structure and can thus be used as inspiration.

Exemplary, one of the rules defined in the aforementioned traffic light is explained here:

{
  "operator": "is",
  "value": 2,
  "actions": [
    {
      "selector": ".red-active",
      "property": "opacity",
      "value": "0"
    },
    {
      "selector": ".yellow-active",
      "property": "opacity",
      "value": "0"
    },
    {
      "selector": ".green-active",
      "property": "opacity",
      "value": "1"
    }
  ]
}

This rule is used to activate the green element within the SVG when the corresponding data point has the value 2.

The logical operator "is", in combination with the value "2" defines that the following rule is executed when the datapoint reaches the exact value of "2".

This rule has 3 associated "actions". Each action targets one of the round elements, which brighten the lights within the traffic light widget. The first action targets the red element with the designation ".red-active" in the "selector". The property manipulated is "opacity". It is set to "0" to remove all opacity. This removes the object. Likewise, the opacity of the yellow element is also set to "0". The green element's opacity is set to "1" to show it entirely.

Both the rules as well as the actions can use already present configuration attributes of datapoints as variables. These attributes are listed in the widget settings directly below the selected datapoint and when one of the "value" input-fields is clicked.

Example

{
    "operator": "between",
    "value": { "from": "{min}, "to": "{max}" },
    "actions": [
    {
      "selector": ".left-tank",
      "property": "fill",
      "value": "{alertrange_1_color}"
    }
  ]
},

In this example, the operator "between" is used to check if the datapoint value is between the "{min}" and "{max}" - which is the specified PV Range configuration. If this is true, then the section ".left-tank" will be highlighted in the defined alert color.

You can also use simple CSS functions inside of actions. This can be helpful to position or scale elements correctly inside the SVG.

Example:

{
  "operator": "always",
  "value": "",
  "actions": [
   {
     "property": "style",
     "selector": "#rect1",
     "value": "transform: translate(22.8px, 51.8px) scaley(clamp(0, calc(1 - ({value} - {min}) / ({max} - {min})), 1))"
    },
    {
      "property": "fill",
      "selector": "#rect2",
      "value": "url(#gradient1)"
    },
  ]
},

In this example, the operator "always" is used to execute the action with every change of the datapoint value. The element with the HTML ID "#rect" is first moved ("translate") with the "transform" CSS attribute, and then adjusted in height with "scaley". In the calculation after this, the normalized datapoint value is interpolated in a value range between 0 and 1.

Important hereby is that these CSS functions only work in conjunction with the "style" property. While it is possible to directly use the "transform" function of the SVG elements, this would not allow the use of CSS functions like "calc", "max", or "clamp".

For example, reusing a defined color gradient in an SVG can be accomplished by using the "url()" function. This is shown in the second action above.