The Utility Pages module provides a framework for rendering and protecting utility pages served up from experience designer.

Methods

register

This method registers a utility page which will then appears as an option on the main utility page listing (see Landing Page).

Parameters:

• name (string): The name of the utility being registered.

• path (string): The path to the landing page for the utility.

• description (string): A description of the utility.

Returns: Nothing.

getAll

This method retrieves all registered utilities in the system.

Returns: An array of all registered utility pages.

guard

This method should be used by every page and endpoint in a utility to ensure that only authenticated users are able to access the utility page and its resources.

Parameters:

• msg (object): The Node-RED msg object.

• apiContext (boolean): True indicates the request being authenticated is in the context of a REST API, which will result in a JSON response in the event of an authentication failure. False indicates a page request, which will result in a redirect to the Login Page if the user is not properly authenticated.

Returns: A promise that will be resolved when the user has been successfully authenticated. Note in the event of an authentication failure, the response is handled directly by this method.

render

Used to render a utility page using the standard utility page layout.

Parameters:

• msg (object): The Node-RED msg object.

• fullWidth (boolean, default = false): Whether or not the utility page should fill the full page-width.

• showLogout (boolean, default = true): Whether or not the show the “Hello [name]!” and logout link.

• showUtilitiesLink (boolean, default = true): Whether or not to display the link to the main utilities listing in the header.

Returns: Nothing, the response is handled directly by this method.

Notes: The layout utilizes the following properties in msg.payload:

• content (string): The HTML for the utility page.

• title (string): The title for the utility page.

• inlineScript (string): Inline JavaScript to include in a script tag on the rendered page.

• additionalScripts (array of strings): An array of URLs of additional scripts to include (via script tags).

• additionalCSS (array of strings): An array of URLs for additional CSS files to include (via link tags)

Layout

Any pages rendered using the Utility Pages module will use a standard Bootstrap-based layout. Vue.js is also included by default on this layout. The layout governs the header containing the breadcrumb, user greeting and logout link.

Utility Functions

The utility page layout includes the following utility functions:

namespace

A utility function for setting a value at a particular namespace path in the global scope.

Parameters:

• namespace (string): The dot syntax namespace path.

• value (any): The value for the established namespace.

Login Page

The following login page is presented when a user tries to access a protected utility page. Authentication occurs using standard Orbita authentication (no particular roles required).

Open

Landing Page

The module includes a main landing page which lists all available utility pages.

The URL of the landing page will be:

Open