Extending Contao Pages with Custom Fields – A Practical Guide

Problem: Need Extra Page Metadata Without Core Changes

When building a website with Contao, you often need to store small bits of information that aren’t part of the core data model – for example a “Featured” flag for pages or a custom SEO description. The traditional way would be to create a new database table and write PHP classes to handle it. This adds maintenance overhead and can break when Contao upgrades.

Contao offers a built‑in feature called Custom Fields that lets administrators add arbitrary fields to existing data containers (e.g., tl_page, tl_article, tl_content) without touching the core schema. The data is stored in the same table as the container, so no migrations are required.

How Custom Fields Work

Custom Fields are created in the backend under System > Custom Fields. Each field has:

• Name – the identifier used in code (e.g., featured).
• Label – the admin label.
• Input type – text, checkbox, number, etc.
• Default value – optional.

After creation, the field must be added to a data container. For pages, go to System > Data Containers > tl_page, open the Custom fields tab, and select the newly created field. The container will now expose the field to the page editor.

Internally, Contao adds a column named after the field key (e.g., featured) to the tl_page table. The column is of type text for most input types; checkboxes are stored as "1" or "0". The column is not indexed by default, which is fine for simple flags but can affect heavy filtering.

Concrete Example: Adding a "Featured" Checkbox to Pages

1. Create the field:

   • Backend: System > Custom Fields → Add new field.
   • Name: featured
   • Label: Featured
   • Input type: checkbox
   • Save.

2. Attach to pages:

   • Backend: System > Data Containers > tl_page.
   • Open Custom fields tab.
   • Check featured and save.

3. Verify persistence:

   • Open a page in the editor, tick the Featured checkbox, and save.
   • Run a database query: SELECT featured FROM tl_page WHERE id=123; (replace 123 with your page ID). The value should be "1".

4. Render in Twig:

   • Open the page template (e.g., page.html.twig). Add:

     {% if page.featured %}
       Featured Page
     {% endif %}

   • Clear the cache and view the page. The banner should appear only on pages where the checkbox was set.

Trade‑Offs and Limitations

• Performance: Custom fields are stored in a single text column per field. When you have many fields or need to filter pages by a field value, the lack of indexing can lead to slow queries. For heavy filtering, consider a dedicated table.
• Data Integrity: Contao does not enforce data types beyond the input widget. A number field can still contain arbitrary text if entered manually.
• Version Differences: The API for accessing custom fields in Twig changed from Contao 4 to 5. In Contao 4 you might need to use {{ page.custom_featured }}, while in Contao 5 the plain {{ page.featured }} works. Always test on your specific version.
• Backup Strategy: Since custom fields live in the same table, a full database backup will include them automatically. However, if you rely on them for critical business logic, document the field names in your architecture notes.

Actionable Checklist

1. Verify that System > Custom Fields is available in your Contao installation.
2. Create the required fields and attach them to the relevant data containers.
3. Test persistence by saving a record and checking the database.
4. Render the field in a Twig template and confirm the output.
5. Monitor query performance if you plan to use the field in list views or search.
6. Document field names and intended usage for future developers.

By using Custom Fields, you can extend Contao’s data model quickly and safely without custom migrations. Just remember that heavy relational logic is better served by dedicated tables.