Skip to main content
Version: 8.1

Component Events and Actions

Inductive University

Events and Actions

Watch the video

In Perspective, events and actions are some of the fundamental building blocks of project functionality. Actions give you the ability to respond to specific user inputs (such as mouse, keyboard, and touch inputs), as well as broad session events (like the beginning and end of the session) in many different ways. Thus, actions are a response to events.

Example uses for events and actions include:

  • Navigating to a new page when the user presses a button.
  • Opening a popup containing details on a specific PLC when a user double-clicks on it in a diagram.
  • Logging the user out of the session when they press Ctrl + L on the keyboard.
  • Scanning a barcode from a mobile device, and sending it to the Gateway.

In this section, we'll cover the basics on how to configure actions and events to suit your project's needs.

Configure Events and Actions​

To configure an event and action on a component:

  1. Select the component.

  2. Right-click on the component, and select Configure Events.

  3. Choose an event from the left-hand side.

    note

    You can configure actions for as many events as you'd like, but you'll need to configure the actions separately for each one.

  4. Next choose one or more actions to associate with the event, by clicking the Add icon. Descriptions of the options for each component action are described in the sections on this page.

  5. Configure the actions as you want. Click OK.

Perspective Events​

Perspective offers a wide range of possible events, but in this section we'll highlight a few common ones. You can find details on all configurable events at Perspective Event Types Reference.

Event TypeExample Event
Component EventMany components have their own events that are related directly to the functionality of the component. For a full list of components with configurable component events, see Perspective Event Types Reference.
System Event
  • onStartup events occur when the View or component is loaded into the session. For example, if you configure an onStartup event on a component, the event will occur when the view it is on is opened.
  • onShutdown events occur when the View or component is removed from the session. Typically this will occur when you navigate away from the View containing the component, or if the session times out.
Mouse Event
  • onClick events occur when the user clicks on any of their mouse's buttons, while the cursor is hovered over the component.
  • onContextMenu events occur when the user clicks the mouse button associated with a context menu (typically the right mouse button, on a two-button mouse).
  • onMouseOver events occur when the mouse pointer enters the component's borders.
Keyboard Event
  • onKeyUp events occur when a key on the keyboard is released, while the component is focused.
  • onKeyPress events will be run repeatedly, while a key is held down and the component is focused.
Touch Event
  • onTouchStart Fired when the user has touched the surface of a touch capable device.
Wheel Event
  • onWheel events occur when a user moves the scroll wheel while hovered over the component.

Action Types​

Each Event can have actions assigned to them, and each Action has some specific purpose. Each event can have any number of actions, and different types of actions can do different things.

If you want to delete an action, use the Delete icon.

Each Action is called in order from top to bottom. To control this execution order, you can reorder the list of Actions using the Up Arrow and Down Arrow icons next to the list. However, Actions are not executed synchronously: sequential actions do not wait for any prior Actions to finish executing before running. Thus, if Action 1 is a long-running script, while Action 2 is quick to finish, it is possible that Action 2 will finish before Action 1.

Shared Action Options​

The bottom of each action lists a set of options. The options listed in the following table are shared across different action types.

OptionDescription
EnabledSpecifies whether the action should be used or ignored.
Prevent DefaultPrevents the browser's default behavior from occurring. Useful when you want to prevent the browser's built-in right-click menu from showing.
Stop PropagationPrevents events from higher up in the component hierarchy from triggering when the selected event triggers.
Security SettingsOpens a panel where you can specify required security levels that must be present for the action to trigger.

Action Setting Reference​

The following headings detail unique settings for each action type. Shared options for each action are listed under Shared Action Options.

Accelerometer Action​

Retrieves accelerometer data from the device's accelerometer (a common feature on smartphones). This is a Perspective App Action, designed to help in gathering data from a mobile device. Each action needs to be configured in two parts:

  1. The action is run on a mobile device, indicating that a type of data should begin to be gathered.
  2. As the data is gathered, or once it's finished being gathered, it is sent to the Gateway to be handled by the corresponding Session Event.
note

This action is designed specifically for the Ignition Perspective App for Android and iOS devices. If it is run in a browser session, it will be ignored.

Action SettingDescription
ContinuousBegins recording accelerometer data, which repeatedly updates the accelerometer object in the current session's Session Properties.
  • Sample Rate indicates how often the accelerometer object should be updated.
  • Context provides the opportunity to pass a custom object through to the Accelerometer Data Received Session Event. A session object is already provided to that event script.
