Theming AM

The UI is built with the Bootstrap framework, and supports Bootstrap themes to customize the look and feel of the user interface.

Only user-facing UI pages support themes. The administration pages cannot be themed, although customizing the footer would alter the appearance for both user-facing and administration pages.

You can apply themes to specific realms, and also to specific authentication chains within those realms. AM includes a default theme, and an inverted dark theme.

To Apply a Theme to the UI

You can perform the steps of this procedure and edit the UI source code, or you can find the files as deployed inside the WAR file. The examples in the procedure use the source code paths, but you can find the referenced files in the /path/to/tomcat/webapps/openam/XUI directory of a deployed AM WAR file.

If you modify resources from the WAR file, you will see they have a hash value appended to them. For example, ThemeConfiguration.[hash].js. The hash value is an alphanumeric value generated each time the UI is rebuilt, to reference the CSS files in the theme, and to map the theme to realms and authentication services.

Perform the following steps to apply a theme to the UI:

Copy your custom Bootstrap theme to a directory in openam-ui-user/src/resources/themes. A custom Bootstrap theme should consist of one or more CSS files, and optionally, media and font files.
As an example, the dark theme is available in the openam-ui-user/src/resources/themes/dark directory.
Edit the openam-ui-user/src/js/config/ThemeConfiguration.js file:
1. Locate the themes element, and under it create a new element with the name of your theme. The following example adds a theme called myTheme:
```
return {
    themes: {
        // There must be a theme named "default".
        "default": { ...
        },
        "fr-dark-theme": { ...
        },
        "myTheme": {}
    },
    mappings: [...]
};
```
2. In the new theme element, create a stylesheets array containing the theme's two CSS files, followed by the required css/structure.css file.
```
return {
    themes: {
        // There must be a theme named "default".
        "default": { ...
        },
        "fr-dark-theme": { ...
        },
        "myTheme": {
            stylesheets: [
                "themes/myTheme/css/bootstrap.min.css",
                "themes/myTheme/css/myTheme.css",
                "css/structure.css"
            ]
        }
    },
    mappings: [...]
};
```
  Note that you must specify paths relative to the openam-ui-user/src/resources directory.
  If required, specify additional settings specific to the new theme, such as the logos to use or the footer information. For information on the available settings, see ThemeConfiguration.js Reference.
3. Locate the mappings array, and create a new element under it to map your new theme to realms and authentication chains.
  Elements in the mappings array are evaluated in order from top to bottom. The first theme that matches the current realm and/or authentication chain is applied. Any subsequent mappings, even if true, are ignored once a match is found.
  If no match is found, the default theme is applied.
  1. Create a theme element, and set the value to the name of your new theme:
```
return {
    themes: { ...
    },
    mappings: [{
        theme: "myTheme"
    }]
};
```
  2. (Optional) Create a realms array, and include the realms the theme will apply to:
```
return {
    themes: { ...
    },
    mappings: [{
        theme: "myTheme",
        realms: ["/", "/test-realm", /^\/a/]
    }]
};
```
    You can use a regular expression to specify the realms the theme should apply to. For example /^\/a/ will apply the theme to all realms that start with /a, including /ab and /a/c.
    If you do not include a realms array, the theme is applied to all realms.
  3. (Optional) Create an authenticationChains array, and include any authentication service (chains or trees) the theme applies to when used:
```
return {
    themes: { ...
    },
    mappings: [{
        theme: "myTheme",
        realms: ["/", "/test-realm", /^\/a/],
        authenticationChains: ["auth-chain-one", "Example-Tree"]
    }]
};
```
    If you specify both realms and authentication services, the theme is only applied when both criteria are true.
(Optional) Compile the UI project using the yarn build command.
(Optional) Start the development UI server to test the changes by following the steps detailed in "To Test UI Pages in a Development Server".
Log in as a user to see the new theme applied:
UI with the Dark Theme
(Optional) 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.