Decoupling Design from Content in Contao: Mastering Custom Page Templates with Twig

Problem: Mixing Design and Content in Contao

In many Contao sites the same layout file is used for every page type. When a designer wants to change the header of a landing page, they end up editing the global template, which can break the shop or blog pages. The result is a tight coupling between design and content structure, making maintenance painful.

Thesis: Use Twig Page Templates to Decouple Layout from Content

Contao 5 ships with a Twig‑based template engine that supports inheritance, blocks, and a fallback mechanism. By creating page‑specific templates and assigning them through the Page settings, designers can change the visual structure without touching the content or core files.

1. Create a Page‑Specific Twig Template

All custom templates live in templates/ (or templates/page/ for organization). The file name must follow Contao’s naming convention: page--{slug}.html.twig (e.g., page--landing.html.twig). Inside the file you can extend the default layout and override blocks.

{# templates/page--landing.html.twig #}
{# Extends the global layout #}
{% extends 'page--default.html.twig' %}

{# Override the header block #}
{% block header %}
  
    {{ page.title }}
  
{% endblock %}

{# Add a new content zone below the article #}
{% block article %}
  {{ parent() }}
  
    {{ article.promo }}
  
{% endblock %}

Key points:

• Extends pulls in the global layout defined by Contao.
• Blocks like header and article are defined in the base template; overriding them replaces that section.
• Calling {{ parent() }} keeps the original block content and appends new markup.

2. Assign the Template in the Contao Backend

Navigate to Structure → Pages, edit the target page, and locate the Template field. Select page--landing from the dropdown. No PHP changes are required.

Permissions: You need the Page > Edit role to change the template. Run the command contao:cache:clear if the new layout doesn’t appear immediately.

3. Verify the Rendered HTML

Open the page in a browser, right‑click, "View Page Source". You should see the new <header> and <section class="promo" elements. If the default layout appears, check:

• File name matches the pattern exactly.
• No syntax errors in the Twig file (Contao logs them).
• Cache cleared after the change.

4. Leverage Block Overrides for Granular Control

Instead of recreating the whole page, you can create a slim template that only overrides specific blocks. For example, to change only the footer on a page type:

{# templates/page--footer-only.html.twig #}
{% extends 'page--default.html.twig' %}
{% block footer %}
  
    © {{ 'now' | date('Y') }} – Custom Footer
  
{% endblock %}

This keeps the rest of the layout intact and reduces duplication.

Trade‑Off: Complexity vs. Flexibility

While block overrides give fine‑grained control, they can make debugging harder. A missing block name or a typo in the template file will silently fall back to the parent, leaving the page looking unchanged. Junior developers may struggle to trace which template file is actually rendering a section. To mitigate this:

• Use descriptive file names and comments.
• Enable Twig debugging (debug: true in config/packages/twig.yaml) to see which templates are loaded.
• Keep a design‑to‑template mapping table in documentation.

Limitations

• Contao 5 only supports Twig for page templates; older projects using Smarty must either upgrade or maintain dual systems, which can cause configuration conflicts.
• Direct edits to core templates (e.g., templates/page--default.html.twig) prevent clean updates; always copy core files into your project’s templates/ folder before modifying.
• Complex inheritance chains (e.g., page → article → content element) may lead to unexpected overrides if block names collide.

Actionable Closing

Follow these steps to decouple design from content in your Contao 5 site:

1. Create a new .html.twig file in templates/ following the page--{slug}.html.twig convention.
2. Extend the global layout and override only the blocks you need.
3. Assign the template via the Page settings in the backend.
4. Clear the cache and verify the output in the browser.
5. Document the mapping between pages and templates for future maintenance.

By keeping design logic in Twig templates and content in Contao’s article system, you gain flexibility, easier updates, and a cleaner separation of concerns.