CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-apereo-cas--cas-server-support-themes

Apereo CAS Web Application Themes Support - Provides comprehensive theme resolution and management capabilities for the Central Authentication Service

Pending
Overview
Eval results
Files

theme-resolution.mddocs/

Theme Resolution

Chain-based theme resolution system that evaluates multiple resolution strategies in priority order to determine the appropriate theme for each request.

Capabilities

ChainingThemeResolver

Theme resolver that chains multiple resolvers and returns the first non-default result.

/**
 * Theme resolver that chains multiple resolvers using chain of responsibility pattern
 */
public class ChainingThemeResolver extends AbstractThemeResolver {
    
    /**
     * Default constructor creating empty resolver chain
     */
    public ChainingThemeResolver();
    
    /**
     * Adds resolver to the chain for evaluation
     * @param r Theme resolver to add to the chain
     * @return This ChainingThemeResolver for method chaining
     */
    @CanIgnoreReturnValue
    public ChainingThemeResolver addResolver(ThemeResolver r);
    
    /**
     * Resolves theme name by trying each resolver in chain order
     * @param httpServletRequest HTTP request to resolve theme for
     * @return Theme name from first resolver returning non-default result, or default theme
     */
    @Override
    public String resolveThemeName(@Nonnull HttpServletRequest httpServletRequest);
    
    /**
     * No-op implementation for theme setting - theme is resolved, not set
     * @param httpServletRequest HTTP request
     * @param httpServletResponse HTTP response  
     * @param s Theme name
     */
    @Override
    public void setThemeName(@Nonnull HttpServletRequest httpServletRequest, 
                           HttpServletResponse httpServletResponse, String s);
}

Usage Examples:

import org.apereo.cas.services.web.ChainingThemeResolver;
import org.springframework.web.servlet.theme.CookieThemeResolver;
import org.springframework.web.servlet.theme.SessionThemeResolver;
import org.springframework.web.servlet.theme.FixedThemeResolver;

// Create chaining resolver
ChainingThemeResolver chainResolver = new ChainingThemeResolver();
chainResolver.setDefaultThemeName("default");

// Add resolvers in priority order
CookieThemeResolver cookieResolver = new CookieThemeResolver();
cookieResolver.setDefaultThemeName("default");
chainResolver.addResolver(cookieResolver);

SessionThemeResolver sessionResolver = new SessionThemeResolver();  
sessionResolver.setDefaultThemeName("default");
chainResolver.addResolver(sessionResolver);

FixedThemeResolver fixedResolver = new FixedThemeResolver();
fixedResolver.setDefaultThemeName("default");
chainResolver.addResolver(fixedResolver);

// Resolve theme for request
String themeName = chainResolver.resolveThemeName(request);

Resolution Chain Strategy

The ChainingThemeResolver evaluates resolvers in the order they were added:

  1. First Match Wins: Returns theme from first resolver that returns non-default theme
  2. Skip Default: Continues chain if resolver returns the configured default theme name
  3. Final Fallback: Returns default theme if no resolver provides a specific theme
// Example evaluation flow:
// 1. CookieThemeResolver returns "default" -> continue
// 2. SessionThemeResolver returns "dark" -> return "dark"
// 3. Remaining resolvers are not evaluated

Standard Resolution Chain

A typical CAS theme resolution chain includes:

  1. Cookie Theme Resolver - Highest priority, user preference persistence
  2. Session Theme Resolver - Session-scoped theme selection
  3. Request Header Theme Resolver - API-driven theme selection
  4. Registered Service Theme Resolver - Service-specific themes
  5. Fixed Theme Resolver - Default fallback theme
// Standard chain configuration (as done by auto-configuration)
chainResolver
    .addResolver(cookieThemeResolver)      // Priority 1
    .addResolver(sessionThemeResolver)     // Priority 2  
    .addResolver(headerThemeResolver)      // Priority 3
    .addResolver(serviceThemeResolver)     // Priority 4
    .addResolver(fixedThemeResolver);      // Priority 5 (fallback)

Theme Resolution Behavior

Default Theme Handling

  • Each resolver has a configured defaultThemeName
  • Chain continues evaluation when resolver returns default theme
  • Final fallback is the chain's own default theme

Theme Name Validation

  • No built-in theme name validation
  • Theme names are passed through as-is
  • Theme existence validation happens at theme source level

Request Context

Theme resolution occurs within the context of:

  • HTTP servlet request
  • Spring Web MVC request cycle
  • CAS authentication flow
  • Service-specific processing

Error Handling

The chaining resolver provides robust error handling:

  • Resolver Exceptions: Logged and chain continues with next resolver
  • Null Results: Treated as default theme, chain continues
  • Empty Strings: Treated as default theme, chain continues
  • Chain Exhaustion: Returns configured default theme

Performance Considerations

  • Lazy Evaluation: Resolvers evaluated only until first match
  • Ordered Execution: Place fastest/most-likely resolvers first
  • Caching: Individual resolvers may implement caching
  • Request Scoped: Resolution happens per-request, not cached across requests

Custom Resolver Integration

// Example custom resolver
public class DatabaseThemeResolver extends AbstractThemeResolver {
    @Override
    public String resolveThemeName(HttpServletRequest request) {
        String userId = getUserIdFromRequest(request);
        return userThemeService.getThemeForUser(userId);
    }
    
    @Override
    public void setThemeName(HttpServletRequest request, 
                           HttpServletResponse response, String themeName) {
        // Implement theme persistence if needed
    }
}

// Add to chain
DatabaseThemeResolver dbResolver = new DatabaseThemeResolver();
dbResolver.setDefaultThemeName("default");
chainResolver.addResolver(dbResolver);

Install with Tessl CLI

npx tessl i tessl/maven-org-apereo-cas--cas-server-support-themes

docs

auto-configuration.md

header-theme-resolution.md

index.md

service-theme-resolution.md

theme-resolution.md

theme-sources.md

tile.json