PHPackages                             richardhj/contao-theme-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. richardhj/contao-theme-framework

ActiveContao-bundle[Templating & Views](/categories/templating)

richardhj/contao-theme-framework
================================

3.0.5(2mo ago)199.9k↑170%[1 issues](https://github.com/richardhj/contao-theme-framework/issues)MITPHPPHP >=8.1

Since Mar 13Pushed 2mo ago5 watchersCompare

[ Source](https://github.com/richardhj/contao-theme-framework)[ Packagist](https://packagist.org/packages/richardhj/contao-theme-framework)[ RSS](/packages/richardhj-contao-theme-framework/feed)WikiDiscussions 3.x Synced 2w ago

READMEChangelog (10)Dependencies (10)Versions (26)Used By (0)

Contao Theme Framework
======================

[](#contao-theme-framework)

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

[![](https://user-images.githubusercontent.com/1284725/132962831-dcef78a7-2604-4782-aaf5-928321683059.png)](https://user-images.githubusercontent.com/1284725/132962831-dcef78a7-2604-4782-aaf5-928321683059.png)

Features
--------

[](#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](https://github.com/contao/contao/issues/2781).

Installation
------------

[](#installation)

```
composer require richardhj/contao-theme-framework
```

Quickstart
----------

[](#quickstart)

### 1. Create a theme folder

[](#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

[](#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

[](#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

[](#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
-----

[](#usage)

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

### Vanilla (No 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.](https://symfony.com/doc/current/components/asset.html)

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:**

```

{{asset::images/logo.svg::my_theme}}

{{ 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

[](#encore)

Read the documentation for Encore here:

First, install Webpack Encore:

```
composer require symfony/webpack-encore-bundle
```

Make sure to configure Encore properly by placing the [webpack.config.js](skeleton/theme/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](https://github.com/richardhj/contao-theme-framework/blob/528dfb7085b0d35036ed771cb0563a6b9f3a74ac/skeleton/theme/assets/webpack.config.js#L7). You can have multiple entrypoints per theme.

Finally, some tips for working with Encore and bundlers:

#### Git-Ignore the public folder

[](#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](skeleton/theme/.gitignore) of the skeleton theme may become handy.

#### Use yarn workspaces to manage multiple themes

[](#use-yarn-workspaces-to-manage-multiple-themes)

You can make use of [yarn workspaces](https://classic.yarnpkg.com/en/docs/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

[](#asset-mapper)

Read the documentation for the Asset Mapper here: [https://symfony.com/doc/current/frontend/asset\_mapper.html](https://symfony.com/doc/current/frontend/asset_mapper.html)

(tba)

FAQ
---

[](#faq)

### Wait – How do I build a website if all fields are disabled from tl\_layout?

[](#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 ``" or "custom ``" 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](https://symfony.com/doc/current/templates.html#the-app-global-variable). You will be surprised how not using modules for the layout significantly enhances maintainability.

### Custom layout sections

[](#custom-layout-sections)

[Custom layout areas](https://docs.contao.org/manual/en/layout/theme-manager/manage-page-layouts/#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 #}

  {{ section.invoke('custom1') }}

  {{ section.invoke('custom2') }}

```

```