Skip to main content

UI Development Process

Introduction​

This guide covers the end-to-end workflow for developing frontend code for Mango Automation modules. It is IDE- and OS-agnostic, though IntelliJ IDEA is the recommended IDE for Mango development.

Technology Brief​

The main Mango user interface is supplied by the mangoUI module. It is a single-page AngularJS (1.x) application that can be extended by other Mango modules -- for example, modules can supply new pages and routes or provide a component for editing a particular type of data source.

Mango modules use Webpack to compile and bundle all web resources into a single JavaScript file that is loaded by the client browser.

The Mango UI relies heavily on the AngularJS Material framework and loosely adheres to the Material Design guidelines.

The UI can also be extended by supplying a user module (AngularJS module) and CSS file stored in Mango's internal file store. This approach is useful for small projects where developing a full Mango module is unnecessary.

Tools Required​

Install these tools before developing Mango modules:

ToolVersionDownload
GitLatestgit-scm.com
Node.js20.x or 22.x LTSnodejs.org
Yarn1.x (Classic)classic.yarnpkg.com
Java (runtime)JDK 17+ minimumAzul Zulu
Java (build)JDK 25Azul Zulu
Maven3.9.9+maven.apache.org
IntelliJ IDEACommunity or Ultimatejetbrains.com
Yarn Version

We use Yarn Classic (1.x) lock files. Yarn 2+ (Berry) is not currently supported.

Code Style and Design Guidelines​

JavaScript​

JavaScript should be written according to the ECMAScript 6 (ES6) standard. We do not use a transpiler such as Babel. Ensure that the features you use are supported by all popular modern browsers: Chrome, Firefox, Safari (iOS and desktop), and Microsoft Edge.

Follow the Airbnb ES6 style guide with these project-specific adjustments:

RuleSetting
Indentation4 spaces (not tabs)
Trailing commasRequired in multiline constructs
QuotesSingle quotes
SemicolonsRequired
Object curly spacingNo spaces ({a, b} not { a, b })
var keywordForbidden -- use const or let

Use a linter (ESLint) in your IDE to check for errors and enforce the style guide. The ESLint configuration for the Airbnb style guide can be found here.

AngularJS​

AngularJS components should use the AngularJS 1.5+ component syntax. Do not use directives for this purpose.

Code that makes REST API requests should be placed in a service. Do not make REST requests directly from a component.

Component and service names should be prefixed with ma to namespace them and prevent conflicts with other libraries.

Do:

  • Leverage the $onInit(), $onChanges(), and $onDestroy() lifecycle hooks
  • Use ES6 classes for component controllers
  • Use & callback bindings for outputs
  • Require ngModel where appropriate and implement its render() and $setViewValue() methods
  • Use the $$ngIsClass and $inject static getters (see the AngularJS patterns in the project CLAUDE.md for the canonical class structure)

Do not:

  • Use two-way/bidirectional = bindings

Material Design​

The Mango UI loosely follows the Google Material Design guidelines, using the AngularJS Material library. Leverage components and directives from this framework whenever appropriate.

HTML​

Markup should be HTML5 with AngularJS extensions.

Layouts​

HTML layouts should use the AngularJS Material flex layout directives or component-specific CSS classes that apply flex layout styles.

Responsive Design​

Layouts should be responsive and work on all screen sizes. Use AngularJS Material flex layout directives to achieve this.

CSS​

  • Prefix CSS class names with ma- to namespace them
  • Scope component styles to the component element tag: ma-my-component .ma-large-text { /* rules */ }
  • Do not use inline styles. Add a CSS file for each component and import it via ES6: import './myComponent.css';
  • Never use the !important keyword. Use a higher-priority selector instead.

Colors​

The Mango UI uses AngularJS Material to apply colors from a configurable palette (set on the "UI Settings" page). Hardcoding colors in CSS is prohibited.

Apply colors using the md-colors directive. Always use a one-time binding when the color will not change.

Localization and Internationalization​

Do not hardcode English text in HTML. Place all messages in the module's classes/i18n.properties file and use the ma-tr directive to include translated messages in markup.

Use moment.js to format dates with a format string that honors the user's locale settings, for example lll LTS. There is also an AngularJS filter named maMoment for formatting dates in markup:

ng-bind="timestamp | maMoment:'format':'ll LTS'"

Cloning the Git Repositories​

Git Configuration​

Add the following to your global Git config:

[branch]
    autosetuprebase = always

Clone Repos​

Clone the Mango repositories for the modules you will be working on into a single directory (your "development home" directory):

Once cloned, switch to the branch corresponding to the version of Mango you are developing on. The main branch tracks the latest development. For specific release lines, use version branches such as 5.x.

Installing Mango​

Please read the installation documentation. Unless directed to use a specific release version, download the latest nightly build from the Mango Store, which is built from the main Git branch.

Configuring mango.properties​

