WinCCOA WebComponent Dashboard — wui-oarxjs-context

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.

Overview

Declarative data-binding for Lit components. A <wui-context-generator> element wraps any consumer (a widget, a custom element, an iX component) and feeds it values resolved from a config object — datapoints, translations, click→dpSet actions, historic queries, alarm colors. Each value is resolved by a small context element keyed by a string in the config.

import '@wincc-oa/wui-oarxjs-context/components/wui-context-generator/wui-context-generator.js';

html`
  <wui-context-generator
    .config=${{
      value: {
        context: 'data-point',
        config: {
          dpName: 'System1:MyDp.',
          definedConfigs: ['value', 'min', 'max', 'unit', 'format', 'alertColor', 'name']
        }
      }
    }}
  >
    <wui-widget-gauge chartType="arc"></wui-widget-gauge>
  </wui-context-generator>
`;

The consumer reads the resolved values from the wui-context-generator (e.g. via Lit Context). Multiple slots in the config are resolved independently; any context can be nested inside another via array / group.

Context Types

Subscribes to a single datapoint (live by default). Available definedConfigs decide which fields are exposed to the consumer:

| Config | Description | | ------------- | ----------------------------- | | value | Current datapoint value | | min / max | Range bounds (from DP config) | | unit | Unit of measurement | | format | Format string (e.g. "%.2f") | | alertColor | Current alarm color | | color | Color value | | name | DP name / description |

For trend charts, switch to fetchMethod: 'historic'. The wui-widget-trend widget expects a series → array → group → datapoint shape, with compress at the data-point config level (not nested inside historic) and 'datapoint' listed first in definedConfigs:

import '@wincc-oa/wui-widgets/wui-widget-trend/wui-widget-trend.js';

const trendConfig = {
  series: {
    context: 'array',
    config: [
      {
        context: 'group',
        config: {
          datapoint: {
            context: 'data-point',
            config: {
              dpName: 'System1:MyDp.',
              compress: true, // ← at this level, NOT inside historic
              fetchMethod: 'historic',
              historic: {
                sTimeRange: '1h' // "20m", "1h", "8h", "24h", ...
              },
              definedConfigs: [
                'datapoint', // ← must be first
                'value',
                'name',
                'unit',
                'format',
                'color',
                'min',
                'max',
                'alertColor'
              ]
            }
          }
        }
      }
    ]
  }
};

html`
  <wui-context-generator .config=${trendConfig}>
    <wui-widget-trend style="width: 100%; height: 100%;" showXAxisGrid showYAxisGrid></wui-widget-trend>
  </wui-context-generator>
`;

wui-widget-trend needs an explicit pixel height. ECharts uses ResizeObserver and won't render without one. height: 100% only works when the parent has a definite height via flex/grid layout.

Under the hood, fetchMethod: 'historic' runs oaRxJsApi.dpQuery() with a TIMERANGE query. See @etm-professional-control/oa-rx-js-api README for raw historic methods (dpQuery, dpGetPeriod).

Full set of historic options:

| Option | Description | | ----------------- | -------------------------------------------------------------------------- | | sTimeRange | Time range string: "5m", "15m", "1h", "24h", … | | compress | Set on the data-point config (above), not here. true enables aggregation | | fields | ["values", "timestamps", "min", "max", "last", "avg", "sum", "count"] | | timeSlots | Number of slots when compress: true | | timeSlotSeconds | Seconds per slot (alternative to timeSlots) | | interpolate | "begin" | "intermediate" | "end" |

When compress: true, the resolved value has shape:

{
  value: {
    values: number[], timestamps: number[],
    min: number[], max: number[], avg: number[], last: number[],
    sum: number[], count: number[]
  },
  name: string, unit: string, format: string
}

Listen to a UI event and write the value to a datapoint:

{
  value: {
    context: 'data-point',
    config: {
      dpName: 'System1:PumpSpeed.',
      definedConfigs: ['value', 'min', 'max', 'unit'],
      dpSet: {
        event: 'change',          // 'change' | 'click'
        validate: true,           // validate the value before sending
        successNotification: true // toast on success
      }
    }
  }
}

dpSet options: event, validate, customValue (override event value with a fixed value), customEvent (custom event handling), successNotification.

A read-and-write slider:

html`
  <wui-context-generator
    .config=${{
      value: {
        context: 'data-point',
        config: {
          dpName: 'System1:PumpSpeed.',
          definedConfigs: ['value', 'min', 'max', 'unit'],
          dpSet: { event: 'change', validate: true }
        }
      }
    }}
  >
    <wui-widget-slider></wui-widget-slider>
  </wui-context-generator>
`;

Useful for buttons that publish a fixed value:

html`
  <wui-context-generator
    .config=${{
      click: {
        context: 'dpset',
        config: { dpName: 'System1:MyDp.', value: 75 }
      }
    }}
  >
    <ix-button>Set to 75</ix-button>
  </wui-context-generator>
`;

Multi-series charts, grouped panels, anything that needs structure rather than a flat scalar:

html`
  <wui-context-generator
    .config=${{
      series: {
        context: 'array',
        config: [
          {
            context: 'group',
            config: {
              name: { context: 'translate', config: 'MyApp.Tank1Label' },
              value: {
                context: 'data-point',
                config: { dpName: 'System1:Tank1Level.', definedConfigs: ['value'] }
              }
            }
          }
        ]
      }
    }}
  >
    <wui-widget-barchart></wui-widget-barchart>
  </wui-context-generator>
`;

{
  headerTitle: {
    context: 'translate',
    config: {
      'en_US.utf8': 'My Page Title',
      'de_AT.utf8': 'Mein Seitentitel'
    }
  }
}

Also accepts a translation key string (e.g. 'WUI_General.Save').

Resolves a DP's current alarm color into a CSS color string. Subscribes (via DpConnectHandler, see @wincc-oa/wui-oarxjs-data README) to the DP's :_alert_hdl.._act_state_color attribute, looks up the resulting color name through the theme's --oa-color--<name> CSS variables, and emits the resolved value (e.g. rgba(255, 0, 0, 1)):

const config = {
  color: {
    context: 'dpconnectalertcolor',
    config: 'System1:MyDp.' // or { dpName: 'System1:MyDp.' } / { dpName: ['Dp1.', 'Dp2.'] }
  }
};

Use this when you want a widget to color itself based on a DP's current alarm state without writing the subscription + name resolution yourself.

Alert.color from AlertService is already a hex string — for that you don't need this context. See @wincc-oa/wui-alert-data README.

Dynamic Context Loading

importContextModule() loads context elements using different strategies based on build configuration:

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

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

License

MIT