It's often useful to let the machines do the work, and output something that's dynamically computed on an entity. By that I mean something that can't be hardcoded as a fixed value for all entities of a particular type, but that varies for each entity, in a way that allows it to be generated in code rather than laboriously entered into each entity form by humans.
For example, you might want a backlink for an entity reference, or a link to a view that has an argument for the entity's ID, or something that depends on field values on the entity.
There are several ways in Drupal of putting something dynamic on the entity's display output. You can of course add something to the build array yourself, in either the entity's view handler or hook_entity_view(). The extra fields system lets you then declare your additional build array item with hook_entity_extra_field_info() which allows it to be rearranged among normal fields in the field admin UI.
This is okay, but the extra fields system is Drupal 5-era stuff. Your piece of build array is just that, some render stuff; it can't participate in any data structures and nothing else will recognise it and work with it.
A better approach is a computed field. This involves a little more boilerplate code than the extra fields technique, but there are several benefits.
The first is that you are defining a field value, not a render array, and you get access to all the field formatters that apply to your type of data. So for example, if your computed data is a URL, you get all of the link field formatters at your disposal, in core and contrib.
The second is that anything that works with fields will be aware of your computed field. So you can add it to a view as a field (though not a sort or filter of course, since it has nothing in the database). You can add it to a SearchAPI index (and there, you actually can filter on it, because SearchAPI will index the computed value into its backend).
The code
Here's what you need to do. You need two things:
- A FieldItemList class.
- A declaration of your field in an entity class or field info hook.
Unlike declaring code fields, you don't need to declare a field storage: that's because a computed field doesn't store anything!
1. The FieldItemList class
Create a subclass of \Drupal\Core\Field\FieldItemList that uses
\Drupal\Core\TypedData\ComputedItemListTrait. In this class, all you need to do
is implement computeValue() to return your data.
<?php
// The namespace doesn't matter, but I like to put it under \Field.
namespace Drupal\my_module\Field;
use Drupal\Core\Field\FieldItemList;
use Drupal\Core\TypedData\ComputedItemListTrait;
use Drupal\Core\Url;
/**
* Field item list class for my computed field.
*/
class MyFieldFieldItemList extends FieldItemList {
use ComputedItemListTrait;
/**
* {@inheritdoc}
*/
protected function computeValue() {
// You have access to the complete entity, so you can use other field
// values.
$entity = $this->parent->getValue();
// Create a field item for your data. You can create more than one for a
// multi-valued field.
$this->list[] = $this->createItem(0, [
'value' => 'cake',
]);
}
}
?>
For most field types, the key to use in the item array is 'value', but some more specialised fields
use something else. You can find this by looking in the field item class for the
field type. For example, in \Drupal\link\Plugin\Field\FieldType\LinkItem::propertyDefinitions()
you can see that for a link field, you need these array keys:
$this->list[] = $this->createItem(0, [
'title' => $this->t('My link title'),
'uri' => $some_url_that_we-compute->toUriString(),
]);
2. Define the field
For the field definition, there are two things to consider:
- Is it on an entity type you control, or somebody else's?
- Do you want a base field or a bundle field?
If it's your own entity type, you define the field in the entity class, in either the baseFieldDefinitions() or bundleFieldDefinitions() method. If it's an existing entity type, you need to use hook_entity_base_field_info() or hook_entity_bundle_field_info().
In all cases, the code is broadly similar. For a base field, it looks like this:
/**
* Implements hook_entity_base_field_info().
*/
#[Hook('entity_base_field_info')]
function entityBaseFieldInfo(EntityTypeInterface $entity_type) {
if ($entity_type->id() == 'node') {
$fields = [];
$fields['my_computed_field'] = BaseFieldDefinition::create('link')
->setLabel($this->t('My computed field'))
->setDescription($this->t('My field is amazing.'))
// This declares it as a computed field.
->setComputed(TRUE)
// This is the class you created earlier, which provides the values.
->setClass(MyFieldFieldItemList::class)
// Optional default view display options, which can be overriden in the admin UI.
->setDisplayOptions('view', [
'label' => 'above',
'type' => 'link',
'weight' => '0',
]);
return $fields;
}
}
For a bundle field, you need the Drupal\entity\BundleFieldDefinition class from Entity module, and a few extra
things need to be explicitly set on the definition because the field system doesn't handle them for you:
$fields['my_computed_field'] = BundleFieldDefinition::create('link')
->setName('my_computed_field')
->setTargetEntityTypeId($entity_type_id)
->setTargetBundle($bundle)
// Rest of the definition as above.
See my earlier blog post on bundle fields for more about their uses and their quirks.
The contrib module
If you want to do it all with less boilerplate, or your computed field is something that's reusable across different entity types, consider the Computed Field module as an alternative to the code examples above. Instead of a Field class, the computational code does in a plugin, which the module then makes available in an admin UI where you can create and edit computed fields alongside the usual stored fields.
And if your computed field is purely a render array rather than data, the Computed Field module
also provides a computed_render_array field type for that, with an accompanying field formatter.
Do you need help with data structures, and their integration with Views or SearchAPI? I'm available for hire - contact me!