Operator screens and process graphics

HMI Shell <smart-hmi-shell>

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

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

Usage in TypeScript

The package ships its definitions: HmiShell is the element type and HmiShellProperties the properties, both exported from smart-industrial/source/typescript/smart.industrial. document.querySelector('smart-hmi-shell') is typed as HmiShell.

import { HmiShell, HmiShellProperties } from 'smart-industrial/source/typescript/smart.industrial';

const hmiShell = document.querySelector('smart-hmi-shell') as HmiShell;

hmiShell.plant = 'Northfield plant';
hmiShell.addEventListener('navigate', (event: CustomEvent) => console.log(event.detail));
hmiShell.setTheme('value');

Properties

Property	Type, default	Description
plant	string	Sets or retrieves the plant or site name, the header's first line.
area	string	Sets or retrieves the area, the first step of the breadcrumb under the plant name.
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	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	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	boolean true	Determines whether the 24-hour clock is shown in the header.
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	string	Sets or retrieves extra text beside the connection word, the gateway's name, a latency.
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	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	boolean true	Determines whether the alarm strip is shown.
showNavigation	boolean true	Determines whether the navigation bar is shown.
showThemeToggle	boolean false	Determines whether the header offers a switch between lightTheme and darkTheme.
lightTheme	string industrial	Sets or retrieves the theme the toggle switches to from a dark one.
darkTheme	string industrial-dark	Sets or retrieves the theme the toggle switches to from a light one.
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	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(): 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.

Event	Description and detail
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.
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.
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.
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

'connected' | 'connecting' | 'reconnecting' | 'error' | 'closed' | 'unknown'

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