NiagaraMods Domo

Version 1.0 Beta #4

Domo is a module that allows you to completely customize the Niagara web login screen. Domo adds three new Login Templates to the Niagara WebService. Two of them are completely redesigned login experiences ready to go out of the box. The third allows you provide your own custom HTML, JavaScript, CSS and images to build a login screen from scratch.

Domo is currently in beta and has a limited feature set. For more information on the limitations in this version, see the Beta Notes & Roadmap section below.

Installation

Domo supports Niagara 4.10 and later. For earlier versions of Niagara (4.6-4.9) use Domo 1.0.0 Beta #2

1. Extract the zip file and copy the nmxdomo-rt.jar file to your Niagara modules directory.

2. If Workbench is open, close it and relaunch.

3. If you are using this module on a local station, restart the station using the Application Director in your Platform.

4. If you are installing on a remote station, connect to the platform of the remote station. Then go to the Software Manager and install the nmxdomo-rt module to the remote station.

Usage

1. Connect to your station, then open the Property Sheet of your WebService component in Config > Services

2. Find the Login Template property, and uncheck null if it is checked.

3. In the first dropdown of the Login Template property, select nmxdomo

4. In the second dropdown of the Login Template property, select the template you wish to use.

5. If you select to use the DomoUserCustom template, you will need to provide a custom login theme to use in your station file system. For more details, see the Using Custom Themes section below

Change Log

Domo Beta #4 - March 22, 2024

• Fixes password reset bugs affecting Niagara 4.13

• Fixes an issue where the authentication scheme check would error when attempting to check the credentials of a user that does not exist

• Fixes an issue with Left Panel theme password strength test

• Password strength check algorithm changed to match Niagara's default more closely

Domo Beta #3 - February 14, 2024

• Adds support for Niagara 4.11+. Domo's new support matrix is 4.10-4.13+

• Two-factor authentication is now supported

• Password strength details and validation are now visible as users reset passwords

• Fixes issues with the password reset option in 4.10

Beta Notes & Roadmap

Important notes about this version

• KNOWN ISSUES (Last updated 03/22/2024)

  • There is an issue with Domo and Niagara 4.14 Beta with 2FA and password reset. We are working with Tridium to resolve the issue, hopefully before the official release of Niagara 4.14.

  • There is a bug in Firefox that prevents logins from working properly. This will be fixed in a future release

• Domo no longer supports versions of Niagara before 4.10, previous Domo beta releases may work with releases of Niagara before 4.10, however, NiagaraMods will not support or update these versions in the future

• Supported Auth Types - the built-in Domo templates and Domo JavaScript library only support digest authentication. This is the default authentication type for Niagara users. Single Sign-on (SSO) and other mechanisms for authentication are supported in Niagara are not supported in Domo. You can write this support yourself in your theme if you are using the DomoUserCustom template and providing your own HTML and JavaScript.

• Localization - the built-in Domo templates do not support Lexicons or localization. We plan to build this support in to a future version. In the meantime, you can localize your own DomoUserCustom template using the theme files for the two built-in templates that are included with the package download.

Built-in Templates

The two built-in templates, DomoLeftPane and DomoFloatingCard provide a simple login interface with beautiful fullscreen wallpapers from Unsplash.com. Both templates are fully responsive and will look great on desktop browsers and mobile phones.

Left Pane

Provides a split login pane with a random full art background image from Unsplash. This background image will change every time a user visits the page, or you can set a custom image to be used all the time.

Floating Card

Provides a centered floating card in the middle of the screen with a full art background image from Unsplash. This background image will change every time a user visits the page, or you can set a custom image to be used all the time.

Customizing the Built-in Templates

Both built-in templates work with the two custom WebService slots that Niagara provides to specify a logo image and a CSS styles. In addition to these two slots, you can further customize the login experience with the slot list below. Just add the slot to the WebService component using the Slot Name below and set the value if one is required.

Using Custom Themes

You can find custom themes to download on the NiagaraMods Exchange under the domo tag.

You can use your own, completely custom HTML, JavaScript, CSS, and image files to build a login page from scratch. To activate the custom page, choose the DomoUserCustom as the Login Template for the WebService and place your custom theme's files in a folder named domo in the root of your station file system at Ord file:^domo/.

For details on building a custom theme, see the Building Custom Themes section below.

Security Notes

Public/Unauthorized Access to Domo Files

When a Domo Login Template is enabled, Domo will serve files in the domo directory of your station file system publicly at the URL login?domo/filname.ext. Domo will only respond to requests for files that exist in the domo directory of your station file system. No other data will be served. Do not put a file in the domo directory unless you want it to be publicly accessible for a login screen.

Web Filtering and Outbound Firewalls

Domo connects to the server unsplash.niagaramodules.com over HTTP/S to fetch randomized wallpapers from the Unsplash API. The images are then downloaded from images.unsplash.com. Ensure that both of these hosts are accessible from your end users' networks/web browsers. This is only necessary if you wish to use Unsplash images as wallpapers. Domo does not cause your Niagara station to hit these end points, they are hit in the end-user's web browser. Domo does not issue any requests over the internet from your station.

WebService Content Security Settings

In Niagara 4.10 and later, the default content security policies of the WebService are more strict. To utilize files loaded from the internet - including the custom fonts, animations, and Unsplash images that are used in Domo themes, you will need to add update your Content Security Policies in the Niagara WebService.

Open the WebService property sheet at Services > WebServices and expand the HTTP Header Providers > Content Security Policy tree. Find the properies listed below and add the corresponding host names. Do not include http or https in these entires. If values already exist in these properies, move to the end and add a space before adding the new value.

Animations

Animations in Domo are powered by animate.css, Domo themes load the animate.css library over the internet from the CloudFlare content delivery network. If you wish to enable animations:

• In the style-src property add cdnjs.cloudflare.com - this allows the station to reach out to the CDN service to retrieve animate.css.

Unsplash

Domo provides keyword based random background images using the Unsplash API and Unsplash content delivery network. If you wish to enable Unsplash images:

• In the connect-src property, add unsplash.niagaramodules.com - this allows Domo to reach out to the NiagaraMods Unsplash API provider to search for free images on Unsplash and load them randomly based on keyword

• In the img-src property, add images.unsplash.com - this allows Domo to load images from the Unsplash image hosting content delivery network

Custom Fonts

Some themes use custom fonts hosted by Google Fonts. To enable their use:

• In the font-src property, add fonts.gstatic.com. If the font-src property is completely empty, set it to 'self' workbench fonts.gstatic.com

• In the style-src property, add fonts.googleapis.com

Building Custom Themes

You can use your own, completely custom HTML, JavaScript, CSS, and image files to build a login page from scratch. To activate the custom page, choose the DomoUserCustom Login Template in the station WebService and add your custom files to a folder named domo in the root of the station file system.

This package file includes examples of the two built-in themes as well as a base template for starting a new custom theme.

Login Page (required)

The only required file for your theme is a login.hbs or login.html page. This file should exist in your station at the file:^domo/login.html or file:^domo/login.hbs ords.

Handlebars Templates

Domo uses Handlebars templates to insert data in to your page. This includes the customization slot values listed above in Customizing the Built-in Templates so you can allow users of your theme to customize it further.

• The login file will be parsed with Handlebars even if it has a .html file extension

• Domo does not support the use of partials, but does support Block Helpers including #if and #unless

• Domo uses handlebars.java to parse templates, for more details on supported features, see the documentation

Template Variables

Template variables can be accessed using the standard Handlebars syntax of {{variableName}}

Custom Template Variables

