MatrixService

Type

Class

Namespace

Craft

Inherits

Craft\MatrixService » Craft\BaseApplicationComponent » CApplicationComponent (opens new window) » CComponent (opens new window)

Implements

IApplicationComponent

Since

1.3

MatrixService provides APIs for managing Matrix fields.

An instance of MatrixService is globally accessible in Craft via {@link WebApp::matrix craft()->matrix}.

See also http://craftcms.com

View source (opens new window)

Public Properties

Property	Description
$behaviors (opens new window)	array (opens new window) – The behaviors that should be attached to this component.

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__get() (opens new window)	Returns a property value, an event handler list or a behavior based on its name.
__isset() (opens new window)	Checks if a property value is null.
__set() (opens new window)	Sets value of a component property.
__unset() (opens new window)	Sets a component property to be null.
asa() (opens new window)	Returns the named behavior object.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
attachEventHandler() (opens new window)	Attaches an event handler to an event.
canGetProperty() (opens new window)	Determines whether a property can be read.
canSetProperty() (opens new window)	Determines whether a property can be set.
deleteBlockById()	Deletes a block(s) by its ID.
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.
detachEventHandler() (opens new window)	Detaches an existing event handler.
disableBehavior() (opens new window)	Disables an attached behavior.
disableBehaviors() (opens new window)	Disables all behaviors attached to this component.
enableBehavior() (opens new window)	Enables an attached behavior.
enableBehaviors() (opens new window)	Enables all behaviors attached to this component.
evaluateExpression() (opens new window)	Evaluates a PHP expression or callback under the context of 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.
getContentTableName()	Returns the content table name for a given Matrix field.
getEventHandlers() (opens new window)	Returns the list of attached event handlers for an event.
getIsInitialized() (opens new window)	Checks if this application component has been initialized.
getParentMatrixField()	Returns the parent Matrix field, if any.
hasEvent() (opens new window)	Determines whether an event is defined.
hasEventHandler() (opens new window)	Checks whether the named event has attached handlers.
hasProperty() (opens new window)	Determines whether a property is defined.
init() (opens new window)	Initializes the application component.
isInitialized()	Checks if this application component has been initialized yet, or not.
raiseEvent() (opens new window)	Raises an event.
saveBlock()	Saves a new or existing Matrix block.
saveBlockType()	Saves a block type.
saveField()	Saves a Matrix field.
saveSettings()	Saves a Matrix field's settings.
validateBlock()	Validates a block.
validateBlockType()	Validates a block type.
validateFieldSettings()	Validates a Matrix field's settings.

deleteBlockById()

Deletes a block(s) by its ID.

View source (opens new window)

Arguments

• $blockIds (integer (opens new window), array (opens new window)) – The Matrix block ID(s).

Returns

boolean (opens new window) – Whether the block(s) were deleted successfully.

Signature

public boolean deleteBlockById ( $blockIds )

deleteBlockType()

Deletes a block type.

View source (opens new window)

Arguments

• $blockType (Craft\MatrixBlockTypeModel) – The block type.

Returns

boolean (opens new window) – Whether the block type was deleted successfully.

Throws

• Exception (opens new window)

Signature

public boolean deleteBlockType ( Craft\MatrixBlockTypeModel $blockType )

deleteMatrixField()

Deletes a Matrix field.

View source (opens new window)

Arguments

• $matrixField (Craft\FieldModel) – The Matrix field.

Returns

boolean (opens new window) – Whether the field was deleted successfully.

Throws

• Exception (opens new window)

Signature

public boolean deleteMatrixField ( Craft\FieldModel $matrixField )

getBlockById()

Returns a block by its ID.

View source (opens new window)

Arguments

• $blockId (integer (opens new window)) – The Matrix block’s ID.
• $localeId (string (opens new window)) – The locale ID to return. Defaults to {@link WebApp::language craft()->language}.

Returns

Craft\MatrixBlockModel, null (opens new window) – The Matrix block, or null if it didn’t exist.

Signature

public Craft\MatrixBlockModel, null getBlockById ( $blockId, $localeId = null )

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\MatrixBlockTypeModel, null (opens new window) – The block type, or null if it didn’t exist.

Signature

