Working with Elements

This document is for a version of Craft CMS that is no longer supported. Please refer to the latest version →

Assets, categories, entries, global sets, Matrix blocks, tags, and users are all considered “elements” in Craft, and working with them is generally pretty consistent, thanks to shared element-focused APIs.

# Fetching Elements

To fetch elements in Craft, you first need to create a new Craft\ElementCriteriaModel (opens new window) instance (yes, the same type of object used to fetch elements from your templates).

Craft\ElementsService (opens new window) provides a getCriteria() function that makes this easy:

$criteria = craft()->elements->getCriteria(ElementType::Entry);

You pass in the class handle of whatever element type you want to fetch. Craft provides constants for each of the built-in element types’ class handles:

  • ElementType::Asset
  • ElementType::Category
  • ElementType::Entry
  • ElementType::GlobalSet
  • ElementType::MatrixBlock
  • ElementType::Tag
  • ElementType::User

What is returned is an ElementCriteriaModel that is ready to be populated with parameters that will tell Craft how it should filter the available elements.

The actual list of available parameters depends on the element type. They are identical to the parameters available to your templates. See craft.entries for a list of the parameters available when fetching entries, for example.

ElementCriteriaModel’s are really just regular old models, and these “parameters” are model attributes. You can set them exactly the same way you would set other models’ attributes.

$criteria->section = 'news';
$criteria->order   = 'postDate desc';
$criteria->limit   = 5;

Once you’ve set your parameters, the last step is to actually fetch the elements. You can do this by calling find(), first(), last(), ids(), or total() – again, just like it works from your templates.

$entries = $criteria->find();

Note that find() will be called automatically within your ElementCriteriaModel if you treat it like an array, so it’s not actually necessary to call it yourself.

foreach ($criteria as $entry)
{
    echo $entry->title . '<br>';
}

# Accessing Element Properties

The elements that are returned via find(), first(), and last() will be models that extend BaseElementModel. Accessing element properties like id and title is just like accessing regular object properties:

$title = $entry->title;

You can access custom field values in the same way:

$body = $entry->myBodyField;

It all works exactly the same as you’re probably used to when working with elements in your templates, because it is exactly the same.

# Saving Elements

If you need to make changes to an element, or create a new one, generally the best place to do that will be through the element types’ own APIs. For example entries should be saved with craft()->entries->saveEntry() (opens new window).

# Creating new Element Types

If you’re writing a plugin that has a need to provide its own Element Type to the system, at a minimum you will need two classes:

  • A class that extends BaseElementType in an elementtypes/ subfolder
  • A class that extends BaseElementModel in a models/ subfolder

We are still documenting all of the different features these classes have at their disposal, along with several other aspects of creating custom element types.

Here are some existing resources, if you want to start diving in: