WinCCOA WebComponent Dashboard - Widgets Library

This package is part of the workspace for the WinCC Open Architecture WebComponent Dashboard, built using Lit and managed with Nx.

Usage information and reference details can be found in the WinCC OA documentation.

Dynamic Widget Loading

importWidgetModule() loads widgets using different strategies based on build configuration:

• Dev mode: Relative imports (../wui-widget-${name}.ts)
• Prod with externals: Namespaced imports via import map (@wincc-oa/wui-widgets/...)
• Prod bundled: Relative imports

The strategy is automatically determined by vite.config.ts based on whether vendorExternals is configured

wui-widget-svg

Renders an SVG file and mutates it live from datapoint values: colors, fill levels, rotation, visibility, text content. A widget author supplies the SVG file plus a set of rules - no changes to wui-widget-svg.ts itself are needed per widget. Silo, pressure gauge, and traffic light dashboard widgets are built this way.

{
  "svgFile": "/data/WebUI/svg/silo.svg",
  "vars": [
    { "name": "min", "value": 0, "usage": "manual" },
    { "name": "max", "value": 200, "usage": "manual" }
  ],
  "rules": [
    {
      "operator": "hasAlert",
      "value": "",
      "actions": [{ "property": "fill", "selector": "#Shape_Alert", "value": "{alert_color}" }]
    }
  ]
}

Each rule is evaluated in order against the datapoint's current value; matching rules run their actions, each setting a property (a CSS style when the property starts with style., textContent for text, otherwise an attribute) on every SVG element matched by selector.

| Operator | Matches when | | -------------------------- | --------------------------------------- | | always | unconditionally | | is / isnot | value equals / does not equal | | smaller / smallerEqual | value is less than / at most | | greater / greaterEqual | value is greater than / at least | | between | value is within {from, to} | | contains | value contains a substring | | hasAlert / hasnotAlert | the datapoint has / has no active alert |

vars declares reusable placeholders for use in rule/action values. See the widget's own settings page for the full vars/rules field reference and examples.

Any {name} in a rule's value or an action's value is replaced before the rule runs: {value} is the datapoint's current value, {formatted_value} is its formatted string, {alert_color} is its active alert color, and any name declared in vars resolves to that variable's value. A var with usage: "OA" resolves from the linked datapoint's own attributes (min, max, unit, format, alertColor, value, name) instead of a fixed value.

wui-widget-svg only reacts to clicks that the SVG itself announces. Add an inline onclick to any element you want to be interactive - it dispatches a wui:svg-shape-click event named after the element's own id:

<g id="my-switch" onclick="dispatchEvent(new CustomEvent('wui:svg-shape-click', { bubbles: true, detail: { eventname: 'click-'+this.id, value: this.getAttribute('value') } }))">
  <!-- visible shape -->
</g>

wui-widget-svg re-dispatches that as a click-my-switch event on itself. Use that exact name as dpSet.event in the widget's datapoint config to write a value when the region is clicked - see @wincc-oa/wui-oarxjs-context's README, "data-point - Event-based writing (dpSet)", for the dpSet config shape. event is not limited to "change"/"click" - any string works, as long as it matches the name the SVG dispatches.

For a working example, see System1:grill1.command.throttle1 in the oa-grill widget's JSON (wc/oa-grill.widget.json in the WinCC OA project data) and the matching station-1-schalter element in its SVG file.

Not every SVG widget needs click handling. Silo, pressure gauge, and traffic light are read-only visualizations - rules alone drive their appearance, with no onclick in the SVG at all.

License

MIT