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.
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:Locate the
themes
element, and under it create a new element with the name of your theme. The following example adds a theme calledmyTheme
:return { themes: { // There must be a theme named "default". "default": { ... }, "fr-dark-theme": { ... }, "myTheme": {} }, mappings: [...] };
In the new theme element, create a
stylesheets
array containing the theme's two CSS files, followed by the requiredcss/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.
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.Create a
theme
element, and set the value to the name of your new theme:return { themes: { ... }, mappings: [{ theme: "myTheme" }] };
(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.
(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:
(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.