CoolCMS API

CustomAssets extends BaseComponent
in package

Custom code inserted from the admin (library "Web / Pages / Custom code").

Model: a page runs exactly the codes assigned to it (relation cms_system_custom_asset_page_relations); there is no site-wide scope and no "replace" mode. "On all pages" is only an admin action that creates the relations to all pages.

Called once per placement in the page:

{control frontSystemCustomAssets 'head'}        // in `<head>`
{control frontSystemCustomAssets 'body_start'}  // right after `<body>`
{control frontSystemCustomAssets 'body_end'}    // before `</body>`

IMPORTANT: all three calls get the same component instance from Nette (same name in the template), so the codes load with one query and are only filtered, see loadAssets(). Naming the component differently per placement would cost three queries per request.

NOTE: without a page entity nothing is rendered. Front\BasePresenter::startup() calls $this->pageEntity->getId() right after initializePage(), so a request without a page fails before the layout renders; error pages do not render custom code.

IMPORTANT: the content is not sanitized, which is the whole point of the library; the author needs their own privilege (:Admin:System:CustomAsset:edit, assignment …:assign). The only safeguard is in wrap(): the closing tag that could break out of <style>/<script> and write arbitrary HTML into the page is stripped from CSS and JS. The html type has no safeguard and cannot have one, because a snippet is inserted precisely to bring its own tags.

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
$assets  : array<int, CustomAsset>|null
Codes assigned to the page of this request, loaded lazily with one query.
$customAssetManager  : CustomAssetManager

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.
assetsForPlacement()  : array<int, CustomAsset>
Page codes for the given placement, ordered by the code `sort` (the query already returns the order, the placement filter keeps it).
frontPresenter()  : BasePresenter|null
Returns the front presenter the component is attached to (null outside the front end or when detached).
getTranslator()  : ITranslator
loadAssets()  : array<int, CustomAsset>
Enabled codes assigned to the page, in one query, ordered by `sort`, `id`.
setTemplateFile()  : void
setTranslator()  : self
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).
currentPage()  : Page|null
Current page (null outside a front presenter).
stripClosingTag()  : string
Removes the closing tag of the given element from the code.
wrap()  : string
Wraps the stored code into a tag by type.
wrapScript()  : string
`<script>`: either directly executable or put to sleep until cookie consent.

Properties

$componentParameters

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

component parameters set by setComponentParameter()

$translatorDomain

protected string|null $translatorDomain = 'front.system.components.customAssets'

$assets

Codes assigned to the page of this request, loaded lazily with one query.

private array<int, CustomAsset>|null $assets = null

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 $placement = 'head' ]) : void
Parameters
$placement : string = 'head'

head | body_start | body_end

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

loadAssets()

Enabled codes assigned to the page, in one query, ordered by `sort`, `id`.

protected loadAssets(Page|null $page) : array<int, CustomAsset>

The relation filter is part of the query (not PHP): a code can be related to hundreds of pages, so loading all codes with relations and sorting in memory does not scale. Relation changes (page tab, bulk actions, new or deleted page) bump the CustomAsset class cache, so the query result never goes stale.

Parameters
$page : Page|null
Return values
array<int, CustomAsset>

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

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

currentPage()

Current page (null outside a front presenter).

private currentPage() : Page|null
Return values
Page|null

stripClosingTag()

Removes the closing tag of the given element from the code.

private stripClosingTag(string $code, string $tag) : string

Matches </style and < / style with whitespace in any letter case, because browsers treat all of them as the end of the element.

Parameters
$code : string
$tag : string
Return values
string

wrap()

Wraps the stored code into a tag by type.

private wrap(CustomAsset $asset) : string

IMPORTANT: stripClosingTag() is the only change the code goes through; without it a </style> in the middle of CSS would end the element and the rest would print into the page as HTML (the same for </script> in JS, including appending another script). It is not content sanitization, it is a lock against breaking out of the element.

Parameters
$asset : CustomAsset
Return values
string

wrapScript()

`<script>`: either directly executable or put to sleep until cookie consent.

private wrapScript(CustomAsset $asset, string $code) : string

With a category filled in it renders as type="text/plain" plus data-cookie-category; cookie-bar.js runs it after consent is given, the same as Google Analytics and Tag Manager in the theme templates.

Parameters
$asset : CustomAsset
$code : string
Return values
string
On this page

Search results