MatrixService

Type
Class
Namespace
Craft
Inherits
Craft\MatrixService » Craft\BaseApplicationComponent » CApplicationComponent » CComponent
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

Public Properties

PropertyDescription
$behaviorsarray – The behaviors that should be attached to this component.

Public Methods

MethodDescription
__call()Calls the named method which is not a class method.
__get()Returns a property value, an event handler list or a behavior based on its name.
__isset()Checks if a property value is null.
__set()Sets value of a component property.
__unset()Sets a component property to be null.
asa()Returns the named behavior object.
attachBehavior()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
attachEventHandler()Attaches an event handler to an event.
canGetProperty()Determines whether a property can be read.
canSetProperty()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()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
detachEventHandler()Detaches an existing event handler.
disableBehavior()Disables an attached behavior.
disableBehaviors()Disables all behaviors attached to this component.
enableBehavior()Enables an attached behavior.
enableBehaviors()Enables all behaviors attached to this component.
evaluateExpression()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()Returns the list of attached event handlers for an event.
getIsInitialized()Checks if this application component has been initialized.
getParentMatrixField()Returns the parent Matrix field, if any.
hasEvent()Determines whether an event is defined.
hasEventHandler()Checks whether the named event has attached handlers.
hasProperty()Determines whether a property is defined.
init()Initializes the application component.
isInitialized()Checks if this application component has been initialized yet, or not.
raiseEvent()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

Arguments

Returns

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

Signature

public boolean deleteBlockById ( $blockIds )

deleteBlockType()

Deletes a block type.

View source

Arguments

Returns

boolean – Whether the block type was deleted successfully.

Throws

Signature

public boolean deleteBlockType ( Craft\MatrixBlockTypeModel $blockType )

deleteMatrixField()

Deletes a Matrix field.

View source

Arguments

Returns

boolean – Whether the field was deleted successfully.

Throws

Signature

public boolean deleteMatrixField ( Craft\FieldModel $matrixField )

getBlockById()

Returns a block by its ID.

View source

Arguments

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

Returns

Craft\MatrixBlockModel, null – 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

Arguments

  • $blockTypeId (integer) – The block type ID.

Returns

Craft\MatrixBlockTypeModel, null – 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

Arguments

  • $fieldId (integer) – The Matrix field ID.
  • $indexBy (string) – 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

Arguments

  • $matrixField (Craft\FieldModel) – The Matrix field.
  • $useOldHandle (boolean) – 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, false – 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

Arguments

Returns

Craft\FieldModel, null – 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

Arguments

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

Returns

boolean – Whether the block was saved successfully.

Throws

Signature

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

saveBlockType()

Saves a block type.

View source

Arguments

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

Returns

boolean – Whether the block type was saved successfully.

Throws

Signature

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

saveField()

Saves a Matrix field.

View source

Arguments

Returns

boolean – Whether the field was saved successfully.

Throws

Signature

public boolean saveField ( Craft\MatrixFieldType $fieldType )

saveSettings()

Saves a Matrix field's settings.

View source

Arguments

Returns

boolean – Whether the settings saved successfully.

Throws

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

Arguments

Returns

boolean – 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

Arguments

  • $blockType (Craft\MatrixBlockTypeModel) – The block type.
  • $validateUniques (boolean) – Whether the Name and Handle attributes should be validated to ensure they’re unique. Defaults to true.

Returns

boolean – 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

Arguments

Returns

boolean – Whether the settings validated.

Signature

public boolean validateFieldSettings ( Craft\MatrixSettingsModel $settings )