Skip to content

NestedElementTrait

Type
Trait
Namespace
craft\base
Implemented by
craft\elements\Address, craft\elements\Entry
Since
5.0.0

NestedElementTrait

View source

Public Properties

PropertyDescription
fieldcraft\base\ElementContainerFieldInterface, null – the element’s field
fieldIdinteger, null – Field ID
ownercraft\base\ElementInterface, null – the owner element
ownerIdinteger, null – the owner element’s ID
primaryOwnercraft\base\ElementInterface, null – the primary owner element
primaryOwnerIdinteger, null – the primary owner element’s ID
saveOwnershipboolean – Whether to save the element’s row in the elements_owners table from afterSave().
sortOrderinteger, null – Sort order
updateSearchIndexForOwnerboolean – Whether the search index should be updated for the owner element, alongside this element.

field

Type
craft\base\ElementContainerFieldInterface, null
Default value
null

the element’s field

View source

fieldId

Type
integer, null
Default value
null

Field ID

View source

owner

Type
craft\base\ElementInterface, null
Default value
null

the owner element

View source

ownerId

Type
integer, null
Default value
null

the owner element’s ID

View source

primaryOwner

Type
craft\base\ElementInterface, null
Default value
null

the primary owner element

View source

primaryOwnerId

Type
integer, null
Default value
null

the primary owner element’s ID

View source

saveOwnership

Type
boolean
Default value
true

Whether to save the element’s row in the elements_owners table from afterSave().

View source

sortOrder

Type
integer, null
Default value
null

Sort order

View source

updateSearchIndexForOwner

Type
boolean
Default value
false
Since
5.2.0

Whether the search index should be updated for the owner element, alongside this element.

This will only be checked if fieldId is set, and false isn’t passed to the updateSearchIndex argument of craft\services\Elements::saveElement().

View source

Public Methods

MethodDescription
attributes()Returns the list of attribute names.
eagerLoadingMap()Returns an array that maps source-to-target element IDs based on the given sub-property handle.
extraFields()Returns the list of fields that can be expanded further and returned by \craft\base\toArray().
getField()Returns the field that contains the element.
getOwner()Returns the owner element, if the element has one.
getOwnerId()Returns the owner element’s ID, if the element has one.
getPrimaryOwner()Returns the primary owner element, if the element has one.
getPrimaryOwnerId()Returns the primary owner element’s ID, if the element has one.
getSortOrder()Returns the element’s sort order, if it has one.
setEagerLoadedElements()Sets some eager-loaded elements on a given handle.
setOwner()Sets the owner element, if the element has one.
setOwnerId()Sets the owner element’s ID, if the element has one.
setPrimaryOwner()Sets the primary owner element, if the element has one.
setPrimaryOwnerId()Sets the primary owner element’s ID, if the element has one.
setSaveOwnership()Sets whether the element’s ownership should be saved when the element is saved.
setSortOrder()Sets the element’s sort order.

attributes()

Returns the list of attribute names.

By default, this method returns all public non-static properties of the class. You may override this method to change the default behavior.

View source

Returns

string[] – List of attribute names.

eagerLoadingMap()

Returns an array that maps source-to-target element IDs based on the given sub-property handle.

This method aids in the eager-loading of elements when performing an element query. The returned array should contain the following keys:

  • elementType – the fully qualified class name of the element type that should be eager-loaded
  • map – an array of element ID mappings, where each element is a sub-array with source and target keys
  • criteria (optional) – any criteria parameters that should be applied to the element query when fetching the eager-loaded elements
  • createElement (optional) - an element factory function, which will be passed the element query, the current query result data, and the first source element that the result was eager-loaded for
php
use craft\base\ElementInterface;
use craft\db\Query;

public static function eagerLoadingMap(array $sourceElements, string $handle)
{
    switch ($handle) {
        case 'author':
            $bookIds = array_map(fn(ElementInterface $element) => $element->id, $sourceElements);
            $map = (new Query)
                ->select(['source' => 'id', 'target' => 'authorId'])
                ->from('{{%books}}')
                ->where(['id' => $bookIds)
                ->all();
            return [
                'elementType' => \my\plugin\Author::class,
                'map' => $map,
            ];
        case 'bookClubs':
            $bookIds = array_map(fn(ElementInterface $element) => $element->id, $sourceElements);
            $map = (new Query)
                ->select(['source' => 'bookId', 'target' => 'clubId'])
                ->from('{{%bookclub_books}}')
                ->where(['bookId' => $bookIds)
                ->all();
            return [
                'elementType' => \my\plugin\BookClub::class,
                'map' => $map,
            ];
        default:
            return parent::eagerLoadMap($sourceElements, $handle);
    }
}

View source

Arguments

  • $sourceElements (self[]) – An array of the source elements
  • $handle (string) – The property handle used to identify which target elements should be included in the map

Returns

array, null, false – The eager-loading element ID mappings, false if no mappings exist, or null if the result should be ignored

extraFields()

Returns the list of fields that can be expanded further and returned by \craft\base\toArray().

This method is similar to \craft\base\fields() except that the list of fields returned by this method are not returned by default by \craft\base\toArray(). Only when field names to be expanded are explicitly specified when calling \craft\base\toArray(), will their values be exported.

The default implementation returns an empty array.

You may override this method to return a list of expandable fields based on some context information (e.g. the current application user).

View source

Returns

array – The list of expandable field names or field definitions. Please refer to \craft\base\fields() on the format of the return value.

getField()

Returns the field that contains the element.

View source

Returns

craft\base\ElementContainerFieldInterface, null

Throws

getOwner()

Returns the owner element, if the element has one.

View source

Returns

craft\base\ElementInterface, null

Throws

getOwnerId()

Returns the owner element’s ID, if the element has one.

View source

Returns

integer, null

Throws

getPrimaryOwner()

Returns the primary owner element, if the element has one.

View source

Returns

craft\base\ElementInterface, null

Throws

getPrimaryOwnerId()

Returns the primary owner element’s ID, if the element has one.

View source

Returns

integer, null

Throws

getSortOrder()

Returns the element’s sort order, if it has one.

View source

Returns

integer, null

setEagerLoadedElements()

Sets some eager-loaded elements on a given handle.

View source

Arguments

  • $handle (string) – The handle that was used to eager-load the elements
  • $elements (self[]) – The eager-loaded elements
  • $plan (craft\elements\db\EagerLoadPlan) – The eager-loading plan

setOwner()

Sets the owner element, if the element has one.

View source

Arguments

setOwnerId()

Sets the owner element’s ID, if the element has one.

View source

Arguments

setPrimaryOwner()

Sets the primary owner element, if the element has one.

View source

Arguments

setPrimaryOwnerId()

Sets the primary owner element’s ID, if the element has one.

View source

Arguments

setSaveOwnership()

Sets whether the element’s ownership should be saved when the element is saved.

View source

Arguments

setSortOrder()

Sets the element’s sort order.

View source

Arguments