Craft 5 Class Reference

Appearance

Cp ​

Type
Class
Namespace
craft\helpers
Inherits
craft\helpers\Cp
Since
3.0.0

Class Cp

View source

Public Methods ​

MethodDescription
addressFieldsHtml()Returns address fields’ HTML (sans country) for a given address.
autosuggestFieldHtml()Renders an autosuggest field’s HTML.
buttonGroupFieldHtml()Renders a button group field’s HTML.
buttonGroupHtml()Renders a button group.
buttonHtml()Renders a button’s HTML.
cardPreviewHtml()Returns HTML for the card preview based on selected fields and attributes.
cardPreviewOptions()Returns an array of available card preview options for the given field layout.
cardThumbOptions()Returns an array of available card thumbnail options for the given field layout.
cardViewDesignerHtml()Renders a card view designer.
checkboxFieldHtml()Renders a checkbox field’s HTML.
checkboxGroupFieldHtml()Renders a checkbox group field’s HTML.
checkboxGroupHtml()Renders a checkbox group input.
checkboxSelectFieldHtml()Renders a checkbox select field’s HTML.
chipHtml()Renders a component’s chip HTML.
colorFieldHtml()Renders a color field’s HTML.
colorHtml()Renders a color input’s HTML.
colorSelectFieldHtml()Renders a color select field’s HTML.
componentPreviewHtml()Returns component preview HTML, for a list of elements.
componentStatusIndicatorHtml()Renders status indicator HTML for a craft\base\Statusable component.
componentStatusLabelHtml()Renders status label HTML for a craft\base\Statusable component.
customSelectFieldHtml()Renders a selectize field’s HTML.
customSelectHtml()Renders a custom select input.
dateFieldHtml()Returns a date field’s HTML.
dateHtml()Returns a date input’s HTML.
dateTimeFieldHtml()Renders a date + time field’s HTML.
disclosureMenu()Returns a disclosure menu’s HTML.
earthIcon()Returns the appropriate Earth icon, depending on the system time zone.
editableTableFieldHtml()Renders an editable table field’s HTML.
editableTableHtml()Renders an editable table’s HTML.
elementCardHtml()Renders an element’s card HTML.
elementChipHtml()Renders an element’s chip HTML.
elementHtml()Renders an element’s chip HTML.
elementIndexHtml()Returns the HTML for an element index.
elementPreviewHtml()Returns element preview HTML, for a list of elements.
elementSelectFieldHtml()Renders an element select field’s HTML.
elementSelectHtml()Renders an element select input’s HTML
entryTypeSelectFieldHtml()Renders an entry type select field’s HTML.
entryTypeSelectHtml()Renders an entry type select input’s HTML
fallbackIconSvg()Returns a fallback icon SVG for a component with a given label.
fieldHtml()Renders a field’s HTML, for the given input HTML or a template.
fieldLayoutDesignerHtml()Renders a field layout designer.
generatedFieldsTableHtml()Renders a Generated Fields table for a field layout
iconPickerFieldHtml()Renders an icon picker field’s HTML.
iconPickerHtml()Renders an icon picker’s HTML.
iconSvg()Returns an SVG icon’s contents for the control panel.
layoutElementSelectorHtml()Renders a field layout element’s selector HTML.
lightswitchFieldHtml()Renders a lightswitch field’s HTML.
lightswitchHtml()Renders a lightswitch input’s HTML.
menuItem()Returns a menu item’s HTML.
metadataHtml()Returns a metadata component’s HTML.
moneyFieldHtml()Renders a money field’s HTML.
moneyInputHtml()Renders a money input’s HTML.
multiSelectFieldHtml()Renders a multi-select field’s HTML.
multiSelectHtml()Renders a multi-select input.
normalizeMenuItems()Normalizes and cleans up the given disclosure menu items.
parseMarkdown()Processes the given text as Markdown, with extra defenses against invalid tags and double-encoded entities.
rangeFieldHtml()Renders a range field’s HTML.
rangeHtml()Renders a range input’s HTML.
readOnlyNoticeHtml()Returns the notice that should show when admin is viewing the available settings pages while allowAdminChanges is set to false.
renderTemplate()Renders a control panel template.
requestedSite()Returns the site the control panel is currently working with, via a site query string param if sent.
reset()Resets requestedSite().
selectFieldHtml()Renders a select field’s HTML.
selectHtml()Renders a select input.
selectizeFieldHtml()Renders a selectize field’s HTML.
selectizeHtml()Renders a selectize input.
siteMenuItems()Returns a menu item array for the given sites, possibly grouping them by site group.
statusIndicatorHtml()Renders status indicator HTML.
statusLabelHtml()Renders status label HTML.
textFieldHtml()Renders a text field’s HTML.
textHtml()Renders a text input’s HTML.
textareaFieldHtml()Renders a textarea field’s HTML.
textareaHtml()Renders a textarea input’s HTML.
timeFieldHtml()Returns a date field’s HTML.
timeHtml()Returns a time input’s HTML.

