Skip to content

ElementHelper ​

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

Class ElementHelper

View source

Public Methods ​

MethodDescription
actionConfig()Returns an element action’s JavaScript configuration.
addElementEditorUrlParams()Ensures the given element edit URL includes the necessary query string params.
attributeHtml()Returns the HTML for a given attribute value, to be shown in table and card views.
doesUriFormatHaveSlugTag()Returns whether a given URL format has a proper {slug} tag.
editableSiteIdsForElement()Returns the editable site IDs for a given element, taking user permissions into account.
elementEditorUrl()Returns a generic editor URL for the given element.
findSource()Returns an element type's source definition based on a given source key/path and context.
generateSlug()Generates a new slug based on a given string.
isAttributeEmpty()Returns whether the attribute on the given element is empty.
isCanonical()Returns whether the given element (or its root element if a block element) is a canonical element.
isDerivative()Returns whether the given element (or its root element if a block element) is a derivative of another element.
isDraft()Returns whether the given element (or its root element if a block element) is a draft.
isDraftOrRevision()Returns whether the given element (or its root element if a block element) is a draft or revision.
isElementEditable()Returns whether the given element is editable by the current user, taking user permissions into account.
isOutdated()Returns whether the given derivative element is outdated compared to its canonical element.
isRevision()Returns whether the given element (or its root element if a block element) is a revision.
isTempSlug()Returns whether the given slug is temporary.
normalizeSlug()Normalizes a slug.
postEditUrl()Returns the URL that users should be redirected to after editing the given element.
renderElements()Renders the given elements using their partial templates.
rootElement()Returns the root owner of a given element.
rootElementIfCanonical()Returns the root element of a given element, unless the element or any of its owners are not canonical.
rootSourceKey()Returns the root level source key for a given source key/path
searchableAttributes()Returns the searchable attributes for a given element, ensuring that slug and title are included.
setNextPrevOnElements()Given an array of elements, will go through and set the appropriate "next" and "prev" elements on them.
setUniqueUri()Sets the URI on an element using a given URL format, tweaking its slug if necessary to ensure it's unique.
shouldTrackChanges()Returns whether changes should be tracked for the given element.
siteStatusesForElement()Returns the site statuses for a given element.
sourceElement()Returns the canonical version of an element.
supportedSitesForElement()Returns a list of sites that a given element supports.
swapInProvisionalDrafts()Swaps out any canonical elements with provisional drafts, when they exist.
tempSlug()Generates a new temporary slug.
translationDescription()Returns the description of a field’s translation support.
translationKey()Returns the translation key for an element title or custom field, based on the given translation method and translation key format.

actionConfig() ​

Since
5.0.0

Returns an element action’s JavaScript configuration.

View source

Arguments ​

Returns ​

array

addElementEditorUrlParams() ​

Since
5.0.0

Ensures the given element edit URL includes the necessary query string params.

View source

Arguments ​

Returns ​

string

attributeHtml() ​

Since
5.0.0

Returns the HTML for a given attribute value, to be shown in table and card views.

View source

Arguments ​

  • $value (mixed) – The field value

Returns ​

string

doesUriFormatHaveSlugTag() ​

Returns whether a given URL format has a proper {slug} tag.

View source

Arguments ​

Returns ​

boolean

editableSiteIdsForElement() ​

Returns the editable site IDs for a given element, taking user permissions into account.

View source

Arguments ​

Returns ​

array

elementEditorUrl() ​

Since
5.0.0

Returns a generic editor URL for the given element.

View source

Arguments ​

Returns ​

string

findSource() ​

Returns an element type's source definition based on a given source key/path and context.

View source

Arguments ​

  • $elementType (string) – The element type class
  • $sourceKey (string) – The source key/path
  • $context (string) – The context

Returns ​

array, null – The source definition, or null if it cannot be found

generateSlug() ​

Since
3.5.0

Generates a new slug based on a given string.

This is different from normalizeSlug() in two ways:

  • Periods and underscores will be converted to dashes, whereas normalizeSlug() will leave those in-tact.
  • The string may be converted to ASCII.

View source

Arguments ​

  • $str (string) – The string
  • $ascii (boolean, null) – Whether the slug should be converted to ASCII. If null, it will depend on the config5:limitAutoSlugsToAscii config setting value.
  • $language (string, null) – The language to pull ASCII character mappings for, if needed

Returns ​

string

isAttributeEmpty() ​

Since
4.2.6

Returns whether the attribute on the given element is empty.

View source

Arguments ​

Returns ​

boolean

isCanonical() ​

