Twig templates in the WXP plugins

Twig is a template language for PHP. A Twig template looks like HTML, with a few extra tags to print values and to repeat or hide parts. All four WXP plugins use it to build the HTML of their menus, opening hours, events and booking forms. Because the layout is in a template and not in PHP code, you can change how a plugin looks without touching the plugin.

The basics #

A template is a text file that ends with .html.twig. Three kinds of tags are enough for most changes:

• {{ ... }} prints a value, for example {{ item.name }}.
• {% ... %} does something, such as a loop or a condition.
• {# ... #} is a comment that is not printed.

{# Print the items of a category #}
<ul>
{% for item in category.items %}
	<li>
		{{ item.name }}
		{% if item.price %}<span class="price">{{ item.price }}</span>{% endif %}
	</li>
{% endfor %}
</ul>

The names you can use, such as item or category in the example above, depend on the plugin and on the template. The data a template receives is called its context. You can add your own values to the context with the ..._template_context filter of each plugin (see the guide Filter- and action hooks of that plugin).

How the plugins use Twig #

• One template per layout. A style such as cards, compact or elegant is one template file. The template setting of a shortcode, block or widget chooses the file.
• Partials. Files that start with an underscore, such as _item.html.twig or _base.html.twig, are pieces that other templates include. They are not layouts to choose.
• Escaping. Every value is escaped as HTML automatically, so text with a < or a quote cannot break the page. You only need to think about this when you print HTML on purpose.
• Missing values. A value that does not exist prints nothing, and it does not cause an error.
• Errors. When a template has a mistake, only that block is affected and the rest of the page keeps working. Users who can edit the theme see a short error message in its place; other visitors see nothing.
• No conflicts. Each plugin carries its own copy of Twig, with a private name, so it does not clash with another plugin or theme that also uses Twig.

Where the plugins look for templates #

A plugin looks for a template in three places, in this order. The first file that is found is used:

• the folder of the plugin in your child theme,
• the folder of the plugin in your parent theme,
• the templates folder inside the plugin.

So to change a layout, copy the file from the templates folder of the plugin to the folder above in your child theme and edit the copy. Never edit the files inside the plugin: an update would replace them. You only have to copy the files you want to change; for all the others the plugin uses its own.

Make your own layout #

• Copy a template that is close to what you want, for example cards.html.twig, into the folder of the plugin in your child theme.
• Give it a new name, for example my-menu.html.twig.
• Use the name without .html.twig in the template parameter of the shortcode: [wxp_menu template="my-menu"].

If you copy a file with the same name as a plugin file, yours replaces it for the whole site. A name that does not exist falls back to the default template of that plugin.

More information #

• Each plugin has a guide Filter- and action hooks with the filters for template folders, template data and the Twig cache.
• Each plugin has a guide with the shortcodes and their template parameter.
• The Twig language itself is described on the website of Twig (twig.symfony.com), in the chapter Twig for Template Designers.