Using Twig in module templates

Just by following the directory structure conventions, the OXID support for the Twig template engine allows you to

register custom (original) module templates

extend existing templates

So, having directory structure conventions means you don’t have to register Twig templates or template extensions in the in metadata.php file explicitly.

Registering a new module’s template

To register new Twig templates, simply put them into the corresponding directory structure inside your module:

└── module-1
    └── views
        └── twig
            ├── module_1_own_template.html.twig
            └── page
                └── module_1_own_template.html.twig

After module activation, the templates will be automatically registered with the namespace matching the module’s ID:

@<module-id>/modules_own_template.html.twig
@<module-id>/page/modules_own_template.html.twig

Attention

Terminology

The expression extensions, when used in the following directory structure, is reserved for template extensions (see Extending existing templates).

└── module-1
        └── views
            └── twig
                └── extensions
                    └── // <- special location for templates that extend other templates

Do not use it to register original (non-extending) module templates.

Extending existing templates

In addition to the out-of-box Twig functionality for template inheritance and reuse (see Twig documentation for extends tag), OXID eSales supports multiple inheritance for Twig templates.

This allows you to have more than one {% extends %} tag called per rendering.

Multiple inheritance is an advanced feature that you can use to combine modifications added to a certain template from multiple modules into an “inheritance chain”.

Attention

No dynamic and conditional inheritance

Multiple inheritance with dynamic or conditional inheritance is not implemented.

Do not use these Twig features in OXID eShop templates.

Depending on the type of the original template, a module template extension can be of one of the following types:

module extension for OXID eShop templates

module extension of OXID module templates

Identify the template extension type easily by examining its directory structure (see the examples under Module extensions for OXID eShop templates and Module extensions for OXID module templates).

Module extensions for OXID eShop templates

This type of template extensions is located in the themes/ sub folder of the extensions/ directory:

├── module-1
   └── views
       └── twig
           ├── extensions
              └── themes
                  ├── default
                     └── shop-template.html.twig //put theme-unaware templates here
                  └── some-twig-theme
                      └── shop-template.html.twig //put theme-specific templates here

In the example above, the result of rendering shop-template.html.twig depends on the active theme’s ID:

If some-twig-theme theme is active, the extensions/themes/some-twig-theme/shop-template.html.twig template is used in the template chain.
If the some-other-twig-theme theme is active, the extensions/themes/default/shop-template.html.twig template is used in the template chain.

Attention

The following paths are reserved:

extensions/themes

extensions/themes/default

They have a special meaning inside of OXID eShop application.

To avoid running into problems with template inheritance, make sure not to use default as your theme ID.

Note

Inheritance for admin templates is similar to the theme-specific inheritance, because admin is a theme as well.

When creating admin template extensions (twig_admin, for example), just use a corresponding ID.

Module extensions for OXID module templates

When your module needs to extend a template that originates in another module, place the extension template in the modules/ sub folder of the extensions/ folder:

├── module-1 // module-1 file structure
   └── views
       └── twig
           ├── module_1_template.html.twig // original module-1 template
           └── page
               └── module_1_template.html.twig // original module-1 template


└── module-2  // module-2 file structure
    └── views
        └── twig
            └── extensions
                └── modules
                    └── module-1
                        ├── module_1_template.html.twig // extension of module-1 template
                        └── page
                            └── module_1_template.html.twig // extension of module-1 template

Note

For shop templates, we can make theme-specific template extensions (similar to Module extensions for OXID eShop templates), but for module templates it’s not supported.

Fine-tuning the template inheritance process

Controlling a template rendering engine that utilizes multiple inheritance can be a daunting task by itself.

The situation might get even more complicated if you face the necessity to control the order in which each module template joins the inheritance chain.

By default, the module template loading order (template chain) depends on the order of module installation.

If the inheritance chain is not rendered as expected adjust it. To do so, in your shop configuration file (var/configuration/shops/1.yaml), use the templateExtensions key.

Example

modules: {  }
moduleChains:
    classExtensions: {  }
    templateExtensions: //configuration key
        'page/some-template.html.twig': //name of the extended template
        - module-id-3 //highest-priority module ID (the template will be loaded last in the chain)
        - module-id-2
        - module-id-4 //lowest-priority module ID (the template will be loaded earlier in the chain)

In our example,

module-id-3 is the highest-priority module ID (the template will be loaded last in the chain)
module-id-4 is the lowest-priority module ID (the template will be loaded earlier in the chain)

So, in our example, having an OXID eShop application with 4 modules active and extending the same eShop template page/some-template.html.twig results in the following template chain:

CHAIN START
shop-template
module-1-template
module-4-template
module-2-template
module-3-template*
CHAIN END

Templates for modules whose IDs are not specified in the templateExtensions (module-1-template, in our example) will be put to the chain start.
They have the lowest priority.

The template that closes the inheritance chain has highest priority because it can go as far as to stop the contents of “parent” templates from being displayed.