Introduction

In Niagara 4, the user interface is moving in a new direction with a heavy focus on HTML5 applications and open web technologies. Tridium provides a number of frameworks and utilities, intended to give developers the power to create their own web apps, from tiny field editors to powerful, full-featured full-screen views.

Developing in HTML5 and JavaScript is a different process from the familiar Java-based process for developing in the Niagara Framework. However, using the tools and techniques described in this document, you can create a JavaScript codebase that is robust, error-checked, and well-tested.

Frameworks and Libraries

Setting Up Your Environment

In order to most effectively develop Niagara web applications, you’ll need to install a few external utilities for building, code analysis, and testing.

The toolchain described in this document is the one used by Tridium to develop all of its HTML5 web applications for Niagara 4. The tools described are free and open-source. The toolchain is separate from the Niagara Framework itself, so if you find that it does not suit your purposes, you are free to use a different set of development tools, or create your own.

To use the standard Tridium toolchain, you’ll need to install the following utilities:

Node.js

npm

npm is a utility used to download and install Node.js modules. It is automatically installed alongside Node.js.

Grunt

Git

Environment Variables

These environment variables are necessary for doing Niagara web development. Some may already be set up for you - type set at your command line to see which are present.

Build and Development Tools

Open Source Niagara Development Utilities

In order to properly build and test JavaScript modules, there is some setup involved. npm libraries need to be downloaded and installed, configuration files need to be written, and code needs to be moved into the proper directories.

grunt-init-niagara

grunt-init is a tool that streamlines the creation of a new JavaScript project. The process is similar to Wizards you might use in Workbench: it asks you a number of setup questions and generates a brand-new web module for you to begin development.

grunt-init-niagara is Tridium’s own grunt-init template which is Niagara-specific; it generates you a brand-new Niagara web module that can be built and run using standard Niagara tools. The module will be pre-configured with source code and test directories, configuration files, and everything necessary to start developing.

All of the modules described in the rest of this section will be automatically included in your new module with no further configuration necessary. Simply type npm install to download everything, then begin development.

While it’s entirely possible to create a new web module without using grunt-init-niagara, we highly recommend that you use it for your first web module to learn about the recommended project structure and configuration.

grunt-niagara

niagara-station

This is a library that allows you to start and stop Niagara 4 stations using Node.js. It is most commonly used during the test process to start a station with BajaScript installed, so that the web module’s unit tests can use a live BajaScript session to verify real-world behavior.

It also has some basic port configuration abilities. For example, if you are running tests on a machine that has port 80 already in use, niagara-station can reconfigure the station to run HTTP on port 8080 instead.

When using grunt-init-niagara, your web module will automatically receive a test station and a default niagara-station configuration.

niagara-test-server

This module simply includes some utilities for logging into a running test station using JavaScript and triggering the browser to run tests. Again, it’s automatically included by grunt-init-niagara.

ESLint

Jasmine

Karma

Building and Compacting your JavaScript

Developing in real time with moduledev mode

When developing a web module, it’s a severe slowdown to have to rebuild your module and restart your station every time you want to test out a new change in your browser. It’s much faster to simply change a file and refresh the browser to pick up the latest changes.

To facilitate this, Niagara 4 includes a moduledev mode that allows files from certain modules to be read directly from your hard drive instead of from a module JAR file. In order to enable this mode, you’ll need to perform the following steps.

First, you’ll need to ensure this feature is enabled in your Tridium license. You’ll need the developer feature included in your license with the moduleDev property set to true. If your license does not include this feature, please contact your Tridium sales representative.

Next, add an entry to system.properties: niagara.module.dev=true. This is for the browser only; for Workbench, there is another setting: niagara.module.dev.wb=true.

Not every file type can be resolved in this way: by default, only JS, CSS, HTML, image files, and some other web-related file types are supported. If you wish to resolve some different file types, you can configure this list using this system property: niagara.module.dev.supportedExtensions=js,css,vm,htm(...)

Next, create a file niagara_home/etc/moduledev.properties. Each entry in this file maps a module name to the directory on your hard drive in which that module’s source code lives. For instance, myModule=d:/niagara/dev/myModule. (Note that the runtime profile is not included! myModule-ux=d:/niagara/dev/myModule/myModule-ux will not work. moduledev mode will resolve files from any of your runtime profile directories.)

