Using Contao’s Template Override System to Customize Frontend Output Safely

Introduction

When a Contao site needs a unique layout for a specific page type, editing the core template directly can cause problems during updates and makes maintenance harder. Contao provides a built‑in override mechanism that lets you copy a core template into your theme’s /templates folder and modify it there. This keeps your changes safe from core upgrades and makes the customisation clear to other developers.

Locate the template

First identify the exact template file you want to change. For page layout the core file is:

system/modules/frontend/templates/fe_page.html5

Note the full path and the file name; you will recreate this structure inside your theme’s /templates directory.

Create the override

Inside your theme (usually under /files/your-theme/templates or the /templates folder at the project root) create the same sub‑directories as in the core:

/templates/frontend/modules/fe_page.html5

Copy the core fe_page.html5 into that location. Contao automatically uses the file found in /templates when rendering, leaving the core file untouched.

Worked example: adding a custom body class for the blog overview

1. Copy system/modules/frontend/templates/fe_page.html5 to /templates/frontend/modules/fe_page.html5.
2. Open the copied file and locate the opening <body> tag.
3. Change it to include a conditional class, for example:

   <body class="bodyClass ?> blog-overview">

4. Save the file.
5. Clear the production cache so Contao picks up the new template. You can do this via the Contao backend (System → Maintenance → Cache cleanup) or run the console command:

   vendor/bin/contao-console cache:clear

6. Reload a blog overview page in the browser and view the page source. You should see the blog-overview class present in the <body> tag.
7. Optionally enable debug mode (debug => true in /system/config/localconfig.php) and check the developer toolbar to confirm that the template being used is the one from /templates/frontend/modules/fe_page.html5.

Trade‑off / limitation

Template overrides are ideal for visual or structural changes (adding classes, moving blocks, altering markup). Any logic that resides in PHP template helpers or requires complex data processing is still executed from the core helpers; if you need to change that logic, consider creating a custom module, a hook, or a content element instead. Overrides do not replace the need to test that the modified markup works with existing CSS and JavaScript.

Actionable close

Start with a small, low‑risk template like fe_page.html5. Test the change in a development environment, verify the output, then promote the override to staging and production using your usual deployment process. Keep a brief README.md inside your /templates folder that lists each overridden file and its purpose; this helps future maintainers understand why the file exists and reduces the chance of accidental deletions during updates.