BatchRecords accelerometer data at a specified interval for a specified rate, then sends the accumulated data to the Gateway, to be handled by the Accelerometer Data Received Session Event.
  • Sample Rate indicates how often a reading should be made.
  • Duration specifies for how long data should be logged.
  • Context provides the opportunity to pass a custom object through to the Accelerometer Data Received Session Event.

    Note: A session object is already provided to that event script.
OffTurns off accelerometer data recording.

Alter Logging Action​

Perspective sessions log their session activity and errors to the logs of the browser they run in. Alter Logging allows us to change how verbose this logging is. This is useful for session debugging.

Action SettingDescription
Remote Logging EnabledIndicates whether the browser logs should also be sent to the Gateway to log in the Gateway logs.

Note: For all messages to be visible, the Perpective.Client logger must be set to the same logging level as the level indicated in this action.
Set Logging LevelDictates how verbose the session's logging should be. A logging level of all (or trace) shows all possible records, while a level of off shows none. Options are:
  • all
  • trace
  • debug
  • info
  • warn
  • error
  • fatal
  • off

Alter Dock​

New in 8.1.19
Allows you to alter the configuration of a docked view. Any action settings left blank will remain unchanged.
Action SettingDescription
ViewThe currently selected view. Changing this will change which view is mounted to this position.
DisplayThis property allows you to show or hide the docked view.
  • visible: The docked view is always expanded/displayed.
  • onDemand: The docked view is collapsed, but allows the user to display the view by clicking on the docked view's handle.
  • auto: Automatically shows or hides the docked view depending on how much space is available in the session: showing the view if the page is wider than the width specified in the auto-breakpoint setting. (Works in conjunction with the Auto Breakpoint property).
Resizable?Determines whether the docked view may be resized or not.
Modal?Determines if the view should be modal, meaning users will not be able to directly interact with other views while the modal view is present. This property is only enabled when the Display property is set to onDemand.
ContentDetermines how the docked view interacts with other views on the page.
  • push: Opening or closing the docked view causes the content in the center to resize: the center view will be 'pushed' out of the way.
  • cover: When opening the dock, it slides in front of the center view, obscuring part of the center view: the dock will 'cover' part of the center view.
  • auto: Acts like the cover option when the viewport is smaller than the Auto Breakpoint value. Acts like the push option when the viewport is larger than the Auto Breakpoint value.
AnchorAllows you to make a view always visible while scrolling. Only available on North docked view configurations.
  • fixed: The docked view will remain in a fixed position, relative to the page. Useful when a north-docked view should stay at the top of a page. Select this option if a docked view is acting as a header that should always be present.
  • scrollable: The docked view will not stay in a fixed position as the user scrolls down in the page. Select this option if the north dock should move along with the page as the user scroll down.
SizeDetermines the size, in pixels, of the view.
  • If the view is docked to the North or South edge, then size determines the height.
  • If the view is docked to the East or West edge, then size determines the width.
Auto BreakpointControls the minimum page width for Auto docked views to be visible. When the session is smaller than this width, these views will be hidden and able to be displayed on demand.This property is enabled when the Display property is set to auto.
Dock IDAn optional arbitrary string that can be used to reference a docked view through other parts of Perspective such as in an action or as a scripting call.
HandleAllows you to show or hide a handle for users to expand/collapse the view.
  • Show: Show handle at all times.
  • Hide: Hide handle at all times.
  • AutoHide: Hide handle when page is not active.
Handle IconPath to an icon used to identify the view when the view is hidden.
View ParametersAllows specific parameter values to be passed to the docked view when navigating to the page.

Dock Action​

Allows you to open or close a docked view. The view must be configured as docked in the Page Configuration section of the designer, and must be configured with a dock ID.

Action SettingDescription
Dock ActionThere are three types of dock actions:
  • Open: Opens the docked view.
  • Close: Closes the docked view.
  • Toggle: Toggles the state of the docked view, so opens the view if it currently closed, or closes it when it is currently open.
IdentifierThe ID of the docked view. Dock ID values can be set when you configure a view as docked.
ParametersParameters that can be passed into the docked view. The name of the parameters must match the name of the view parameters that are already set up.

Fullscreen Action​

Enters full screen mode. Requesting to enter full screen mode only works with events that originate from user interactions. Some browsers may not support full screen requests.

Action SettingDescription
EnterEnters full screen mode.
ExitExits full screen mode.
ToggleChanges the Session's browser to whichever mode it is not currently in.
ViewEnters full screen mode on a targeted view.
PageEnters full screen mode on a targeted page.

Login and Logout Actions​

Logs the current user in or out of the session. The only action property is the Enabled option which specifies whether the action should be used or ignored.

