CoolCMS API

CategoryList extends BaseComponent
in package
uses InitializationTrait, CategoryRailTrait

Table of Contents

Constants

CATEGORY_RAIL_STYLES  : array<string|int, mixed> = ['Style_2', 'Style_4', 'Style_5', 'Style_6']
Styles that can be drawn from the shared template.
CATEGORY_RAIL_TEMPLATE_DIR  : string = __DIR__ . '/../../../Base/Front/Components/Cate...
Shared templates of {@see CATEGORY_RAIL_STYLES} for all modules.
SIGNAL_STYLES  : mixed = ['Style_1', 'Style_2', 'Style_4', 'Style_5', 'S...
Styles allowed in the `showAll!` signal: own templates `Style_1`-`Style_2` and the shared category strip styles `Style_4`-`Style_6` ({@see CategoryRailTrait}).
SUB_ITEM_COUNT_CAP  : mixed = 50
Cap on the number of subcategories from the signal.

Properties

$container  : Container
$routerDispatcher  : RouterDispatcher
$showAll  : bool
Expands the preferred list to the complete tree (signal `showAll!`).
$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
$categoryTree  : array<int, array<string, mixed>>|null
Tree from {@see TreeStructure::prepareForTemplate()}; never mutated, assigned to the template by value.
$lastRenderArgs  : array{string, ?int, bool, bool}|null
Arguments of the last full render.
$loadedCategories  : array<int, object>|null
Categories loaded once per component instance (the query does not depend on render arguments).
$manager  : CategoryManager
$rootCategoryTree  : array<int, array{item: object, children: array, hasChildren: bool}>|null
Root categories only, as tree nodes (see the `$rootsOnly` branch in `intilializeRender()`).

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
handleShowAll()  : void
Signal "All categories": expands the preferred list to the complete one.
hasServiceByType()  : bool
Returns whether the container has a service of the given type.
initializeAllContexts()  : void
injectDeviceDetector()  : void
onCreate()  : void
render()  : void
renderHorizontalCompact()  : void
Row tile: icon on the left, name next to it, count on the right.
renderLink()  : void
Row of links, the text variant of {@see renderHorizontalCompact()}, count in parentheses after the name.
renderTile()  : void
renderTileGroup()  : void
Tile with a group of subcategories: a colored area with an icon and the first `$subItemCount` children (default 3), below it the name and the number of companies.
renderVertical()  : 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.
buildCategoryRailParent()  : array{name: string, href: string}|null
Returns the way one level up: the first item of the strip when the current category has a parent.
buildCategoryRailRows()  : array<int, array{id: int|null, name: string, href: string, count: int|null, iconPath: string|null, asset: object|null, iconClass: string|null, active: bool, children: array}>
Converts tree nodes into plain arrays for the template.
categoryRailCount()  : int|null
Returns the item count of a category.
categoryRailHref()  : string
Category list target for the shared styles `Style_4`/`Style_5` ({@see CategoryRailTrait}).
categoryRailTemplateDir()  : string
Returns the directory to load the template from.
frontPresenter()  : BasePresenter|null
Returns the front presenter the component is attached to (null outside the front end or when detached).
getTranslator()  : ITranslator
prepareCategoryRail()  : void
Fills `$railRows` and `$railParent` for the shared templates.
setTemplateFile()  : void
setTranslator()  : self
categoryRailCurrentId()  : int|null
categoryRailIconPath()  : string|null
Returns the legacy icon path, or `null` when unusable.
categoryRailName()  : string
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).
getActivePath()  : array<int, int>
getCurrentCategory()  : Category|null
intilializeRender()  : void

Constants

CATEGORY_RAIL_STYLES

Styles that can be drawn from the shared template.

private array<string|int, mixed> CATEGORY_RAIL_STYLES = ['Style_2', 'Style_4', 'Style_5', 'Style_6']

CATEGORY_RAIL_TEMPLATE_DIR

Shared templates of {@see CATEGORY_RAIL_STYLES} for all modules.

private string CATEGORY_RAIL_TEMPLATE_DIR = __DIR__ . '/../../../Base/Front/Components/CategoryList'

SIGNAL_STYLES

Styles allowed in the `showAll!` signal: own templates `Style_1`-`Style_2` and the shared category strip styles `Style_4`-`Style_6` ({@see CategoryRailTrait}).

private mixed SIGNAL_STYLES = ['Style_1', 'Style_2', 'Style_4', 'Style_5', 'Style_6']

SUB_ITEM_COUNT_CAP

Cap on the number of subcategories from the signal.

private mixed SUB_ITEM_COUNT_CAP = 50

Properties

$showAll

Expands the preferred list to the complete tree (signal `showAll!`).