addressFieldsHtml() ​

Since
4.0.0

Returns address fields’ HTML (sans country) for a given address.

View source

Arguments ​

Returns ​

string

autosuggestFieldHtml() ​

Since
3.7.0

Renders an autosuggest field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

buttonGroupFieldHtml() ​

Since
5.8.0

Renders a button group field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

buttonGroupHtml() ​

Since
5.8.0

Renders a button group.

View source

Arguments ​

Returns ​

string

buttonHtml() ​

Since
5.7.0

Renders a button’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

cardPreviewHtml() ​

Returns HTML for the card preview based on selected fields and attributes.

View source

Arguments ​

Returns ​

string

Throws ​

cardPreviewOptions() ​

Since
5.9.0

Returns an array of available card preview options for the given field layout.

View source

Arguments ​

Returns ​

array{label: string, value: string}[]

cardThumbOptions() ​

Since
5.9.6

Returns an array of available card thumbnail options for the given field layout.

View source

Arguments ​

Returns ​

array{label: string, value: string}[]

cardViewDesignerHtml() ​

Since
5.5.0

Renders a card view designer.

View source

Arguments ​

Returns ​

string

checkboxFieldHtml() ​

Since
3.6.0

Renders a checkbox field’s HTML.

Note that unlike the checkboxField macro in _includes/forms.html, you must set the checkbox label via $config['checkboxLabel'].

View source

Arguments ​

Returns ​

string

Throws ​

checkboxGroupFieldHtml() ​

Since
5.0.0

Renders a checkbox group field’s HTML.

View source

Arguments ​

Returns ​

string

checkboxGroupHtml() ​

Since
5.0.0

Renders a checkbox group input.

View source

Arguments ​

Returns ​

string

checkboxSelectFieldHtml() ​

Since
3.6.0

Renders a checkbox select field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

chipHtml() ​

Since
5.0.0

Renders a component’s chip HTML.

