CoolCMS API

DashboardTiles extends BaseComponent
in package

Application

uses PrivilegeGuardTrait

FinalYes

Band of dashboard tiles: selected links from the admin menu, grouped into sections.

What is shown is set by each project itself in the dashboard tiles settings. A tile is a menu item: icon, label and target come from the item, so nothing is entered twice and renaming the item propagates here. Enabling is held by two columns (dashboard_tile, dashboard_order) on the item itself.

Sections are derived, not set: a tile belongs under the first-level item above its menu item (e-shop, adverts, system, ...), so the placement comes from the menu structure the admin knows.

Cost: one query for enabled tiles plus one for their ancestors (section names). Without an enabled tile the band is not rendered at all, so a fresh installation has no empty block with a heading on the dashboard.

Constants

FALLBACK_ICON : mixed = 'fa-solid fa-arrow-right': Icon for an item that has none of its own, so a tile is never empty.

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
$adminMenuItemManager : AdminMenuItemManager

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
isTargetAllowed() : bool: Returns whether the logged-in user may open the given admin target. For visibility (tiles, autocomplete, buttons); it does not throw.
requirePrivilege() : void: Throws 403 when the logged-in user lacks the given admin privilege.
resolvePageTarget() : string|null: Returns the RBAC key of the target page: `<presenter>:<action>`, e.g. `:Admin:System:User:show`.
setTemplateFile() : void
setTranslator() : self
buildHref() : string|null: Returns the link to the item target, or `null` when it does not exist in this installation.
collectSections() : array<int, array{title: string, tiles: array}>: Returns enabled tiles grouped into sections, sections ordered as in the menu.
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).
findEnabledItems() : array<int, AdminMenuItem>: Returns enabled tiles. Ordering inside a section is done by {@see sortTiles()}; this only provides stable input.
isTileAllowed() : bool: Whether the current role may open the tile target. Fail-closed pattern shared with {@see \App\UI\Admin\System\Components\MenuComponent\Menu::filterByPrivileges()} and {@see \App\UI\Admin\System\Components\DashboardAttentionComponent\DashboardAttention}: the key is `<presenter>:<action>` of the target page; without a target or without `isAllowed()` the answer is no.
loadAncestors() : array<int, AdminMenuItem>: Returns section names: the first-level items under which tiles fall.
resolveLanguageId() : int|null
resolveSection() : array{id: int, title: string, order: int}: Returns the tile section: its first-level ancestor found via the `lft`–`rgt` range.
sortTiles() : array<int, array{label: string, icon: string, href: string}>: Orders the tiles inside a section.

FALLBACK_ICON

Icon for an item that has none of its own, so a tile is never empty.


    private
        mixed
    FALLBACK_ICON
    = 'fa-solid fa-arrow-right'

$container


        public
            Container
    $container

#[Inject]

$routerDispatcher


        public
            RouterDispatcher
    $routerDispatcher

$translator


        public
            ITranslator
    $translator

$appContext


        protected
            AppContext
    $appContext

$componentParameters


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

component parameters set by setComponentParameter()

$currencyContext


        protected
            CurrencyContext|null
    $currencyContext
     = NULL

$deviceDetector


        protected
            DeviceDetector|null
    $deviceDetector
     = NULL

$languageContext


        protected
            LanguageContext|null
    $languageContext
     = NULL

$localizationContext


        protected
            LocalizationContext|null
    $localizationContext
     = NULL

$settingContext


        protected
            SettingContext
    $settingContext

$themeContext


        protected
            ThemeContext|null
    $themeContext
     = NULL

$translatorDomain


        protected
            string|null
    $translatorDomain
     = 'admin.system.components.dashboardTiles'

$adminMenuItemManager read-only


        private
            AdminMenuItemManager
    $adminMenuItemManager

__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>

__construct()


    public
                    __construct(AdminMenuItemManager $adminMenuItemManager) : mixed

Parameters

$adminMenuItemManager : AdminMenuItemManager

createComponent()


    public
                    createComponent(string $name) : IComponent|null

