139 lines
12 KiB
Markdown
139 lines
12 KiB
Markdown
---
|
||
task: Configure a trend (chart) component; what each setting does on the desktop and in the HTML display
|
||
version: R1.03
|
||
source: IM 36K10C50-01EN §2.27 (Trend, Tables 2.27-10…28), §2.29 (Micro Trend); IM 36K10R30-01EN §4.8.7; installed web client code (`%TLS_WAP_PATH%\mobileoperator\src\fasttools\ui\components\implementation\charts\`); practiced on CI-Eng-Sample (display CIENG_TrendLab) 2026-10-02
|
||
status: verified (desktop Operator Interface: every row marked ✅/❌ below; HTML display: §6)
|
||
---
|
||
|
||
# Trend settings (desktop and web)
|
||
|
||
Example: `examples/CI-Eng-Sample/displays/CIENG_TrendLab.xml` (deployed by
|
||
`deploy_displays.cmd`). Method used: change one XML value in the display, deploy, *View >
|
||
Reload* in the client, compare.
|
||
|
||
## 1. Before you start
|
||
|
||
- **Data**: the trend draws history. `TANK1.LEVEL` / `TANK1.INFLOW` are internal items: after a
|
||
CI Server start they are `NOT INIT` (value 0) until something writes them, and the trend then
|
||
shows nothing (or a bold black line at 0 with status drawing). For tests run
|
||
`displays/trend_feed.ps1` (writes sine waves with `itmval` every 5 s; `-Seconds` = run time).
|
||
- **Reload**: changes in the display file show after *View > Reload*. A reload within a few
|
||
seconds of the deploy can still show the old file — reload again.
|
||
- The **Trend properties** dialog (right-click the trend) and the trend toolbar change the trend
|
||
only for the session; *Save trend as* writes a trend definition to
|
||
`%TLS_WAP_PATH%\cfg\charts\<name>.xml` (same `<chartPanel>` format; factory `Template1..4.xml`).
|
||
The display file holds the start-up settings under `<chart>` › `<config>` › `<chartPanel>`.
|
||
|
||
## 2. Pen source (`<pen>` › `<source uri=…>`)
|
||
|
||
```
|
||
ci:/item/<Section>.<Tag>[?historygroup=<GROUP>[&aggregationperiod=<PERIOD>]][#<ATTR>]
|
||
```
|
||
|
||
| Part | Values | Result (desktop and web the same) |
|
||
|---|---|---|
|
||
| no `historygroup` | — | works; trend picks the highest-priority storage group (here `CIENG_SCAN10S`, seen in table mode); legend without `[group]` |
|
||
| `historygroup=CIENG_EVENT` / `CIENG_SCAN10S` | an item storage group | works; legend `… [GROUP]` |
|
||
| aggregation group without attribute | e.g. `CIENG_AGG` | ❌ `WFL-E-HIS_ITMN` / `ITH-E-NO_ADM_UPD` *Item not defined in group, or group not specified* |
|
||
| aggregation group **with** `aggregationperiod` + `#MAX` | periods `30MIN HOUR SHIFT DAY WEEK MONTH YEAR`; attributes `MAX MIN AVG INT SDV CNT DFSM` | ✅ one flat segment per finished period; legend `… / AGG_MAX 30MIN [CIENG_AGG]` |
|
||
| `#H` `#HH` `#L` `#LL` `#DB` | limit / deadband attributes | ❌ *Record not found* unless the limit history is stored |
|
||
| `uri=""` | — | empty pen |
|
||
|
||
`&` must be written `&` in the XML. The *Pen attributes > Attribute[n]* property of the
|
||
component is the same attribute (`ITEM_VALUE`, `AGG_MAX`…): connecting it to an item by mistake
|
||
gives *Short attribute name (<value>) is invalid* (ISS-041 history).
|
||
|
||
## 3. Pen settings (`<pen>`)
|
||
|
||
| XML | Values | Desktop result |
|
||
|---|---|---|
|
||
| `type` | 0/1 line, 2 bar (no button in the pen panel), 3 stair-step, 4 scatter (squares); **+256** = status drawing: offline / `NOT INIT` parts drawn bold black (256 = Edit Module default = line + status) | ✅ |
|
||
| `color`, `stroke width` | | ✅ |
|
||
| `paint` (fill) `<paint type="paint"><paint type="colorSet" …/></paint>` | | ✅ filled from 0 up, **opaque** (covers other pens); legend symbol filled |
|
||
| `visible` false | | ✅ line hidden **and** removed from legend; tick cleared in the pen panel |
|
||
| `visibleLegend` false / `legendText` | | ✅ hidden from / renamed in the legend |
|
||
| `scaleRangeType` | **0** item scale range (item definition), **1** manual `minimum`/`maximum`, **2** fit to data (with margin; min/max ignored) | ✅ |
|
||
| `procentual` | | ✅ axis 0–100 % of the range, `%` label |
|
||
| `timeShift` | seconds | ✅ data drawn later by that time (overlay of older data) |
|
||
| `axisVisible` | | ✅ value axis (left); clicking a legend entry also shows that pen's axis and thickens the line (hover thickens) |
|
||
| `axisPosition` | 0 left, 1 right | ✅ |
|
||
| `axisColor`, `labelColor` (`<axisColor type="colorSet" r=… g=… b=…/>`, `@NULL` = pen colour) | | ✅ axis + ticks / numbers |
|
||
| `labelRotation` | degrees | ✅ |
|
||
| `majorTickVisible` + `minorTickVisible` false | | removes the numbers too |
|
||
| `title`, `titlePlacement` | | ❌ nothing shown |
|
||
| `majorGridVisible`, `minorGridVisible`, `majorGridColor` | | ✅ horizontal grid in pen colour / given colour |
|
||
| `lowHighLimitGridVisible`, `lowLowHighHighLimitGridVisible` | | ✅ lines at the **item definition** limits |
|
||
| `lowLimit`…`highHighLimit` | | ❌ ignored (item definition limits are used) |
|
||
| `lowHighLimitGridAreaVisible` | | ✅ band L…H in pen colour, **opaque, drawn over the line** |
|
||
| `maximumPens` (chart level) | | ✅ only the first n pens are loaded |
|
||
| `description` | | pen panel shows the **item** description, not this value |
|
||
|
||
## 4. Chart settings (`<chartPanel>`)
|
||
|
||
| Group | XML | Desktop result |
|
||
|---|---|---|
|
||
| Time range | `<timeRange type="timeRangeLast" count="10"><type type="timeUnit" value="TimeUnitMinute"/></timeRange>`; `timeRangeCurrent` (no count) = current minute/hour/day…; units `TimeUnitMinute Hour Day Week Month Year` | ✅ (*Current hour*: 12:00–13:00, line up to now) |
|
||
| | `updating` true | ✅ runs live when opened (play grey, stop red) |
|
||
| | `updateInterval` (s) | ✅ shown in *Update every* (60 → "1 Minutes") |
|
||
| | `autoUpdateInterval` true | ✅ the *Update every* field disappears |
|
||
| | `fillHistory` false | ✅ empty (all pens red tag) until the first update interval, then filled |
|
||
| | custom range: `<timeRange type="timeRangeSpecific"><startTime type="date" value="2026.10.02 13:30:00.0 AEST"/><endTime type="date" value="…"/></timeRange>` (format `yyyy.MM.dd HH:mm:ss.S z`) | ✅ desktop and web: axis and time control show the range; desktop greys out play, stop and *Update every* (no live update) |
|
||
| Performance | `optimised` true (default) = sample interval by zoom (`cfg\configurations\ChartThresholdTables.xml`) | — |
|
||
| | `optimised` false + `useSampleInterval` true + `sampleInterval` 60 | ✅ one point per 60 s, last value held to now |
|
||
| | `useSampleInterval` false | ✅ all stored samples |
|
||
| | `updateFromHistory` false (runtime values) | no visible difference |
|
||
| Appearance | `plotAreaTransparent` false + `plotAreaPaint` | ✅ plot colour (paint has no effect while transparent) |
|
||
| | `backgroundPaint` | ❌ no visible effect |
|
||
| | `hairlineVisible`, `hairlineColor` | ✅ toolbar hairline button on; click in the plot → line + box with time and pen values |
|
||
| | `timeSliderVisible`, `valueSliderVisible` false | ✅ sliders removed |
|
||
| | `xAxisReversed` / `yAxisReversed` | ✅ newest left **and** time axis moves to the top / 0 at top **and** value axis moves right |
|
||
| | `renderMode` `Rendering2d`, `RenderingTable`, `Rendering3dObl`, `Rendering3dOrt`; `RenderingCSS` | ✅ table = sample time, value and status per pen (good to see what the server returns); 3dObl = hatched ribbons; 3dOrt = 3D box with the time axis into depth, lines thick and **black** (pen colours lost); ❌ `RenderingCSS`: display does not load (`renderingType 4 is unsupported`) |
|
||
| Time axis | `timeAxisMajorGridColor`, `timeAxisLabelRotation`, `timeAxisTitle` | ✅ (the time-axis title shows, unlike the pen title) |
|
||
| | `timeAxisLongLabelVisible` false | ✅ date line under the first label removed |
|
||
| | `timeAxisMinorTickVisible`, `timeAxisMinorGridVisible` | nothing at a 10-minute range |
|
||
| Header/footer | `headerText`, `footerText` | ✅ top-left above the plot / bottom-left below the time control |
|
||
| Legend | `legendPositionType` `PositionNorthEast` (default, right panel), `PositionSouthWest` (= full-height panel on the **left**); also `NorthBottom NorthTop NorthWest SouthBottom SouthTop SouthEast East Absolute` | ✅ |
|
||
| | `legendTitle`, `legendColor`, `legendBackgroundColor`, `legendTransparancy` | ✅ |
|
||
| Controls | `toolbarVisible` false, `timeRangeControlVisible` false | ✅ toolbar / date and range boxes removed |
|
||
| Pen panel | `penPanelVisible`; `penPanelLayout` columns: 0 visible, 1 colour, 2 source, 3 description, 4 units, 5 hairline value, 6 statistics (min \| max \| avg of the shown range), 7 legend, 8 min, 9 max, 10 %, 11 scale range, 12 time offset, 13 appearance, 14 axis, 15 grid (default visible 0–4, 8, 9, 11, 13) | ✅ |
|
||
|
||
Gaps (CI Server stopped): the desktop joined the last and next sample with a straight line, or
|
||
held a scan-group pen flat (seen once); the web drops to 0.
|
||
|
||
## 5. Component property sheet (Edit Module, connectable)
|
||
|
||
20 pen slots `[00]`–`[19]`. Inputs (⇦, item → trend): colours, tooltip, visible, transparency,
|
||
rotation, zoom. Outputs (⇨): *Hairline value[n]*, *Time range begin/end*, *Update interval*,
|
||
*Updating possible*. Both (◇): *Item name[n]*, *Attribute[n]*, *Color[n]*, *Min/Max[n]*,
|
||
*Scale type[n]*, *History group[n]*, *Updating*, *Use history*, *Item index/name*,
|
||
*Configuration file*. Connections were listed, not tested.
|
||
|
||
## 6. HTML display (web client)
|
||
|
||
- **A trend with fewer than 50 visible pens with an item draws no line** in R1.03 (ISS-041):
|
||
the web code always builds 50 data columns (`PEN_COUNT_LIMIT`) but labels only the visible
|
||
pens with an item; console `Mismatch between number of labels (…) and number of columns in
|
||
array (51)`. The desktop is not affected.
|
||
- **Workaround** (verified 2026-10-02): pad the trend to 50 pens with
|
||
`displays/add_trend_spares.ps1 -Path <display>.xml`. Spares copy the first pen's source,
|
||
are scaled to 1E30–2E30 (clipped), hidden from the legend and get blank unique legend texts
|
||
in the legend background colour
|
||
(the web legend ignores *Show in legend*, ISS-056). Run it again after editing the trend; do
|
||
not keep hidden real pens: one hidden real pen (49 visible) and nothing draws again (checked).
|
||
Cost: 50 history requests per trend.
|
||
- **Web check of the settings** (2026-10-02, padded scratch copy of `CIENG_TrendLab`, checked in
|
||
the browser; supported-property lists: IM 36K10C50 Table 2.27-28, IM 36K10R30 §4.8.7):
|
||
|
||
| Works as on the desktop | Ignored on the web | Different on the web |
|
||
|---|---|---|
|
||
| pen type line / stair-step / scatter, stroke, fill paint, `legendText`, scale range 0/1/2 (item, manual, fit), `axisVisible`, `axisColor`, `labelColor`; last / current time range, `updateInterval`, `autoUpdateInterval` (field hidden), `updating` true/false, fixed sample interval, `timeRangeControlVisible`; `plotAreaTransparent` + `plotAreaPaint`, header, footer, time-axis grid colour, time-axis label rotation, `timeAxisLongLabelVisible`, `legendVisible`, legend text and background colour | pen `labelRotation`, `axisPosition` (axis stays left), `procentual`, major/minor grid, limit lines; `timeAxisTitle`, legend position and title, pen panel, trend toolbar (no way to add pens in the browser), `xAxisReversed`, render mode (always 2D), *Show in legend* (ISS-056) | `timeShift`: data shifted, then message *Illegal start/end time specification*. Hairline: shown on **hover** (not click), box with time, value and status of the nearest pen only. Only **one** value axis is drawn; pens without an axis are plotted as % of their own range against it (misleading). Gaps (CI Server down) drop to 0. |
|
||
- **Micro Trend** (`<microTrend>`, up to 4 pens, own SVG drawing, no controls; per-pen
|
||
`<property type="componentProperty"><name>itemName[0]</name><value>…</value></property>`,
|
||
`scaleMin[n]`, `scaleMax[n]`; elements `numberOfPens`, `realTime`, `fillWithHistory`,
|
||
`timeRange` (s, default 300), `sampleCount` (default 300)): drew on desktop and web the first
|
||
time, then stayed blank on several later opens (ISS-055). Cause: *Number of pens* resets all
|
||
pen sources, so fixed item names can be lost during load. **Connect** `microTrend.itemName[n]`
|
||
to the item with attribute `ItemName` instead (`<action type="actionConnectTo">`, `<direction>1`,
|
||
`<itemAttribute>ItemName`; sample `CIENG_TrendLab`): both pens then drew on every open; the
|
||
history fill still failed at times on the web and on the desktop (only the live part drew;
|
||
ISS-055 open).
|