Go to page content

Template Best Practices and Pitfalls

Preferred solutions to common tasks and pitfalls you may encounter.

Why

Guidelines or best practices provide common ground which makes the work of various practitioners understandable by others.  Documenting common pitfalls is a useful mechanism for reinforcing the value of best practices in avoiding unnecessary complications.

Assumptions

It is assumed that anyone reading this is already familiar with template terminology and template authoring.

Best Practices

Variable Naming

Name your variables for what they represent.  If you are searching for articles make the search result variable article to make things clear.

In particular if you are iterating over a list or other iterable variable called images, then your item variable should be named image.  This makes generative templates easier to follow.

Pitfalls

Using 'm' as a template variable blocks model access

Avoid using the name m for a variable.  It has a special meaning in templates for accessing model modules like m_site and m_rsc as m.site and m.rsc.  Effectively all Erlang modules with names starting with m_ are made available in templates through the m variable.

It is particularly important since using m as a variable name will disable model module access for the entire scope within which that variable is defined.  This can lead to very confusing template errors.

Using 'id' as a template variable blocks access to the current page

Zotonic sets id based on the page being rendered.  It is also conventionally used by dispatch rules to supply the ID of the page to render.   Note, however, that there are legitmate cases for using id as a template variable. It is a good idea to reuse another template to render a section for one page and treating related content as the "current page" for that template by assigning id in a for loop or with context.  Using id otherwise will likely confuse other developers trying to read your templates.

This page is part of the Zotonic documentation, which is licensed under the Apache License 2.0.