The following config settings can be passed to $config:

  • attributes – Any custom HTML attributes that should be set on the chip
  • autoReload – Whether the chip should auto-reload itself when it’s saved
  • class – Class name(s) that should be added to the container element
  • hyperlink – Whether the chip label should be hyperlinked to the component’s URL (only applies if the component implements craft\base\CpEditable)
  • id – The chip’s id attribute
  • inputName – The name attribute that should be set on a hidden input, if set
  • inputValue – The value attribute that should be set on the hidden input, if inputName is set. Defaults to [[\craft\base\Identifiable::getId()`]].
  • labelHtml – The label HTML, if it should be different from craft\base\Chippable::getUiLabel()
  • overrides – Any config overrides that should persist when the chip is re-rendered
  • selectable – Whether the chip should include a checkbox input
  • showActionMenu – Whether the chip should include an action menu (only applies if the component implements craft\base\Actionable)
  • showDescription – Whether the chip should include the component’s description (only applies if the component implements craft\base\Describable)
  • showHandle – Whether the component’s handle should be show (only applies if the component implements craft\base\Grippable)
  • showIndicators – Whether the component’s indicators should be shown (only applies if the component implements craft\base\Indicative)
  • showLabel – Whether the component’s label should be shown
  • showStatus – Whether the component’s status should be shown (only applies if the component implements craft\base\Statusable)
  • showThumb – Whether the component’s thumbnail should be shown (only applies if the component implements craft\base\Thumbable or craft\base\Iconic)
  • size – The size of the chip (small or large)
  • sortable – Whether the chip should include a drag handle

View source

Arguments ​

Returns ​

string

colorFieldHtml() ​

Since
3.6.0

Renders a color field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

colorHtml() ​

Since
5.6.0

Renders a color input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

colorSelectFieldHtml() ​

Since
5.0.0

Renders a color select field’s HTML.

View source

Arguments ​

Returns ​

string

componentPreviewHtml() ​

Since
5.4.0

Returns component preview HTML, for a list of elements.

View source

Arguments ​

Returns ​

string

componentStatusIndicatorHtml() ​

Since
5.2.0

Renders status indicator HTML for a craft\base\Statusable component.

View source

Arguments ​

Returns ​

string, null

componentStatusLabelHtml() ​

Since
5.2.0

Renders status label HTML for a craft\base\Statusable component.

View source

Arguments ​

Returns ​

string, null

customSelectFieldHtml() ​

Since
5.0.0

Renders a selectize field’s HTML.

View source

Arguments ​

Returns ​

string

customSelectHtml() ​

Since
5.0.0

Renders a custom select input.

View source

Arguments ​

Returns ​

string

dateFieldHtml() ​

Since
4.0.0

Returns a date field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

dateHtml() ​

Since
4.0.0

Returns a date input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

dateTimeFieldHtml() ​

Since
3.7.0

Renders a date + time field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

disclosureMenu() ​

Since
5.0.0

Returns a disclosure menu’s HTML.

See menuItem() for a list of supported item config options.

Horizontal rules can be defined with the following key:

  • hr – Set to true

Groups of items can be defined as well, using the following keys:

  • group – Set to true
  • heading – The group heading
  • items – The nested item definitions
  • listAttributes – any HTML attributes that should be included on the <ul>

View source

Arguments ​

Returns ​

string

earthIcon() ​

Since
5.0.0

Returns the appropriate Earth icon, depending on the system time zone.

View source

Returns ​

string

editableTableFieldHtml() ​

Since
3.6.0

Renders an editable table field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

editableTableHtml() ​

Since
5.8.0

Renders an editable table’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

elementCardHtml() ​

Since
5.0.0

Renders an element’s card HTML.

The following config settings can be passed to $config:

  • attributes – Any custom HTML attributes that should be set on the card
  • autoReload – Whether the card should auto-reload itself when it’s saved
  • context – The context the card is going to be shown in (index, field, etc.)
  • hyperlink – Whether the card label should be hyperlinked to the element’s URL
  • id – The card’s id attribute
  • inputName – The name attribute that should be set on the hidden input, if context is set to field
  • selectable – Whether the card should include a checkbox input
  • showActionMenu – Whether the card should include an action menu
  • showEditButton – Whether the card should include an edit button
  • sortable – Whether the card should include a drag handle

View source

Arguments ​

Returns ​

string

elementChipHtml() ​

Since
5.0.0

Renders an element’s chip HTML.

The following config settings can be passed to $config:

  • attributes – Any custom HTML attributes that should be set on the chip
  • autoReload – Whether the chip should auto-reload itself when it’s saved
  • class – Class name(s) that should be added to the container element
  • context – The context the chip is going to be shown in (index, field, etc.)
  • hyperlink – Whether the chip label should be hyperlinked to the element’s URL
  • id – The chip’s id attribute
  • inputName – The name attribute that should be set on a hidden input, if set
  • inputValue – The value attribute that should be set on the hidden input, if inputName is set. Defaults to [[\craft\base\Identifiable::getId()`]].
  • labelHtml – The label HTML, if it should be different from craft\base\Chippable::getUiLabel()
  • overrides – Any config overrides that should persist when the chip is re-rendered
  • selectable – Whether the chip should include a checkbox input
  • showActionMenu – Whether the chip should include an action menu
  • showDescription – Whether the chip should include the element’s description
  • showDraftName – Whether to show the draft name beside the label if the element is a draft of a published element
  • showHandle – Whether the element’s handle should be show (only applies if the element implements craft\base\Grippable)
  • showIndicators – Whether the element’s indicators should be shown (only applies if the element implements craft\base\Indicative)
  • showLabel – Whether the element’s label should be shown
  • showProvisionalDraftLabel – Whether an “Edited” badge should be added to the label if the element is a provisional draft
  • showStatus – Whether the element’s status should be shown
  • showThumb – Whether the element’s thumbnail should be shown
  • size – The size of the chip (small or large)
  • sortable – Whether the chip should include a drag handle

View source

Arguments ​

Returns ​

string

elementHtml() ​

DEPRECATED

Deprecated in 5.0.0. elementChipHtml() or elementCardHtml() should be used instead.

Since
3.5.8

Renders an element’s chip HTML.

View source

