Customizations using JavaScript in the Loginapp REST UI SDK

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

JavaScript customizations

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.

API	Registers with	Purpose
iam.api.types.CustomLayout	iam.api.types.registerLayout	Customizing the layout of an existing page. In particular: ● Header ● Footer ● Content Frame See: 17.3.2.4.3. Customization of the Loginapp REST UI layout using default HTML files
iam.api.types.CustomProductPage	iam.api.types.registerPage	Modify or extend an existing page of the Loginapp REST UI. Examples: ● Adding new UI elements to a page, e.g. a subtitle. ● Changing the order UI elements. ● Adding dynamic behavior, e.g. a password meter. See: 17.3.2.4.4.2. Customizing an existing product page using the Loginapp REST UI SDK
iam.api.types.CustomJavaScriptPage	iam.api.types.registerPage	Provide an entirely new page written in JavaScript. The difference between changing an existing page and adding a new page is all about the control of the flow in the Loginapp REST UI. Existing Page: ● Flow control remains under the control of the product. The Loginapp REST UI will call all registered and applicable methods during all lifecycle events that require them. NewPage: ● Flow control is handed to the JavaScript Code of the new Page. The page must provide the content and potential function after the rendering of the page. The page must also deal with both successful and unsuccessful flow responses. See: 17.3.2.4.4.3. Adding new pages using the Loginapp REST UI SDK

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 semantic of those methods are described in detail. Note that methods that are not explicitly described in this documentation are considered internal and may change any time without further notice.

Applying customization

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 in the page that is to be rendered at this point. If none of the customizations return true, the default customization from the product are being used.

Avoid constructors

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.

Browser caching

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.

Use of libraries

The Loginapp REST UI SDK currently does not provide a mechanism to include 3rd party JavaScript libraries. For now, libraries have to be part of iam-custom.js.