Matrix
- Type
- Class
- Namespace
- craft\services
- Inherits
- craft\services\Matrix » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
- Implements
- yii\base\Configurable (opens new window)
- Since
- 3.0.0
The Matrix service provides APIs for managing Matrix fields.
An instance of the service is available via Craft::$app->matrix
.
View source (opens new window)
# Public Properties
Property | Description |
---|---|
allBlockTypes | craft\models\MatrixBlockType[] – An array of block types. |
behaviors (opens new window) | yii\base\Behavior (opens new window) – List of behaviors attached to this component. |
# allBlockTypes
- Type
- craft\models\MatrixBlockType[]
- Default value
null
- Access
- Read-only
- Since
- 3.3.0
An array of block types.
View source (opens new window)
# Public Methods
Method | Description |
---|---|
__call() (opens new window) | Calls the named method which is not a class method. |
__clone() (opens new window) | This method is called after the object is created by cloning an existing one. |
__construct() (opens new window) | Constructor. |
__get() (opens new window) | Returns the value of a component property. |
__isset() (opens new window) | Checks if a property is set, i.e. defined and not null. |
__set() (opens new window) | Sets the value of a component property. |
__unset() (opens new window) | Sets a component property to be null. |
attachBehavior() (opens new window) | Attaches a behavior to this component. |
attachBehaviors() (opens new window) | Attaches a list of behaviors to the component. |
behaviors() (opens new window) | Returns a list of behaviors that this component should behave as. |
canGetProperty() (opens new window) | Returns a value indicating whether a property can be read. |
canSetProperty() (opens new window) | Returns a value indicating whether a property can be set. |
className() (opens new window) | Returns the fully qualified name of this class. |
createRevisionBlocks() | Creates revisions for all the blocks that belong to the given canonical element, and assigns those revisions to the given owner revision. |
defineContentTableName() | Defines a new Matrix content table name. |
deleteBlockType() | Deletes a block type. |
deleteMatrixField() | Deletes a Matrix field. |
detachBehavior() (opens new window) | Detaches a behavior from the component. |
detachBehaviors() (opens new window) | Detaches all behaviors from the component. |
duplicateBlocks() | Duplicates Matrix blocks from one owner element to another. |
duplicateOwnership() | Duplicates block ownership relations for a new draft element. |
ensureBehaviors() (opens new window) | Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component. |
getAllBlockTypes() | Returns all the block types. |
getBehavior() (opens new window) | Returns the named behavior object. |
getBehaviors() (opens new window) | Returns all behaviors attached to this component. |
getBlockById() | Returns a block by its ID. |
getBlockTypeById() | Returns a block type by its ID. |
getBlockTypesByFieldId() | Returns the block types for a given Matrix field. |
getSupportedSiteIds() | Returns the site IDs that are supported by Matrix blocks for the given propagation method and owner element. |
handleChangedBlockType() | Handle block type change |
handleDeletedBlockType() | Handle block type change |
hasEventHandlers() (opens new window) | Returns a value indicating whether there is any handler attached to the named event. |
hasMethod() (opens new window) | Returns a value indicating whether a method is defined. |
hasProperty() (opens new window) | Returns a value indicating whether a property is defined for this component. |
init() (opens new window) | Initializes the object. |
mergeCanonicalChanges() | Merges recent canonical Matrix block changes into the given Matrix field’s blocks. |
off() (opens new window) | Detaches an existing event handler from this component. |
on() (opens new window) | Attaches an event handler to an event. |
saveBlockType() | Saves a block type. |
saveField() | Saves a Matrix field. |
saveSettings() | Saves a Matrix field's settings. |
trigger() (opens new window) | Triggers an event. |
validateBlockType() | Validates a block type. |
validateFieldSettings() | Validates a Matrix field's settings. |
# createRevisionBlocks()
- Since
- 4.0.0
Creates revisions for all the blocks that belong to the given canonical element, and assigns those revisions to the given owner revision.
View source (opens new window)
Arguments
$field
(craft\fields\Matrix) – The Matrix field$canonical
(craft\base\ElementInterface) – The canonical element$revision
(craft\base\ElementInterface) – The revision element
# defineContentTableName()
- Since
- 3.0.23
Defines a new Matrix content table name.
View source (opens new window)
Arguments
$field
(craft\fields\Matrix)
Returns
# deleteBlockType()
Deletes a block type.
View source (opens new window)
Arguments
$blockType
(craft\models\MatrixBlockType) – The block type.
Returns
boolean (opens new window) – Whether the block type was deleted successfully.
# deleteMatrixField()
Deletes a Matrix field.
View source (opens new window)
Arguments
$matrixField
(craft\fields\Matrix) – The Matrix field.
Returns
boolean (opens new window) – Whether the field was deleted successfully.
Throws
# duplicateBlocks()
- Since
- 3.2.0
Duplicates Matrix blocks from one owner element to another.
View source (opens new window)
Arguments
$field
(craft\fields\Matrix) – The Matrix field to duplicate blocks for$source
(craft\base\ElementInterface) – The source element blocks should be duplicated from$target
(craft\base\ElementInterface) – The target element blocks should be duplicated to$checkOtherSites
(boolean (opens new window)) – Whether to duplicate blocks for the source element’s other supported sites$deleteOtherBlocks
(boolean (opens new window)) – Whether to delete any blocks that belong to the element, which weren’t included in the duplication$trackDuplications
(boolean (opens new window)) – Whether to keep track of the duplications from craft\services\Elements::$duplicatedElementIds and craft\services\Elements::$duplicatedElementSourceIds$force
(boolean (opens new window)) – Whether to force duplication, even if it looks like only the block ownership was duplicated
Throws
- Throwable (opens new window)
if reasons
# duplicateOwnership()
- Since
- 4.0.0
Duplicates block ownership relations for a new draft element.
View source (opens new window)
Arguments
$field
(craft\fields\Matrix) – The Matrix field$canonical
(craft\base\ElementInterface) – The canonical element$draft
(craft\base\ElementInterface) – The draft element
# getAllBlockTypes()
- Since
- 3.3.0
Returns all the block types.
View source (opens new window)
Returns
craft\models\MatrixBlockType[] – An array of block types.
# getBlockById()
Returns a block by its ID.
View source (opens new window)
Arguments
$blockId
(integer (opens new window)) – The Matrix block’s ID.$siteId
(integer (opens new window), null (opens new window)) – The site ID to return. Defaults to the current site.
Returns
craft\elements\MatrixBlock, null (opens new window) – The Matrix block, or null
if it didn’t exist.
# getBlockTypeById()
Returns a block type by its ID.
View source (opens new window)
Arguments
$blockTypeId
(integer (opens new window)) – The block type ID.
Returns
craft\models\MatrixBlockType, null (opens new window) – The block type, or null
if it didn’t exist.
# getBlockTypesByFieldId()
Returns the block types for a given Matrix field.
View source (opens new window)
Arguments
$fieldId
(integer (opens new window)) – The Matrix field ID.
Returns
craft\models\MatrixBlockType[] – An array of block types.
# getSupportedSiteIds()
- Since
- 3.3.18
Returns the site IDs that are supported by Matrix blocks for the given propagation method and owner element.
View source (opens new window)
Arguments
$propagationMethod
(string (opens new window))$owner
(craft\base\ElementInterface)$propagationKeyFormat
(string (opens new window), null (opens new window))
Returns
# handleChangedBlockType()
Handle block type change
View source (opens new window)
Arguments
$event
(craft\events\ConfigEvent)
# handleDeletedBlockType()
Handle block type change
View source (opens new window)
Arguments
$event
(craft\events\ConfigEvent)
Throws
- Throwable (opens new window)
if reasons
# mergeCanonicalChanges()
- Since
- 3.7.0
Merges recent canonical Matrix block changes into the given Matrix field’s blocks.
View source (opens new window)
Arguments
$field
(craft\fields\Matrix) – The Matrix field$owner
(craft\base\ElementInterface) – The element the field is associated with
# saveBlockType()
Saves a block type.
View source (opens new window)
Arguments
$blockType
(craft\models\MatrixBlockType) – The block type to be saved.$runValidation
(boolean (opens new window)) – Whether the block type should be validated before being saved. Defaults totrue
.
Returns
Throws
- yii\base\Exception (opens new window)
if an error occurs when saving the block type - Throwable (opens new window)
if reasons
# saveField()
Saves a Matrix field.
View source (opens new window)
Arguments
$field
(craft\fields\Matrix) – The Matrix field$owner
(craft\base\ElementInterface) – The element the field is associated with
Throws
- Throwable (opens new window)
if reasons
# saveSettings()
Saves a Matrix field's settings.
View source (opens new window)
Arguments
$matrixField
(craft\fields\Matrix) – The Matrix field$validate
(boolean (opens new window)) – Whether the settings should be validated before being saved.
Returns
boolean (opens new window) – Whether the settings saved successfully.
Throws
- Throwable (opens new window)
if reasons
# validateBlockType()
Validates a block type.
If the block type doesn’t validate, any validation errors will be stored on the block type.
View source (opens new window)
Arguments
$blockType
(craft\models\MatrixBlockType) – The block type.
Returns
boolean (opens new window) – Whether the block type validated.
# validateFieldSettings()
Validates a Matrix field's settings.
If the settings don’t validate, any validation errors will be stored on the settings model.
View source (opens new window)
Arguments
$matrixField
(craft\fields\Matrix) – The Matrix field
Returns
boolean (opens new window) – Whether the settings validated.