public bool $showAll = false

Persistent so that the non-JS fallback works: a click without Naja does a full reload with ?...-showAll=1 and the page renders already expanded.

NOTE: only meaningful for a mount with $preferredOnly = true; elsewhere the value is ignored. The component is mounted on a page through {multicontrol frontComcatCategoryList-<key>:...}: each mount is its own instance with its own state and snippet. Two mounts of one instance (a plain {control} twice) would break the snippet and the persistent parameter.

Attributes
#[Persistent]

$componentParameters

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

component parameters set by setComponentParameter()

$translatorDomain

protected string|null $translatorDomain = 'front.comcat.components.categoryList'

$categoryTree

Tree from {@see TreeStructure::prepareForTemplate()}; never mutated, assigned to the template by value.

private array<int, array<string, mixed>>|null $categoryTree = null

$lastRenderArgs

Arguments of the last full render.

private array{string, ?int, bool, bool}|null $lastRenderArgs = null

IMPORTANT: the snippet phase of AJAX calls render() on the invalidated component without arguments (Nette bypasses the template that passes them). Without remembering them the default Style_1 without the tiles snippet would be drawn and the payload would be empty; the same problem is solved in AdvertRenderer through selectedStyle plus the multiplier context.

$loadedCategories

Categories loaded once per component instance (the query does not depend on render arguments).

private array<int, object>|null $loadedCategories = null

$rootCategoryTree

Root categories only, as tree nodes (see the `$rootsOnly` branch in `intilializeRender()`).

private array<int, array{item: object, children: array, hasChildren: bool}>|null $rootCategoryTree = 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>>

handleShowAll()

Signal "All categories": expands the preferred list to the complete one.

public handleShowAll([string $style = 'Style_2' ][, int|null $subItemCount = null ][, bool $showSubItems = false ]) : void

IMPORTANT: render arguments travel in the signal (the link passes them from the template): the snippet phase of AJAX calls render() without arguments and the layout does not run, so render has nowhere to take them from; for the same reason AdvertRenderer carries selectedStyle from the signal. Without it the payload had no snippets.

The non-JS fallback is handled by parameter persistence (a full reload with ?...-showAll=1, where the layout runs and the template passes the arguments).

Parameters
$style : string = 'Style_2'
$subItemCount : int|null = null
$showSubItems : bool = false

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 = 'Style_1' ][, int|null $subItemCount = null ][, bool $showSubItems = true ][, bool $preferredOnly = false ]) : void
Parameters
$style : string = 'Style_1'
$subItemCount : int|null = null
$showSubItems : bool = true
$preferredOnly : bool = false

renderHorizontalCompact()

Row tile: icon on the left, name next to it, count on the right.

public renderHorizontalCompact([int|null $subItemCount = null ][, bool $showSubItems = true ]) : void

The layout comes from the shared .list--horizontal-compact variant that the article and advert lists use under the same name, hence the same method name instead of a private synonym.

NOTE: prints one level only; $subItemCount and $showSubItems have no effect (the parameters stay for the same signature as the other styles). Meant for a strip of subcategories above a list, not for a signpost.

Parameters
$subItemCount : int|null = null
$showSubItems : bool = true

renderLink()

Row of links, the text variant of {@see renderHorizontalCompact()}, count in parentheses after the name.

public renderLink([int|null $subItemCount = null ][, bool $showSubItems = true ]) : void

NOTE: prints one level only; $showSubItems has no effect (the parameter stays for the same signature as the other styles).

Parameters
$subItemCount : int|null = null
$showSubItems : bool = true

renderTile()

public renderTile([int|null $subItemCount = null ][, bool $showSubItems = true ][, bool $preferredOnly = false ]) : void
Parameters
$subItemCount : int|null = null
$showSubItems : bool = true
$preferredOnly : bool = false

renderTileGroup()

Tile with a group of subcategories: a colored area with an icon and the first `$subItemCount` children (default 3), below it the name and the number of companies.

public renderTileGroup([int|null $subItemCount = null ][, bool $showSubItems = true ]) : void

NOTE: $showSubItems has no effect: that switch controls the nested recursive list of Style_2, which this style does not render. Children are always listed, as a flat single-level list.

Parameters
$subItemCount : int|null = null
$showSubItems : bool = true

renderVertical()

public renderVertical([int|null $subItemCount = null ][, bool $showSubItems = true ]) : void
Parameters
$subItemCount : int|null = null
$showSubItems : bool = true

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

buildCategoryRailParent()

Returns the way one level up: the first item of the strip when the current category has a parent.

protected buildCategoryRailParent(mixed $parent) : array{name: string, href: string}|null
Parameters
$parent : mixed
Return values
array{name: string, href: string}|null —

