0
# CAS Themes Support
1

2
The CAS Themes Support library provides comprehensive theme management capabilities for the Central Authentication Service (CAS). It enables dynamic theme selection based on multiple strategies including registered service configurations, browser cookies, HTTP session attributes, request headers, and fixed configuration settings.
3

4
## Package Information
5

6
- **Package Name**: org.apereo.cas:cas-server-support-themes
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Gradle or Maven dependencies
10

11
**Gradle:**
12
```gradle
13
implementation 'org.apereo.cas:cas-server-support-themes:7.2.4'
14
```
15

16
**Maven:**
17
```xml
18
<dependency>
19
    <groupId>org.apereo.cas</groupId>
20
    <artifactId>cas-server-support-themes</artifactId>
21
    <version>7.2.4</version>
22
</dependency>
23
```
24

25
## Core Imports
26

27
```java
28
// Main Configuration
29
import org.apereo.cas.config.CasThemesAutoConfiguration;
30

31
// Theme Sources
32
import org.apereo.cas.services.web.DefaultCasThemeSource;
33
import org.apereo.cas.services.web.AggregateCasThemeSource;
34
import org.apereo.cas.services.web.CasThemeResourceBundleMessageSource;
35

36
// Theme Resolvers
37
import org.apereo.cas.services.web.ChainingThemeResolver;
38
import org.apereo.cas.services.web.RegisteredServiceThemeResolver;
39
import org.apereo.cas.services.web.RequestHeaderThemeResolver;
40

41
// Configuration Properties
42
import org.apereo.cas.configuration.CasConfigurationProperties;
43
import org.apereo.cas.configuration.model.support.themes.ThemeProperties;
44
import org.apereo.cas.configuration.model.core.web.view.ViewProperties;
45

46
// CAS Services API (for service-based theme resolution)
47
import org.apereo.cas.services.ServicesManager;
48
import org.apereo.cas.services.WebBasedRegisteredService;
49
import org.apereo.cas.authentication.AuthenticationServiceSelectionPlan;
50
import org.apereo.cas.authentication.principal.Service;
51

52
// Spring Framework Types
53
import org.springframework.ui.context.ThemeSource;
54
import org.springframework.web.servlet.ThemeResolver;
55
import org.springframework.web.servlet.theme.AbstractThemeResolver;
56
import org.springframework.ui.context.support.ResourceBundleThemeSource;
57
```
58

59
## Basic Usage
60

61
```java
62
import org.apereo.cas.services.web.ChainingThemeResolver;
63
import org.apereo.cas.services.web.DefaultCasThemeSource;
64
import org.apereo.cas.configuration.CasConfigurationProperties;
65
import org.springframework.web.servlet.theme.CookieThemeResolver;
66
import org.springframework.web.servlet.theme.SessionThemeResolver;
67

68
// Basic theme source setup
69
CasConfigurationProperties casProperties = // ... obtained from Spring context
70
DefaultCasThemeSource themeSource = new DefaultCasThemeSource(casProperties);
71

72
// Create a chaining theme resolver with multiple strategies
73
ChainingThemeResolver chainResolver = new ChainingThemeResolver();
74
chainResolver.setDefaultThemeName("cas-theme-default");
75

76
// Add cookie-based theme resolution
77
CookieThemeResolver cookieResolver = new CookieThemeResolver();
78
cookieResolver.setDefaultThemeName("cas-theme-default");
79
chainResolver.addResolver(cookieResolver);
80

81
// Add session-based theme resolution  
82
SessionThemeResolver sessionResolver = new SessionThemeResolver();
83
sessionResolver.setDefaultThemeName("cas-theme-default");
84
chainResolver.addResolver(sessionResolver);
85

86
// Resolve theme from HTTP request
87
String themeName = chainResolver.resolveThemeName(request);
88
System.out.println("Resolved theme: " + themeName);
89

90
// Get theme resources
91
Theme theme = themeSource.getTheme(themeName);
92
MessageSource messageSource = theme.getMessageSource();
93
String welcomeMessage = messageSource.getMessage("login.welcome", null, 
94
    "Welcome", request.getLocale());
95
```
96

97
## Architecture
98

99
The CAS Themes Support library is built around several key components:
100

101
- **Auto-Configuration**: Spring Boot auto-configuration (`CasThemesAutoConfiguration`) that automatically sets up theme resolution based on properties
102
- **Theme Sources**: Implementations that load theme properties and resources (`DefaultCasThemeSource`, `AggregateCasThemeSource`)
103
- **Theme Resolvers**: Chain of responsibility pattern for theme resolution using multiple strategies (`ChainingThemeResolver`)
104
- **Resolution Strategies**: Individual resolvers for different theme selection methods (cookie, session, service-based, header-based)
105
- **Resource Management**: Static resource handling with caching and versioning support
106

107
## Capabilities
108

109
### Auto-Configuration
110

111
Spring Boot auto-configuration that sets up theme resolution beans automatically based on CAS configuration properties.
112

113
```java { .api }
114
@AutoConfiguration
115
@ConditionalOnFeatureEnabled(feature = CasFeatureModule.FeatureCatalog.Thymeleaf)
116
public class CasThemesAutoConfiguration {
117
    
118
    @Bean
119
    @ConditionalOnMissingBean(name = "casThemeSource")
120
    @RefreshScope(proxyMode = ScopedProxyMode.DEFAULT)
121
    public ThemeSource themeSource(CasConfigurationProperties casProperties);
122
    
123
    @Bean
124
    @ConditionalOnMissingBean(name = "casThemeResolver")
125
    @RefreshScope(proxyMode = ScopedProxyMode.DEFAULT)
126
    public ThemeResolver themeResolver(
127
        ObjectProvider<CasConfigurationProperties> casProperties,
128
        ObjectProvider<AuthenticationServiceSelectionPlan> authenticationRequestServiceSelectionStrategies,
129
        ObjectProvider<ServicesManager> servicesManager);
130
}
131
```
132

