CoolCMS API

ThemeSwitcher extends BaseComponent
in package
uses InitTrait

FinalYes

Site appearance switcher offering the visitor the templates the installation provides.

It is a sales feature on the CoolCMS demo site ("this is how your site can look"), so it renders for everyone, without login. The choice belongs only to the visitor: it is held in their session cookie, read by DefaultThemeResolver. The admin site setting does not change and other visitors still see the site as configured.

IMPORTANT: mount it in parts/shared/bottom.latte (one per template, outside {snippet page}), like the cookie bar; inside the snippet an AJAX redraw would destroy it.

It renders nothing only when both env switches are off (CMS_THEME_SWITCH=0 and CMS_SKIN_SWITCH=0; then InitTrait::switchableThemes() returns an empty list) or when fewer than two color dots remain in total.

Table of Contents

Properties

$container  : Container
$routerDispatcher  : RouterDispatcher
$translator  : ITranslator
$appContext  : AppContext
$componentParameters  : array<string, mixed>
$currencyContext  : CurrencyContext|null
$deviceDetector  : DeviceDetector|null
$languageContext  : LanguageContext|null
$localizationContext  : LocalizationContext|null
$settingContext  : SettingContext
$themeContext  : ThemeContext|null
$translatorDomain  : string|null
$httpRequest  : Request
$themeCatalog  : ThemeCatalog
$themeResolver  : DefaultThemeResolver

Methods

__call()  : mixed
Dispatches `renderXyz()` to `render('Xyz', ...$args)`.
__construct()  : mixed
createComponent()  : IComponent|null
getAppContext()  : AppContext
getComponentParameter()  : mixed
Returns a component parameter, or null when it is not set.
getContainer()  : Container
getCurrencyContext()  : CurrencyContext|null
getLanguageContext()  : LanguageContext|null
getLocalizationContext()  : LocalizationContext|null
getRouterDispatcher()  : RouterDispatcher
getSettingContext()  : SettingContext
getSettings()  : array<int, array<string, mixed>>
getThemeContext()  : ThemeContext|null
hasServiceByType()  : bool
Returns whether the container has a service of the given type.
initializeAllContexts()  : void
injectDeviceDetector()  : void
onCreate()  : void
render()  : void
setAppContext()  : $this
setComponentParameter()  : void
Sets a component parameter.
setCurrencyContext()  : $this
setLanguageContext()  : $this
setLocalizationContext()  : $this
setSettingContext()  : $this
setThemeContext()  : $this
setup()  : void
setupAppContext()  : void
typedComponent()  : T
Returns a subcomponent with a verified type.
frontPresenter()  : BasePresenter|null
Returns the front presenter the component is attached to (null outside the front end or when detached).
getTranslator()  : ITranslator
setTemplateFile()  : void
setTranslator()  : self
activeThemeName()  : string|null
Directory name of the currently displayed template (`template1`), or null.
createMultiplierComponent()  : Multiplier<string|int, IComponent>
Creates a multiplier for the component.
createNewComponentInstance()  : IComponent|null
Creates a new component instance without adding it to the presenter; used by the multiplier.
createStandardComponent()  : IComponent|null
Creates a standard component (not a multiplier).
switchableThemes()  : array<int, array{name: string, label: string, description: ?string, active: bool, variants: list, previewColors: list}>
Returns the offer for rendering; an empty array means "render nothing".
switchableVariants()  : array<int, array{skin: ?string, label: ?string, color: ?string, url: string, active: bool}>
Returns catalog variants completed with a link and an "is active" flag.
switchUrl()  : string
Returns the link that switches to the given template and skin: the current URL plus `?_theme=...&_skin=...`.

Properties

$componentParameters

protected array<string, mixed> $componentParameters = []

component parameters set by setComponentParameter()

$translatorDomain

protected string|null $translatorDomain = 'front.base.components.themeSwitcher'

Methods

__call()

Dispatches `renderXyz()` to `render('Xyz', ...$args)`.

public __call(string $name, array<string|int, mixed> $args) : mixed

Called only when the component has no renderXyz() method of its own.

Parameters
$name : string
$args : array<string|int, mixed>

createComponent()

public createComponent(string $name) : IComponent|null
Parameters
$name : string
Return values
IComponent|null

getComponentParameter()

Returns a component parameter, or null when it is not set.

public getComponentParameter(string $name) : mixed
Parameters
$name : string

getContainer()

public getContainer() : Container
Return values
Container

getSettings()

public getSettings() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

hasServiceByType()

Returns whether the container has a service of the given type.

public hasServiceByType(string $className) : bool

