Builder Templates

Extend the page builder template support for third party extensions.

With a custom template you are able to create layouts with the builder for views of third party extensions. This combined with dynamic content feature allows you to use the content of this view and assign it to elements in your layout.

Adding a Template

The templates YOOtheme Pro can be extended by listening to the customizer.init event in the bootstrap.php file of a module. The config parameter customizer.templates is used to register a template type and pick an unique key as template identifier. Additional fields can be used to set filter parameters for the template which are used to match the template and show them only on a certain page.

<?php

namespace MyApp;

use YOOtheme\Config;

class TemplateListener
{
    public function initCustomizer(Config $config)
    {
        $config->add('customizer.templates', [

            'com_example.index' => [
                'label' => 'My Index Template',
                'fieldset' => [
                    'default' => [
                        'fields' => [
                            'my_field' => [
                                'label' => 'My Field',
                                'description' => 'My field description ...',
                                'type' => 'text',
                            ],
                        ],
                    ],
                ],

            ],

        ]);
    }
}

Matching a Template

After registering a template it also needs to be matched on the page in order to render the builder layout. Therefore you need to listen to the builder.template event to implement your custom matching logic. On a view match return an array with the type and query of the matching template definition. Optionally parameters can be passed to the builder by setting the params key of the returned array.

<?php

namespace MyApp;

class TemplateListener
{
    public static function matchTemplate($view, $tpl)
    {
        $layout = $view->getLayout();
        $context = $view->get('context');

        // match context and layout from view object
        if ($context === 'com_example.index' && $layout === 'default' && !$tpl) {

            // return type, query and parameters of the matching view
            return [
                'type' => $context,
                'query' => ['my_field' => $view->get('my_field')],
                'params' => ['item' => $view->get('item')],
            ];
        }
    }
}

Event Arguments

Argument Type Description
$view Joomla\CMS\MVC\View\HtmlView A view object which is currently rendered.
$tpl string A view sub-template if available.

Adding a Query Type

The templates can query data from view using a dedicated Query type. This code example creates a example_item query which will resolve a MyItem type. Since this dynamic content source is only available on the matching view the metadata needs to have a view option with the template identifier, in this example com_example.index. The root value can be used to access all parameters from the builder, including the parameters passed by matching the template. The previous example does this by using the params option to pass the item parameter.

Note Read the sources guide on how to create dynamic content sources with GraphQL.

<?php

namespace MyApp;

class MyQueryType
{
    public static function config()
    {
        return [

            'fields' => [

                'example_item' => [

                    'type' => 'MyItem',

                    'metadata' => [

                        // Label in dynamic content select box
                        'label' => 'Example Item',

                        // Option group in dynamic content select box
                        'group' => 'Example',

                        // Template identifer for the current view
                        'view' => ['com_example.index'],
                    ],

                    'extensions' => [
                        'call' => __CLASS__ . '::resolve',
                    ],

                ],

            ]

        ];
    }

    public static function resolve($root, $args, $context, $info)
    {
        // get item from root value parameter array
        if (isset($root['item'])) {
            return $root['item'];
        }
    }
}
YOOtheme Pro Documentation