--- title: Customize the UI layout description: To perform basic customizations, edit the openam-ui-user/src/js/config/ThemeConfiguration.js and then rebuild the UI. component: pingam version: 8.1 page_id: pingam:ui-customization:ui-customizing-layout canonical_url: https://docs.pingidentity.com/pingam/8.1/ui-customization/ui-customizing-layout.html keywords: ["User Interface", "Customization", "Source Code"] page_aliases: ["ui-customization-guide:ui-customizing-layout.adoc"] --- # Customize the UI layout To perform basic customizations, edit the `openam-ui-user/src/js/config/ThemeConfiguration.js` and then rebuild the UI. > **Collapse: ThemeConfiguration.js reference** > > The file contains a full configuration for the mandatory `default` theme. Additional themes should use a duplicate of the default theme's configuration. Any parameters that are not configured will inherit values from the mandatory `default` theme. > > The available parameters for each theme in the file are as follows: > > * `themes`: Title; also represents an array of theme objects. > > * *name*: Theme title. > > * `stylesheets`: An ordered array of URLs to CSS stylesheet files that are applied to every page. It is highly recommended to include the variable `StructureStyle` as one of the entries to provide default styles for layout and structure. > > For example: `["themes/dark/css/bootstrap.min.css", StructureStyle, "themes/dark/css/theme-dark.css"]` > > * `path`: A path relative to the `openam-ui-user/src/resources/themes` folder, that contains `templates` or `partials` directories, used for customizing the default layout of UI pages. The path must include a trailing slash character `/` . > > For example, `["theme-path/"]`. > > * `icon`: URL to a resource to use as a favicon. > > * `settings`: Configuration settings for the theme. Missing parameters inherit their value from the mandatory `default` theme. > > * `logo`: Parameters for the logo displayed on user profile pages. > > * `src`: Filename of the logo. > > * `title`: HTML `title` attribute of the logo. > > * `alt`: HTML `alt` attribute of the logo. > > * `height`: Logo height in CSS notation. For example: `75px` or `10%`. > > * `width`: Logo width in CSS notation. For example: `150px` or `25%`. > > * `loginLogo`: Parameters for the logo displayed on login pages. > > * `src`: Filename of the logo. > > * `title`: HTML `title` attribute of the logo. > > * `alt`: HTML `alt` attribute of the logo. > > * `height`: Logo height in CSS notation. For example: `75px` or `10%`. > > * `width`: Logo width in CSS notation. For example: `150px` or `25%`. > > * `footer`: Parameters to display in the footer of each UI page. > > * `mailto`: Email address. > > * `phone`: Telephone number. This procedure demonstrates how to customize the layout of UI pages by copying the relevant files into a theme, editing the source, and making changes to the CSS. 1. Download the UI source code as explained in [Download the UI source](downloading-ui.html). 2. Modify the UI source as follows: * Copy the `src/resources/themes/dark` directory to a new directory with a suitable name for the theme that contains your customizations, for example, `myTheme`. | | | | - | ------------------------------------------------------------------------------------------------------- | | | You can modify the original files, but it is recommended to create a new theme containing your changes. | * Edit the `openam-ui-user/src/js/config/ThemeConfiguration.js` file, which contains the configuration the UI uses when applying a theme, and make a copy of the `"fr-dark-theme"` section, named after the directory you created in the previous step (`"myTheme"`). In this example, in the `footer` element, change the email address to `Feedback@example.com`, and add a new element called `icon` that points to an icon to display in the footer. Alter the `path` property to point to the name of the directory you created in the `themes` directory earlier, including a trailing slash. For example `myTheme/`. The new section will resemble the following: ```none "myTheme": { // An ordered list of URLs to stylesheets that will be applied to every page. stylesheets: [ "themes/myTheme/css/bootstrap.min.css", StructureStyle, "themes/myTheme/css/theme-dark.css" ], // A path that is prepended to every relative URL when fetching resources (including images, stylesheets and // HTML template files). Must include a trailing forward slash. path: "myTheme/", settings: { loginLogo: { src: "themes/myTheme/images/login-logo-white.png", title: "ForgeRock", alt: "ForgeRock", height: "228px", width: "220px" }, footer: { // A contact email address. mailto:"Feedback@example.com", // The footer icon. icon : "images/logo-horizontal.png" } } } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------- | | | Specify resource paths within the theme configuration as relative to the `openam-ui-user/src/resources/` directory. | * Edit the `mappings` section of the `ThemeConfiguration.js` file to apply the new theme to the required contexts. For example, to apply the theme to the Top Level Realm, use: ```none mappings: [ { theme: "myTheme", realms: ["/"] } ] ``` For more information about the format of the `ThemeConfiguration.js`file, see [ThemeConfiguration.js reference](#ui-customizing-config-parameters). * Copy the template file that contains the HTML code for the footer, `openam-ui-user/src/resources/themes/default/templates/common/FooterTemplate.html`, into the same path but within the `myTheme` directory, for example: ```bash $ cp openam-ui-user/src/resources/themes/default/templates/common/FooterTemplate.html \ openam-ui-user/src/resources/themes/myTheme/templates/common/FooterTemplate.html ``` * Add a table, containing an image, in the new `FooterTemplate.html` file, as follows: ```html

Horizontal ForgeRock Logo ForgeRock XUI at Example.com
Send us Feedback!

``` The file contains variables expressed in double curly brackets (`{{}}`); they are the paths defined in the `ThemeConfiguration.js` file. Notice that the image has the `footer_image` CSS class applied to simplify applying a style to it in the next step. * Copy and edit any additional files that require customization from the `/themes/default/templates` and `/themes/default/partials` directories to the equivalent path in your `themes` directory. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------ | | | AM uses the partials and templates from the `/themes/default` directory if an equivalent file is not found in your customized theme. | * Edit the `/am-external/openam-ui/openam-ui-user/src/resources/themes/myTheme/css/theme-dark.css` file to specify the height of the image, and add padding to the `footer_image` class. For example: ```css .footer_image { height: 3em; padding-right: 1em; } ``` 3. Rebuild the UI by running the `yarn build` command. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------- | | | If you receive errors during the build, you may be missing the required components locally. Try running `yarn install`, and then try again. | 4. Test the UI pages by following the steps detailed in [Test UI pages in a development server](ui-testing-deploying.html#xui-dev-server). You can now see the customized template in the login page: ![Example of a customized template](_images/footer-example.png)Figure 1. Example of a customized template 5. Once you are satisfied with the changes, deploy the output in the `build` directory to the `/path/to/tomcat/webapps/am/XUI/` directory of your AM instances. There is no need to restart the AM instance. Subsequent visits to the UI pages will use the rebuilt files.