[keycloak-dev] Theme support for forms

[Stian Thorgersen]

As forms and the account management console are aimed at end-users it's important that it's easy for developers to customize the look and feel of these so they integrate well with their organizations and applications.

This is one of the main reasons we're using a template engine instead of a web framework. We've chosen FreeMarker as it seems to be relatively popular, is powerful and at the same time has a relatively low learning curve.

For the next release I'm going to add support for themes to the forms. As part of this I'd like to split the forms (login, registration, etc.) and account management into two separate maven modules. Initially I'll focus on adding theme support for the forms, but shouldn't be a problem to add support for both in the next release.

A theme will consist of:

* theme.properties - standard java properties file with theme name, name of theme it extends, etc. Can also contain theme specific config options
* css
* images
* messages
* pages

A theme can extend another theme, in which case it can override specific resources in the theme. For example a theme could consist of nothing but "theme.properties" and "css/styles.css". In fact this will be the recommended approach as in most cases it should be possible to do the required customization using css (anyone that doubt's this can have a look at http://www.csszengarden.com/ to see what can be achieved with css).

If needed a theme can override pages as well, this will be html pages with the addition of FreeMarker syntax. All pages can be overridden, or just individual pages.

A theme can be packaged as a ZIP, then copied into a specific directory or uploaded through the admin console. It will also be possible to package a theme as a JAR and add as a dependency, in which case we'll use ServiceLoader to discover themes on the class-path (this is how the default theme will be packaged to make sure it's easily available).

There will also be an SPI to allow replacing FreeMarker with whatever you want. We'll provide one implementation which is what's described above. This will probably be left for later though.

Finally, through the admin console it will be possible to set what theme to use for a realm. Initially this will only be setting the theme name, but in the future we may also support configuring theme properties. The default theme when creating a new realm will be the Keycloak theme.