Operator screens and process graphics

HMI Shell `<smart-hmi-shell>`

HmiShell is the display frame for operator screens described in ISA-101.

JavaScript TypeScript Angular React Vue Blazor

<smart-hmi-shell> · 17 properties, 2 methods, 4 events · source/modules/smart.hmishell.js

Usage in Angular

The Angular wrapper is HmiShellComponent from HmiShellModule: every property is an input, every event an output named on<Event>, and the methods are called on the component reference from @ViewChild. A method that returns a value returns a Promise of it, resolved once the component has rendered; its ...Sync() twin returns the value at once, or null before the component has rendered. Unknown bindings are rejected at compile time.

import { HmiShellModule, HmiShellComponent } from 'smart-industrial/angular/hmishell';

<smart-hmi-shell #hmiShell [plant]="'Northfield plant'"
    (onNavigate)="onNavigate($event)"></smart-hmi-shell>

@ViewChild('hmiShell', { read: HmiShellComponent }) hmiShell!: HmiShellComponent;
// methods are called on the component reference
this.hmiShell.setTheme('value');

Properties

Input	Type, default	Description
`[plant]` plant	string	Sets or retrieves the plant or site name, the header's first line.
`[area]` area	string	Sets or retrieves the area, the first step of the breadcrumb under the plant name.
`[screen]` screen	string	Sets or retrieves the name of the screen, shown as the last step of the breadcrumb and included in the accessible name of the shell.
`[user]` user	string	Sets or retrieves who is logged on. Shown as a button in the header that raises userClick, for a application's log-off or e-signature dialog. Empty hides it.
`[userRole]` userRole	string	Sets or retrieves the role of the user, shown next to the name. The property is not named role because role is the ARIA attribute of the component.
`[showClock]` showClock	boolean true	Determines whether the 24-hour clock is shown in the header.
`[connection]` connection	HmiShellConnection unknown	Sets or retrieves the data connection state, using the state words reported by a Smart.Industrial.Connect session, plus unknown for a screen without a session. The state is shown as a word with an indicator dot and exposed as a live status; a lost connection is announced assertively.
`[connectionDetail]` connectionDetail	string	Sets or retrieves extra text beside the connection word, the gateway's name, a latency.
`[navigation]` navigation	array	Sets or retrieves the displays as [{ id, label, level, active, alarms, disabled }]. level is the ISA-101 display level (1 to 4) and indents the item. alarms is a number or { critical, warning, advisory }; the badge shows the highest non-zero priority with its count, and the priority word is included in the accessible name of the item. A plain number is treated as critical. Pressing an item raises the navigate event; the application changes the screen.
`[alarms]` alarms	array	Sets or retrieves the alarms the footer summarises, in the shape AlarmBanner takes: [{ id, tag, message, priority, severity, timestamp, acknowledged, active, shelvedUntil, suppressed, outOfService }], read as ISA-18.2 reads an alarm list. Priority 0 and 1 are critical, 2 warning, 3 and above advisory - a number written as text counts as the number, and a severity (critical, warning, advisory) given on a record wins over its priority. The footer counts the active alarms by priority; counts as unacknowledged both active unacknowledged alarms and alarms that returned to normal before anybody acknowledged them; names the most urgent unacknowledged alarm (by priority, then the newest); and takes its colour from the worst alarm that is active or still unacknowledged. Shelved, suppressed and out-of-service alarms are not active and never named as needing attention; they are counted separately ('2 shelved'). A record without active is active. It acknowledges nothing.
`[showFooter]` showFooter	boolean true	Determines whether the alarm strip is shown.
`[showNavigation]` showNavigation	boolean true	Determines whether the navigation bar is shown.
`[showThemeToggle]` showThemeToggle	boolean false	Determines whether the header offers a switch between lightTheme and darkTheme.
`[lightTheme]` lightTheme	string industrial	Sets or retrieves the theme the toggle switches to from a dark one.
`[darkTheme]` darkTheme	string industrial-dark	Sets or retrieves the theme the toggle switches to from a light one.
`[density]` density	HmiShellDensity normal	Sets or retrieves the target density. touch makes every target in the shell at least 44 px and the header taller, for panel PCs and gloved operation; normal is the desktop density. The value is reflected to an attribute used by the stylesheet.
`[announceChanges]` announceChanges	boolean true	Determines whether a change of connection state is read through the live region.

Methods

Method	Description
`setTheme(theme: string): void`	Sets the theme on the shell and on every element inside it that has a theme, so the whole screen switches at once, and raises the themeChange event. `theme` string The theme name.
`isDark(): Promise<any>` and `isDarkSync(): boolean`	Returns whether the current theme is the dark theme: the darkTheme, or any theme whose name ends in -dark.

Events

The data of an event is in event.detail. navigate is a request: the HMI shell keeps screen and the active item in navigation until the application changes them. themeChange follows a theme the shell has already applied, and alarmsClick and userClick report clicks on the alarm strip and the user area.

Output	Description and detail
`(onNavigate)` navigate	This event is triggered when a display is selected in the navigation bar. The application changes the screen. A held Enter raises it once. `id` string The display's id. `item` object The navigation item as the application supplied it. `index` number Its position in the list.
`(onAlarmsClick)` alarmsClick	This event is triggered when the alarm strip is pressed - with the mouse, or with Enter or Space, since the strip is a button in the tab order - so that the application can open the alarm list. A control placed in the footer slot by the application does not raise this event. `alarms` any[] A copy of the alarm list.
`(onUserClick)` userClick	This event is triggered when the user button is pressed, for a application's log-off or e-signature dialog. `user` string Who is logged on. `role` string Their role.
`(onThemeChange)` themeChange	This event is triggered when the theme is switched through the toggle or setTheme, after every element inside the shell has been switched with it. `theme` string The theme now in force. `previousTheme` string The theme before.

Types

`type HmiShellConnection`

`type HmiShellDensity`

'normal' | 'touch'

CSS variables

The component declares 7 CSS variables; the CSS page shows how to set them.

--smart-hmi-shell-height --smart-hmi-shell-gap --smart-hmi-shell-header-height --smart-hmi-shell-target --smart-hmi-shell-canvas --smart-hmi-shell-panel --smart-hmi-shell-border