The template engine and the design chain #

This page is for engineers who need to understand how a page is rendered, how a template is chosen, and what can go wrong there. The template language is Exponential's own; it is not Twig or Smarty, although its brace syntax looks similar. The authoritative rules are in Kernel architecture.

Contents #

1. The engine
2. Data access from templates
3. The design chain
4. Overrides
5. Caching inside templates
6. Debugging rendering
7. Review rules

The engine #

eZTemplate (lib/eztemplate/classes/eztemplate.php) compiles .tpl files to PHP and runs the compiled files (site.ini [TemplateSettings] TemplateCompile=enabled shipped). Operators (|wash, ezurl, i18n) and functions ({def}, {foreach}, {include}, {cache-block}) are PHP classes registered in eztemplateautoload.php files as entries of $eZTemplateOperatorArray and $eZTemplateFunctionArray. The engine loads them from [TemplateSettings] AutoloadPathList[] and from the extensions listed in ExtensionAutoloadPath[].

The language reference is in the help: Template language and Template operators.

Data access from templates #

Templates do not query the database: the language has no SQL construct. Data comes from:

• the view's variables, set by the module view before rendering;
• fetch functions: fetch( 'content', 'list', hash( ... ) ), mapped in kernel/<module>/function_definition.php and executed by eZFunctionHandler. A fetch that returns content applies the user's permissions;
• template operators, which are PHP and can do anything, so they are reviewed like views.

The design chain #

A design is a directory of templates, stylesheets and images. Designs are stacked so a site contains only what differs from the base: site.ini [DesignSettings] SiteDesign, AdditionalSiteDesignList[] and StandardDesign (standard). Extensions add design directories through design.ini [ExtensionSettings] DesignExtensions[]. eZTemplateDesignResource builds the chain: extension design directories first, then design/<design>/.

Overrides #

override.ini blocks choose another template for a view when conditions match: Source, MatchFile, Subdir and Match[...] (for example the class identifier or the node). Since July 2026 overrides are ordered by Priority, lower first (Template override ordering). The administration page Design > Templates writes only settings/siteaccess/<sa>/override.ini.append.php.

A site or extension overrides a kernel template through override.ini or its own design directory; it must not edit files in design/standard/ or design/admin*/.

Caching inside templates #

See Cache invalidation and clearing.

Debugging rendering #

• Template path comments wrap each rendered template in HTML comments naming its file (Template path comments).
• The debug bar lists the templates used by a page (The Exp Debug bar).
• ./console exp:eztemplatecheck (bin/php/eztemplatecheck.php) checks templates for syntax errors.

Review rules #

• Every variable from content or input is printed with |wash, or through an operator that escapes.
• An operator that builds HTML in PHP escapes it there.
• No SQL in templates, and no raw database handle passed to one.
• In the administration designs: no <style> block or style="" attribute, and no inline script code; this is checked by tests in tests/tests/design/ (Styling the administration).
• Scripts that must stay inline carry the Content Security Policy nonce: <script nonce="{csp_nonce()}">.

Related pages #

• Templates and design
• View results and the pagelayout
• The design chain
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.