Attribute Keys

Attribute Keys in a Package

Review the theme packaging documentation for understanding Concrete CMS package format and controller file.

To add a custom attribute type like 'Property Location' to a 'Property Manager' package with handle property_manager:

Create package directories:

mkdir packages/property_manager
mkdir packages/property_manager/attributes/

Move entities from application/src/Entity to packages/property_manager/src/Concrete/Entity, changing namespaces from PropCo\Property\Location to Concrete\Package\PropertyManager\Entity.

Transfer property_location attribute type:

mv application/blocks/property_location packages/property_manager/attributes/property_location

In the package's install() method, instantiate Concrete\Core\Attribute\TypeFactory using Concrete\Core\Application\Application:

public function install()
{
   $pkg = parent::install();
   $factory = $this->app->make('Concrete\Core\Attribute\TypeFactory');
   $type = $factory->getByHandle('property_location');
   if (!is_object($type)) {
       $type = $factory->add('property_location', 'Property Location', $pkg);
   }       
}

Link attribute type with pages:

$service = $this->app->make('Concrete\Core\Attribute\Category\CategoryService');
$category = $service->getByHandle('collection')->getController();
$category->associateAttributeKeyType($type);

$service->getByHandle('collection') retrieves a Concrete\Core\Entity\Attribute\Category object. Use getController for the Concrete\Core\Attribute\Category\PageCategory class.

Grouping Attribute Keys into Sets

Add attribute keys to sets during package installation for organization or integration with existing sets.

For an existing "Exclude Subpages from Nav" attribute:

Access the key object:

$key = $category->getByHandle('exclude_subpages_from_nav');
if (!is_object($key)) {
   $key = new PageKey();
   $key->setAttributeKeyHandle('exclude_subpages_from_nav');
   $key->setAttributeKeyName('Exclude Subpages from Nav');
   $key = $category->add('boolean', $key, null, $pkg);
}

Retrieve the attribute set entity:

$factory = $this->app->make('Concrete\Core\Attribute\SetFactory');
$navSet = $factory->getByHandle('navigation'); // the built-in navigation set

Associate the key to the set:

$service = $this->app->make('Concrete\Core\Attribute\Category\CategoryService');
$categoryEntity = $service->getByHandle('collection');
$category = $categoryEntity->getController();
$setManager = $category->getSetManager();
$setManager->addKey($navSet, $key);

To create a new set and add keys:

Check if the set exists:

$factory = $this->app->make('Concrete\Core\Attribute\SetFactory');
$set = $factory->getByHandle('fancy_new_set');
if (!is_object($set)) {
   // Set doesn't exist
}

Add the set if not present:

$service = $this->app->make('Concrete\Core\Attribute\Category\CategoryService');
$categoryEntity = $service->getByHandle('collection');
$category = $categoryEntity->getController();
$setManager = $category->getSetManager();
$set = $setManager->addSet('fancy_new_set', 'Fancy New Set', $pkg);

Associate keys to the new set:
```
$setManager->addKey($set, $key);
```

Validating Attribute Keys and Values

Complex attribute types need validation before saving to prevent database issues. This applies to both keys and values, ensuring they meet specific criteria.

Validating Attribute Keys

For validation, consider an attribute key with a custom select menu. Implement a validateKey() method in the controller to ensure an option is selected. Add an empty option to the type_form.php select menu and then validate:

<fieldset>
    <legend><?= t('Location Settings') ?></legend>
    <div class="form-group">
        <label class="control-label" for="formDisplayMethod">Form Display Method</label>
        <select class="form-control" name="formDisplayMethod">
            <option value="">** Choose a Display Method</option>
            <!-- Other options here -->
        </select>
    </div>
</fieldset>

public function validateKey($data = false)
{
    $e = $this->app->make('error');
    if (!isset($data['formDisplayMethod']) || !in_array($data['formDisplayMethod'], ['select', 'radio_list'])) {
        $e->add(t('You must specify a display method.'));
    }
    return $e;
}

Validating Attribute Value Forms

Similarly, add validation for an attribute's form submission. Use validateForm($data) in the attribute type controller:

// Form with None option and other selections

public function validateForm($data)
{
    if (!isset($data['propertyLocationID']) || !$data['propertyLocationID']) {
        return new FieldNotPresentError(new AttributeField($this->getAttributeKey()));
    }
    $propertyLocationID = intval($data['propertyLocationID']);
    if (!in_array($propertyLocationID, [1, 2, 3, 4])) {
        return new Error(t('Invalid property location ID.'), new AttributeField($this->getAttributeKey()));
    }
    return true;
}

Validating Attributes in Current State, Not Form Submission

To validate attributes based on their current value objects rather than form submissions, use validateValue():

public function validateValue()
{
    $location = $this->getValue();
    if (!is_object($location)) {
        return new Error(t('Property Location missing.'), new AttributeField($this->getAttributeKey()));
    }
    if (!$location->getLocationID()) {
        return new Error(t('Invalid property location ID.'), new AttributeField($this->getAttributeKey()));
    }
    return true;
}

This process ensures attributes are validated in various contexts.

CIF Example: Attribute Keys

Attribute keys are defined inside an attributekeys tag right under the main concrete5-cif tag. Every attribute key is defined by an attributekey tag.

<?xml version="1.0"?>
<concrete5-cif version="1.0">
    <attributekeys>
        <attributekey ... />
        <attributekey ... />
        ...
    </attributekeys>
</concrete5-cif>

Common `attributekey` attributes

Any type of attribute key have these attributes:

package [required] is the handle of the package that installs the attribute
category [required] is the category handle of the attribute key. These are the the default category handles:
- collection: for page attributes
- file for file attributes
- site for site attributes
- user for user attributes
type [required] is the handle of type of the attribute values. These are the default attribute type handles:
- address: address attribute value
- boolean: checkbox attribute value
- date_time: date/time attribute value
- email: email attribute value
- express: express entity attribute value
- image_file: image/file attribute value
- number: number attribute value
- page_selector: page selector attribute value
- rating: rating attribute value
- select: option list attribute value
- social_links: social links attribute value
- telephone: phone number attribute value
- text: text attribute value
- textarea: text area attribute value
- topics: topics attribute value
- url: URL attribute value
handle [required] is the handle of the attribute key
name [required] is the name of the attribute key
indexed [optional, defaults to 0] set to 1 to include the attribute in the search by keywords
searchable [optional, defaults to 0] set to 1 to make the attribute available in custom dashboard searches

Attributes for the `user` attribute keys

In addition to the common attributes, you can also use these attributes:

profile-displayed [optional, defaults to 0] set to 1 to show the attribute in public profile pages
member-list-displayed [optional, defaults to 0] set to 1 to show the attribute in member list pages
profile-editable [optional, defaults to 0] set to 1 to make the attribute editable in profile pages
profile-required [optional, defaults to 0] set to 1 to make the attribute editable and required in profile pages
register-editable [optional, defaults to 0] set to 1 to show the attribute on registration forms
register-required [optional, defaults to 0] set to 1 to require the attribute on registration forms

Example:

<attributekey
    package="my_package_handle"
    category="user"
    type="text"
    handle="first_last_name"
    name="First and last name"
    indexed="1"
    searchable="1"
    profile-displayed="1"
    member-list-displayed="1"
    profile-editable="1"
    profile-required="1"
    register-editable="1"
    register-required="1"
/>