The name is composed dynamically (module plus component), so class_exists() runs first, and a true result guarantees a valid type.

Parameters
$className : string
Tags
phpstan-assert-if-true

class-string $className

Return values
bool

render()

public render([string $style = 'Switcher' ]) : void
Parameters
$style : string = 'Switcher'

setComponentParameter()

Sets a component parameter.

public setComponentParameter(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed

typedComponent()

Returns a subcomponent with a verified type.

public typedComponent(string $name, T> $type) : T

Use it instead of an inline @var above $this['x'] (which does not narrow the type) and instead of the generic IComponent that $this['x'] returns. See Form::typedComponent().

Parameters
$name : string
$type : T>
Tags
template
Return values
T

frontPresenter()

Returns the front presenter the component is attached to (null outside the front end or when detached).

protected frontPresenter() : BasePresenter|null
Return values
BasePresenter|null

getTranslator()

protected getTranslator() : ITranslator
Return values
ITranslator

setTemplateFile()

protected setTemplateFile(string $dir, string $filename) : void
Parameters
$dir : string
$filename : string

setTranslator()

protected setTranslator(ITranslator $translator) : self
Parameters
$translator : ITranslator
Return values
self

activeThemeName()

Directory name of the currently displayed template (`template1`), or null.

private activeThemeName() : string|null
Return values
string|null

createMultiplierComponent()

Creates a multiplier for the component.

private createMultiplierComponent(string $name) : Multiplier<string|int, IComponent>
Parameters
$name : string
Return values
Multiplier<string|int, IComponent>

createNewComponentInstance()

Creates a new component instance without adding it to the presenter; used by the multiplier.

private createNewComponentInstance(string $baseName[, int|string|null $uniqueKey = null ]) : IComponent|null
Parameters
$baseName : string
$uniqueKey : int|string|null = null
Return values
IComponent|null

createStandardComponent()

Creates a standard component (not a multiplier).

private createStandardComponent(string $name) : IComponent|null
Parameters
$name : string
Return values
IComponent|null

switchableThemes()

Returns the offer for rendering; an empty array means "render nothing".

private switchableThemes() : array<int, array{name: string, label: string, description: ?string, active: bool, variants: list, previewColors: list}>

The catalog (ThemeCatalog) knows each template and its colors; this trait adds only what belongs to the visitor: switch links and the "currently viewed" flag.

Each template carries a list of variants: color dots that select the template and its skin at once. The first is always the base look (no skin), followed by the template's skins. A template without skins has a single dot.

Return values
array<int, array{name: string, label: string, description: ?string, active: bool, variants: list, previewColors: list}>

switchableVariants()

Returns catalog variants completed with a link and an "is active" flag.

private switchableVariants(string $themeName, array<int, array{skin: ?string, label: ?string, color: ?string, duplicateColor: bool}> $variants) : array<int, array{skin: ?string, label: ?string, color: ?string, url: string, active: bool}>

IMPORTANT: a color the catalog marked as repeated (duplicateColor) is dropped from the offer, because two identical dots side by side look like a bug and a click shows no difference. The exception is the currently active skin: it stays even with a duplicate color, otherwise the check mark would have nothing to attach to and the panel would claim nothing is selected. That is why it is not filtered in the catalog, which does not know what the visitor is viewing.

Parameters
$themeName : string
$variants : array<int, array{skin: ?string, label: ?string, color: ?string, duplicateColor: bool}>
Return values
array<int, array{skin: ?string, label: ?string, color: ?string, url: string, active: bool}>

switchUrl()

Returns the link that switches to the given template and skin: the current URL plus `?_theme=...&_skin=...`.

private switchUrl(string $themeName, string|null $skin) : string

Staying on the same page is intended: the visitor wants to see this content in another look, not jump to the home page. The parameters stay in the address, which is fine on the demo site; a shared link shows the recipient the same thing.

NOTE: the link is not a signal (handle...): that would need a CSRF token and change on every redraw, so it could be neither cached nor shared. Switching is safe: it changes only the cookie of whoever clicked.

IMPORTANT: a choice equal to the site setting sends off, which cancels the choice. Sending the name would store a hard cookie when the visitor clicks the default look, so a later admin change would never reach them while they feel they "switched nothing". This holds for the template and the skin separately. The skin comparison applies only within the target template; for a skin of another template off is not sent even if the name matches.

IMPORTANT: both parameters always go together. A dot selects the pair (template, skin), so a click on the base look must also cancel the skin; otherwise the skin from the previous choice would stay and not belong to the new template.

Parameters
$themeName : string
$skin : string|null
Return values
string
On this page

Search results