null for a root category or a page outside categories; the item is then not rendered

buildCategoryRailRows()

Converts tree nodes into plain arrays for the template.

protected buildCategoryRailRows(array<string|int, mixed> $nodes[, int $childLimit = 0 ]) : array<int, array{id: int|null, name: string, href: string, count: int|null, iconPath: string|null, asset: object|null, iconClass: string|null, active: bool, children: array}>

NOTE: the name is neither trimmed nor escaped; striptags|trim stays in the template so the output is identical to the former per-module copies.

Parameters
$nodes : array<string|int, mixed>

nodes from TreeStructure::prepareForTemplate()

$childLimit : int = 0

how many children to list in a tile (0 = none, Style_4)

Return values
array<int, array{id: int|null, name: string, href: string, count: int|null, iconPath: string|null, asset: object|null, iconClass: string|null, active: bool, children: array}>

categoryRailCount()

Returns the item count of a category.

protected categoryRailCount(object $category) : int|null

Overridable hook; the default reads the denormalized column of Bazaar/Comcat. The shop category entity carries no product count, so ProductCategoryList overrides it with a subtree count. Blog and Discussion return null and the templates render no count.

Parameters
$category : object
Return values
int|null

categoryRailHref()

Category list target for the shared styles `Style_4`/`Style_5` ({@see CategoryRailTrait}).

protected categoryRailHref(int $categoryId) : string

IMPORTANT: slug is the id of the target page ($targetSlug), not the current one; without it the link to another module ends in a 404.

Parameters
$categoryId : int
Return values
string

categoryRailTemplateDir()

Returns the directory to load the template from.

protected categoryRailTemplateDir(string $ownDir, string $style) : string

A module's own copy (also a theme-specific one) takes precedence: whoever needs to deviate puts the file back into their Templates/…. The lookup mirrors BaseComponent::setTemplateFile() and only the final fallback returns the shared directory:

  • Templates/<Theme>/<Variant>/<style>.latte is a copy for the current theme;
  • Templates/Default/<style>.latte is a module copy for all themes;
  • otherwise the shared template in Base/Front/Components/CategoryList.

IMPORTANT: the lookup must never glob across all themes of the module. A theme-specific copy of another theme would be picked up while rendering a different theme, and when Templates/Default lacks the style the template file does not exist, which is a 500 for every theme without its own copy. Without a theme (CLI, no presenter) step one is skipped.

Parameters
$ownDir : string
$style : string
Return values
string

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

prepareCategoryRail()

Fills `$railRows` and `$railParent` for the shared templates.

protected prepareCategoryRail(string $style[, int|null $childLimit = null ]) : void

IMPORTANT: call it right before setTemplateFile(). Bazaar still filters $sortedItems (preferred categories) in between, so an earlier call would hand the tiles the unfiltered tree.

Style_4 and Style_6 take the children of the current category ($currentBranch), or the roots when there is no context. null and [] differ: null means "not in a category, show roots", an empty array means "in a leaf category, nothing to show"; hence ??, not ?:.

  • Style_2 is Style_5 (tiles, roots/sortedItems) without the children list (childLimit 0): a flatter signpost, not a group with subcategories.
  • Style_6 is Style_4 (contextual nodes plus the way back $railParent) with a different template (a row of links instead of a tile with an icon).

NOTE: Bazaar, Comcat, Discussion and Blog have their own Templates/Default/Style_2.latte (categoryRailTemplateDir() prefers the module copy), so the shared Style_2 serves only the shop until the others switch to it.

Parameters
$style : string
$childLimit : int|null = null

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

categoryRailCurrentId()

private categoryRailCurrentId() : int|null
Return values
int|null

categoryRailIconPath()

Returns the legacy icon path, or `null` when unusable.

private categoryRailIconPath(object $category) : string|null

IMPORTANT: getAssetPath() can return ".", a non-empty but unusable string; without this check <img src="."> renders a broken image. Entities without getAssetPath() (articles, discussions, shop) return null and are drawn through the asset renderer only.

Parameters
$category : object
Return values
string|null

categoryRailName()

private categoryRailName(object $category) : string
Parameters
$category : object
Return values
string

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

getActivePath()

private getActivePath(array<string|int, object> $categories, Category|null $currentCategory) : array<int, int>
Parameters
$categories : array<string|int, object>
$currentCategory : Category|null
Return values
array<int, int>

intilializeRender()

private intilializeRender([array<string|int, mixed> $items = [] ][, bool $rootsOnly = false ]) : void
Parameters
$items : array<string|int, mixed> = []
$rootsOnly : bool = false
On this page

Search results