Customizations using JavaScript in the Loginapp REST UI SDK

The Loginapp REST UI SDK provides more powerful and advanced types of customizations using JavaScript.

To enable customizations in JavaScript, the Loginapp REST UI SDK provides a file to contain all JavaScript code located at:
$CUSTOM_DIRECTORY/src/assets/custom/js/iam-custom.js

Programmatically, the following classes are intended as an API to extend from. API classes are characterized by having api in their namespace.

Every custom class must be registered before it can be used.

iam.api.types.CustomLayout

iam.api.customizing.registerLayout

iam.api.types.CustomProductPage

iam.api.customizing.registerPage

iam.api.types.CustomJavaScriptPage

iam.api.customizing.registerPage

These are classes using JavaScripts ES6 class declarations. In custom code, they are meant to be extended. To implement custom behavior, methods can be overwritten.

In the remainder of this documentation, the available methods and the semantics of those methods are described in detail. Note that methods that are not explicitly described in this documentation are considered internal and may change without further notice.

For larger projects or more advanced customizations, writing all JavaScript in just one large file can become confusing. The REST UI SDK, therefore, supports the usage of JavaScript modules allowing to modularize code into separate JavaScript files containing functions or classes. The use of JavaScript modules is also advantageous to include 3rd party JavaScript libraries.

With JavaScript modules, you may, e.g., keep a separate JavaScript file per CustomJavaScriptPage, CustomProductPage, or CustomLayout.

Example:
Instead of having the code of a page directly in iam-custom.js, it can be extracted to a separate file like my-custom-password-page.js where the class MyCustomPasswordPage is made accessible to other JavaScript modules using the export keyword.

copy

export class MyCustomPasswordPage extends iam.api.types.CustomProductPage { 
 
    isApplicable({pageId, flowId, stepId}) { 
        return pageId === 'iamAuthPassword'; // Only apply to the password page 
    } 
 
    onPageEnter() { 
        console.log('This is just an example'); 
    } 
}

In iam-custom.js , the file can be referenced and the exported class MyCustomPasswordPage can be imported using the import keyword:

copy

import {MyCustomPasswordPage} from './my-custom-password-page.js'; 
 
iam.api.customizing.initialize = function () { 
    iam.api.customizing.registerPage(new MyCustomPasswordPage()); 
};

Note that in this example, my-custom-password-page.js is located in the same folder as iam-custom.js. However, you may choose any folder or folder structure for your additional JavaScript files as long as they reside within the assets folder.

More specifically, it is recommended to choose $CUSTOM_DIRECTORY/src/assets/custom/js as the parent folder for all your JavaScript files or nested folders containing JavaScript.

Note that API methods like iam.api.customizing.registerPage or iam.api.customizing.registerLayout can only be invoked when called within iam.api.customizing.initialize.

To make the JavaScript customization of the Loginapp REST UI flexible (i.e. specific to only a certain page or flow), every customization must provide a method isApplicable . This method is called with the current values of flowId, stepId and pageId and returns either true or false. With this method, the Loginapp REST UI is able to determine if a registered customization is to be applied to the page that is to be rendered at this point. If none of the customizations return true, the default customization from the product is used.

Like most programming languages, ES6 classes provide constructors that are invoked when instantiating an object. When extending from classes provided by IAM as an API, it is highly recommended to avoid using the constructor for HTML rendering and application logic. At the moment the constructor is invoked, the rest of the Loginapp REST UI usually is not yet ready. Also, the constructor is only invoked once whereas custom implementations are expected to work on multiple pages, e.g. for a layout.

Instead of using the constructor, stick to the methods provided as API.

IAM by default sets caching headers for static assets like images, fonts, etc. For assets used through SASS, the caching is automatically handled correctly. During the compilation from SASS to CSS, every asset name is extended with a hash value. Changes in assets will change the hash value and therefore change file names. This forces all browsers to download the new asset.

Care should be taken when using static files in HTML that are injected through JavaScript (e.g. using custom blocks or in render methods). If such an approach is taken, these files must be versioned manually to deal with browser caching correctly.

To avoid problems with caching, it is recommended to use SASS whenever possible.