Dynamic Themes

With the introduction of Service Management application, deployers are now able to switch the themes based on different services. For example, you may want to have different login screens (different styles) for staff applications and student applications. Or, you want to show two layouts for day time and night time. This document could help you go through the basic settings to achieve this.

Static Themes

CAS is configured to decorate views based on the theme property of a given registered service in the Service Registry. The theme that is activated via this method will still preserve the default views for CAS but will simply apply decorations such as CSS and Javascript to the views. The physical structure of views cannot be modified via this method.

Configuration

• Add a [theme_name].properties placed to the root of src/main/resources folder. Contents of this file should match the following:

1
2
3
cas.standard.css.file=/themes/[theme_name]/css/cas.css
cas.javascript.file=/themes/[theme_name]/js/cas.js
cas.admin.css.file=/themes/[theme-name]/css/admin.css

• Create the directory src/main/resources/static/themes/[theme_name]. Put the theme-specific cas.css and cas.js inside the appropriate directories for css and js.
• Specify [theme_name] for the service definition under the theme property.

1
2
3
4
5
6
7
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "^https://www.example.org",
  "name" : "MyTheme",
  "theme" : "[theme_name]",
  "id" : 1000
}

Themed Views

CAS can also utilize a service’s associated theme to selectively choose which set of UI views will be used to generate the standard views (casLoginView.html, etc). This is specially useful in cases where the set of pages for a theme that are targeted for a different type of audience are entirely different structurally that simply using a simple theme is not practical to augment the default views. In such cases, new view pages may be required.

Views associated with a particular theme by default are expected to be found at: src/main/resources/templates/<theme-id>. Note that CAS views and theme-based views may both be externalized out of the web application context. When externalized, themed views are expected to be found at the specified path via CAS properties under a directory named after the theme. For instance, if the external path for CAS views is /etc/cas/templates, view template files for theme sample may be located /etc/cas/templates/sample/.

To see the relevant list of CAS properties, please review this guide.

Configuration

• Add a [theme_name].properties placed to the root of src/main/resources folder. Contents of this file should match the following:

1
2
3
cas.standard.css.file=/themes/[theme_name]/css/cas.css
cas.javascript.file=/themes/[theme_name]/js/cas.js
cas.admin.css.file=/themes/[theme-name]/css/admin.css

• Clone the default set of view pages into a new directory based on the theme id (i.e. src/main/resources/templates/<theme-id>).
• Specify the name of your theme for the service definition under the theme property.

Groovy Themes

If you have multiple themes defined, it may be desirable to dynamically determine a theme for a given service definition. In order to do, you may calculate the final theme name via a Groovy script of your own design. The theme assigned to the service definition needs to point to the location of the script:

1
2
3
4
5
6
7
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "^https://www.example.org",
  "name" : "MyTheme",
  "theme" : "file:///etc/cas/config/themes.groovy",
  "id" : 1000
}

The script itself may be designed as:

1
2
3
4
5
6
7
8
9
10
11
12
13
import java.util.*

def String run(final Object... args) {
    def service = args[0]
    def registeredService = args[1]
    def queryStrings = args[2]
    def headers = args[3]
    def logger = args[4]

    // Determine theme ...

    return null
}

Returning null or blank will have CAS switch to the default theme. The following parameters may be passed to a Groovy script:

RESTful Themes

Somewhat similar to the above option, you may calculate the final theme name via a REST endpoint of your own design. The theme assigned to the service definition needs to point to the location of the REST API. Endpoints must be designed to accept/process application/json via GET requests. A returned status code 200 allows CAS to read the body of the response to determine the theme name. Empty response bodies will have CAS switch to the default theme.

1
2
3
4
5
6
7
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "^https://www.example.org",
  "name" : "MyTheme",
  "theme" : "https://themes.example.org",
  "id" : 1000
}

The following parameters may be passed to a Groovy script: