Skip to content

Top Bar

The Top Bar is the application header of an OpenBridge project. It shows the application and page name, the most important active alert, and the buttons that open the project-wide menus: navigation, alerts, brilliance (palette and dimming), user, and apps. It is found in the OpenBridge section of the Perspective Component Palette as Top Bar.

The Top Bar is designed to be placed once, in a top dock that is shared by all pages, so the menus and the palette are the same wherever the operator navigates. It is 48 px high, and its box never grows taller, whatever its position settings say: make the dock 48 px high.

Top Bar with every element enabled

From left to right:

  1. Navigation menu button — opens the navigation menu. See Navigation Menu.
  2. App icon, app name and page name — hasAppIcon, appIcon, appName, pageName.
  3. Asset picker (not in the picture) — a dropdown button that switches the asset the page shows. See Asset Picker.
  4. Command button — shows whether this workstation is in command. See Command Button.
  5. Alert message — the highest-priority active alert, with an ACK button. See Alert Menu.
  6. Alert button — one badge per alarm priority, then the bell and the total (the global counter). Opens the Alert Menu.
  7. Diagnostic button — off by default: the number of diagnostic alarms. Opens the Diagnostics Menu.
  8. Dimming button — opens the Brilliance Menu.
  9. User button — opens the User Menu.
  10. Apps button — see Apps Button.
  11. Clock — see Clock.

A Top Bar dropped from the palette with default properties shows only the navigation button, the app and page names, the alert button, the dimming button and the clock:

Top Bar with default properties

All menus opened from the Top Bar behave the same way:

  • Clicking a button opens its menu; clicking the same button again closes it.
  • A menu also closes when the operator presses Escape or clicks anywhere outside it.
  • Only one of the alert, diagnostics, brilliance and user menus is open at a time. Opening one closes the others.
  • The button of the open menu is shown highlighted.

Note: In the Designer, the Top Bar is only interactive in Preview Mode. Buttons that change the palette, the brightness or the pressed state of a button write to the component’s properties, so a click in Preview Mode is saved with the view. Reset those properties before saving if needed.


Navigation menu button pressed

The navigation menu button (☰) sits at the far left of the Top Bar. The Top Bar does not draw the navigation menu itself: the contents are an ordinary Perspective view that you design, shown in a docked view. This lets you use any components for navigation, for instance buttons with Navigate actions or an OpenBridge navigation menu.

There are two ways to connect the button to a menu.

  1. Create a view for the navigation menu, for example Navigation/Menu.
  2. Open Page Configuration and add a docked view on the left (or right) side of the page (or under Shared Settings for every page):
    • View: the navigation view.
    • Dock ID: an id, for example nav.
    • Display: onDemand.
    • Handle: hide.
    • Content: cover (the menu floats over the page) or push.
  3. On the Top Bar, set bindNavMenuToDock to true and navDock to the Dock ID (nav).

The button now opens and closes the dock, and it is highlighted while the dock is open — also when the dock is opened or closed from a script. Like the other menus, the dock closes on Escape and on a click outside the dock and the Top Bar.

When bindNavMenuToDock is false, clicking the button only toggles the navMenuButtonPressed property. Bind something to that property, for example a property change script that calls system.perspective.openDock / system.perspective.closeDock, or the visibility of an embedded view.

With autocloseNavMenu set to true (default), the menu closes automatically when the page changes, so the operator returns to the page after choosing a destination.

Name Description Property Type
navMenuButtonPressed Whether the navigation menu is open. Written by the Top Bar when the button is clicked. When bindNavMenuToDock is true it follows the dock and is not read as input. value
bindNavMenuToDock Open and close a docked view with the button, and highlight the button while the dock is open. value
navDock Dock ID, from the Page Configuration, of the dock to open. Only shown when bindNavMenuToDock is true. value
autocloseNavMenu Close the navigation menu when the page changes. Default true. value

Alert menu