Arguments ​

  • $element (craft\base\ElementInterface) – The element to be rendered
  • $context (string) – The context the chip is going to be shown in (index, field, etc.)
  • $size (string) – The size of the chip (small or large)
  • $inputName (string, null) – The name attribute that should be set on the hidden input, if $context is set to field
  • $showStatus (boolean) – Whether the element status should be shown (if the element type has statuses)
  • $showThumb (boolean) – Whether the element thumb should be shown (if the element has one)
  • $showLabel (boolean) – Whether the element label should be shown
  • $showDraftName (boolean) – Whether to show the draft name beside the label if the element is a draft of a published element
  • $single (boolean) – Whether the input name should omit the trailing []
  • $autoReload (boolean) – Whether the element should auto-reload itself when it’s saved

Returns ​

string

elementIndexHtml() ​

Since
5.0.0

Returns the HTML for an element index.

View source

Arguments ​

  • $elementType (class-string<\craft\base\ElementInterface>)
  • $config (array)

Returns ​

string

elementPreviewHtml() ​

Since
3.6.3

Returns element preview HTML, for a list of elements.

View source

Arguments ​

  • $elements (craft\base\ElementInterface[]) – The elements
  • $size (string) – The size of the element (small or large)
  • $showStatus (boolean) – Whether the element status should be shown (if the element type has statuses)
  • $showThumb (boolean) – Whether the element thumb should be shown (if the element has one)
  • $showLabel (boolean) – Whether the element label should be shown
  • $showDraftName (boolean) – Whether to show the draft name beside the label if the element is a draft of a published element

Returns ​

string

elementSelectFieldHtml() ​

Since
3.7.0

Renders an element select field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

elementSelectHtml() ​

Since
4.0.0

Renders an element select input’s HTML

View source

Arguments ​

Returns ​

string

Throws ​

entryTypeSelectFieldHtml() ​

Since
5.0.0

Renders an entry type select field’s HTML.

View source

Arguments ​

Returns ​

string

entryTypeSelectHtml() ​

Since
5.0.0

Renders an entry type select input’s HTML

View source

Arguments ​

Returns ​

string

fallbackIconSvg() ​

Since
5.0.0

Returns a fallback icon SVG for a component with a given label.

View source

Arguments ​

Returns ​

string

fieldHtml() ​

Since
3.5.8

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

View source

Arguments ​

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

Returns ​

string

Throws ​

fieldLayoutDesignerHtml() ​

Since
4.0.0

Renders a field layout designer.

View source

Arguments ​

Returns ​

string

generatedFieldsTableHtml() ​

Renders a Generated Fields table for a field layout

View source

Arguments ​

Returns ​

string

iconPickerFieldHtml() ​

Since
5.0.0

Renders an icon picker field’s HTML.

View source

Arguments ​

Returns ​

string

iconPickerHtml() ​

Since
5.0.0

Renders an icon picker’s HTML.

View source

Arguments ​

Returns ​

string

iconSvg() ​

Since
5.0.0

Returns an SVG icon’s contents for the control panel.

The icon can be a system icon’s name (e.g. 'whiskey-glass-ice'), the path to an SVG file, or raw SVG markup.

System icons can be found in src/icons/solid/.

View source

Arguments ​

Returns ​

string, null

layoutElementSelectorHtml() ​

Since
5.0.0

Renders a field layout element’s selector HTML.

View source

Arguments ​

Returns ​

string

lightswitchFieldHtml() ​

Since
3.6.0

Renders a lightswitch field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

lightswitchHtml() ​

Since
4.0.0

Renders a lightswitch input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

menuItem() ​

Since
5.0.0

Returns a menu item’s HTML.

The item config can contain a type key set to a \craft\enums\MenuItemType case. By default, it will be set to:

  • MenuItemType::Link if url is set
  • MenuItemType::Group if heading or items are set
  • MenuItemType::Button in all other cases

Link and button item configs can contain the following keys:

  • id – The item’s ID
  • label – The item label, to be HTML-encoded
  • icon – The item icon name
  • html – The item label, which will be output verbatim, without being HTML-encoded
  • description – The item description
  • status – The status indicator that should be shown beside the item label
  • url – The URL that the item should link to
  • action – The controller action that the item should trigger
  • params – Request parameters that should be sent to the action
  • confirm – A confirmation message that should be presented to the user before triggering the action
  • redirect – The redirect path that the action should use
  • requireElevatedSession – Whether an elevated session is required before the action is triggered
  • selected – Whether the item should be marked as selected
  • hidden – Whether the item should be hidden
  • attributes – Any HTML attributes that should be set on the item’s <a> or <button> tag
  • liAttributes – Any HTML attributes that should be set on the item’s <li> tag

View source

Arguments ​

Returns ​

string

metadataHtml() ​

Returns a metadata component’s HTML.

View source

