NestedElementTrait

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

NestedElementTrait

Public Properties

Property	Description
field	craft\base\ElementContainerFieldInterface, null – the element’s field
fieldId	integer, null – Field ID
owner	craft\base\ElementInterface, null – the owner element
ownerId	integer, null – the owner element’s ID
primaryOwner	craft\base\ElementInterface, null – the primary owner element
primaryOwnerId	integer, null – the primary owner element’s ID
saveOwnership	boolean – Whether to save the element’s row in the `elements_owners` table from `afterSave()`.
sortOrder	integer, null – Sort order
updateSearchIndexForOwner	boolean – 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

Method	Description
addInvalidNestedElementIds()	Registers invalid nested element IDs with the element, so an `error` class can be added on their cards.
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.

`addInvalidNestedElementIds()`

Since: 5.3.0

Registers invalid nested element IDs with the element, so an error class can be added on their cards.

View source

Arguments

$ids (integer[])

`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