Debugging templates #

Part 2, chapter 15. Template problems fall into three groups: the wrong template is used, a variable is not what you think, or the template has an error. This chapter gives the tool for each. Turn on debug output first (Debug output and logs for developers).

Which template is used? #

Development only: the comments go into every output, including mails, JSON, XML and RSS. Never leave them on in production.

When an override does not apply, the used-templates table tells you what the kernel requested (Source) and what it chose; compare that with your override.ini block (Template overrides: the basics).

What is in this variable? #

{$node|attribute( 'show', 1 )}

prints a table of the variable's attributes, one level deep (2 for two levels). On a node it lists name, node_id, object, data_map, url_alias and the rest, which is how you find the name of the attribute you need. Remove it before you commit: it is for your eyes only. Note that it reads every attribute, including expensive ones.

For values you do not want in the page, write them to the debug output:

{debug-log var=$node.name msg='the node name'}
{debug-log msg='reached the teaser branch'}

The engine prints Debug: (the node name) followed by the value in the debug report.

How long does it take? #

{debug-timing-point id='menu'}
    ... the expensive part ...
{/debug-timing-point}

adds a timing point around a part of the template; debug-accumulator sums repeated blocks. The timings appear in the debug output's timing table. Combine with [DatabaseSettings] SQLOutput=enabled to see which fetch is slow.

The engine's messages #

Each message names the template file and the line and column, for example full.tpl:12[5].

Stale output #

If your change does not show up:

1. Is the template compiled from an old version? Clear the template cache: php bin/php/ezcache.php --clear-tag=template.
2. Is the page in the view cache? Clear it: php bin/php/ezcache.php --clear-tag=content.
3. Is it a new file? Clear the template override cache: --clear-id=template-override.
4. Is the part inside a {cache-block}? Clear --clear-id=template-block.
5. Velocity keeps a response cache: ./console exp:velocity cache clear --apply.

While you work, TemplateCompile=disabled avoids step 1 entirely.

A routine for a broken page #

1. Read the errors in the debug output; the first one is usually the cause.
2. Find the template with path comments.
3. Dump the variables you depend on with attribute( 'show' ).
4. Cut the template down until the error disappears; the last thing you removed is the problem.
5. Undo the debug lines, clear the caches, check again.

eZpedia's "Learning: Template Debugging" describes the same tools from the earlier years.

Related pages #

• Previous: The template operators builders use most
• Next: Caching and templates
• Template path comments
• The Exp Debug bar
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.