After installation, configure your mango.properties file (located in mango-data/mango.properties) to enable development features.

Store URL​

When developing on the nightly build, set the store URL to pull updates from the test store:

store.url=https://teststore.mangoautomation.net

Development Mode​

Enable development mode to load web resources from your module development directory instead of from the installed module. This lets you change source files and see changes immediately on browser refresh.

development.enabled=true
development.home=/path/to/your/development/home
development.moduleDirectories=ma-dashboards
development.linkWeb=true
development.linkResources=true
development.linkClasses=true
development.loadMavenClasses=false

Configure development.moduleDirectories with a comma-separated list of repository directories inside your development home.

To limit development mode to specific modules, use the whitelist setting:

development.whitelistModules=mangoUI
Windows Users
  • You need to give your development user permission to create symbolic links: see this guide.
  • Escape backslashes in the development.home path, for example: C:\\Users\\YourName\\mango-dev

Effects of Development Mode​

When development mode is enabled:

  • Java classes and properties files are loaded from the module's development directory (maven-target/classes)
  • A symlink is created from the installed module's web directory to your development directory's web folder
  • You can run Webpack in your development directory and see changes on page reload
  • AngularJS module files from SNAPSHOT modules are loaded with a new ?v= parameter on each page refresh, so you do not need to disable your browser cache
  • A button appears on the UI toolbar to clear the translation cache and reload the page

Miscellaneous Settings​

Prevent Mango from opening a browser window on each start:

web.openBrowserOnStartup=false

Enable the Swagger/OpenAPI UI at http://localhost:8080/swagger-ui.html:

swagger.enabled=true

Starting Mango​

Use the $MA_HOME/bin/start-mango.sh script to start Mango. See the installation documentation for details.

You should now be able to access Mango at http://localhost:8080/ (provided you have not changed the default port or HTTPS settings).

Compiling Frontend Code​

Ensure the module you are working on is installed in Mango (development mode only works for installed modules).

Install Node.js dependencies in your module development directory:

yarn install --frozen-lockfile

Compile and bundle the source files from the module's web-src directory into the web directory:

yarn webpack --mode development

Alternatively, run Webpack in watch mode for automatic recompilation when source files change:

yarn webpack --mode development --watch

Refresh your browser to see updated changes.

Debugging​

Compile your module's frontend code using Webpack development mode (as shown above) to enable readable source maps in your browser's developer tools. Chrome DevTools is recommended for JavaScript debugging.

When modules are built via Maven for production deployment, Webpack runs in production mode, which minifies the JavaScript and makes debugging difficult.

Browser Caching​

With development mode enabled, all module resource files are loaded with a ?v= query parameter that changes on each page refresh. You should not need to clear or disable your browser cache.

However, the Mango UI installs a service worker that caches module assets. In Chrome DevTools, go to the Application panel and check Bypass for network under the Service Workers section. Note that DevTools must remain open for this setting to take effect.

Module Directory Structure​

The following summarizes the general directory layout of a Mango module (may vary slightly between modules):

Paths marked with ** should not be committed to the Git repository.

PathDescription
srcJava source code
src-testJava test source code
resourcesJava resources included in the built .jar file
file-resourcesGeneral resource files installed into the module directory
api-testNode.js/Mocha tests for the REST API
classesFiles added to the Java classpath
classes/i18n.propertiesRoot translations file (effectively en_US translations)
** maven-targetOutput directory used by Maven when building the module
web-srcSource files for Webpack compilation (JS, CSS, HTML, images)
webFiles served by the web server once the module is installed
** web/angularOutput directory for Webpack bundling
licenceTypes.xmlModule licensing information
module.propertiesModule metadata loaded by Mango
pom.xmlMaven build configuration and Java dependencies
RELEASE-NOTESRelease notes displayed by the store
webpack.config.jsWebpack configuration file
yarn.lockYarn lock file for NPM package versions
package.jsonNPM package information and JavaScript dependencies
** node_modulesInstalled NPM dependencies
** nodeNode.js and Yarn binaries used during Maven builds

Creating a New Module​

  1. Copy the default pom.xml into your new module directory.
  2. Edit the pom.xml with your module name, artifact ID, and description.
  3. Copy the default package.json into the module directory.
  4. Run yarn install.
  5. Run yarn run update-package-json.
  6. Create a web-src directory with a root .js file named after your module.
  7. Create a webpack.config.js file.
  8. Run mvn install to build the module.

Building a Complete Module Zip File​

With Maven 3.9.9+ installed, build a complete module zip for installation into Mango:

mvn install -Pinstall-module

To compile frontend code in development mode during the build:

mvn install -Pinstall-module -Dwebpack.mode=development

For a full Mango build including core and all modules:

mvn install -Pcore-bundle,core-zip,install-module,maven-cache

The first build will take longer as Maven downloads all plugins and dependencies. Copy the built module zip from maven-target into $MA_HOME/web/modules and restart Mango to install it.