3.4. Creating a Theme
A theme consists of:
- HTML templates (Freemarker Templates)
- Images
- Message bundles
- Stylesheets
- Scripts
- Theme properties
Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the Red Hat Single Sign-On theme, but you could also consider extending the base theme if you are significantly changing the look and feel of the pages. The base theme primarily consists of HTML templates and message bundles, while the Red Hat Single Sign-On theme primarily contains images and stylesheets.
When extending a theme you can override individual resources (templates, stylesheets, etc.). If you decide to override HTML templates bear in mind that you may need to update your custom template when upgrading to a new release.
While creating a theme it’s a good idea to disable caching as this makes it possible to edit theme resources directly from the themes
directory without restarting Red Hat Single Sign-On. To do this edit standalone.xml
. For theme
set staticMaxAge
to -1
and both cacheTemplates
and cacheThemes
to false
:
<theme> <staticMaxAge>-1</staticMaxAge> <cacheThemes>false</cacheThemes> <cacheTemplates>false</cacheTemplates> ... </theme>
Remember to re-enable caching in production as it will significantly impact performance.
To create a new theme start by creating a new directory in the themes
directory. The name of the directory becomes the name of the theme. For example to create a theme called mytheme
create the directory themes/mytheme
.
Inside the theme directory create a directory for each of the types your theme is going to provide. For example to add the login type to the mytheme
theme create the directory themes/mytheme/login
.
For each type create a file theme.properties
which allows setting some configuration for the theme. For example to configure the theme themes/mytheme/login
that we just created to extend the base theme and import some common resources create the file themes/mytheme/login/theme.properties
with following contents:
parent=base import=common/keycloak
You have now created a theme with support for the login type. To check that it works open the admin console. Select your realm and click on Themes
. For Login Theme
select mytheme
and click Save
. Then open the login page for the realm.
You can do this either by login through your application or by opening the Account Management console (/realms/{realm name}/account
).
To see the effect of changing the parent theme, set parent=keycloak
in theme.properties
and refresh the login page.
3.4.1. Theme Properties
Theme properties are set in the file <THEME TYPE>/theme.properties
in the theme directory.
- parent - Parent theme to extend
- import - Import resources from another theme
- styles - Space-separated list of styles to include
- locales - Comma-separated list of supported locales
There are a list of properties that can be used to change the css class used for certain element types. For a list of these properties look at the theme.properties file in the corresponding type of the keycloak theme (themes/keycloak/<THEME TYPE>/theme.properties
).
You can also add your own custom properties and use them from custom templates.
When doing so, you can substitute system properties or environment variables by using these formats:
-
${some.system.property}
- for system properties -
${env.ENV_VAR}
- for environment variables.
A default value can also be provided in case the system property or the environment variable is not found with ${foo:defaultValue}
.
If no default value is provided and there’s no corresponding system property or environment variable, then nothing is replaced and you end up with the format in your template.
Here’s an example of what is possible:
javaVersion=${java.version} unixHome=${env.HOME:Unix home not found} windowsHome=${env.HOMEPATH:Windows home not found}