Since
3.7.17

Returns whether the given element (or its root element if a block element) is a canonical element.

View source

Arguments ​

Returns ​

boolean

isDerivative() ​

Since
3.7.17

Returns whether the given element (or its root element if a block element) is a derivative of another element.

View source

Arguments ​

Returns ​

boolean

isDraft() ​

Since
3.7.0

Returns whether the given element (or its root element if a block element) is a draft.

View source

Arguments ​

Returns ​

boolean

isDraftOrRevision() ​

Since
3.2.0

Returns whether the given element (or its root element if a block element) is a draft or revision.

View source

Arguments ​

Returns ​

boolean

isElementEditable() ​

Returns whether the given element is editable by the current user, taking user permissions into account.

View source

Arguments ​

Returns ​

boolean

isOutdated() ​

Since
3.7.12

Returns whether the given derivative element is outdated compared to its canonical element.

View source

Arguments ​

Returns ​

boolean

isRevision() ​

Since
3.7.0

Returns whether the given element (or its root element if a block element) is a revision.

View source

Arguments ​

Returns ​

boolean

isTempSlug() ​

Since
3.2.2

Returns whether the given slug is temporary.

View source

Arguments ​

Returns ​

boolean

normalizeSlug() ​

Since
3.5.0

Normalizes a slug.

View source

Arguments ​

Returns ​

string

postEditUrl() ​

Since
5.2.0

Returns the URL that users should be redirected to after editing the given element.

View source

Arguments ​

Returns ​

string

renderElements() ​

Since
5.0.0

Renders the given elements using their partial templates.

If no partial template exists for an element, its string representation will be output instead.

View source

Arguments ​

Returns ​

\Twig\Markup

Throws ​

rootElement() ​

DEPRECATED

Deprecated in 5.4.0. Use craft\base\ElementInterface::getRootOwner() instead.

Since
3.2.0

Returns the root owner of a given element.

View source

Arguments ​

Returns ​

craft\base\ElementInterface

rootElementIfCanonical() ​

Since
5.0.0

Returns the root element of a given element, unless the element or any of its owners are not canonical.

View source

Arguments ​

Returns ​

craft\base\ElementInterface, null

rootSourceKey() ​

Since
3.7.25.1

Returns the root level source key for a given source key/path

View source

Arguments ​

Returns ​

string

searchableAttributes() ​

Since
4.6.0

Returns the searchable attributes for a given element, ensuring that slug and title are included.

View source

Arguments ​

Returns ​

string[]

setNextPrevOnElements() ​

Given an array of elements, will go through and set the appropriate "next" and "prev" elements on them.

View source

Arguments ​

setUniqueUri() ​

Sets the URI on an element using a given URL format, tweaking its slug if necessary to ensure it's unique.

View source

Arguments ​

Throws ​

shouldTrackChanges() ​

Since
3.7.4

Returns whether changes should be tracked for the given element.

View source

Arguments ​

Returns ​

boolean

siteStatusesForElement() ​

Since
4.4.7

Returns the site statuses for a given element.

View source

Arguments ​

  • $element (craft\base\ElementInterface) – The element to return site statuses for
  • $editableOnly (boolean) – Whether to only return statuses for sites the user has access to

Returns ​

array<int,bool> – The site statuses, indexed by site ID

sourceElement() ​

DEPRECATED

Deprecated in 3.7.0. Use craft\base\ElementInterface::getCanonical() instead.

Since
3.3.0

Returns the canonical version of an element.

View source

Arguments ​

Returns ​

craft\base\ElementInterface

supportedSitesForElement() ​

Returns a list of sites that a given element supports.

Each site is represented as an array with siteId, propagate, and enabledByDefault keys.

View source

Arguments ​

  • $element (craft\base\ElementInterface) – The element to return supported site info for
  • $withUnpropagatedSites (boolean) – Whether to include sites the element is currently not being propagated to

Returns ​

array[]

Throws ​

swapInProvisionalDrafts() ​

Since
5.2.0

Swaps out any canonical elements with provisional drafts, when they exist.

View source

Arguments ​

tempSlug() ​

Since
3.2.2

Generates a new temporary slug.

View source

Returns ​

string

translationDescription() ​

Since
3.5.0

Returns the description of a field’s translation support.

View source

Arguments ​

Returns ​

string, null

translationKey() ​

Since
3.5.0

Returns the translation key for an element title or custom field, based on the given translation method and translation key format.

View source

Arguments ​

Returns ​

string

Constants ​

ConstantDescription
URI_MAX_LENGTH