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.