MatrixBlockElementType

Type
Class
Namespace
Craft
Inherits
Craft\MatrixBlockElementType » Craft\BaseElementType » Craft\BaseComponentType » Craft\BaseApplicationComponent » CApplicationComponent » CComponent
Implements
Craft\IComponentType, Craft\IElementType, IApplicationComponent
Since
1.3

The MatrixBlockElementType class is responsible for implementing and defining Matrix blocks as a native element type in Craft.

See also http://craftcms.com

View source

Public Properties

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

Protected Properties

PropertyDescription
$componentTypestring

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.
defineAvailableTableAttributes()Defines all of the available columns that can be shown in table views.
defineCriteriaAttributes()Defines any custom element criteria attributes for this element type.
defineSearchableAttributes()Defines which element model attributes should be searchable.
defineSortableAttributes()Defines the attributes that elements can be sorted by.
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.
getAvailableActions()Returns the available element actions for a given source (if one is provided).
getClassHandle()Returns the component’s handle, ideally based on the class name.
getContentFieldColumnsForElementsQuery()Returns the field column names that should be selected from the content table.
getContentTableForElementsQuery()Returns the content table name that should be joined into an elements query for a given element criteria.
getDefaultTableAttributes()Returns the list of table attribute keys that should be shown by default.
getEagerLoadingMap()Returns an array that maps source-to-target element IDs based on the given sub-property handle.
getEditorHtml()Returns the HTML for an editor HUD for the given element.
getElementQueryStatusCondition()Returns the element query condition for a custom status criteria.
getEventHandlers()Returns the list of attached event handlers for an event.
getFieldsForElementsQuery()Returns the fields that should take part in an upcoming elements qurery.
getIndexHtml()Returns the element index HTML.
getIsInitialized()Checks if this application component has been initialized.
getName()Returns the component’s name.
getSource()Returns a source by its key and context.
getSources()Returns this element type's sources.
getStatuses()Returns all of the possible statuses that elements of this type may have.
getTableAttributeHtml()Returns the HTML that should be shown for a given element’s attribute in Table View.
hasContent()Returns whether this element type will be storing any data in the content table (tiles or custom fields).
hasEvent()Determines whether an event is defined.
hasEventHandler()Checks whether the named event has attached handlers.
hasProperty()Determines whether a property is defined.
hasStatuses()Returns whether this element type can have statuses.
hasTitles()Returns whether this element type has titles.
init()Initializes the application component.
isInitialized()Checks if this application component has been initialized yet, or not.
isLocalized()Returns whether this element type stores data on a per-locale basis.
isSelectable()Returns whether this component should be shown when the user is creating a component of this type.
modifyElementsQuery()Modifies an element query targeting elements of this type.
onAfterMoveElementInStructure()Performs actions after an element has been moved within a structure.
populateElementModel()Populates an element model based on a query result.
raiseEvent()Raises an event.
routeRequestForMatchedElement()Routes the request when the URI matches an element.
saveElement()Saves a given element.

defineCriteriaAttributes()

Defines any custom element criteria attributes for this element type.

This method returns an array which will get merged into the array defined in {@link ElementCriteriaModel::defineAttributes()}, when new ElementCriteriaModel instances are created targeting this element type (generally from {@link ElementsService::getCriteria() craft()->elements->getCriteria()}).

If this method were to return the following:

return array(
    'foo' => AttributeType::String,
    'bar' => AttributeType::String,
);

then when someone creates a new ElementCriteriaModel instance targeting this elmeent type, they will be able to do this:

$criteria = craft()->elements->getCriteria('ThisElementType');
$criteria->foo = 'FooParamValue';
$criteria->bar = 'BarParamValue';

You can check for these custom criteria attributes, and factor their values into the actual database query, from {@link modifyElementsQuery()}.

IElementType::defineCriteriaAttributes()

IElementType::defineCriteriaAttributes()

View source

Returns

array – Custom criteria attributes.

Signature

public array defineCriteriaAttributes ( )

getContentTableForElementsQuery()

Returns the content table name that should be joined into an elements query for a given element criteria.

This method will get called from {@link ElementsService::buildElementsQuery()} as it is building out a database query to fetch elements with a given criteria. It will only be called if {@link hasContent()} returns true.

If this method returns false, no content table will be joined in, and it will be up to the elements’ {@link BaseElementModel::getContent() getContent()} methods to fetch their content rows on demand.

IElementType::getContentTableForElementsQuery()

IElementType::getContentTableForElementsQuery()

View source

