Add Event for adding custom tabs to element "Edit" screens at runtime

[michaelrog]

Continuing the conversation we started in the Commerce repo...

It'd be great to have a way for plugins to add custom tabs to element edit screens at runtime.

Something like...

Event::on(
    Fields::class,
    Fields::EVENT_MODIFY_TABS,
    function(ElementTabsEvent $event) {
        if ($event->element instanceof Entry) {
            $tabs = $event->tabs;
            $tabs[] = [
                'label' => "My Tab",
                'url' => 'mytab',
                'class' => 'custom-tab',
                'content' => Craft::$app->getView()->renderTemplate('my-plugin/_myTab',
            ];
            $event->tabs = $tabs;
        }
    }
);

For Commerce Orders, an additional "static" rendering would also potentially be needed:

Event::on(
    Fields::class,
    Fields::EVENT_MODIFY_TABS,
    function(ElementTabsEvent $event) {
        if ($event->element instanceof Order) {
            $tabs = $event->tabs;
            $tabs[] = [
                'label' => "My Tab",
                'class' => 'custom-tab',
                'content' => Craft::$app->getView()->renderTemplate('my-plugin/_myTab',
                'staticContent' => Craft::$app->getView()->renderTemplate('my-plugin/_myTab_static',
            ];
            $event->tabs = $tabs;
        }
    }
);

It's already technically possible to add custom tabs, by hijacking the Twig context in template hooks... but it feels icky. Having an officially supported method would be much nicer. 😄

[brandonkelly]

Just added a new EVENT_CREATE_FORM event to craft\models\FieldLayout for Craft 3.6.

This will trigger right before createForm() starts looping through the field layout’s tabs, and gives you a chance to modify the existing tabs or add new ones.

Note that at this stage you are dealing with FieldLayoutTab and FieldLayoutElement models, not the raw HTML. It is up to each individual field layout element to define its rendered HTML, via formHtml().

Here’s an example of how to add a new tab to a field layout, with a text field, HR, and rendered template:

use craft\elements\Entry;
use craft\events\CreateFieldLayoutFormEvent;
use craft\fieldlayoutelements\HorizontalRule;
use craft\fieldlayoutelements\StandardTextField;
use craft\fieldlayoutelements\Template;
use craft\models\FieldLayout;
use craft\models\FieldLayoutTab;
use yii\base\Event;

Event::on(
    FieldLayout::class,
    FieldLayout::EVENT_CREATE_FORM,
    function(CreateFieldLayoutFormEvent $event) {
        if ($event->element instanceof Entry) {
            $event->tabs[] = new FieldLayoutTab([
                'name' => 'My Tab',
                'elements' => [
                    new StandardTextField([
                        'attribute' => 'myTextField',
                        'label' => 'My Text Field',
                    ]),
                    new HorizontalRule(),
                    new Template([
                        'template' => '_layout-elements/info'
                    ]),
                ],
            ]);
        }
    }
);

You can tell if the form should be rendered statically via $event->static.

[brandonkelly]

Craft 3.6 RC2 is out now with that new event.

[brandonkelly]

Craft 3.6 has now been officially released ✨

[michaelrog]

Just finished a hefty refactor of our Commerce plugin's tab UI to use this new event instead of our previous hacks. It's so much cleaner (and less bug-prone) now!

@brandonkelly this was a really nice implementation. The FieldLayoutElement models are easy to work with, and all the abstractions feel like they're in just the right spots. Bravo, and thanks! 🙏🏼

[michaelrog]

p.s. To my future self (and maybe to @mattstein for docs)... 😃

The Template UI element renders its target template in the site template mode. In this context, plugin templates are not automatically available.

This is easily solved by using the EVENT_REGISTER_SITE_TEMPLATE_ROOTS event to register my template root for the site context. (Craft already registers cp template roots automatically, in BasePlugin; it's up to the user to register site template roots manually.)

And if you're getting really fancy, trying to render templates from other plugins, modules, or Craft, then you can invoke the renderTemplate function directly (from one of your own templates), to force the cp context:

{{ craft.app.view.renderTemplate(
    'some-other-plugin/_includeThatNeedsToBeRenderedInCp',
    { ... },
    'cp'
) | raw }}

[brandonkelly]

For plugin-provided UI, it’s probably better to just define your own custom field layout UI elements, by extending craft\fieldlayoutelements\BaseUiElement.