Modifying field formats and the Content Name Pattern in Ibexa DXP

Content management systems, including the Ibexa DXP, typically create a Content Name for each content item stored in the database. Content Names are automatically generated from attributes required for a content type, and so do not necessarily match other content attributes, such as Title, that users can edit directly.

Content Names are useful in a variety of applications, such as search results that include content items that may not have a Title attribute – user accounts, dates, and the like. In short, every content object has a Content Name, so they are the global, friendly identifier for content items in the Ibexa DXP.

In some instances, you may want to change the fields that are used to generate Content Names, or change how those fields are formatted. Perhaps the primary attribute used to generate the Content Name is not unique to each item of a content type,, and you want to append another field to its name for easier identification. And perhaps you also want to dress up the way this additional field attribute publishes.

In this post, I’ll demonstrate how to modify the Content Name Pattern that Ibexa uses to identify content items. I’ll also show you how to “decorate” the display of a specific field name to further customize how content items present themselves to users.

Figure 1

We’ve decorated the format of date fields and changed the content naming pattern of a content type to create this customized display.

We’ve decorated the format of date fields and changed the content naming pattern of a content type to create this customized display.

Creating a more meaningful content name

One of our clients here at Mugo Web operates a repository of legal case rulings related to high-end residential real estate, the focus of its B2B publishing business. Given the highly structured nature of legal rulings, we created a content type, called Case, to encapsulate these legal records with field attributes such as Case Title and Decision Date.

Since these cases are formally named for the litigants involved, they can share a Case_title value with several other cases. In our example depicted in Figure 1, there might be several rulings named “Behrend v. Gramercy-Rutherford Townhouse Corp.” in the court record.

So, our client wanted to distinguish these items by adding the info of when the case in question was decided, which we hold in the Decision ate field. The client also wanted to make the Decision Date field display in a more friendly format, so we wrote code in Symfony to “decorate” the display of this information.

You can see the results in the image above – case rulings display in Ibexa with their case name, followed by a custom-formatted ruling date, set off by parentheses.

Decorating the format of fields with Symfony

First, let’s look at the Symfony code required to decorate the display of the Decision Date field. By default, each field type generates a display string based on the method, getName.

For the Date field type, this is hard-coded as:

$value->date->format('l d F Y')

This means that when a Date field type is presented in Ibexa, it will appear as “Wednesday 5 September 2018".

However, with Symfony you can decorate the field type service to present it as you wish. For example, if we want to change the format of the Date Type field from “l d F Y” to “M j, Y” we can define the service as follows:

services:
    Mugo\CustomBundle\FieldType\Date\Type:
        decorates: 'ezpublish.fieldType.ezdate'
        arguments: ['@.inner']

Then we create the code:

bundles/Mugo/CustomBundle/FieldType/Date/Type.php

<?php
namespace Mugo\CustomBundle\FieldType\Date;
use eZ\Publish\Core\FieldType\Date\Type as BaseDateType;
use eZ\Publish\API\Repository\Values\ContentType\FieldDefinition;
use eZ\Publish\SPI\FieldType\Value as SPIValue;
use eZ\Publish\Core\FieldType\Date\Value;
use eZ\Publish\Core\Base\Exceptions\InvalidArgumentType;
class Type extends BaseDateType
{
    private $decorated;
    public function __construct(BaseDateType $decorated)
    {
        $this->decorated = $decorated;
    }
    /**
     * @param \eZ\Publish\Core\FieldType\Date\Value|\Mugo\CustomBundle\FieldType\Date\Value|\eZ\Publish\SPI\FieldType\Value $value
     */
    public function getName(SPIValue $value, FieldDefinition $fieldDefinition, string $languageCode): string
    {
        if ($this->isEmptyValue($value)) {
            return '';
        }
        return $value->date->format('M j, Y');
    }
    protected static function checkValueType($value): void
    {
        if (!$value instanceof Value) {
            throw new InvalidArgumentType('$value', Value::class, $value);
        }
    }
}

Now, when dates publish in the Ibexa UX, they will take the format “Sep 5, 2018". Note that this is a global change for all content types that use this field type, unless you add some more code to limit the change to certain field types.

Figure 2

This custom Content Name Pattern will present the Case content type with a combination of a text field and a custom “decorated” date, along with parentheses.

This custom Content Name Pattern will present the Case content type with a combination of a text field and a custom “decorated” date, along with parentheses.

Changing the Content Name Pattern

With our Decision Date field display decorated, we can now change the Content Name Pattern for our Case content type to include all the information we want.

The Content Name Pattern is set within the Ibexa Admin interface at:

Admin > Content Types > Content > [CONTENT TYPE]

This value is expressed as <field_identifier>, with any literal text you want to include outside the carat characters. For example, you might use the Content Name Pattern Gift #<code> to more clearly label gift codes in an ecommerce solution.

In our example project, as shown in Figure 2, we set the Content Name Pattern for content type Case to:

<case_title> (<decision_date>)

To create the naming pattern you see in Figure 1.

Some possible workarounds and caveats

The Ibexa DXP does offer some workarounds for the process I just detailed, but each approach has its own drawbacks.

It’s possible to edit templates to change the name format for items of a certain content type on a case-by-case basis. But this could require an enormous amount of template editing, and break fetches based on the Content Name containing the required pattern.

Another possible workaround is to add an on-publish workflow to update either a distinct field or the content name to fit your desired pattern. This can work, but it also can cause problems, such as ensuring that the content name is updated not only when the content is published but also when it is edited. As well, adding redundant field is seldom good practice, and could create confusion if an editor tries to update the content in that field manually.

Conclusion

In this post, I’ve looked at ways to decorate the display of field content and change the naming pattern of content types in the Ibexa DXP. And the real-world example we discussed is just one practical application. For example, you could use the same approach to include a checkbox value or an approver’s identity in the content name.

By customizing the Content Name Pattern, you can make it much easier for users to identify the content they need to access within the Ibexa DXP.