Customizing the UI Layout

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 Downloading the UI.

2. Modify the UI source as follows:

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

      Tip

      You can modify the original files, but it is recommended to create a new theme containing your changes.

   2. 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:

      "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"
              }
          }
      }

      Important

      Specify resource paths within the theme configuration as relative to the openam-ui-user/src/resources/ directory.

   3. 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:

      mappings: [
          { theme: "myTheme", realms: ["/"] }
      ]

      For more information about the format of the ThemeConfiguration.js file, see ThemeConfiguration.js Reference.

   4. Copy the template file that contains the HTML code for the footer, openam-ui-user/src/resources/themes/default/templates/common/FooterTemplate.html, file into the same path but within the myTheme directory, for example:

      $ cp openam-ui-user/src/resources/themes/default/templates/common/FooterTemplate.html openam-ui-user/src/resources/themes/myTheme/templates/common/FooterTemplate.html

   5. Add a table, containing an image, in the new FooterTemplate.html file, as follows:

      <div class="container">
          <p>
              <table align="center">
                  <td>
                      <img src="{{theme.settings.footer.icon}}" alt="Horizontal ForgeRock Logo" align="middle" class="footer_image">
                  </td>
                  <td>
                      <b>ForgeRock XUI at Example.com</b>
                      <br/>
                      <a href="mailto: {{theme.settings.footer.mailto}}">Send us Feedback!</a>
                  </td>
              </table>
          </p>
      </div>

      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.

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

      Note

      AM uses the partials and templates from the /themes/default directory if an equivalent file is not found in your customized theme.

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

      .footer_image {
          height: 3em;
          padding-right: 1em;
      }

3. Rebuild the UI by running the yarn build command.

   Tip

   If you receive errors during the build, you may be missing the required components locally. Try running yarn install, and then try again.

4. (Optional) Test the UI pages by following the steps detailed in "To Test UI Pages in a Development Server".

   You can now see the customized template in the login page:

   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/openam/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.