Contao Theme Framework

A new standardized and database-less way to build frontend themes in Contao.

Features

• Automatically registers themes and layouts defined via a theme.yml manifest file: Almost no database to maintain - easier deployment!
• Disables all redundant fields from the tl_theme and tl_layout palettes - you define all settings via the manifest file (except for the module includes).
• Registers a themes' public folder as Asset package, supports file versioning via a manifest.json!
• Out-of-the-box support for Symfony Encore and its entrypoints.json!

This extension is stable and supported from Contao >=4.13 and will be integrated into the Contao Core at some time eventually, see contao/contao#2781.

Installation

composer require richardhj/contao-theme-framework

Quickstart

1. Create a theme folder

Create a folder for your theme under /themes with the following structure:

|- files
|- themes
 |- my_theme
  |- assets           (Optional folder, we recommend placing your CSS/JS files there)
  |- public           (Distribution folder with your CSS/JS files, will be symlinked into the web/ folder)
  |- templates        (Overridden Contao templates, for frontend modules, etc.pp.)
  |- theme.[yml|yaml] (Theme manifest)

If you do not use a preprocessor, you place all your CSS/JS files into the public folder.

Alternatively, copy the boilerplate folder:

cp -r vendor/richardhj/contao-theme-framework/skeleton/theme themes/[my_theme]

This command will install an opinionated starter theme pack.

ℹ️ Except for the directory structure that is predetermined, you are free in the technology you use (Encore, Webpack, Gulp, SASS, plain CSS, …).

2. Write the theme manifest

Write your theme manifest:

# themes/[my_theme]/theme.yml

theme:
  name: My cool theme

layouts:
  # "_default" is a special key.
  # Will create a "default" layout, and all other layouts will merge these settings.
  # Using this key is optional.
  # The key:value structure maps the tl_layout structure.
  _default:
    name: Default layout
    template: fe_page
    rows: 3rw

  other_layout:
    name: Other layout
    template: fe_page_2

image_sizes:
  # See https://docs.contao.org/dev/framework/image-processing/image-sizes/#size-configuration

In a next version, the XML format for theme manifests will be available.

3. Install themes

To install your new theme, run the migrate command:

./vendor/bin/contao-console contao:migrate -n

ℹ️ The themes will only be updated on the migrate command when making changes on the theme manifest. It is best to add the migrate command to your deployment script (which is a good idea anyway).

To create the symlink for the public folder, run the following command (this only needs to be done once, and this is automatically done on composer install, so you usually should not be required to do this):

./vendor/bin/contao-console contao:symlinks

4. Create frontend modules and assign them to layouts

Login to the Contao backend, where you will find the new theme. Create frontend modules (if necessary) and assign them to the layouts accordingly.

Usage

The following chapters describe how you write frontend code, depending on your preferred toolchain:

Vanilla (No toolchain)

Each theme's public folder (i.e., /themes/[my_theme]/public) is registered as assets.packages component. Learn more about the Asset component.

You can reference any file inside the theme's public folder with the {{asset}} insert tag or corresponding twig function. The theme name equals the folder name.

When you use a manifest.json inside the public folder, it will be handled by Symfony's Asset component. Make sure to use setManifestKeyPrefix('') in your webpack.config.js file then.

Example:

<!-- HTML5 -->
{{asset::images/logo.svg::my_theme}}

<!-- Twig -->
{{ asset('images/logo.svg', 'my_theme') }}

ℹ️ The simplest way to include a CSS file to the page is to modify the fe_page.html5 template and include the {{asset::css/custom.css::my_theme}} insert tag.

Encore

Read the documentation for Encore here: https://symfony.com/doc/current/frontend/encore/index.html

First, install Webpack Encore:

composer require symfony/webpack-encore-bundle

Make sure to configure Encore properly by placing the webpack.config.js file inside your themes/[my_theme]/assets folder.

Then you will be able to inject your CSS and JS files to the page template:

{{ theme_link_tags('app') }}
{{ theme_script_tags('app') }}

ℹ️ The name "app" matches the name of the entry defined in the webpack.config.js. You can have multiple entrypoints per theme.

Finally, some tips for working with Encore and bundlers:

Git-Ignore the public folder

The distributed theme files inside the public folder usually are versioned and contain duplicated information so that you do not want to check in those files to version control. Instead, you want to build the theme (yarn run prod) before deploying.

ℹ️ The .gitignore file of the skeleton theme may become handy.

Use yarn workspaces to manage multiple themes

You can make use of yarn workspaces. This will allow you to run the build command once when having multiple themes in use:

// /package.json

{
  "private": true,
  "workspaces": ["themes/*/assets"],
  "scripts": {
    "prod": "yarn workspaces run prod"
  }
}

You then will be able to run yarn run prod from the root directory.

Asset Mapper

Read the documentation for the Asset Mapper here: https://symfony.com/doc/current/frontend/asset_mapper.html

(tba)

FAQ

Wait – How do I build a website if all fields are disabled from tl_layout?

Good question!