Parameters

$name : string

Return values

IComponent|null

getAppContext()


    public
                    getAppContext() : AppContext

Return values

AppContext

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

getCurrencyContext()


    public
                    getCurrencyContext() : CurrencyContext|null

Return values

CurrencyContext|null

getLanguageContext()


    public
                    getLanguageContext() : LanguageContext|null

Return values

LanguageContext|null

getLocalizationContext()


    public
                    getLocalizationContext() : LocalizationContext|null

Return values

LocalizationContext|null

getRouterDispatcher()


    public
                    getRouterDispatcher() : RouterDispatcher

Return values

RouterDispatcher

getSettingContext()


    public
                    getSettingContext() : SettingContext

Return values

SettingContext

getSettings()


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

Return values

array<int, array<string, mixed>>

getThemeContext()


    public
                    getThemeContext() : ThemeContext|null

Return values

ThemeContext|null

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

Return values

bool

initializeAllContexts()


    public
                    initializeAllContexts() : void

injectDeviceDetector()


    public
                    injectDeviceDetector(DeviceDetector $detector) : void

Parameters

$detector : DeviceDetector

onCreate()


    public
                    onCreate() : void

render()


    public
                    render() : void

setAppContext()


    public
                    setAppContext(AppContext $appContext) : $this

Parameters

$appContext : AppContext

Return values

$this

setComponentParameter()

Sets a component parameter.


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

Parameters

$name : string
$value : mixed

setCurrencyContext()


    public
                    setCurrencyContext(CurrencyContext|null $currencyContext) : $this

Parameters

$currencyContext : CurrencyContext|null

Return values

$this

setLanguageContext()


    public
                    setLanguageContext(LanguageContext|null $languageContext) : $this

Parameters

$languageContext : LanguageContext|null

Return values

$this

setLocalizationContext()


    public
                    setLocalizationContext(LocalizationContext|null $localizationContext) : $this

Parameters

$localizationContext : LocalizationContext|null

Return values

$this

setSettingContext()


    public
                    setSettingContext(SettingContext $settingContext) : $this

Parameters

$settingContext : SettingContext

Return values

$this

setThemeContext()


    public
                    setThemeContext(ThemeContext|null $themeContext) : $this

Parameters

$themeContext : ThemeContext|null

Return values

$this

setup()


    public
                    setup(BasePresenter|BasePresenter $presenter) : void

Parameters

$presenter : BasePresenter|BasePresenter

setupAppContext()


    public
                    setupAppContext(AppContext $appContext) : void

Parameters

$appContext : AppContext

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>

Return values

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

isTargetAllowed()

Returns whether the logged-in user may open the given admin target. For visibility (tiles, autocomplete, buttons); it does not throw.


    protected
                    isTargetAllowed(string|null $key) : bool

IMPORTANT: fail-closed like requirePrivilege(): an empty key and a presenter without isAllowed() both mean no. A component that skips this question lists the target to everyone.

Parameters

$key : string|null

Return values

bool

requirePrivilege()

Throws 403 when the logged-in user lacks the given admin privilege.


    protected
                    requirePrivilege(string $key) : void

Call it as the first statement of a mutating signal, before loading data, so the check cannot be bypassed by something being written first.

Parameters

$key : string

resolvePageTarget()

Returns the RBAC key of the target page: `<presenter>:<action>`, e.g. `:Admin:System:User:show`.


    protected
            static        resolvePageTarget(object|null $page) : string|null

Same interpretation as Menu::filterByPrivileges(), BasePresenter::authorizeListing() and PrivilegeCheckTrait::checkCurrentPrivilege(). The key is derived from the page target only, never from a file or class name.

Returns null when the page is missing or has no presenter, so there is nothing to allow.

Parameters

$page : object|null: AdminPage entity (hydrated, hence just object)

Return values

string|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

buildHref()

Returns the link to the item target, or `null` when it does not exist in this installation.


    private
                    buildHref(AdminMenuItem $polozka) : string|null

Parameters