Action SettingDescription
Ask the IdP to re-authenticate usersDetermines how re-authentication requests sent to the Identity Provider will be handled. Identity Providers can choose to ignore re-authentication requests, defaulting to their own behavior. Options are as follows:
  • Project - Use the re-authentication setting located in the General category of Project Properties.
  • Enable - Prompt the user to provide their credentials, even if they're already logged into the session.
  • Disable - When selected, the user will not have to provide their credentials if they're already logged in.

Authentication Challenge Action​

New in 8.1.16

The Authentication Challenge action will navigate the user to an IdP, allowing a different user to authenticate against an IdP without logging out the currently logged in user. After the user successfully logs in, the IdP navigates them back to Perspective and triggers a session event onAuthChallengeCompleted with contextual information about this second user’s identity and their security levels. The session's authentication state will remain unchanged — in other words, the second user will only be logged in as the user executing the session’s onAuthChallengeCompleted event handler script. This provides the opportunity for workflows that include requiring a supervisor's "e-signature" before performing certain actions.

note

The second user will not be logged into the IdP or remembered in any way by the IdP when the IdP is an internal Ignition type, since the internal Ignition IdP is aware of “sessionless” authentication challenges. External IdP types (OIDC and SAML) are not aware of “sessionless” authentication challenges since there is no such concept in the respective open standards. To work around this, a separate IdP tailored specifically for the secondary users’ authentication challenges may be specified under the Identity Provider action setting. So long as this special IdP is only used for these secondary user authentication challenges (and not used anywhere else), and so long as the Ask the IdP to re-authenticate users setting is enabled, secondary users should always be required to provide their credentials every time an authentication challenge is triggered.

Action SettingDescription
Identity ProviderSpecifies the IdP to authenticate against. This may be different from the project's IdP. If set to None, the project default IdP is used.
Ask the IdP to re-authenticate usersDetermines how re-authentication requests sent to the Identity Provider will be handled. Identity Providers can choose to ignore re-authentication requests, defaulting to their own behavior. Options are as follows:
  • Project - Use the re-authentication setting located in the General category of Project Properties.
  • Enable - Prompt the user to provide their credentials, even if they're already logged into the session.
  • Disable - When selected, the user will not have to provide their credentials if they're already logged in.
TimeoutAn integer representing the number of minutes the system will wait in between the authentication request and the authentication response before timing out the request. If set to zero, the default of two minutes will be used as the timeout.
PayloadAn opaque payload that may contain any information the user wants to pass to the Authentication Challenge Completed session event.
FramingHow the challenge should be presented to the user’s current page:
  • Same Tab / Window - User is navigated away from the client and to the IdP in the same window/tab. Once authentication is complete at the IdP, they are redirected back to the client.
  • New Tab / Window - A new tab is opened in the user’s browser, leaving the current client tab open while it waits for the new tab to complete the authentication challenge at the IdP.
  • Embedded Frame - The redirect to the IdP is embedded in an Iframe within the current client’s page.
Note: Mobile and workstation clients do not support “New Tab / Window” and will fall back to “Same Tab / Window”. Mobile clients do not support “Embedded Frame” and will fall back to “Same Tab / Window”.

The Navigation action allows you to navigate to different views, pages, or URLs from an event. The Navigation action has several modes. Each mode allows for a different type of navigation and different options. The following table lists the types of navigation:

TypeDescription
PageNavigates to a separate page.
  • Set Page: A string denoting the page URL of the target page. See Page URLs.
  • Open in new tab: Specifies whether the newly opened page should replace the current page, or open in a new browser tab.
ViewReplaces the current main View with a new main View. See View.
UrlNavigates to an external web address. See Url.
Browser
New in 8.1.5
Navigates either forward or backward using browser history. See Browser.

View​

SettingDescription
Select ViewThe path to the view that should be used.
ParametersA set oparameters to pass to the view. Add or remove parameters with the Add icon and Delete icon. In the Value field for a given parameter, you can pass in a path to a property value using the Parameter icon

Url​

SettingDescription
Enter UrlThe URL that the action should navigate to. Example: https://inductiveautomation.com/
Open in new tab:Specifies whether the newly opened page should replace the current page, or open in a new browser tab.

Browser​

SettingDescription
NavigateSpecifies whether to go forward or backwards in browser history when the action is triggered.
Prevent DefaultPrevents the browser's default behavior from occurring. Useful when you want to prevent the browser's built-in right-click menu from showing.
Stop PropagationPrevents events from higher up in the component hierarchy from triggering when the selected event triggers.

Request Print Action​

New in 8.1.28

Prints the contents of the page, view, or component. To print content using Perspective component methods instead, see Requesting Print.