Now, whenever a request is made for a file, with a supported extension, from your web module, it will be resolved from your hard drive instead of from the JAR. This way, hitting refresh in the browser will always load your up-to-date changes. Note that this mode should never be enabled in production - only in development.

First Steps

Now that you’ve set up your environment and gotten a brief introduction to the various JavaScript libraries and frameworks available to you, it’s time to start developing! This section will contain a full tutorial, from creating your first module using grunt-init-niagara, to writing your first test, to viewing the result in the browser.

Creating a new module

package.json

Gruntfile.js

This file is used by Grunt. It describes all the automated tasks that are available for your module, and sets up configuration settings for each.

You will see at the bottom of the file that it loads tasks for the grunt-niagara module. This is a utility module that includes tasks that we at Tridium have found to be very useful when developing web applications. It sets up a default configuration for each one that we find to work well. You are free to override these configurations as you wish, but just leaving this file alone and working with the provided config is a great way to get started. (Later on, if you decide that grunt-niagara isn’t right for you, you can leave it out completely and build your own toolchain as you see fit.)

To see the tasks that are available to you right out of the box, just type grunt.

Another feature that grunt-niagara provides for you is the ability to pass in config flags on the command line when running tests. To see a list of all available flags, type grunt flags. A few flags you may find particularly useful are:

• --testOnly: if your test suite grows large, you may find it taking longer and longer to run all of your specs. You can use testOnly to limit which specs are run.
• --station-http-port: if your test station runs a different HTTP port, you can specify which port your tests should use to attempt to log into the station. There are also corresponding flags for HTTPS, FOX, and FOXS.
• --override-station-ports: used in conjunction with the previous flags, actually will inject the port number into the config.bog before starting the station to force it to run on a particular port. This is helpful if one of the default ports is already in use on your machine.
• --station-log-level: configure how much detail from the station log is output to the console when running tests. It defaults to NONE because usually you’ll only want to see the actual test output instead of a lot of noise from the station. But dialing it up to INFO, FINE, or all the way to ALL can help with debugging.

Many of these flags’ default values are set using the niagara_home and niagara_user_home environment variables.

Watching - The Important Stuff

A note on Continuous Integration

Unit tests, as configured by grunt-niagara, will export their results in a JUnit-compatible XML format. This means that if your organization uses a Continuous Integration solution, like Bamboo or Jenkins, it can consume these XML files. Your JavaScript code can then be included in your CI process.

When invoking the Grunt process, use grunt ci to run CI-related tasks and generate these XML files. If needed, you can use the --junit-reports-dir flag to specify where the XML results go.

Building your JavaScript into a Niagara module

Implementing your JavaScript-based widgets is only one part of the development process. They must also be built into your Niagara module so that they can be deployed to Niagara stations and supervisors.

Specifying additional Grunt tasks

By default, the Niagara build environment will run any Grunt tasks you have configured (the default is just the requirejs task) prior to building the module jar. You can change this by editing the “gruntBuild” section of your module’s Gradle build file:

gruntBuild { tasks 'requirejs' }

You may add additional tasks by specifying the task name(s) as such:

gruntBuild { tasks 'less', 'babel', 'requirejs' }

You can then build your module as normal:

gradlew :myWebModule-ux:jar

Compacting using the Grunt RequireJS Plugin

Implementing BIJavaScript

Often, your HTML5 web app will have an instance of some BajaScript value: a Facets, for instance, or a DynamicEnum, that you wish to present to the user in an editor. You could manually go and fetch the code for FacetsEditor or DynamicEnumEditor, then instantiate, initialize, and load it into your page. It would be much easier, though, to simply ask the framework for an editor that’s appropriate to edit that value. Then, you’ll be certain that you’ll be provided the correct, most up-to-date version of that editor.

Also, consider the Property Sheet. If you have a custom Baja value and a custom field editor to edit that value, you’ll need to create an association between the two so the Property Sheet knows how to show the correct editor for your custom value.

