Completely transform the Niagara login experience with built-in responsive templates or create your own custom login screens from scratch
Readme
NiagaraMods Domo
Version 1.0 Beta 1
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 works on Niagara 4.3 and later
Extract the zip file and copy the
nmxdomo-rt.jar
file to your Niagara modules directory.If Workbench is open, close it and relaunch.
If you are using this module on a local station, restart the station using the Application Director in your Platform.
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
Connect to your station, then open the Property Sheet of your WebService component in Config > Services
Find the
Login Template
property, and unchecknull
if it is checked.In the first dropdown of the
Login Template
property, selectnmxdomo
In the second dropdown of the
Login Template
property, select the template you wish to use.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
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.
Slot Name | Type / Description | |
---|---|---|
|
The default Niagara logo slot, the image at this Ord will be used as the logo on the page | |
|
The default Niagara CSS slot, the CSS file at this Ord will included in the login page. Use this to override the page styles with custom values | |
|
Color used for the buttons and input boxes. If this is not set, a default color of | |
|
If this slot exists, the background of the left pane will be semi-transparent and the wallpaper image will show through. Note: this slot only effects the | |
|
If this slot exists, the themes will not connect to Unsplash to download a random wallpaper image. Instead, if no | |
|
A custom search term to use when finding a random wallpaper image from Unsplash. If this slot does not exist, the search term that is used for the image search will be | |
|
Provide a File Ord to an image that will be used as the background for the page. Note that if this slot has a value, the login will no longer fetch an image from Unsplash. If this slot does not exist, or it is | |
|
The background color for the wallpaper area. The value can be any CSS color string including Hex, RGB, RGBA, and HSL. If this slot does not exist or is | |
|
If this slot exists when a background color will be used as the wallpaper (either because Unsplash is turned off and there is no | |
|
The background color for the entire page. Other backgrounds including | |
|
If this slot exists, the End User License Agreement links below the form will be hidden. |
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.
Beta Notes & Roadmap
Important notes about this version of Domo
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.
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.
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}}
Variable | Description | |
---|---|---|
|
The title of the station, typically the station name | |
|
The value of the | |
|
True if a custom | |
|
True if a custom | |
|
True if the | |
|
The value of the | |
|
True if the | |
|
True if the | |
|
The value of the | |
|
True if the | |
|
True if the | |
|
The value of the | |
|
True if the | |
|
True if a login attempt was unsuccessful | |
|
The username attached to the current session |
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=