The Top Bar reads alarms from the gateway alarm system directly; no binding is needed. It updates like the Alert List: within a fraction of a second for the gateway’s own alarms, and within a second for alarms from remote tag providers. Alarms are shown in two places:

  • The alert message in the middle of the bar shows the most important active alarm: its icon, title, description and activation time. If the operator may acknowledge it, an ACK button is shown next to it.
  • The alert button is a global counter: one badge per alarm priority, then the bell and the total. See The Alert Button.

Clicking the alert button or the alert message opens the Alert Menu. While the alert message is shown, the menu opens right under it, the same width as the message; otherwise it opens under the alert button, kept inside the window on narrow screens. It lists alarms with the most recent first (alarms that became active at the same moment are sorted by priority), in two tabs: Unacked and Active. Unacked lists the alarms still waiting for acknowledgement, cleared ones included; Active lists the active alarms and leaves out the cleared, unacknowledged ones. Expand a row (˅) to see more of the alarm. At the bottom of the menu:

Button What it does
ACK visible Acknowledges every alarm listed in the menu that can be acknowledged. Hidden when allowAlertAcknowledge is false or no listed alarm can be acknowledged.
Silence Fires the onAlertSilenceClick event. Silencing the audible alarm is done by your script. Hidden when showAlertSilenceButton is false.
Alerts › Navigates to the page in alertPath (default /alarms), typically a page with the Alert List Page component, and closes the menu. Hidden when showAlertListButton is false.

Use the filter property to select alarms on the gateway, in the same way as the Alarm Status Table:

  • filter.states — which alarm states to include. By default active and cleared unacknowledged alarms and active acknowledged alarms are included; cleared and acknowledged alarms are not.
  • filter.priorities — which priorities to include. Diagnostic is excluded by default.
  • filter.conditions — source, displayPath and provider filters. Separate several values with commas; * is a wildcard.

maxAlerts (default 50) limits how many alarms are sent to the menu; the newest are kept. The alert button still counts every alarm that matches the filter.

By default the alert button is a global counter: one badge per alarm priority — critical, high, medium and low — then the bell and the total. A priority without alarms has no badge. counterType picks how the badges are drawn:

  • badges (default) — the count inside a badge filled with the priority colour.
  • alert-level — the priority shape with the count beside it, as the OpenBridge 6.0 top bar drew it.

Alert button as a global counter with the priority shapes, a stopwatch badge for the shelved alarms, the bell and the total

counterFilter picks which counts are shown. The total is the sum of the priorities shown, so a priority switched off here is neither drawn nor counted, even when filter.priorities lets it through to the alert message and the menu. Diagnostic alarms are off by default, like filter.priorities.diagnostic. counterFilter.shelved adds the number of shelved alarms after the priorities, as a neutral badge with a stopwatch icon. Shelved alarms are counted on their own: they are never in the total, and they do not appear in the alert message or in the menu.

The global counter does not blink. With globalCounter set to false the button shows the bell and the number of alarms only, coloured by the highest priority, and blinks while there are unacknowledged alarms — the alert button of earlier releases.

Acknowledge is allowed when both canAcknowledge and allowAlertAcknowledge are true. canAcknowledge is also checked on the gateway, so it is the property to bind to a role or security check. alertConvention decides which alarms can be acknowledged:

  • levels — every unacknowledged alarm can be acknowledged.
  • bam — follows BAM (Bridge Alert Management): only alarms, cautions and level alerts can be acknowledged.

titleSource and descriptionSource select which alarm field (label, name, notes or displayPath) is used as the title and description, both in the alert message and in the menu. dateFormat sets how times are formatted, and showTimeInUtc shows them in UTC instead of the workstation time zone.