Arguments ​

  • $data (array) – The data, with keys representing the labels. The values can either be strings or callables. If a value is false, it will be omitted.

Returns ​

string

moneyFieldHtml() ​

Since
5.0.0

Renders a money field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

moneyInputHtml() ​

Since
5.0.0

Renders a money input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

multiSelectFieldHtml() ​

Since
4.0.0

Renders a multi-select field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

multiSelectHtml() ​

Since
4.0.0

Renders a multi-select input.

View source

Arguments ​

Returns ​

string

normalizeMenuItems() ​

Since
5.0.0

Normalizes and cleans up the given disclosure menu items.

View source

Arguments ​

Returns ​

array

parseMarkdown() ​

Since
5.8.3

Processes the given text as Markdown, with extra defenses against invalid tags and double-encoded entities.

View source

Arguments ​

Returns ​

string

rangeFieldHtml() ​

Since
5.5.0

Renders a range field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

rangeHtml() ​

Since
5.5.0

Renders a range input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

readOnlyNoticeHtml() ​

Since
5.6.0

Returns the notice that should show when admin is viewing the available settings pages while allowAdminChanges is set to false.

View source

Returns ​

string

renderTemplate() ​

Renders a control panel template.

View source

Arguments ​

Returns ​

string

Throws ​

requestedSite() ​

Since
4.0.0

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.

reset() ​

Since
5.7.0

Resets requestedSite().

View source

selectFieldHtml() ​

Since
3.6.0

Renders a select field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

selectHtml() ​

Since
3.6.0

Renders a select input.

View source

Arguments ​

Returns ​

string

selectizeFieldHtml() ​

Since
4.0.0

Renders a selectize field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

selectizeHtml() ​

Since
4.0.0

Renders a selectize input.

View source

Arguments ​

Returns ​

string

siteMenuItems() ​

Since
5.0.0

Returns a menu item array for the given sites, possibly grouping them by site group.

If only one site is meant to be shown, an empty array will be returned.

View source

Arguments ​

  • $sites (array<int,\craft\models\Site|array{site: \craft\models\Site, status?: string}>)
  • $selectedSite (craft\models\Site, null)
  • $config (array)

Returns ​

array

statusIndicatorHtml() ​

Since
5.0.0

Renders status indicator HTML.

When the status is equal to "draft" the draft icon will be displayed. The attributes passed as the second argument should be a status definition from craft\base\ElementInterface::statuses()

View source

Arguments ​

  • $status (string) – Status string
  • $attributes (array) – Attributes to be passed along.

Returns ​

string, null

statusLabelHtml() ​

Since
5.2.0

Renders status label HTML.

When the status is equal to "draft" the draft icon will be displayed. The attributes passed as the second argument should be a status definition from craft\base\ElementInterface::statuses()

View source

Arguments ​

  • $config (array) – Config options

Returns ​

string, null

textFieldHtml() ​

Since
3.6.0

Renders a text field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

textHtml() ​

Since
4.0.0

Renders a text input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

textareaFieldHtml() ​

Since
3.6.0

Renders a textarea field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

textareaHtml() ​

Since
4.0.0

Renders a textarea input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

timeFieldHtml() ​

Since
4.0.0

Returns a date field’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

timeHtml() ​

Since
4.0.0

Returns a time input’s HTML.

View source

Arguments ​

Returns ​

string

Throws ​

Constants ​

ConstantDescription
CHIP_SIZE_LARGE
CHIP_SIZE_SMALL
ELEMENT_SIZE_LARGE
ELEMENT_SIZE_SMALL

Events ​

EVENT_DEFINE_ELEMENT_CARD_HTML ​

Type
craft\events\DefineElementHtmlEvent
Since
5.0.0

The event that is triggered when defining an element’s card HTML.

See also elementCardHtml()

EVENT_DEFINE_ELEMENT_CHIP_HTML ​

Type
craft\events\DefineElementHtmlEvent
Since
5.0.0

The event that is triggered when defining an element’s chip HTML.

See also elementChipHtml()

EVENT_DEFINE_ELEMENT_INNER_HTML ​

DEPRECATED

Deprecated in 5.0.0. EVENT_DEFINE_ELEMENT_CHIP_HTML should be used instead.

Type
craft\events\DefineElementInnerHtmlEvent
Since
4.0.0

The event that is triggered when defining an element’s inner HTML.

EVENT_REGISTER_ALERTS ​

Type
craft\events\RegisterCpAlertsEvent

The event that is triggered when registering control panel alerts.