Twig templates and the design engine
This page is for developers and theme builders who render a DXP site. The DXP renders with Twig, and the package
ibexa/design-engine adds designs and themes with a fallback chain, much like the design chain of Exponential 6.
The configuration keys below were read from the package's Configuration class in an installed project.
Contents
- Designs and themes
- The @ibexadesign namespace
- Where theme templates live
- Configuration keys
- Giving a siteaccess its design
- Debugging which template was used
Designs and themes
The package's own description: "A design is a labeled collection of themes. Theme order defines the fallback
order." A design my_design with themes [my_theme, standard] looks for a template in my_theme first and falls
back to standard. The standard design is always defined; ibexa/standard-design provides its templates
(The standard design and your theme).
The @ibexadesign namespace
Refer to theme templates through the @ibexadesign Twig namespace, never by a theme's path:
extends '@ibexadesign/pagelayout.html.twig'
include '@ibexadesign/parts/header.html.twig' The engine resolves the name through the current siteaccess's design and its theme order. The skeleton README
mentions an @ezdesign namespace; on Platform v5 the installed engine registers @ibexadesign.
Where theme templates live
By convention, each theme is a directory under templates/themes/:
templates/themes/
my_theme/
pagelayout.html.twig
full/article.html.twig
line/article.html.twigBundles can ship themes too, in their Resources/views/themes/<theme>/.
Configuration keys
Under ibexa_design_engine in config/packages/:
| Key | Meaning |
|---|---|
design_list | Designs and their themes in fallback order, for example my_design: [my_theme, standard] |
templates_theme_paths | Extra template directories per theme ("Each path MUST exist") |
templates_override_paths | Directories checked before every theme directory |
disable_assets_pre_resolution | When true, asset paths are not pre-resolved at compile time (defaults to the debug setting) |
ibexa_design_engine:
design_list:
my_design: [my_theme, standard]Giving a siteaccess its design
ibexa:
system:
site_group:
design: my_designThe administration siteaccesses use their own design; leave it as installed.
Debugging which template was used
- In
APP_ENV=dev, the Symfony web profiler lists the rendered templates, and the design engine adds a data collector to it. php bin/console debug:twiglists Twig functions, filters and namespaces.php bin/console exponential:debug:config-resolver design --siteaccess=siteshows the design a siteaccess uses.
Related pages
- The standard design and your theme
- Twig functions you use daily
- The design chain in Exponential 6, for comparison
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.