Configuring Contao Backend Layouts for Different Page Structures

Quick answer

In Contao 4.x you can change a page’s HTML structure without moving it in the page tree by defining a Backend Layout in config/layout.php and assigning its ID to the page. The front‑end controller reads that ID, loads the matching template, and places the page’s content elements into the slots declared in the template.

How it works – a worked example

1. Define the layouts

Create or edit config/layout.php and return an array that maps layout IDs to a human‑readable name and a frontend template:

<?php
return [
    'layouts' => [
        'default' => [
            'name'  => 'Default layout',
            'template' => 'fe_page_default',
        ],
        'sidebar' => [
            'name'  => 'Sidebar layout',
            'template' => 'fe_page_sidebar',
        ],
    ],
];

Each key (default, sidebar) is the layout ID you will later assign to a page.

2. Create the frontend templates

Place the template files in templates/. They must follow Contao’s naming convention (fe_page_*.html5) and contain slot markers where content elements will be injected.

templates/fe_page_default.html5

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>{{ page_title }}</title>
</head>
<body>
    <header>{{ header }}</header>
    <main>{{ main }}</main>
    <footer>{{ footer }}</footer>
</body>
</html>

templates/fe_page_sidebar.html5

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>{{ page_title }}</title>
</head>
<body>
    <header>{{ header }}</header>
    <div class="layout">
        <aside>{{ sidebar }}</aside>
        <section>{{ main }}</section>
    </div>
    <footer>{{ footer }}</footer>
</body>
</html>

The markers ({{ main }}, {{ sidebar }}, etc.) correspond to the default content element groups that Contao provides.

3. Assign a layout to a page

In the Contao backend:

1. Navigate to Site Structure and edit the page you want to change.
2. Open the Page Settings tab.
3. Find the Layout dropdown and select Sidebar layout (or the name you gave).
4. Save the page.

Alternatively, you can set the layout programmatically in a custom controller or module:

$this->Template->layout = 'sidebar'; // layout ID from config/layout.php

4. What happens under the hood

When a request arrives, Contao’s front‑end controller:

1. Loads the page record from the database.
2. Reads the layout field (the ID).
3. Looks up that ID in config/layout.php to get the template name.
4. Loads the corresponding template from templates/.
5. Renders the template, replacing each {{ slot }} marker with the HTML generated from the page’s content elements assigned to that slot.

Limits and common pitfalls

Fallback to the default layout

If the layout ID stored in a page does not exist in config/layout.php, Contao silently falls back to the default layout. This can produce an unexpected appearance and is often missed during debugging because no error is shown in the frontend.

Template location and naming

Custom templates must reside in the templates/ directory (or a subdirectory that is added to the template paths via config/config.php). Using a different folder or misspelling the template name results in a Template not found exception, which is logged in var/logs/.

Cache clearing

After adding, renaming, or removing a layout entry you must clear Contao’s internal cache; otherwise the old layout list is used and new IDs appear to be missing. Run:

vendor/bin/contao-console cache:clear

Multilingual considerations
Backend Layouts are stored per‑page, not per‑language. The same layout ID is used for all language variants of a page. If you need different structures per language, create separate pages or use a custom module that overrides the layout based on the current language.
Upgrade safety
Layout definitions survive Contao 4.x upgrades as long as the template files remain present. After a major upgrade, run the Install Tool → System → Maintenance → “Update database” to ensure any new layout‑related fields are migrated.

Verification steps

    
Add a new layout entry to config/layout.php (e.g., 'fullwidth' => ['name' => 'Full width', 'template' => 'fe_page_fullwidth']).
    
Clear the cache: vendor/bin/contao-console cache:clear.
    
Assign the new layout to a test page via the backend.
    
Open the page in a browser and view the page source.
    
Confirm that the HTML structure matches templates/fe_page_fullwidth.html5 (look for the slot markers you defined).
    
Check var/logs/ for any Template not found messages; none should appear if the template exists and the layout ID is correct.


Summary
Contao Backend Layouts let you switch a page’s HTML structure by defining a simple ID‑to‑template map in config/layout.php, assigning that ID to a page, and relying on Contao’s front‑end controller to inject content elements into the template’s slots. Remember to keep template files in the correct location, clear the cache after changes, and verify that the layout ID exists to avoid silent fallback to the default layout.