ElementsService

Type

Class

Namespace

Craft

Inherits

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

Implements

IApplicationComponent

Since

1.0

ElementsService provides APIs for managing elements.

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

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.
buildElementsQuery()	Preps a {@link DbCommand} object for querying for elements, based on a given element criteria.
canGetProperty() (opens new window)	Determines whether a property can be read.
canSetProperty() (opens new window)	Determines whether a property can be set.
deleteElementById()	Deletes an element(s) by its ID(s).
deleteElementsByType()	Deletes elements by a given type.
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.
eagerLoadElements()	Eager-loads additional elements onto a given set of elements.
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.
findElements()	Finds elements.
getAction()	Returns an element action by its class handle.
getAllActions()	Returns all installed element actions.
getAllElementTypes()	Returns all installed element types.
getCriteria()	Returns an element criteria model for a given element type.
getElementById()	Returns an element by its ID.
getElementByUri()	Returns an element by its URI.
getElementType()	Returns an element type by its class handle.
getElementTypeById()	Returns the element type(s) used by the element of a given ID(s).
getElementUriForLocale()	Returns an element’s URI for a given locale.
getEnabledLocalesForElement()	Returns the locales that a given element is enabled in.
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.
getTotalElements()	Returns the total number of elements that match a given criteria.
handleRequestEnd()	Perform element clean-up work.
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.
mergeElementsByIds()	Merges two elements together.
onBeforeBuildElementsQuery()	Fires an 'onBeforeBuildElementsQuery' event.
onBeforeDeleteElements()	Fires an 'onBeforeDeleteElements' event.
onBeforePerformAction()	Fires an 'onBeforePerformAction' event.
onBeforeSaveElement()	Fires an 'onBeforeSaveElement' event.
onBuildElementsQuery()	Fires an 'onBuildElementsQuery' event.
onMergeElements()	Fires an 'onMergeElements' event.
onPerformAction()	Fires an 'onPerformAction' event.
onPopulateElement()	Fires an 'onPopulateElement' event.
onPopulateElements()	Fires an 'onPopulateElements' event.
onSaveElement()	Fires an 'onSaveElement' event.
parseRefs()	Parses a string for element reference tags (opens new window).
populateElements()	Populates element models from a given element query's result set.
raiseEvent() (opens new window)	Raises an event.
saveElement()	Handles all of the routine tasks that go along with saving elements.
setPlaceholderElement()	Stores a placeholder element that {@link findElements()} should use instead of populating a new element with a matching ID and locale.
updateDescendantSlugsAndUris()	Updates an element’s descendants’ slugs and URIs.
updateElementSlugAndUri()	Updates an element’s slug and URI, along with any descendants.
updateElementSlugAndUriInOtherLocales()	Updates an element’s slug and URI, for any locales besides the given one.

buildElementsQuery()

Preps a {@link DbCommand} object for querying for elements, based on a given element criteria.

View source (opens new window)

Arguments

• $criteria
• $contentTable
• $fieldColumns
• $justIds (boolean (opens new window)) – Whether the method should only return an array of the IDs of the matched elements. Defaults to false.

Returns

Craft\DbCommand, false (opens new window) – The DbCommand object, or false if the method was able to determine ahead of time that there’s no chance any elements are going to be found with the given parameters.

Signature

public Craft\DbCommand, false buildElementsQuery ( &$criteria = null, &$contentTable = null, &$fieldColumns = null, $justIds = false )

deleteElementById()

Deletes an element(s) by its ID(s).

View source (opens new window)

Arguments

• $elementIds (integer (opens new window), array (opens new window)) – The element’s ID, or an array of elements’ IDs.

Returns

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

Throws

• Exception (opens new window)

Signature

public boolean deleteElementById ( $elementIds )

deleteElementsByType()

Deletes elements by a given type.

View source (opens new window)

Arguments

• $type (string (opens new window)) – The element type class handle.

Returns

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

Signature

public boolean deleteElementsByType ( $type )

