What are Sylius Template Events?

Think of Sylius Template Events as a kind of hook in your Twig template that you can extend without modifying the original twig template.

At first, I was not sure if I should like the Template Event implementation. It looked a bit weird to me at first. After using it for a while, I do like it as it is easy to use, and thanks to the integration in the Symfony Profiler, it is very easy to work.

How does it work?

First, we need to "execute" a Sylius Template Event call in our Twig template:

{{ sylius_template_event('sylius.test.event', _context) }}

Now, we can register blocks for the sylius.test.event. Based on their priority, these blocks are rendered one by one in the HTML code where the sylius_template_event() call was placed:

sylius_ui:
    events:
      sylius.test.event:
            blocks:
                block1:
                    template: '@MySyliusPlugin/Test/_block1.html.twig'
                    priority: 20
                block2:
                    template: '@MySyliusPlugin/Test/_block2.html.twig'
                    priority: 10

This configuration will first render block2 with its respective Twig template and then render block1 with the template defined for this block.

Rendering a simple, static Twig template is nice. Passing data to the Twig template to render would be even nicer. Thanks to the context configuration, that's possible:

sylius_ui:
    events:
      sylius.test.event:
            blocks:
                block2:
                    template: '@MySyliusPlugin/Test/_block2.html.twig'
                    priority: 10
                    context:
                        message: 'Hello!'

This configuration will create a Twig variable called "message" containing the string "Hello!". This is an acceptable solution for static data, but what about injecting dynamic data in the Twig template for a specific event?

That is what Context Providers are responsible for. You create a Context Provider class which implements the Sylius\Bundle\UiBundle\ContextProvider\ContextProviderInterface interface and tag it with sylius.ui.template_event.context_provider to let Sylius be aware of it:

<?php

declare(strict_types=1);

namespace App\ContextProvider;

use Sylius\Bundle\UiBundle\ContextProvider\ContextProviderInterface;
use Sylius\Bundle\UiBundle\Registry\TemplateBlock;

class TestContextProvider implements ContextProviderInterface
{

    public function provide(array $templateContext, TemplateBlock $templateBlock): array
    {
        $templateContext['custom_block2_var'] = 'Hello World!';
        return $templateContext;
    }

    public function supports(TemplateBlock $templateBlock): bool
    {
        return 'sylius.test.event' === $templateBlock->getEventName()
            && 'block2' === $templateBlock->getName();
    }
}

This code will create a Twig variable custom_block2_var containing the string "Hello World!". And as you can see, in the supports() method, the context provider implementation can decide for which event and/or block it should be executed.

In your service configuration tag the context provider:

services:
    # ...

    App\ContextProvider\TestContextProvider:
        tags:
            - { name: sylius.ui.template_event.context_provider }

There's a lot more to discover when working with Sylius Template Events. Check the Sylius documentation for more insights.