Builder Templates

Add template support for third party extensions to the YOOtheme Pro page builder.

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 in YOOtheme Pro can be extended by listening to the customizer.init event in the bootstrap.php file of a module, or in a child theme's config.php file. The config parameter customizer.templates is used to register a template type and pick a 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', [

            'example.single' => [
                'label' => 'My Single 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.

The event receives the current WP_Query. This example matches a single post of the example custom post type and passes the current post to the builder.

<?php

namespace MyApp;

use WP_Post;
use WP_Query;

class TemplateListener
{
    public static function matchTemplate(WP_Query $query): ?array
    {
        if (!$query->is_singular('example')) {
            return null;
        }

        $item = $query->get_queried_object();

        if (!$item instanceof WP_Post) {
            return null;
        }

        return [
            'type' => 'example.single',
            'query' => ['my_field' => get_post_meta($item->ID, 'my_field', true)],
            'params' => ['item' => $item],
        ];
    }
}

Event Arguments

Adding a Query Type

The templates can query data from a view using a dedicated Query type. This code example creates an 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 matching template identifier. 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 identifier for the current view
                        'view' => ['example.single'],
                    ],

                    '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'];
        }
    }
}

Adding a Preview URL

Optionally, you can also provide a preview URL that is used in the customizer preview, when clicking on a template in the sidebar. You need to listen for the builder.template.load event and then add an url key with the preview URL as value to the template array.

<?php

namespace MyApp;

class TemplateListener
{
    public static function loadTemplateUrl(array $template): array
    {
        if (/* Check for your template */) {
            $template['url'] = // Generate a route matching this template;
        }

        return $template;
    }
}