Skip to content

NestedElementManager ​

Type
Class
Namespace
craft\elements
Inherits
craft\elements\NestedElementManager » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
5.0.0

Nested Element Manager

This can be used by elements or fields to manage nested elements, such as users → addresses, or Matrix fields → nested entries.

If this is for a custom field, field must be set. Otherwise, attribute must be set.

View source

Public Properties ​

PropertyDescription
attributestring, null – The attribute name used to access nested elements.
behaviorsyii\base\Behavior – List of behaviors attached to this component.
criteriaarray – Additional element query params that should be set when fetching nested elements.
fieldcraft\base\FieldInterface, null – The field associated with this nested element manager.
isTranslatableboolean
ownerIdParamstring – The name of the element query param that nested elements use to associate with the owner’s ID
primaryOwnerIdParamstring – The name of the element query param that nested elements use to associate with the primary owner’s ID
propagationKeyFormatstring, null – The propagation key format that the nested elements should use, if propagationMethod is set to PropagationMethod::Custom.
propagationMethod\craft\enums\PropagationMethod – The propagation method that the nested elements should use.
translationDescriptionstring, null
valueGetterClosure, null – Closure that will get the value.
valueSetterClosure, null, false – Closure that will update the value.

attribute ​

Type
string, null
Default value
null

The attribute name used to access nested elements.

View source

criteria ​

Type
array
Default value
[]

Additional element query params that should be set when fetching nested elements.

View source

field ​

Type
craft\base\FieldInterface, null
Default value
null

The field associated with this nested element manager.

View source

isTranslatable ​

Type
boolean
Default value
null
Access
Read-only

View source

ownerIdParam ​

Type
string
Default value
'ownerId'

The name of the element query param that nested elements use to associate with the owner’s ID

View source

primaryOwnerIdParam ​

Type
string
Default value
'primaryOwnerId'

The name of the element query param that nested elements use to associate with the primary owner’s ID

View source

propagationKeyFormat ​

Type
string, null
Default value
null

The propagation key format that the nested elements should use, if propagationMethod is set to PropagationMethod::Custom.

View source

propagationMethod ​

Type
\craft\enums\PropagationMethod
Default value
\craft\enums\PropagationMethod::All

The propagation method that the nested elements should use.

This can be set to one of the following:

  • PropagationMethod::None – Only save elements in the site they were created in
  • PropagationMethod::SiteGroup – Save elements to other sites in the same site group
  • PropagationMethod::Language – Save elements to other sites with the same language
  • PropagationMethod::Custom – Save elements to other sites based on a custom propagation key format
  • PropagationMethod::All – Save elements to all sites supported by the owner element

View source

translationDescription ​

Type
string, null
Default value
null
Access
Read-only

View source

valueGetter ​

Type
Closure, null
Default value
null

Closure that will get the value.

View source

valueSetter ​

Type
Closure, null, false
Default value
null

Closure that will update the value.

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.
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.
deleteNestedElements()Deletes nested elements alongside the given owner element.
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.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getCardsHtml()Returns the HTML for managing nested elements via cards.
getIndexHtml()Returns the HTML for managing nested elements via an element index.
getIsTranslatable()Returns whether the field or attribute should be shown as translatable in the UI, for the given owner element.
getSearchKeywords()Returns the search keywords for nested elements of the given owner element.
getSupportedSiteIds()Returns the site IDs that are supported by nested elements for the given owner element.
getTranslationDescription()Returns the description of this field or attribute’s translation support, for the given owner element.
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.
maintainNestedElements()Maintains the nested elements after an owner element has been saved.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
restoreNestedElements()Restores nested elements which had been deleted alongside their owner.
trigger()Triggers an event.

__construct() ​

Constructor

View source

Arguments ​

  • $elementType (class-string<\craft\base\NestedElementInterface>) – The nested element type.
  • $queryFactory (callable) – A factory method which returns a query for fetching nested elements
  • $config (array) – Name-value pairs that will be used to initialize the object properties.

deleteNestedElements() ​

Deletes nested elements alongside the given owner element.

View source

Arguments ​

getCardsHtml() ​

Returns the HTML for managing nested elements via cards.

View source

Arguments ​

Returns ​

string

getIndexHtml() ​

Returns the HTML for managing nested elements via an element index.

View source

Arguments ​

Returns ​

string

getIsTranslatable() ​

Returns whether the field or attribute should be shown as translatable in the UI, for the given owner element.

View source

Arguments ​

Returns ​

boolean

getSearchKeywords() ​

Returns the search keywords for nested elements of the given owner element.

View source

Arguments ​

Returns ​

string

getSupportedSiteIds() ​

Since
5.0.0

Returns the site IDs that are supported by nested elements for the given owner element.

View source

Arguments ​

Returns ​

integer[]

getTranslationDescription() ​

Returns the description of this field or attribute’s translation support, for the given owner element.

View source

Arguments ​

Returns ​

string, null

init() ​

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source

maintainNestedElements() ​

Maintains the nested elements after an owner element has been saved.

This should be called from the element’s afterPropagate() method, or the field’s afterElementPropagate() method.

View source

Arguments ​

restoreNestedElements() ​

Restores nested elements which had been deleted alongside their owner.

View source

Arguments ​

Constants ​

ConstantDescription
VIEW_MODE_CARDS
VIEW_MODE_INDEX

Events ​

EVENT_AFTER_CREATE_REVISIONS ​

Type
craft\events\DuplicateNestedElementsEvent

The event that is triggered after revisions are created for nested elements.

See also \craft\elements\createRevisions()


EVENT_AFTER_DUPLICATE_NESTED_ELEMENTS ​

Type
craft\events\DuplicateNestedElementsEvent

The event that is triggered after nested elements are duplicated.


EVENT_AFTER_SAVE_ELEMENTS ​

Type
craft\events\BulkElementsEvent

The event that is triggered after nested elements are resaved.