The way to do this is to create a simple Java class in your module. Its only job is to provide answers to these questions:

1. What JavaScript file represents the implementation of my editor?
2. What Types can I edit with this editor?

What JavaScript file defines my editor?

To let the Niagara framework know about the JavaScript file containing your editor, create a Java class that extends BSingleton and implements javax.baja.web.js.BIJavaScript. This simply creates a mapping between a Niagara Type and a JavaScript file.

@NiagaraType
@NiagaraSingleton
public final class BMyWebModuleWidget
  extends BSingleton
  implements BIJavaScript, BIFormFactorMini, BIOffline
{
  private BMyWebModuleWidget() {}

  public JsInfo getJsInfo(Context cx) { return JS_INFO; }

  private static final JsInfo JS_INFO = JsInfo.make(
    BOrd.make("module://myWebModule/rc/MyWebModuleWidget.js"),
    BMyWebModuleJsBuild.TYPE
  );
}

As you can see, there is very little to a BIJavaScript class. It has only one method to implement, getJsInfo(), which lets the Niagara Framework know where the JavaScript implementation of your widget is located.

What Types can I edit with my editor?

Now that you’ve implemented a JavaScript editor and registered its existence with the framework, you can also declare it to be compatible with certain Types. For instance, MyWebModuleWidget might be able to load values of type myWebModule:MyWebModuleComponent. To declare this relationship, simply register your BIJavaScript as an agent on a Type. You can do this the usual way, in module-include.xml:

<type name="MyWebModuleWidget" class="com.tridium.mywebmodule.BMyWebModuleWidget">
  <agent><on type="myWebModule:MyWebModuleComponent" /></agent>
</type>

Or (recommended) the new annotation-based method available in Niagara 4:

@NiagaraType(agent = @AgentOn(types = { "myWebModule:MyWebModuleComponent" }))
public final class BMyWebModuleWidget

Switching your Station into Web Development mode

One last thing to consider. At this point you have two files containing your editor’s code: the one you’ve just created, with the human-readable JavaScript code (MyWebModuleWidget.js), and the built and minified version for conserving network traffic (myWebModule.built.min.js).

During normal usage, your station will only serve up the minified file. This is absolutely the correct behavior: on an embedded device, conservation of network traffic is key. But take a look at the minified file: it’s completely incomprehensible. When developing and debugging, you really want to be able to see the original, human-readable code.

By enabling webdev mode for your module, the station will kick into debug mode: it will switch over to serving up the original file, so that you can open up the console in Chrome or Internet Explorer and trace through your actual code.

To enable webdev mode, simply go into the spy page for the station and visit the webDevSetup page. (You’ll need to actually visit the web interface first - so the station serves up some files - for it to appear.) Enable webdev mode for the ID of your BJsBuild, and from then on, the unminified files from your module will be served to the browser. This is invaluable when debugging your code live in the browser. (To learn more about browser debugging, search the web for “{your browser name} console tutorial.”)

You can also configure webdev by hand by editing %niagara_user_home%/etc/webdev.properties.

Moving Forward

Let’s do a quick recap of what you’ve accomplished so far.

1. You’ve created a widget with JavaScript that can be used in the new Niagara 4 HTML5 web views (MyWebModuleWidget.js)
2. You’ve registered its existence with the framework (BMyWebModuleWidget implements BIJavaScript)
3. You’ve optimized it down within a single built JavaScript file to minimize network traffic (requirejs configuration creates myWebModule.built.min.js)
4. You’ve registered the existence of the built file with the framework (BMyWebModuleJsBuild extends BJsBuild) and let the framework know that your widget’s code is packaged within it (BMyWebModuleWidget references BMyWebModuleJsBuild)
5. You’ve let the framework know to show you a MyWebModuleWidget when it tries to load an editor for a compatible Type (BMyWebModuleWidget is an Agent on BMyWebModuleComponent).

Appendix

Migrating from niagara-rjs to grunt-niagara

When using grunt-init-niagara to create a new Niagara module targeting 4.6 or later, grunt-niagara will automatically be used in place of niagara-rjs. When migrating an existing module to the latest version of Niagara, the niagara-rjs config should be removed and migrated to use grunt-niagara instead. This section will describe that migration process.