The layouts in Contao are highly redundant. You don't need to configure a viewport-attribute, body-class, etc. via the layout. Instead, just put those changes directly into your fe_page template.

Instead of selecting CSS files and JS files via the layout (which is limited to files within /files), directly include your files via the {{asset}} insert tag or twig function (or via Encore, see below). Don't use the "custom <head>" or "custom <script>" settings in your layout. It's hard to maintain and keep track of. Instead, put those things directly into the template.

Considering these matters of maintainability, it's easier not to configure any settings in the layout. Assigning the modules to the layout sections is all you do in the layouts.

If your layouts use rows and cols, set the corresponding config in the theme.yml. For instance, rows: 3rw enables the header and footer section.

Using Twig templates (optional):

In case your header and footer sections only contain static content, you do not have to configure those sections in your layout. Just include those sections via Twig includes. For navigation menus, you can use a Knp Menu (see below). For a user menu, you can use the {{ app.user }} variable. You will be surprised how not using modules for the layout significantly enhances maintainability.

Custom layout sections

Custom layout areas in the layout work as follows.

First, define the sections in the layout:

# themes/[my_theme]/theme.yml
layouts:
  _default:
    name: Default layout
    sections:
      - title: Bereich A
        id: custom1
        position: manual
        template: block_section
      - title: Bereich B
        id: custom2
        position: manual
        template: block_section

Then, add the section(s) to the page layout (i.e., fe_page):

{# themes/my_theme/fe_page.html.twig #}

<div>
  {{ section.invoke('custom1') }}
</div>
<div>
  {{ section.invoke('custom2') }}
</div>

<!-- themes/my_theme/fe_page.html5 -->

<div>
  <?php $this->section('custom1') ?>
</div>
<div>
  <?php $this->section('custom2') ?>
</div>

Migrate to theme-framework

You can migrate your existing theme and layouts to the theme-framework.

Before running contao:migrate:

1. Add a new column named alias to the tl_theme table and set 'alias' = 'my_theme' (where my_theme matches the name of your theme folder).

2. Add a new column named alias to the tl_layout table and set 'alias' = '_default' (where _default matches the name of your layout defined via the manifest file).

3. All layout settings defined via the manifest file will be overridden in the contao:migrate command. Existing settings won't be touched.

Best Practices

Do not rename the theme folder

Renaming the theme folder will create a new Contao theme in the database internally. You'll need to re-assign the layouts to the pages.

Use twig templates

You can use Twig or PHP templates by your preference. As already mentioned, your templates belong to the templates folder.

For Twig templates, suffix your file with .html.twig, i.e., fe_page.html.twig. For PHP templates, use the default naming, i.e., fe_page.html5.

Twig templates in the theme folder use the namespace @Contao_Theme_<name>, in a way that the template /themes/my_theme/templates/fe_page.html.twig can be referenced as @Contao_Theme_MyTheme/fe_page.html.twig.

ℹ️ Note that the "theme slug" for the Twig namespace will be transformed to CamelCase. If your theme folder is named my_theme, the Twig namespace will be @Contao_Theme_MyTheme.

You can place twig templates also in global (non theme-related) folders -- whatever feels right for you.

File	Twig namespace and reference	Prio (first wins)
/themes/my_theme/templates/fe_page.html.twig	@Contao_Theme_MyTheme/fe_page.html.twig	1
/templates/fe_page.html.twig	@Contao_Global/fe_page.html.twig	2
/contao/templates/fe_page.html.twig	@Contao_App/fe_page.html.twig	3

Read more about the usage of Twig templates in Contao under https://docs.contao.org/dev/framework/templates/twig/.

Use Webpack Encore to compile your theme assets

The skeleton theme comes with a pre-defined webpack.config.js file. The configuration will automatically process your asset files from the assets folder and generate the bundled files into the public folder.

Webpack Encore will also provide an entrypoints.json in the public folder. This helps to easily add the correct JS and CSS files to the current page (see above for usage).

Use a KnpMenu for navigation modules

With a KnpMenu you are much more flexible in outputting a navigation wherever you need it on the page.

See https://github.com/richardhj/contao-knp-menu for more information.

Do not deploy the assets folder

The assets folder with the source files (if present) should be excluded from the deployment because it most likely contains the node_modules folder next to the source folder. In contrast, all other files, like the theme.yml manifest and public and templates folders need to be uploaded when deploying.

Uninstalling

You wonder what happens to your themes when you uninstall the extension?

First, all your themes, layouts, and image size configurations stay in Contao. They won't get removed.

Second, templates under /themes/foobar/templates won't use the namespace @Contao_Theme_Foobar anymore but the namespace @Contao_Theme__themes_foobar_templates. This may break your website. For this to fix, move the templates folder to /templates/Foobar (from the project root). The Twig namespace stays intact.

Third, you lose the Encore and assets integration. This means that using the asset ({{ asset() }}) function or insert tag ({{asset::*}}) will fail. Further, the twig functions theme_link_tags() and theme_script_tags() will become unavailable. For this to fix, you have to include your CSS/JS files by directly referencing to them.

Use Symfony UX

// TODO