Theme Switcher
Persistent CSS themes with optional Bootstrap 5.3 color-mode integration.
The shared CoreApp\Personalization\ThemeSwitcher provides theme selection,
cookie persistence, stylesheet registration and document-level theme metadata. Applications
configure their own themes through APPNETOS class extensions.
How it works
During __invoke(), the switcher initializes its theme definitions and reads the selected
key from the APPNETOS Cookie controller. If the cookie is missing or refers to an unavailable theme,
the first valid theme is selected and stored. If no valid themes exist, the switcher renders
nothing.
The selected theme's src is registered through Core CSS. Core UI receives
data-appnetos-theme and, when configured, data-bs-theme for the root
<html> element. The shared JavaScript and CSS resources for the selector
interface are registered during normal rendering.
The HTML root attributes and stylesheet must be collected after the switcher has initialized. AJAX theme selection persists the new choice; applying the change to the already loaded page requires client-side handling or a reload.
Theme configuration
Override getThemes() in an application-specific class extension. Each entry requires
a unique nonempty key and a nonempty CSS src. Titles, icons and
Bootstrap color modes are optional.
protected function getThemes(): array
{
return [
[
'key' => 'light',
'title' => 'Light',
'src' => '/src/my-app/app/css/light.min.css',
'icon' => '/src/my-app/app/img/themes/light.svg',
'bootstrap_theme' => 'light',
],
[
'key' => 'dark',
'title' => 'Dark',
'src' => '/src/my-app/app/css/dark.min.css',
'icon' => '/src/my-app/app/img/themes/dark.svg',
'bootstrap_theme' => 'dark',
],
];
}
| Field | Purpose |
|---|---|
key |
Required unique identifier used for persistence and the APPNETOS theme attribute. |
src |
Required public stylesheet path registered through Core CSS. |
title |
Optional display label; defaults to the theme key. |
icon |
Optional icon path for the selector UI. |
bootstrap_theme |
Optional value for data-bs-theme on the HTML root. |
Persistent cookies and switcher identifiers
Override getThemeSwitcherId() to assign a stable identifier. The switcher uses it to
generate a logical cookie key; the shared Cookie controller adds the active application or session
scope and normalizes the physical browser cookie name.
protected function getThemeSwitcherId(): string
{
return 'theme-switcher-docs';
}
protected function getThemeCookieLifetime(): int
{
return 31536000; // 365 days
}
Cookies are configured by the shared controller with the root path, automatic HTTPS detection,
HttpOnly enabled and SameSite=Lax. The default Theme Switcher lifetime
is 365 days and can be overridden as shown above.
Different identifiers retain independent selections; pages using the same identifier share the corresponding selection within the applicable cookie scope. Use only one Theme Switcher per page, because the stylesheet and HTML theme attributes are document-wide.
Core UI and stylesheet output
For an active dark theme with Bootstrap integration, the rendered document can include:
<html lang="en" data-appnetos-theme="dark" data-bs-theme="dark">
The active theme stylesheet is registered through Core\Css::add() with the priority
returned by getThemeCssPriority() (1000 by default). The application's rendering
pipeline is responsible for emitting the registered CSS resources.
The Bootstrap color-mode attribute is optional. If a theme omits bootstrap_theme,
the switcher does not set data-bs-theme for that theme.
AJAX and customization
loadThemes() renders the configured choices and their active state. The
selectTheme() endpoint validates the supplied switcher identifier and theme key,
then writes the selected key to its persistent cookie. Invalid selections are rejected.
Applications can customize getThemes(), getThemeSwitcherId(),
getThemeCookieLifetime(), getThemeCssPriority(),
resolveThemeTitle() and the Bootstrap-versioned template paths.
The shared implementation currently supports Bootstrap 5.3.8 templates.