Template resolution: designs and overrides #

This page is for developers who know Twig's template paths and namespaces, Laravel's view paths and vendor overrides, or Django's template loaders. Exponential resolves a template name such as design:node/view/full.tpl in two steps: first through a design chain (a stack of directories), then through override rules that can swap the file depending on what is being rendered.

Contents #

1. The design chain
2. Override rules
3. Compared with other frameworks
4. Where your templates go
5. Finding out which file rendered

The design chain #

A design is a directory of templates, stylesheets and images. A siteaccess names its designs in site.ini [DesignSettings]: SiteDesign, AdditionalSiteDesignList[] and StandardDesign (standard). Extensions add their design directories with design.ini [ExtensionSettings] DesignExtensions[]. eZTemplateDesignResource (kernel/common/eztemplatedesignresource.php) builds the chain, extension design directories first, then design/<design>/; the first directory that has the file wins (Design and override system, Designs and the fallback chain).

Override rules #

override.ini (of the siteaccess and of every extension) has one group per rule:

[node/view/full#ng_article]
Source=node/view/full.tpl
MatchFile=node/view/full/full_ng_article.tpl
Subdir=templates
Match[class_identifier]=ng_article
Priority=1

When node/view/full.tpl is fetched for an object of the class ng_article, the file override/templates/node/view/full/full_ng_article.tpl of the design chain is used instead. The first rule whose conditions all match wins; rules are ordered by Priority (lower first) when one is given (Resources and overrides, Template override ordering).

Match keys are set by whoever renders: content/view sets the node's keys (class_identifier, node, parent_node, section, url_alias, depth, viewmode, state and more); node_view_gui sets them per item, so a list can render each child with its class's line template. A view of your own can add keys with eZTemplateDesignResource::instance()->setKeys().

Compared with other frameworks #

Where your templates go #

Never edit design/standard/ or the kernel's admin designs: override instead, so updates do not overwrite you.

Finding out which file rendered #

• Template path comments print the file name around each template's output (Template path comments).
• The debug bar lists the templates used on a page (Exp debug bar).
• After adding a new template file, clear the template-override cache; otherwise the old resolution stays cached (Template caches).

Related pages #

• The view layer
• Template overrides
• Templates and design guide
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.