eagerLoadElements()

Eager-loads additional elements onto a given set of elements.

View source (opens new window)

Arguments

• $elementType (Craft\BaseElementType) – The root element type
• $elements (Craft\BaseElementModel[]) – The root element models that should be updated with the eager-loaded elements
• $with (string (opens new window), array (opens new window)) – Dot-delimited paths of the elements that should be eager-loaded into the root elements

Returns

void

Signature

public void eagerLoadElements ( Craft\BaseElementType $elementType, $elements, $with )

findElements()

Finds elements.

View source (opens new window)

Arguments

• $criteria (Craft\ElementCriteriaModel) – An element criteria model that defines the parameters for the elements we should be looking for.
• $justIds (boolean (opens new window)) – Whether the method should only return an array of the IDs of the matched elements. Defaults to false.

Returns

array (opens new window) – The matched elements, or their IDs, depending on $justIds.

Signature

public array findElements ( $criteria = null, $justIds = false )

getAction()

Returns an element action by its class handle.

View source (opens new window)

Arguments

• $class (string (opens new window)) – The element action class handle.

Returns

Craft\IElementAction, null (opens new window) – The element action, or null.

Signature

public Craft\IElementAction, null getAction ( $class )

getAllActions()

Returns all installed element actions.

View source (opens new window)

Returns

Craft\IElementAction[] – The installed element actions.

Signature

public Craft\IElementAction[] getAllActions ( )

getAllElementTypes()

Returns all installed element types.

View source (opens new window)

Returns

Craft\IElementType[] – The installed element types.

Signature

public Craft\IElementType[] getAllElementTypes ( )

getCriteria()

Returns an element criteria model for a given element type. This should be the starting point any time you want to fetch elements in Craft.

$criteria = craft()->elements->getCriteria(ElementType::Entry);
$criteria->section = 'news';
$entries = $criteria->find();

View source (opens new window)

Arguments

• $type (string (opens new window)) – The element type class handle (e.g. one of the values in the {@link ElementType} enum).
• $attributes (mixed) – Any criteria attribute values that should be pre-populated on the criteria model.

Returns

Craft\ElementCriteriaModel – An element criteria model, wired to fetch elements of the given $type.

Throws

• Craft\Exception

Signature

public Craft\ElementCriteriaModel getCriteria ( $type, $attributes = null )

getElementById()

Returns an element by its ID. If no element type is provided, the method will first have to run a DB query to determine what type of element the $elementId is, so you should definitely pass it if it’s known.

The element’s status will not be a factor when using this method.

View source (opens new window)

Arguments

• $elementId (integer (opens new window)) – The element’s ID.
• $elementType (null (opens new window)) – The element type’s class handle.
• $localeId (string (opens new window)) – The locale to fetch the element in. Defaults to {@link WebApp::language craft()->language}.

Returns

Craft\BaseElementModel, null (opens new window) – The matching element, or null.

Signature

public Craft\BaseElementModel, null getElementById ( $elementId, $elementType = null, $localeId = null )

getElementByUri()

Returns an element by its URI.

View source (opens new window)

Arguments

• $uri (string (opens new window)) – The element’s URI.
• $localeId (string (opens new window), null (opens new window)) – The locale to look for the URI in, and to return the element in. Defaults to {@link WebApp::language craft()->language}.
• $enabledOnly (boolean (opens new window)) – Whether to only look for an enabled element. Defaults to false.

Returns

Craft\BaseElementModel, null (opens new window) – The matching element, or null.

Signature

public Craft\BaseElementModel, null getElementByUri ( $uri, $localeId = null, $enabledOnly = false )

getElementType()

Returns an element type by its class handle.

View source (opens new window)

Arguments

• $class (string (opens new window)) – The element type class handle.

Returns

Craft\IElementType, null (opens new window) – The element type, or null.

Signature

public Craft\IElementType, null getElementType ( $class )

getElementTypeById()

