Using the UI Builder

The Curity Identity Server installation comes bundled with a UI Builder. It is a small toolkit that can be used when customizing the templates. It contains both a previewer that can serve the velocity templates without the server being running, as well as the source code for all templates and styles.

Setting up the environment

Prerequisites

  • Node.js 14 or later
  • Java 21 or later

Installation

The UI Builder is located in $INSTALL_DIR/misc/ui-builder. It contains a package.json with the Node.js dependencies. To install it simply return

$ npm install

This will install the node dependencies such as Webpack and Browsersync.

Note

npm, the Node package manager, the npm Registry, and npm CLI is distributed with Node.js - which means that when you download Node.js, you automatically get npm installed on your computer.

Using from a different location

Once development starts the UI Builder can be used as an integral part of the development process. For development in Linux or MacOS, the JRE provided with the Curity Identity Server can be used, by updating the environment file with the path to the installation. Alternatively, a local Java installation can be used.

Listing 219 Updating the file: environment
INSTALLATION_DIR=/path/to/curity/installation/release

Note

The UI Builder can be used outside of the installation. When doing so update environment to point to the root of the Curity Identity Server installation.

For development in Windows, Java 17 or later must be installed.

Running the previewer

Once installed the UI Builder provides a build system for the Sass and JavaScript source files. It also contains a previewer where all templates can be viewed. To start it run:

$ npm start

This will start the Java preview server, and also a Browser-Sync proxy and a file watcher. Any change made in the src directory of the UI Builder will immediately be compiled, and reflected in the browser via browser-sync.

If the command does not open a browser immediately go to the following address in your browser:

http://localhost:3000/listing

Working with Velocity variables

The structure of some screens are controlled by Velocity variables. A good example is the sms enter-otp screen. It is located under $UI_BUILDER/src/curity/templates/core/authenticator/sms/enter-otp/get.vm. To view it in the previewer open the main page at http://localhost:3000 and type sms in the search field.

../../_images/previewer-search.jpg

Fig. 190 Search screen in the previewer

This shows all templates related to the SMS authentication. Notice in the previewer, it doesn’t show any fragments or layouts since those aren’t entry points for screens. They are pulled in from the screens listed in the previewer.

Select the enter-otp/get.vm template from the list of sms templates, and you’ll see something similar to this:

../../_images/sms-enter-otp.jpg

Fig. 191 SMS Enter OTP Template

This template is controlled via variables set by Curity when it loads the template. Inspect the source $UI_BUILDER/src/curity/templates/core/authenticator/sms/enter-otp/get.vm for the template and the following is present:

Listing 220 Sms Enter OTP template
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
...
#if ($_allowRegistrationDuringLogin)
<div class="center px3 mt4">
    <p>
        #message("authenticator.sms.enter-otp.view.register-info")

        #if (!$_showInfoBeforeRegistration)
        ## The next thing the user will see is a login prompt (unless they've logged in before with
        ## an allowed authenticator), so we'll give them a bit of extra info before they're
        ## redirected.
        #message("authenticator.sms.enter-otp.view.register-info-login")
        #end
    </p>

    <a href="$nextPage" class="button button-grey button-fullwidth" role="button">
        <i class="icon ion-ios-plus-outline inlineicon"></i>#message(
        "authenticator.sms.enter-otp.view.register-or-change")
    </a>

</div>
#else
...

One line 2 it checks if $_allowRegistrationDuringLogin is configured. If so it shows another section. To have the previewer show this, simply set that variable in the main screen and click apply.

../../_images/previewer-set-variable.jpg

Fig. 192 Set a context variable in the previewer

Then click the enter-otp/get.vm template again and see the difference

../../_images/sms-enter-otp-with-register.jpg

Fig. 193 SMS Enter OTP screen with registration enabled

Overriding templates

The structure in the ui-builder source tree for templates mimics the deployment structure of Curity in $IDSVR_DIR/usr/share/templates.

To override a template, create a copy in the overrides directory following the same structure. For example, to override the fragments/logo.vm

  1. Add your logo to the images folder $UI_BUILDER/src/curity/images/your-logo.svg
  2. Create the fragments folder in the overrides src directory $UI_BUILDER/src/curity/templates/overrides/fragments/logo.vm
  3. Update the content:
Listing 221 Overriding the logo
1
<img class="login-logo" src="$_staticResourceRootPath/assets/images/your-logo.svg">

If you are running npm start then the previewer will be updated automatically. Visit the same page as above http://localhost:3000/authenticator/sms/enter-otp/get. Now you’ll notice that the logo is updated.

Tip

You can view the core templates without overrides by adding ?area=core in the URL or by adding a velocity variable _area with the value core.

To view the non-overridden template add ?area=core to the query string: http://localhost:3000/authenticator/sms/enter-otp/get?area=core and only the core templates are shown.

Working with template areas

Just like with overrides you can create and view template-areas in the previewer. To create a template area simply create a folder with the name of your template area in the file:$UI_BUILDER/src/curity/templates/template-areas directory.

Example

  1. Create a template area called myarea by adding the folder file: $UI_BUILDER/src/curity/templates/template-areas/myarea
  2. Add the fragments folder in the myarea folder like before
  3. Add an empty logo.vm in the fragments folder

Now visit http://localhost:3000/authenticator/sms/enter-otp/get again. You still see the override logo, not the template area logo. To view the template area add ?area=myarea to the url. Now the logo disappers.

Note

You can control which templates you see in the preview by the velocity variable _area. For example _area=myarea will show the templates under myarea without the need to add the query parameter. Adding a query parameter though, will override the velocity variable ?area=overrides will deem anything set on the velocity variable obsolete.

Warning

Do not update the core templates. Always copy them to overrides or an area in template-areas before editing. Updating core templates will cause issues when migrating between Curity versions.

Working with translations

You can change the language of the previewer by setting the _locale velocity variable or adding a query parameter ?locale=sv. Similar to the _areas velocity variable, the query parameter overrides the velocity variable (if it exists). The language shown by default is english.

Building

When running npm run build Webpack builds and copies all output to the build directory. The structure in the build directory mimics the structure in $IDSVR_DIR/usr/share. So you’ll find templates and webroot that you simply can copy into your Curity installation $IDSVR_DIR/usr/share structure.

Tip

Creating new files under template-areas, overrides or webroot won’t show up in the build directory if the previewer is running, so, to make sure everything is updated, always restart the build before copying the files to your installation.