How To

How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

Last updated Apr 12, 2021

The purpose of this article is to provide information on adding a new custom XUI page. Custom XUI pages can be used to extend the functionality in AM/OpenAM.

3 readers recommend this article

This article has been archived and is no longer maintained by ForgeRock.

Adding an new custom UI page

The XUI uses require.js for modular JavaScript® loading, backbone.js for model/view binding and handlebars.js for templating.

The following steps demonstrate creating a XUI page in AM/OpenAM that includes some sample text.

  1. Create a routes file to introduce a new route to your view, for example: /path/to/tomcat/webapps/openam/XUI/config/routes/CustomAMRoutesConfig.js And define a route in this file, for example: define("config/routes/CustomAMRoutesConfig", [ ], function() { var obj = { "helloWorldView" : { view: "org/forgerock/openam/ui/custom/HelloWorldView", role: "ui-user", url: "helloWorld/" } }; return obj; });
  2. Update the AppConfiguration.js file (located in the /path/to/tomcat/webapps/openam/XUI/config/ directory) to add the new routes file to your Application Configuration; find the section that includes paths to the routes (~line 31) and add a new route:  { "routes": "config/routes/CustomAMRoutesConfig" }
  3. Create a view file, for example: /path/to/tomcat/webapps/openam/XUI/org/forgerock/openam/ui/custom/HelloWorldView.js And add your view code to this file, for example: define("org/forgerock/openam/ui/custom/HelloWorldView", [ "org/forgerock/commons/ui/common/main/AbstractView", "org/forgerock/commons/ui/common/main/Configuration", "org/forgerock/commons/ui/common/util/UIUtils" ], function(AbstractView) { var HelloWorldView = AbstractView.extend({ template: "templates/custom/HelloWorld.html", baseTemplate: "templates/common/DefaultBaseTemplate.html", events: { } }); return new HelloWorldView(); });
  4. Create a template file, for example: /path/to/tomcat/webapps/openam/XUI/templates/custom/HelloWorld.html And add some sample text to this file: <h2>Hello World!</h2> <p> Some sample text. </p>
  5. Clear your browser cache and restart the web application container in which AM/OpenAM runs to apply these changes. 

That's it. You should now be able to view the new view by navigating to #helloWorld/ after logging in, for example:

See Also

FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM

How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)?

How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

How do I change the title shown on the browser tab in AM (All versions) and OpenAM 13.x?

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.