133
[Auto-Configuration](./auto-configuration.md)
134

135
### Theme Sources
136

137
Theme source implementations that load and manage theme properties and resources from various locations.
138

139
```java { .api }
140
public class DefaultCasThemeSource extends ResourceBundleThemeSource {
141
    public DefaultCasThemeSource(CasConfigurationProperties casProperties);
142
    
143
    @Override
144
    protected MessageSource createMessageSource(@Nonnull String basename);
145
}
146

147
public class AggregateCasThemeSource extends ResourceBundleThemeSource {
148
    public AggregateCasThemeSource(CasConfigurationProperties casProperties);
149
    
150
    @Override  
151
    protected MessageSource createMessageSource(@Nonnull String basename);
152
}
153
```
154

155
[Theme Sources](./theme-sources.md)
156

157
### Theme Resolution
158

159
Chain-based theme resolution system that evaluates multiple resolution strategies in priority order.
160

161
```java { .api }
162
public class ChainingThemeResolver extends AbstractThemeResolver {
163
    public ChainingThemeResolver addResolver(ThemeResolver r);
164
    
165
    @Override
166
    public String resolveThemeName(@Nonnull HttpServletRequest httpServletRequest);
167
    
168
    @Override
169
    public void setThemeName(@Nonnull HttpServletRequest httpServletRequest, 
170
                           HttpServletResponse httpServletResponse, String s);
171
}
172
```
173

174
[Theme Resolution](./theme-resolution.md)
175

176
### Service-Based Theme Resolution  
177

178
Advanced theme resolution based on registered service configurations, supporting Groovy scripts and HTTP URLs for dynamic theme selection.
179

180
```java { .api }
181
public class RegisteredServiceThemeResolver extends AbstractThemeResolver {
182
    public RegisteredServiceThemeResolver(
183
        ObjectProvider<ServicesManager> servicesManager,
184
        ObjectProvider<AuthenticationServiceSelectionPlan> authenticationRequestServiceSelectionStrategies,
185
        ObjectProvider<CasConfigurationProperties> casProperties);
186
    
187
    @Override
188
    public String resolveThemeName(@Nonnull HttpServletRequest request);
189
}
190
```
191

192
[Service-Based Theme Resolution](./service-theme-resolution.md)
193

194
### Header-Based Theme Resolution
195

196
Simple theme resolution that extracts theme names from HTTP request headers.
197

198
```java { .api }
199
public class RequestHeaderThemeResolver extends AbstractThemeResolver {
200
    public RequestHeaderThemeResolver(String themeHeaderName);
201
    
202
    @Override
203
    public String resolveThemeName(HttpServletRequest request);
204
}
205
```
206

207
[Header-Based Theme Resolution](./header-theme-resolution.md)
208

209
## Types
210

211
```java { .api }
212
// Spring Framework Types
213
interface ThemeSource {
214
    Theme getTheme(String themeName);
215
}
216

217
interface Theme {
218
    String getName();
219
    MessageSource getMessageSource();
220
}
221

222
interface ThemeResolver {
223
    String resolveThemeName(HttpServletRequest request);
224
    void setThemeName(HttpServletRequest request, HttpServletResponse response, String themeName);
225
}
226

227
abstract class AbstractThemeResolver implements ThemeResolver {
228
    String getDefaultThemeName();
229
    void setDefaultThemeName(String defaultThemeName);
230
}
231

232
class ResourceBundleThemeSource implements ThemeSource {
233
    String getBasenamePrefix();
234
    void setBasenamePrefix(String basenamePrefix);
235
    protected MessageSource createMessageSource(String basename);
236
}
237

238
// CAS Services Types
239
interface Service {
240
    String getId();
241
}
242

243
interface ServicesManager {
244
    RegisteredService findServiceBy(Service service);
245
}
246

247
class WebBasedRegisteredService extends BaseRegisteredService {
248
    String getTheme();
249
    void setTheme(String theme);
250
    RegisteredServiceAccessStrategy getAccessStrategy();
251
}
252

253
interface AuthenticationServiceSelectionPlan {
254
    Service resolveService(Service service);
255
}
256

257
// CAS Configuration Types  
258
class CasConfigurationProperties {
259
    ThemeProperties getTheme();
260
    ViewProperties getView();
261
    TgcProperties getTgc();
262
}
263

264
class ThemeProperties {
265
    String getDefaultThemeName();    // Default: "cas-theme-default"
266
    String getParamName();          // Default: "theme"
267
}
268

269
class ViewProperties {
270
    List<String> getTemplatePrefixes();
271
    ThemeSourceTypes getThemeSourceType();  // Default: DEFAULT
272
    
273
    enum ThemeSourceTypes {
274
        DEFAULT,     // Use DefaultCasThemeSource
275
        AGGREGATE    // Use AggregateCasThemeSource
276
    }
277
}
278

279
class TgcProperties {
280
    String getDomain();
281
    boolean isHttpOnly();
282
    String getMaxAge();
283
    String getPath();
284
    boolean isSecure();
285
}
286

287
// Spring Web Types
288
class HttpServletRequest {
289
    String getHeader(String name);
290
    String getQueryString();
291
    Locale getLocale();
292
    void setAttribute(String name, Object value);
293
}
294

295
class HttpServletResponse {
296
    // HTTP response methods
297
}
298

299
interface MessageSource {
300
    String getMessage(String code, Object[] args, String defaultMessage, Locale locale);
301
}
302

303
class StaticMessageSource implements MessageSource {
304
    void addMessage(String code, Locale locale, String msg);
305
}
306
```