Returns the element type(s) used by the element of a given ID(s). If a single ID is passed in (an int), then a single element type will be returned (a string), or null if no element exists by that ID.

If an array is passed in, then an array will be returned.

View source (opens new window)

Arguments

• $elementId (integer (opens new window), array (opens new window)) – An element’s ID, or an array of elements’ IDs.

Returns

string (opens new window), array (opens new window), null (opens new window) – The element type(s).

Signature

public string, array, null getElementTypeById ( $elementId )

getElementUriForLocale()

Returns an element’s URI for a given locale.

View source (opens new window)

Arguments

• $elementId (integer (opens new window)) – The element’s ID.
• $localeId (string (opens new window)) – The locale to search for the element’s URI in.

Returns

string (opens new window), null (opens new window) – The element’s URI, or null.

Signature

public string, null getElementUriForLocale ( $elementId, $localeId )

getEnabledLocalesForElement()

Returns the locales that a given element is enabled in.

View source (opens new window)

Arguments

• $elementId (integer (opens new window)) – The element’s ID.

Returns

array (opens new window) – The locales that the element is enabled in. If the element could not be found, an empty array will be returned.

Signature

public array getEnabledLocalesForElement ( $elementId )

getTotalElements()

Returns the total number of elements that match a given criteria.

View source (opens new window)

Arguments

• $criteria (Craft\ElementCriteriaModel) – An element criteria model that defines the parameters for the elements we should be counting.

Returns

integer (opens new window) – The total number of elements that match the criteria.

Signature

public integer getTotalElements ( $criteria = null )

handleRequestEnd()

Perform element clean-up work.

View source (opens new window)

Signature

public void handleRequestEnd ( )

mergeElementsByIds()

Merges two elements together. This method will update the following:

• Any relations involving the merged element
• Any structures that contain the merged element
• Any reference tags in textual custom fields referencing the merged element

View source (opens new window)

Arguments

• $mergedElementId (integer (opens new window)) – The ID of the element that is going away.
• $prevailingElementId (integer (opens new window)) – The ID of the element that is sticking around.

Returns

boolean (opens new window) – Whether the elements were merged successfully.

Throws

• Exception (opens new window)

Signature

public boolean mergeElementsByIds ( $mergedElementId, $prevailingElementId )

onBeforeBuildElementsQuery()

Fires an 'onBeforeBuildElementsQuery' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeBuildElementsQuery ( Craft\Event $event )

onBeforeDeleteElements()

Fires an 'onBeforeDeleteElements' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeDeleteElements ( Craft\Event $event )

onBeforePerformAction()

Fires an 'onBeforePerformAction' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforePerformAction ( Craft\Event $event )

onBeforeSaveElement()

Fires an 'onBeforeSaveElement' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBeforeSaveElement ( Craft\Event $event )

onBuildElementsQuery()

Fires an 'onBuildElementsQuery' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onBuildElementsQuery ( Craft\Event $event )

onMergeElements()

Fires an 'onMergeElements' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onMergeElements ( Craft\Event $event )

onPerformAction()

Fires an 'onPerformAction' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onPerformAction ( Craft\Event $event )

onPopulateElement()

Fires an 'onPopulateElement' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onPopulateElement ( Craft\Event $event )

onPopulateElements()

Fires an 'onPopulateElements' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onPopulateElements ( Craft\Event $event )

onSaveElement()

Fires an 'onSaveElement' event.

View source (opens new window)

Arguments

• $event (Craft\Event)

Returns

null (opens new window)

Signature

public null onSaveElement ( Craft\Event $event )

parseRefs()

Parses a string for element reference tags (opens new window).

View source (opens new window)

Arguments

• $str (string (opens new window)) – The string to parse.

Returns

string (opens new window) – The parsed string.

Signature

public string parseRefs ( $str )

populateElements()

Populates element models from a given element query's result set.

View source (opens new window)

Arguments