Arguments

Returns

string – The content table name, or false if it cannot be determined.

Signature

public string getContentTableForElementsQuery ( Craft\ElementCriteriaModel $criteria )

getEagerLoadingMap()

Returns an array that maps source-to-target element IDs based on the given sub-property handle.

This method aids in the eager-loading of elements when performing an element query. The returned array should contain two sub-keys:

  • elementType – indicating the type of sub-elements to eager-load (the element type class handle)
  • map – an array of element ID mappings, where each element is a sub-array with source and target keys.

IElementType::getEagerLoadingMap()

IElementType::getEagerLoadingMap()

View source

Arguments

  • $sourceElements (Craft\BaseElementModel[]) – An array of the source elements
  • $handle (string) – The property handle used to identify which target elements should be included in the map

Returns

array, false – The eager-loading element ID mappings, or false if no mappings exist

Signature

public array, false getEagerLoadingMap ( $sourceElements, $handle )

getFieldsForElementsQuery()

Returns the fields that should take part in an upcoming elements qurery.

These fields will get their own parameters in the {@link ElementCriteriaModel} that gets passed in, their field types will each have an opportunity to help build the element query, and their columns in the content table will be selected by the query (for those that have one).

If a field has its own column in the content table, but the column name is prefixed with something besides “field_”, make sure you set the columnPrefix attribute on the {@link FieldModel}, so {@link ElementsService::buildElementsQuery()} knows which column to select.

IElementType::getFieldsForElementsQuery()

IElementType::getFieldsForElementsQuery()

View source

Arguments

Returns

Craft\FieldModel[]

Signature

public Craft\FieldModel[] getFieldsForElementsQuery ( Craft\ElementCriteriaModel $criteria )

getName()

Returns the component’s name.

This is what your component will be called throughout the Control Panel.

IComponentType::getName()

View source

Returns

string – The component’s name.

Signature

public string getName ( )

hasContent()

Returns whether this element type will be storing any data in the content table (tiles or custom fields).

IElementType::hasContent()

IElementType::hasContent()

View source

Returns

boolean – Whether the element type has content. Default is false.

Signature

public boolean hasContent ( )

isLocalized()

Returns whether this element type stores data on a per-locale basis.

If this returns true, the element model’s {@link BaseElementModel::getLocales() getLocales()} method will be responsible for defining which locales its data should be stored in.

IElementType::isLocalized()

IElementType::isLocalized()

View source

Returns

boolean – Whether the element type is localized. Default is false.

Signature

public boolean isLocalized ( )

modifyElementsQuery()

Modifies an element query targeting elements of this type.

If your element type is storing additional data in its own table, this method is the place to join that table in.

$query
    ->addSelect('mytable.foo, mytable.bar')
    ->join('mytable mytable', 'mytable.id = elements.id');

This is also where you get to check the {@link ElementCriteriaModel} for all the custom attributes that this element type supports via {@defineCriteriaAttributes()}, and modify the database query to reflect those parameters.

if ($criteria->foo)
{
    $query->andWhere(DbHelper::parseParam('mytable.foo', $criteria->foo, $query->params));
}

if ($criteria->bar)
{
    $query->andWhere(DbHelper::parseParam('mytable.bar', $criteria->bar, $query->params));
}

If you are able to determine from the element criteria’s paramteers that there’s no way that the query is going to match any elements, you can have it return false. The query will be stopped before it ever gets a chance to execute.

IElementType::modifyElementsQuery()

IElementType::modifyElementsQuery()

View source

Arguments

Returns

mixedfalse in the event that the method is sure that no elements are going to be found.

Signature

public mixed modifyElementsQuery ( Craft\DbCommand $query, Craft\ElementCriteriaModel $criteria )

populateElementModel()

Populates an element model based on a query result.

This method is called by {@link ElementsService::findElements()} after it has finished fetching all of the matching elements’ rows from the database.

For each row of data returned by the query, it will call this method on the element type, and it is up to this method to take that array of raw data from the database, and populate a new element model with it.

You should be able to accomplish this with a single line:

return MyElementTypeModel::populateModel($row);

IElementType::populateElementModel()

IElementType::populateElementModel()

View source

Arguments

  • $row (array) – The row of data in the database query result.

Returns

array – The element model, populated with the data in $row.

Signature

public array populateElementModel ( $row )

Protected Methods

MethodDescription
getTableAttributesForSource()Returns the attributes that should be shown for the given source.
prepElementCriteriaForTableAttribute()Preps the element criteria for a given table attribute