Custom table attributes in custom entry sources

[jamesmacwhite]

I'm using the EVENT_REGISTER_SOURCES event to create custom entry sources in the CP index context.

$event->sources[] = [
    'key' => 'exampleKey',
    'sites' => [1],
    'label' => Craft::t('plugin-handle', 'Source name'),
    'criteria' => [
        'siteId' => 1,
        'section' => 'section,
        'id' => $ids
    ],
    'data' => [
        'handle' => 'sourceHandle',
    ],
];

Is it possible to provide custom fields in the Table Attributes list for these custom sources, the fields offered are the default:

Does the event offer a way to extend the ability to allow selecting custom fields required?

[AugustMiller]

I think you're looking for the craft\base\Element::EVENT_REGISTER_TABLE_ATTRIBUTES and EVENT_DEFINE_ATTRIBUTE_HTML events, and/or the craft\services\ElementSources::EVENT_DEFINE_SOURCE_TABLE_ATTRIBUTES event.

The former must be used together to define a virtual attribute and then provide HTML for it (here's an example of registration, and rendering).

The latter is a slightly more direct version of the registration side—it allows you to act on a single element source via the dedicated craft\events\DefineSourceTableAttributes event class, which exposes elementType and source properties:

use craft\events\DefineSourceTableAttributesEvent;
use craft\services\ElementSources;
use yii\base\Event;

Event::on(
    ElementSources::class,
    ElementSources::EVENT_DEFINE_SOURCE_TABLE_ATTRIBUTES,
    function (DefineSourceTableAttributesEvent $event) {
        // Skip processing for anything but entries:
        if ($event->elementType !== Entry::class) {
           return false;
        }

        // Also skip if it's not among the custom sources we are interested in:
        if ($event->source !== 'exampleKey') {
           return false;
        }

        // Add the new attribute:
        $attributes = $event->attributes;
        $attributes['exampleAttrKey'] = [
            'label' => 'Example Attribute',
        ];

        $event->attributes = $attributes;
    }
);

Note that the "key" here (exampleAttrKey) must either correspond to an element property, a getter method, or whatever you check in EVENT_DEFINE_ATTRIBUTE_HTML:

use craft\base\Element;
use craft\events\DefineAttributeHtmlEvent;
use yii\base\Event;

Event::on(
    Element::class,
    Element::EVENT_DEFINE_ATTRIBUTE_HTML,
    function (DefineAttributeHtmlEvent $event) {
        if ($event->attribute !== 'exampleAttrKey') {
            return;
        }

        $event->html = 'HTML string!';
    }
);

If you want to skip processing any other handlers, you can also set $event->handled = true;.

[AugustMiller]

Also—custom fields’ table attribute keys generally follow this pattern…

/^(field|fieldInstance):(.+)/

…where the portion after a : is a field UUID or field layout element UUID!

[jamesmacwhite]

@AugustMiller Thanks for your reply and detailed response, this sounds like what I'm looking for and I'll test it out!

[AugustMiller]

Ah, shoot! I may have misinterpreted your question—I think that the real answer is simply: yes, you should have access to the custom fields associated with whatever entry types would be permitted by the criteria.

I am going to ask about this, internally. In the meantime, you can do something like this to backfill what Craft is missing:

use Craft;
use craft\elements\Entry;
use craft\services\ElementSources;

Event::on(
    ElementSources::class,
    ElementSources::EVENT_DEFINE_SOURCE_TABLE_ATTRIBUTES,
    function(DefineSourceTableAttributesEvent $event) {
        if ($event->source !== 'exampleKey') {
            return;
        }

        $attributes = $event->attributes;

        $event->attributes = array_merge($attributes, Craft::$app->getElementSources()->getTableAttributesForFieldLayouts(Entry::fieldLayouts(null)));
    }
);

[jamesmacwhite]

Ah OK, thanks for this. So it is more of a potential bug that custom fields are not available in any custom entry sources that have been defined?

[brandonkelly]

The selectable custom fields are based on which field layouts the element type says are available to the source. That’s defined by Element::defineFieldLayouts(). The base implementation in craft\base\Element will return all field layouts associated with the element type, however the method is overridden by Asset, Category, and Entry, in such a way that didn’t consider that the source key could have been defined via EVENT_REGISTER_SOURCES. So when an unexpected source key was passed, an empty array was returned rather than falling back to the default behavior.

I’ve fixed that for the next Craft 4 and 5 releases (3a34393 + 00a6feb). So going forward, if a source key is passed to defineFieldLayouts() that doesn’t look like a native key, each of the element types’ field layouts will be returned by default.

It might still make sense for your module/plugin to add a EVENT_REGISTER_FIELD_LAYOUTS handler, to narrow the layouts down to whichever ones are actually applicable, based on whatever other criteria your source is specifying. For example, if you are only pulling entries from one section, you could add this:

use craft\elements\Entry;
use craft\events\RegisterElementFieldLayoutsEvent;
use craft\models\EntryType;
use yii\base\Event;

Event::on(
    Entry::class,
    Entry::EVENT_REGISTER_FIELD_LAYOUTS,
    function(RegisterElementFieldLayoutsEvent $event) {
        if ($event->source === 'exampleKey') {
            $section = Craft::$app->entries->getSectionByHandle('section');
            $event->fieldLayouts = array_map(
                fn(EntryType $entryType) => $entryType->getFieldLayout(),
                $section->getEntryTypes(),
            );
        }
    },
);

(You could add that additional event handler now and custom fields will start showing up as expected; no need to wait for the next release.)

[jamesmacwhite]

Amazing, thank you! Thanks for the explanation and suggestions on implementing this with custom entry sources, I'll look at adjusting my existing sources and code.

[brandonkelly]

Just tagged 4.13.5 and Craft 5.5.5 with that fix :)