$polozka : AdminMenuItem

Return values

string|null

collectSections()

Returns enabled tiles grouped into sections, sections ordered as in the menu.


    private
                    collectSections() : array<int, array{title: string, tiles: array}>

Return values

array<int, array{title: string, tiles: array}>

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

findEnabledItems()

Returns enabled tiles. Ordering inside a section is done by {@see sortTiles()}; this only provides stable input.


    private
                    findEnabledItems() : array<int, AdminMenuItem>

Return values

array<int, AdminMenuItem>

isTileAllowed()

Whether the current role may open the tile target. Fail-closed pattern shared with {@see \App\UI\Admin\System\Components\MenuComponent\Menu::filterByPrivileges()} and {@see \App\UI\Admin\System\Components\DashboardAttentionComponent\DashboardAttention}: the key is `<presenter>:<action>` of the target page; without a target or without `isAllowed()` the answer is no.


    private
                    isTileAllowed(AdminMenuItem $polozka) : bool

Parameters

$polozka : AdminMenuItem

Return values

bool

loadAncestors()

Returns section names: the first-level items under which tiles fall.


    private
                    loadAncestors() : array<int, AdminMenuItem>

Loaded by one query over the whole level, not one per tile: level 1 has about ten items, so taking it whole is cheaper than N queries.

Return values

array<int, AdminMenuItem> —

key is the id of the first-level item

resolveLanguageId()


    private
                    resolveLanguageId() : int|null

Return values

int|null

resolveSection()

Returns the tile section: its first-level ancestor found via the `lft`–`rgt` range.


    private
                    resolveSection(AdminMenuItem $polozka, array<int, AdminMenuItem> $predci, int|null $lang) : array{id: int, title: string, order: int}

An item that is itself on the first level is its own section.

Parameters

$polozka : AdminMenuItem
$predci : array<int, AdminMenuItem>
$lang : int|null

Return values

array{id: int, title: string, order: int}

sortTiles()

Orders the tiles inside a section.


    private
                    sortTiles(array<int, array{label: string, icon: string, href: string, order: int, lft: int}> $tiles) : array<int, array{label: string, icon: string, href: string}>

IMPORTANT: sorting by dashboard_order ascending in SQL does not work: zero would come first, so "by menu" would precede every explicitly numbered tile, the opposite of what the admin suggests. Sorting happens here:

tiles with a filled order (1–9), ascending,
then the rest in menu order.

There are about ten tiles, so sorting in PHP costs nothing.

Parameters

$tiles : array<int, array{label: string, icon: string, href: string, order: int, lft: int}>

Return values

array<int, array{label: string, icon: string, href: string}>

DashboardTiles extends BaseComponent in package Application uses PrivilegeGuardTrait

Table of Contents

Constants

Properties

Methods

Constants

FALLBACK_ICON

Properties

$container

Attributes

$routerDispatcher

$translator

Tags

$appContext

$componentParameters

$currencyContext

$deviceDetector

$languageContext

$localizationContext

$settingContext

$themeContext

$translatorDomain

$adminMenuItemManager read-only

Methods

__call()

Parameters

__construct()

Parameters

createComponent()

Parameters

Return values

getAppContext()

Return values

getComponentParameter()

Parameters

getContainer()

Return values

getCurrencyContext()

Return values

getLanguageContext()

Return values

getLocalizationContext()

Return values

getRouterDispatcher()

Return values

getSettingContext()

Return values

getSettings()

Return values

getThemeContext()

Return values

hasServiceByType()

Parameters

Tags

Return values

initializeAllContexts()

injectDeviceDetector()

Parameters

onCreate()

render()

setAppContext()

Parameters

Return values

setComponentParameter()

Parameters

setCurrencyContext()

Parameters

Return values

setLanguageContext()

Parameters

Return values

setLocalizationContext()

Parameters

Return values

setSettingContext()

Parameters

Return values

setThemeContext()

Parameters

Return values

DashboardTiles extends BaseComponent
in package

Application

uses PrivilegeGuardTrait