Craft 5 Class Reference

Appearance

Cp ​

Type
Class
Namespace
craft\web\twig\variables
Inherits
craft\web\twig\variables\Cp » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.0.0

Control panel functions

View source

Public Properties ​

PropertyDescription
alertsarray
behaviorsyii\base\Behavior – List of behaviors attached to this component.
booleanEnvOptionsarray
envOptionsarray
envSuggestionsarray[]
fsOptionsarray
languageEnvOptionsarray
languageOptionsarray
requestedSitecraft\models\Site, null – The site, or null if the user doesn’t have permission to edit any sites.
templateSuggestionsarray[]
timeZoneOptionsarray
volumeOptionsarray

alerts ​

Type
array
Default value
null
Access
Read-only

View source

booleanEnvOptions ​

Type
array
Default value
null
Access
Read-only
Since
3.7.22

View source

envOptions ​

Type
array
Default value
null
Access
Read-only
Since
3.7.22

View source

envSuggestions ​

Type
array[]
Default value
null
Access
Read-only
Since
3.1.0

View source

fsOptions ​

Type
array
Default value
null
Access
Read-only
Since
4.0.0

View source

languageEnvOptions ​

Type
array
Default value
null
Access
Read-only
Since
5.0.0

View source

languageOptions ​

Type
array
Default value
null
Access
Read-only
Since
5.0.0

View source

requestedSite ​

Type
craft\models\Site, null
Default value
null
Access
Read-only
Since
4.0.4

The site, or null if the user doesn’t have permission to edit any sites.

View source

templateSuggestions ​

Type
array[]
Default value
null
Access
Read-only
Since
3.1.0

View source

timeZoneOptions ​

Type
array
Default value
null
Access
Read-only
Since
3.7.0

View source

volumeOptions ​

Type
array
Default value
null
Access
Read-only
Since
4.0.0

View source

Public Methods ​

MethodDescription
__call()Calls the named method which is not a class method.
__clone()This method is called after the object is created by cloning an existing one.
__construct()Constructor.
__get()Returns the value of a component property.
__isset()Checks if a property is set, i.e. defined and not null.
__set()Sets the value of a component property.
__unset()Sets a component property to be null.
areAlertsCached()Returns whether the control panel alerts are cached.
attachBehavior()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
behaviors()Returns a list of behaviors that this component should behave as.
canGetProperty()Returns a value indicating whether a property can be read.
canSetProperty()Returns a value indicating whether a property can be set.
className()Returns the fully qualified name of this class.
craftIdAccountUrl()Returns the Craft Console account URL.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
field()Renders a field’s HTML, for the given input HTML or a template.
fieldLayoutDesigner()Renders a field layout designer’s HTML.
getAlerts()Returns an array of alerts to display in the control panel.
getAsciiCharMap()Returns ASCII character mappings for the given language, if it differs from the application language.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getBooleanEnvOptions()Returns environment variable options for a boolean menu.
getEnvOptions()Returns environment variable options for a select input.
getEnvSuggestions()Returns the available environment variable and alias suggestions for inputs that support them.
getFsOptions()Returns all options for a filesystem input.
getLanguageEnvOptions()Returns environment variable options for a language menu.
getLanguageOptions()Returns all known language options for a language input.
getRequestedSite()Returns the site the control panel is currently working with, via a site query string param if sent.
getTemplateSuggestions()Returns the available template path suggestions for template inputs.
getTimeZoneOptions()Returns all known time zones for a time zone input.
getVolumeOptions()Returns all options for a volume input.
hasEventHandlers()Returns a value indicating whether there is any handler attached to the named event.
hasMethod()Returns a value indicating whether a method is defined.
hasProperty()Returns a value indicating whether a property is defined for this component.
init()Initializes the object.
nav()Returns the control panel nav items.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
prepFormActions()Prepares form actions
settings()Returns the list of settings.
trigger()Triggers an event.

areAlertsCached() ​

Returns whether the control panel alerts are cached.

View source

Returns ​

boolean

craftIdAccountUrl() ​

Returns the Craft Console account URL.

View source

Returns ​

string

field() ​

Since
3.7.24

Renders a field’s HTML, for the given input HTML or a template.

View source

Arguments ​

  • $input (string) – The input HTML or template path. If passing a template path, it must begin with template:.
  • $config (array)

Returns ​

string

Throws ​

fieldLayoutDesigner() ​

DEPRECATED

Deprecated in 5.5.0. The fieldLayoutDesigner() global CP function should be used instead.

Since
4.0.0

Renders a field layout designer’s HTML.

View source

Arguments ​

Returns ​

string

getAlerts() ​

Returns an array of alerts to display in the control panel.

View source

Returns ​

array

getAsciiCharMap() ​

Since
3.1.9

Returns ASCII character mappings for the given language, if it differs from the application language.

View source

Arguments ​

Returns ​

array, null

getBooleanEnvOptions() ​

Since
3.7.22

Returns environment variable options for a boolean menu.

View source

Returns ​

array

getEnvOptions() ​

Since
3.7.22

Returns environment variable options for a select input.

View source

Arguments ​

Returns ​

array

getEnvSuggestions() ​

Since
3.1.0

Returns the available environment variable and alias suggestions for inputs that support them.

View source

Arguments ​

  • $includeAliases (boolean) – Whether aliases should be included in the list (only enable this if the setting defines a URL or file path)
  • $filter (callable, null) – A function that returns whether a given value should be included

Returns ​

array[]

getFsOptions() ​

Since
4.0.0

Returns all options for a filesystem input.

View source

Returns ​

array

getLanguageEnvOptions() ​

Since
5.0.0

Returns environment variable options for a language menu.

View source

Arguments ​

  • $appOnly (boolean) – Whether to limit the env options to those that match available app locales