• $results (array (opens new window)) – The result set of an element query
• $criteria (Craft\ElementCriteriaModel) – The element criteria model
• $contentTable (string (opens new window)) – The content table that was joined in by buildElementsQuery()
• $fieldColumns (array (opens new window)) – Info about the content field columns being selected

Returns

Craft\BaseElementModel[] – The populated element models.

Signature

public Craft\BaseElementModel[] populateElements ( $results, Craft\ElementCriteriaModel $criteria, $contentTable, $fieldColumns )

saveElement()

Handles all of the routine tasks that go along with saving elements. Those tasks include:

• Validating its content (if $validateContent is true, or it’s left as null and the element is enabled)
• Ensuring the element has a title if its type {@link BaseElementType::hasTitles() has titles}, and giving it a default title in the event that $validateContent is set to false
• Saving a row in the elements table
• Assigning the element’s ID on the element model, if it’s a new element
• Assigning the element’s ID on the element’s content model, if there is one and it’s a new set of content
• Updating the search index with new keywords from the element’s content
• Setting a unique URI on the element, if it’s supposed to have one.
• Saving the element’s row(s) in the elements_i18n and content tables
• Deleting any rows in the elements_i18n and content tables that no longer need to be there
• Calling the field types’ {@link BaseFieldType::onAfterElementSave() onAfterElementSave()} methods
• Cleaing any template caches that the element was involved in

This method should be called by a service’s “saveX()” method, after it is done validating any attributes on the element that are of particular concern to its element type. For example, if the element were an entry, saveElement() should be called only after the entry’s sectionId and typeId attributes had been validated to ensure that they point to valid section and entry type IDs.

View source (opens new window)

Arguments

• $element (Craft\BaseElementModel) – The element that is being saved
• $validateContent (boolean (opens new window), null (opens new window)) – Whether the element's content should be validated. If left 'null', it will depend on whether the element is enabled or not.

Returns

boolean (opens new window)

Throws

• \Craft\Exception|\Exception

Signature

public boolean saveElement ( Craft\BaseElementModel $element, $validateContent = null )

setPlaceholderElement()

Stores a placeholder element that {@link findElements()} should use instead of populating a new element with a matching ID and locale. This is used by Live Preview and Sharing features.

View source (opens new window)

Arguments

• $element (Craft\BaseElementModel) – The element currently being edited by Live Preview.

Returns

null (opens new window)

Signature

public null setPlaceholderElement ( Craft\BaseElementModel $element )

updateDescendantSlugsAndUris()

Updates an element’s descendants’ slugs and URIs.

View source (opens new window)

Arguments

• $element (Craft\BaseElementModel) – The element whose descendants should be updated.
• $updateOtherLocales (boolean (opens new window)) – Whether the element’s other locales should also be updated.
• $asTask (boolean (opens new window)) – Whether the descendants’ slugs and URIs should be updated via a background task.

Returns

null (opens new window)

Signature

public null updateDescendantSlugsAndUris ( Craft\BaseElementModel $element, $updateOtherLocales = true, $asTask = false )

updateElementSlugAndUri()

Updates an element’s slug and URI, along with any descendants.

View source (opens new window)

Arguments

• $element (Craft\BaseElementModel) – The element to update.
• $updateOtherLocales (boolean (opens new window)) – Whether the element’s other locales should also be updated.
• $updateDescendants (boolean (opens new window)) – Whether the element’s descendants should also be updated.
• $asTask (boolean (opens new window)) – Whether the element’s slug and URI should be updated via a background task.

Returns

null (opens new window)

Signature

public null updateElementSlugAndUri ( Craft\BaseElementModel $element, $updateOtherLocales = true, $updateDescendants = true, $asTask = false )

updateElementSlugAndUriInOtherLocales()

Updates an element’s slug and URI, for any locales besides the given one.

View source (opens new window)

Arguments

• $element (Craft\BaseElementModel) – The element to update.

Returns

null (opens new window)

Signature

public null updateElementSlugAndUriInOtherLocales ( Craft\BaseElementModel $element )