Attribute Basics

Concrete CMS Custom Attributes

Concrete CMS allows attaching custom data to objects like pages, users, and files. Examples include setting a page's 'Exclude from Nav' or viewing a file's dimensions. Custom attributes play a key role in these functionalities.

Custom Attributes Creation

Concrete editors can easily create custom attributes for pages, users, or files via the Dashboard, as detailed in the editor's guide. Developers have more extensive options, like adding new attribute types and integrating them into custom objects. Understanding attributes is crucial, especially for Express data management.

Attribute Keys

These are the custom attributes added via the Dashboard, like "Exclude from Nav", "Width", "Height", etc. Creating an attribute key means adding a custom attribute.

Attribute Types

Types of data stored by a custom attribute when creating an attribute key. Common types include "Text", "Textarea", "Boolean", and "Image/File". Developers often extend the system by creating custom attribute types.

Attribute Key Settings

Introduced in version 8, these settings objects store configurations for specific attribute keys, simplifying data management without custom database queries. For instance, settings for a textarea attribute are stored in Concrete\Core\Entity\Attribute\Key\Settings\TextareaSettings.

Attribute Categories

Categories are object types in Concrete that can be linked to custom attribute values, such as Pages, Files, and Users.

Attribute Values

Values assigned to pages, files, or users in the Concrete interface or programmatically create attribute values linking an attribute category identifier (like a page ID) with an attribute key and a data value object.

Attribute Data Values

These objects store specific data types in the database, such as a numerical value in Concrete\Core\Entity\Attribute\Value\Value\NumberValue.

Attribute Controllers

Each attribute type has a controller, a Concrete class responsible for data management in different views and situations. Custom attribute types require a corresponding controller.

Attribute Value Objects and Output Formatting

Working with attributes programmatically often involves using methods like:

$file->getAttribute('width'); // returns a decimal

$page->getAttribute('exclude_nav'); // returns true or false

$page->getAttribute('thumbnail'); // returns a Concrete\Core\Entity\File\File object or null

These methods return the attribute's native value, the most flexible and useful format. For instance, the Image/File attribute returns a file object, not just a file ID.

However, for displaying attributes on a webpage or in an email, we need different representations. Consider an array of attribute keys:

$attributes = array($widthKey, $excludeKey, $thumbnailKey);

Looping through these attributes and processing the response requires a conditional approach:

foreach($attributes as $key) {
    $response = $page->getAttribute($key);
    switch($key->getAttributeTypeHandle()) {
        // cases for 'boolean', 'image_file', 'number'
    }
}

This method is limited and not easily extensible. A better approach is using getAttributeValueObject() which returns an instance of Concrete\Core\Attribute\AttributeValueInterface or null. This method offers more options:

$file->getAttributeValueObject('width'); // returns Concrete\Core\Entity\Attribute\Value\FileValue
$page->getAttributeValueObject('exclude_nav'); // returns Concrete\Core\Entity\Attribute\Value\PageValue
$page->getAttributeValueObject('thumbnail'); // returns Concrete\Core\Entity\Attribute\Value\PageValue

With the attribute value object, you can access the controller, underlying value object, and different output responses:

$thumbnail = $page->getAttributeValueObject('thumbnail');
print $thumbnail->getDisplayValue(); // Outputs <img src="/path/to/image.jpg" />
print $thumbnail->getPlainTextValue(); // Outputs URL
print $thumbnail->getSearchIndexValue(); // Returns ID

Controlling the Attribute Value Response

Native Value

Defining a getValue() method in the data value entity class or attribute type controller controls the native response.

Display Value

Implement getDisplayValue() in the attribute type controller or __toString() in the custom value class for custom display responses.

Plain Text Value

Works similarly to display value, controlled by getPlainTextValue() or __toString().

Search Index Value

Controlled by getSearchIndexValue() within the attribute type controller, determining the value returned to the search indexer.