Skip to the content
Documentation
Version 6.x Supported

Debugging templates

Written by Graham Brookins, Updated by Graham Brookins Maintainers: Graham Brookins
No ratings yet

When a page looks wrong, three questions come up: which template printed this, why that template and not mine, and what went wrong inside it. Exponential answers them with the Exp Debug bar, template path comments and a syntax checker. Switch them on for yourself only, never for every visitor of a live site: debug output shows paths, settings and queries.

Switching on debug output for yourself

In settings/​override/​site.​ini.​append.​php (or the file of one siteaccess), show the debug output only to your address or your user:

[DebugSettings]
DebugOutput=enabled
DebugByIP=enabled
DebugIPList[]=203.0.113.10
# or, for signed-in users by user id:
#DebugByUser=enabled
#DebugUserIDList[]=14

Clear the INI cache (php bin/php/ezcache.php --clear-tag=ini) and reload a page. The debug output appears where the pagelayout has <!--DEBUG_​REPORT-->, as the Exp Debug bar pinned to the bottom of the window.

The Exp Debug bar

The bar shows the page time, the number of SQL queries, the memory, the content view cache (hit or newly generated), the cache blocks and the number of compiled templates. Each value opens its tab. For templates, three tabs matter:

  • Rendering, sub-tab Template tree: every template the request rendered, with its time. An override shows as the requested template, an arrow and the file that answered, for example node/view/full.tpl → .​.​.​/​override/​templates/​node/​view/​full/​full_​ng_​frontpage.​tpl. The other sub-tabs show the content view cache, the cache blocks and the template settings in effect.
  • Templates: the list of used templates, each with a link that opens it in the Template Editor. It is recorded when [TemplateSettings] ShowUsedTemplates=enabled; the tab says so when it is off. [DebugSettings] UsedTemplateEditUrl can point the edit links at the administration siteaccess.
  • Messages: errors, warnings and notices, including those of the template system, which name the template, the line and the column, such as "Variable 'items' doesn't exist, cannot set" or an operator parameter without a default value.
The Rendering tab of the Exp Debug bar with the template tree of a page

The template tree of a page: node/view/full.tpl answered by an override template, the pagelayout and the debug toolbar, each with its time.

The Settings tab switches the debug settings, among them ShowUsedTemplates and ShowTemplatePathComments, per scope from the browser, and the Cache tab clears caches. Everything about the bar: The Exp Debug bar.

Template path comments

With [TemplateSettings] ShowTemplatePathComments=enabled, every template's output is wrapped in HTML comments that name its file. View the page source and search for START:

<!-- START design/example/templates/pagelayout/footer.tpl -->
...
<!-- STOP design/example/templates/pagelayout/footer.tpl -->
<!-- START extension/mytheme/design/example/override/templates/full/article.tpl (node/view/full.tpl) -->

A name in brackets is the Source of the override rule that chose the file. The comments are left out where they would break the output (inside a tag, a script, a style, and in output that is not HTML), but they add markup to every page: use them on a development siteaccess only, and switch them off again. Clear the template cache after switching (--clear-tag=template). See Template path comments.

Checking the syntax

exp:template:check checks templates of all three engines without rendering them and without writing anything:

./console exp:template:check design/example/override/templates/full/article.tpl
./console exp:template:check --design=example --level=strict
./console exp:template:check --siteaccess=eng --format=json --output=var/tmp/check.json

The levels are syntax, compile (the default: the template is also compiled and the compiled PHP checked) and strict (also the security policy, the includes and unknown operators). The command ends with PASS or FAIL and an exit code, so it fits a deployment pipeline. The older php bin/​php/​eztemplatecheck.​php checks .tpl files. See Checking template syntax.

Looking inside a template

  • {$variable|attribute( 'show', 1 )} and {$variable|dump} print what a variable holds; see Array and object inspection.
  • {debug-log var=$items msg='items of the menu'} writes a value to the debug output instead of the page, and {debug-timing-point id='menu'}.​.​.​{/​debug-timing-point} measures the time of a part in the Timing tab.

A change that does not show

Symptom Look at
A new override has no effect The rule's Source, MatchFile and conditions, its place in the order (Template Editor), and the caches: clear the tags ini and template.
"Custom match file: path ... not found in any resource" MatchFile is relative to override/templates/ of a design in the chain; the message lists every path that was tried.
The node shows old content The content view cache: clear the cache with the id content. A part that stays old is in a cache block: clear the id template-block.
Your template is used on one siteaccess but not another The design chain of each siteaccess (see Designs and design order) and where the rule is defined.

More cases, with the messages and their causes: Errors and debugging; for Twig templates: Debugging Twig templates.

Contributors

Comments

Add a comment

Comments are read by a moderator before they appear.