Name Description Property Type
showAlerts Show the alert message in the middle of the Top Bar. Default true. value
showAlertsButton Show the alert button. Default true. value
globalCounter Show the alert button as a global counter: one badge per priority, then the bell and the total. Default true. value
counterType How the global counter draws each priority: badges or alert-level. Default badges. value
counterFilter Which counts the global counter shows. See below. object
showAlertListButton Show the Alerts › button in the menu. Default true. value
showAlertSilenceButton Show the Silence button in the menu, which fires onAlertSilenceClick. Default true. value
allowAlertAcknowledge Show the ACK and ACK visible buttons. Default true. value
canAcknowledge Whether the operator may acknowledge alarms from this component. When false, acknowledge is hidden and the gateway rejects acknowledge requests. Default true. value
alertConvention Which alarms can be acknowledged: levels or bam. Default levels. value
alertPath Page the Alerts › button navigates to. Default /alarms. value
titleSource Alarm field used as the title: label, name, notes or displayPath. Default label. value
descriptionSource Alarm field used as the description. Default notes. value
dateFormat Format of alarm times, for example DD/MM/YYYY HH:mm:ss. Use HH for 24-hour time and hh with a for 12-hour time. value
showTimeInUtc Show alarm times in UTC instead of the local time zone. Default false. value
maxAlerts Most alarms sent to the menu. Default 50, at most 1000. Large values slow down the client. value
filter Gateway-side alarm filter. See below. object

filter sub-properties:

Name Description Property Type
states.activeUnacked Include active, unacknowledged alarms. Default true. value
states.activeAcked Include active, acknowledged alarms. Default true. value
states.clearUnacked Include cleared, unacknowledged alarms. Default true. value
states.clearAcked Include cleared, acknowledged alarms. Default false. value
priorities.diagnostic Include diagnostic alarms. Default false. value
priorities.low Include low alarms. Default true. value
priorities.medium Include medium alarms. Default true. value
priorities.high Include high alarms. Default true. value
priorities.critical Include critical alarms. Default true. value
conditions.source Alarm source path filter. Comma-separated, * wildcard. Default *. value
conditions.displayPath Display path filter (falls back to source path). Comma-separated, * wildcard. Default *. value
conditions.provider Alarm provider filter. Comma-separated. Empty means all providers. value

counterFilter sub-properties:

Name Description Property Type
critical Show the number of critical alarms. Default true. value
high Show the number of high alarms. Default true. value
medium Show the number of medium alarms. Default true. value
low Show the number of low alarms. Default true. value
diagnostic Show the number of diagnostic alarms. Default false. value
shelved Show the number of shelved alarms after the priorities, with a stopwatch icon. Never in the total. Default false. value

Diagnostics menu

Diagnostics are the alarms of priority Diagnostic: a signal in manual or simulated mode, a sensor due for calibration, an alarm blocked in the PLC. They are usually kept out of the alert button, so filter.priorities.diagnostic is false by default. With showDiagnosticButton set to true, the Top Bar shows a diagnostic button right after the alert button: a six-armed asterisk with the number of diagnostic alarms. The button never blinks.

The diagnostic alarms are read from the gateway alarm system like the alert button’s alarms, with the same filter.states and filter.conditions, and the priority fixed to Diagnostic whatever filter.priorities.diagnostic says. So the diagnostic button counts the diagnostic alarms whether or not they also appear in the alert button; maxAlerts limits how many are sent to the menu.

Clicking the button opens the Diagnostics Menu under it: one row per diagnostic alarm, newest first, with its title, description, day and time and an ACK button while the alarm can be acknowledged. Expand a row (˅) to see more of the alarm. At the bottom of the menu:

Button What it does
ACK all visible Acknowledges every diagnostic alarm listed in the menu that can be acknowledged. Hidden when allowAlertAcknowledge is false; disabled when nothing can be acknowledged.
Diagnostics list Navigates to the page in diagnosticPath (default /diagnostics), typically a page with an Alert List Page component filtered to diagnostics, and closes the menu. Hidden when showDiagnosticListButton is false.

Acknowledging follows the same rules as the Alert Menu: canAcknowledge, allowAlertAcknowledge and alertConvention. Under the bam convention diagnostic alarms cannot be acknowledged at all, so the menu shows no ACK buttons. titleSource, descriptionSource, dateFormat and showTimeInUtc apply to the rows as they do to the alert message and menu.

Name Description Property Type
showDiagnosticButton Show the diagnostic button after the alert button. Default false. value
diagnosticPath Page the Diagnostics list button navigates to. Default /diagnostics. Only shown when showDiagnosticButton is true. value
showDiagnosticListButton Show the Diagnostics list button in the menu. Default true. Only shown when showDiagnosticButton is true. value

