What are Sylius Twig Hook Sections?

While digging deeper into Sylius templates, you may have found Twig Hooks named like this sylius_admin.customer.create.content.form.sections#left or this sylius_admin.customer.create.content.form.sections#right.

You might be wondering about the purpose of the #left and #right suffixes in these names.

The #left and #right parts are referred to as Twig Hook Sections in Sylius. Essentially, a section allows you to organize your Twig hooks in a logical way without introducing unnecessary complexity to your Twig Hook structure.

To break it down further, consider a scenario where you want to divide a form into two columns in your form template. You can define two sections, such as:

<div class="row">
    <div class="class="col-12 col-md-6">
        {% hook 'left' %}
    </div>
    <div class="class="col-12 col-md-6">
        {% hook 'right' %}
    </div>
</div>

To use these sections, you would need to update your Twig Hook structure by prefixing the hook names with the corresponding section names. Specifically:

• Hooks intended for the left section would require the sylius_admin.customer.create.content.form.left prefix
• Hooks intended for the right section would require the sylius_admin.customer.create.content.form.right prefix

Although the prefixing approach is technically feasible, it can become cumbersome when reorganizing Twig Hooks and their templates. Renaming hooks to match a new structure can lead to unnecessary complexity and accidental overwriting of templates.

Moreover, the placement of Hookables on the left or right side of the form shouldn't be a concern in your Twig Hook structure. This is where Sections provide a convenient solution. By configuring hooks to use sylius_admin.customer.create.content.form.sections#left or sylius_admin.customer.create.content.form.sections#right, subsequent hooks can simply use the base sylius_admin.customer.create.content.form.sections hook name, without considering the final section placement.

As a result, you can freely assign a hook like sylius_admin.customer.create.content.form.sections.address to either the left or right section of the form, all without needing to modify its configuration. This added flexibility simplifies the management and maintenance of your Twig Hooks.

By default, Sections are denoted by a # character, but you can customize this separator using the sylius_twig_hooks.hook_name_section_separator configuration option. Behind the scenes, the Sylius\TwigHooks\Hook\Normalizer\Prefix\RemoveSectionPartNormalizer class handles the normalization of hook names.

If you require a custom normalization logic, you can create a custom implementation by developing a class that implements the Sylius\TwigHooks\Hook\Normalizer\Prefix\RemoveSectionPartNormalizerInterface interface. This allows for flexible and tailored normalization of hook names to suit your specific needs.

Initially, the concept may seem unfamiliar and even confusing, making it challenging to follow. However, as you become more accustomed to it, the logic and benefits become clearer, ultimately helping you streamline and simplify your Twig Hook structure.