Action SettingDescription
Select Print Target
  • Page: Print the contents of the page.
  • View: Print the contents of the view.
  • Component: Print the contents of the component.
Document TitleThe name of the save file.

Opens a view as a popup, or closes an existing popup.

Action SettingDescription
Popup Action
  • Open: Opens a view as a popup.
  • Close: Closes an existing popup.
  • Toggle: Opens a popup if it isn't open, and closes the popup if it is open.
Select ViewThe path to the view that should appear as a popup.
ParametersA set of parameters to pass to the view. Add or remove parameters with the Add icon and Delete icon. In the Value field for a given parameter, you can pass in a path to a property value using the Parameter icon.
IdentifierA string that specifies a unique popup identity. If you want to close an open popup from a popup action, you'll need to supply the identifier that was used to open it.
TitleA string of text to display in the titlebar. If omitted, no titlebar is used.
Show close buttonA boolean indicating if a Close Icon should be displayed on the popup.
DraggableA boolean indicating if the popup should be able to be dragged to new positions.
ResizableA boolean indicating if the popup is allowed to be resized.
ModalA boolean indicating if the popup should be modal, meaning it is the only view the user can interact with while open.
Background dismissibleA boolean indicating if the popup can be dismissed by clicking outside of it. This setting is only applied if the modal option is enabled. If omitted, defaults to false.
Position ExactExact Positioning controls where in the session the popup should appear, and how large it should be. If no specifications are given, the popup will open centered at its default size.
  • Top, Left, Bottom, and Right control how far the popup should be offset from each margin of the session.
  • Width and Height specify how large the popup should appear.
Position RelativeRelative Positioning enables the popup to be positioned based off of the mouse cursor position when used with a Mouse Event. The Circle icon in the center represents the mouse location. The arrows icons represent the location the popup will appear in relation to the user's mouse cursor. Click on an arrow to position the popup window.


Viewport Bound
New in 8.1.3
If selected then Popups will be "shifted" on open to always open within the bounds of the viewport. If the Popup would have been larger than the viewport then Popup will be resized to fit within the bounds. This setting also prevents a Popup from being dragged even partially off-screen.

Refresh Action​

Reloads the current browser tab.

Scan Barcode Action​

Allows the user to scan a single barcode on their mobile device, which is then sent to the Gateway and handled by the Barcode Scanned Session Event.

This is a Perspective App Action, designed to help in gathering data from a mobile device. Each action needs to be configured in two parts:

  1. The action is run on a mobile device, indicating that a type of data should begin to be gathered.
  2. As the data is gathered, or once it's finished being gathered, it is sent to the Gateway to be handled by the corresponding Session Event.
caution

This action is designed specifically for the Ignition Perspective App for Android and iOS devices. If it is run in a browser session, it will be ignored.

Action SettingDescription
Barcode TypeIndicates the format of the barcode to be scanned. Any can be used to catch all barcodes.
Barcode Background Color
New in 8.1.3
This option enables the reading of barcodes with light or dark backgrounds, or previously white barcodes with black backgrounds couldn't be read. Options are Light, Dark, or Auto.
ContextProvides the opportunity to pass a custom object through to the Barcode Scanned Session Event.

Note: A session object is already provided to that event script.

Scan Ndef NFC Action​

Allows the Perspective app to catch any scans by the phone using the NFC data exchange format (Ndef), which is then sent to the Gateway and handled by the NFC Ndef Scanned Session Event. This suppresses any default behavior of the phone in catching the scan.

caution

This action is designed specifically for the Ignition Perspective App for Android and iOS devices. If it is run in a browser session, it will be ignored.

Action PropertyDescription
Single ModeListens for a single NDEF scan to send.
Continuous ModeListens indefinitely for NDEF scans, which are sent to the gateway as they are received.
Off ModeTurns off listening for NDEF scans.

Script Action​

Write a script that happens on the event specified. See Perspective Component Methods and system.perspective Functions for more details on how to configure script actions.

Script actions contain a built-in "event" object, that further contains values pertaining to the underlying event. These values and descriptions are displayed in the docstring.

Theme Action​

Changes the theme for the session.

Action SettingDescription
Select ThemeTheme that will be used, for example dark, light, light-cool etc. Dropdown list of all available themes.

Workstation Mode Action​

note

This action will only take effect if called from a Session running in Workstation.

New in 8.1.0
When called from a session running in Perspective Workstation, changes the mode of workstation from Windowed Mode to Kiosk Mode.
Action SettingDescription
WindowedEnters Windowed Mode.
KioskEnters Kiosk Mode
ToggleToggles the current mode between Windowed and Kiosk.