Creating Gruntfile.js and package.json

One option is to run grunt-init-niagara in an empty directory, which will generate a Gruntfile and package.json for you. Or, for an existing module, you can manually create them as shown below. Both of these files go in the root of your module part, that is, yourModuleName/yourModuleName-ux.

//package.json
{
  "name": "yourModuleName-ux",
  "version": "0.1.0",
  "devDependencies": {
    "@babel/core": "^7.0.0",
    "@babel/preset-env": "^7.0.0",
    "babel-plugin-istanbul": "^4.1.3",
    "grunt": "~1.0.1",
    "grunt-niagara": "^2.1.0"
  }
}
 
 
//Gruntfile.js
const SRC_FILES = [
  'src/rc/**/*.js',
  '!src/rc/**/*.min.js'
];
const TEST_FILES = [
  'srcTest/rc/**/*.js'
];
const ALL_FILES = SRC_FILES.concat(TEST_FILES);
 
module.exports = function runGrunt(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
 
    jsdoc:     { src: SRC_FILES },
    eslint:    { src: ALL_FILES },
    watch:     { src: ALL_FILES },
    karma:     {},
    babel:     {},
    requirejs: {},
    niagara:   {
      station: {
        forceCopy: true,
        sourceStationFolder: './srcTest/stations/bajauxUnitTest'
      }
    }
  });
 
  grunt.loadNpmTasks('grunt-niagara');
};

Configuring RequireJS

Let’s look at an example niagaraRjs config block from a legacy Gradle file.

//in myModule-ux.gradle:
niagaraRjs {
  builds = [
    'myDefaultBuild': [
      rootDir: 'src/rc',
      include: [
        'nmodule/myModule/rc/fe/MyWidget',
        'nmodule/myModule/rc/fe/YourWidget',
        // ... every file in my module
      ]
    ]
  ]
 
  options = [
    disablePlugins: [ 'baja', 'lex', 'css' ],
    exclude: [ 'Handlebars', 'underscore', 'hbs' ],
    hbs: [
      disableHelpers: true,
      disableI18n: true
    ],
 
    paths: [
      'nmodule': 'empty:',
      'bajaScript': 'empty:',
      'jquery': 'empty:',
      'bajaux': 'empty:',
      'dialogs': 'empty:',
      'profileInfo': 'empty:',
      'bajauxContainer': 'empty:',
      'jqueryContextMenu': 'empty:',
      'hx': 'empty:',
      'Promise': 'empty:',
      'ace': 'empty:',
 
      'nmodule/myModule': 'src',
      'nmodule/myModuleTest': 'srcTest',
 
      'Handlebars': projectResource('js-ux', 'rc/handlebars/handlebars-v2.0.0'),
      'hbs': projectResource('js-ux', 'rc/require-handlebars-plugin/hbs'),
      'i18nprecompile': projectResource('js-ux', 'rc/require-handlebars-plugin/hbs/i18nprecompile'),
      'json2': projectResource('js-ux', 'rc/require-handlebars-plugin/hbs/json2'),
      'underscore': projectResource('js-ux', 'rc/underscore/underscore')
    ],
    rhinoJvmArgs: [ '-Xss4m' ]
  ]
}

The grunt-niagara equivalent of this configuration is:

// in myModule-ux.gradle:
apply plugin: "com.tridium.niagara-grunt"
gruntBuild { tasks 'requirejs' }
 
// in Gruntfile.js:
requirejs: {}

That’s it! By including an empty requirejs block, RequireJS optimization will be turned on, using the default behavior. The default behavior of grunt-niagara matches the existing behavior of niagara-rjs and is described below:

• Automatically include every .js file in src/rc into the builtfile
• Place the builtfile at build/src/rc/yourModuleName.built.min.js, where it will be packaged into the .jar
• Disable the appropriate plugins (for instance, you cannot actually use the baja! plugin to start up a BajaScript session while optimizing)
• Omit the most commonly used libraries from other modules, to prevent them from being unnecessarily duplicated in your builtfile
• Use require-handlebars-plugin to package Handlebars templates into the builtfile