Returns ​

array

getLanguageOptions() ​

Since
5.0.0

Returns all known language options for a language input.

View source

Arguments ​

  • $showLocaleIds (boolean) – Whether to show the hint as locale id; e.g. en, en-GB
  • $showLocalizedNames (boolean) – Whether to show the hint as localizes names; e.g. English, English (United Kingdom)
  • $appLocales (boolean) – Whether to limit the returned locales to just app locales (cp translation options) or show them all

Returns ​

array

getRequestedSite() ​

Since
4.0.4

Returns the site the control panel is currently working with, via a site query string param if sent.

View source

Returns ​

craft\models\Site, null – The site, or null if the user doesn’t have permission to edit any sites.

getTemplateSuggestions() ​

Since
3.1.0

Returns the available template path suggestions for template inputs.

View source

Returns ​

array[]

getTimeZoneOptions() ​

Since
3.7.0

Returns all known time zones for a time zone input.

View source

Arguments ​

  • $offsetDate (DateTime, null) – The DateTime object that contains the date/time to compute time zone offsets from

Returns ​

array

getVolumeOptions() ​

Since
4.0.0

Returns all options for a volume input.

View source

Returns ​

array

nav() ​

Returns the control panel nav items.

Each control panel nav item should be defined by an array with the following keys:

  • label – The human-facing nav item label
  • url – The URL the nav item should link to
  • id – The HTML id attribute the nav item should have (optional)
  • icon – The path to an SVG file that should be used as the nav item icon (optional)
  • fontIcon – A character/ligature from Craft’s font icon set (optional)
  • badgeCount – A number that should be displayed beside the nav item when unselected
  • subnav – A sub-array of subnav items

Subnav arrays should be associative, with identifiable keys set to sub-arrays with the following keys:

  • label – The human-facing subnav item label
  • url – The URL the subnav item should link to

For example:

php
[
    'label' => 'Commerce',
    'url' => 'commerce',
    'subnav' => [
        'orders' => ['label' => 'Orders', 'url' => 'commerce/orders',
        'discounts' => ['label' => 'Discounts', 'url' => 'commerce/discounts',
    ],
]

Control panel templates can specify which subnav item is selected by defining a selectedSubnavItem variable.

twig
{% set selectedSubnavItem = 'orders' %}

View source

Returns ​

array

Throws ​

prepFormActions() ​

Since
3.6.10

Prepares form actions

View source

Arguments ​

Returns ​

array, null

settings() ​

Returns the list of settings.

View source

Returns ​

array

Events ​

EVENT_REGISTER_CP_NAV_ITEMS ​

Type
craft\events\RegisterCpNavItemsEvent

The event that is triggered when registering control panel nav items.

php
use craft\events\RegisterCpNavItemsEvent;
use craft\web\twig\variables\Cp;
use yii\base\Event;

Event::on(
    Cp::class,
    Cp::EVENT_REGISTER_CP_NAV_ITEMS,
    function(RegisterCpNavItemsEvent $e) {
        $e->navItems[] = [
            'label' => 'Item Label',
            'url' => 'my-module',
            'icon' => '/path/to/icon.svg',
        ];
    }
);

craft\events\RegisterCpNavItemsEvent::$navItems is an array whose values are sub-arrays that define the nav items. Each sub-array can have the following keys:

  • label – The item’s label.

  • url – The URL or path of the control panel page the item should link to.

  • icon – The path to the SVG icon that should be used for the item.

  • badgeCount (optional) – The badge count number that should be displayed next to the label.

  • external (optional) – Set to true if the item links to an external URL.

  • id (optional) – The ID of the <li> element. If not specified, it will default to nav-.

  • subnav (optional) – A nested array of sub-navigation items that should be displayed if the main item is selected.

    The keys of the array should define the items’ IDs, and the values should be nested arrays with label and url keys, and optionally badgeCount and external keys.

If a subnav is defined, subpages can specify which subnav item should be selected by defining a selectedSubnavItem variable that is set to the selected item’s ID (its key in the subnav array).

EVENT_REGISTER_CP_SETTINGS ​

Type
craft\events\RegisterCpSettingsEvent
Since
3.1.0

The event that is triggered when registering links that should render on the Settings page in the control panel.

php
use craft\events\RegisterCpSettingsEvent;
use craft\web\twig\variables\Cp;
use yii\base\Event;

Event::on(
    Cp::class,
    Cp::EVENT_REGISTER_CP_SETTINGS,
    function(RegisterCpSettingsEvent $e) {
        $e->settings[Craft::t('app', 'Modules')][] = [
            'label' => 'Item Label',
            'url' => 'my-module',
            'icon' => '/path/to/icon.svg',
        ];
    }
);

craft\events\RegisterCpSettingsEvent::$settings is an array whose keys define the section labels, and values are sub-arrays that define the individual links.

Each link array should have the following keys:

  • label – The item’s label.
  • url – The URL or path of the control panel page the item should link to.
  • icon – The path to the SVG icon that should be used for the item.

EVENT_REGISTER_FORM_ACTIONS ​

Type
craft\events\FormActionsEvent
Since
3.6.10

The event that is triggered when preparing the page’s form actions.

php
use craft\events\FormActionsEvent;
use craft\web\twig\variables\Cp;
use yii\base\Event;

Event::on(
    Cp::class,
    Cp::EVENT_REGISTER_FORM_ACTIONS,
    function(FormActionsEvent $event) {
        if (Craft::$app->requestedRoute == 'entries/edit-entry') {
            $event->formActions[] = [
                'label' => 'Save and view entry',
                'redirect' => Craft::$app->getSecurity()->hashData('{url}'),
            ];
        }
    }
);

See also prepFormActions()