You can expose any additional WebService slots as custom template variables by including a file named custom.slots in the domo directory. The full Ord location is file:^domo/custom.slots. This file should contain a list of slot names you wish to make available as template variables. There should be one slot name per line. The following custom.slots example file will make the customSlot and Another$20Slot variables available in the template with the same values as the slots on the WebService. Two other Boolean variables named hasCustomSlot and hasAnother$20Slot will be created that can be used to check if the slot exists from template HBS/HTML files and from JavaScript.

custom.slots Example:

customSlot
Another Slot

Note the space in the second entry Another Slot will be converted to Slot Path syntax Another$20Slot – you must use Slot Path syntax when accessing the slot from your template.

<!-- Example Usage in Template -->
<h1>
  Custom Slot is: <b>{{customSlot}}</b>
</h1>

<!-- Check if slot exists in WebService before displaying its value -->
{{#if hasAnother$20Slot}}
  <h2>
    Another Slot is: <b>{{Another$20Slot}}</b>
  </h2>
{{/if}}

To verify or find out which slots and variables are included in the template you can print out the full list in a web browser's console with the following JavaScript:

console.log($domo.config);

Supporting Files

You can access other files in the domo directory from your template's HTML/HBS file using the /login?domo/filename.ext path. For example, if you have an image named logo.png in your station at the Ord file:^domo/logo.png you could display it in your Login HTML file like this:

<img src="/login?domo/logo.png">

Only files in the domo directory can be accessed this way. These are the only files from your station made available to users who have not logged in. Make sure you do not put any file in the domo directory unless you want it to be publicly accessible.

Niagara Logo and Login CSS

You can include the standard logo file and login css file specified in the WebService slots with the standard URLs used by Niagara:

Logo - /login/logo

Example

<img src="/login/logo">

Login CSS - login/loginCss

Example

<link rel="stylesheet" href="/login/loginCss" />

User Defined Custom Background Image

You can access the custom background slot in your HTML using the /login?image=background URL.

CSS Example

.background {
  background-image: url('/login?image=background');
}

HTML Image Tag Example

<img src="/login?image=background">

Domo JavaScript Library

The Domo JavaScript Library can be utilized in your custom login pages by including the following lines in the <head> tag in your HTML before any content or other external JavaScript files are loaded.

<script type="text/javascript" src="/login/core/auth.min.js"></script>
<script type="text/javascript" src="/login?domo.js"></script>

auth.min.js

This file is part of the base Niagara login system. It provides JavaScript functions utilized by the Domo JavaScript Library to log a user in to Niagara. It must be included before domo.js and is required for it to function properly.

login?domo.js

This script provides an API to interact with Domo and the Niagara login system. The API is accessed using the global $domo variable or window.$domo.

$domo.config

The domo configuration object. This object includes JavaScript variables for all Template Variables listed above in the Template Variables section. It will also include any custom slot you've defined in the custom.slots file. For more information see Custom Template Variables above.

// Example Configuration Object

window.$domo.config = {
  title: "station",
  primaryColor: "#2d8cf0",
  hasLoginCss: false,
  hasLogo: true,
  hasBackground: false,
  backgroundColor: "#2d8cf0",
  hasGradient: false,
  hasPageBackground: false,
  pageBackground: "",
  transparent: true,
  noUnsplash: false,
  unsplashSearch: "abstract",
  hideEula: false,
  hasError: false,
  hasPasswordReset: false,
  hasPasswordResetError: false,
  passwordResetObj: {
    digits: "at least 1 digit(s)",
    digitsNum: "1",
    length: "at least 10 character(s)",
    lengthNum: "10",
    lower: "at least 1 lower case character(s)",
    lowerNum: "1",
    resetError: "null",
    resetMessage: "You are required to reset your password before continuing.",
    resetTitle: "Password Reset",
    special: "at least 0 special character(s)",
    specialNum: "0",
    strength: "Your password must contain:",
    upper: "at least 1 upper case character(s)",
    upperNum: "1"
  },
  forgetUserId: false,
}

$domo.display(selector, value)

Sets the CSS display style for a given selector.

// Hide all elements with given class
$domo.display('.class-name', 'none');

// Show element for specific ID
$domo.display('#element-id', 'block');

$domo.login(options)

Attempt to login to Niagara with the given options:

// default options
options = {
  username: null,
  password: null,
  redirect: true,
  successCallback: null,
  failCallback: null,
  rememberUserId: true,
};

username <String>
The username submitted to Niagara login. If the value is null Domo will automatically look for an element with an id of username and attempt to use it's value as the username submitted for login.

password <String>
The password submitted to Niagara login. If the value is null Domo will automatically look for an element with an id of password and attempt to use it's value as the password submitted for login.

rememberUserId <Boolean>

Another way to control if Domo remembers the last successfully logged in user. This is overridden if the forgetUserId slot is set.

redirect <Boolean> or <Object>
Whether or not to redirect the user after a login attempt. If set to true, the user will be directed to the Niagara system after they've logged in or back to the login page if there is an error. If you set this to false, you should handle redirecting users manually in the success and fail callbacks.

You can pass an object if you wish handle redirects differently for success and failure. Below is an example:

redirect: {
  success: true,
  fail: false, // will be handled by callback
}

success <Function (url, response)>
Function called when a login is successful. Parameters are a URL to redirect the user to and the full response from the login service. This function may or may not be called if the redirect option is true due to the redirect happening immediately after a successful login.

fail <Function (url, error)>
Function called when a login fails. Parameters are a URL to redirect the user to and an error response from the login service. This function may or may not be called if the redirect option is true due to the redirect happening immediately after a failed login.

Login Examples

// If your input fields have 'username' and 'password' as their IDs
$domo.login();

// Using callbacks to redirect the user after additional JavaScript logic
$domo.login({
  redirect: false,
  successCallback: function(url, response) {
    alert('Login successful');
    location.href = url;
  },
  failCallback: function(url, error) {
    alert('Login error');
    location.href = url;
  },
});

// Using callbacks and only redirecting on success
$domo.login({
  redirect: {
    success: true,
    fail: false,
  },
  fail: function(url, error) {
    alert('Login error');
    location.href = url;
  },
});

$domo.check2FA(username)

Check a username to see if the user has two-factor authentication turned on.

username The username that you want to check for two-factor authentication.

Example

$domo.check2FA('UserWithout2FA');
// returns false -> user either doesn't exist, or two-factor authentication is off

$domo.check2FA('UserWith2FA')
// returns true -> user has two-factor authentication on

$domo.twoFactorLogin(options)

attempt to login to Niagara using two factor authentication with the following options:

// default options
options = {
  username: null,
  password: null,
  token: null,
  redirect: true,
  successCallback: null,
  failCallback: null,
  rememberUserId: true,
};

username The username submitted to Niagara login. If the value is null Domo will automatically look for an element with an id of username and attempt to use it's value as the username submitted for login.

password
The password submitted to Niagara login. If the value is null Domo will automatically look for an element with an id of password and attempt to use it's value as the password submitted for login.

token
The token submitted to Niagara login. If the value is null Domo will automatically look for an element with an id of token and attempt to use it's value as the token submitted for login.

redirect
Whether or not to redirect the user after a login attempt. If set to true, the user will be directed to the Niagara system after they've logged in or back to the login page if there is an error. If you set this to false, you should handle redirecting users manually in the success and fail callbacks.

successCallback: function (url, response)
Function called when a login is successful. Parameters are a URL to redirect the user to and the full response from the login service. This function may or may not be called if the redirect option is true due to the redirect happening immediately after a successful login.

failCallback: function (url, error)
Function called when a login fails. Parameters are a URL to redirect the user to and an error response from the login service. This function may or may not be called if the redirect option is true due to the redirect happening immediately after a failed login.

rememberUserId Another way to control if Domo remembers the last successfully logged in user. This is overridden if the forgetUserId slot is set.

Examples

// if your input fields have 'username', 'password', and 'token' as their IDs
$domo.twoFactorLogin();

// using callbacks
$domo.twoFactorLogin({
  redirect: false,
  successCallback: function(url, response) {
    alert('Two-Factor login successful');
    location.href = url;
  },
  failCallback: function(url, error) {
    alert('Two-factor login error');
    location.href = url;
  },
});

$domo.resetPass(options)

Attempt to reset the password for the current force-reset user (post login) using the following options:

// default options
options = {
  newPassword: null,
  confirm: null,
  redirect: true,
  successCallback: null,
  failCallback: null,
};

newPassword
The new password to assign the user. If the value is null Domo will automatically look for an element with an id of new-password and attempt to use it's value as the password submitted for assignment.

confirm
The confirmation password submitted that should match the password field. If the value is null Domo will automatically look for an element with an id of confirm-password and attempt to use it's value as the confirmation password submitted for login. This field and newPassword must match exactly.

redirect
Whether or not to redirect the user after a login attempt. If set to true, the user will be directed to the Niagara system after they've logged in or back to the login page if there is an error. If you set this to false, you should handle redirecting users manually in the success and fail callbacks.

successCallback: function (url, response)
Function called when a login is successful. Parameters are a URL to redirect the user to and the full response from the login service. This function may or may not be called if the redirect option is true due to the redirect happening immediately after a successful login.

failCallback: function (url, error)
Function called when a login fails. Parameters are a URL to redirect the user to and an error response from the login service. This function may or may not be called if the redirect option is true due to the redirect happening immediately after a failed login.

Examples

// if your input fields have 'new-password' and 'confirm-password' as their ids
$domo.resetPass();

// using callbacks
$domo.resetPass({
  redirect: false,
  successCallback: function(url, response) {
    alert('Reset password successful');
    location.href = url;
  },
  failCallback: function(url, error) {
    alert('Reset password error');
    location.href = url;
  },
});

$domo.checkPassword(options)

Checks a password and confirmation password against the authenticated user's authentication scheme's password strength parameters.

password
The new password to assign the user. If the value is null Domo will automatically look for an element with an id of

 new-password and attempt to use it's value as the password submitted for assignment.

confirm
The confirmation password submitted that should match the password field. If the value is null Domo will automatically look for an element with an id of confirm-password and attempt to use it's value as the confirmation password submitted for login. This field and newPassword must match exactly.

Examples

// if your input fields have 'new-password' and 'confirm-password' as their ids
$domo.checkPassword();

// strings with default digest rules
$domo.checkPassword({ password: 'Domo123!!', confirm: 'Domo123!!' });

// returns
{
  digitsPass: true,
  lowerPass true,
  upperPass: true,
  lengthPass false,
  specialPass: true
}

$domo.checkMatchPassword(options)

Checks a password and confirmation password against one another and returns whether they match

password
The new password to assign the user. If the value is null Domo will automatically look for an element with an id of new-password and attempt to use it's value as the password submitted for assignment.

confirm
The confirmation password submitted that should match the password field. If the value is null Domo will automatically look for an element with an id of confirm-password and attempt to use it's value as the confirmation password submitted for login. This field and newPassword must match exactly.

Examples

// if your input fields have 'new-password' and 'confirm-password' as their ids
$domo.checkMatchPassword();

// strings with default digest rules
$domo.checkMatchPassword({ password: 'Domo123!!', confirm: 'Domo123!!' });

// returns true;

domo.updateFormVisibility(options)

If you adhere to a few layout rules you can use this helper function to hide or show form elements easily using the following options:

// default options
options = {
  usernameWrapId: 'username-wrap',
  passwordWrapId: 'password-wrap',
  tokenWrapId: 'token-wrap',
  showUsername: true,
  showPassword: true,
  showToken: true,
  duration: 300,
  focusId: token,
};

usernameWrapId
Id of the HTML element that contains all the username form elements together, e.g. label and input.

passwordWrapId
Id of the HTML element that contains all the username form elements together, e.g. label and input.

tokenWrapId
Id of the HTML element that contains all the username form elements together, e.g. label and input.

showUsername When true it will remove both the hide and hidden class from the usernameWrapId element. When false it will add the hide class, wait the duration and then add the hidden class.

showPassword When true it will remove both the hide and hidden class from the passwordWrapId element. When false it will add the hide class, wait the duration and then add the hidden class.

showToken When true it will remove both the hide and hidden class from the tokenWrapId element. When false it will add the hide class, wait the duration and then add the hidden class.

duration Number of milliseconds to wait after hiding to start showing shown content. Only used when something is hidden.

focusId Id of the HTML element you want to focus after all elements have been updated.

Examples

// Using the following HTML:
<div id="username-wrap" class="field-wrap">
  <div class="field-label">Username</div>
  <input type="text" autocapitalize="none" name="j_username" id="username" placeholder="Enter your username" />
</div>
<div id="password-wrap" class="field-wrap">
  <div class="field-label">Password</div>
  <input type="password" autocapitalize="none" name="j_password" id="password" placeholder="Enter your password" autocomplete="off" />
</div>
<div id="token-wrap" class="field-wrap hide hidden">
  <div class="field-label">Token</div>
  <input type="text" name="j_token" id="token" placeholder="Authenticator code" autocomplete="off" />
</div>

// hide username and password, show token
$domo.updateFormVisibility({ 
  showUsername: false,
  showPassword: false,
  showToken: true
});

Unsplash

You can use Unsplash to load in random images. To use the Domo Unsplash library include the following JavaScript after the other Domo libraries above.

<script type="text/javascript" src="/login?unsplash.js"></script>

$domo.unsplash(selectors, options, callback, fallback);

selectors <Object>
Object that specifies which elements in your HTML file will be loaded with content from Unsplash. There is a selector for the image/photo content, the author/photographer name, and author/photographer link. It is required to include author/photographer attribution when using Unsplash images.

selectors = {
  image: '.image', // img elements will have their src set, other elements will have their background-image style property set
  author: '#authorName', // Name of photographer/author
  authorLink: '#authorLink', // Anchor tag for author link, this must be an <a> element
}

options <Object>
Unsplash options to refine your random image search.

options = {
  term: $domo.config.unsplashSearch, // search term, use the config to pull from the slot on WebService
  orientation: 'portrait', // or 'landscape' or 'square'
  content_filter: 'high', // or 'low' – keeps content safe for work
  featured: true, // or false, when true only shows featured photos
};

callback <Function (image)>
Callback function called when the API has completed. image will be null if there was an error loading the data. If the call was successful, image will be an array containing a single object with Unsplash image data.

fallback <String> or <Object> 

Object or string specifying a fallback value if the API call is unsuccessful. If this value is a string, the string will be used to set the background-color of any element matching the selectors.image selector. If fallback is an object, fallback.color will be used. You can also specify fallback.gradient = true to use fallback.color in a gradient fading to transparent.

// Fallback color with gradient example
fallback = {
  color: #ff0000, // red
  gradient: true,
}

Unsplash Example

HTML

<script type="text/javascript" src="/login?unsplash.js"></script>
<div class="background" />
<div class="author-container">
  Photo by
  <a href="#" class="author-link"><span class="author-name" /></a>
  via <a href="https://unsplash.com">Unsplash</a>
</div>

JAVASCRIPT

var selectors = {
  image: '.background',
  author: '.author-name',
  authorLink: '.author-link',
};
var options = {
  term: $domo.config.unsplashSearch,
  orientation: 'landscape',
  content_filter: 'high',
  featured: true,
};
var callback = function(image) {
  // Display author elements after image has loaded
  if (image && image.user) {
    $domo.display('.author-container', 'block');
  }
};
$domo.unsplash(selectors, options, callback, {
  gradient: $domo.config.hasGradient,
  color: $domo.config.backgroundColor,
});

Copyright 2020-2024 NiagaraMods