Brilliance menu

The dimming button opens the Brilliance Menu, where the operator chooses the OpenBridge palette for the whole session:

  • Day/Night — steps between the bright, day, dusk and night palettes. The choice is written to the palette property and applied to every OpenBridge component in the session immediately.
  • Brilliance — a brightness slider, shown when showBrightness is true. The value (0–100) is written to the brightness property. The Top Bar does not dim the screen itself; bind brightness to whatever controls the display.

Top Bar in the night palette

To keep the Ignition theme (session.props.theme) in step with the palette:

  1. Set useIgnitionTheme to true.
  2. Bind theme bidirectionally to session.props.theme.
  3. Adjust palletteToTheme if your project uses other theme names.

When the operator selects a palette, the Top Bar writes the matching theme. When the theme changes from elsewhere, the Top Bar picks a matching palette (day before dusk before bright before night, when several palettes map to the same theme).

Name Description Property Type
showBrillianceMenu Show the dimming button and apply palette to the session. Default true. value
palette Current palette: bright, day, dusk or night. Default day. value
showBrightness Show the brightness slider in the menu. Default false. value
brightness Brightness selected in the menu, 0–100. Default 100. value
useIgnitionTheme Keep theme in step with palette. Default false. value
theme Ignition theme. Bind to session.props.theme. Only shown when useIgnitionTheme is true. value
palletteToTheme Which Ignition theme each palette maps to. Default bright/day → light, dusk/night → dark. object

Signed out Signed in
User menu, signed out User menu, signed in

Set showUserButton to true to show the user button. It opens the User Menu, which shows a Sign in button when isLoggedIn is false, and the user’s name, initials and a Sign out button when isLoggedIn is true.

Bind the properties to the session:

  • isLoggedIn → session.props.auth.authenticated
  • userFullName → session.props.auth.user.userName (or a full-name field from your identity provider). The initials are made from the first and last word of the name.

What happens on Sign in / Sign out is decided by bindUserButtonToAuth:

  • true — the Top Bar signs in and out directly, with the same authentication as the Login and Logout actions. The events below still fire.
  • false — only the onSignInClick and onSignOutClick events fire, and you handle them in a script, for instance with system.perspective.login() and system.perspective.logout().

Sign-in redirects to the identity provider and has no effect in the Designer.

Name Description Property Type
showUserButton Show the user button and its menu. Default false. value
bindUserButtonToAuth Sign in and out directly from the menu. Default false. value
isLoggedIn Whether a user is signed in. Selects which view of the menu is shown. Default false. value
userFullName Name of the signed-in user. Only shown when isLoggedIn is true. value

Apps button pressed

Set showAppsButton to true to show the apps button (the 3×3 grid). The Top Bar does not include an apps menu: clicking the button toggles appsButtonPressed, and the button is highlighted while it is true. Bind the property to open your own launcher, for example the visibility of an embedded view, a popup, or a dock. Set appsButtonPressed back to false from your script when the launcher closes.

Name Description Property Type
showAppsButton Show the apps button. Default false. value
appsButtonPressed Whether the apps button is pressed. Toggled on each click. Only shown when showAppsButton is true. value

Top Bar with the asset picker after the page name, showing Merd B

Set hasAssetPicker to true to show the asset picker after the page name, for pages that show one of several assets — a cage, a vessel, an engine. It is a dropdown button whose label is the selected asset. Clicking it lists the assets in assets; picking one writes its key to selectedAssetKey. The Top Bar only holds the selection: bind selectedAssetKey bidirectionally to a session or view property, and let that property decide what the page shows.

assets is a list of objects with a label (the text shown) and a key (the value written to selectedAssetKey). Add them in the property editor, or bind the list to a query or a tag to build it at runtime. Keys may be text or numbers; a pick writes the key back as it is in assets, so a numeric key stays a number. While selectedAssetKey is empty or matches no asset, the picker shows the first asset.

The picker has no breakpoint: it stays visible on narrow screens.