public Craft\MatrixBlockTypeModel, null getBlockTypeById ( $blockTypeId )

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.
• $indexBy (string (opens new window)) – The property the block types should be indexed by. Defaults to null.

Returns

Craft\MatrixBlockTypeModel[] – An array of block types.

Signature

public Craft\MatrixBlockTypeModel[] getBlockTypesByFieldId ( $fieldId, $indexBy = null )

getContentTableName()

Returns the content table name for a given Matrix field.

View source (opens new window)

Arguments

• $matrixField (Craft\FieldModel) – The Matrix field.
• $useOldHandle (boolean (opens new window)) – Whether the method should use the field’s old handle when determining the table name (e.g. to get the existing table name, rather than the new one).

Returns

string (opens new window), false (opens new window) – The table name, or false if $useOldHandle was set to true and there was no old handle.

Signature

public string, false getContentTableName ( Craft\FieldModel $matrixField, $useOldHandle = false )

getParentMatrixField()

Returns the parent Matrix field, if any.

View source (opens new window)

Arguments

• $matrixField (Craft\FieldModel) – The Matrix field.

Returns

Craft\FieldModel, null (opens new window) – The Matrix field’s parent Matrix field, or null if there is none.

Signature

public Craft\FieldModel, null getParentMatrixField ( Craft\FieldModel $matrixField )

saveBlock()

Saves a new or existing Matrix block.

$block = new MatrixBlockModel();
$block->fieldId = 5;
$block->ownerId = 100;
$block->ownerLocale = 'en_us';
$block->typeId = 2;
$block->sortOrder = 10;

$block->setContentFromPost(array(
    'fieldHandle' => 'value',
    // ...
));

$success = craft()->matrix->saveBlock($block);

View source (opens new window)

Arguments

• $block (Craft\MatrixBlockModel) – The Matrix block.
• $validate (boolean (opens new window)) – Whether the block should be validated before being saved. Defaults to true.

Returns

boolean (opens new window) – Whether the block was saved successfully.

Throws

• Exception (opens new window)

Signature

public boolean saveBlock ( Craft\MatrixBlockModel $block, $validate = true )

saveBlockType()

Saves a block type.

View source (opens new window)

Arguments

• $blockType (Craft\MatrixBlockTypeModel) – The block type to be saved.
• $validate (boolean (opens new window)) – Whether the block type should be validated before being saved. Defaults to true.

Returns

boolean (opens new window) – Whether the block type was saved successfully.

Throws

• Exception (opens new window)

Signature

public boolean saveBlockType ( Craft\MatrixBlockTypeModel $blockType, $validate = true )

saveField()

Saves a Matrix field.

View source (opens new window)

Arguments

• $fieldType (Craft\MatrixFieldType) – The Matrix field type.

Returns

boolean (opens new window) – Whether the field was saved successfully.

Throws

• Exception (opens new window)

Signature

public boolean saveField ( Craft\MatrixFieldType $fieldType )

saveSettings()

Saves a Matrix field's settings.

View source (opens new window)

Arguments

• $settings (Craft\MatrixSettingsModel) – The settings model.
• $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

• Exception (opens new window)

Signature

public boolean saveSettings ( Craft\MatrixSettingsModel $settings, $validate = true )

validateBlock()

Validates a block. If the block doesn’t validate, any validation errors will be stored on the block.

View source (opens new window)

Arguments

• $block (Craft\MatrixBlockModel) – The Matrix block to validate.

Returns

boolean (opens new window) – Whether the block validated.

Signature

public boolean validateBlock ( Craft\MatrixBlockModel $block )

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\MatrixBlockTypeModel) – The block type.
• $validateUniques (boolean (opens new window)) – Whether the Name and Handle attributes should be validated to ensure they’re unique. Defaults to true.

Returns

boolean (opens new window) – Whether the block type validated.

Signature

public boolean validateBlockType ( Craft\MatrixBlockTypeModel $blockType, $validateUniques = true )

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

• $settings (Craft\MatrixSettingsModel) – The settings model.

Returns

boolean (opens new window) – Whether the settings validated.

Signature

public boolean validateFieldSettings ( Craft\MatrixSettingsModel $settings )