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.
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 gulp and Browsersync.
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.
Once development starts the UI Builder can be used as an integral part of the development process. Adding the UI Builder to a local repository is often needed, and is supported. When doing this, the UI Builder needs to have a reference to the Curity installation. It does not run Curity but it uses some libraries available in the installation.
To use the UI Builder outside of the installation, the environment file can be updated with the path to the installation.
Edit the environment file in the root of the UI Builder with the path to the installation:
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.
$ 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:
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.
Fig. 173 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:
Fig. 174 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:
<div class="center px3 mt4">
## 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
<a href="$nextPage" class="button button-grey button-fullwidth" role="button">
<i class="icon ion-ios-plus-outline inlineicon"></i>#message(
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.
Fig. 175 Set a context variable in the previewer
Then click the enter-otp/get.vm template again and see the difference
Fig. 176 SMS Enter OTP screen with registration enabled
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
<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.
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.
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.
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.
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.
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.
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.
When running the gulp build (gulp or npm run build) gulp 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.
npm run build
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.