Note: As with the Dropdown Button, the list does not open in the Designer, not even in Preview Mode: the Designer’s built-in browser cannot show this kind of list. Try it in a session. To choose what the picker shows in the Designer, set selectedAssetKey in the property editor.

Name Description Property Type
hasAssetPicker Show the asset picker. Default false. value
selectedAssetKey Key of the asset the picker shows; empty or unmatched, the first asset. Written by the Top Bar when the operator picks another. Only shown when hasAssetPicker is true. value
assets The assets the picker lists, each with a label and a key. Empty by default. Only shown when hasAssetPicker is true. array

Set showInCommand to true to show the command button next to the page name. inCommand selects whether it shows this workstation as in command. The button is an indicator only; clicking it does nothing.

Name Description Property Type
showInCommand Show the command button. Default false. value
inCommand Whether the workstation is in command. Only shown when showInCommand is true. value

The clock at the far right shows the current time, updated by the client. It is display-only: it has no hover or press state and does nothing when clicked.

Name Description Property Type
showClock Show the clock. Default true. value
showTimezone Show the time zone after the time. Default true. value
utcHourOffset Time zone of the clock, in hours from UTC. Default 0. value

Each element but the asset picker has a breakpoint: when the browser window (not the component) is narrower than the value in pixels, the element is hidden. Set a breakpoint to 0 to always show the element.

1280 px 480 px
Top Bar at 1280 px Top Bar at 480 px

When the window is narrower than the dimming or apps button’s breakpoint, a ⋮ button appears at the right. It opens a menu with the hidden Dimming, Apps and User buttons; choosing one does what the button does. The ⋮ button only appears below the dimming or apps breakpoint, so keep userButtonBreakpointPx at or below the larger of those two — otherwise there is a width range where the user button is hidden and nothing reaches it.

Name Description Property Type
appIconBreakpointPx Hide the app icon below this width. Default 500. value
appTitleBreakpointPx Hide the app name below this width. Default 500. value
dimmingButtonBreakpointPx Hide the dimming button below this width. Default 500. value
userButtonBreakpointPx Hide the user button below this width. Default 500. value
appsButtonBreakpointPx Hide the apps button below this width. Default 500. value
alertMessageBreakpointPx Hide the alert message below this width. The alert button still opens the Alert Menu. Default 500. value

Properties not covered in the sections above:

Name Description Property Type
appName Name of the application. Default App. value
pageName Name of the current page, shown in bold. Default Page. Bind it to the page, for example with an expression on page.props.path. value
hasAppIcon Show the app icon. Default false. value
appIcon Icon shown before the app name, chosen with the icon picker. Only shown when hasAppIcon is true. value
style Standard Perspective style object. object
Event Description Event Object
onSignInClick Fired when the operator clicks Sign in in the User Menu. —
onSignOutClick Fired when the operator clicks Sign out in the User Menu. —
onAlertSilenceClick Fired when the operator clicks Silence in the Alert Menu. —

The event objects are empty. The User Menu of the Top Bar has no user name and password fields, so onSignInClick carries no username or password, unlike the onSignedInClick event of the User Menu component.

  1. Create a view Framework/TopBar with a flex container root, and add a Top Bar with position.grow = 1.

  2. In Page Configuration → Shared Settings, add a top dock: View Framework/TopBar, Display visible, Size 48, Content push, Handle hide.

  3. Add a left dock with Dock ID nav, your navigation view, Display onDemand, Handle hide, Content cover.

  4. On the Top Bar set:

    Property Value
    appName Engine
    bindNavMenuToDock true
    navDock nav
    alertPath /alarms
    showUserButton true
    bindUserButtonToAuth true
  5. Bind pageName to the current page and isLoggedIn/userFullName to session.props.auth.

On the Top Bar, configure the onAlertSilenceClick event with a script action:

def runAction(self, event):
system.tag.writeBlocking(['[default]Bridge/Horn/Silence'], [True])

Set useIgnitionTheme to true, then bind theme bidirectionally to session.props.theme. Selecting Night in the Brilliance Menu now also switches the Ignition theme to dark, and switching the theme to light from a script selects the Day palette.

Built on the OpenBridge Design System