Using UI Kit#

The Curity Identity Server comes with UI Kit, a public GitHub repository. It contains the source code for all templates and styles, as well as a previewer that can serve the Velocity templates without the server being running.

Setting up the environment#

Prerequisites#

  • Node.js (version as specified in the .nvmrc file)
  • Java 21 or later

Installation#

To install all dependencies across a monorepo using npm workspaces, run:

npm install

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.

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

Running the previewer#

Once installed UI Kit provides a build system and an asset pipeline. It also contains a previewer where all templates can be viewed. To start it run:

npm start

This will start the previewer and any changes made in the src directory of UI Kit will immediately be compiled, and reflected in the browser.

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 is controlled by Velocity variables. A good example is the sms enter-otp screen. It is located under src/identity-server/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.

Search screen in the previewer

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:

SMS Enter OTP Template

SMS Enter OTP Template

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

...
#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.

Set a context variable in the previewer

Set a context variable in the previewer

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

SMS Enter OTP screen with registration enabled

SMS Enter OTP screen with registration enabled

Overriding templates#

The structure in the source tree for templates mimics the deployment structure of the Curity Identity Server 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 src/identity-server/images/your-logo.svg
  2. Create the fragments folder in the overrides src directory src/identity-server/templates/overrides/fragments/logo.vm
  3. Update the content:
<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.

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 src/identity-server/templates/template-areas directory.

Example#

  1. Create a template area called myarea by adding the folder src/identity-server/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.

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 versions of the Curity Identity Server.

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 _area 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 installation ${IDSVR_DIR}/usr/share structure.

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.

Was this helpful?