Contao

Themes

Extensions

Choose your extension:

Contao Advanced Classes

The module extends the CSS classes of Contao elements with sets of CSS classes that you define yourself. Editors and admins can quickly pick predefined CSS classes from select fields.

Our configurator (still in development) lets you adapt the sets to your requirements easily.

Predefined sets for column width, column offset, order (pull/push) and visibility are included for Bootstrap, Materialize, Bulma and Spectre.css.

This documentation covers the following topics:

@MDevster 63 commits

@seibtph 58 commits

@visionpixel 1 commits

Requirements

Note

Advanced Classes is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Advanced Classes requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher.

Contao Manager

Advanced Classes is easy to install with the Contao Manager. Just search for Advanced Classes.

The extension in the extension directory on contao.org.

Installation

With the Contao Manager

Open the Contao Manager and log in
Select Discover in the menu
Enter Advanced Classes in the search field and click Add
Select Packages in the menu
If you use Contao 4.13 or lower, enter version 1.3.* instead of the latest version. With Contao 5, the Contao Manager installs the latest version automatically.
Click Apply changes to start the installation
Open the install tool (under Tools) and update the database

Configuration

Select a class set

Select the class set in the Contao settings under Advanced CSS settings. After that you can assign the classes to your front end elements.

Selecting the classes on a front end element:

Custom set

Create a JSON file (example) and store it, for example, in the files folder.

Create or edit the file app/Resources/contao/config/config.php and add the following to register the set. Then clear the cache in the Contao Manager.

<?php

$GLOBALS['TL_CONFIG']['advancedClassesSets'][] = '/files/sets/custom-set.json';

You can now select the set in the settings.

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

AlleAktien Quantitativ for Contao

Allows the insertion of various stock charts via insert tags.

Requirements

Note

AlleAktien Quantitativ for Contao is compatible with Contao 4.9 or higher.

Contao 4

Contao requires a web server such as Apache or NGINX with PHP and MySQL support. This bundle requires Contao 4.9 or higher and PHP 7.2 or 8.0.

Contao Manager

You can install the bundle with the Contao Manager (see installation).

Note

The bundle has no visual interface, so you will not see any changes in the back end. It adds several new insert tags.

Configuration

This bundle does not need to be configured.

Installation

1. Installation with the Contao Manager

Use the “Discover” https://youdomain.com/contao-manager.phar.php/#/discover function to install the bundle in the Contao Manager.
Search for the bundle using the keyword alleaktien. The bundle will then be offered to you for installation.
Click on “Add” in the bundle.
Then click on “Packages” and then on “Apply Changes”. The bundle will now be installed.

2. Perform database update

The usual database update after installation can be omitted.

Usage

1. What does the bundle offer?

This bundle adds new insert tags that display charts of stock prices. The charts are embedded in the website via an iframe and generated by AlleAktien Quantitativ. The copyright of the charts and content belongs to AlleAktien Quantitativ.

Benefits:

Always up-to-date and reliable figures directly from AlleAktien
Interactive charts – real added value for your visitors
20 years of fundamental figures
2,000+ stocks worldwide
100% free of charge
100% optimized for iPhone and iPad

The result looks like this, for example: Chart: QuoteChart, Deutsche Telekom share price.

2. How do I use it?

With a Contao insert tag you can embed individual charts from AlleAktien Quantitativ in your website free of charge and show long-term, always up-to-date and above all interactive fundamental stock figures. All with a single insert tag. Installation takes less than 10 seconds. The copyright of the charts and content remains with AlleAktien Quantitativ.

3. How are the insert tags structured?

An insert tag looks like this, for example:

{{aaq::ISIN::CHART-TYPE}}

where:

ISIN stands for International Securities Identification Number.

CHART-TYPE stands for one of the following chart types:

QuoteChart: share price of the last 20 years, daily
RevenueChart: revenue, EBIT and earnings
RevenuePerShareChart: revenue, EBIT and earnings per share
MarginsChart: gross margin, EBIT margin, profit margin
DividendChart: dividends
DividendYieldChart: dividend yield
PayoutRatioChart: payout ratio (dividends / earnings per share)
SharesOutstandingChart: number of shares outstanding
ValuationChart: P/E ratio, P/S ratio and EBIT multiple

4. What do the different charts look like?

QuoteChart

Insert tag: {{aaq::DE0005557508::QuoteChart}}

RevenueChart

Insert tag: {{aaq::DE0005557508::RevenueChart}}

RevenuePerShareChart

Insert tag: {{aaq::DE0005557508::RevenuePerShareChart}}

MarginsChart

Insert tag: {{aaq::DE0005557508::MarginsChart}}

DividendChart

Insert tag: {{aaq::DE0005557508::DividendChart}}

DividendYieldChart

Insert tag: {{aaq::DE0005557508::DividendYieldChart}}

PayoutRatioChart

Insert tag: {{aaq::DE0005557508::PayoutRatioChart}}

SharesOutstandingChart

Insert tag: {{aaq::DE0005557508::SharesOutstandingChart}}

ValuationChart

Insert tag: {{aaq::DE0005557508::ValuationChart}}

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Amphtml for Contao

Deliver your content to mobile devices even faster.

This extension lets you deliver additional AMPHTML pages from your Contao installation. It works with a dedicated theme that you can adapt to your own requirements.

Quick start

This documentation covers the following topics:

@MDevster 25 commits

@seibtph 10 commits

Requirements

Note

Amphtml is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Amphtml requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher.

Contao Manager

Amphtml is easy to install with the Contao Manager. Just search for amphtml-bundle.

The extension in the extension directory on contao.org.

Installation

Contao 4

With the Contao Manager

Open the Contao Manager and log in
Select Install packages
Enter “amphtml” in the search field
Click Check & install and then Apply changes
Open the install tool and update the database

Contao 3

Log in to the Contao back end
In the back end modules, select Extension catalog under System
Enter “amphtml” in the search field and press Enter
In the search result, click the install icon in the top right corner and follow the instructions

Select the search result “amphtml” and click the Install button

Configuration

1 / Download the cto file

Download the cto file from https://github.com/pdir/amphtml-bundle/raw/master/files/amphtml.cto
Install the theme via “Themes > Theme import”.
Activate AMPHTML in the website root, select default as the AMP HTML layout and choose the columns you want to display

Append ?amp to the domain to open the AMP pages (e.g. www.domain.com?amp).

CSS customization

Custom CSS for the AMPHTML pages goes into amphtml_custom.css.

Rename the file amphtml_custom_.css to amphtml_custom.css in files/amphtml
Copy the CSS from amphtml.css to amphtml_custom.css
Make your changes in amphtml_custom.css

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Animated Timeline for Contao

The Animated Timeline bundle is a jQuery extension based on jQuery Roadmap that displays content in a dynamic timeline with a fade-in animation.

You can choose between a horizontal and a vertical timeline, or combine both so that desktop devices show the horizontal timeline and mobile devices the vertical one.

Quick start

This documentation covers the following topics:

@seibtph 49 commits

@MDevster 27 commits

@cgoIT 1 commits

Requirements

Note

Animated Timeline is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Animated Timeline requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher.

Contao Manager

Animated Timeline is easy to install with the Contao Manager. Just search for animated-timeline-bundle.

The extension in the extension directory on contao.org.

Installation

1 / Open the Contao Manager

First open the Contao Manager at the following URL: https://www.your-domain.com/contao-manager.phar.php. Click Discover and enter animated-timeline in the search field. Add the bundle pdir/animated-timeline-bundle, go to Packages and click Apply changes at the bottom. The installation should now start.

2 / Update the database

Then update the database.

Configuration

1 / Placing the content elements

Wrapper elements

First place an element of type Wrapper (start) and Wrapper (end) in an article. You find them under Animated Timeline (see the following screenshot).

The element type Wrapper (start) has the following settings:

Orientation:
- Horizontal: The slider is displayed horizontally but not optimized for mobile devices.
- Vertical: The slider is displayed vertically and optimized for mobile devices.
- Auto: The slider is displayed horizontally on desktop devices and vertically on mobile devices.
Elements per slide: Number of elements shown per page. If there are more elements than this number, a navigation for showing the other elements is displayed.
Back button: Defines the back button if there are more elements than shown per slide. You can also insert HTML, e.g. an icon from an icon font library.
Next button: Defines the next button if there are more elements than shown per slide. You can also insert HTML, e.g. an icon from an icon font library.
Custom template: Select a template here if you want to copy and customize it.

Timeline element

Inside the wrapper elements, place an element of type Timeline element. There you can enter a headline and a text.

You can also add a single image or an image slider.

This is what it could look like in the back end:

Demo

You find a demo on demo.pdir.de

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Business Reviews for Contao

Easily display reviews from multiple platforms like Google+, Facebook and Trustedshops on your Contao website.

Quick start

These topics are contained in the documentation:

Requirements

Note

Business Reviews for Contao is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Business Reviews requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher.

Contao Manager

Business Reviews is easy to install with the Contao Manager. Please use the upload function in the Contao Manager.

Configuration

Installation

Die Installation des Business Reviews Contao Moduls erfolgt über die **Pakete hochladen" Funktion des Contao Managers und ist nur auf Anfrage möglich. Kontaktiere uns am besten über das Kontaktformular.

1 / Contao Manager aufrufen

Contao Manager öffnen: https://example.com/contao-manager.phar.php/#/packages

2 / Hochladen der Zip-Datei

Lade die aktuelle Version des business-reviews-bundle aus deiner Bestellmail oder deinem Kundenkonto über die Pakete hochladen Funktion des Contao Managers hoch und bestätige anschließend den Upload mit Uploads bestätigen unten im Manager. Anschließend kannst du die Änderungen anwenden und der Manager beginnt mit der Installation.

3 / Datenbank updaten

Rufe anschließend das Installtool auf und aktualisiere die Datenbank.

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Contao Klaro

The Klaro Consent Manager makes the well-known privacy manager Klaro (see heyklaro.com) available in Contao 4.

Klaro is normally configured with a static configuration (JavaScript file) to fit the needs of the users. This module makes configuration easier by making all parameters accessible in the back end. You no longer have to write your own KlaroConfig, but can set (almost) all parameters conveniently in the back end.

Klaro is GDPR compliant, easy to configure, lightweight and compatible with all modern browsers. For a lightning-fast setup we have prepared an extensive configuration file with more than 20 services. Learn more on our project website.

This documentation covers the following topics:

@MDevster 124 commits

@seibtph 15 commits

@theroch 2 commits

Requirements

Contao 4

Note

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Our Klaro module requires Contao 4.9 or higher and PHP 7.2.

Contao Manager

Contao Klaro is easy to install with the Contao Manager. Just search for Contao Klaro.

The extension in the extension directory on contao.org.

Installation

Contao 4

With the Contao Manager

Open the Contao Manager and log in
Select Discover in the menu
Enter Klaro in the search field and click Add
Select Packages in the menu and click Apply changes
Open the install tool (under Tools) and update the database

Configuration

0. Overview

As the Klaro configuration can become quite extensive, we have sorted the individual components into different configuration areas. This makes the configuration clearer and helps you find the parameters faster. This means that the parameters of the KlaroConfig file are now found in four areas.

These four areas are:

Klaro configuration (config)
Klaro services (config.services)
Klaro purposes (purposes)
Klaro translations (config.translations)

Note

The following explanation often refers to the annotated configuration. This is a commented example configuration file that the Klaro developers provide to users for orientation. You find the annotated configuration here. Sometimes we also refer to the API documentation. You find it here.

Klaro quick configuration

Note

Several questions showed us that the configuration of Klaro is not as easy as it ideally should be. That is why this documentation starts with a quick configuration section. With it you should be able to create a working configuration within about 5 minutes after installing the bundle. The following three steps are required: 1. Create a configuration 2. Create two translations and 3. Assign the configuration to the website root (root page).

1. Create a minimal configuration

2. Create two translations

To start, Klaro needs the translation for the current language (here we assume de) and a fallback language, which Klaro calls zz. The screenshot shows two suggestions for naming them.

Now create, for example, a German translation named Deutsch-Deutschland (de-DE) with the language code de, and a second fallback translation named Klaro Default (zz-ZZ) (or Klaro Fallback (zz-ZZ)) with the language code zz. You can ignore the two warnings here.

3. Assign the configuration to the website root

Once that is done, switch to the root page (we assume a root page already exists) and activate the Klaro configuration you just created. You recognize the root page by the type Website root. Only this page type has the option Klaro settings. Activate your Klaro configuration here and assign it to the website root.

Done

If you now reload the page in the front end, you should see the Klaro Consent Manager at the bottom right. It looks like this: As no purposes and services have been configured yet, the modal dialog with the services stays empty after clicking Let me choose. Configuring services and purposes would therefore be the next step.

Note

We recommend defining purposes first and then creating services. Basic purposes would be: analytics, statistics, video-streaming, audio-streaming, security etc. Basic services would be: google-analytics => analytics (purpose), matomo => statistics, youtube-video => video-streaming, vimeo => video-streaming, soundcloud => audio-streaming etc.

Configuring Klaro (in detail)

The Contao Klaro module makes the Klaro configuration more flexible, because the KlaroConfig is always rebuilt from the parameter set at runtime. This makes changes to the configuration quick and easy. This concept also allows you to keep many configurations, which can be assigned to a website root (root page) as needed. There can, however, only be one valid configuration per root page. This way you can define different privacy profiles for your site and activate the right one when needed. The module respects the language code of the website root (root page), so nothing else needs to be configured here. Of course you still have to define a translation, otherwise Klaro only shows the default language.

Where do I start?

If you want to use Klaro on your site, we recommend that you first check your site structure and adjust it if necessary. Perhaps your site already follows the recommendations described below?

For multilingual sites there should be a website root (root page) for each language (see screenshot). Below each of these website roots there should be a page with the language-specific privacy policy. You can select this page later in the configuration to link in a friendly way to the privacy policy in the respective language.

A small detour…

Once this structure exists, you could simply open and edit the desired website root under Site structure. There you find (but only if it is a website root, a so-called root page) the additional legend Klaro settings.

Note

A Klaro configuration is always bound to the root page (website root) of a website!

Here you can assign a Klaro configuration to the website root. On a first installation, however, none has been defined yet. So you first have to create at least one configuration.

1. Klaro configuration

You manage the Klaro configurations in the menu Klaro configuration. Each configuration offers the options below. We explain them one after the other…

Basic settings

In the basic settings you can give the configuration a name. As mentioned at the beginning, Contao Klaro supports many configurations, of which Klaro only uses one at runtime. As there can be many configurations, you have to give each one a name.

Configure services

Here you configure the services that Klaro should manage. Klaro can manage any number of (custom) services. Each service is categorized. The category is the purpose of the service. The concept is perhaps easiest to explain with the two components Klaro notice (sometimes also called consent box) and Klaro manager (also called modal window). Here comes another small detour…

Note

Klaro essentially appears on your website through two visible elements: the Klaro notice (consent box) and the Klaro manager (modal window). The Klaro notice is shown to visitors every time they open the website, as long as Klaro does not find any consent information in its storage. The Klaro notice looks like this: The Klaro manager is shown to visitors when they click the link ‘Let me choose’. It can also be opened explicitly via the API with klaro.show(). The Klaro manager lists the purposes (categories) one below the other, and each purpose can have one or more services assigned. It looks roughly like this… Purposes can be, for example: Analytics, Security, Chat, Advertising or Streaming – etc. You can define the purposes yourself. By services, Klaro basically means the websites (or API endpoints) to which user data requiring consent is transferred. You can also define the services yourself. Users are therefore asked for their consent to a service or a purpose. A purpose can be assigned to many services and a service to many purposes. You define these assignments yourself.

After this short definition of the terms purpose and service, let’s continue with the configuration. We had stopped at the services. The services that a configuration should use can be selected in the following section. Here is an example:

Note

When you configure Klaro for the first time, you will probably not see any services to choose from here. You have to define your services first before you can complete the configuration. You can read more about configuring services under 2. Configure Klaro services.

Configure the script

Note

You can skip this point. It is only relevant for experienced users!

Klaro is written in JavaScript. Here you can define two parameters for the script itself. The first parameter is the loading mode and the second the name of the configuration variable.

The loading mode defines how the script is loaded. The way it is loaded is not unimportant, but we won’t go into detail here. Klaro supports the modes synchronous, deferred (defer) and asynchronous (async). The mode defer is recommended. It is the default.

You can define a different name for the configuration variable here. This is usually not necessary. If, however, a variable with the same name happens to exist in the current namespace, a different name may be necessary.

When the page loads and the consent box is shown at the bottom right, you can set some parameters for this display. Another short note first:

Note

Klaro usually does not start with the Klaro manager (modal window), but only with the consent box, a small notice at the bottom right of the browser window. It looks (roughly) like this: The text shown here, ‘Consent Notice Text 4096 Zeichen und HTML Text’, is just an example text that you can define yourself; we explain it in more detail later.

The following parameters can be configured:

The first switch, HTML mode, lets you output HTML instead of plain text as the notice. This opens up many more possibilities for designing notice texts in Klaro. Even tables and graphics can be displayed. In theory even SVG would be possible, but we haven’t tried it yet…

The switch Start Klaro as a modal dialog shows the Klaro manager immediately on start instead of the consent box. The Klaro manager overlays the website content so that the visitor can change their consents. Clicking outside the modal window closes the manager without applying the changes. Only after clicking Save is the consent information stored locally (see also the next section Configure cookies).

The switch Force modal means that the Klaro manager cannot be closed until the user has explicitly confirmed with Save. This lets you require certain consents before the site can be used, because the site cannot be used while the Klaro manager is open as a modal.

The switch Default consent for all services is self-explanatory. If enabled, all services are set to accepted when Klaro starts or on the first visit to the site. The Klaro developers advise against using it, as it contradicts the concept of self-determined privacy.

The switch Accept all shows an additional button in the Klaro manager that lets the user accept all services with one click. If this option is not enabled, each service has to be accepted individually.

If the option Hide »I decline« is enabled, the corresponding button in the Klaro notice is hidden. As a result, the user has to open the manager to withdraw consent. The Klaro developers advise against using it, as it contradicts the concept of self-determined privacy.

If the option Hide »Let me choose« is enabled, the corresponding button in the consent box (notice) is affected. This button lets website users open the manager and configure their consents individually.

The last option in this section lets you select pages in your page tree on which the Klaro manager and the Klaro notice should not be active. Klaro.js itself is still loaded on all pages. This is necessary so that the manager can be opened again to change the consents.

Configure cookies

In this section you configure the storage behavior of Klaro. Another configuration option for cookies is in the section Cookie rules of the services. There you can define a separate list of cookie rules for each service.

The following parameters can be configured:

The DIV ID is the »ID« attribute of the Klaro DIV tag. Strictly speaking, this is not a parameter related to storage behavior. You can simply define your own ID here if the default one is already in use. The default is ‘klaro’.

Under Storage key you can change the key for the browser local storage. Klaro writes the consent information to a storage on the client side (see also the following parameter). To find this information again, Klaro needs an identifier. That is this storage key. It has nothing to do with encryption. The default is ‘klaro’.

Under Storage method you choose in which storage Klaro.js saves the consent information. Klaro currently offers the two options Cookie Storage and Browser Local Storage. Feel free to look up the pros and cons of these two storage locations. The default is Cookie Storage.

In the field Cookie domain you configure the domain. Don’t forget this! Without the domain your root page is running on, Klaro does not work correctly. So please configure the cookie domain!

Finally, you can set the cookie expiry time here. The default is 30 (days).

Callback definition

Note

You can skip this point. It is only relevant for experienced users!

Klaro.js supports callbacks (rudimentarily). Basically two callback definitions are possible (not to be confused with the watchers briefly mentioned in the Klaro API!). One callback can be defined in the KlaroConfig and one more for each service. As the KlaroConfig can define several services, there can be many service callbacks, but only a single config.callback. The callbacks have a uniform signature of the form function(consent,service) {}, where consent (bool = true/false) is the consent status and service represents the internal Klaro service object. consent returns the current consent status for the given service. You cannot change the function signature in the Contao Klaro module, only write the function body yourself. You are responsible for correct script code!

Tip

We were not successful in finding a useful application for the callbacks. At least they do not behave as described in the annotated configuration. However, we didn’t spend much time analyzing the Klaro code, as that was not our goal. You find a small overview of the problems on GitHub

Testing and maintenance

Here you can activate a so-called test mode. You find a short note on it in the annotated config.

2. Configure Klaro services

You manage services in the menu Klaro services. A service offers the following options:

Name (of the service configuration)

In the Name section you can give the service configuration a name. This name helps you find the service configuration easily and distinguish it from other configurations.

In the second section you define the service name, the assignment of purposes and the cookie rules.

Note

Please note that these parameters always refer to only one service. Please also note that the name of the service configuration and the service name are two different things! The name of the service configuration is meant to help you organize and distinguish many configurations, whereas the service name is used internally by Klaro.js and is important. If the service name is defined incorrectly, Klaro does not work correctly! As we don’t know exactly how Klaro handles this string internally, we recommend using only lowercase letters and hyphens here. Our Contao Klaro module allows all characters, but we don’t know whether Klaro.js accepts them. Feel free to try it out, though.

So you have to enter a string for the service in the field Service name! This field is mandatory! The example shows ‘google-analytics’. We recommend this notation. It is also suggested by the annotated configuration.

Next you can assign the service to different purposes. If no purposes have been defined yet, this list is empty. You then first have to create new purposes in the menu Klaro purposes. You find more about this below in the section 3. Configure Klaro purposes.

Note

In the image above you also see a purpose [contaoce] translation missing whose name looks a bit odd. You always see this display when a translation for this purpose is missing under Klaro translations. You find more about this below in the section 4. Configure Klaro translations. This also shows nicely that there are many dependencies within the Klaro configuration.

Finally, you can define so-called cookie rules here. We used the examples from the annotated configuration. If you want to understand how these rules work, we recommend a look at the annotated configuration.

Service defaults

Here you configure how the service is preset when the page is first loaded by Klaro. The options are largely self-explanatory.

With the option accepted you define whether this service is already preset to accepted when the site is opened.

Required means that the user cannot deactivate this service. So use this option for services that are necessary for your website to work at all (e.g. shopping cart cookies etc.).

If the option force is enabled, Klaro loads the service even if the visitor has not yet consented to it. The Klaro developers advise against using it, as it contradicts the concept of self-determined privacy.

If the option once is enabled, the service is only requested once by Klaro, no matter how often the user switches it on and off. This matters, for example, for tracking scripts that create a new request every time Klaro notices a change of consent by the user.

If the option contextual is enabled, Klaro treats the service as »contextual«. This means that a separate consent is requested at the corresponding positions in the layout before the content of the element is shown.

Callback definition

Note

You can skip this point. It is only relevant for experienced users!

As mentioned in the section 1. Klaro configuration, Klaro supports certain callbacks. Here you can define a callback (more precisely the function body) for the service.

3. Configure Klaro purposes

There is not much to say about the Klaro purposes. Klaro uses them to create an internal assignment to the services. Conversely, each service can be assigned one or more purposes.

Name and Klaro key (purpose key)

For the name of the purpose you can enter any string.

For the Klaro key it is important to use only lowercase letters and hyphens. Klaro uses this string internally as a JavaScript object key, and – put simply – it must not contain any other characters.

4. Configure Klaro translations

Finally, we come to the Klaro translations. Klaro is designed for multilingual use throughout. This (unfortunately) also opens up a great many configuration options. As not all elements need to be configurable by the user and this can quickly become confusing, we have only made selected translations accessible. We based the selection on everyday use.

Note

As Klaro is relatively tolerant (meaning that in case of errors it tries not to block or hinder the website it runs on), we followed this concept for the translations. This means you can enter translations incorrectly or not at all. Of course, texts will then be missing or you will get odd output. But that’s up to you…

The Klaro translations offer the following options:

Name of the translation

As there can be many translations, we follow our habit here and offer a name for the translation. It is a string you can choose freely; the field is mandatory. We recommend following the Klaro annotated configuration for the naming. There the languages are defined by language codes according to ISO 639-1. So we recommend naming them as in the following image:

Language code and link to the privacy policy

Next you set the language code (the country code). Klaro uses ISO 639-1 codes.

Below the language code you can select a link to a page with your privacy policy in the respective language.

Two important notes:

Note

As the Contao Klaro module takes its language from the website root (root page), no further configuration is needed by the user. If Klaro ever shows the wrong language on your website, first check whether the language code of your Klaro translation matches the language code currently selected in the root page. The Contao Klaro module configures the KlaroConfig using the language code of the root page. Contao’s own language fallback is not taken into account in our module, as Klaro brings its own fallback concept. Perhaps this will be implemented later…

Note

Internally, Klaro also uses a so-called language fallback code: zz. According to the annotated configuration you should therefore also define a translation for the language zz. We did not get clearly reproducible results with it. According to the annotated configuration, elements from zz should be shown when other languages are not defined. However, we observed that Klaro prefers the translations of the fallback language zz over the correctly defined translations of other language codes, so that the actual (current/desired) language is not shown. It may therefore be necessary not to define zz at all, or to define it in the desired language. Just try it out…

Here you can enter a text or any (well, not quite – but try it!) HTML. The TinyMCE editor helps you with this. Here you also find the example text from this explanation: “Consent Notice Text 4096 Zeichen und HTML Text”. If you look closely, you can see that this consent notice is shown in bold and italics. That is already simple HTML. If instead you see the tags themselves, i.e. <b>Consent</b> (or similar), you may not yet have enabled the option HTML mode under Klaro configuration -> Configure the consent notice -> HTML mode. We limited the number of characters to 4096.

Klaro lets you define two different texts: the one just mentioned for the consent box (the Klaro notice) and a different text for the modal window. Here you set the text for the modal window. This output also supports HTML code, as described above. The number of characters is limited to 4096.

Translation table for registered purposes

Now follow two tables for the translations. We start with the translation of the purposes. All translation tables work in a similar way, so here is some basic information first.

Note

For Contao insiders: As a translation is in the simplest case a key-value mapping, we implemented this function with the KeyValueWizard. This is a compromise between performance and usability, because the KeyValueWizard is unfortunately not ideally equipped for this use. Here you can assign a translation to each previously defined purpose (key). The correct key must be entered under key. If you enter an unknown key or make a typo, you cannot save the record. As you can’t keep all keys in your head at the same time, the error message and a little helper we built in assist you. You can see from the error message which keys are allowed and where the typo might be.

Tip

We built in a little helper that automatically re-enters the already registered keys for you. So if everything went wrong, simply delete all elements from the table. At the end, one key-value pair remains. Delete the contents of these fields as well and save the record with the Save button. In this situation the widget determines all registered keys again and pre-fills the table. You then only have to add the translations (see the image in the previous note).

Translation table for registered services

There is not much to add here. In this table you define the translation for registered services. Otherwise, everything said for the previous table applies.

Note

While working with Klaro we noticed that some texts and labels don’t quite fit the problem that is being solved. We noticed this, for example, when displaying elements for which no consent had been given yet. So we thought it would be good to be able to adjust these texts as well. The default configuration looks like this, for example: Yes or Always? That is somewhat unclear, especially considering that we also want to welcome visitors who speak other languages on our website. That is why we added an option to customize this placeholder.

In the field Question text you can now phrase the question in more detail. Klaro.js offers the variable {title} here, which is replaced by the name of the assigned service (don’t ask why service.name is called title here). In the image you can see that at this position the consent for the service »YouTube« is requested. The left button gives a one-time consent (until the next request / reload of the page), so we labelled it »once«.

The right button gives consent until revoked (via the Klaro manager alias modal window), hence this label.

Services

This page shows examples of how to include various services.

Adjustments for the HTML code element

Depending on the content, additional entries under Allowed HTML tags and Allowed HTML attributes may be necessary.

Tags: <iframe><noscript>
Attributes: allow,data-name,data-src,data-type,frameborder,height,scrolling,src,width

FundraisingBox (iframe)

The <script> tag must contain the following attributes: type="text/plain" data-type="text/javascript" data-src="..." data-name="fundraisingbox".

Add data-name="fundraisingbox" to the <a> tag.

<script type="text/plain" data-type="text/javascript" data-src="https://secure.fundraisingbox.com/app/paymentJS?hash=12345..." data-name="fundraisingbox"></script>
<noscript>Please enable JavaScript</noscript>
<a href="https://www.fundraisingbox.com" target="_blank" rel="noopener noreferrer" data-name="fundraisingbox">
  <img class="no-lazy !important;" style="border: 0 !important;"
  src="https://secure.fundraisingbox.com/images/FundraisingBox-Logo-Widget.png"
  alt="FundraisingBox Logo" border="0" />
</a>

Google Analytics

Select the template analytics_google.html5 provided by the Klaro extension and include it in the layout, or adjust your template accordingly. The attributes in the <script> tag are what matters.

<script type="text/plain" data-type="application/javascript" data-name="google-analytics">
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
  ga('create', '<?= $GoogleAnalyticsId ?>', 'auto');
  ga('set', 'anonymizeIp', true);
  ga('send', 'pageview');
</script>

Google Maps

The example refers to the Contao Google Maps Bundle and is only available from Klaro version 1.1.1.

To show the following notice in the front end, select the template gmap_map_klaro.html.twig at the very bottom of the Google Maps map settings (Content -> Google Maps -> wrench icon).

Google Tag Manager

Add the following code as high up in the <head> as possible. The attributes in the <script> tag are what matters:

data-type="application/javascript" type="text/plain" data-name="google-tag-manager".

<!-- Google Tag Manager -->
<script data-type="application/javascript" type="text/plain" data-name="google-tag-manager">(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
<!-- End Google Tag Manager -->

Also add the following code directly after the opening <body> tag. Replace src with data-src and add data-name="google-tag-manager".

<!-- Google Tag Manager (noscript) -->
<noscript><iframe data-name="google-tag-manager" data-src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->

Hotjar

Add the following attributes to the <script> tag: type="text/plain" data-type="application/javascript" data-name="hotjar".

<!-- Hotjar Tracking Code -->
<script type="text/plain" data-type="application/javascript" data-name="hotjar">
    (function(h,o,t,j,a,r){
        h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
        h._hjSettings={hjid:XXXXXX,hjsv:6};
        a=o.getElementsByTagName('head')[0];
        r=o.createElement('script');r.async=1;
        r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
        a.appendChild(r);
    })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>

Matomo

Select the template analytics_matomo.html5 provided by the Klaro extension and include it in the layout, or adjust your template accordingly. The attributes in the <script> tag are what matters.

<script type="text/plain" data-type="application/javascript" data-name="matomo">
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u='<?= $MatomoPath ?>';
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', <?= $MatomoSite ?>]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.defer=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>

Meta Pixel

Add the following attributes to the <script> tag: data-type="application/javascript" type="text/plain" data-name="meta-pixel".

In the <img> tag, replace src with data-src and add data-name="meta-pixel".

<!-- Meta Pixel Code -->
<script data-type="application/javascript" type="text/plain" data-name="meta-pixel">
!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'XXXXXXXXXXXXXXX');
fbq('track', 'PageView');
</script>
<noscript><img height="1" width="1" style="display:none" data-name="meta-pixel" data-src="https://www.facebook.com/tr?id=XXXXXXXXXXXXXXX&ev=PageView&noscript=1"
/></noscript>
<!-- End Meta Pixel Code -->

Mixcloud (iframe)

In the <iframe> tag, replace src with data-src and add data-name="mixcloud".

<iframe width="100%" height="60" data-src="https://www.mixcloud.com/widget/iframe/?hide_cover=1&mini=1&light=1&feed=%2Fpfadfinder%2Fliquid-drum-and-bass%2F" data-name="mixcloud" frameborder="0">
</iframe>

Soundcloud Player (iframe)

In the <iframe> tag, change src to data-src and add data-name="soundcloud".

<div>
<iframe width="100%" height="300" scrolling="no" frameborder="no" allow="autoplay" data-src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/224507370&color=%23ff5500&auto_play=false&hide_related=false&show_comments=true&show_user=true&show_reposts=false&show_teaser=true&visual=true" data-name="soundcloud">
</iframe>
<div style="font-size: 10px; color: #cccccc;line-break: anywhere;word-break: normal;overflow: hidden;white-space: nowrap;text-overflow: ellipsis; font-family: Interstate,Lucida Grande,Lucida Sans Unicode,Lucida Sans,Garuda,Verdana,Tahoma,sans-serif;font-weight: 100;">
	<a href="https://soundcloud.com/pfadfinder" title="Pfadfinder" target="_blank" style="color: #cccccc; text-decoration: none;">Pfadfinder</a> · 
	<a href="https://soundcloud.com/pfadfinder/mixtape-podcast-18nd-sep-2015" title="Mixtape Podcast - 18nd Sep 2015" target="_blank" style="color: #cccccc; text-decoration: none;">Mixtape Podcast - 18nd Sep 2015</a>
	</div>
</div>

Spotify (iframe)

In the <iframe> tag, replace src with data-src and add data-name="spotify".

<div class="column is-6">
	<iframe style="border-radius:12px" data-src="https://open.spotify.com/embed/show/4xXvD63BkDDalKZg6PI5mk?utm_source=generator" data-name="spotify" width="100%" height="232" frameborder="0" allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture">
	</iframe>
</div>

Vimeo video

The extension provides a template ce_vimeo_klaro.html5 that you can select in the content element.

YouTube video

The extension provides a template ce_youtube_klaro.html5 that you can select in the content element.

Import configuration file

Note

To be safe, back up your database first! A wrong selection can delete all content in the database.

Guide for Contao 5

You find the guide for Contao 5 here.

Guide for Contao 4

You find the guide for Contao 4 here.

Configuring services

You find examples for configuring services here.

Contao 5

Note

To be safe, back up your database first! A wrong selection can delete all content in the database.

In Contao 5 you import the configuration file directly in the back end under Themes by clicking Import.

Select the file to import and click Import.

CAUTION: Before you click Continue, select Data only, without truncating the tables as the import type, otherwise the whole database and all content of the website may be deleted.

The configuration should now have been created under Klaro configuration.

To show the Klaro banner, assign the Klaro configuration to the root page in the site structure.

The Klaro banner should now be visible at the bottom right of the website.

Contao 4

Note

To be safe, back up your database first! A wrong selection can delete all content in the database.

In Contao 4 you import the configuration file with the install tool. Open the install tool by appending /contao/install to your domain.

Upload the file to the templates folder first. You can only do this via FTP, not directly in the Contao back end.

Under Import a template, select the file. Make sure to tick Do not truncate tables, otherwise all content will be deleted from the database!

The configuration should now have been created under Klaro configuration.

To show the Klaro banner, assign the Klaro configuration to the root page in the site structure.

The Klaro banner should now be visible at the bottom right of the website.

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

krpano Bundle for Contao

The krpano bundle for Contao 4 integrates the well-known and widely used panorama software of the same name into the Contao CMS. The free version of the bundle installs the equally free demo version of the krpano viewer for HTML5.

Important notes!

The HTML5 viewer adds a “krpano demo version” watermark. For unrestricted use of krpano you need to buy a krpano license!
You have to create the panoramas yourself. The corresponding droplets are not included in the bundle. If you already use krpano, you can keep using your file structures.
The Flash component of krpano is not supported by this bundle.
You find an overview of the available krpano licenses here: krpano.com/buy.
A demo of the bundle is available here: demo.pdir.de/krpano-bundle.

Further links

Report a problem

Installation

1. Installation with the Contao Manager

To install the bundle, use the “Discover” function of the Contao Manager: https://yourdomain.com/contao-manager.phar.php/#/discover.
Search for the bundle with the keyword krpano. The bundle is then offered for installation.
Click “Add” on the bundle.
Then click “Packages” and then “Apply changes”. The bundle is now installed.

2. Run a database update

After the installation has finished, run a database update.

Configuration

After the installation you will find a new menu item pdir Apps in the main menu of the back end. It contains three entries: Panoramas, Hotspots and Configuration. The three entries are largely self-explanatory.

under »Panoramas« you manage all panoramas registered in the system
under »Hotspots« you manage all hotspots. Hotspots are always assigned to one or more panoramas.
under »Configuration« you manage a krpano configuration.

List

This menu item gives access to the available panoramas. They are shown in a customized list. Each record is shown with a heading and in two columns. The heading shows the ID of the panorama and its name. The left column contains data about the hotspots and a preview image (krpano preview.jpg, if one was generated). The right column (currently) contains the description text, as it can be very long.

Edit

As usual in Contao, click the yellow pencil to edit a record. The detail view looks like this: Each panorama record gives access to the following data:

Panorama name and alias

You can set a name and an alias for each panorama.

The field of view (also called »view«)

A view consists of three parameters: the horizontal viewing direction, the vertical viewing direction and the field of view angle (sometimes called the zoom value). The view is initialized with start values when it loads. You enter them under Field of view and viewing direction:

the start viewing direction, horizontal (krpano pov = point of view) is a decimal number with two decimal places. The range is from -180.00° (left) to +180° (right). This setting may differ from older krpano versions. Strictly speaking, -180° = +180°, i.e. a vector on the horizon plane pointing »backwards«. If you want to know more about the structure and configuration of a view, we recommend the krpano documentation on the view.
the start viewing direction, vertical (krpano poh = point of heading) is also a decimal number with two decimal places. The range is from +90.00° (zenith) to -90° (nadir).
the start field of view angle (fov = field of view) is a decimal number with two decimal places. The range is (theoretically) 0.00°, (in practice) 27.54° to (theoretically) 180.00°, (in practice) 120.00°.

Preview

The preview window is below the view parameters and shows the current panorama. It is initialized with the values of the view. The preview also shows all hotspots associated with the panorama and several overlays. It looks like this:

Overlay »View«

At the top left there is an overlay with the three parameters (pov, poh and fov) of the view. It shows the parameters of the current view. If you click into the preview and »drag« the panorama with the mouse button held down, you can move the view (pan and zoom). The parameters are updated continuously. Once you have changed the view, you can save the parameters with one click. This makes working with a panorama easier, because you don’t have to enter all three parameters separately every time.

Info

To set the view again, click into the preview and not on a hotspot! The view overlay cannot be hidden.

Overlay »Debug mode«

This overlay can be shown and hidden. It shows important parameters of the panorama and helps with troubleshooting.

Overlay »Hotspots«

On the right edge of the preview there is an overlay with all hotspots of the panorama.

Info

Unfortunately, not all hotspot types have the correct icons yet.

The following icons are available:

Icon	Meaning
	Error This hotspot is faulty or cannot be jumped to (not a GoTo hotspot).
	GoTo Click this hotspot to jump to it. There is a target panorama available at the marked position.
	Image This is an image hotspot. A photo or hover information is shown at this position.

This menu item lists the hotspots.

Real Estate Module for Contao

Quick start

This documentation covers the following topics:

@MDevster 280 commits

@seibtph 123 commits

@gmpf 1 commits

@agonyz 1 commits

Requirements

Note

The real estate module is compatible with Contao 5 and 4.

Contao 5 and Contao 4

Contao 5 requires a web server such as Apache or NGINX with PHP and MySQL support. Our real estate module requires Contao 4.13 or Contao 5.x and PHP 8 or higher.

Tip

We recommend Contao 5.3 with PHP 8.3 or higher.

Contao Manager

The real estate module is easy to install with the Contao Manager. Just search for maklermodul-bundle.

The extension in the extension directory on contao.org.

License

The real estate module for Contao is available as a domain license and can be ordered online on www.maklermodul.de.

For the full version, install the maklermodul-sync-bundle.

Note

You receive the required access data and the installation guide by email after your order.

Order a license Product website

Installation

Note

You should already be familiar with the Contao CMS.

Tip

– The Contao installation must be in the root directory. – jQuery must already be included.

Steps

1 / Installing the real estate module demo

The real estate module is compatible with Contao 4.4 and higher. To install the demo, follow these steps:

Open the Contao Manager and log in
Select Install packages
Enter “maklermodul” in the search field
Click Check & install and then Apply changes
Open the install tool and update the database

You can buy a license for the real estate module here. After buying the license and installing the Maklermodul Bundle, continue with the steps in the section Installing the full version.

2 / Installing the full version

To use the full version you need the Maklermodul Sync Bundle in addition to the Maklermodul Bundle. If you haven’t installed the demo yet, follow the steps in the section Installing the real estate module demo.

Installing the Maklermodul Sync Bundle:

Option 1: via the Contao Manager and a zip file

log in to the Contao Manager and go to the section “Packages”
upload the ZIP file to the server with the button “Upload packages”
click the button “Confirm uploads”
click the button “»maklermodul sync for Contao 4« + Add package”
start the Contao Manager update/installation by clicking the button “Apply changes”
wait until the installation/update has finished
click the button “Update database” - the install tool starts
log in to the install tool and run the database updates
go back to the Contao Manager and finish the installation.

Option 2: manual installation

Install the Maklermodul Sync Bundle by editing the file composer.json in the Contao root directory. Add the following line at the end of require, and don’t forget to add a comma after the line before it (see the composer.json example).

For Contao 4.4, replace VERSION with 1.3. For Contao 4.6, replace VERSION with 2.0.

"pdir/maklermodul-sync-bundle": "^VERSION"

Then add the following lines at the end of the file, before the last closing curly bracket, and replace BENUTZERNAME (user name) and PASSWORT (password) with the access data from your order email. Again, add a comma after the curly bracket in the line before.

,
"repositories": [
    {
        "type": "composer",
        "url": "https://BENUTZERNAME:PASSWORT@packages.contao.store"
    }
]

Example of what composer.json should look like for Contao 4.4:

{
    "type": "project",
    "require": {
        "contao/calendar-bundle": "^4.4",
        "contao/comments-bundle": "^4.4",
        "contao/conflicts": "*@dev",
        "contao/faq-bundle": "^4.4",
        "contao/listing-bundle": "^4.4",
        "contao/manager-bundle": "4.4.*",
        "contao/news-bundle": "^4.4",
        "contao/newsletter-bundle": "^4.4",
        "pdir/maklermodul-bundle": "^1.4",
        "pdir/maklermodul-sync-bundle": "^1.3"
    },
    "extra": {
        "contao-component-dir": "assets"
    },
    "scripts": {
        "post-install-cmd": [
            "Contao\\ManagerBundle\\Composer\\ScriptHandler::initializeApplication"
        ],
        "post-update-cmd": [
            "Contao\\ManagerBundle\\Composer\\ScriptHandler::initializeApplication"
        ]
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://BENUTZERNAME:PASSWORT@packages.contao.store"
        }
    ]
}

3 / Updating packages and the database

Then open the Contao Manager at https://www.your-domain.com/contao-manager.phar.php. Start the Contao Manager and click Update packages. Then click Check & install and wait for the installation to finish.

Afterwards, open the install tool and update the database.

Configuration

Note

A root page should already exist.

1 / Create pages

First create one page each for the list view and the detail view.

2 / Create modules

In the left navigation, select Themes under Layout and click the gear icon Edit the front end modules of theme ID … for the theme of your website.

Create a module for the list view

Select New module and create a module for the list view:

Enter a title for your property list.
Under Module type, select Immobilienliste (property list) under pdirMaklermodul.
Under Detail view, select the corresponding page.
If no template is selected, the template makler_list is used by default.

The page Displayed fields and filters shows how to display fields and filters in the list view. You find further settings on the page List view configuration.

Create a module for the detail view (exposé)

Select New module and create a module for the detail view:

Enter a title for the exposé.
Under Module type, select Expose under pdirMaklermodul.
Under Immobilienliste (property list), select the page that shows the property list.
Under property templates, select either the template makler_details_simple or makler_details_extended.

Optional:

You can show a Google Maps map. Learn more on the page Integrating Google Maps.
You can set your own placeholder image in case a property has no image. If no placeholder image is selected and the property has no image, a placeholder image provided by the module is shown.

3 / Include the modules

Once you have created the modules, include them in the articles of the list and detail view.

Select the corresponding article of the list or detail view.
Choose New element and place it anywhere.
Select the element type Module and choose the module you created.

4 / Adjust the settings

Note

No longer necessary since Contao 4.9. Otherwise, enable auto_item in the settings under front end settings.

For the link to the detail page to work, auto_item must be enabled. Since Contao 4.9 it is enabled by default and has to be disabled explicitly in config.yml if you don’t want it:

# config/config.yml
contao:
    localconfig:
        useAutoItem: false

5 / Adjusting the property URL in parameters.yml

Note

Required since version 2.5.0. Here you can adjust how the alias for the property URL is generated.

Recommended configuration

Add the following lines to parameters.yml in app/config/ or, since Contao 4.9, in config/ (“parameters:” may already exist):

parameters:
    pdir_maklermodul.aliasPrefix: null
    pdir_maklermodul.alias: 'freitexte/objekttitel'
    pdir_maklermodul.aliasSuffix: 'verwaltung_techn/objektnr_extern'
    pdir_maklermodul.validAliasCharacters: '0-9a-z'
    pdir_maklermodul.aliasDelimiter: '-'
    pdir_maklermodul.aliasLocale: 'de'

This generates the alias from the property title and the external property number and only allows ASCII digits and lowercase letters.

The URL could then look like this:

example.org/details/expose/traumhafte-grosszugig-und-hochwertig-sanierte-wohnung-mit-erholungswert-14246.html

Example with the property title only:

parameters:
    pdir_maklermodul.aliasPrefix: null
    pdir_maklermodul.alias: 'freitexte/objekttitel'
    pdir_maklermodul.aliasSuffix: null
    pdir_maklermodul.validAliasCharacters: '0-9a-z'
    pdir_maklermodul.aliasDelimiter: '-'
    pdir_maklermodul.aliasLocale: 'de'

The URL could then look like this:

example.org/details/expose/traumhafte-grosszugig-und-hochwertig-sanierte-wohnung-mit-erholungswert.html

Allowed characters for the alias

- Unicode digits and lowercase letters -> '\pN\p{Ll}'
- Unicode digits and letters -> '\pN\pL'
- ASCII digits and lowercase letters -> '0-9a-z'
- ASCII digits and letters -> '0-9a-zA-Z'

For technical reasons, the import currently cannot use the settings of the root page.

Alias delimiter (aliasDelimiter)

pdir_maklermodul.aliasDelimiter: '-'
Result: example.org/details/expose/traumhafte-grosszugig-und-hochwertig-sanierte-wohnung-mit-erholungswert.html

pdir_maklermodul.aliasDelimiter: '_'
Result: example.org/details/expose/traumhafte_grosszugig_und_hochwertig_sanierte_wohnung_mit_erholungswert.html

Locale-specific alias (aliasLocale)

pdir_maklermodul.aliasLocale: 'en'
Result: example.org/details/expose/traumhafte-grosszugig-und-hochwertig-sanierte-wohnung-mit-erholungswert.html

pdir_maklermodul.aliasLocale: 'de'
Result: example.org/details/expose/traumhafte-großzügig-und-hochwertig-sanierte-wohnung-mit-erholungswert.html

Import

Uploading the files with the property data

You can import your own property data or the demo data. You can only import your own property data with the full version.

If you want to download the demo data first, select Maklermodul Setup under PDIR APPS in the left navigation and click the button Download demo data. You then find the demo data in the file manager in the folder maklermodul/data.

Importing your own property data

After the installation there is a new directory maklermodul under the back end module System → File manager. This folder must contain 3 more directories with the following names: data, org, upload.

To upload the zip file, click File upload. The view changes; click the icon Paste into this folder to the right of upload. Under File upload, click the button Choose files. Select the zip file and click Open at the bottom right. Then click the button Upload files.

The file should now be in the directory ‘upload’.

Notes

Uploaded file is too large:

If the file cannot be imported because of its size, select Settings in the left navigation and increase the value for Maximum upload file size in the File uploads tab.

jQuery is not loaded:

Make sure jQuery is loaded. To add it, select Themes in the left navigation and then the icon for Page layouts. When editing the layout, you can load jQuery in the jQuery tab.

Changing the files folder or keeping the file after the import:

If you have changed the files directory or want to keep the imported file after the import, create a file named import.ini in the folder maklermodul in the file manager. The imported file is then stored in the folder maklermodul/org after the import.

The file could look as follows. With the option keep-source you set whether the imported file is kept after the import.

import-source="files/maklermodul/upload"
import-target="files/maklermodul/data"
keep-source=true

Starting the import

To run the import manually, start it in the back end module Maklermodul Setup by clicking the button Run import.

Setting up a cron job

Since Contao 5, recurring tasks should no longer be implemented with the Contao cron ($GLOBALS['TL_CRON']). Instead, set up a real cron job on the server. How to configure it depends on your hosting provider.

Option 1: run a CLI command (recommended)

Many hosting providers allow running a console command directly as a cron job. In this case use the following command:

php vendor/bin/contao-console maklermodul:import && php vendor/bin/contao-console maklermodul:index

Depending on the hosting environment, the PHP command may differ, for example:

php
php84
php8.4
/usr/bin/php
/usr/bin/php8.4-cli

Your hosting provider tells you the exact name.

Option 2: call a PHP file

If your host doesn’t support CLI commands as cron jobs, create a PHP file instead (e.g. in the public directory) that runs the required console commands. The cron job then calls this file regularly.

maklermodul.import.php

<?php

$command = sprintf(
    'php %1$s/vendor/bin/contao-console maklermodul:import && php %1$s/vendor/bin/contao-console maklermodul:index',
    dirname(__DIR__)
);

exec($command, $output, $result);

exit($result);

Here, too, php is only an example. Depending on the hosting provider, adjust this part to the available PHP CLI version.

We recommend running the cron job at a regular interval (e.g. every half hour). The right interval depends on how often new data should be imported.

Notes on hosting providers

All-Inkl

At All-Inkl you set up the cron job in the KAS under Tools → Cronjobs. With Cronjob anlegen (create cron job) you select the PHP file and set the execution interval.

Poor man’s cron

Create the file app/Resources/contao/config/config.php if it doesn’t exist and add the following content. Then rebuild the cache in the Contao Manager.

Note

Since Contao 4.9, place config.php in contao/config/config.php.

<?php

/**
 * Maklermodul Cron
 *
 * see documentation for details
 * https://docs.maklermodul.de/import.html
 *
 */
$GLOBALS['TL_CRON']['hourly'][] = array('Pdir\MaklermodulSyncBundle\Module\Sync', 'estateImport');
$GLOBALS['TL_CRON']['hourly'][] = array('Pdir\MaklermodulSyncBundle\Module\Sync', 'estateIndex');

Note: these cron jobs only run when the website is actually visited.

Possible options for the execution frequency:

$GLOBALS['TL_CRON']['monthly']
$GLOBALS['TL_CRON']['weekly']
$GLOBALS['TL_CRON']['daily']
$GLOBALS['TL_CRON']['hourly']
$GLOBALS['TL_CRON']['minutely']

More information about cron jobs in Contao:

https://docs.contao.org/dev/framework/cron/

Run the poor man’s cron regularly: (depending on the hosting provider, this can be set up in its interface)

https://example.org/_contao/cron

Please note that in the settings under Front end settings the checkbox Disable the command scheduler must not be enabled for the poor man’s cron to work.

Real cron job on the server

22 minutes past every full hour (for hourly jobs)

22 * * * * cd /path/to/contao && php vendor/bin/contao-console maklermodul:import && php vendor/bin/contao-console maklermodul:index

Running it manually on the console

php vendor/bin/contao-console maklermodul:import
php vendor/bin/contao-console maklermodul:index

Immobilienscout24 import

Installation

You need the pdir/maklermodul-immobilienscout24-bundle. The bundle must be installed in addition to the Sync Bundle.

Setup

You need your personal access data for the Immobilienscout24 API. You find out how to get it here (in German).

Enter your personal access data (consumerKey, consumerSecret, tokenKey and tokenSecret) in the Contao back end under PDIR APPS -> Immobilienscout24 Import. Select “api” as the type and “immobilienscout24” as the model.

Cron

Recommendation: set up a real cron job with the Contao console.

php vendor/bin/contao-console maklermodul:immoscout:import
php vendor/bin/contao-console maklermodul:index

Alternatively, use a poor man’s cron (runs when the Contao website is visited).

Activate the poor man’s cron in the cron job settings.

Customization

Topics

List view

Topics

Fields and filters

As you have probably noticed, two fields in the list view module were skipped during setup: Displayed fields and Filter. If these two fields are empty, the default configuration applies, whose effect you currently see when you open the list view.

As the name Displayed fields suggests, this field controls which data is provided in the list view. Suppose you only want to show the first property image together with the title; then enter the following in the field Displayed fields:

freitexte.objekttitel
anhaenge.anhang.#1.@gruppe
anhaenge.anhang.#1.daten.pfad
anhaenge.anhang.#1.format
anhaenge.anhang.#1.anhangtitel

Save the module settings, go to the menu item Maklermodul Setup in the left navigation and build the index with the button Build index. The index must be rebuilt after every change to the fields Displayed fields and Filter, otherwise the changes have no effect.

If you now reload the page with your list view, you will notice that the filter has disappeared. This is because the default settings no longer apply as soon as something has been entered in the field Displayed fields.

To let your customers filter by type of use, type of marketing and location, add the following lines to both fields:

objektkategorie.nutzungsart.@WAZ
objektkategorie.nutzungsart.@GEWERBE
objektkategorie.nutzungsart.@ANLAGE
objektkategorie.nutzungsart.@WOHNEN
objektkategorie.vermarktungsart.@MIETE_PACHT
objektkategorie.vermarktungsart.@LEASING
objektkategorie.vermarktungsart.@KAUF
objektkategorie.vermarktungsart.@ERBPACHT
geo.plz
geo.ort

The two fields would now look like this:

Save the module settings and rebuild the index.

You should now find filter buttons for the fields above in the list view. A button is generated for each value that occurs in at least one property.

You find further settings on the page List view configuration.

Customizing the select fields

To change the label Alle (all) in the select fields, adjust the template makler_list_filter_select.html5. You can create the template in the back end under the menu item Templates.

Replace the following line …

<option value="-1">Alle</option>

… with this line:

<option value="-1"><?= $filter['name'] ?></option>

After saving the change, the website should show the field name instead of Alle.

Settings

Sorting

You can sort the properties in the list view of your website by a specific field. The field must be listed in the module under displayed fields and in the template. Then rebuild the index.

Under Field selection you choose the field to sort by.

Under Field type you select the field type (number, floating point number or text).

Under Sorting you choose ascending or descending order.

Conditions

The field Conditions narrows down the results by certain criteria. If, for example, you want to show all two-room apartments in the town of Meißen, add the two lines from the image. Add only one condition per line and do NOT add a comma at the end of a line. Mind upper and lower case! For the changes to take effect, rebuild the index.

More examples:

Location NOT EQUAL Leipzig

geo.ort!=Leipzig

Property address released

objektadresse_freigegeben=true

Property title contains “ruhig gelegen” (only available in Maklermodul Bundle >= 2.2.0 and Maklermodul Sync Bundle >= 2.2.0)

freitexte.objekttitel=%ruhig gelegen%

Marketing type rent/lease

objektkategorie.vermarktungsart.@MIETE_PACHT=true

Marketing type purchase

objektkategorie.vermarktungsart.@KAUF=true

Image settings

Under image size, select the image mode. The options are:

Proportional: The longer side of the image is fitted to the bounding box.
Fit the box: The shorter side of the image is fitted to the bounding box.
Important part: Defines an important area that is used as the image section.
Left | Top: Image section at the top left.
Center | Top: Image section at the top center.
Right | Top: Image section at the top right.
Left | Center: Image section at the center left.
Center | Center: Image section in the center.
Right | Center: Image section at the center right.
Left | Bottom: Image section at the bottom left.
Center | Bottom: Image section at the bottom center.
Right | Bottom: Image section at the bottom right.

In the first text field next to the image mode you enter the width in pixels. In the next text field you enter the height in pixels.

You can also set your own placeholder image in case a property in the list view has no image. If no placeholder image is selected and the property has no image, a placeholder image provided by the module is shown.

Pagination

Under Number of properties you choose how many properties are shown per page.

Under Number of links you choose how many links the pagination shows. For this, enable the option Use Isotope.

Example - Use Isotope enabled:

Example - Use Isotope not enabled:

Filter only

If you enable Filter only in the options, all filter results are hidden. You then have to specify a list view to redirect to when the user clicks the button Search properties. The filter settings are passed on.

More options

With Show in sitemap navigation, the properties of this list view are also shown in the sitemap navigation. The template nav_makler_sitemap must be selected in the template settings of the sitemap navigation.

Debug shows all available field keys that can be used.

Include CSS includes the module’s own CSS in the template.

Include JavaScript includes the module’s own JavaScript in the template.

Enabling Backwards compatibility means that the old template functions are used in the list view (earlier versions <1.4.0). Rebuild the index after changing this.

Property attributes

You can define how property attributes are displayed in the filter of the list view.

You control the type, i.e. how each property attribute is output, by creating a file named data.filter.ini in the folder maklermodul in the file manager. Then rebuild the index on the Maklermodul Setup page.

Example content of data.filter.ini

flaechen.wohnflaeche = 'cssMapRange10'

The living space is then output in steps of 10.

The following output types are available

General types:

cssMapDefault output without change
cssMapBoolean output as a true or false button
cssMapNumber output of prices in the format 12.000,00

Ranges

cssMapRange1
cssMapRange3
cssMapRange10
cssMapRange50
cssMapRange100
cssMapRange200
cssMapRange1000
cssMapRange10000
cssMapRange50000
cssMapRange100000

Available since version 1.2.0 build 16

cssMapFloor1
cssMapFloor3
cssMapFloor10
cssMapFloor50
cssMapFloor100
cssMapFloor200
cssMapFloor1000
cssMapFloor10000
cssMapFloor50000
cssMapFloor100000

Detail view

Topics

Integrating Google Maps

Follow these steps to show a Google Maps map on your website.

You can also show a privacy-compliant Google Maps map. Users first see a notice that Google Maps is used and have to confirm with a click that the map may be shown. This prevents data transfer to Google if users don’t consent.

1 / Install the Google Maps extension:

To install the extension, follow these steps:

Open the Contao Manager and log in
Select Install packages
Enter “dlh_googlemaps” in the search field
Click Add package on the extension delahaye/dlh_googlemaps and then Apply changes
Open the install tool and update the database

2 / Enter the API key in the site structure

In the site structure, enter the Google Maps API key in the website root of your site. You find the setting in the Google Maps tab. All information on creating the API key is on the Google Maps APIs website.

3 / Create a Google Maps map:

After a successful installation you should see a new menu item Google Maps under Content in the left menu. Click it and create a new map with the button “New Google Map”. You only need to enter a title; you can keep all other settings or change them as you like. Address and geo coordinates are set automatically by the real estate module.

4 / Create a module:

Then click Themes under Layout in the left menu. Click the gear icon to edit the front end modules of the theme. Now create a new module.

Give your module a meaningful title. Select Google Map as the module type. You can also use the search in the select field. In the map data tab, select the map you just created.

In the template settings tab, select the template mod_dlh_googlemaps_default_mm.

Privacy notice:

A checkbox enables or disables the privacy notice, so that data is only sent to Google once the user explicitly consents. If you leave the privacy notice field empty, the default text of the module is used. Alternatively, you can enter your own text or use our example below.

If you paste the following code in the source code view (icon <>), the privacy notice is shown on your website as in the image below.

<h3>This website uses Google Maps</h3>
<p>Click here to activate it permanently. I agree that data will be transferred to Google when using it. Note: You can revoke your consent at any time for the future by deleting the cookie dlh_googlemaps. You find detailed information on how we handle user data in our privacy policy.</p>
<p><a class="btn" href="#">Activate Google Maps</a></p>

5 / Adjusting the real estate module template

Select Templates under Layout in the left menu and edit your detail view template (makler_details_extended or makler_details_simple). If the template is not in this folder yet, create it with the button “New template”.

In the template, add the following code snippet where the map should be shown. Replace ID with the ID of the module you created (you see it at the very top when editing the module).

{{insert_module::ID}}

If the map should only be shown when the address is actually released, put the code snippet inside the following if statement.

Example of including the Google Maps map:

<?php if($this->estate->renderer('verwaltung_objekt.objektadresse_freigeben')->asText()->value(true) == true && $this->showMap == 1): ?>
    <h3>Karte</h3>
    <div class="address">
        <h4>Objektanschrift</h4>
        <?php $this->estate->renderer('geo.strasse')->asText()->value() ?> <?php $this->estate->renderer('geo.hausnummer')->asText()->value() ?><br />
        <?php $this->estate->renderer('geo.plz')->asText()->value() ?> <?php $this->estate->renderer('geo.ort')->asText()->value() ?>
    </div>

    {{insert_module::48}}

    <script>
        $(document).ready( function() {
            $("#confirm-googlemaps").click( function() {
                setMap();
            });

            $("#confirm-googlemaps .btn").click( function() {
                $("#confirm-googlemaps").trigger("click");
                return false;
            });

            var mapsCookie = "<?= \Input::cookie('dlh_googlemaps') ?>";
            if(mapsCookie != "" || $(".dlh_googlemap > div").attr("id") != "confirm-googlemaps") {
                setMap();
            }

            function setMap() {
                setTimeout( function() {
                    var geocoder = new google.maps.Geocoder();
                    var lat; var lng;
                    geocodeAddress(geocoder);
                },500);
            }

            function geocodeAddress(geocoder, resultsMap) {
                var address = "<?php $this->estate->renderer('geo.strasse')->asText()->value() ?>";
                address = address + " <?php $this->estate->renderer('geo.hausnummer')->asText()->value() ?>";
                address = address + ", <?php $this->estate->renderer('geo.ort')->asText()->value() ?>";
                geocoder.geocode({'address': address}, function(results, status) {
                    if (status === google.maps.GeocoderStatus.OK) {
                        lat = results[0].geometry.location.lat();
                        lng = results[0].geometry.location.lng();
                        setCenter(lat, lng);
                        setMarker(lat, lng);
                    }
                });
            }

            function setCenter(lat, lng) {
                gmap1.setCenter(new google.maps.LatLng(lat, lng));
            }

            function setMarker(lat, lng) {
                var gmap1_marker = new google.maps.Marker({
                    position: new google.maps.LatLng(lat, lng),
                    map: gmap1,
                    zIndex: 1
                });
            }
        });
    </script>
<?php endif; ?>

Optional: CSS adjustments

To make CSS adjustments, edit your CSS file. If you don’t have one yet, create a CSS file, e.g. style.css, and select it in the page layout under external stylesheets.

Code snippets

Below are some code snippets that show how to adjust colors, widths and heights.

Change the height of the Google Maps map:

.mod_dlh_googlemaps, .dlh_googlemap {
    height: 600px;
}

Change the privacy notice:

#confirm-googlemaps {
    background: #fff;
    color: #000;
    width: 50%;
}

Change the h3 headline:

#confirm-googlemaps h3 {
    background: #f2f2f2;
    color: #b91e1e;
}

Change the button:

#confirm-googlemaps a.btn {
    background: #d45a5a;
    color: #fff;
}

Change the button hover:

#confirm-googlemaps a.btn:hover {
    background: #b91e1e;
    color: #fff;
}

Property inquiry form

Including a simple property inquiry form

Create a new form named “Objektanfrage” (property inquiry) with the form generator. Add the fields and descriptions you need, and don’t forget a field for the property number, ideally as a hidden field.

Passing the property number

With a little JavaScript we can pass the property number to the input field. You can add the script, for example, to the detail view template (makler_details_simple or makler_details_extended).

Passing the property number to the input field with the ID “ctrl_17” with jQuery

<script>
if(typeof jQuery('.verwaltung-techn-objektnr-extern') != 'undefined')
  jQuery('#ctrl_17').val(jQuery('.verwaltung-techn-objektnr-extern .value-text').html());
</script>

Passing the property number to the input field with the ID “ctrl_17” with MooTools

<script>
if(typeof $('.verwaltung-techn-objektnr-extern') != 'undefined')
    $('#ctrl_17').set('value', $('.verwaltung-techn-objektnr-extern .value-text')[0].get('text'));
</script>

This is what the finished form can look like

Form with OpenImmo feedback XML

This guide shows how to set up a property inquiry form with OpenImmo feedback XML in Contao 4 using the real estate module and the Notification Center. The goal is that property inquiries do not simply land in the inbox of the real estate software, but are shown under “Objektanfragen” (property inquiries).

The following steps assume that, in addition to the real estate module, the Notification Center is installed and the property list and the exposé are set up.

Create the property inquiry form

To set up the property inquiry form, create a new form in the form generator and name it, for example, “Anfrage Objekt”. You should also select a redirect page to which visitors are sent after submitting the form. We will create the notification later, so leave this field empty for now.

Create the form fields

Now create the fields in the form.

For the property number you can create a normal text field or a hidden field. The field name must be oobj_id.

The field names of the other fields must be exactly as in the following screenshot or the XML example after it. You don’t have to create all fields that appear in the XML example, though.

XML example:

<openimmo_feedback>
	<sender>
		<name/>
		<openimmo_anid/>
		<datum>01.01.2010</datum>
		<makler_id>12345</makler_id>
	</sender>
	<objekt>
		<portal_unique_id/>
		<portal_obj_id/>
		<anbieter_id/>
		<oobj_id>Objektnummer</oobj_id>
		<zusatz_refnr/>
		<expose_url>http:www.domain.de/expose?ID=12345</expose_url>
		<vermarktungsart>Kauf</vermarktungsart>
		<bezeichnung>Kurzbeschreibung</bezeichnung>
		<etage/>
		<whg_nr/>
		<strasse>Objekt_Strasse</strasse>
		<ort>Objekt_Ort</ort>
		<preis>Objektpreis</preis>
		<gebot/>
		<wae/>
		<interessent>
			<int_id/>
			<anrede>Herr</anrede>
			<vorname>Vorname_Interessent</vorname>
			<nachname>Nachname_Interessent</nachname>
			<firma>Firma_Interessent</firma>
			<strasse>Strasse_Interessent</strasse>
			<postfach/>
			<plz>PLZ</plz>
			<ort>Ort_Interessent</ort>
			<tel>01234/1234567</tel>
			<fax>01224/6545223</fax>
			<mobil/>
			<email>email@domain.de</email>
			<bevorzugt>EMAIL, POST oder FAX</bevorzugt>
			<wunsch>BESICHTIGUNG oder RÜCKRUF</wunsch>
			<anfrage>Anfrage-Text </anfrage>
		</interessent>
	</objekt>
</openimmo_feedback>

Place the form and fill in the property number

You can then add the form to the article of the exposé by selecting the element type Form and the corresponding form.

To make sure the form field for the property number gets the right value, we need a small piece of jQuery code. You can put the following code, for example, in a separate JavaScript file or add it in the layout under Custom JavaScript code.

<script>
jQuery(document).ready(function($) {
	if(typeof $('.verwaltung_techn-objektnr_extern') != 'undefined') {
		$('input[name="oobj_id"]').val( $('.verwaltung_techn-objektnr_extern .value-text').html() );
	}
});
</script>

This is what the finished property inquiry form could look like:

Create the OpenImmo feedback XML

Next, create a file named openimmo_feedback.xml in the file manager. It must look like the following example.

<?xml version="1.0" encoding="ISO-8859-1"?>
<openimmo_feedback>    
	<sender>        
		<name>Ihre Makler 24</name>        
		<datum>16.03.2020</datum>        
		<makler_id>5038545</makler_id>    
	</sender>    
	<objekt>        
		<oobj_id>##form_oobj_id##</oobj_id>        
		<interessent>            
			<anrede>##form_anrede##</anrede>            
			<vorname>##form_vorname##</vorname>            
			<nachname>##form_nachname##</nachname>            
			<strasse>##form_strasse##</strasse>            
			<plz>##form_plz##</plz>            
			<ort>##form_ort##</ort>            
			<tel>##form_tel##</tel>            
			<fax>##form_fax##</fax>            
			<email>##form_email##</email>            
			<bevorzugt>##form_bevorzugt##</bevorzugt>            
			<wunsch>##form_wunsch##</wunsch>            
			<anfrage>##form_anfrage##</anfrage>        
		</interessent>    
	</objekt>
</openimmo_feedback>

Create the notification

Create a notification:

For the form to be sent, create a new notification under Notification Center - Notifications and select Form submission as the notification type.

Create a message:

Then create a new message and select the gateway. If no gateway exists yet, go to Gateways in the left navigation and create one. There you can also enter SMTP data by ticking Override SMTP settings. Don’t forget to tick the checkbox to publish the message.

Create a language:

Once the gateway is selected in the message, you can add new languages with the button Manage languages. A new window opens where you can create a new language with the button at the top right.

The following steps are required (see the following screenshot):

Select the language German and enable the fallback language checkbox
Fill in the metadata (sender name, sender email, recipient)
Fill in the content
- Enter the email subject
- Select the mode HTML and text
- In raw text, enter e.g. ##raw_data##
- Fill in the HTML (example at the end of this page)
Under Attachments - Attachments from templates, select the openimmo_feedback.xml you just created

You could, for example, insert the following HTML code in the HTML field. Click the icon <> to open the source code editor and paste the HTML code. The example email is in German, as the OpenImmo format is mainly used in Germany.

<!-- BODY -->
<table class="body-wrap" style="font-family: 'Helvetica Neue', 'Helvetica', Helvetica, Arial, sans-serif; width: 100%; background: #f5f5f5;">
<tbody>
	<tr>
		<td class="container" style="margin: 0 auto!important; display: block!important; max-width: 600px;" align="" bgcolor="#FFFFFF">
			<h1 style="margin: 20px 15px; padding: 10px; line-height: 1.1; margin-bottom: 15px; color: #000; font-size: 14px; background: #f2f2f2; font-weight: bold;">Objektanfrage</h1>
			<!-- content -->
			<div class="content" style="padding: 5px 15px;">
				<h2 style="margin: 0; padding: 5px 10px; line-height: 1.1; margin-bottom: 15px; color: #fff; font-size: 14px; background: #00a0e1;">Daten zum Objekt</h2>
				<table class="greybox obj-daten" style="margin: 0; padding: 15px; background: #f2f2f2; margin-bottom: 20px; width: 100%;" bgcolor="">
				<tbody>
					<tr style="margin: 0; padding: 0;">
						<td style="margin: 0; padding: 0;">
							<p style="margin: 0; padding: 0; color: #000; margin-bottom: 5px; font-weight: normal; font-size: 14px; line-height: 1.6;"><label style="margin: 0; padding: 0; font-weight: bold; color: #000; display: inline-block;">Objekt-Nr:</label> ##form_oobj_id##</p>
						</td>
					</tr>
				</tbody>
				</table>
				<h2 style="margin: 0; padding: 5px 10px; line-height: 1.1; margin-bottom: 15px; color: #fff; font-size: 14px; background: #00a0e1;">Anmerkungen/Fragen</h2>
				<table class="greybox" style="margin: 0; padding: 15px; background: #f2f2f2; margin-bottom: 20px; width: 100%;" bgcolor="">
				<tbody>
					<tr style="margin: 0; padding: 0;">
						<td style="margin: 0; padding: 0;">
							<p style="margin: 0; padding: 0; color: #000; margin-bottom: 5px; font-weight: normal; font-size: 14px; line-height: 1.6;">##form_anfrage##</p>
					</td>
					</tr>
				</tbody>
				</table>
				<h2 style="margin: 0; padding: 5px 10px; line-height: 1.1; margin-bottom: 15px; color: #fff; font-size: 14px; background: #00a0e1;">Ihre Angaben</h2>
				<table class="greybox" style="margin: 0; padding: 15px; background: #f2f2f2; margin-bottom: 20px; width: 100%;" bgcolor="">
				<tbody>
					<tr style="margin: 0; padding: 0;">
						<td style="margin: 0; padding: 0;">
							<p style="margin: 0; padding: 0; color: #000; margin-bottom: 5px; font-weight: normal; font-size: 14px; line-height: 1.6;">
							{if form_firma!=""} <strong>Firma:</strong> ##form_firma##<br>{endif}
							<strong>Name:</strong> ##form_vorname## ##form_nachname##<br>
							<strong>Straße:</strong> ##form_strasse##<br>
							<strong>PLZ/Ort:</strong>##form_plz## ##form_ort##<br>
							<strong>E-Mail:</strong> ##form_email##<br>
							<strong>Tel:</strong> ##form_tel##<br>
							{if form_fax!=""}<strong>Fax:</strong> ##form_fax##<br>{endif}
							{if form_wunsch!=""}Ich bitte um einen {if form_wunsch=="BESICHTIGUNG"}Besichtigungstermin{endif}{if form_wunsch=="RÜCKRUF"}Rückruf{endif}<br>{endif}
							{if form_bevorzugt!=""}Ich bitte um Übersendung eines Exposés per {if form_bevorzugt=="EMAIL"}E-Mail{endif}{if form_bevorzugt=="POST"}Post{endif}{if form_bevorzugt=="FAX"}Fax{endif}<br>{endif} 
							{if form_AGBs!=""}Ich bin damit einverstanden, dass XXX mich kontaktiert (telefonisch, per Post oder Email) und meine Daten für interne Zwecke speichert. Ich habe die AGB und die Datenschutzerklärung gelesen. Mit den AGB und der Datenschutzerklärung von XXX erkläre ich mich hiermit ausdrücklich einverstanden.{endif}
							</p>
						</td>
					</tr>
				</tbody>
				</table>
			</div>
			<!-- /content -->
		</td>
	</tr>
</tbody>
</table>
<!-- /BODY -->

If everything has been set up according to this guide, the OpenImmo feedback XML form should now work. :)

Displaying images

Here you find various code snippets that you can add to the detail view template to display images.

Output all images:

<?php foreach ($this->estate->attachments()->startAt(0) as $attachment) : ?>
    <?php $attachment->size(600,350)->render() ?>
<?php endforeach; ?>

This snippet outputs all attachments of the group BILD. With startAt() you can specify any start position. With size() you specify the image width and height.

Output a specific number of images:

<?php foreach ($this->estate->attachments()->range(0,3) as $attachment) : ?>
    <?php $attachment->size(600,350)->render() ?>
<?php endforeach; ?>

With range() you specify a start position (starting at 0) and the length. For example, range(0,3) outputs 3 images starting at position 0.

Output images of one or more groups:

<?php foreach ($this->estate->attachments()->startAt(0) as $attachment) : ?>
    <?php $attachment->group("BILD,GRUNDRISS,AUSSENANSICHTEN,INNENANSICHTEN,PANORAMA")->size(600,350)->render() ?>
<?php endforeach; ?>

With group() you specify attachments of a certain group. Enter several groups comma-separated.

Header image with headline

1 / Create a module:

Under Themes and Modules in the theme of your website, create a new module.

Select the module type “MaklerModul Kopfbild” (header image). If the property title should be shown as the headline, select the option “Show headline”. Alternatively, you can enter your own headline that replaces the property title in the header image (the option “Show headline” must be selected). The header image can be shown either as a normal image or as a background image.

You can also set your own placeholder image for the header image in case a property has no image. If no placeholder image is selected and the property has no image, a placeholder image provided by the module is shown.

2 / Create a content element:

You can also create the header image as a content element in an article. Select MaklerModul Kopfbild under pdirMaklermodul as the element type. The content element offers exactly the same settings as the module.

3 / This is what the finished header image can look like:

Additional fields

You can of course also use custom fields.

Simply create a file named data.mapping.php in the folder files/maklermodul.

Below you see an example excerpt from the XML and examples you can add to data.mapping.php to illustrate the mapping.

The file must always end with return $userMapping;! The changes only take effect after the properties have been imported again!

Excerpt from the XML:

<objektkategorie>
    <nutzungsart WOHNEN="false" GEWERBE="true"/>
    <vermarktungsart KAUF="false" MIETE_PACHT="true"/>
    <objektart>
        <buero_praxen buero_typ="PRAXISFLAECHE"/>
    </objektart>
</objektkategorie>

Example: Map all offices/practices to commercial properties

Add the following to data.mapping.php to map all offices/practices, regardless of their office type, to commercial properties (“Gewerbeimmobilien”).

<?php

$userMapping["objektkategorie/objektart/buero_praxen/@buero_typ"] = array('objektkategorie.objektart', 'Gewerbeimmobilien');

return $userMapping;

Example: Use the value of the office type

If the value of buero_typ (PRAXISFLAECHE in the example) should be passed on, add the following to data.mapping.php.

<?php

$userMapping["objektkategorie/objektart/buero_praxen/@buero_typ"] = 'objektkategorie.objektart.buero_praxen';

return $userMapping;

Example: Map a specific office type to a custom value

If the German term Praxisfläche should be passed instead of PRAXISFLAECHE, add the following to data.mapping.php.

<?php

$userMapping["objektkategorie/objektart/buero_praxen[@buero_typ='PRAXISFLAECHE']"] = array('objektkategorie.objektart.buero_praxen','Praxisfläche');

return $userMapping;

Example: Map the property category with all property types:

<?php

$userMapping["objektkategorie/objektart/zimmer"] = array('objektkategorie.objektart', 'Zimmer');
$userMapping["objektkategorie/objektart/wohnung"] = array('objektkategorie.objektart', 'Wohnung');
$userMapping["objektkategorie/objektart/haus"] = array('objektkategorie.objektart', 'Haus');
$userMapping["objektkategorie/objektart/grundstueck"] = array('objektkategorie.objektart', 'Grundstück');
$userMapping["objektkategorie/objektart/buero_praxen"] = array('objektkategorie.objektart', 'Gewerbeimmobilien');
$userMapping["objektkategorie/objektart/einzelhandel"] = array('objektkategorie.objektart', 'Gewerbeimmobilien');
$userMapping["objektkategorie/objektart/gastgewerbe"] = array('objektkategorie.objektart', 'Gastgewerbe');
$userMapping["objektkategorie/objektart/hallen_lager_prod"] = array('objektkategorie.objektart', 'Gewerbeimmobilien');
$userMapping["objektkategorie/objektart/land_und_forstwirtschaft"] = array('objektkategorie.objektart', 'Land- & Forstwirtschaft');
$userMapping["objektkategorie/objektart/parken"] = array('objektkategorie.objektart', 'Parken');
$userMapping["objektkategorie/objektart/sonstige"] = array('objektkategorie.objektart', 'Sonstige');
$userMapping["objektkategorie/objektart/freizeitimmobilie_gewerblich"] = array('objektkategorie.objektart', 'Freizeitimmobilie, Gewerblich');
$userMapping["objektkategorie/objektart/zinshaus_renditeobjekt"] = array('objektkategorie.objektart', 'Zinshaus, Renditeobjekt');

return $userMapping;

When you import the existing properties again, a filter objektkategorie.objektart is available.

Example: Map a custom field

<?php
$userMapping["geo/user_defined_simplefield[@feldname='Straße freigeben']"] = 'strasse_freigeben';
return $userMapping;

In the list view module you then simply enter strasse_freigeben.

Example: Rename the marketing type

$userMapping["objektkategorie/vermarktungsart/@KAUF[.='true']"] = ['objektkategorie.vermarktungsart', 'Kauf'];
$userMapping["objektkategorie/vermarktungsart/@MIETE_PACHT[.='true']"] = ['objektkategorie.vermarktungsart', 'Miete'];

$userMapping["objektkategorie/vermarktungsart/@KAUF[.='1']"] = ['objektkategorie.vermarktungsart', 'Kauf'];
$userMapping["objektkategorie/vermarktungsart/@MIETE_PACHT[.='1']"] = ['objektkategorie.vermarktungsart', 'Miete'];

In the list view module you then simply enter objektkategorie.vermarktungsart.

Search & replace

Since version 2.5.0 of the Maklermodul Sync Bundle you can replace letters and characters. For example, add the following to data.mapping.php to remove brackets, slashes and spaces from the property number.

<?php

$userMapping['verwaltung_techn/objektnr_extern'] = ['sortierung', ['search' => '(,), ,/', 'replace' => ',,,']];

return $userMapping;

Before: 21 (1/16)
After: 21116

When you import the existing properties again, a filter sortierung is available.

If the original field should not be imported, add the option 'excludeOriginal' => true, for example as follows:

<?php

$userMapping['verwaltung_techn/objektnr_extern'] = ['sortierung', ['search' => '(,), ,/', 'replace' => ',,,', 'excludeOriginal' => true]];

return $userMapping;

Translations

You can easily change the labels of fields in the language files.

Use langconfig.php (in system/config) or create a file default.php in contao/languages/de (since Contao 4.9; use the folder of the respective language, e.g. contao/languages/en).

For example:

$GLOBALS['TL_LANG']['makler_modul_mplus']['field_keys']['preise.gesamtbelastungbrutto'] = 'Mtl. Gesamtbelastung';

Then clear the cache in the Contao Manager and rebuild the index in the real estate module.

You find the available variables here: https://github.com/pdir/maklermodul-bundle/blob/master/src/Resources/contao/languages/de/makler_modul_mplus.php

Code snippets

Code snippets for small template adjustments

List view

Showing net cold rent/purchase price in German number format in the filter

Add the following source code to the end of the template makler_list.html5.

<script>
$(document).ready( function() {
    jQuery("#estate_filter_list .preise-nettokaltmiete .button, #estate_filter_list .preise-kaufpreis .button").each(function(i, obj) {
        jQuery(obj).html(filterGermanNumber(jQuery(obj).html()) + ' €');
    });

    //  helper functions
    function numberWithPoint(x) {
        return x.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ".");
    }
    function filterGermanNumber(x) {
        var parts = x.toString().split(".");
        parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ".");
        return parts.join(",");
    }
});
</script>

The prices should then be shown as follows.

Seo, Sitemap & Co.

The real estate module generates search engine friendly (SEF) URLs from the title and the property number. These URLs are also passed to the search index of Contao’s own search with every import.

Example

www.yourwebsite.com/expose/wow-klein-und-fein-gemuetlich-wohnen-mit-blick-in-ruhiger-lage-14266.html

Google Sitemap

Use Contao’s own XML sitemap function under Layout -> Site structure -> Website root -> XML sitemap to submit a sitemap to search engines. Please note that you have to specify the location of the sitemap.xml file in robots.txt.

Example

Sitemap: http://www.maklermodul.de/sitemap.xml
Alternatively, you can submit the sitemap address directly in Google Search Console.

User-agent: *
Disallow: /check/
Disallow: /contao/
Disallow: /system/
Disallow: /templates/
Disallow: /vendor/
Disallow: /share/index.php
Disallow: /build.xml
Disallow: /composer.json
Disallow: /composer.lock
Disallow: /README.md

Sitemap: http://www.maklermodul.de/sitemap.xml

Contao Sitemap

You can also create a sitemap for your visitors.

You find an example of how to set this up in Contao here: Creating a sitemap (in German). The real estate module also includes the template nav_makler_sitemap, which you can select if you want to show your properties in the sitemap.

Update

You can update the extension with the Contao Manager. Then open the install tool and update the database if necessary.

Tip

A database backup beforehand never hurts!

Themes

Contao themes

with layout templates for the real estate module

The following themes already include layout templates (CSS and templates) for the real estate module:

MATE theme

MATE is a Contao theme that supports Contao 4.x and uses the front end framework Materialize based on Material Design.

The theme is optimized for all devices and common browsers and already includes styles for all modules and elements of the Contao core. Header, footer and content as well as colors and layout can easily be adapted to your needs.

The MATE theme is available free of charge (with copyright notice) or as a paid version (without copyright notice).

There are 4 different color schemes with matching shades: green, blue, dark and yellow.

Demo: https://mate.pdir.de/immobilien.html Documentation: Setting up the real estate module in the theme Install for free or order a license: https://contao-themes.net/theme-detail/mate.html

Property list with select fields

Property list with buttons

Exposé (detail view)

ODD theme

ODD is a Contao theme developed for creative websites based on Contao 4.x.

The theme is optimized for all devices and common browsers and comes with plenty of useful elements for your website by default, such as content sliders, pricing boxes and of course all modules and elements of the Contao core in the creative ODD style and in three different color schemes.

Header, footer, slider, colors and layout and of course all content can easily be adapted to your requirements.

TOO “SLANTED”? You can also configure the slanted ODD elements to be straight ;)

There are 3 different color schemes with matching shades: green, gray and blue.

Demo: https://odd.contao-themes.net/immobilien.html Documentation: Setting up the real estate module in the theme Install for free or order a license: https://contao-themes.net/theme-detail/odd.html

Property list with select fields

Property list with buttons

Exposé (detail view)

NATURE theme

NATURE is a true all-rounder among Contao themes with a natural, simple look, developed for all kinds of websites based on Contao 4.x and the Bulma CSS framework.

The theme is optimized for all devices and common browsers and includes all modules and elements of the Contao core as well as plenty of useful extra elements, such as a fullpage slider, pricing boxes or sticky teaser boxes, in the purist, stylish NATURE style and in 6 different color schemes.

The theme layout (header, footer, elements, colors, etc.) is universal and flexible and can be adapted quickly and easily to your needs.

The theme also has a brand-new feature: an iOS dark mode that is easy on the eyes in the dark and also saves battery.

There are 6 different color schemes with matching shades (light/green, light/red, light/blue, dark/green, dark/red, dark/blue)

Demo: https://nature.contao-themes.net/immobilien.html Documentation: Setting up the real estate module in the theme Install for free or order a license: https://contao-themes.net/theme-detail/nature.html

Property list with select fields

Property list with buttons

Exposé (detail view)

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Real estate module for Contao

Notes

Which field keys are there?

That’s easy: every import creates a list of all field keys found. If you enable the checkbox Debug in the list view module, all these field keys are listed in the list view. From there you can copy and paste them.

Other extensions and themes

SWGlossar

SWGlossar

When using the extension SWGlossar by Sascha Weidner (Sioweb), the output of the list view may have problems.

The extension uses the hook “outputFrontendTemplate” to replace terms in the template. This can cause paths in the JavaScript of the real estate module to be output incorrectly.

One example is the term “Makler”. SWGlossar also replaces the alias “makler” in URLs and paths.

Use the extension’s function “Ignore these tags” to exclude certain paths from being changed.

SWGlossar: ignoring certain tags

Newsticker for Contao

The Newsticker bundle is a jQuery extension for Contao 4 based on jQuery Easy Ticker.

With the newsticker you can automatically scroll a number of elements in a list up or down. The elements are simply created as content elements.

Quick start

This documentation covers the following topics:

@seibtph 11 commits

@MDevster 2 commits

Requirements

Note

Newsticker is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Newsticker requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher.

Contao Manager

Newsticker is easy to install with the Contao Manager. Just search for newsticker-bundle.

The extension in the extension directory on contao.org.

Installation

Tip

Depending on the version of the Contao Manager you have installed, the button labels look slightly different. That is why there are two guides. You always find the version in the footer on the far left.

1 / Installation with Contao Manager 1.2.x:

Open the Contao Manager: https://www.your-domain.com/contao-manager.phar.php
Click Discover in the menu and search for Newsticker.
Add the package named Newsticker.
Click Packages in the menu and then Apply changes in the footer.
Then open the install tool and update the database.

2 / Installation with Contao Manager 1.1.x:

Open the Contao Manager: https://www.your-domain.com/contao-manager.phar.php
Click Search packages and search for Newsticker.
Add the package named Newsticker.
In the footer, click Check changes and then Apply changes.
Then open the install tool and update the database.

Configuration

Note

jQuery must be enabled in the page layout!

1 / Create the wrapper elements

First create one element of type Newsticker wrapper (start) and one of type Newsticker wrapper (end).

The element Newsticker wrapper (start) has several settings:

Setting	Description
Direction	Choose the direction in which the elements move (up / down).
Transition speed	Defines the transition speed. Values: slow, medium, fast or a value in milliseconds.
Interval	Number of milliseconds until the next change. Enter 0 to disable the automatic change.
Height	Adjusts the height of the newsticker. With auto the height adapts automatically. You can also set values such as 200px or 300px.
Number of visible elements	Defines how many elements are visible. Enter 0 to show all elements or a specific value such as 1, 2, 3 etc.
Pause on mouse over	Pauses the newsticker when the user moves the mouse over an element.
Show controls	Enable this option to show the controls (up, down, play, pause).

Create newsticker elements

Inside the wrapper elements, place an element of type Newsticker element. There you can set a headline, a text and an image. Under hyperlink settings you can also link the whole element.

In the back end, the structure of the elements should look roughly like this:

Examples

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Sharepoint for Contao

With this extension you can import files from your Sharepoint server into your Contao website and display them in a DataTables table.

All features:

Import files from your Sharepoint server into Contao
Display the data in a DataTables table
Sort by fields
Choose the columns to display
Show a search
Show a pagination for multiple pages
Set the number of entries per page
Set the select box entries per page
Combine several fields in one column
Custom adjustments via your own template
Load a language file based on your website settings

Quick start

This documentation covers the following topics:

Requirements

Note

Sharepoint for Contao is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Sharepoint requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher.

Contao Manager

Sharepoint is easy to install with the Contao Manager. Please use the upload function in the Contao Manager.

Installation

The Sharepoint Contao module is installed with the Upload packages function of the Contao Manager and is only available on request. The best way to contact us is the contact form.

1 / Open the Contao Manager

Open the Contao Manager: https://example.com/contao-manager.phar.php/#/packages

2 / Upload the zip file

Upload the current version of the sharepoint-bundle from your order email or your customer account with the Upload packages function of the Contao Manager and confirm the upload with Confirm uploads at the bottom of the manager. Then click Apply changes and the manager starts the installation.

3 / Update the database

Then open the install tool and update the database.

Configuration

1 / Create a source

First select Sharepoint under PDIR in the left navigation. Then create a new Sharepoint source with the button “Create a new Sharepoint list”.

Enter all list and Sharepoint settings (example: figure 1).

Figure 1: Create a new Sharepoint source (example data)

2 / Create a module

Create a new module of type “Sharepoint - DataTables” in your theme. In the module, select the source you just created under Data source and enter under Main node the node that contains the data in the file.

You can choose how many entries per page are shown, which values the select box offers for the entries per page, and whether a pagination or a search field is displayed.

In the table you can add new rows or columns with the plus icons (see figure 2). The first row of the table is always used as the header. In the second row you define which data from the imported file is shown in which column. Several entries in one column can be given comma-separated (without spaces). In the table they are then output separated by a space.

With the field “Sort by field” you can sort ascending or descending by a field name (as named in the 2nd row of the table). Under Expert settings you can assign an ID or a class. An ID is not required. If none is given, the module generates one itself.

Finally, include the module in an article.

Figure 2: Create a new table (example data)

Custom adjustments

You can make custom adjustments in the template mod_datatables.html5. Simply place the template in your templates folder. In the module you can then select a custom template under template settings.

In the second row of the table you can also leave columns at the beginning or end empty. They are ignored when the table is output. This lets you add your own columns in the template.

Cron job

By editing localconfig.php in system/config you can set up a cron job that runs at different intervals. Simply add one of the following lines to the file.

Every minute:

$GLOBALS['TL_CRON']['minutely'][] = ['Pdir\ContaoSharepointBundle\EventListener\CronListener', 'loadFile'];

Hourly:

$GLOBALS['TL_CRON']['hourly'][] = ['Pdir\ContaoSharepointBundle\EventListener\CronListener', 'loadFile'];

Daily:

$GLOBALS['TL_CRON']['daily'][] = ['Pdir\ContaoSharepointBundle\EventListener\CronListener', 'loadFile'];

Weekly:

$GLOBALS['TL_CRON']['weekly'][] = ['Pdir\ContaoSharepointBundle\EventListener\CronListener', 'loadFile'];

Monthly:

$GLOBALS['TL_CRON']['monthly'][] = ['Pdir\ContaoSharepointBundle\EventListener\CronListener', 'loadFile'];

Language file

The matching language file is loaded based on the Contao website settings. Language files that are not loaded can be specified in the template. You find all language files here: list of supported languages. Click a language to find the URL of its language file under CDN, which you then include in the template. To do so, change the following line in the JavaScript code of the template (in this example for Norwegian Bokmål):

"language": {
    "url": "//cdn.datatables.net/plug-ins/1.10.16/i18n/Norwegian-Bokmal.json"
},

More examples and documentation for the DataTables table plugin are available at datatables.net.

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Socialfeed for Contao

The Social Feed extension shows a feed from the most popular social networks. Facebook, Instagram, Twitter and LinkedIn are currently supported, more channels will follow. The posts are written directly to the database, created as news and can then be displayed on the website with the news list module.

On contao-themes.net you can support the further development of our themes and extensions by buying special packages or donating development hours.

Quick start

This documentation covers the following topics:

@MDevster 204 commits

@seibtph 169 commits

@rabauss 10 commits

@SGehle 2 commits

@fritzmg 2 commits

@contaoacademy 1 commits

@w3scout 1 commits

@bytehead 1 commits

@PaoloB 1 commits

@koertho 1 commits

Requirements

Note

Socialfeed is compatible with Contao 4.4 or 5.3 and higher.

Contao 4/5

Contao 4/5 requires a web server such as Apache or NGINX with PHP and MySQL support. Our Social Feed bundle requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 5.3 with PHP 8.2 or higher.

Contao Manager

Socialfeed is easy to install with the Contao Manager. Just search for social-feed-bundle.

The extension in the extension directory on contao.org.

Installation

Contao 4 or 5

With the Contao Manager

Open the Contao Manager and log in
In the Discover tab, enter “Social Feed” in the search field
Click Add and then Apply changes in the Packages tab
Update the database

After installing the module, you find the new menu item Social Feed Accounts under PDIR APPS in the left menu.

On this page you can create new accounts and edit their settings.

Configuration

Facebook

Setting up the Facebook stream

1 / Create a Facebook app

Create a new app with the button “Create app” at the top right.

In the App details dialog, enter a suitable app name.

Under use cases, in the Content management area, select the use case “Manage everything on your Page” and click Next.

In the Business step, choose the option “I don’t want to connect a business portfolio yet” and click Next again.

Skip the following Requirements step without selecting anything (just click Next). An overview appears – use “Go to dashboard” to switch to the app dashboard.

In the left navigation bar, open Use cases and click “Customize”.

Scroll down, find the permissions pages_read_engagement and pages_read_user_content and enable them with “Add”. These permissions are required to generate an access token in the Contao back end later.

In the left navigation bar under “Facebook Login for Business”, open Settings. In the field “Valid OAuth Redirect URIs”, enter the following URL: https://your-domain.com/_facebook/auth (Replace the domain with the one of your own website.)

Under App settings → Basic you find the App ID and the App secret – you will need both in the Contao back end later. In this area you also have to enter the App domain (the domain of your own website). Without it, the access token cannot be generated and an error message appears.

To read posts you must be an admin of the page, otherwise you first have to submit the Facebook app for app review.

2 / Create a news archive

Create a new news archive in the Contao back end into which the Facebook posts will be imported. A redirect page must be selected, although it is not relevant for the Social Feed bundle.

3 / Create an account and generate an access token

Under the menu item Social Feed Accounts, use the button Create a new Social Feed account to create a new account. Select Facebook as the type.

Facebook account: The name of the account as it appears in the URL
App ID: You find the App ID in your app under App settings -> Basic.
App secret: You find the App secret in your app under App settings -> Basic.
Access token: The access token is filled in automatically.
News archive: The archive into which the Facebook posts will be imported.
Cron job execution: Choose between different intervals for importing posts.
Import page posts only: If you select this option, only the page’s own posts are imported and no posts that users have written on its wall.
Last import: These fields are filled in automatically. You can empty them so that the cron job runs again.

After you click the button “Generate access token”, you are redirected to Facebook to connect the app with your Facebook page.

Make sure you have entered and saved the account name, the App ID and the App secret first. Only then click the button.

After a successful connection, the access token is generated automatically and saved in the database.

In the first window, click Continue.

Then select the page whose posts you want to import.

Check the permissions. Click Save.

The user is now connected to the app. Click Got it and the access token is saved automatically.

You can test the generated access token with the Access Token Debugger. If you enter the token on that page and click Debug, it should look like the following screenshot. It is important that the expiry date is Never, otherwise you would have to generate a new access token after it expires.

It is also important that the user who generated the access token remains an admin of the Facebook page. Otherwise the access token becomes invalid. The access token also becomes invalid if the user changes their Facebook password.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

Twitter

Setting up the Twitter stream

1 / Create a Twitter developer account and app

To show Twitter posts on your website you need a Twitter account and a Twitter developer account. You find a step-by-step guide here: Setting up the developer account/Twitter app.

Note

Since February 2023, tweets can no longer be read with the free Twitter API. You need at least the Basic plan for USD 100/month for the tweet import to work.

2 / Create a news archive

First create a news archive into which the Twitter posts will be imported. You have to specify a redirect page for the news archive because it is a mandatory field, although it is not relevant for the Social Feed bundle as there is no news detail page. Ideally, create a separate news archive for each Twitter account, so you can deselect individual accounts in the news list module later.

3 / Create an account

To create an account, click Create a new Social Feed account and select the type Twitter. A form opens where you enter all the required account data. After saving, it may take 2-3 minutes until all posts are imported.

API key: Found in the app details in the tab “Keys and tokens”.
API secret key: Found in the app details in the tab “Keys and tokens”.
Access token: Found in the app details in the tab “Keys and tokens”.
Access token secret: Found in the app details in the tab “Keys and tokens”.
Twitter account: Enter the name of the Twitter account, without @.
Search term: Instead of showing the posts of an account, you can also search for a specific term.
Maximum number of posts: The maximum number of posts imported at once.
News archive: Select the news archive into which the Twitter posts should be imported.
Cron job execution: Choose how often the cron job runs to import new Twitter posts. The options are: no cron job, every minute, hourly, daily, weekly and monthly.
Also import retweets: If you enable this checkbox, retweets are imported and shown as well.
Also import replies: If you enable this checkbox, replies are imported and shown as well.
Link hashtags and mentions: If you enable this checkbox, hashtags (e.g. #contao) and mentions (e.g. @pdirGmbH) are linked. For this, the template news_social_feed_extended must be selected in the news list module.
Last import: The two text fields for the last import only show when the last import took place.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

Twitter App

Setting up the Twitter developer account/app

Note

Since February 2023, tweets can no longer be read with the free Twitter API. You need at least the Basic plan for USD 100/month for the tweet import to work.

Create a developer account

1 / Open the Twitter developer website

Open https://developer.twitter.com/en/apply-for-access and click Apply for a developer account. Log in with your Twitter account, or sign up if you don’t have a Twitter account yet.

A page opens where you choose why you want to use the Twitter developer tools. Select Doing something else.

2 / Select the country

Select the country and enter a name for the developer account.

3 / App usage

Now describe how the Twitter API will be used.

Fill in the first input field, for example with this text, or describe it in your own words.

The twitter api will be used to show posts belonging to a page or a hashtag and information about the posts creator on the own website. The posts and images will be written directly into the website database and will be showed on the website.

For “Do you plan to display Tweets or aggregate data about Twitter content outside of Twitter?” you could enter the following text.

The posts will be shown on the own website with the post image, text, post creator and profile image.

All other input fields are not relevant, you can disable them.

4 / Review

Review the data you entered and click Looks good!

5 / Complete the registration

Accept the Developer Agreement and click Submit Application. You should then receive a confirmation email. Click the confirmation link in this email to complete the registration of the developer account.

6 / Create an app

You can create a new app on this page: https://developer.twitter.com/en/apps.

Fill in the following fields:

App name: Any name for the app (it must not have been taken by another user).
Application description: A short description of the app, e.g. Show posts from twitter on the own website.
Website URL: The URL of your website.
Tell us how this app will be used: Describe how the app will be used. You can paste the text from above, for example.

Once the app has been created, a new page with the app details should open. Click Keys and tokens in the navigation at the top. There you can see the API key, API secret key, access token and access token secret that you need to read the Twitter posts. To see the access token and access token secret the first time, click Generate.

Instagram

Setting up the Instagram stream

1 / Create a Facebook app

Create a new app with the button “Create app” at the top right.

In the App details dialog, enter a suitable app name.

Under Business messaging, select the use case “Manage messaging & content on Instagram”.

In the Business step, choose the option “I don’t want to connect a business portfolio yet” and click Next again.

Skip the following Requirements step without selecting anything (just click Next). An overview appears – use “Go to dashboard” to switch to the app dashboard.

In the left navigation bar, open Use cases and click “Customize”.

This area contains the Instagram app ID and the app secret. You will enter both values later in the corresponding Social Feed account in the Contao back end.

Scroll further down and click “Set up” at “4. Set up Instagram business login”.

A popup opens. Enter the redirect URL there: https://your-domain.com/_instagram/auth (Replace the domain with the one of your own website.)

At the bottom left of the menu, open App roles → Roles (1). Use the button “Add people” (2) to add a new role of type “Instagram tester” (3). In the search field, enter the name of the Instagram account whose content you want to read, select the correct account from the results and click “Add”.

Accept the invitation at the following link: https://www.instagram.com/accounts/manage_access

In the tab “Tester invites”, click “Accept”.

The Instagram tester should now be shown in the app roles – without the status “Pending”.

2 / Create a news archive

First create a new news archive. It collects your Instagram posts. When setting it up you have to specify a redirect page, although it plays no role for the Social Feed bundle. For a better overview, we recommend creating a separate archive for each Instagram account. That way you can easily hide individual accounts in the news list module later.

3 / Create an account and generate a token

Account settings

In the left navigation, go to PDIR APPS and click Social Feed accounts. Choose New account to create a new Social Feed account for the import.

Select Instagram as the type.

Paste the App ID and App secret into the corresponding fields, save, and use the button Request access token to generate a new access token. Before that, select the correct news archive into which the Instagram posts should be imported. You find the App ID and App secret in the Facebook app under API setup with Instagram business login.

Generate the access token

When you tick Request access token, you should be redirected to Instagram.

The access token should now be generated and the fields Instagram access token and Access token expires on should be filled in.

Other fields

Instagram account: Enter the profile name that should be shown on the website.
Maximum number of posts: Defines how many posts are imported.
News archive: Select the news archive into which the Instagram posts should be imported.
Cron job execution: Choose how often the cron job runs to import new Instagram posts. The options are: no cron job, every minute, hourly, daily, weekly and monthly.
Last import: The two text fields for the last import only show when the last import took place. Empty them to force a new import.
Profile image: The profile image is not imported by default, so select it in this field to show it on the website. You can also set an image size, e.g. Important part, 50x50px.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

Setting up the LinkedIn stream

1 / Create a LinkedIn developer account and app

To show LinkedIn posts on your website you need a LinkedIn account and a LinkedIn developer account. You find a step-by-step guide here: Setting up the LinkedIn app.

2 / Create a news archive

First create a news archive into which the LinkedIn posts will be imported. You have to specify a redirect page for the news archive because it is a mandatory field, although it is not relevant for the Social Feed bundle as there is no news detail page. Ideally, create a separate news archive for each LinkedIn account, so you can deselect individual accounts in the news list module later.

3 / Create an account

To create an account, click Create a new Social Feed account and select the type LinkedIn. A form opens where you enter all the required account data. After saving, it may take 2-3 minutes until all posts are imported.

Client ID: Found in your LinkedIn app in the Auth tab.
Client secret: Found in your LinkedIn app in the Auth tab.
Company page ID: Shown in the URL of your company page (if you are an admin).
Maximum number of posts: The maximum number of posts imported at once.
News archive: Select the news archive into which the LinkedIn posts should be imported.
Cron job execution: Choose how often the cron job runs to import new LinkedIn posts. The options are: no cron job, every minute, hourly, daily, weekly and monthly.
Access token expires on: As long as the refresh token is valid, the access token is automatically extended by 2 months each time.
Refresh token expires on: When the refresh token has expired, the access token has to be generated again manually.
Last import: The two text fields for the last import only show when the last import took place.
Profile image: The profile image is not imported by default, so select it in this field to show it on the website. You can also set an image size, e.g. Important part, 50x50px.

When you click the button “Generate access token”, you are redirected to LinkedIn to grant your app the required permissions.

Make sure you have entered and saved the client ID, the client secret and the company page ID first. Only then click the button.

After a successful authorization, the access token is saved automatically.

A refresh token is saved as well. It is used to regenerate the access token every 2 months. The refresh token is valid for one year. After that, the user has to generate the access token again with the checkbox ‘Generate access token’.

When the refresh token expires and the user has to act, the website admin receives a reminder email.

4 / Create a module

The page Module setup contains everything else about creating and placing the module.

LinkedIn App

Open the following page: https://developer.linkedin.com. After clicking Create app and logging in with your LinkedIn account, you get to the form for the new app.

Enter a name, select the LinkedIn page and upload an app logo.

Then verify the company with the Verify button.

Copy the link and send it to the admin of the page, or open it yourself.

The admin can now verify the app for the company.

Now switch to the Products tab and add Marketing Developer Platform as a product.

Click the link View access form to open the form you need to fill in.

Fill in the whole form. LinkedIn then reviews and approves it. Only then does the app have the permissions to read the posts of the page.

Do not write that it will be used for a social feed on your own website, otherwise access will not be granted. Instead, write for example that the API will be used to publish news posts automatically on your own LinkedIn page.

The review usually doesn’t take long; in our test it took only about an hour. It may take longer, though. Once approved, Marketing Developer Platform should be listed under the added products.

In the Auth tab you find the client ID and client secret you need for the next steps. You also have to add the redirect URL under OAuth 2.0 settings: https://your-domain.com/auth/linkedin

Now continue with the steps described on this page: LinkedIn

Feed Moderation

Since version 2.5.0 you can choose which posts are imported and which are skipped. So far this feature is only available for Instagram; Facebook and Twitter will follow later.

First create a Social Feed account. You find all the information in the respective sections Facebook, Instagram or Twitter. The cron job should not be active, so that posts are not imported automatically.

Then select the news archive into which the posts should be imported (pencil icon). Click the button Social Feed at the top right, select your account and fetch the feed.

A list of posts appears, which you can select with checkboxes and import. After clicking the button Import entries (at the very bottom), the selected posts are imported into the news archive.

Module

1 / Create a module

Once you have created your accounts, create the corresponding module. Go to Themes > Front end modules of theme ID x (gear icon) and create a new module.

As module type, select Newslist under News. Select the news archives you want to show in your Social Feed stream. With the field Total number of items you can limit the number of posts. If you want a pagination, fill in the field Items per page.

As the news template, select news_social_feed. As the custom template, select mod_newslist_social_feed. Under image settings, adjust the image size as needed.

Under Social Feed settings you can set the maximum text length and the number of columns, enable/disable Masonry and show/hide images.

Extended template for Twitter

To link hashtags and mentions, select the news template news_social_feed_extended. In addition, the checkbox Link hashtags and mentions must be enabled in the Social Feed account.

You find a demo here: https://demo.pdir.de/social-feed-extended-template.

So far this only works for Twitter posts and not yet for Facebook and Instagram posts.

2 / Place the module

After creating the module, place it anywhere you like.

3 / Template adjustments

If you use Contao 4.4 or 4.5, the post image is not linked by default. If you want to link the image, adjust the template news_social_feed.html5 as follows.

<a href="<?= $this->url ?>" target="_blank">
    <?php if ($this->addImage && $this->sfImages): ?>
        <?php $this->insert('image', $this->arrData); ?>
    <?php endif; ?>
</a>

4 / Customize the stylesheets

You can change the path to the stylesheets in the template mod_newslist_social_feed. This requires at least version 2.5.2 of the Social Feed module.

<?php  $GLOBALS['TL_CSS']['social_feed'] = 'bundles/pdirsocialfeed/css/social_feed.scss||static'; ?>

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Missing icons/emojis

If no icons/emojis are shown in the posts, set the collation of the database table tl_news and of the columns headline and teaser to utf8mb4_unicode_ci. Then import the affected posts again.

You can do this with a change in config.yml. Depending on your Contao installation, config.yml is located in the folder app/config or config.

doctrine:
 dbal:
   connections:
     default:
       default_table_options:
         charset: utf8mb4
         collate: utf8mb4_unicode_ci

Then clear the cache in the Contao Manager, import the posts again and the emojis should be shown.

Syscara Import for Contao

The Syscara Import bundle is an extension for the vehicle manager and imports vehicle data via the API of the well-known CRM software SYSCARA©.

Your benefits

fast and automatic loading of all specified vehicles via the Syscara API
automatic mapping of the vehicle data from the API to the vehicle manager
automatic import of all photos and the floor plan (for motorhomes) of each vehicle

Note

The import requires access data for the Syscara CRM. Without access data, no vehicle data can be read from the Syscara API.

Note

SYSCARA and the SYSCARA logo are registered trademarks of a third party and are not affiliated with pdir GmbH or the Syscara Import* extension for Contao. The extension uses the mobile.de* API to import the vehicle data.

Quick start

Order a license Product website

This documentation covers the following topics:

Requirements

Note

Syscara Import is compatible with Contao 4.9 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. The Syscara Import bundle requires Contao 4.9 or higher and PHP 7.4. The vehicle manager must be installed in version 3.1 or higher.

Tip

We recommend Contao 4.9 with PHP 7.4 or higher.

License

Syscara Import for Contao is available as a domain license and can be ordered online on pdir.de.

For the full version, install vehicle-syscara-import.

Note

You receive the required access data and the installation guide by email after your order.

Order a license Product website

Installation

Contao 4 with the Contao Manager

The extension is easy to install with the Contao Manager.

Open the Contao Manager and log in
Select Discover in the navigation
Enter “Fahrzeugmanager” in the search field
Click Add on Fahrzeugmanager (formerly Mobile.de Inserate)
Select Packages in the navigation
Click the green Apply changes button at the bottom
Run the database changes when the installation has finished

As soon as you want to import data from SYSCARA, you need a license.

Order a license Product website

Configuration

You find more information about the configuration in the vehicle manager section Configuration.

Synchronization

You find more information about the synchronization in the vehicle manager section Synchronization.

Linking the vehicle number

To make vehicles reachable via their vehicle number (domain.com/VEHICLENUMBER), first install the extension terminal42/contao-url-rewrite.

In the folder app/src/EventListener, create a PHP file named HookListener.php.

<?php

namespace App\EventListener;

use Contao\CoreBundle\ServiceAnnotation\Hook;
use Contao\Database;
use Contao\StringUtil;

class HookListener {
    /**
     * @Hook("vehicleFetchItems")
     */
    public function vehicleFetchItems($vehicles): void
    {
        $vehicles = json_decode(json_encode($vehicles), true);

        $database = Database::getInstance();
        $database->execute("TRUNCATE tl_url_rewrite");

        foreach($vehicles as $item) {
            $alias = '/details/'.StringUtil::generateAlias($item['hersteller'].' '.$item['modell'].' '.$item['baureihe'].' '.$item['eigene_id']).'.html';
            $alias = str_replace(['ä','ü','ö'], ['a','u','o'], $alias);

            $set = [
                'name' => $item['eigene_id'],
                'tstamp' => time(),
                'type' => 'basic',
                'requestPath' => '/'.$item['eigene_id'],
                'responseUri' => $alias,
                'responseCode' => 301
            ];
            $database->prepare("INSERT INTO tl_url_rewrite %s")->set($set)->execute();
        }
    }
}

The line $database->execute("TRUNCATE tl_url_rewrite"); empties the table. If you have other rewrite rules, you need to adjust this part.

You may also need to adjust the alias in $alias = '/details/' if the vehicle detail page has a different URL.

Then create config.php in the folder app/contao/config and clear the cache in the Contao Manager.

<?php

use App\EventListener\HookListener;

$GLOBALS['TL_HOOKS']['vehicleFetchItems'][] = [HookListener::class, 'vehicleFetchItems'];

With the next import, the table should be filled. You find it in the back end under System > URL rewrites.

Theme Helper for Contao

Global content is managed in folders, and each area gets its own article and a theme tag. Available tags are assigned in the article properties. The articles can be included anywhere with a dedicated insert tag, e.g. {{theme::content::THEME_HELPER_01}}. The available tags are registered in config.php.

Quick start

Installation

Contao 4

With the Contao Manager

Open the Contao Manager and log in
Select Discover in the menu
Enter Theme Helper in the search field and click Add
Select Packages in the menu
If you use Contao 4.13 or lower, enter version 1.4.* instead of the latest version. With Contao 5, the Contao Manager installs the latest version automatically.
Click Apply changes to start the installation
Open the install tool (under Tools) and update the database

Configuration

Define your own theme helper tags

You can add your own theme helper tags in localconfig.php in system/config. Afterwards clear the cache in the Contao Manager.

$GLOBALS['tl_config']['theme_tags'][] = 'THEME_HELPER_01';

In the article settings, select the theme helper tag you created under Template settings.

You can then use the content of the article anywhere with the following insert tag.

{{theme::content::THEME_HELPER_01}}

Vehicle Manager for Contao

An extension with filters and features to show your vehicle stock on your own website. All vehicles can be managed directly in the back end. Extensive filter and sorting functions complete the list view. The detail view contains all vehicle information and a lean product slider. Additional features can be integrated on request. Just ask us.

Your benefits

List view with extensive filter and sorting functions
Detail view with Contao image slider
Featured vehicle
Templates and design can be customized the usual “Contao way”
Guaranteed support for the latest or current Contao LTS version

Optionally available

Automatic synchronization of vehicles from the mobile.de platform via API
Automatic synchronization of vehicles from the SysCara platform via XML import

More information is available on the project website.

More information about the vehicle manager on pdir.de

Note

mobile.de and the mobile.de logo are registered trademarks of a third party and are not affiliated with pdir GmbH or the mobile.de* extension for Contao. The extension uses the mobile.de* API to import the vehicle data.

Quick start

Order a license Product website

This documentation covers the following topics:

@MDevster 251 commits

@seibtph 139 commits

@cmette 1 commits

Requirements

Note

The vehicle manager is compatible with Contao 4.9 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. The vehicle manager requires Contao 4.9 or higher and PHP 7.2.

Tip

We recommend Contao 4.13 with PHP 8.1 or higher.

Contao Manager

The vehicle manager is easy to install with the Contao Manager. Just search for Fahrzeugmanager.

The extension in the extension directory on contao.org.

License

The vehicle manager for Contao is available as a domain license and can be ordered online on pdir.de.

For the full version, install the mobilede-sync-bundle.

Note

You receive the required access data and the installation guide by email after your order.

Order a license Product website

Installation

The extension is easy to install with the Contao Manager.

Open the Contao Manager and log in
Select Discover in the navigation
Enter “Fahrzeugmanager” in the search field
Click Add on Fahrzeugmanager (formerly Mobile.de Inserate)
Select Packages in the navigation
Click the green Apply changes button at the bottom
Run the database changes when the installation has finished

As soon as you want to import data from mobile.de, you need a license.

Order a license Product website

Configuration

This section covers the following topics:

1 / Create modules

First create one page each for the list view and the detail view.

List view

For the list view, place an element in the intended article and select the element type Fahrzeugmanager Listenansicht (vehicle manager list view).
In the field Detail view, select the page with the detail view.

Example placement of the element

Filter

Since version 2.3.0 of the vehicle manager you can show the filter form and the results on separate pages.

To show the filter form on a separate page, place an element of type Fahrzeugmanager Listenansicht (vehicle manager list view), select the page for the list view and enable the options Filter only and Show filter expanded.

This is what it should look like in the front end.

Detail view

For the detail view, place an element in the intended article and select the element type Fahrzeugmanager Detailansicht (vehicle manager detail view).

Contact form in the detail view

The ce_mobilede_reader template contains the following insert tag at around line 192: {{insert_form::1}} Enter the ID of the form you want to include here.

You can pass the vehicle model to the form when the page loads, for example with the following script:

<script>
$(document).ready( function() {
  if(jQuery('.md-detail-header h1').length) {
    jQuery('.additional-form input[name="Fahrzeug"]').html(jQuery('.md-detail-header h1').html());
  }
});
</script>

Example placement of the element

Accounts

Account overview

The menu item Accounts (PDIR APPS) opens the account overview, where you can also create a new account with the New button at the top right.

Create a new account

mobile.de import

Select MobileDe API Sync as the API type to import data from mobile.de.

Note

For the mobile.de API sync you need the full version of the vehicle manager, the access data for the mobile.de API and your customer ID. You find the customer ID in the source code of your mobile.de dealer page. (Example: https://home.mobile.de/MY-COMPANY, press F12 and search for “customerId” in the source code.)

Note

The API access data is not the same as your dealer login! This article (in German) describes where to find the access data and how to create it.

SYSCARA import

If you use the Syscara extension and want to import data from SYSCARA, select the API type Syscara-API Sync.

Synchronization

Manual synchronization

You can run a manual synchronization for all active accounts in the back end at any time. Go to PDIR APPS * Vehicle manager * Start import.

Automatic synchronization / poor man’s cron

Contao runs some tasks at regular intervals with its own cron functionality. All active vehicle manager accounts are updated every hour.

Automatic synchronization / real cron job on the server

Recommendation: set up a real cron job with the Contao console.

php vendor/bin/contao-console vehicle:mobileDe:import

The Contao manual explains how to set up the cron job correctly.

Import demo data

You can import our demo data for the initial setup. Go to PDIR APPS * Vehicle manager * Import demo data.

Update

You can update the extension with the Contao Manager. Then open the install tool and update the database if necessary.

Tip

A database backup beforehand never hurts!

Themes

Contao themes

These themes already include layout templates (CSS and templates) for the vehicle manager.

MATE theme

MATE is a Contao theme that supports Contao 4.x and uses the front end framework Materialize based on Material Design.

The MATE theme is available free of charge (with copyright notice) or as a paid version (without copyright notice).

There are 4 different color schemes with matching shades: green, blue, dark and yellow.

Demo: https://mate.pdir.de/immobilien.html Documentation: Vehicle manager Install for free or order a license: https://contao-themes.net/theme-detail/mate.html

List view (vertical layout)

List view (horizontal layout)

Exposé (detail view)

Issues

If you ran into problems during installation or setup, or if you found a bug in the extension, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Contao Manual

Overview

Which topic are you interested in?

Users

Contao Video Tutorials

Overview

Here you find an overview of all Contao video tutorial topics. The videos are in German.

Getting started with Contao

Logging in to Contao

MARKENZOO briefly explains how to log in to Contao (video in German). In under a minute you learn how to get to the Contao login page of your website.

Articles, content and elements

The site structure

MARKENZOO briefly explains what the Contao site structure is (video in German). In under a minute you learn what subpages are and how to show and hide them.

The articles page

MARKENZOO briefly explains the Contao articles page. In under a minute you see how the article structure is organized and how to display a preview.

Adding an article

MARKENZOO briefly explains how to add a new article including a content element in the article structure.

Duplicating an article

MARKENZOO briefly explains how to duplicate an article including its content elements and why this is often the more practical way to add a new article.

MARKENZOO briefly explains how to hide an article in the menu so that it is no longer visible in the navigation, and also how the page can still be reached.

The file manager

MARKENZOO briefly explains the Contao file manager (video in German). In under a minute you see how the file manager should be organized and how to upload files.

Users and permissions

Managing users and permissions in Contao

MARKENZOO briefly explains how to assign permissions to users in Contao (video in German). Their example: a new employee in the user group “Redaktion” (editorial team).

Creating user groups in Contao

MARKENZOO briefly explains how to create user groups in Contao and assign permissions. Their example: the user group “Redaktion”.

The Contao Manager

The Contao Manager – no fear of updates

Maren Lange explains the Contao Manager (video in German).

the basic procedure for updating Contao 4 installations
a short description of the Contao Manager
typical errors that can occur when updating via the Manager
how to deal with errors during an update
where to get help and which information is needed for it

Creating anchors

Creating and using anchors

MARKENZOO briefly explains how to create anchors (jump labels) in Contao, both within a subpage and as a navigation (video in German).

Creating forms

Creating forms in Contao

MARKENZOO briefly explains how to create a form in Contao (video in German). Their example: the contact form on the MARKENZOO website.

Creating FAQs

Managing FAQs in Contao

MARKENZOO briefly explains how to create FAQs in Contao and include the frequently asked questions on your site (video in German).

Clearing the browser cache

The browser cache is a buffer of the web browser in which resources that have already been loaded (e.g. texts, images, fonts and stylesheets) are kept as a copy on the user’s computer (locally). When these resources are used, outdated content may be displayed in the browser. Clearing the browser cache fixes this.

Note

Use a hard refresh if you only want to clear the cache of individual pages.

Hard refresh of individual pages

All common browsers let you clear the cache of a single page by pressing Ctrl + F5 (on a Mac Cmd + Shift + R). The cache of the current page is cleared and the page reloads. The changes to the page should now be visible.

Clearing the Mozilla Firefox cache

Open Mozilla Firefox
Press Ctrl + Shift + Del at the same time
In the first drop-down menu, select Everything to clear the entire time range
Tick Cache
Now click OK

Clearing the Google Chrome cache

Open Google Chrome
Press Ctrl + Shift + Del at the same time
Open the Advanced tab
Under Time range, select All time
Activate Cached images and files
Then click Clear data

Clearing the Safari cache

Option 1

On a Mac, clear the cache with the keyboard shortcut [cmd] + [alt] + [E].

Option 2

Clear the Safari cache via the Develop menu.

Open Safari and click Safari > Settings in the menu bar at the top left.
In the settings, go to Advanced at the top right and tick Show Develop menu in menu bar. The option Develop then appears in the menu bar.
Click the option you just added and select Empty Caches.

Microsoft Edge & Internet Explorer

Open Microsoft Edge or Internet Explorer
Press Ctrl + Shift + Del at the same time
Under Time range, select All time
Activate Cached images and files
Then click Clear now

Command line commands

Commands

The Contao framework provides many commands via the script vendor/bin/contao-console (e.g. the well-known command vendor/bin/contao-console cache:clear).

Overview of the commands provided by Contao

# contao
  contao:automator              Runs automator tasks on the command line.
  contao:backup:create          Creates a new database backup.
  contao:backup:list            Lists the existing database backups.
  contao:backup:restore         Restores a database backup.
  contao:crawl                  Crawls the Contao root pages with the desired subscribers.
  contao:cron                   Runs all registered cron jobs on the command line.
  contao:filesync               Synchronizes the registered DBAFS with the virtual filesystem.
  contao:install                Installs the required Contao directories.
  contao:install-web-dir        Installs the files in the public directory.
  contao:install:lock           Locks the install tool.
  contao:install:unlock         Unlocks the install tool.
  contao:maintenance-mode       Changes the state of the system maintenance mode.
  contao:migrate                Executes migrations and updates the database schema.
  contao:resize-images          Resizes deferred images that have not been processed yet.
  contao:setup                  Sets up a Contao Managed Edition. This command is run when executing the "contao-setup" binary.
  contao:symlinks               Symlinks the public resources into the public directory.
  contao:user:create            Creates a new Contao back end user.
  contao:user:list              Lists Contao back end users.
  contao:user:password          Changes the password of a Contao back end user.
  contao:version                Outputs the contao/core-bundle version (deprecated).

Commands from the Symfony framework and the libraries required by Contao

# assets
  assets:install                Install bundle's web assets under a public directory

# cache
  cache:clear                   Clear the cache
  cache:pool:clear              Clear cache pools
  cache:pool:delete             Delete an item from a cache pool
  cache:pool:list               List available cache pools
  cache:pool:prune              Prune cache pools
  cache:warmup                  Warm up an empty cache

# config
  config:dump-reference         Dump the default configuration for an extension

# dbal
  dbal:run-sql                  Executes arbitrary SQL directly from the command line.

# debug
  debug:autowiring              List classes/interfaces you can use for autowiring
  debug:config                  Dump the current configuration for an extension
  debug:container               Display current services for an application
  debug:contao-twig             Displays the Contao template hierarchy.
  debug:dca                     Dumps the DCA configuration for a table.
  debug:dotenv                  Lists all dotenv files with variables and values
  debug:event-dispatcher        Display configured listeners for an application
  debug:firewall                Display information about your security firewall(s)
  debug:fragments               Displays the fragment controller configuration.
  debug:pages                   Displays the page controller configuration.
  debug:plugins                 Displays the Contao Manager plugin configurations.
  debug:router                  Display current routes for an application
  debug:translation             Display translation messages information
  debug:twig                    Show a list of twig functions, filters, globals and tests

# doctrine
  doctrine:cache:clear-collection-region            Clear a second-level cache collection region
  doctrine:cache:clear-entity-region                Clear a second-level cache entity region
  doctrine:cache:clear-metadata                     Clear all metadata cache of the various cache drivers
  doctrine:cache:clear-query                        Clear all query cache of the various cache drivers
  doctrine:cache:clear-query-region                 Clear a second-level cache query region
  doctrine:cache:clear-result                       Clear all result cache of the various cache drivers
  doctrine:database:create                          Creates the configured database
  doctrine:database:drop                            Drops the configured database
  doctrine:ensure-production-settings               Verify that Doctrine is properly configured for a production environment
  doctrine:mapping:convert [orm:convert:mapping]    Convert mapping information between supported formats
  doctrine:mapping:import                           Imports mapping information from an existing database
  doctrine:mapping:info
  doctrine:query:dql                                Executes arbitrary DQL directly from the command line
  doctrine:query:sql                                Executes arbitrary SQL directly from the command line.
  doctrine:schema:create                            Executes (or dumps) the SQL needed to generate the database schema
  doctrine:schema:drop                              Executes (or dumps) the SQL needed to drop the current database schema
  doctrine:schema:update                            Executes (or dumps) the SQL needed to update the database schema to match the current mapping metadata
  doctrine:schema:validate                          Validate the mapping files

# fos
  fos:httpcache:clear                       Clear the HTTP cache.
  fos:httpcache:invalidate:path             Invalidate cached paths on all configured caching proxies
  fos:httpcache:invalidate:regex            Invalidate everything matching a regular expression on all configured caching proxies
  fos:httpcache:invalidate:tag              Invalidate cached content matching the specified tags on all configured caching proxies
  fos:httpcache:refresh:path                Refresh paths on all configured caching proxies

# lint
  lint:container                Ensure that arguments injected into services match type declarations
  lint:twig                     Lint a Twig template and outputs encountered errors
  lint:xliff                    Lint an XLIFF file and outputs encountered errors
  lint:yaml                     Lint a YAML file and outputs encountered errors

# router
  router:match                  Help debug routes by simulating a path info match

# secrets
  secrets:decrypt-to-local      Decrypt all secrets and stores them in the local vault
  secrets:encrypt-from-local    Encrypt all local secrets to the vault
  secrets:generate-keys         Generate new encryption keys
  secrets:list                  List all secrets
  secrets:remove                Remove a secret from the vault
  secrets:set                   Set a secret in the vault

# security
  security:encode-password      Encode a password
  security:hash-password        Hash a user password

# translation
  translation:extract           [translation:update] Extract missing translations keys from code to translation files.
  translation:pull              Pull translations from a given provider.
  translation:push              Push translations to a given provider.

Additional commands from other extensions

# [pdir Maklermodul](https://github.com/pdir/maklermodul-bundle) 
maklermodul
  maklermodul:clear         Deletes the property data folder.
  maklermodul:import        Imports properties from OpenImmo XML files.
  maklermodul:index         Creates indexes for list views.
  maklermodul:sync          Imports & indexes property data.

# [Contao Utils Bundle](https://github.com/heimrichhannot/contao-utils-bundle)
huh
  huh:utils:create-image-size-items         Creates image size items for a given image size entity. Image size entities with existing image size items will be skipped.

Themes

Choose your theme:

Guides

0.1 Theme for Contao

Quick start

The theme documentation covers the following topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Our theme requires Contao 4.4 or higher and PHP 5.6.

Tip

We recommend Contao 4.9 with PHP 7.1 or higher to get the best possible loading time with our theme!

Contao Manager

The theme is easy to install with the Contao Manager. You find an installation guide here.

License

Buying and registering a license

The 0.1 theme is available free of charge (with copyright notice) or as a paid version (without copyright notice).

You can buy the paid license on contao-themes.net. Select the option without copyright notice, enter your domain and click the button Add to cart. Then go to checkout and follow the steps.

After successful payment (possible payment methods are PayPal, Sofort bank transfer or credit card) you receive an invoice by email, and we will activate your domain shortly, so that you can register it in the Contao back end.

Until then, you can already install and use the theme with the copyright notice.

Tip

As the holder of a paid license you receive premium support if you have problems installing or setting up the theme.

Registering the license

Note

If you ordered the theme license via themes.contao.org, please send us an email with your domain and the theme you ordered to support[AT]pdir.dev, so that we can activate the theme domain in the back end.

If you have bought a license and already installed the theme, you can register it in the back end under the menu item Themes. Click Activate theme domain, enter your domain and then click Check Domain. If the domain was registered successfully, you see the message Domain registered. When you reload the page, it should look like the following screenshot.

If you only see the message “You can set a Theme Licence in Layout -> Themes.” when you click the button Activate theme domain, edit the theme and enter 0.1 in the field Theme code (see the following screenshot). The input field for the domain should then be visible.

Removing the copyright notice

Once you have bought a license, you can remove the copyright notice, which is placed in an article, in the Contao back end.

Go to the article view, find the article 03 Copyright under Elements > 03 Footer and edit it with the pencil icon.

Installation

Still using Contao 4? You find the installation guide here.

Contao 4 installation guide

Note

The demo can only be imported into an empty Contao installation.

Note

If you have already created content on your site, see this guide: Installation into an existing Contao installation.

Installation in Contao 5

Open the Contao Manager: www.your-domain.com/contao-manager.phar.php. In the Discover tab, enter 0.1 Theme and click Add.

In the Packages tab you should now see a new package to be installed. Click the button Apply changes at the bottom to start the installation.

Once the installation has finished, click Update database.

Run all database migrations and click Continue. In the first step, all folders and files are created in the file manager.

Then the missing fields are created in the database.

In the last step, the demo data is imported.

Done! When you open your site, you should already see the demo.

Notes

Error message: This page isn’t working / The page redirected you too many times

Edit the root page and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error message: imagick not installed

If the error message imagick not installed occurs with PHP 8.0, you can fix it with an adjustment in config.yml and then clearing the cache. More information in the PDIR blog post (in German)

Contao 4

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Tip

The following steps are only necessary for the first installation, not for an update of the theme. To update the theme, simply use the Contao Manager. Then open the install tool and update the database. A database backup never hurts!

Steps

1 / Install the 0.1 theme bundle

First open the Contao Manager at the following URL: www.your-domain.com/contao-manager.phar.php. Click Discover, enter 0.1 theme in the search field and add the package 0.1 Theme.

Then switch to Packages, enter the version ^1.0 via the gear icon and start the installation of the theme with the button Apply changes. With the latest version, the Contao Manager would otherwise install version 2.x, which is only compatible with Contao 5.

2 / Update the database

Then open the install tool and update the database. In the install tool you also have to create an admin user account.

You reach the install tool in the Contao Manager via the menu item Tools or at the URL: www.your-domain.com/contao/install.

3 / Synchronize theme files and empty tl_files

Log in to the back end with the user account you created and select 0.1 Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager in the folder zeroOne and copies the SQL files for the database import to the templates folder.

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’. This step must be done before importing the database.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

4 / Import the database

Now open the install tool. In the tab “Import a template” you can import a .sql file from the templates directory. Select the file for your Contao version and tick Do not truncate tables. Then click Import a template.

If you selected the minimal Contao installation in the Contao Manager (without news, calendar, newsletter, comments, listing, FAQ), select the SQL file named minimal_installtool.sql.

If the database was imported successfully, you should see a message that a template was imported, as shown in the screenshot.

5 / Recreate symlinks

Then switch back to the Contao back end, select System maintenance and recreate the symlinks by ticking Recreate symlinks and then clicking the button Purge data.

6 / Settings

Under Advanced CSS settings, select the class set spectre.json.

Notes

Error message: This page isn’t working / The page redirected you too many times

Edit the root page and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error message: imagick not installed

If the error message imagick not installed occurs with PHP 8.0, you can fix it with an adjustment in config.yml and then clearing the cache. More information in the PDIR blog post (in German)

Customization

Header and footer

You edit the header content in the articles under Elements > 01 Header.

You edit the footer content in the articles under Elements > 03 Footer.

Contact form

If you want to receive contact form submissions by email, select Form generator in the left navigation and edit the form settings (the second icon). Under Send form data, replace the email address.

Customizing the styling

Once the theme has been installed, the SCSS files are located in the file manager under zeroOne/scss. For your own customizations, simply use custom.scss, where you can write both SCSS and plain CSS, and _custom_variables.scss.

In _custom_variables.scss you can change the colors and the font of the theme and select a different color scheme. To change a variable, uncomment the line (remove the slashes).

Tip

If the SCSS file was not edited with the Contao editor but uploaded with an FTP program, clear the script cache under system maintenance in the Contao back end and reload the page with Ctrl + F5 if necessary.

Note

Do not rename the theme folder zeroOne in the file manager, otherwise the SCSS files will no longer be loaded. You don’t need to include the files in the page layout yourself; the theme loads them automatically.

Color schemes

By default, the 0.1 theme comes with a light layout in orange/yellow colors. You can also activate other color schemes:

Light color scheme - orange/yellow (DAY)
Light color scheme - green/blue (EARTH)
Light color scheme - red/blue (NIGHT)

To switch to a different layout, uncomment (remove the slashes) the line with the desired color scheme in the section Colour Schemes of _custom_variables.scss. You may have to reload the page in the browser with Ctrl + F5 for the changes to take effect.

Example for activating the EARTH color scheme:

@import 'colour_schemes/earth';
//@import 'colour_schemes/night';

@import '#{$scssPath}/colour_schemes/earth';
//@import '#{$scssPath}/colour_schemes/night';

If the variable $scssPath doesn’t exist in _custom_variables.scss yet, add it before the import statements. $scssPath: "../../../vendor/contao-themes-net/zero-one-theme-bundle/src/Resources/public/scss";

Dark mode

Many devices and apps now offer a dark mode that shows the user interface in dark colors and the text in light colors for better readability. When dark mode is active, the 0.1 theme automatically switches to a darker color scheme, no matter which color scheme you have activated. This is easier on the eyes and can also improve battery life thanks to the lower lighting energy.

If you prefer, you can disable dark mode by commenting out the following line in _custom_variables.scss (put two slashes at the beginning of the line):

//@import 'colour_schemes/dark_mode';

//@import '#{$scssPath}/colour_schemes/dark_mode';

Automatic adjustment of images to the color scheme

In the 0.1 theme, the images of news, events and the parallax element are automatically tinted to match the selected color scheme with CSS image filters. In the DAY color scheme images appear yellow/orange, while in the NIGHT scheme a violet filter is placed over the images. You can tint any image with these color filters by adding the class css-filter to the image element.

You can also disable the automatic color filters. To do so, comment out the following line in _custom_variables.scss (put two slashes at the beginning of the line).

This feature is supported by all current browsers (except Internet Explorer).

//@import 'colour_schemes/adjust_images';

//@import '#{$scssPath}/colour_schemes/adjust_images';

Variables

To change colors and the font, uncomment the corresponding lines in _custom_variables.scss (remove the slashes).

Variable	Meaning
$body-font-family	Font
$zeroOneColor_1	Dark text and backgrounds, navigation, back-to-top button, buttons, text color on gradient background, footer, form labels
$zeroOneColor_2	Dark primary color, gradient background right, button and link hover
$zeroOneColor_3	Light primary color, gradient background left, active tab, hover on social icons, events in the calendar
$zeroOneColor_4	Headlines, dark primary color
$zeroOneColor_5	Light text, buttons, navigation level 1, parallax element, back-to-top button, footer, forms

$body-bg	Background color of the page
$body-font-color	Text color
$link-color	Link color
$link-color-dark	Link color on hover
$boxes-background	Background color for boxes, ^{news and event lists without images, calendar, forms, striped tables}

$footer-background_1	Background color of the upper footer area
$footer-color-1	Text color of the upper footer area
$footer-background-2	Background color of the lower footer area (copyright)
$footer-color-2	Text color of the lower footer area (copyright)

$border-radius	Rounded corners for buttons, forms, navigation etc. - possible values e.g. 10px, 100% or 0px (no rounded corners).
$mobile-navbar-breakpoint	Breakpoint at which the mobile navigation with the burger icon is shown - default: 960px

Including a font

To include a font, add CSS code like the following at the very beginning of _custom_variables.scss. Replace the name and the paths of the font. The path must always start with /.

@font-face {
	font-family: "Beispiel-Font";
	font-style: normal;
	font-weight: normal;
	src: url("/files/zeroOne/fonts/font.woff"),
	url("/files/zeroOne/fonts/font.ttf"),
	url("/files/zeroOne/fonts/font.svg");
}

_custom_variables.scss defines a variable for the font ($body-font-family). Uncomment the line (remove the slashes) and add the name of the font at the beginning.

$body-font-family: 'Beispiel-Font', -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto;

Defining SCSS for specific pages only

CUSTOM_STYLES

You can add the following line to templates so that the SCSS is only loaded on pages where this template is used. Always use the full path starting from files.

<?php $GLOBALS['CUSTOM_STYLES'][] = 'files/zeroOne/scss/ce_text' ?>

ZERO_ONE_STYLES

With ZERO_ONE_STYLES you can load SCSS files from the theme or the Spectre framework. The path always starts at the folder bundles/contaothemesnetzeroonetheme/scss.

<?php $GLOBALS['ZERO_ONE_STYLES'][] = '_buttons'; ?>

FAQ

Images

How can I reduce the height of the large header image on the home page?

Add the following CSS to custom.scss.

.hero .hero-body {
    min-height: inherit;
    padding-bottom: 50px;
}

How can I change or remove the background image of the large header image on the home page?

Add the following CSS to custom.scss to change the background image.

.hero .hero-body {
  background-image: url(/files/zeroOne/img/quote.svg);
}

You can of course also remove the background image.

.hero .hero-body {
  background-image: none;
}

Why is an image not shown?

The folder in the file manager may not be set to public. You can check this by editing the folder. Public must be ticked, otherwise the image is not shown in the front end.

Why doesn’t the large view of an image open in a lightbox when I click it?

For this, jQuery and the jQuery template j_colorbox must be loaded in the theme. You edit the layout in the back end under Themes with the third-to-last icon Edit the page layouts of theme ID 1.

Why are animated GIFs not shown?

For animated GIFs, do not set an image size in the image settings, otherwise the animation is lost.

Why are some images not shown? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message can look roughly like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing library

In config.yml you can specify a different image processing service; then clear the cache. This often solves the problem. If WEBP is supported, you should also be able to select it in the image sizes.

contao:
    image:
        imagine_service: 'contao.image.imagine.gd'

contao:
    image:
        imagine_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Events/News

How can I remove the left column with the image in events/news?

If no image is selected in the news/event, the left column is not shown. Otherwise you can select the template event_full_zeroone_without_image or news_full_zeroone_without_image in the event reader/news reader module.

Contact page

How can I replace or edit the graphic with the contact details on the contact page?

You find the SVG graphic in the file manager in the folder zeroOne/img/files/zeroOne/img/navbar_level_2.svg. You can simply replace it with another graphic (the file name must stay the same).

If you only want to change the background color, you can also edit the source code of the file in the file manager (the second-to-last icon). After the opening <g, add the code fill="#015b7e" and replace the color code with your desired color (see the following screenshot).

How can I change the background color of the form field labels?

You can change this with the variable $zeroOneColor_1 in der in _custom_variables.scss. Alternatively, you can add the following CSS to custom.scss.

.form-label, .form-group label:not(.form-checkbox):not(.form-radio), 
.ce_form .widget:not(.widget-checkbox):not(.widget-radio) label:not(.form-checkbox):not(.form-radio) {
    background: #d23b3b;
}

How can I change the text color of the input fields?

You can change this with the variable $body-font-color in der in _custom_variables.scss. Alternatively, you can add the following CSS to custom.scss.

.form-input, .form-select, .checkbox_container > div, .radio_container .form-group > div, textarea {
	color: #333;
}

Text elements

How can I change the color of every second table row?

You can change this with the variable $boxes-background in der in _custom_variables.scss. Alternatively, you can add the following CSS to custom.scss.

.table.table-striped tbody tr:nth-of-type(odd) {
  background: #cceaff;
}

Article backgrounds

Note

This feature is only available from 0.1 theme version 2.1.0 (Contao 5) or 1.11.0 (Contao 4).

You can change the background and text color of an article with classes.

The following classes are available for the background:

bg-zeroone-2 (Primary Color Dark)
bg-zeroone-3 (Primary Color Light)
bg-zeroone-4 (Primary Color Darken)
bg-dark
bg-gray
bg-light
bg-success
bg-warning
bg-error

The following classes are available for the text color:

text-primary
text-secondary
text-dark
text-gray
text-light
text-success
text-warning
text-error

More information: Spectre documentation

Example

Adding the classes in the article settings:

This is what it would look like in the front end:

Elements

The following pages explain each element of the 0.1 theme and describe how exactly you can use it.

Accordion

For the accordion, simply select the content element template ce_accordionSingle_zeroone or ce_accordionStart_zeroone for the single element or the accordion start element.

The accordion is based on the Spectre accordion and works entirely without JavaScript, so the j_accordion template does not need to be included in the page layout.

Buttons

To place a button, follow these steps:

Select the element type Hyperlink
Enter the link address/link text (hyperlink settings)
Up to Contao 4.13: select the content element template ce_hyperlink_button_zeroone (template settings)
Contao 5.0 and later: select the content element template content_element/hyperlink/button_zeroone (template settings)

In the tab Advanced CSS classes, under Button style (in classes for content elements), you can assign more classes to change the look of the button: .btn-primary, .btn-link, .btn-success, .btn-error.

Under button size you can change the size of the button: .btn-sm (small), .btn-lg (large).

With button full width the button spans the entire available width: .btn-block.

Carousel

Note

This feature is only available from 0.1 theme version 1.5.0.

The carousel is based on the Spectre carousel and works entirely without JavaScript.

Place the wrapper elements

First you need an element of type Wrapper start (content slider) and Wrapper end. Select the template ce_sliderStart_carousel or ce_sliderStop_carousel for the content elements. The js_slider template does not need to be activated in the layout.

Wrapper start

Wrapper stop

Place the teaser box element

Inside the wrapper elements, place an element of type Teaserbox (under Contao Themes). Assign the template ce_cthemes_teaserbox_carousel to the content element. You can choose a headline, a text, a link and an image. For the image, select the image size Carousel to get the right size.

In the end, the structure of the elements should look like this:

Customize the appearance

By adding more classes you can change the text color and the look of the button. You make these settings in the Teaserbox element under Advanced CSS classes (at the very end).

To show the button with a black background and white text, select the class .btn-primary under button style.

Change the slide effect

Note

This feature is only available from 0.1 theme version 2.1.0 (Contao 5) or 1.11.0 (Contao 4).

Add the class fade to the element of type Wrapper start (content slider) to change the slide effect to a fade effect.

Example

Content box

Note

This feature is only available from 0.1 theme version 1.5.0.

Place the content element

Place an element of type Content Box (under Contao Themes) and select the template ce_cthemes_contentbox_zeroone. With the grid you can show several elements side by side.

Customize the appearance

By adding more classes you can change the text color, background and the look of the buttons. You make these settings in the content element under Advanced CSS classes (at the very end).

To show the button with a black background and white text, select the class .btn-primary under button style.

You can also add the classes bg-zeroone-2, bg-zeroone-3 or bg-zeroone-4 under expert settings to show the content box in one of the primary colors.

Examples

Grid

The theme is based on Spectre CSS, which among other things lets you show elements side by side and, at the same time, in a single column on mobile devices.

Place the content container

To show two text elements side by side, for example, first add one element of type Contao Themes (content container start) and one of type Contao Themes (content container end).

The element of type Content container start needs the col attribute .columns under Advanced CSS classes.

Place the content elements

Between the wrapper elements, place the elements you want to show side by side. Select the col attribute .column under advanced CSS classes.

You can also define more classes, e.g. column widths for certain resolutions or column gaps. You find more information in the Spectre documentation under Flexbox grid and Responsive.

Example

Headlines

Change color and size

Select the element type Headline
Under expert settings you can assign different CSS classes (second input field):
- primary-color-dark: headline in the dark primary color
- primary-color-light: headline in the light primary color
- headline-35: headline is always 35px

Change the alignment

Under advanced CSS classes, in text alignment (under classes for content elements), you can change the alignment of the headline. You can select the following classes:

text-left: left-aligned
text-center: centered
text-right: right-aligned
text-justify: justified

Headlines with dots

Select the element type Headline
Select the content element template ce_headline_zeroone (up to Contao 4.13) or content_element/headline/dotted_zeroone (Contao 5.0 and later)
Under Expert settings, add the CSS class headline-dotted (second input field)

The headline would then look like this:

Media elements

Download(s)

Select the element type Download or Downloads
Make your settings
Up to Contao 4.13: select the content element template ce_download_zeroone or ce_downloads_zeroone (template settings)
Contao 5.0 and later: select the content element template content_element/download/download_zeroone or content_element/downloads/downloads_zeroone (template settings)

Gallery

Select the element type Gallery
Make your settings
Up to Contao 4.13: select the content element template ce_gallery_zeroone (template settings)
Contao 5.0 and later: select the content element template content_element/gallery/gallery_zeroone (template settings)

YouTube video

Select the element type YouTube
Make your settings
Up to Contao 4.13: select the content element template ce_youtube_zeroone (template settings)
Contao 5.0 and later: select the content element template content_element/youtube/youtube_zeroone (template settings)

Parallax

For a parallax element, create a new article, edit the article settings and enter the following CSS classes under expert settings (second input field): hero parallax fullwidth.

In the article, place a text element and add, for example, a headline and a text. Under image settings you select the image.

Under Template settings, select the template ce_text_hero_parallax_zeroone (up to Contao 4.13) or content_element/text/parallax_zeroone (Contao 5.0 and later).

This is what the finished parallax element should look like:

Price box

Note

This feature is only available from 0.1 theme version 1.5.0.

Place the content element

Place an element of type Price table (under Contao Themes) and select the template ce_cthemes_pricebox_zeroone.

With the grid you can show several elements side by side. If the price boxes should have no spacing to the left and right, select .col-gapless (in more classes for columns) under Advanced CSS classes in the content container start.

Customize the appearance

By adding more classes you can change the text color, background, text alignment and the look of the buttons. You make these settings in the content element under Advanced CSS classes (at the very end).

To show the button with a black background and white text, select the class .btn-primary under button style.

To center the content, select .text-center under text alignment.

You can also add the classes bg-zeroone-2, bg-zeroone-3 or bg-zeroone-4 under expert settings to show the price box in one of the primary colors.

Examples

Quote

For a quote element, create a new article, edit the article settings and enter the following CSS classes under expert settings (second input field): hero quote text-center.

In the article, place a text element and add a headline.

You don’t need to fill in the text field, as it is not output. As it is a mandatory field, it is enough to add, for example, just an empty line.

Under Image settings you select the image shown in the background.

Under advanced CSS classes, make the following settings:

select .column under Add col attribute
select .col-mx-auto under Offset

This is what the finished quote element should look like:

Sticky teaser box

The sticky teaser box element is based on the NATURE theme element and is not a feature of the 0.1 theme, but you can build it yourself with template, SCSS and JavaScript adjustments.

Create a template

Create a new template under Templates and select ce_cthemes_teaserbox.html5. It is best to rename the template, e.g. to ce_cthemes_teaserbox_sticky.html5.

Replace the template content with the following code:

<div class="<?= $this->class ?> block sticky-teaserbox full-height"<?= $this->cssID ?><?php if ($this->style): ?> style="<?= $this->style ?>"<?php endif; ?>>
    <div class="inside">
        <?php $this->block('content'); ?>
    
        <?php if ($this->addImage): ?>
            <figure class="image_container float_above" style="background-image:url('<?= $this->picture['img']['src'] ?>')"></figure>
        <?php endif; ?>
    
        <div class="content">
            <?php if ($this->headline): ?>
            <<?= $this->hl ?>>
                <?php if($this->page != ""): ?><a href="<?= $this->page ?>"<?= $this->target ?><?= $this->rel ?><?= $this->pageTitle ?>><?php endif; ?>
                    <?= $this->headline ?>
                <?php if($this->page != ""): ?></a><?php endif; ?>
            </<?= $this->hl ?>>
        <?php endif; ?>
    
        <?= $this->text ?>
    
        <?php if($this->page != ""): ?>
            <div class="pageLink">
                <a href="<?= $this->page ?>"<?= $this->target ?><?= $this->rel ?><?= $this->pageTitle ?>><?= $this->pageText ?></a>
            </div>
        <?php endif; ?>
    </div>
    
    <?php $this->endblock(); ?>
    </div>
</div>

Place the content elements

Now place elements of type Teaser Box (under Contao Themes) and select the template you just created.

Styling

Go to the file manager, edit custom.scss in zeroOne/scss and add the following SCSS code. You may have to reload the page with Ctrl + F5 or clear the script cache for the changes to take effect.

.ce_ct_teaserBox.sticky-teaserbox {
  padding: 0;
  
  .content {
    width: 50%;
    margin-left: 50%;
    padding: 80px 200px 80px 80px;
  }

  .image_container {
    display: none;
    width: 50%;
    background-size: cover;
    height: 100%;
    background-position: center;
    position: absolute;
  }

  .inside {
    height: 100vh;
    align-items: center;
    
    h1, h2, h3, h4, h5, h6 {
        width: 100%;
        text-align: left;
        padding: 0;
    }
    
    .pageLink {
        width: 100%;
    }
  }
  
  p {
  	font-size: 18px;
  }

  .pageLink a {
    @extend .btn;
  }
}

.sticky-container {
  position: relative;

  .sticky-column {
    position: absolute;
    width: 50%;
    height: 100%;
    padding-top: 0;
    content: "";
    left: 0;
    top: 0;

    .sticky-column-background {
      background: center center/cover no-repeat;
      background-image: inherit;
      position: -webkit-sticky;
      position: sticky;
      top: 0;
      width: 100%;
      height: 100vh;
      z-index: 10;

      @for $i from 1 through 20 {
        &:nth-of-type(#{$i}) {
          z-index: #{$i};
        }
      }
    }
  }
}

@media (max-width: 1280px) {
    .ce_ct_teaserBox.sticky-teaserbox .content {
        padding: 20px 80px;
    }
}

@media (max-width: 960px) {
    .ce_ct_teaserBox.sticky-teaserbox {
        .content {
            padding: 20px 40px;
        }
    
        p {
            font-size: 16px;
        }
    }
}

@media (max-width: 600px) {
    .sticky-container .sticky-column {
        display: none;
    }
    
    .ce_ct_teaserBox.sticky-teaserbox {
        .content {
            width: 100%;
            margin: 0;
            padding: 20px;
        }
        
        .image_container {
            display: block;
            width: 100%;
            position: relative;
            height: 300px;
        }
        
        .inside {
            height: inherit;
        }
    }
}

Additional JavaScript

Add the following JavaScript in the layout under Custom JavaScript code. jQuery must also be loaded under jQuery.

Alternatively, you can create a JavaScript file and include it in the layout.

<script>
jQuery(document).ready(function($) {
	if( $(".sticky-teaserbox").length > 0 ) {
        $(".sticky-teaserbox").closest(".mod_article").removeClass("block");
        $(".sticky-teaserbox").closest(".mod_article").addClass("sticky-container");
        $("<div class='sticky-column'></div>").insertBefore(".sticky-teaserbox:nth-of-type(1)");
    }
    $(".sticky-teaserbox").each( function() {
        var style = $(this).find(".inside > .image_container").attr("style").replace(/\"/g, "'"); // replace for ie11
        $(".sticky-column").append('<div class="sticky-column-background" style="'+style+'"></div>');
    });
})	
</script>

Example

Tables

To place a table, follow these steps:

Select the element type Table
Define the table entries
Up to Contao 4.13: select the custom template ce_table_zeroone (template settings)
Contao 5.0 and later: select the custom template content_element/table/table_zeroone (template settings)

Under Expert settings you can define more CSS classes in the second input field to change the look of the table:

table-striped: striped table
table-hover: hover effect
table-scroll: scrollable table

Tabs

For a tabs element, first place one element of type Content container start and one of type Content container end.

In the element Content container start, enter the class tabs in the second input field under Expert settings.

Then place an element of type Tabs navigation inside the content containers.

In the Tabs navigation element you define the individual tabs under Tabs settings. Always enter a unique value and a label.

After the tabs navigation element, add one element of type Tabs wrapper (start) and one of type Tabs wrapper (stop).

Inside the tab wrapper elements, add the content as text elements. Under Expert settings, enter the respective value from the tabs navigation element as the CSS class.

This is what it should look like in the end:

Teaser box

To place a teaser box, follow these steps:

Select the element type Teaser Box (under Contao Themes)
Add a headline and text, and fill in the link address/text in the teaser box settings
Select the custom template ce_cthemes_teaserbox_zeroone (template settings)

By default the teaser box is then shown as in the following screenshot:

You can also add an image by ticking Add an image under Image settings. Under Image alignment you choose whether the image is aligned left or right.

A teaser box with an image is then shown as in the following screenshots.

Modules

The following pages explain each module of the 0.1 theme and describe how exactly you can use it.

Calendar

Follow these steps to place a calendar:

Select the module Calendar (under Events)
Make your settings (calendars, first day of the week, redirect page etc.)
Select the calendar template (template settings)
cal_default (normal calendar)
cal_mini (mini calendar)
Select the custom template mod_calendar_zeroone (template settings)
Include it in an article with the element type Module

Calendar with event details

Mini calendar

Calendar day view

Events

Event list

Follow these steps to place an event list:

Select the module Event list (under Events)
Make your settings (calendars, number of events etc.)
Select the event template (template settings)
event_teaser_zeroone (event list with images)
event_list_zeroone (event list without images)
event_upcoming (simple event list with date and title only)
Select the custom template mod_eventlist_zeroone (template settings)
Select the image size News & Events / List view (image settings)
Add the CSS class columns (second input field) (expert settings)
Include it in an article with the element type Module

Simple event list

Event list without images

Event list with images

Event reader

Follow these steps to place the event reader (detail view):

Select the module Event reader (under Events)
Select the calendars
Select the event template event_full_zeroone (template settings)
Select the image size News & Events / Detail view (image settings)
Include it in an article with the element type Module

Forms

When you create a form, select the form template form_wrapper_zeroone in the form settings under Template settings.

The 0.1 theme also includes more templates for form fields, which you select in the respective elements under template settings if the fields should look like in the theme demo.

Checkbox menu:

form_checkbox_zeroone: stacked
form_checkbox_inline_zeroone: side by side

Radio button menu:

form_radio_zeroone: stacked
form_radio_inline_zeroone: side by side

Submit field:

form_submit_zeroone

User modules

Select mod_login_zeroone under template settings so that the login form is already styled to match the theme.

To show the form with placeholders only, select the template mod_login_placeholder_zeroone.

Change password

Select mod_changePassword_zeroone under template settings so that the module is already styled to match the theme.

Lost password

Select mod_lostPassword_zeroone under template settings so that the module is already styled to match the theme.

Registration

Select member_zeroone or member_grouped_zeroone under template settings so that the registration form is already styled to match the theme.

Personal data

Select member_zeroone or member_grouped_zeroone under template settings so that the personal data form is already styled to match the theme.

Form with placeholders

To show form fields in a simple form or registration form with placeholders only and without labels, you have to override the templates. In the left navigation, select Templates under Layout and duplicate the corresponding template with the button New template.

Text field:

form_textfield.html5

<?php $this->extend('form_row'); ?>

<?php $this->block('field'); ?>
  <?php if ($this->hasErrors()): ?>
    <p class="error"><?= $this->getErrorAsString() ?></p>
  <?php endif; ?>

  <input type="<?= $this->type ?>" name="<?= $this->name ?>" id="ctrl_<?= $this->id ?>" class="text<?php if ($this->hideInput): ?> password<?php endif; ?><?php if ($this->class): ?> <?= $this->class ?><?php endif; ?>" value="<?= Contao\StringUtil::specialchars($this->value) ?>"<?= $this->getAttributes() ?><?php if ($this->label): ?> placeholder="<?= $this->label ?><?php if ($this->mandatory): ?> *<?php endif; ?>"<?php endif; ?>>
<?php $this->endblock(); ?>

Select field:

form_select.html5

<?php $this->extend('form_row'); ?>

<?php $this->block('field'); ?>
  <?php if ($this->hasErrors()): ?>
    <p class="error"><?= $this->getErrorAsString() ?></p>
  <?php endif; ?>

  <?php if ($this->multiple): ?>
    <input type="hidden" name="<?= '[]' == substr($this->name, -2) ? substr($this->name, 0, -2) : $this->name ?>" value="">
  <?php endif; ?>

  <select name="<?= $this->name ?>" id="ctrl_<?= $this->id ?>" class="<?= $this->class ?>"<?= $this->getAttributes() ?>>
    <?php foreach ($this->getOptions() as $option): ?>
      <?php if ('group_start' == $option['type']): ?>
        <optgroup label="<?= $option['label'] ?>">
      <?php endif; ?>

      <?php if ('option' == $option['type']): ?>
    	<?php if($option['value'] == '') $option['label'] = $this->label; ?>
        <option value="<?= $option['value'] ?>"<?= $option['selected'] ?>><?= $option['label'] ?></option>
      <?php endif; ?>

      <?php if ('group_end' == $option['type']): ?>
        </optgroup>
      <?php endif; ?>
    <?php endforeach; ?>
  </select>
<?php $this->endblock(); ?>

Password field:

form_password.html5

<?php $this->extend('form_row'); ?>

<?php $this->block('field'); ?>
  <?php if ($this->hasErrors()): ?>
    <p class="error"><?= $this->getErrorAsString() ?></p>
  <?php endif; ?>

    <input type="password" name="<?= $this->name ?>" id="ctrl_<?= $this->id ?>" class="text password<?php if ($this->class): ?> <?= $this->class ?><?php endif; ?>" value="" autocomplete="new-password"<?= $this->getAttributes() ?><?php if ($this->label): ?> placeholder="<?= $this->label ?><?php if ($this->mandatory): ?> *<?php endif; ?>"<?php endif; ?>>
<?php $this->endblock(); ?>

Textarea:

form_textarea.html5

<?php $this->extend('form_row'); ?>

<?php $this->block('field'); ?>
  <?php if ($this->hasErrors()): ?>
    <p class="error"><?= $this->getErrorAsString() ?></p>
  <?php endif; ?>

  <textarea placeholder="<?= $this->label ?>" name="<?= $this->name ?>" id="ctrl_<?= $this->id ?>" class="textarea<?php if ($this->class): ?> <?= $this->class ?><?php endif; ?>" rows="<?= $this->rows ?>" cols="<?= $this->cols ?>"<?= $this->getAttributes() ?>><?= $this->value ?></textarea>
<?php $this->endblock(); ?>

In the 0.1 theme, the mega menu is available from version 1.13.0 (for Contao 4) or 2.3.0 (Contao 5).

You find an example of what it looks like on a finished website in our theme demo.

This is what it could look like on the website:

How do I activate it?

If you have a new Contao installation and have already imported the current theme demo, you can activate the mega menu simply by changing the page layout in the page settings.

If you can’t select it in your Contao installation yet, edit the navigation module and switch the module template and the navigation template to the templates with the suffix megamenu.

Adding images

You can also add an image for each menu item, which is shown in the mega menu.

News

News list

Follow these steps to place a news list:

Select the module Newslist (under News)
Make your settings (archives, number of items etc.)
Select the news template (template settings)
news_latest_zeroone (news list with images)
news_short_zeroone (news list without images)
news_simple (simple news list with date/author and title only)
Select the custom template mod_newslist_zeroone (template settings)
Select the image size News & Events / List view (image settings)
Add the CSS class columns (second input field) (expert settings)
Include it in an article with the element type Module

News list with images

News list without images

Simple news list

News reader

Follow these steps to place the news reader (detail view):

Select the module Newsreader (under News)
Make your settings (archives, fields)
Select the news template news_full_zeroone (template settings)
Select the image size News & Events / Detail view (image settings)
Include it in an article with the element type Module

Follow these steps to place a newsletter:

Select the module Subscribe or Unsubscribe (under Newsletter)
Make your settings (channels, redirect etc.)
Select the newsletter template nl_default_zeroone (template settings)
Include it in an article with the element type Module

Search

Follow these steps to place a search engine:

Select the module Search engine (under Applications)
Make your settings
Select the custom template mod_search_zeroone (template settings)
Include it in an article with the element type Module

Password forms

Personal data

Registration

Update

You can update the theme with the Contao Manager. Then open the install tool and update the database.

If a problem occurs after the update, have a look at our solutions.

Tip

A database backup beforehand never hurts!

Issues

If you ran into problems during installation or setup, or if you found a display issue of the theme in a specific browser, please open a new ticket:

All tickets Create a new ticket

Note

Please check first whether your bug is already known.

Known issues

# 1 Some images are not shown

Host: Mittwald

Solution: Switch your PHP version from FPM to CGI (under Tools > Software manager > Script languages).

# 2 An error occurred when opening the front end

Check in _custom_variables.scss (in the file manager under zeroOne/scss) whether the variable $scssPath exists and how the color schemes are included.

If the variable $scssPath exists in _custom_variables.scss, remove it.

//@import 'colour_schemes/earth';
//@import 'colour_schemes/night';

@import 'colour_schemes/dark_mode';

/*
 * Kommentieren Sie die folgende Zeile aus, wenn die Bilder nicht dem ent-
 * sprechenden Farbschema angepasst werden sollen.
 *
 * Uncomment the following line if the images should not be adjusted to the
 * colour scheme.
 */
@import 'colour_schemes/adjust_images';

Check in _custom_variables.scss (in the file manager under zeroOne/scss) whether the variable $scssPath exists and how the color schemes are included.

If the variable $scssPath doesn’t exist in _custom_variables.scss yet, add it before the import statements.

$scssPath: "../../../vendor/contao-themes-net/zero-one-theme-bundle/src/Resources/public/scss";

The lines under Colour Schemes should look like the following code example. It is important that #{$scssPath} is at the beginning.

//@import '#{$scssPath}/colour_schemes/earth';
//@import '#{$scssPath}/colour_schemes/night';

@import '#{$scssPath}/colour_schemes/dark_mode';

/*
 * Kommentieren Sie die folgende Zeile aus, wenn die Bilder nicht dem ent-
 * sprechenden Farbschema angepasst werden sollen.
 *
 * Uncomment the following line if the images should not be adjusted to the
 * colour scheme.
 */
@import '#{$scssPath}/colour_schemes/adjust_images';

Creuva Theme for Contao

Creuva – create something new. Creuva is a flexible theme for Contao 5.7 and Contao 6 based on the Theme Components Bundle. A single command sets up the theme, page layout, modules and website root, optionally with basic pages or a complete demo website.

Quick start

Buy a license
Installation
Demos: Standard, Company, Portfolio, Sports club
Report a problem

What’s included

17 color schemes, light, dark or system color mode, two typographies and four corner radii – all configurable in the page layout, with contrasts that meet WCAG 2.1 AA
Four demos (Standard / Creative, Company, Portfolio / Studio, Sports club) and a style guide with all elements
Custom content elements such as hero, logo bar and match pairing, plus many template variants (card, icon box, call to action, image & text, key figures, timeline, gallery slider …)
CSS classes via select fields using the CSS Style Selector: backgrounds, grids, spacing, buttons, animations
Search, Open Graph and link previews, lightbox, responsive images and self-hosted fonts
Export websites as templates and import them into other installations

The theme documentation covers these topics:

Requirements

	Contao 5.7	Contao 6
PHP	8.3 or higher	8.4 or higher
Page layout	Type “Modern”	Type “Modern”

Contao system requirements

The Contao Manager or Composer installs these extensions automatically:

Theme Components Bundle version 2.0 or higher
CSS Style Selector Bundle version 2.1 or higher

Creuva styles the modules for news, events, FAQ, newsletter, comments and listing, but they are optional. The demos only create news and events if the respective bundle is installed.

Tip

You can set up Creuva in an empty or in an existing installation. Existing content is kept, the theme comes with its own page layout.

Note

The demo files (icons, PDFs) are served via the symlink public/files/creuva-demo. On Windows, contao:symlinks needs administrator rights or developer mode for this, otherwise icons and downloads are missing.

License

Buying a license

You can get a license for Creuva at contao-themes.net. A license is valid for one domain including subdomains; for multiple websites you need several single licenses or a license for unlimited domains. You may use the theme for private and commercial projects.

Copyright notice

The bottom bar in the footer always contains the link “powered by contao-themes.net”. It is part of the license and may only be removed or changed with a license without copyright link – even if you only use the theme as a base and customize it.

Agencies and transfer

You can transfer the usage rights to your client once; the agency then loses its rights.
You need a new license for each additional project (except with the license for unlimited domains).
Reselling the theme or any of its parts is not allowed.

Demo content and libraries

Texts, images and other media in the demos are for preview purposes only and must not be used for your own websites. The bundled fonts (Plus Jakarta Sans and Fraunces under the SIL Open Font License 1.1) and the required packages are subject to their own licenses; you can find an overview in the bundle’s THIRD-PARTY-NOTICES.md file.

You can find the full license terms in the LICENSE file in the bundle.

Installation

Installation takes two steps: install the package, then set up the theme. You can do the setup in the back end under Layout › Creuva or on the console with creuva:install – both lead to the same result.

1. Install the package

With the Contao Manager

Open the Contao Manager (www.your-domain.com/contao-manager.phar.php), search for creuva in the Discover tab, add the package pdir/creuva-theme-bundle and click Apply changes. Then update the database when the Contao Manager prompts you to.

With Composer

composer require pdir/creuva-theme-bundle
vendor/bin/contao-console contao:migrate

2. Set up the theme in the back end

Log in to the back end as an administrator and open Layout › Creuva. Under Set up you choose what should be created:

Option	Result
Import a demo website	New website root with all pages, content, news, images and forms of a demo
Create an empty site structure	New website root with start, contact, imprint, privacy, accessibility statement, sitemap and search pages
Use an existing website	The Creuva layout is assigned to the selected website roots, the content stays unchanged
Only create the theme	Create the theme, modules and page layout; you assign the layout yourself later

For a new website root you enter the title, language and optionally the domain. You need the domain if there already is a website root with the same language and no domain. Below each form you find the matching console command and, after running it, the output.

Note

If the page reports that the database is not up to date, update it first in the Contao Manager or with contao:migrate.

What gets created

the theme “Creuva” with the modules main navigation, header, footer – brand, footer navigations, copyright and bottom links
a page layout of type “Modern” with the template page/layout/creuva, with all modules assigned to their slots
the image size “Logo” (480 × 120 px, 2x density), if the theme does not have one yet
the CSS styles for the CSS Style Selector
the assignment of the layout to the website root

The theme detects the contact, imprint, privacy, accessibility, sitemap and search pages of an existing website by their alias (kontakt, impressum, datenschutz, barrierefreiheit, sitemap, suche …) and links them in the header button, the header search and the footer. Module names and texts follow the language of the website root (German or English).

2. Set up the theme on the console

# Existing website: the website root is queried or passed by ID
vendor/bin/contao-console creuva:install --root=1

# New website with basic pages
vendor/bin/contao-console creuva:install --with-pages --site-title="My Company" --dns=example.org

# Complete demo website with sample content, images, news and form
vendor/bin/contao-console creuva:install --demo

Option	Description
`--root=<ID>`	Website root that receives the Creuva layout (can be used multiple times)
`--with-pages`	Create a new website root with basic pages (automatic if there is none yet)
`--demo[=<name>]`	Create a new website root with a demo: `standard` (default), `unternehmen`, `portfolio`, `sportverein` or a folder such as `files/my-demo`
`--site-title`, `--language`, `--dns`	Title, language (default `de`) and domain of the new website root
`--scheme`	Color scheme, e.g. `green` (default), `petrol`, `blue` – see Color schemes
`--variant`	Color mode: `light` (default), `dark`, `auto` (follows the system setting)
`--typography`	`modern` (default, Plus Jakarta Sans) or `editorial` (headings in Fraunces)
`--theme-name`	Name of the theme (default “Creuva”), e.g. for a second variant
`--replace`	Delete the website with the same domain and language, including its theme, beforehand, see Reset content
`--reset`	Delete all Contao content beforehand
`--force`, `--no-backup`	With `--reset`/`--replace`: without confirmation or without a database backup

Notes

Error message: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Demo icons and downloads are missing

Run vendor/bin/contao-console contao:symlinks so that public/files/creuva-demo is created.

Search finds nothing

Build the search index once after the setup: System › Maintenance or contao:crawl.

Manual setup

creuva:install or Layout › Creuva takes care of these steps for you. If you prefer to put the theme together yourself, proceed as follows:

1. Theme and modules

Create a new theme under Layout › Themes and add these modules to it:

Navigation menu (2 levels) for the main menu
Creuva › Creuva header – logo, navigation module, CTA button, optional search; contains the mobile menu
optionally Search engine on a hidden “Search” page (see Search)
Creuva › Creuva brand – logo, claim and social media links for the footer (the platform is detected from the URL)
Custom navigation with a headline for each footer column (e.g. Services, Company, Legal)
optionally Custom HTML code for the copyright and a custom navigation for the links at the bottom right
optionally Creuva › Creuva style switcher for trying out the color schemes (see Style switcher)

2. Page layout

Create a page layout of type “Modern” with the template page/layout/creuva and assign the modules to the slots:

Slot	Content
`top`	optional bar, style switcher
`header`	Creuva header
`main`	articles
`prefooter`	optional, e.g. a logo bar above the footer
`footer`	Creuva brand and footer navigations
`bottom`	copyright, sitemap, cookie settings

The bottom bar always contains the link “powered by contao-themes.net”, see License.

3. Design

In the page layout, set the color scheme, color mode, typography, corner radius and animations under Creuva design, see Design.

4. Import CSS styles

To make the Creuva classes available as select fields:

vendor/bin/contao-console creuva:css-styles

Accessibility

Give each navigation module a unique ARIA label under Expert settings, e.g. “Main navigation”, “Services”, “Service links”.
The headlines of the footer columns should be h2.
In forms, set the Autocomplete field for name, email, phone etc. (name, email, tel, organization).

The installer and the demos already do this.

Demos and styleguide

Creuva comes with four demos. Each one is imported as a website root of its own – in the back end under Layout › Creuva › Set up (option “Import a demo website”) or on the console. In an existing installation, you add the demo alongside with its own domain (--dns) or language (--language).

Demo	Command	For	Live
Standard / Creative	`creuva:install --demo`	Agencies, freelancers, small businesses	View
Company	`creuva:install --demo=unternehmen`	Mid-sized companies, industry, trades	View
Portfolio / Studio	`creuva:install --demo=portfolio`	Photographers, architects, creative studios	View
Sports club	`creuva:install --demo=sportverein`	Football and sports clubs, associations	View

All demos use only core elements, Creuva elements and template variants, so they work the same in Contao 5.7 and 6. The elements are independent of the demos: whatever a demo shows, you can use on any Creuva website.

Note

The texts, images and media of the demos are for preview purposes only and must not be used on your own websites. The contact form does not send any emails – add the sending in the form generator.

Standard / Creative

Pages: home page, services (web design, development, consulting), projects with six project pages, about us with team, pricing, news & knowledge with FAQ and downloads, contact with thank-you page, legal notice, privacy policy, accessibility statement, sitemap, search and a 404 page
Modules: main navigation, header with CTA and search, footer with four columns and social media links, news list and reader, sitemap, search engine
Image sizes for every spot in the layout (logo, hero, card, image & text, wide, team, avatar, news, gallery) with several widths, WebP and lazy loading
News archive with three posts (only with the News bundle installed)
Files under files/creuva-demo/standard/ (illustrations, icons, PDFs) with alt texts
Favicon in the website root and the style switcher for trying out the color schemes

Company

A classic company website (“Kessler Metalltechnik GmbH”, Light, color scheme Ocean, square corners):

Pages: home page with key figures, services and industries; services with machinery; industry solutions; references; company with history, certificates and locations; careers with job offers and online application (file upload); download center; news; contact with contact persons
Job offers are news items in the archive “Stellenangebote” with the list template news_creuva_job (see News)
Process steps as a template variant of the description list

Portfolio / Studio

For photographers, architects and creative studios (“Studio Lichtung”, typography Editorial, color scheme Terracotta, small corners):

Pages: home page with full-screen hero, works with six project pages, image archive (masonry gallery with lightbox), studio with team, services with pricing and FAQ, journal, contact
Project pages: full-screen hero, project data (facts), text, a different gallery arrangement or a slider with thumbnails on each page, and a link to the next project
Image tiles (creuva_tile), logo bar and the grid class “Versetzt” (offset, u-grid-offset)

Sports club

For football and sports clubs (“TSV Rotenbach 1921”, Light, color scheme Red, medium corners, crest as logo):

Pages: home page with next match and latest result, teams with training times and league table, fixtures, club with board and sports park, news, sponsors with packages, membership with online application and membership form (PDF)
Fixtures and results are events in the calendar “Spielplan”. Their dates are relative to the day of the import, so the next matches are always in the future.
Content element “Match” and table class “Liga-Tabelle” (league table, u-table-league)

Styleguide

The styleguide shows all elements, template variants, CSS classes and modules of the theme on one page: colors, typography, buttons, lists, tables, media, key figures, accordion, backgrounds, animations, all form fields, breadcrumb and news list. It is independent of the demos and can be added to any Creuva website – under Layout › Creuva › Styleguide or on the console:

vendor/bin/contao-console creuva:styleguide --root=1
vendor/bin/contao-console creuva:styleguide --root=1 --replace   # recreate after a theme update

Page “Styleguide” (alias styleguide) at the end of the website, not in the navigation, not in the search index and with noindex,nofollow
its own modules, a form and a news archive with the prefix “Styleguide – "
files under files/creuva-demo/styleguide/

The demos install the styleguide as well.

Accessibility statement

Every demo comes with the page zugaenglichkeitserklaerung, linked in the footer. Each section is a text element of its own; sections that don’t fit every website (PDF documents, videos, maps, third parties, BFSG, dispute resolution …) are hidden and can be shown via the eye icon. --with-pages creates the page with a placeholder.

Note

The text is a template. The theme alone does not make a website accessible; the date and details must match the website in question.

Custom demo and export

You can export a website as a template and import it into another installation – e.g. as a starter package for client projects. The template is a folder with a demo.yaml and the files used, the same structure as the bundled demos.

Exporting a website

In the back end under Layout › Creuva › Export a website (administrators only), you choose the website root and optionally a title and folder name. Below, all exports are listed with date, number of files and size; you can download them as a ZIP and delete them. On the console:

vendor/bin/contao-console creuva:export
vendor/bin/contao-console creuva:export 1 --name=kunde-x --title="Kunde X"

var/exports/kunde-x/
├── demo.yaml       pages, contents, modules, forms, news, events, image sizes, design
└── files/          the files used

The export includes:

the page tree with articles and content elements, and the modules, forms, news and events used in it
the image sizes of the theme and all sizes used in contents
all referenced files with alt texts
header, logos, brand and footer columns from the Creuva modules
color scheme, color mode, typography, corner radius and logo height, plus the favicon and preview image of the website root

Not exported are custom colors of the layout, recipient addresses of forms, tables of other extensions and the styleguide page (it is recreated on import). Insert tags with IDs such as {{insert_module::3}} and the elements “Content element” and “Article” (aliases) cannot be transferred; the export lists them as warnings. Page links such as {{link_url::12}} are converted to aliases.

Tip

To move a complete website, a database backup is the better way. The export is meant for templates.

Importing a custom demo

Unzip the ZIP and copy the folder to files/<name>. Do not make the folder public, otherwise the demo.yaml can be accessed on the web.
Under Layout › Creuva › Set up, enter files/<name> in “Or own folder”, or:

vendor/bin/contao-console creuva:install --demo=files/kunde-x

The files are copied to files/creuva-demo/local-<folder name>/, the source folder stays unchanged. With filesFolder: inhalte in the demo.yaml, they end up in files/inhalte/ instead; this folder is not deleted by creuva:reset.

Structure of the demo.yaml

The definition is YAML. You write references as page:<alias>, module:<key>, image_size:<key>, news_archive:<key>, calendar:<key> or file:<path>. An example with the most important sections:

design:
  scheme: green       # color scheme, color mode, typography and corner radius of the page layout
  variant: light
  typography: modern
  radius: large
  logoHeight: 4rem
  stylesheets: ['files/design/custom.css']   # created if it does not exist
header:
  logo: file:design/logo.png
  search: suche       # alias of the search results page
brand:
  logo: file:design/logo-hell.png
bottom: ['impressum', 'datenschutz', 'sitemap']   # links next to the copyright
imageSizes:
  card:
    name: Karte (4:3)
    width: 800
    height: 600
    resizeMode: crop
    densities: 400w, 600w, 800w
    sizes: '(min-width: 80rem) 384px, (min-width: 44rem) 31vw, calc(100vw - 2rem)'
    lazyLoading: true
pages:
  - title: Start
    articles:
      - elements:
          - { type: 'image', singleSRC: 'file:bilder/foto.jpg', size: 'image_size:card' }
modules:
  newslist: { name: 'News', type: 'newslist', news_archives: ['news_archive:blog'], imgSize: 'image_size:card' }
layout:
  prefooter: [partner]   # additional modules in sections of the page layout
styleguide: true

You define events under events:; the date is a strtotime() expression ("2026-12-05", "5 December"), relative values such as 'date:next saturday 15:00' are possible as well. The bundled demos in the bundle’s demo/ folder are the best template.

Image sizes of the demos

Each image size is meant for one spot in the layout, so the browser doesn’t load more than necessary:

Key	Name	For
`logo`	Logo	Logo in header and footer
`hero`	Hero	Image in the hero element
`cover`	Vollbild (16:9)	Full-width hero
`card`	Karte (4:3)	Cards in three or four columns, slider with several cards
`media`	Bild & Text (4:3)	Template variant “Image & text”, cards in two columns
`wide`	Breit	Image across the content width
`tile-portrait`, `tile-landscape`	Kachel hoch/quer	Image tiles
`slider`	Slider (3:2)	Images in a slider across the content width
`team`, `avatar`	Team, Avatar	Portrait and testimonial
`news`, `news-detail`	News-Teaser, News-Detail	News list and header of the news reader
`gallery`	Galerie (responsiv)	Galleries, the gallery template sets `sizes` per image

Resetting contents

The demo import does not overwrite any existing contents. To import a demo again or to put an installation back into the state right after a fresh install, there are two ways.

Warning

Both commands delete contents. A database backup is created automatically beforehand – only turn it off if you are sure.

Deleting all contents (`creuva:reset`)

# Delete all contents (with confirmation and database backup)
vendor/bin/contao-console creuva:reset

# Delete contents and import the demo again
vendor/bin/contao-console creuva:install --demo --reset

In the back end, this corresponds to the option “Delete all contents first” under Layout › Creuva › Set up.

All Contao tables are emptied: site structure, articles, content elements, themes, modules, layouts, forms, news, versions, search index etc. The IDs start at 1 again.
Back end users and user groups, members and member groups and the file manager are kept.
Of the files, only the demo folder files/creuva-demo is deleted.
The backup is stored under var/backups/creuva-reset__<timestamp>.sql.gz; restore it with contao:backup:restore <file name>.
Without confirmation (e.g. in scripts): --force, without backup: --no-backup.

Replacing one website of a multisite installation (`--replace`)

--reset deletes all websites. If several websites run in one installation, --replace only replaces the website that the import would create:

vendor/bin/contao-console creuva:install --demo=files/meine-demo \
    --site-title="Meine Firma" --dns=example.org --theme-name="Meine Firma" --replace

This deletes the website roots with the same domain and language including their subpages and contents, the theme with the name from --theme-name and the themes whose layouts this website uses, as well as forms, news archives and calendars – but only if no other website uses them.

If the theme is also used by another website, the command aborts without deleting anything.
Before deleting, the command lists all affected records and asks for confirmation.
Files are kept; the import overwrites the demo files, their UUIDs stay the same.
If there is no matching website yet, --replace simply creates it.
Cannot be combined with --reset and --root; requires --demo or --with-pages.

Afterwards, rebuild the search index with contao:crawl.

Design

You set up the look in the page layout under Creuva design. Below the fields, a live preview shows a heading, buttons and boxes with the current selection.

Field	Options
Color scheme	17 schemes, see below
Color mode	Light / Minimal, Dark / Creative, Light or dark by system setting
Typography	Modern (Plus Jakarta Sans) or Editorial (headings in Fraunces) – can be combined with any color mode
Corner radius	Square, Small, Medium, Large – rounding of cards, buttons and images
Primary color, Accent color	optional custom colors as a hex value without `#`, they override the scheme
Logo height	Height of the logo in the header as a CSS value, e.g. `4rem` (default `2.25rem`); the header grows with it
Own stylesheets	CSS files from the file manager, see Custom CSS
Animations	All sections, CSS class only, None

Tip

The live preview checks custom colors: it shows a notice if white text on the primary color, or the accent color as text on white, falls below a contrast ratio of 4.5:1. The accent color is also used for links and small text.

Color schemes

Each scheme consists of a primary color (buttons, dark areas, links; it also tints backgrounds, borders and text) and an accent color (accents, badges, icons, focus outlines). All schemes meet the WCAG contrast requirements (text 4.5:1, large text and graphics 3:1) in light and dark mode.

Scheme	Key	Primary	Accent
Green (default)	`green`	`#1d3b2a`	`#3c9a2f`
Sage	`sage`	`#2f3e36`	`#52755f`
Olive	`olive`	`#2e3220`	`#647219`
Graphite & lime	`lime`	`#1c1f22`	`#b5e61d`
Petrol	`petrol`	`#0f3a40`	`#0b7d7d`
Ocean	`ocean`	`#0b2545`	`#08759a`
Blue	`blue`	`#1b2f4b`	`#2f6fd6`
Indigo	`indigo`	`#1a1b4b`	`#4f46e5`
Violet	`violet`	`#2a1846`	`#7c4dff`
Plum	`plum`	`#33152e`	`#9c3d8f`
Magenta	`magenta`	`#3d1430`	`#c92a63`
Red	`red`	`#3f1418`	`#c8323a`
Bordeaux	`bordeaux`	`#3b0d1f`	`#a3214e`
Terracotta	`terracotta`	`#3b2219`	`#b84f24`
Orange	`orange`	`#2d1b0e`	`#f08c00`
Yellow	`yellow`	`#26241c`	`#f2b705`
Midnight & gold	`gold`	`#141a2e`	`#c9a227`

You need the key for creuva:install --scheme=…, for the demo.yaml and for links to the style switcher.

Color mode “System”

With “Light or dark by system setting”, the website appears light or dark depending on what the visitor has set in their operating system or browser, and switches along when the setting changes. A small script sets the mode before the first render, so the page doesn’t flash. Without JavaScript, it stays light.

Design per website

In the website root, you can additionally set color scheme, color mode, typography and corner radius under “Creuva design”. These values take precedence over the page layout; a scheme in the website root also replaces the custom colors of the layout. This way, several websites can share one layout and still look different.

The installer and the demos leave the fields in the website root empty (“As in the page layout”), so changes in the page layout become visible right away.

Animations

Setting	Effect
All sections (default)	All elements in the main section fade in from below on scroll, grids and news lists element by element, “Image & text” from both sides; key figures count up
CSS class only	Only elements with a class from “Animation” (see CSS classes)
None	No scroll animations, no intro animation in the hero, numbers appear immediately

The u-reveal-* classes set the direction per element and take precedence; u-reveal-none excludes an element or a whole article.
Contents that are already visible on load are never hidden; without JavaScript, everything is visible right away.
Visitors who have “Reduce motion” turned on in their system settings don’t see any animations.
Hover effects (cards lift, images zoom, arrows move along) are always active.

You can adjust duration, distance and delay with CSS:

:root {
  --reveal-duration: 0.6s;   /* default 0.8s */
  --reveal-distance: 1.5rem; /* default 2.5rem */
  --reveal-stagger: 60ms;    /* delay per element in the grid */
  --hover-lift: -4px;        /* lift of cards on hover */
}

Fonts

Plus Jakarta Sans and Fraunces ship with the theme and are self-hosted, so there are no requests to Google. The browser only loads Fraunces if the typography “Editorial” is selected.

Style switcher

The front end module Creuva › Creuva style switcher shows a cog on the left edge. Visitors can use it to try out color scheme, color mode (Light, Dark, System), typography (Modern, Editorial) and corner radius live – ideal for a demo or for choosing a color scheme together with clients.

Setting it up

Create a module of the type Creuva style switcher under Layout › Themes › Modules (the demos already have one).
Assign it to the top section in the page layout, so the selection takes effect before the first render.

The selection is only stored in the browser (localStorage) and applies to all pages with the module.

Linking a combination

You can link to a combination directly, e.g.:

https://www.deine-domain.de/?scheme=red&theme=dark&typography=editorial&radius=none

Parameter	Values
`scheme`	Key of the color scheme, e.g. `petrol`
`theme`	`light`, `dark`, `auto`
`typography`	`modern`, `editorial`
`radius`	`none`, `small`, `medium`, `large`

Saving the selection for the website

In the front end preview, the switcher additionally shows administrators the button “Save for the website”. It saves the selection in the website root of the current website, clears the page cache and then applies to all visitors. Editors without admin rights and regular visitors don’t see the button.

Back end users only

With the module option “Logged in back end users only”, the switcher is invisible to visitors. It only appears when you are logged in to the back end; a selection previously stored in the browser then no longer applies to visitors.

Note

Set this option on live websites. Without it, every visitor sees the switcher.

Custom CSS and templates

Own stylesheets

Create a CSS file in the file manager, e.g. files/design/custom.css, and select it in the page layout under Creuva design › Own stylesheets. It is loaded after the Creuva CSS, with its modification time for cache busting. The folder must be public.

All Creuva styles live in CSS cascade layers (creuva.*). This means your own styles without a layer always take precedence – without !important and without long selectors.

Colors, spacing and rounding

Colors, spacing and typography are CSS variables and are easy to override:

:root {
  --scheme-primary: #123456; /* primary color incl. tinted backgrounds */
  --radius-l: 0.75rem;
}

For custom primary and accent colors, the page layout is usually enough (see Design).

Accordion with a custom icon

Give the accordion the class u-accordion-icon plus a class of your own, and set the icon with CSS:

.content-accordion.mein-icon {
  --accordion-icon-mask: url("/files/icons/paket.svg");
}

Customizing templates

All templates are Twig templates and can be overridden in the templates/ folder as usual, e.g. templates/content_element/creuva_hero.html.twig:

{% extends '@Contao/content_element/creuva_hero.html.twig' %}

Print

Only the content is printed, black on white, without header, footer, breadcrumb, slider controls and backgrounds. Links in the text appear with their address, accordions are expanded, and cards and images are not split across pages.

Elements and modules

Creuva comes with its own content elements and modules and styles the Contao core elements. The Styleguide shows how everything looks together.

Content elements

Element	Description
Creuva › Hero	Intro section with kicker, headline with highlighted part, text, two buttons, image and badge
Logo bar (`creuva_logos`)	Client or partner logos; no background of its own, the section defines it
Match (`creuva_match`)	Competition, home and away team with crests, kick-off, venue, optional result and button

Hero

The hero image comes in several shapes:

Organic – image with an organic mask
Rounded – the whole image with a shadow and an accent shape behind it
Image unchanged
Image unchanged with accent shape – no shadow and no cropping, ideal for cut-out images with a transparent background
Full screen (text on the image) – hero across the full width, portrait format on phones

The badge appears as a small card with check marks, one line per point. Image and text are optional.

Logo bar

You link the logos via the file metadata (“Link” field). In dark mode the logos sit on a light surface so that dark and colored logos stay readable. The exceptions are the background „Primär (dunkel)“ (primary, dark) and the class u-logos-original, both meant for white logos. The logo bar is also available as a module, e.g. for the prefooter slot above the footer.

Match

Without a result, the element shows the kick-off time (next match); with a result, it shows the final score. The matching table class is „Liga-Tabelle“ (league table, u-table-league): a compact table with centered numbers; your own team is highlighted if it is bold in the table.

Modules

Module	Description
Creuva header	Logo, main navigation with dropdowns, CTA button, mobile menu and the optional search
Creuva brand	Logo, claim and social media links for the footer; the platform is detected from the URL
Logo bar	like the content element, for the slots of the page layout
Creuva style switcher	Try out color scheme, color mode, typography and corner radius, see Style switcher

A full-width contact section below the footer columns is an HTML module with the class c-footer-contact in the footer slot (see the standard demo for an example).

Styled core elements

Creuva also styles:

the Contao core elements: text, list, description list, table, image, gallery, content slider, accordion, downloads (with file type and size, e.g. “PDF · 245 KB”), hyperlink, code, top link, forms, breadcrumb, search
the news modules (list as cards, reader, archive menu, pagination)
events (list with date badge, reader, month and mini calendar, menu), FAQ, newsletter, comments and listing
the elements of the Theme Components Bundle 2.0: content box, teaser box, price box, feature element, simple box, icon tile, modal
select fields in forms, without JavaScript

Accordion

Each entry is a card with a round plus/minus toggle. To add an icon in front of the question, set a class on the accordion element: u-accordion-icon (question mark), u-accordion-info or u-accordion-chat. You can add an icon of your own with CSS, see Custom CSS.

Sections with a background

You can also select the background classes (u-bg-muted, u-bg-accent, u-bg-primary) on an article – the article then becomes a full-width section with a background.

Every article has section spacing at the top and bottom. If two articles without a background or with the same background follow each other, the top spacing of the second one is dropped so it doesn’t double up. You can adjust individual articles in the CSS Style Selector under „Abstände“ (spacing).

Topics

Template variants

You can choose these variants under Template settings › Custom template. All of them work independently of the demos; the Styleguide shows examples.

Text

Variant	Use
`creuva_card`	Card with image, category (subline), title and text; the last link makes the whole card clickable
`creuva_feature`	Icon box with a round icon (SVG or small image); on hover the card lifts and the icon is filled with the primary color
`creuva_cta`	Call to action: a surface with kicker, two-tone headline and text on the left, the links in the last paragraph as buttons on the right (the first one filled, the others as outlines)
`creuva_media`	Image & text: image left, right, above or below (image alignment), kicker, two-tone headline, text with a check list; links in the last paragraph become buttons
`creuva_testimonial`	Testimonial: quote in the text, name as headline, role as subline, portrait as image
`creuva_team`	Team member: portrait, name, role (subline), contact
`creuva_price`	Price card: package as headline, price as subline, list of features, last link as button; highlighted with `u-featured`
`creuva_tile`	Image tile: image in the proportions of its image size, the whole tile is clickable

Icon box: In the CSS Style Selector under „Elementoptionen › Icon-Box“ (element options › icon box) you find „Ohne Karte“ (without card, u-feature-plain, e.g. benefits in a row) and „Icon links, ohne Karte“ (icon on the left, u-feature-inline, e.g. contact details).

Call to action: You choose the color under „Farben des Elements“ (element colors: white, gray, light accent, accent color, outline; text and buttons adapt). „Call to Action › Zentriert“ (centered, u-cta-stacked) puts the buttons below the text. To span the full window width, use „Breite › Volle Breite“ (width › full width, u-full-bleed) – then set „Innenabstand oben und unten: Kein“ (top and bottom padding: none) on the article.

Description list

Variant	Use
`creuva_stats`	Key figures as cards: term = number, description = label
`creuva_timeline`	Timeline: term = year/step, description = event; horizontal as soon as the element is wide enough, vertical in a grid column
`creuva_facts`	Facts as a card, e.g. project data: term = label (“Client”), description = value
`creuva_steps`	Process steps: numbered steps, side by side with a connecting line from tablet width up

Key figures: Characters before or after the number ("+", “%”, “o’clock”) are highlighted, and the numbers count up while you scroll. Ranges such as “11–20” don’t count up, and dates stay unchanged. Optionally, an icon sits above each number (field Icons (key figures), in the order of the entries). With u-no-countup the numbers don’t count up.

Gallery

Variant	Use
`creuva_slider`	Gallery as a slider: Images per row sets how many images a slide shows (1–6; at most two on tablets, one on phones); Full-size view opens the lightbox

You can find more about galleries under Sliders and galleries.

Links as buttons

In boxes with u-bg-primary or u-bg-accent, a link that stands alone in the last paragraph is automatically shown as a button. In texts with u-lead and in section headers it becomes an arrow link (“View all services →”).

Headlines and text

Headline addition

The Theme Components Bundle adds a subline to headlines. Creuva calls the field “Headline addition”:

addition without a checkbox → small line above the headline (“WHAT WE DO”)
addition with “Two-tone headline” → addition and headline in one line, the actual headline appears in the accent color (“More than just an agency.”)
addition with “Show addition below” → line below the headline

Kicker

Text elements and description lists also have the Kicker field: small uppercase text above the headline. Together with a two-tone headline you get the combination used on the demo home page (“CREATIVE PARTNERS ON EQUAL TERMS – More than just an agency.”).

Section header

Headline on the left, intro and link on the right: create an element group with the classes u-grid-2 u-align-end, and inside it a headline element and a text element with the class u-lead whose last paragraph contains only the link.

Text formats in the editor

The text editor has a “Formats” menu with the theme’s text styles:

Text: Accent color, Highlight, Muted – for selected words
Paragraph: Lead (larger), Kicker
Links: Button, Secondary button – select the link and choose the format

Buttons

In the CSS Style Selector, „Primär-Button“ (primary), „Sekundär-Button“ (secondary), „Akzent-Button“ (accent) or „Outline“ turn a hyperlink element into a button. On a text element with this selection, the links in the last paragraph become buttons, side by side. In “Image & text” and in call-to-action boxes this happens automatically.

Sliders and galleries

Content slider

In the content slider element, every element inside is a slide: images, cards, testimonials, texts or whole element groups. Creuva adds the following to the slider settings:

Elements per view (1–4): at most two on tablets, one on phones
Navigation arrows and Dots: can be turned off individually, shown in a bar below the slides; they are hidden when all elements fit into the view
Thumbnails: preview images below the slider, taken from the first image of each slide, e.g. for an image gallery

Autoplay (delay), speed, start slide and loop are the Contao fields. Cards and boxes in a row have the same height.

Gallery

You set the columns with Images per row (1–6), and Full-size view opens the lightbox. You can choose more layouts in the CSS Style Selector under „Galerie-Anordnung“ (gallery layout):

Class	Layout
`u-gallery-mosaic`	large image on the left, next to it one wide and two small ones, four images each
`u-gallery-mosaic-right`	like the mosaic, large image on the right
`u-gallery-featured`	first image across the full width
`u-gallery-masonry`	images in their own height – choose an image size without cropping

Image size

A gallery has only one image size for all images. So that every tile still loads a suitable image, the demos and the Styleguide include the image size „Galerie (responsiv)“ (gallery, responsive; proportional, widths from 320 to 1600 px). The gallery template sets the right sizes value for every image, depending on the layout, the position and “Images per row”. The important part set in the file manager stays visible in the tile.

For your own galleries, choose this image size or create one following the same principle – the widths are enough.

Tip

The format of an image is defined by the image size, not by the CSS. Gallery grids and gallery sliders need a size with fixed cropping for images of equal height (e.g. „Karte (4:3)“, card 4:3). Mosaic and „Erstes Bild groß“ (first image large) fill their tiles with any size, masonry needs a size without cropping.

With Full-size view/new window, images in the gallery and the image element open the Creuva lightbox: dark background, caption or title from the metadata, counter, previous/next, keyboard (Esc, arrow keys) and swiping on phones. The images of a gallery form a group. You don’t need any jQuery or MooTools templates in the page layout for this.

Preferred loading

The first large image on a page (at least 400 px wide, in the first article, e.g. the hero image) is automatically prioritized and loaded without lazy loading. This improves the Largest Contentful Paint in PageSpeed. If a page starts with text, all images stay unchanged.

News and events

News list

The news list shows the items as cards. With the class u-news-no-author on the module (news list, news reader or news archive) you hide the author; the date stays.

Job offers

The list template news_creuva_job shows news items as job ads: a card with title, tags and teaser. The tags come from the subline, separated by “·”, e.g. “Full-time · Neuburg · starting now”. The “Company” demo has an example.

News reader

The news reader shows a header like the hero: archive, date and reading time as the kicker, headline, subheadline as intro and author, next to it the news item’s image (image size in the News reader module). The content elements follow in the reading column.

Highlighted part: In the news item you find this field next to the headline. The text you enter appears in the accent color, e.g. “Accessibility becomes mandatory – what websites need now”. It must appear exactly like this in the headline. In lists, in the page title and in search engines the headline stays single-colored.

Reading time: The words of the content elements divided by 200 words per minute, rounded up, at least one minute. Headline, teaser and images don’t count.

Caption: Lists show no caption. The news reader only shows it if it is entered in the news item itself under Overwrite metadata; the caption from the file manager is not used.

Events

The event list shows events with a date badge. The event reader, month and mini calendar and the event menu are styled as well. The “Sports club” demo uses events for the fixtures and results.

CSS classes

All Creuva classes are available as styles in the CSS Style Selector, in the CSS style section of content elements, articles and modules. So you don’t need to remember any class names – you just select them.

Categories and groups

The classes are sorted into categories (e.g. „Abstände“, spacing) and, within them, into groups (e.g. „Innenabstand oben und unten“, top and bottom padding). Each group appears in the element as a select field with exactly one style. An element only shows the groups that fit its type – „Raster“ (grid), for example, only on element groups, „Buttons“ only on hyperlink and text elements.

Categories and groups are normal records. Under Layout › CSS styles you can change them, sort them by drag and drop and add your own categories and groups. Sections and element types always apply to the whole group.

Importing the classes

The classes are imported

automatically by creuva:install,
once by contao:migrate on existing websites, as long as no Creuva group exists yet,
after a theme update with new classes, by this command:

vendor/bin/contao-console creuva:css-styles

The import only adds what is missing. Your changes in the back end – titles, element types, removed styles, your own categories and groups – are kept.

Switching from the Style Manager

The classes are still stored in the CSS class field, so the front end stays unchanged. After the update, contao:migrate creates the Creuva groups and transfers the selection. You recreate your own Style Manager groups as CSS styles. Afterwards you can delete the tables tl_style_manager_archive and tl_style_manager as well as the styleManager columns.

Tip

The classes also work directly in the CSS class field, e.g. in places without a CSS style selection.

Overview of the classes

Area	Classes
Background	`u-bg-surface`, `u-bg-muted`, `u-bg-accent`, `u-bg-primary`
Width	`u-full-bleed` (background across the full width), `u-narrow`
Frame	`u-card`, `u-featured` (highlighted price card)
Grid (element group)	`u-grid-2`, `u-grid-3`, `u-grid-4`; alignment `u-align-start` (don’t stretch columns), `u-align-center`, `u-align-end`; column width with two columns `u-cols-wide-start`, `u-cols-wide-end` (3 : 2)
Table	`u-table-compare` (package comparison: columns 2–4 colored, “✓”/"–" as icons), `u-table-league` (league table)
News	`u-news-no-author` (hide author)
Spacing	padding `u-py-` (top and bottom), `u-pt-` (top), `u-pb-` (bottom); margin `u-my-`, `u-mt-`, `u-mb-` – each `0`, `s`, `m`, `l`, `xl`
Text	`u-text-left`, `u-text-center`, `u-text-right`, `u-lead`, `u-muted`, `u-accent`, `u-kicker`
Buttons	`u-button` (primary), `u-button-secondary` (white), `u-button-accent`, `u-button-outline`, `u-button-outline-accent`
Element colors	`u-card-white`, `u-card-muted`, `u-card-soft`, `u-card-primary`, `u-card-accent`, `u-card-outline-primary`, `u-card-outline-accent`, `u-card-flat`, `u-card-none`
Icon color	`u-icon-soft` (default), `u-icon-accent`, `u-icon-primary`, `u-icon-white`, `u-icon-light`, `u-icon-plain`, `u-icon-original`
Icon box	`u-feature-plain` (without card), `u-feature-inline` (icon on the left)
Call to action	`u-cta-stacked` (centered, buttons below the text)
Gallery	`u-gallery-mosaic`, `u-gallery-mosaic-right`, `u-gallery-featured`, `u-gallery-masonry`
Animation	`u-reveal-up`, `u-reveal-left`, `u-reveal-right`, `u-reveal-down`, `u-reveal-zoom`, `u-reveal-blur`, `u-reveal-fade`, `u-reveal-none`, `u-reveal-stagger` (content one after another), `u-no-countup`
Elements	`u-accordion-icon`, `u-accordion-info`, `u-accordion-chat`, `u-media-plain` (image & text without accent surface)
Visibility	`u-hide-mobile`, `u-hide-desktop`

Element colors

Cards, icon boxes, testimonials, price cards and the boxes of the Theme Components Bundle get a surface (white, gray, light accent, primary or accent color) or just a colored outline. On dark surfaces, text, links and kickers automatically switch to the contrast color.

You set the circle behind the icon of an icon box separately. With the primary and accent color the icon turns white; this works with single-colored SVG icons. SVG icons are colored in the color scheme; with u-icon-original they keep the colors of the file (e.g. multicolored icons). PNG and JPG images always keep their colors.

For key figures, the selection applies to each individual number. Without a selection they only have a light surface on a dark background, and with u-card-none not even there.

Technically, the classes only set CSS variables (--card-bg, --card-border, --icon-bg …) that all cards read – see Custom CSS.

Search and SEO

Search

The Creuva header can show a magnifying glass (field Search in the header, legend Search). It opens a search field above the page – also with Ctrl+K (⌘+K) or / – and sends the search terms to the selected search results page. Without the checkbox, no magnifying glass appears.

The results page holds the core module Website search. Creuva styles it with its own templates: a large search field, results as cards with the page path, highlighted search terms and an optional image, plus tips when nothing was found.

creuva:install --with-pages and the demos create the page „Suche“ (search; hidden, noindex, not in the search index) and activate the search in the header. In a demo definition of your own, header: { search: suche } (alias of the results page) is enough.

The page layout only adds the main section to the search index. Header, footer and copyright therefore don’t show up in the search results.

Note

Rebuild the search index once after an update: back end › System › Maintenance or

vendor/bin/contao-console contao:crawl

Search engines and link previews

On all indexable pages, the Creuva layout outputs Open Graph tags and twitter:card: title, description, address (as in the canonical link, without tracking parameters), language (og:locale, e.g. de_DE) and a preview image of 1200 × 630 px.

For the preview image, the layout uses, in this order:

on pages with a news reader, the image of the news item – the item then appears as og:type “article” with publication and modification date
the first hero, image or other element with an image in the main section, also inside element groups
the Preview image for social networks in the website root (metadata, field creuvaOgImage)

SVG files are skipped, WebP, AVIF and GIF are output as PNG, and JPEG stays JPEG. Smaller images are not upscaled.

Tip

Set a preview image for social networks in the website root. Then pages without an image also get a link preview.

Canonical

Website roots created by creuva:install have the canonical tag enabled. On existing websites, you enable it in the website root. The Styleguide is set to noindex,nofollow.

Update

You update Creuva like any other Contao bundle, using the Contao Manager or Composer:

composer update pdir/creuva-theme-bundle

Then run the database migrations – in the Contao Manager via Update database or on the console:

vendor/bin/contao-console contao:migrate

The migrations apply changes to the page layout, CSS styles and settings. Your content and the design settings of the website root are kept.

After the update

Depending on the update, these steps may be useful:

Step	Command
Add new CSS classes to the CSS Style Selector	`vendor/bin/contao-console creuva:css-styles`
Recreate the style guide with the new elements	`vendor/bin/contao-console creuva:styleguide --root=1 --replace`
Rebuild the search index	`vendor/bin/contao-console contao:crawl`

creuva:css-styles only adds missing categories, groups and styles. Changes you made in the back end are kept. The --root option specifies the ID of the website root that contains the style guide.

Warning

If you have overridden templates (see Custom CSS), compare them with the bundle’s templates after an update. Otherwise your copies will be missing new features.

You can find what changed in each version in the changelog on GitHub.

Issues

If you run into problems during installation or setup, or you notice a display error of the theme in a particular browser, please create a new ticket or write to us at support@pdir.dev.

Ticket overview Create new ticket

Note

Please check first whether your issue is already known.

Known limitations

# 1 Accessibility tools and animations of the Theme Components Bundle have no effect

The accessibility tools (contrast, font size) and the scroll animations of the Theme Components Bundle use the generatePage and parseFrontendTemplate hooks. Contao does not run these for page layouts of type “Modern”. The settings in the website root therefore have no effect in the Creuva layout.

Creuva comes with its own animations, see Animations.

# 2 Demo icons and downloads are missing on Windows

The demo files (SVG icons, PDFs) are loaded directly from files/creuva-demo/ and need the symlink public/files/creuva-demo (contao:symlinks). On Windows this fails without administrator rights or developer mode.

For local development, a directory junction helps:

mklink /J public\files\creuva-demo files\creuva-demo

creuva:install --reset and contao:symlinks cannot handle an existing junction and abort. Remove the junction beforehand with rmdir public\files\creuva-demo (this only deletes the link).

0.1 Isotope for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Our theme requires Contao 4.4 or higher and PHP 7.1.

Contao Manager

The theme can easily be installed via the Contao Manager. You find an installation guide here.

Installation

Note

The 0.1 Isotope Bundle can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Tip

Steps

1 / Adjust composer.json

Install the 0.1 Isotope Bundle by editing the file composer.json in the Contao root directory. Add the following lines at the end of the file (as in the example composer.json below). Replace the domain and the password.

,
"repositories": [
  {
    "type": "composer",
    "url": "https://[DOMAIN]:[PASSWORT]@packages.contao.store"
  }
]

Add the following line at the end of require. Don’t forget the comma in the second-to-last line.

"contao-themes-net/zero-one-isotope-bundle": "^1.0"

Example of what composer.json should look like for Contao 4.13:

{
    "type": "project",
    "require": {
        "contao/calendar-bundle": "^4.13",
        "contao/comments-bundle": "^4.13",
        "contao/conflicts": "*@dev",
        "contao/faq-bundle": "^4.13",
        "contao/listing-bundle": "^4.13",
        "contao/manager-bundle": "4.13.*",
        "contao/news-bundle": "^4.13",
        "contao/newsletter-bundle": "^4.13",
        "contao-themes-net/zero-one-isotope-bundle": "^1.0"
    },
    "extra": {
        "contao-component-dir": "assets"
    },
    "scripts": {
        "post-install-cmd": [
            "@php vendor/bin/contao-setup"
        ],
        "post-update-cmd": [
            "@php vendor/bin/contao-setup"
        ]
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://BENUTZERNAME:PASSWORT@packages.contao.store"
        }
    ]
}

2 / Run Composer update

Now open the Contao Manager and run the update by clicking the button Apply changes at the bottom.

3 / Update the database

Then open the install tool and update the database. In the install tool you also have to create an admin user account.

You reach the install tool in the Contao Manager via the menu item Tools or via the URL: www.your-domain.com/contao/install.

4 / Synchronize the theme files

Log in to the back end with the user account you created and select the menu item 0.1 Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager under the folder zeroOne and copies the SQL files for the database import into the templates folder.

5 / Synchronize the Isotope files

Select the menu item 0.1 Isotope Setup under CONTAO-THEMES-NET in the left navigation and click the button Synchronize files to create all product images and move the SQL files into the templates folder so that they can be imported.

6 / Empty the table ’tl_files'

Under the menu item 0.1 Theme Setup, empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’. This step must be carried out before importing the database.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

7 / Import the attributes

In the install tool, import the template named 0.1_isotope_attributes.sql. Make sure to tick Do not truncate tables.

Then clear the cache.

When you open the install tool again now, some new fields should be created. Update the database.

8 / Import the theme and Isotope demo data

Now import the template named 0.1_isotope_demo_contao_4.x.x.sql (depending on your Contao version) in the install tool. Make sure to tick Do not truncate tables.

For the import to work, Contao must be installed with the bundles for news, calendar, FAQ, newsletter, listing and comments.

If you don’t want to use these Contao bundles, you can uninstall them afterwards.

9 / Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

10 / Settings

Under Advanced CSS settings, select the class set spectre.json.

In addition, Use folder URLs must be active. You find it in the settings under Front end settings (up to Contao 4.10) or in the site structure in the settings of the website root under URL settings (Contao 4.11 and later).

11 / Import the CSS

Add the following line to custom.scss (file manager, under zeroOne/scss) so that the styling is loaded:

@import '../../../public/bundles/contaothemesnetzerooneisotope/scss/isotope';

Note

If your installation has a /web directory instead of /public, replace it in the path.

Also add the following line to activate the dark mode:

@import '../../../public/bundles/contaothemesnetzerooneisotope/scss/dark_mode';

Note

As of Contao 4.12 the publicly accessible subfolder was renamed from /web to /public. If your installation has a /web directory, use web instead of public in the import statement.

12 / Further extensions

If users should not only be able to order as guests but also register, install the extension terminal42/contao-autoregistration. In the settings of the website root under Member registration, activate the three checkboxes so that users are logged in and activated right after registering.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Customization

You find the Isotope manual here: User manual (German)

Order confirmation

Why are no order confirmation emails sent?

For the order confirmation emails to be sent, the SMTP data still has to be entered. You find the settings in the Contao back end under the menu item Gateways (under Notification Center). Edit the entry Email Gateway and override the SMTP settings there.

Product list

How can I change the number of products per row?

Go to Themes, edit the front end modules of the theme (gear icon) and select the product list module. Under Template settings you can change the number in the field Columns. Under Gallery, also select the matching image size.

Content elements

How can I display a full-width slider in the header area?

This feature is only available as of 0.1 Isotope version 1.3.0.

The slider is based on the Spectre carousel and works completely without JavaScript, so no JavaScript template or jQuery has to be activated in the layout.

Create an article and add the classes carousel-home fullwidth in the article settings.

In the article, create the elements Content-Slider (Umschlag Anfang) (wrapper start) and Content-Slider (Umschlag Ende) (wrapper stop) and select the template ce_sliderStart_carousel or ce_sliderStop_carousel respectively.

Between the wrapper elements, create elements of type Teaserbox. Under Template settings, select ce_cthemes_teaserbox_carousel and for the image the image size Carousel Startseite (1920x970).

In the end it should look like this:

You find an example in the 0.1 Isotope demo

How can I adjust the height of the slider on the home page?

You can adjust the height of the slider with your own CSS in custom.scss.

e.g.

.carousel-home .carousel {
    height: 800px;
}

Images

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

You can specify a different image processing service in config.yml; afterwards the cache has to be cleared. This often solves the problem already. If WEBP is supported, you should also be able to select it in the image sizes.

contao:
    image:
        image_service: 'contao.image.imagine.gd'

contao:
    image:
        image_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Other

How do I get nicer invoices?

Install the extension isotope/isotope_documents.

The extension ships various templates that you can select in the back end for the respective document.

How do I add a registration/login form to the shop?

So that users are activated right after registering and do not have to click a confirmation link in the email first, install the extension terminal42/contao-autoregistration.

Once the extension is installed, tick the following options in the website root under Member registration: activate automatically, log in automatically, log in automatically after activation.

Create a page “Anmeldung” (login) where the modules for the login and registration form are placed.

Under the menu item Member groups (Account manager), create a member group for the customers.

Now the modules have to be created or adjusted. For the login form, create a module of type Login form. Set the checkout page as redirect page and select the template mod_login_zeroone.

Also create a module of type Registration, select the fields to display and the member group. Select the checkout page as redirect page and assign the template member_grouped_zeroone to the module. Don’t forget to tick Allow login.

In the cart module, select the login page you just created as the redirect page for the checkout.

In the checkout module, select “Both allowed” as checkout method.

Finally, place the modules for login and registration in the article of the login page. If guest orders should also be possible, simply place a link that leads to the checkout.

When you are in the cart and want to continue to the checkout, you should now be redirected to the login page, where you can choose between continuing as a guest, logging in or registering.

Update

You can update the theme easily via the Contao Manager. Then open the install tool and update the database.

If a problem occurs after the update, also have a look at our possible solutions.

Tip

A database backup beforehand never hurts!

Issues

If you ran into problems during installation or setup, or you found a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check beforehand whether your issue is already known.

CONVERT Theme for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Our theme requires Contao 4.4 or higher and PHP version 5.6.

Tip

We recommend Contao 4.9 with PHP version 7.1 or higher to achieve the best possible loading time with our theme!

Contao Manager

The theme is very easy to install with the Contao Manager. You find an installation guide here.

License

Buy and register a license

The CONVERT theme is available for free (with copyright notice) or with a paid license (without copyright notice).

You can buy the paid license at contao-themes.net. Select the option without copyright notice, enter your domain and then click the button Add to cart. Then go to checkout and follow the next steps.

After successful payment you receive an invoice by email and we will activate your domain shortly, so that you can register it in the Contao back end.

Until then you can already install and use the theme with the copyright notice.

Tip

As the holder of a paid license you get premium support if you have problems installing or setting up the theme.

Register the license

Note

If you ordered the theme license via themes.contao.org, please send us an email with your domain and the ordered theme to support[AT]pdir.dev, so that we can activate the theme domain in the back end.

If you bought a license and have already installed the theme, you can register it in the back end under the menu item Themes. Click Activate theme domain, enter your domain and then click Check Domain. If the domain was registered successfully, you should see the message Domain registered. When you reload the page, it should look like the following screenshot.

If you only see the message “You can set a Theme Licence in Layout -> Themes.” when you click the button Activate theme domain, you have to edit the theme and enter convert in the field Theme Code. The input field for the domain should then be visible.

Remove the copyright notice

Once you have bought a license, you can remove the copyright notice, which is placed in an article, in the Contao back end.

Go to the article view, look for the article 03/01 Footer under Elemente - 03 Footer (at the very end) and edit it via the pencil icon.

Installation

Still using Contao 4? You find the installation guide here.

Contao 4 installation guide

Note

The demo can only be imported into an empty Contao installation.

Note

If you have already created content on your site, see the following guide: Installation into an existing Contao installation.

Installation in Contao 5

Open the Contao Manager: www.your-domain.com/contao-manager.phar.php. In the Discover tab, enter CONVERT Theme and click Add.

In the Packages tab you should now see a new package to be installed. Click the button Apply changes at the bottom to start the installation.

Once the installation is finished, click Update database.

Run all database migrations and click Continue. The first step creates all folders and files in the file manager.

Then the missing fields are created in the database.

In the last step the demo data is imported.

Done! When you open your site, you should already see the demo. The theme comes with 2 demo variants, each with its own website root.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Contao 4

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Tip

Steps

1 / Install the CONVERT Theme Bundle

First open the Contao Manager at the following URL: www.your-domain.com/contao-manager.phar.php. Select Discover, enter CONVERT Theme in the search field and add the package CONVERT Theme.

Then switch to Packages, enter the version ^1.7 via the gear icon and start the installation of the theme with the button Apply changes. With the latest version the Contao Manager would otherwise install version 2.x, which is only compatible with Contao 5 and later.

2 / Update the database

Then open the install tool and update the database. You also have to create an admin user account in the install tool.

You can reach the install tool in the Contao Manager via the menu item Tools or at the URL: www.your-domain.com/contao/install.

3 / Synchronize the theme files and empty tl_files

Log in to the back end with the user account you created and select the menu item CONVERT Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager under the folder convert and copies the SQL files for the database import into the templates folder.

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’. This step must be carried out before importing the database.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

4 / Import the database

Now open the install tool. Under the tab “Import a template” you can import an .sql file from the templates directory. Select the file for your Contao version and tick Do not truncate tables. Then click Import a template.

Besides the landing page demo, the CONVERT theme also comes with an app demo (SQL files starting with convert_theme_contao_app_demo) with different content.

If you chose the minimal Contao installation in the Contao Manager (without news, calendar, newsletter, comments, listing, FAQ), select the SQL file named minimal_installtool.sql.

If the database was imported successfully, a message should appear that a template was imported, as shown in the screenshot.

5 / Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

6 / Settings

Under Advanced CSS settings, select the class set spectre.json.

Notes:

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Customization

Header and footer

You can edit the logo in the article under Elemente > 01 Header.

You can edit the footer content in the article under Elemente > 03 Footer.

Customizing the styling

Once the theme has been installed, the SCSS files are located in the file manager under the path convert/scss. For your own customizations, simply use custom.scss, which accepts both SCSS and plain CSS, and _custom_variables.scss.

In _custom_variables.scss you can change the colors and font of the theme. To change a variable, uncomment the line (remove the slashes).

Tip

If the SCSS file was not edited with the Contao editor but uploaded with an FTP program, you have to purge the script cache under System maintenance in the Contao back end and, if necessary, reload the page with Ctrl + F5.

Note

Do not rename the theme folder convert in the file manager, otherwise the SCSS files will no longer be loaded. You do not have to include the files in the page layout yourself, the theme already loads them automatically.

Color schemes

By default the CONVERT theme comes with a light layout in orange colors. You can activate other color schemes, though:

Dark color scheme
Light color scheme - green/blue

To switch to another layout, uncomment (remove the slashes) the line with the desired color scheme in the Colour Schemes section of _custom_variables.scss. You may need to reload the page in the browser with Ctrl + F5 for the changes to take effect.

Activate the light color scheme - green/blue:

@import 'colour_schemes/green_blue';

Activate the light color scheme - green/blue:

@import '#{$scssPath}/colour_schemes/green_blue';

If the variable $scssPath does not exist in _custom_variables.scss yet, add it before the import statements.
$scssPath: "../../../vendor/contao-themes-net/convert-theme-bundle/src/Resources/public/scss";

Variables

To change colors and the font, uncomment the corresponding lines in _custom_variables.scss (remove the slashes).

Variable	Meaning
$body-font-family	Font
$primary-color	Primary color
$dark-color	Dark shade (black)
$light-color	Light shade (white)

$body-bg	Page background color
$body-font-color	Font color
$link-color	Link color
$link-color-dark	Link color on hover

$footer-background_1	Background color of the footer area
$footer-color-1	Font color of the footer area
$border-radius	Rounded corners for buttons, teaser boxes etc. - possible values e.g. 10px, 100% or 0px (no rounded corners).
$article-width	Width of an article (default: 1180px)
$article-padding	Padding of an article (default: 60px 20px -> means: 60px top/bottom, 20px left/right)

$button-background	Button background
$button-color	Button font color
$button-background-hover	Button background on mouseover
$button-color-hover	Button font color on mouseover

Dark mode

Since iOS 13/Android 10 you can activate dark mode, which switches the user interface to a black background and the text to a lighter color for better readability. If you activate dark mode, the CONVERT theme automatically switches to a darker color scheme. This is easier on your eyes at night and may slightly improve battery life.

You can also deactivate dark mode in _custom_variables.scss by commenting out the corresponding line (two slashes at the beginning of the line).

//@import 'colour_schemes/dark_mode';

//@import '#{$scssPath}/colour_schemes/dark_mode';

Adding a font

To add a font, insert CSS code like the following at the very beginning of _custom_variables.scss. Replace the name and the paths of the font. The path must always start with a /.

@font-face {
	font-family: "Beispiel-Font";
	font-style: normal;
	font-weight: normal;
	src: url("/files/convert/fonts/font.woff"),
	url("/files/convert/fonts/font.ttf"),
	url("/files/convert/fonts/font.svg");
}

_custom_variables.scss defines a variable for the font ($body-font-family). Uncomment the line (remove the slashes) and add the name of the font at the beginning.

$body-font-family: 'Beispiel-Font', -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto;

FAQ

Images

Why is an image not displayed?

The folder in the file manager may not be set to public. You can check this by editing the folder. Public must be ticked, otherwise the image is not displayed in the front end.

Why doesn’t the large view of an image open in a lightbox when I click it?

The theme has to load jQuery and the jQuery template j_colorbox. You can edit the layout in the back end under Themes via the third-to-last icon Edit the page layouts of theme ID 1.

Why are animated GIFs not displayed?

For animated GIFs, do not set an image size in the image settings, otherwise the animation is lost.

How do I add an image to the intro area on the home page?

Simply add an image element after the teaser box in the Intro article. The image is then displayed below the text.

Image on top

To display the image above the text, place the image element before the teaser box.

Image on the left

To place the image to the left of the text, add the class left-image in the settings of the parent article (wrench icon) under Expert settings.

Image on the right

To place the image to the right of the text, add the class right-image in the settings of the parent article (wrench icon) under Expert settings.

Image below, overlapping

To place the image below the text with a slight overlap, add the class image-overflow in the settings of the parent article (wrench icon) under Expert settings.

How do I remove the background blur in the intro area?

Add the following CSS to custom.scss and then reload the page with Ctrl + F5.

.intro .ce_ct_teaserBox .image>div {
    filter: none;
}

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

contao:
    image:
        imagine_service: 'contao.image.imagine.gd'

contao:
    image:
        imagine_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Other

How do I prevent the theme CSS file from being cached?

Visitors who have already visited the website are usually served a cached file. If you want to prevent this, you can adjust the fe_page template.

Adjust the following template: fe_page_convert.html5.

To prevent the CSS file from being cached, you can append a timestamp to the file name, for example. In the line echo $combiner->getCombinedFile(); ?>">, insert the following before the quotation marks: ?date=<?= time() ?>

It should look like this:

<link rel="stylesheet" type="text/css" media="all" href="<?php
        // add stylesheets
        $combiner = new Combiner();
        $combiner->add($file->path);
        echo $combiner->getCombinedFile(); ?>?date=<?= time() ?>">

Update

You can easily update the theme with the Contao Manager. Then open the install tool and update the database.

If a problem occurs after the update, have a look at our possible solutions.

Tip

A database backup beforehand never hurts!

Issues

If you ran into problems during installation or setup, or you noticed a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check first whether your problem is already known.

Known issues

# 1 An error occurred when opening the front end

In _custom_variables.scss (in the file manager under convert/scss), check whether the variable $scssPath exists and how the color schemes are included.

If the variable $scssPath exists in _custom_variables.scss, you have to remove it.

/* ============================= */
/*        Colour Schemes         */
/* ============================= */

//@import 'colour_schemes/dark';
//@import 'colour_schemes/green_blue';

/* ============================= */
/*          Dark Mode            */
/* ============================= */

@import 'colour_schemes/dark_mode';

In _custom_variables.scss (in the file manager under convert/scss), check whether the variable $scssPath exists and how the color schemes are included.

If the variable $scssPath does not exist in _custom_variables.scss yet, you have to add it before the import statements.

$scssPath: "../../../vendor/contao-themes-net/convert-theme-bundle/src/Resources/public/scss";

The lines under Colour Schemes should look like the following code example. It is important that #{$scssPath} is at the beginning.

/* ============================= */
/*        Colour Schemes         */
/* ============================= */

//@import '#{$scssPath}/colour_schemes/dark';
//@import '#{$scssPath}/colour_schemes/green_blue';

/* ============================= */
/*          Dark Mode            */
/* ============================= */

@import '#{$scssPath}/colour_schemes/dark_mode';

# 2 Unknown insert tag {{ua::browser|attr}}

After an update from Contao 4 to 5, the error Unknown insert tag {{ua::browser|attr}} may appear in the system log. The insert tag is in the page layout under the expert settings in the field Body class. As the insert tag no longer exists in Contao 5, you can remove it from the page layout.

MATE Theme for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Contao 5

Contao system requirements

Version 3.0.0 of the MATE theme requires at least Contao 5.0.0 and PHP 8.0.

Tip

We recommend Contao 5.3 with PHP version 8.3 or higher to achieve the best possible loading time with our theme!

Contao Manager

The MATE theme is easy to install with the Contao Manager. You find a step-by-step installation guide here: MATE theme installation.

License

Buy and register a license

The MATE theme is available for free (with copyright notice) or with a paid license (without copyright notice). You find the detailed license terms of the MATE theme here.

After successful payment you receive an email with the theme license, an invoice and further details.

Until then you can already install and use the theme with the copyright notice.

Tip

As the holder of a paid license you get premium support if you have problems installing or setting up the theme.

Register the license

Note

If you bought a license and have already installed the theme, you can register it in the back end under the menu item Themes. Click Activate theme domain, enter your domain and then click Check Domain. If the domain was registered successfully, you see the message Domain registered. When you reload the page, it should look like the following screenshot.

If you only see the message “You can set a Theme Licence in Layout -> Themes.” when you click the button Activate theme domain, you have to edit the theme and enter mate in the field Theme Code (see the following screenshot). The input field for the domain should then be visible.

Remove the copyright notice

Once you have bought a license, you can remove the copyright notice, which is placed in an article, in the Contao back end.

Go to the article view, look for the article 05/05 footer bottom under MATE Elements - 05 Footer and edit it via the pencil icon. It contains a text element that you can edit.

Installation

Still using Contao 4? You find the installation guide here.

Contao 4 installation guide

Note

The demo can only be imported into an empty Contao installation.

Note

If you have already created content on your site, see the following guide: Installation into an existing Contao installation.

Installation in Contao 5

Open the Contao Manager: www.your-domain.com/contao-manager.phar.php. In the Discover tab, enter MATE Theme and click Add.

In the Packages tab you should now see a new package to be installed. Click the button Apply changes at the bottom to start the installation.

Once the installation is finished, click Update database.

Run all database migrations and click Continue. The first step creates all folders and files in the file manager.

Then the missing fields are created in the database.

In the last step the demo data is imported.

Done! When you open your site, you should already see the demo.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Contao 4

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Tip

Steps

Follow these steps to install the MATE theme. At the end of the guide you also find a helpful video.

1) Install the MATE Theme Bundle

First open the Contao Manager at the following URL: www.your-domain.com/contao-manager.phar.php. Select Discover, enter mate theme in the search field and add the package MATE Theme.

Then switch to Packages, enter the version ^2.20 via the gear icon and start the installation of the theme with the button Apply changes. With the latest version the Contao Manager would otherwise install version 3.x, which is only compatible with Contao 5 and later.

Then open the install tool and update the database.

2) Synchronize the theme files and empty the table ’tl_files'

Log in to the back end with the user account you created and select the menu item Mate Theme Setup under MATE THEME in the left navigation. Then click the button Synchronize theme files (see image 2). This creates all files in the file manager under the folder mate and copies the SQL files for the database import into the templates folder.

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’. This step must be carried out before importing the database.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

Image 2: Synchronizing the theme files

3) Import the database

Now open the install tool. Under the tab Import a template (see the following screenshot) you can import an .sql file from the templates directory. Select the file for your Contao version and tick Do not truncate tables. Then click Import a template.

If you chose the minimal Contao installation in the Contao Manager (without news, calendar, newsletter, comments, listing, FAQ), select the SQL file named minimal_installtool.sql.

If the database was imported successfully, you should get a message that a template was imported, as in the following screenshot.

Alternatively, you can import the sql file with phpMyAdmin.

Image 3: Importing a template

4) Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

5) Settings

In the Settings, activate Auto_item and Use folder URLs under Front end settings. As of Contao 4.7 the setting to activate auto_item no longer exists in the back end; it is always active by default. As of Contao 4.11 the option “Use folder URLs” is no longer in the settings but in the website root under URL settings.

Image 4: Front end settings

Under Advanced CSS settings, select the class set materialize.json (see image 5).

Image 5: Advanced CSS settings

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Helpful video (German)

Customization

CSS customization

How to define colors, fonts and your own CSS is explained on the page Colors and fonts.

JavaScript customization

For your own JavaScript, it is best to create a separate file and include it in the theme.

Placing elements with your own insert tag

Under MATE Elements you find articles that you can include anywhere on the website with an insert tag. In the back end, go to Articles and scroll all the way down.

In the article settings (wrench icon) you can select the matching Theme Helper Tag under Template settings (see image 2). If you use several website roots with the MATE theme in one Contao installation, you can also select the desired page under Page name.

You then include the article with an insert tag in an HTML element or a template, e.g.:

{{theme::content::MATE02/01}}

The first number stands for the type (Header, Modules or Footer) and the second number for the Theme Helper Tag in the article.

How to create your own Theme Helper Tags is explained in the Theme Helper documentation.

Image 1: Articles under MATE Elements

Image 2: Selecting the Theme Helper Tag in the article

Image 3: Including the article via the Theme Helper Tag

Customizing the header

You find the header content in the articles under MATE Elements – 01 Header. In the back end, open the menu item Articles and scroll all the way down.

Opening hours, phone number and email including icons are included in the module Header / Top.
Logo, navigation and search are loaded via the module Navigation / Hauptnavigation.

You can replace the logo in the article 01/04 Logo. It contains two logos: the second logo appears when the navigation gets a green background while scrolling. This second logo must have the CSS class fixed-nav.

The footer content is in the articles under MATE Elements – 05 Footer. You find them in the back end under Articles (at the very bottom).

They are included – just like the newsletter box (see Theme elements) – via the module Footer.

Helpful videos (German)

Introductory Contao 4 tutorial

Basic settings in Contao

Colors & Fonts

Colors and fonts

After installing the theme, you find the SCSS files in the file manager under the path mate/sass.

Depending on the installed theme version, there are two ways to make your own customizations:

Older theme versions: You use the files

custom.scss (for SCSS and CSS)
_custom_colors.scss (to change the base colors and choose a color scheme)
_custom_variables.scss (for more detailed adjustments such as fonts or colors of individual elements)

To change a variable, remove the comment characters (slashes) in front of the line in the respective file.

Newer theme versions: As of the latest version there are no SCSS variables anymore, only CSS variables. In addition, _custom_colors.scss was merged into _custom_variables.scss – so you only find one file named _custom_variables.scss. There you can adjust all color and other variables. Here, too, you have to uncomment the lines to activate changes.

In both cases you can still add your own SCSS or CSS in custom.scss.

Tip

Note

Do not rename the theme folder mate in the file manager, otherwise the SCSS files will no longer be loaded. You do not have to include the files in the page layout yourself, the theme already loads them automatically.

Color schemes

By default the MATE theme comes with a light layout and a green primary color. You can also choose other color schemes:

Light color scheme / green primary color
Light color scheme / blue primary color
Light color scheme / red primary color
Light color scheme / yellow primary color
Dark color scheme

All of the color schemes above are adjusted for high contrast to ensure good readability and accessibility.

In addition there is a green, blue, yellow and dark color scheme that is not adjusted for high contrast. These come from an earlier theme version and are still included for backward compatibility.

To switch to a different color scheme, uncomment the corresponding line under Colour Schemes in _custom_variables.scss (or _custom_colors.scss in the older theme version) by removing the slashes. You may need to reload the page with Ctrl + F5 for the change to take effect.

@import 'mate_color_schemes/mate_green_colors_contrast';
//@import 'mate_color_schemes/mate_dark_colors_contrast';
//@import 'mate_color_schemes/mate_blue_colors_contrast';
//@import 'mate_color_schemes/mate_yellow_colors_contrast';
//@import 'mate_color_schemes/mate_red_colors_contrast';

//@import 'mate_color_schemes/mate_dark_colors';
//@import 'mate_color_schemes/mate_blue_colors';
//@import 'mate_color_schemes/mate_yellow_colors';

If you want to use several color schemes on one website, follow this guide.

Variables

Important note If you use the latest version of the MATE theme, you may wonder where _custom_colors.scss has gone. Don’t worry: as of MATE version 3.5.0, a new installation of the MATE theme only has _custom_variables.scss, which now contains all color and variable definitions.

What this means for you:

v2 (new installation from version 3.5.0): A new installation of the theme only has _custom_variables.scss with all color and variable settings. Use CSS variables for your customizations.
v1 (version older than 3.5.0 / update from a version older than 3.5.0): If you updated the MATE theme or installed a version older than 3.5.0, both _custom_variables.scss and _custom_colors.scss remain. Use SCSS variables for your customizations.

Tip

ℹ️ How do I update my existing installation to the new version with CSS variables? As of version 3.5.0 the MATE theme was thoroughly adapted for accessibility. If you want to use all current and future features, you should switch to the new version. You find a detailed guide here: Update to CSS variables.

In our theme you can adjust many styles via CSS variables. They are already prepared in the stylesheet, but commented out by default (with //). To activate or override a variable, simply remove the // at the beginning of the line.

📁 Where to find the variables You find the file for adjusting the variables in the file manager under mate/sass/_custom_variables.scss.

✅ Example: activating a variable

// Vorher (nicht aktiv):
//--mateColor2: #86af49;

// Nachher (aktiv):
--mateColor2: #86af49;

🔧 The most important CSS variables Here is an overview of the most important CSS variables that you can adjust in mate/sass/_custom_variables.scss.

Variable	Meaning
`--mateColor1`	Primary color, light shade
`--mateColor2`	Primary color
`--mateColor3`	Primary color, dark shade
`--mateColor4`	Secondary color
`--mateColor6`	Secondary color, light shade

`--mateColorWhite`	White
`--mateColorBlack`	Black
`--mateColorGreyLight`	Light grey
`--mateColorGreyDark`	Dark grey
`--pageBackground`	Background color of the website

`--primary-text-color`	Primary text color
`--secondary-text-color`	Secondary text color
`--mateColor2-text-color`	Text in the primary color – e.g. for links or headlines on a light background
`--mateColor3-text-color`	Text in the dark shade of the primary color – e.g. for links or headlines on a light background
`--mateColor4-text-color`	Text in the secondary color – e.g. for links or headlines on a light background

`--boxes-background`	Background color of boxes (e.g. teaser, contact, news, event, form, breadcrumbs)
`--boxes-text-color`	Text color in boxes (e.g. teaser, contact, news, event, form, breadcrumbs)

`--rgba-mateColor2`	Primary color as an rgb value
`--rgba-boxes-background`	Box background as an rgb value

Variables in _custom_colors.scss

Base colors:

$mateColor1: Primary color, light shade $mateColor2: Primary color $mateColor3: Primary color, dark shade $mateColor4: Secondary color $mateColor6: Secondary color, light shade

$mateColorWhite: White $mateColorBlack: Black $mateColorGreyLight: Light grey $mateColorGreyDark: Dark grey $pageBackground: Background color of the website

Text colors:

$primary-text-color: Primary text color $secondary-text-color: Secondary text color

Boxes:

$boxes-background: Background color of the boxes (e.g. content box, teaser box, news, events, login, newsletter, etc.) $boxes-text-color: Font color of the boxes (e.g. content box, teaser box, news, events, login, newsletter, etc.)

Content box:

$contentbox-first-background: Background color of the first content box $contentbox-second-background: Background color of the second content box

Adding a font

If you want to use your own font, you can include it at the very top of _custom_variables.scss.

🔗 Recommendation: fonts via Google Webfonts Helper

A great way to include a font quickly and easily is the site:

👉 Google Webfonts Helper

There you can:

choose a font from the Google Fonts library,
select the font styles you need,
download a ZIP file with the font files,
and generate the matching @font-face CSS code right away.
Important: Under “Customize Folder prefix”, enter the path to your fonts folder, e.g. /files/mate/fonts/.

📄 Example: adding the CSS to _custom_variables.scss Copy the generated CSS code from the website (e.g. for the font “Ubuntu”) and paste it at the very top of _custom_variables.scss:

/* ubuntu-regular - latin */
@font-face {
  font-display: swap;
  font-family: 'Ubuntu';
  font-style: normal;
  font-weight: 400;
  src: url('/files/mate/fonts/ubuntu-v20-latin-regular.woff2') format('woff2');
}

Then assign the font in the CSS variables in _custom_variables.scss as follows:

:root {
  --font1: 'Ubuntu'; // Text light
  --font2: 'Ubuntu'; // Überschriften
  --font3: 'Ubuntu'; // Text normal
}

  $font1: 'Ubuntu'; // Text light
  $font2: 'Ubuntu'; // Überschriften
  $font3: 'Ubuntu'; // Text normal

Examples of changing colors

To change the navigation colors, edit the variables under the heading Header and Navigation in _custom_variables.scss. To activate a variable, simply remove the // at the beginning of the line.

Example: The following example changes the colors and backgrounds of the main navigation.

:root {
    --navbar-bg-color: #437d4f; // Hintergrundfarbe der Navigation
    --navbar-color: #fff; // Schriftfarbe der Links
    --navbar-active-color: #000; // Schriftfarbe des aktiven Menüpunkts und bei Mouse-Hover
    --navbar-dropdown-hover-bg-color: lighten(#437d4f, 10%); // Hintergrundfarbe des Dropdown-Menü bei Mouse-Hover
    --navbar-dropdown-hover-color: #000; // Schriftfarbe des Dropdown-Menü bei Mouse-Hover
    --navbar-dropdown-bg: #437d4f; // Hintergrundfarbe des Dropdown-Menü
    --navbar-dropdown-color: #fff; // Schriftfarbe der Links im Dropdown-Menü
    --navbar-search-color: #fff; // Farbe des Suchicons
}

$navbar-bg-color: #437d4f; // Hintergrundfarbe der Navigation
$navbar-color: #fff; // Schriftfarbe der Links
$navbar-active-color: #000; // Schriftfarbe des aktiven Menüpunkts und bei Mouse-Hover
$navbar-dropdown-hover-bg-color: lighten(#437d4f, 10%); // Hintergrundfarbe des Dropdown-Menü bei Mouse-Hover
$navbar-dropdown-hover-color: #000; // Schriftfarbe des Dropdown-Menü bei Mouse-Hover
$navbar-dropdown-bg: #437d4f; // Hintergrundfarbe des Dropdown-Menü
$navbar-dropdown-color: #fff; // Schriftfarbe der Links im Dropdown-Menü
$navbar-search-color: #fff; // Farbe des Suchicons

The following example changes the colors and backgrounds of the main navigation when scrolling down (when the navigation sticks to the top of the screen).

:root {
    --navbar-stuck-bg-color: rgba(#437d4f, .8); // Hintergrundfarbe der Navigation
    --navbar-stuck-color: #fff; // Schriftfarbe der Links
    --navbar-stuck-active-color: #000; // Schriftfarbe des aktiven Menüpunkts und bei Mouse-Hover
    --navbar-stuck-dropdown-hover-bg-color: lighten(#437d4f, 10%); // Hintergrundfarbe des Dropdown-Menü bei Mouse-Hover
    --navbar-stuck-dropdown-hover-color: #000; // Schriftfarbe des Dropdown-Menü bei Mouse-Hover
    --navbar-stuck-dropdown-color: #fff; // Hintergrundfarbe des Dropdown-Menü
    --navbar-stuck-dropdown-bg: #437d4f; // Schriftfarbe der Links im Dropdown-Menü
    --navbar-stuck-search-color: #fff; // Farbe des Suchicons
}

$navbar-stuck-bg-color: rgba(#437d4f, .8); // Hintergrundfarbe der Navigation
$navbar-stuck-color: #fff; // Schriftfarbe der Links
$navbar-stuck-active-color: #000; // Schriftfarbe des aktiven Menüpunkts und bei Mouse-Hover
$navbar-stuck-dropdown-hover-bg-color: lighten(#437d4f, 10%); // Hintergrundfarbe des Dropdown-Menü bei Mouse-Hover
$navbar-stuck-dropdown-hover-color: #000; // Schriftfarbe des Dropdown-Menü bei Mouse-Hover
$navbar-stuck-dropdown-color: #fff; // Hintergrundfarbe des Dropdown-Menü
$navbar-stuck-dropdown-bg: #437d4f; // Schriftfarbe der Links im Dropdown-Menü
$navbar-stuck-search-color: #fff; // Farbe des Suchicons

The following example changes the colors and backgrounds of the mobile navigation.

:root {
    --navbar-mobile-menu-icon-color: #fff; // Farbe des mobilen Burgermenu-Icons
    --navbar-stuck-mobile-menu-icon-color: #fff; // Farbe des mobilen Burgermenu-Icons, wenn die Navigation am oberen Bildschirmrand stehen bleibt
    --navbar-mobile-background: #437d4f; // Hintergrundfarbe
    --navbar-mobile-color: #fff; // Schriftfarbe der Links
    --navbar-mobile-dropdown-background: lighten(#437d4f, 10%); // Hintergrundfarbe der weiteren Menüebenen
    --navbar-mobile-dropdown-color: #fff; // Schriftfarbe der weiteren Menüebenen
}

$navbar-mobile-menu-icon-color: #fff; // Farbe des mobilen Burgermenu-Icons
$navbar-stuck-mobile-menu-icon-color: #fff; // Farbe des mobilen Burgermenu-Icons, wenn die Navigation am oberen Bildschirmrand stehen bleibt
$navbar-mobile-background: #437d4f; // Hintergrundfarbe
$navbar-mobile-color: #fff; // Schriftfarbe der Links
$navbar-mobile-dropdown-background: lighten(#437d4f, 10%); // Hintergrundfarbe der weiteren Menüebenen
$navbar-mobile-dropdown-color: #fff; // Schriftfarbe der weiteren Menüebenen

To change the footer colors, edit the variables under the heading Footer in _custom_variables.scss. Remove the // at the beginning of the line to activate the variable.

💡 Note: Some variables are only available from MATE version 2.11.0. It is best to update the theme to the latest version to be able to use all options.

:root {
    --footer-newsletter-bg-color: #f1f1f1; // Hintergrundfarbe des Newsletter-Bereich
    --footer-newsletter-color: #000; // Schriftfarbe des Newsletter-Bereich
    --footer-newsletter-button-background: #b50000; // Hintergrundfarbe des Buttons im Newsletter-Bereich
    --footer-newsletter-button-background-hover: lighten(#b50000,10%); // Hintergrundfarbe des Buttons bei Mouseover im Newsletter-Bereich
    --footer-input-bg-color: rgba(#b50000,.3); // Hintergrundfarbe des Eingabefelds im Newsletter-Bereich
    --footer-input-color: #000; // Schriftfarbe des Eingabefelds im Newsletter-Bereich
    
    --footer-primary-bg-color: #dedede; // Hintergrundfarbe im Footer-Bereich unter dem Newsletter
    --footer-primary-color: #000; // Schriftfarbe im Footer-Bereich unter dem Newsletter
    --footer-primary-link-color: #b50000; // Linkfarbe im Footer-Bereich unter dem Newsletter
    --footer-primary-link-color-hover: lighten(#b50000,10%); // Linkfarbe bei Mouseover im Footer-Bereich unter dem Newsletter
    --footer-headline-border-color: #000; // Farbe der Rahmen unter den Überschriften
    --footer-news-events-time-color: #7d7d7d; // Schriftfarbe des Datum bei News-/Eventsbeiträgen
    
    --footer-secondary-bg-color: #b50000; // Hintergrundfarbe des Copyright-Bereich
    --footer-secondary-color: #fff; // Schriftfarbe im Copyright-Bereich
    --footer-secondary-link-color: #f7f7f7; // Linkfarbe im Copyright-Bereich
    --footer-secondary-link-color-hover: darken(#f7f7f7,10%); // Linkfarbe bei Mouseover im Copyright-Bereich
}

$footer-newsletter-bg-color: #f1f1f1; // Hintergrundfarbe des Newsletter-Bereich
$footer-newsletter-color: #000; // Schriftfarbe des Newsletter-Bereich
$footer-newsletter-button-background: #b50000; // Hintergrundfarbe des Buttons im Newsletter-Bereich
$footer-newsletter-button-background-hover: lighten(#b50000,10%); // Hintergrundfarbe des Buttons bei Mouseover im Newsletter-Bereich
$footer-input-bg-color: rgba(#b50000,.3); // Hintergrundfarbe des Eingabefelds im Newsletter-Bereich
$footer-input-color: #000; // Schriftfarbe des Eingabefelds im Newsletter-Bereich

$footer-primary-bg-color: #dedede; // Hintergrundfarbe im Footer-Bereich unter dem Newsletter
$footer-primary-color: #000; // Schriftfarbe im Footer-Bereich unter dem Newsletter
$footer-primary-link-color: #b50000; // Linkfarbe im Footer-Bereich unter dem Newsletter
$footer-primary-link-color-hover: lighten(#b50000,10%); // Linkfarbe bei Mouseover im Footer-Bereich unter dem Newsletter
$footer-headline-border-color: #000; // Farbe der Rahmen unter den Überschriften
$footer-news-events-time-color: #7d7d7d; // Schriftfarbe des Datum bei News-/Eventsbeiträgen

$footer-secondary-bg-color: #b50000; // Hintergrundfarbe des Copyright-Bereich
$footer-secondary-color: #fff; // Schriftfarbe im Copyright-Bereich
$footer-secondary-link-color: #f7f7f7; // Linkfarbe im Copyright-Bereich
$footer-secondary-link-color-hover: darken(#f7f7f7,10%); // Linkfarbe bei Mouseover im Copyright-Bereich

Changing the colors of content boxes

To change the colors of content boxes (e.g. teaser boxes, news, events), edit the variables in _custom_colors.scss. Remove the // at the beginning of the line to activate the variable.

:root {
    --boxes-background: #333; // Hintergrundfarbe
    --boxes-text-color: #fff; // Schriftfarbe
}

$boxes-background: #333; // Hintergrundfarbe
$boxes-text-color: #fff; // Schriftfarbe

Changing the colors of the content box

To change the content box, edit the variables in the Content Box section of _custom_variables.scss. Simply remove the // at the beginning of the line to activate and adjust the variable.

:root {
    --contentbox-first-color: #fff; // Schriftfarbe der 1. Content Box
    --contentbox-second-color: #fff; // Schriftfarbe der 2. Content Box
    --contentbox-first-background: #2d2d2d; // Hintergrundfarbe der 1. Content Box
    --contentbox-second-background: #191919; // Hintergrundfarbe der 2. Content Box
}

$contentbox-first-color: #fff; // Schriftfarbe der 1. Content Box
$contentbox-second-color: #fff; // Schriftfarbe der 2. Content Box
$contentbox-first-background: #2d2d2d; // Hintergrundfarbe der 1. Content Box
$contentbox-second-background: #191919; // Hintergrundfarbe der 2. Content Box

Layouts

All possible layouts are already created under Themes - Page layouts. Example integrations can be found on the Layouts page. You select the layout in the page under Layout settings.

One-column layout

For the one-column layout, select the page template fe_page_mate and enter the body class default-col. You set the page template and the body class in the page layout under Expert settings.

Layout with left column

For the layout with a left column, select the page template fe_page_mate_left and enter the body class left-col.

Layout with right column

For the layout with a right column, select the page template fe_page_mate_right and enter the body class right-col.

Layout with left and right column

For the layout with a left and right column, select the page template fe_page_mate_leftright and enter the body class left-right-col.

Multidomain

If you want to use several domains with the MATE theme for Contao and each should have its own custom.scss, _custom_colors.scss and _custom_variables.scss, you need a few adjustments. This guide shows you how. You should have at least MATE theme version 2.9.1 installed.

Note

As of Contao 4.12 the publicly accessible subfolder was renamed from /web to /public. If your installation has a /web directory, use web instead of public in the following code examples.

Important note

If you use the latest version of the MATE theme, you may wonder where _custom_colors.scss has gone. Don’t worry: as of MATE version 3.5.0, a new installation of the MATE theme only has _custom_variables.scss, which now contains all color and variable definitions.

What this means for you:

v1 (update from a version older than 3.5.0): If you updated the MATE theme, both _custom_variables.scss and _custom_colors.scss remain.
v2 (new installation from version 3.5.0): A new installation of the theme only has _custom_variables.scss with all color and variable settings.

1) Create the SCSS files

Create a folder in the file manager under mate/sass (e.g. domain2). Copy the files custom.scss and _custom_variables.scss into this folder.

In _custom_variables.scss, adjust the path of the color schemes as follows.

//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_green_colors_contrast';
@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_dark_colors_contrast';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_blue_colors_contrast';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_yellow_colors_contrast';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_red_colors_contrast';

//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_dark_colors';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_blue_colors';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_yellow_colors';

/* ============================= */
/*     Automatic Dark Mode       */
/* ============================= */

//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/mate_color_schemes/mate_dark_mode';

Create a folder in the file manager under mate/sass (e.g. domain2). Copy the files custom.scss, _custom_colors.scss and _custom_variables.scss into this folder.

In _custom_colors.scss, adjust the path of the color schemes as follows.

//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/mate_color_schemes/mate_dark_colors';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/mate_color_schemes/mate_blue_colors';
//@import '../../../../public/bundles/contaothemesnetmatetheme/sass/mate_color_schemes/mate_yellow_colors';

Create a folder in the file manager under mate/sass (e.g. domain2). Copy the files custom.scss, _custom_colors.scss and _custom_variables.scss into this folder.

In _custom_colors.scss, adjust the path of the color schemes as follows.

//@import '../../../../public/bundles/matetheme/sass/mate_color_schemes/mate_dark_colors';
//@import '../../../../public/bundles/matetheme/sass/mate_color_schemes/mate_blue_colors';
//@import '../../../../public/bundles/matetheme/sass/mate_color_schemes/mate_yellow_colors';

In the same folder, also create a file mate.scss with the following content. If you installed the MATE theme in a local development environment, the file must be named mate_win.scss.

// variables;
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/v2/_mate_variables";
@import "_custom_variables";

// color
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/color-variables";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/color-classes";

// variables;
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/variables";

// reset
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/normalize";

// components
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/global";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/badges";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/icons-material-design";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/grid";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/navbar";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/typography";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/transitions";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/cards";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/toast";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/tabs";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/tooltip";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/buttons";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/dropdown";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/waves";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/modal";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/collapsible";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/chips";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/materialbox";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/forms/forms";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/table_of_contents";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/sidenav";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/preloader";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/slider";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/carousel";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/tapTarget";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/pulse";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/datepicker";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/timepicker";

// theme and custom styles
@import '../../../../public/bundles/contaothemesnetmatetheme/sass/v2/style';
@import 'custom';

// variables;
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/_mate_colors";
@import "_custom_colors";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/_mate_variables";
@import "_custom_variables";

// color
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/color-variables";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/color-classes";

// variables;
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/variables";

// reset
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/normalize";

// components
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/global";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/badges";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/icons-material-design";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/grid";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/navbar";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/typography";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/transitions";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/cards";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/toast";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/tabs";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/tooltip";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/buttons";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/dropdown";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/waves";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/modal";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/collapsible";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/chips";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/materialbox";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/forms/forms";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/table_of_contents";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/sidenav";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/preloader";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/slider";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/carousel";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/tapTarget";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/pulse";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/datepicker";
@import "../../../../public/bundles/contaothemesnetmatetheme/sass/components/timepicker";

// theme and custom styles
@import '../../../../public/bundles/contaothemesnetmatetheme/sass/style';
@import 'custom';

// variables;
@import "../../../../public/bundles/matetheme/sass/_mate_colors";
@import "_custom_colors";
@import "../../../../public/bundles/matetheme/sass/_mate_variables";
@import "_custom_variables";

// color
@import "../../../../public/bundles/matetheme/sass/components/color-variables";
@import "../../../../public/bundles/matetheme/sass/components/color-classes";

// variables;
@import "../../../../public/bundles/matetheme/sass/components/variables";

// reset
@import "../../../../public/bundles/matetheme/sass/components/normalize";

// components
@import "../../../../public/bundles/matetheme/sass/components/global";
@import "../../../../public/bundles/matetheme/sass/components/badges";
@import "../../../../public/bundles/matetheme/sass/components/icons-material-design";
@import "../../../../public/bundles/matetheme/sass/components/grid";
@import "../../../../public/bundles/matetheme/sass/components/navbar";
@import "../../../../public/bundles/matetheme/sass/components/typography";
@import "../../../../public/bundles/matetheme/sass/components/transitions";
@import "../../../../public/bundles/matetheme/sass/components/cards";
@import "../../../../public/bundles/matetheme/sass/components/toast";
@import "../../../../public/bundles/matetheme/sass/components/tabs";
@import "../../../../public/bundles/matetheme/sass/components/tooltip";
@import "../../../../public/bundles/matetheme/sass/components/buttons";
@import "../../../../public/bundles/matetheme/sass/components/dropdown";
@import "../../../../public/bundles/matetheme/sass/components/waves";
@import "../../../../public/bundles/matetheme/sass/components/modal";
@import "../../../../public/bundles/matetheme/sass/components/collapsible";
@import "../../../../public/bundles/matetheme/sass/components/chips";
@import "../../../../public/bundles/matetheme/sass/components/materialbox";
@import "../../../../public/bundles/matetheme/sass/components/forms/forms";
@import "../../../../public/bundles/matetheme/sass/components/table_of_contents";
@import "../../../../public/bundles/matetheme/sass/components/sidenav";
@import "../../../../public/bundles/matetheme/sass/components/preloader";
@import "../../../../public/bundles/matetheme/sass/components/slider";
@import "../../../../public/bundles/matetheme/sass/components/carousel";
@import "../../../../public/bundles/matetheme/sass/components/tapTarget";
@import "../../../../public/bundles/matetheme/sass/components/pulse";
@import "../../../../public/bundles/matetheme/sass/components/datepicker";
@import "../../../../public/bundles/matetheme/sass/components/timepicker";

// theme and custom styles
@import '../../../../public/bundles/matetheme/sass/style';
@import 'custom';

2) Create a template

Under Templates, create a new template fe_page_mate.html5 and rename it (e.g. fe_page_mate_domain2.html5).

In line 15, add the newly created folder from the file manager to getCombinedStylesheet().

<link rel="stylesheet" type="text/css" media="all" href="<?= ContaoThemesNet\MateThemeBundle\ThemeUtils::getCombinedStylesheet('domain2'); ?>">

3) Create a layout

Go to Themes and Edit the page layouts of the theme (4th icon from the right) and duplicate any layout (e.g. default). You can name it e.g. “default - domain2”. Edit the layout and select the fe_page template you just created under Expert settings (at the very bottom) in Page template.

4) Assign the layout to the page

Finally, assign the layout to a page.

FAQ

Images

Why is an image not displayed?

The folder in the file manager may not be set to public. You can check this by editing the folder. Public must be ticked, otherwise the image is not displayed in the front end.

Why doesn’t the large view of an image open in a lightbox when I click it?

The theme has to load jQuery and the jQuery template j_colorbox. You can edit the layout in the back end under Themes via the third-to-last icon Edit the page layouts of theme ID 1.

Why are animated GIFs not displayed?

For animated GIFs, do not set an image size in the image settings, otherwise the animation is lost.

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

contao:
    image:
        imagine_service: 'contao.image.imagine.gd'

contao:
    image:
        imagine_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Content elements

How do I nest accordions?

Duplicate the template j_accordion with the following content:

<script src="<?= $this->asset('js/jquery-ui.min.js', 'contao-components/jquery-ui') ?>"></script>
<script>
  jQuery(function($) {
    $(document).accordion({
      // Put custom options here
      heightStyle: 'content',
      header: '.toggler',
      collapsible: true,
      create: function(event, ui) {
        ui.header.addClass('active');
        $('.toggler').attr('tabindex', 0);
      },
      activate: function(event, ui) {
        ui.newHeader.addClass('active');
        ui.oldHeader.removeClass('active');
        $('.toggler').attr('tabindex', 0);
      }
    });
$(&#39;.toggler-inner&#39;).parent().accordion({
  // Put custom options here
  heightStyle: &#39;content&#39;,
  header: &#39;.toggler-inner&#39;,
  collapsible: true,
  active: false,
  create: function(event, ui) {
    ui.header.addClass(&#39;active&#39;);
    $(&#39;.toggler-inner&#39;).attr(&#39;tabindex&#39;, 0);
  },
  activate: function(event, ui) {
    ui.newHeader.addClass(&#39;active&#39;);
    ui.oldHeader.removeClass(&#39;active&#39;);
    $(&#39;.toggler-inner&#39;).attr(&#39;tabindex&#39;, 0);
  }
});

$(&#39;.toggler-outer&#39;).parent().accordion({
  // Put custom options here
  heightStyle: &#39;content&#39;,
  header: &#39;.toggler-outer&#39;,
  collapsible: true,
  //active: false,
  create: function(event, ui) {
    ui.header.addClass(&#39;active&#39;);
    $(&#39;.toggler-outer&#39;).attr(&#39;tabindex&#39;, 0);
  },
  activate: function(event, ui) {
    ui.newHeader.addClass(&#39;active&#39;);
    ui.oldHeader.removeClass(&#39;active&#39;);
    $(&#39;.toggler-outer&#39;).attr(&#39;tabindex&#39;, 0);
  }
});
});
</script>

With active: false or active: true you control whether the accordions are closed or open by default.

Add the class toggler-outer under class names to the outer accordions and the class toggler-inner to the inner accordions.

Outer accordions:

Inner accordions:

Example:

How do I keep all accordions closed?

Go to the menu item Templates and duplicate the template j_accordion.html5. Add the following line to the parameters:

active: false,

The template should then look like this:

<script src="<?= $this->asset('js/jquery-ui.min.js', 'contao-components/jquery-ui') ?>"></script>
<script>
  jQuery(function($) {
    $(document).accordion({
      // Put custom options here
      heightStyle: 'content',
      header: '.toggler',
      collapsible: true,
      active: false,
      create: function(event, ui) {
        ui.header.addClass('active');
        $('.toggler').attr('tabindex', 0);
      },
      activate: function(event, ui) {
        ui.newHeader.addClass('active');
        ui.oldHeader.removeClass('active');
        $('.toggler').attr('tabindex', 0);
      }
    });
  });
</script>

How do I hide the “More” button in the news slider on the home page if the news item has no content?

Adjust the template news_mate_slider.html5.

Replace the code in line 16, where the headline is set, with the following line:

<h2><?php if($this->hasText) { echo $this->linkHeadline; } else { echo $this->headline; } ?></h2>

In line 22, remove the following part: || $this->hasTeaser.

To display the headline in white as well, add the following lines to custom.scss:

.slider.mod_newslist h2 {
  color: #fff;
}

How do I change the font sizes in the news slider navigation?

You can do this with an adjustment in custom.scss:

#wrapper .slider.mod_newslist .indicators .indicator-item .subheadline {
  font-size: 16px;
}
#wrapper .slider.mod_newslist .indicators .indicator-item .headline {
font-size: 16px;
}

How do I link the image in the news slider?

Edit the template news_mate_slider.html5 and replace the following line (line 2) …

<div class="img" <?php if ($this->addImage): ?>style="background-image:url('<?= $this->picture['img']['src'] ?>');"<?php endif; ?>></div>`

… with the following lines:

<a href="<?= $this->link ?>" class="img">
  <div <?php if ($this->addImage): ?>style="background-image:url('<?= $this->picture['img']['src'] ?>');"<?php endif; ?>></div>
</a>

Also add some CSS to custom.scss.

#wrapper .slider.mod_newslist .img {
  position: relative;
}
#wrapper .slider.mod_newslist .img div {
position: absolute;
top: 0;
width: 100%;
height: 100%;
left: 0;
background-size: cover;
background-position: center;
background-repeat: no-repeat;
}

How do I remove or change the icons of an unordered list?

You can do this with an adjustment in custom.scss.

Remove icons:

.ce_list ul:not(.browser-default) li:before,
.ce_text ul:not(.browser-default) li:before {
  display: none;
}

Change icons:

.ce_list ul:not(.browser-default) li:before,
.ce_text ul:not(.browser-default) li:before {
  content: "+";
}

Forms

How do I customize the date picker?

You can customize the date picker with some JavaScript. For example, create a JS file in the file manager and include it via the page layout.

Example:

jQuery(document).ready(function ($) {
    $('input.datepicker').datepicker({
        selectMonths: true, // Creates a dropdown to control month
        selectYears: '150', // Creates a dropdown of 15 years to control year,
        maxDate: new Date(new Date().getFullYear() + 30, new Date().getMonth(), new Date().getDate()),
        autoClose: true, // Close upon selecting a date,
        format: 'dd.mm.yyyy',
        container: 'div.datepicker',
        firstDay: 1,
        yearRange: [1900, new Date().getFullYear() + 30],
        i18n: {
            nextMonth: 'Nächster Monat',
            previousMonth: 'Vorheriger Monat',
            labelMonthSelect: 'Monat wählen',
            labelYearSelect: 'Jahr wählen',
            months: ['Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember'],
            monthsShort: ['Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez'],
            weekdays: ['Sonntag', 'Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag'],
            weekdaysShort: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
            weekdaysAbbrev: ['S', 'M', 'D', 'M', 'D', 'F', 'S'],
            today: 'Heute',
            clear: 'Löschen',
            done: 'OK',
            cancel: 'Abbrechen',
            format: 'dd.mm.yyyy'
        },
    });
});

You find all options in the Materialize documentation.

Only Saturday and Sunday selectable

With the function disableDayFn() you can control which days are selectable. With the following example, only Saturdays and Sundays are selectable.

disableDayFn(date) {
    if(date.getDay() === 0 || date.getDay() === 6)
        return false
    else
        return true
}

Complete JavaScript code:

jQuery(document).ready(function ($) {
	$('input.datepicker').datepicker({
        selectMonths: true, // Creates a dropdown to control month
        selectYears: '150', // Creates a dropdown of 15 years to control year,
        maxDate: new Date(new Date().getFullYear() + 30, new Date().getMonth(), new Date().getDate()),
        autoClose: true, // Close upon selecting a date,
        format: 'dd.mm.yyyy',
        container: 'div.datepicker',
        firstDay: 1,
        yearRange: [1900, new Date().getFullYear() + 30],
        i18n: {
            nextMonth: 'Nächster Monat',
            previousMonth: 'Vorheriger Monat',
            labelMonthSelect: 'Monat wählen',
            labelYearSelect: 'Jahr wählen',
            months: ['Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember'],
            monthsShort: ['Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez'],
            weekdays: ['Sonntag', 'Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag'],
            weekdaysShort: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
            weekdaysAbbrev: ['S', 'M', 'D', 'M', 'D', 'F', 'S'],
            today: 'Heute',
            clear: 'Löschen',
            done: 'OK',
            cancel: 'Abbrechen',
            format: 'dd.mm.yyyy'
        },
        disableDayFn(date) {
            if(date.getDay() === 0 || date.getDay() === 6)
                return false
            else
                return true
        },
    });
});

Only weekdays selectable

To make only weekdays selectable, it is enough to set the option disableWeekends to true.

disableWeekends: true

How do I show the top bar of the header in the mobile view?

With some CSS in custom.scss you can show the bar in the mobile view.

@media (max-width: 767px) {
  .sectionTop {
    display: block;
.inside {
   height: inherit;
   overflow: hidden;
}
}
}

Layout

How do I display a full-width content area in the middle of the content?

To display a full-width content area (e.g. a full-width image), a few template adjustments are necessary.

Adjust fe_page_mate.html5

Edit the template fe_page_mate.html5 and remove the line <div class="container"> and the closing </div> inside <?php $this->block('container'); ?>.

<?php $this->block('container'); ?>
    <?php $this->parent(); ?>
<?php $this->endblock(); ?>

Adjust mod_article.html5

Edit the template mod_article.html5 and insert the following line after the opening <div>, at around line 24: <div class="container">. Before the last closing </div>, insert another </div>. In the line before that you can also add the class fullwidth to set some spacing at the top and bottom with your own CSS.

<div class="<?= $this->class ?> block fullwidth"<?= $this->cssID ?><?php if ($this->style): ?> style="<?= $this->style ?>"<?php endif; ?>>
    <div class="container">
    ...
    </div>
</div>

Create a customized mod_article template

Now duplicate the template mod_article and name it e.g. mod_article_without_container.html5. Then simply remove the two lines you just added.

Adjustments for multi-column layouts

If you use multi-column layouts (with a left/right column), the corresponding templates have to be adjusted as well.

In the templates fe_page_mate_left.html5, fe_page_mate_leftright.html5 and fe_page_mate_right.html5, insert the line <div class="container"> and the closing </div> inside <?php $this->block('container'); ?>.

<?php $this->block('container'); ?>
    <div class="container">
        <?php $this->parent(); ?>
    </div>
<?php $this->endblock(); ?>

Assigning templates in articles

If content should be displayed across the full width, edit the article settings (the wrench icon after the pencil) and assign the article template mod_article_without_container in the template settings.

You would also have to assign the template mod_article_without_container to all articles with the header image.

In addition, all articles under MATE Elements - 01 Header, 02 Modules and 03 Footer must be assigned the template mod_article_without_container.

Custom CSS

To get some more spacing at the top and bottom, edit custom.scss:

#main .mod_article.fullwidth {
	margin-top: 50px;
	margin-bottom: 50px;
}

Example

Can all subfolders of the subpage navigation be expanded automatically?

You can achieve this with the following adjustment in custom.scss.

.subnav .dropdown-content {
    display: block;
    visibility: visible;
    height: inherit;
    position: relative;
}

How do I disable the uppercase text in the navigation?

You can achieve this with the following adjustment in custom.scss.

#header .nav-wrapper ul li {
  text-transform: none;
}

Other

How do I prevent the theme CSS file from being cached?

Visitors who have already visited the website are usually served a cached file. If you want to prevent this, you can adjust the fe_page template.

Adjust the following template: fe_page_mate.html5.

It should look like this:

<link rel="stylesheet" type="text/css" media="all" href="<?php
// add stylesheets
$combiner = new Combiner();
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
$combiner->add('bundles/matetheme/sass/mate_win.scss');
} else {
$combiner->add('bundles/matetheme/sass/mate.scss');
}
echo $combiner->getCombinedFile(); ?>?date=<?= time() ?>">

Helpers

If you add the following line to custom.scss, you can use various classes on content elements to adjust the spacing (margin/padding).

@import 'spacing-helpers';

Classes	Explanation
for all screen sizes
`m-10`, `m-20` … `m-100`	Margin (10px, 20px … 100px)
`mt-10`, `mt-20` … `mt-100`	Margin top (10px, 20px … 100px)
`mb-10`, `mb-20` … `mb-100`	Margin bottom (10px, 20px … 100px)
`ml-10`, `ml-20` … `ml-100`	Margin left (10px, 20px … 100px)
`mr-10`, `mr-20` … `mr-100`	Margin right (10px, 20px … 100px)
`p-10`, `p-20` … `p-100`	Padding (10px, 20px … 100px)
`pt-10`, `pt-20` … `pt-100`	Padding top (10px, 20px … 100px)
`pb-10`, `pb-20` … `pb-100`	Padding bottom (10px, 20px … 100px)
`pl-10`, `pl-20` … `pl-100`	Padding left (10px, 20px … 100px)
`pr-10`, `pr-20` … `pr-100`	Padding right (10px, 20px … 100px)
only for screen size > 600px
`m-m-10`, `m-m-20` … `m-m-100`	Margin (10px, 20px … 100px)
`mt-m-10`, `mt-m-20` … `mt-m-100`	Margin top (10px, 20px … 100px)
`mb-m-10`, `mb-m-20` … `mb-m-100`	Margin bottom (10px, 20px … 100px)
`ml-m-10`, `ml-m-20` … `ml-m-100`	Margin left (10px, 20px … 100px)
`mr-m-10`, `mr-m-20` … `mr-m-100`	Margin right (10px, 20px … 100px)
`p-m-10`, `p-m-20` … `p-m-100`	Padding (10px, 20px … 100px)
`pt-m-10`, `pt-m-20` … `pt-m-100`	Padding top (10px, 20px … 100px)
`pb-m-10`, `pb-m-20` … `pb-m-100`	Padding bottom (10px, 20px … 100px)
`pl-m-10`, `pl-m-20` … `pl-m-100`	Padding left (10px, 20px … 100px)
`pr-m-10`, `pr-m-20` … `pr-m-100`	Padding right (10px, 20px … 100px)
only for screen size > 992px
`m-l-10`, `m-l-20` … `m-l-100`	Margin (10px, 20px … 100px)
`mt-l-10`, `mt-l-20` … `mt-l-100`	Margin top (10px, 20px … 100px)
`mb-l-10`, `mb-l-20` … `mb-l-100`	Margin bottom (10px, 20px … 100px)
`ml-l-10`, `ml-l-20` … `ml-l-100`	Margin left (10px, 20px … 100px)
`mr-l-10`, `mr-l-20` … `mr-l-100`	Margin right (10px, 20px … 100px)
`p-l-10`, `p-l-20` … `p-l-100`	Padding (10px, 20px … 100px)
`pt-l-10`, `pt-l-20` … `pt-l-100`	Padding top (10px, 20px … 100px)
`pb-l-10`, `pb-l-20` … `pb-l-100`	Padding bottom (10px, 20px … 100px)
`pl-l-10`, `pl-l-20` … `pl-l-100`	Padding left (10px, 20px … 100px)
`pr-l-10`, `pr-l-20` … `pr-l-100`	Padding right (10px, 20px … 100px)
only for screen size > 1200px
`m-xl-10`, `m-xl-20` … `m-xl-100`	Margin (10px, 20px … 100px)
`mt-xl-10`, `mt-xl-20` … `mt-xl-100`	Margin top (10px, 20px … 100px)
`mb-xl-10`, `mb-xl-20` … `mb-xl-100`	Margin bottom (10px, 20px … 100px)
`ml-xl-10`, `ml-xl-20` … `ml-xl-100`	Margin left (10px, 20px … 100px)
`mr-xl-10`, `mr-xl-20` … `mr-xl-100`	Margin right (10px, 20px … 100px)
`p-xl-10`, `p-xl-20` … `p-xl-100`	Padding (10px, 20px … 100px)
`pt-xl-10`, `pt-xl-20` … `pt-xl-100`	Padding top (10px, 20px … 100px)
`pb-xl-10`, `pb-xl-20` … `pb-xl-100`	Padding bottom (10px, 20px … 100px)
`pl-xl-10`, `pl-xl-20` … `pl-xl-100`	Padding left (10px, 20px … 100px)
`pr-xl-10`, `pr-xl-20` … `pr-xl-100`	Padding right (10px, 20px … 100px)

Update to CSS variables

With version 3.5.0 the MATE theme was made accessible and all SCSS variables were switched to CSS variables. This means a manual intermediate step is necessary when updating from an older version (< 3.5.0) to a newer version (≥ 3.5.0).

Requirements

Existing installation of the MATE theme < 3.5.0
Update to Contao 5

1. Update the theme

Open the Contao Manager.
Update the MATE theme to 3.5.0 or higher (recommended: latest version).

2. Changes to the SCSS files

As of version 3.5.0 the file _custom_colors.scss no longer exists. All color definitions are now in _custom_variables.scss.

📂 Old structure (< 3.5.0)

mate/sass/
├── custom.scss
├── _custom_variables.scss
└── _custom_colors.scss

📂 New structure (≥ 3.5.0)

mate/sass/
├── custom.scss
└── _custom_variables.scss

3. Create the new theme files

After the update to 3.5.0 or higher the site still works, but not all new features are available right away. You should therefore create the current theme files.

Complete re-import of the theme folder

In the file manager, rename the folder mate, e.g. to mate-alt.
In the Contao Manager, open System maintenance → Check database and run the database update.
The migration that creates the new theme files is now offered – run it.
A new folder mate with the current files is created.

Moving images: If there were images in the old mate folder, move them either into the new folder or into a separate image folder. References are kept if the images were added in Contao via “Add an image”.

4. Transfer your own customizations

If you made changes in custom.scss, _custom_colors.scss or _custom_variables.scss, you have to transfer them manually to the new files.

Important: V2 uses CSS variables instead of SCSS variables.

Example color variable

Before (V1 – SCSS):

$mateColor1: #b6cf92;

New (V2 – CSS variables):

:root {
  --mateColor1: #b6cf92;
}

CSS variables are used in code like this:

color: var(--mateColor1);

5. Update SCSS customizations

If your custom.scss still uses SCSS variables ($variable), change them to the CSS variable format (var(--variable)).

Example:

/* Vorher */
color: $mateColor1;

/* Neu */
color: var(--mateColor1);

Accessibility

You find detailed tips, new features from version 3.5.0 and best practices for accessible design here: ♿ Accessibility in the MATE theme

Direct download of the new variables file

You find the current _custom_variables.scss here: 📄 GitHub: _custom_variables.scss

If you want to adjust the files manually, the sass folder must also contain an empty file named .v2 to activate the V2 structure.

Accessibility

Accessibility in the MATE theme (version 3.5.0 and later)

With version 3.5.0 the MATE theme was thoroughly revised with regard to accessibility and switched to CSS variables. To use these features, a manual intermediate step is necessary when updating from an older version (< 3.5.0) to a newer version (≥ 3.5.0). ➡️ Guide: Update to CSS variables

1. Header icons for contrast mode and font size

Version 3.2.0 adds controls to the header to:

toggle contrast mode (high contrast)
adjust the font size (links to the accessibility statement by default)

Settings

Edit the website root in the site structure.
Under WCAG settings (Web Content Accessibility Guidelines) you find two checkboxes:
- “Allow switching to high contrast mode”
- “Allow displaying the icon for changing the font size” These options are active by default in a fresh installation.

If you installed the theme from scratch

If you install the MATE theme from version 3.2.0 and import the demo, the icons are already in the header.

If you have an existing installation

Create an article
- Under Articles, create a new article, e.g. “01/06 contrast and size” under Nature Theme Elemente -> 01_Header.
- In the article settings, select the Theme Helper Tag MATE01/06 under Template settings.
- Add the CSS class contrast-size-switcher to the article.

Add content
- Create a text element in the article with the following content:
```
{{comp::contrast}} {{comp::size::barrierefreiheit.html#fontSize}}
```
- Add the CSS class wcag.

Including it in the template
- The article with the Theme Helper Tag MATE01/06 is included automatically via the navigation template.
- If you have customized your own mod_navigation_nature.html5, add the insert tag there manually.

<?php if($this->showMobileMenu == 1): ?>
  <ul id="mobile-menu<?= $this->id ?>" class="mobile-menu sidenav hc-bg-black-ter <?= $this->level ?>">
    <?= $this->mobileNav ?>
    <li>
      <!-- contrast and size switcher -->
      {{theme::content::MATE01/06}}
    </li>
  </ul>
<?php endif; ?>

2. New accessible templates (version 3.5.0 and later)

To avoid redundant links (e.g. image, headline and button all linked), it is enough to link only the button. This improves keyboard navigation.

Adapted templates are available for various content elements such as teaser box, content box etc. These templates have the suffix _bf (German “barrierefrei”, accessible).

3. General accessibility tips

When creating content, pay attention to the following:

Provide alternative texts (alt tags) for images
Use meaningful link texts (not just “click here”)
Mind the contrast (text color/background color)
Use headings in a correct hierarchy
Use tables only for tabular data (not for layout)
Give forms label elements

4. Tools for testing accessibility

pdir Website Check – automatic check for accessibility and SEO.
WAVE Web Accessibility Evaluation Tool – browser extension for analyzing accessibility problems.
axe DevTools – developer tools for accessibility testing.
Contrast Checker – checks color contrast.

Elements

Topics

Content Box

For the content box, select the element type Content box. You can change the background color by giving the element classes (e.g. “grey lighten-3”, for more information see the section Colors) or by adjusting the CSS (custom.scss). How to display elements side by side is explained in the section Grid.

Content Slider

Contao’s own content slider

For the element Content slider (wrapper start), select the template ce_sliderStart_mate. For the closing element Content slider (wrapper end), select the template ce_sliderStop_mate. The slider is styled as in the following example if the text elements get the class slidebox1.

If you give the wrapper start element the class smaller, the content slider is displayed with a height of only 250px.

Content slider with image and text below

To create a content slider like in the following example, place text elements between the elements Content slider (wrapper start) and Content slider (wrapper end).

Give the element of type wrapper start the classes slider slider-text-below-image in the second input field under Expert settings, and select the template ce_sliderStart_mate under Template settings.

For the element of type wrapper end, select the template ce_sliderStop_mate.

You find an example in the MATE theme demo on the page Content Slider.

This is what the content slider should look like:

Placement of the elements:

Selecting the template and setting the classes in the wrapper start element:

CountTo

Version 2.1.0 of the MATE theme added the CountTo feature. It counts numbers up when they come into view. You find an example in the MATE theme demo.

To display the elements side by side as in the example, place text elements between an element of type Grid (grid start) and Grid (grid stop). In the text element you can set the column widths under Advanced CSS classes, see image. The section Grid explains this in more detail.

Give the grid start element the class count-to-container under Expert settings, otherwise it is not styled as in the example.

Use our Material Icons insert tag to add an icon, e.g. {{mi::place}}. place is the name of the icon in this case and can be replaced as you like. You also find a list of the Material Icons and their names in our documentation.

In our example, the label is set as an h6 heading in the text.

For the number, also use our CountTo insert tag, e.g. {{countTo::929::founded}}. The second part is always the number, the third part is an ID. If you include several insert tags on one page, each must have a unique ID.

Example:

Example placement of the elements in the article:

Text element:

Setting column widths in the text element:

Header image

For the header image, select the element type Image and the template ce_image_mate_headerimage (up to Contao 4.13) or content_element/image/header_image_mate (Contao 5.0 and later). You can choose the visible part of the image by setting the important part of the image.

You find an example integration of a normal header image on the layout pages of the demo site. An example integration of a narrow header image is on the Contact page.

Normal header image:

Narrow header image:

For a narrower header image, give the element the class smaller.

Left-aligned header image:

For a left-aligned header image, simply give the element the class left.

Right-aligned header image:

For a right-aligned header image, simply give the element the class right.

Headlines

If a content element with a headline gets the class bordered-left or bordered-right, the headline is displayed with a border at the bottom left or bottom right.

Headline with a border on the left:

Headline with a border on the right:

Hyperlinks

If a link should look like a button (white text on a green background), give the link the class btn.

Media elements (images, galleries, videos)

Image gallery

Depending on how many thumbnails per row should be displayed, the arrangement of the images adapts automatically and takes up all the available space.

Carousel image gallery

Only available from MATE theme version 2.12.0!

For a carousel image gallery, create an element of type Gallery. You can set the number of images per row in the field Thumbnails per row. With Full-size view/new window the image can also be opened in a lightbox (the j_colorbox template must be added to the layout for this). You should also create an image size (important part, e.g. 400x400 or 200x200), as the carousel is designed for square images.

In the template settings under Content element template, select one of the following templates:

content_element/gallery/carousel (simple carousel)
content_element/gallery/carousel_large (simple carousel with large images)
content_element/gallery/carousel_with_indicators (carousel with navigation dots)
content_element/gallery/carousel_large_with_indicators (carousel with large images and navigation dots)

In the template settings under Gallery template, select one of the following templates:

gallery_carousel (simple carousel)
gallery_carousel_large (simple carousel with large images)
gallery_carousel_with_indicators (carousel with navigation dots)
gallery_carousel_large_with_indicators (carousel with large images and navigation dots)

Simple carousel

Template: content_element/gallery/carousel / gallery_carousel

Template: content_element/gallery/carousel_with_indicators / gallery_carousel_with_indicators

Simple carousel with large images

Template: content_element/gallery/carousel_large / gallery_carousel_large

Template: content_element/gallery/carousel_large_with_indicators / gallery_carousel_large_with_indicators

YouTube video

For a YouTube video, select the template ce_youtube_mate (only up to Contao 4.13).

News slider

The news slider displays news items in a slider. The slider is included on the home page of the demo site. In the theme, the slider is included in the article Start in the header via the insert tag {{theme::content::MATE02/01}}.

You do not need content slider wrapper elements; you only have to include a module of type Newslist. Select news_mate_slider as the news template and mod_newslist_mate_slider as the custom template. The total number of items can be chosen freely.

You select the image and the teaser texts in the settings of each news item.

To swap the position of text and image, edit the item settings of the news and add the CSS class image-right under Expert settings.

As of version 2.8.0 you can adjust the slider settings (height, interval, transition speed and navigation) in the module Newslist.

You can integrate an area for newsletter subscriptions in the footer. The newsletter box is included in the module Footer via the insert tag {{theme::content::MATE02/01}}. The module itself is included in an article under MATE Elements - Moduls - 02/02 newsletter. For the CSS to be loaded, the article must have the ID newsletter.

Parallax element

Version 2.1.0 of the MATE theme added the parallax element. Place an element of type Parallax element in the article. There you can set a headline, the text, the height, a link and an image. You find examples of parallax elements in the MATE theme demo.

Parallax element with container width

If you select ce_mate_parallax_container under Custom template in the template settings, the text is displayed as wide as the normal content of the website.

Simple content box

You can give an element of element type Text a white background with some padding by assigning the custom template ce_text_simplebox_mate to the element.

Teaser Box

For the teaser box, select the element type Teaser box. You can adjust the width of the boxes by assigning CSS classes. If you add an image, select the image size Teaser-Box (450x270).

Teaser box with text/image side by side

Note

This feature was added in MATE theme version 2.21.0.

Enter headline and text

Image settings

If you add an image, the image alignment (left or right) controls whether the image is displayed to the left or right of the text.

Further settings

Under Teaser box settings you can select a page to link to and enter the link text.

The field Card CSS class changes the background and text color. You can use the classes of the Materialize color palette. To change the background, add e.g. the following classes: red, red lighten-5. To change the text color, use e.g. the classes white-text and black-text.

Select the template

Under Template settings, select the template ce_mate_teaserbox_card.

Example

This is what it could look like. You find more examples in our theme demo.

Possible error: images no longer displayed after an update

This error can occur if you customized the template ce_mate_teaserbox.html5.

Replace the following line …

{{picture::<?= $this->picture ?>?size=10&alt=<?= $this->metaImg[$GLOBALS['TL_LANGUAGE']]['alt'] ?>}}

… with the following line:

<?php $this->insert('image', $this->arrData); ?>

You can then select the image size in the content element.

Testimonial slider

Version 2.1.0 of the MATE theme added a testimonial slider. You find examples in the MATE theme demo.

First place an element of type Content slider (wrapper start) and one of type Content slider (wrapper end). Between them you can place as many elements of type Text element with background image as you like. There you can enter a text and set an image (profile picture) and a background image.

If the slider should be displayed narrow (see documentation), give the element Content slider (wrapper start) the class smaller under Expert settings (the second input field).

Example of a testimonial slider:

Placement of the elements in the article:

Selecting the element type and entering the text:

Selecting the image (profile picture):

Selecting the background image:

Removing the background image blur:

You can remove the blur of the background image with the following CSS, which has to be added to custom.scss under files/mate/sass:

.ce_mateTextBackgroundElement .bg-image {
    filter: none;
}

Modules

Topics

To add a breadcrumb, create a new module of type Breadcrumb navigation under Themes > Edit the front end modules of the theme (gear icon). Select mod_breadcrumb_mate as the custom template.

Then go back to Themes and edit the page layouts of the theme (to the right of the gear icon). Under Front end modules - Included modules, add a new row by clicking the green plus. Select the module you just created and Header as the layout section.

In the end, the breadcrumb should look like the following example.

To show the news or event title in the breadcrumb on the news and event detail view, you can use the following insert tag in the page name: {{page::pageTitle}}

Events

Event list with images and teaser

For an event list with images and a teaser text, select the template event_mate_teaser and the image size News-Box (520x350) in the module. In the module of the detail view, select the template event_mate_full.

Event list without images and with teaser

For an event list without images and with a teaser text, select the template event_mate_list in the module. In the module of the detail view, select the template event_mate_full.

Event list

For a simple event list without images and teaser text, select the template event_mate_upcoming in the module. In the module of the detail view, select the template event_mate_full.

Customization

Changing the number of columns:

To change the number of columns, you only have to adjust the template and the classes, e.g. col s12 m4 to display the list in three columns on desktops and in one column on mobile devices. How exactly to use the classes is explained on the following page: Grid.

<div class="event layout_teaser<?= $this->classUpcoming ?> col s12 m4">
[...]
</div>

Forms

For the file upload field, select the custom template form_mate_upload.

For the module type Login form, select the custom template mod_login_mate.

As of version 2.0.0 of the MATE theme you can add modal dialogs with a module. Go to the front end modules and create a new module of type Modal. There you can set a link, give it additional classes and edit the actual content of the modal dialog. You can include the module anywhere, e.g. in an article.

If the modal dialog should be fixed to the bottom of the screen, add the class bottom-sheet in the field CSS classes for the modal dialog.

There is a separate module type Navbar for navigations. In the navbar settings (see image 1) you can choose between different navbar types:

Navigation with dropdown, right-aligned,
Navigation without dropdown, left-aligned,
Navigation without dropdown, right-aligned,
Logo and navigation stacked/centered

You find example integrations under the menu item Modules - Navigation.

The navigation template mod_mate_navbar is used.

The navigation template mod_mate_navbar_left is used.

The navigation template mod_mate_navbar is used.

For a subpage navigation, as placed in the left and right column of the demo, for example, select the navbar type Navigation without dropdown, left-aligned and give the module the class subnav. Hide the logo, search and mobile navigation.

If the custom navigation should look like the subpage navigation, select the navigation template nav_mate_left_customnav and add the class subnav under Expert settings.

If the news archive menu should look like the subpage navigation, select the module template mod_newsmenu_mate.

News

News with images and teaser

For news with images and a teaser text, select the template news_mate_latest and the image size News-Box (520x350) in the module. In the module of the detail view, select the template news_mate_full.

News without images and with teaser

For news without images and with a teaser text, select the template news_mate_short in the module. In the module of the detail view, select the template news_mate_full.

Simple news list

There is no separate template for a simple news list without images and teaser text. In the module of the detail view, select the template news_mate_full.

Customization

Changing the number of columns:

<div class="layout_latest arc_<?= $this->archive->id ?> block<?= $this->class ?> col s12 m4">
[...]
</div>

Search

For the search engine module, select the template search_mate.

Extensions

Topics

euf_overlay

With the extension euf_overlay you can create an overlay (also known as a popup or popover) that is displayed on top of the actual website.

For the overlay to cover all other content of the MATE theme, an adjustment in custom.scss is necessary.

#euf_overlay {
  z-index: 5;
}

Google Maps

If you want to include a Google Maps map, install the package delahaye/dlh_googlemaps with the Contao Manager.

On the contact page there is a placeholder image next to the contact form where, for example, a Google Maps map could be included. If the map should be displayed there, give the element the classes col s12 m5.

Materialize

The MATE theme uses the front-end framework Materialize, based on Material Design.

Colors

You find the palette of colors that Materialize provides on the Materialize website or in the theme under Elements and Colors. Each color consists of a base class and optional classes that make the color lighter or darker.

Background color

To change the background color of an element, simply add a class with the color name and a class with the desired lightness level to the element.

Text color

To set a text color, simply use the color name with the suffix -text.

Grid

Materialize uses a 12-column grid system. You also find examples and explanations on the Materialize website.

Screen sizes

	Mobile devices	Tablets	Desktops	Large desktops
Resolution	<= 600px	> 600px	> 992px	> 1200px
Class prefix	.s	.m	.l	.xl
Number of columns	12	12	12	12

The class col must always come first. If several elements should be displayed side by side, the parent element must get the class row. For example, the classes col s12 m6 l4 make the element …

12 columns wide on mobile devices.
6 columns wide on tablets.
4 columns wide on desktops.

Usage

The extension Advanced Classes is used to assign these classes to elements. You can add the classes to content elements under Advanced CSS classes (see image 3), although not all elements are supported (e.g. the teaser or content box). If an element is not supported, add the classes manually under Expert settings.

Image 3: Setting advanced CSS classes

For the elements to be displayed correctly, the surrounding element must get the class row. The extension Contao Bootstrap Grid is used for this. Simply create an element of element type Grid Start and select the grid Umschlag mit Klasse row (see image 4). It should then look like image 5. The grid stop element is created automatically.

Under Themes and Manage grid definitions (the second-to-last icon) an empty grid element was created that makes sure a div element with the class row is created.

Image 4: Creating a grid wrapper

Image 5: Elements in a grid wrapper

Icons

To use icons, simply give the element the class material-icons and the icon name as content. You find all icons and their names either on the Material Design website or in the theme under Elements and Icons.

For example:

<i class="material-icons">insert_schedule</i>

You can change size and color by adding further classes.

Multilingual websites

To build a multilingual website with the MATE theme, you can install the extension Contao Multilingual Pages [i18nl10n]. Then you do not have to duplicate the site structure, only the elements that are displayed in different languages. You find documentation for Contao 3 here; there is none for Contao 4 yet.

Alternatively, you can create a site structure for each language without this extension. You find more about this in the Contao manual.

Contao Multilingual Pages [i18nl10n]

If you do not want to duplicate the site structure, install the extension exploreimpact/contao-i18nl10n with the Contao Manager.

In the website root of the site structure you can select the alternative languages under i18nl10n settings.

Under the menu item Multilingual pages, add the pages in the other languages. To create all pages, click L10N for all.

The elements now have the option to select the language under L10n settings. Select Neutral if the element should be displayed in all languages.

Duplicating the site structure

If you prefer to work with several site structures, select the corresponding website root under MATE Elements in the article settings under Template settings.

Other extensions

The MATE theme uses the following extensions:

Contao Advanced Classes

The module extends the CSS classes of Contao elements with sets of CSS classes you can define yourself. Editors and admins can quickly access predefined CSS classes via select fields. You set the classes in a content element under Advanced CSS classes (see image 1).

Contao Bootstrap Grid

The Bootstrap Grid module is only used to wrap several elements that should be displayed side by side in a DIV with the class row (see image 2). For this, an empty grid element was created under Themes and Manage grid definitions (the second-to-last icon).

Contao SEO Serp Preview

Contao SEO Serp Preview shows in a page how the page would look in the Google search results. In the site structure you can also use the button Enable SERP to see where a page title or page description is still missing.

Real Estate Module

The MATE theme already comes with templates and stylesheets for the Real Estate Module (Maklermodul).

Documentation

The Real Estate Module documentation contains all information on installing and setting up the module.

Including the stylesheets

Add the following line to custom.scss (/files/mate/sass) so that the list and detail view are displayed as in the screenshots.

@import 'maklermodul';

Setup

Create pages

First create one page each for the list view and the detail view.

List view module

Create a module of type Immobilienliste as described in the documentation.

Select the real estate template makler_list_mate
Select the image size Maklermodul / Listenansicht

Detail view module

Create a module of type Expose as described in the documentation.

Select the real estate template makler_details_extended_mate

Header image module

Create a module of type MaklerModul Kopfbild as described in the documentation.

Placing the modules

Place the modules for the list view and the exposé in the articles of the respective pages. For the header image, create another article placed in the header (above the article of the detail view).

Examples

If you have carried out all steps as described, the list should be displayed as in the following screenshots.

List view with button filter

List view with select filter

Exposé

With the Social Feed Bundle you can display posts from Facebook and Instagram in the MATE theme. Simply install the package named pdir/social-feed-bundle with the Contao Manager.

A guide on setting up the feed can be found on the following page: Social Feed documentation.

Single-column social media stream (example integration in the left column)

Two-column social media stream

Three-column social media stream

Tabcontrol

If you use the Tabcontrol extension by Christian Barkowsky and want to link to a tab, you can do this with anchors, e.g. www.example.org/page.html#tabControl_tabname. It is important that the ID always starts with tabControl_, otherwise the MATE theme tries to scroll to the anchor on the same page. The panel must also have the corresponding ID.

Vehicle Manager

The MATE theme already comes with templates and stylesheets for the Vehicle Manager (Fahrzeugmanager).

Documentation

The documentation contains all information on installing and setting up the Vehicle Manager.

Including the stylesheets

Add the following line to custom.scss so that the list and detail view are displayed as in the screenshots.

@import 'mobilede';

Setup

Create pages

First create one page each for the list view and the detail view.

List view module

Create a content element of type Fahrzeug Manager Listenansicht as described in the documentation.

Select the list view template ce_mobile_list_mate
Ad template ce_mobile_item (vertical layout) or ce_mobile_item_horizontal_mate (horizontal layout)

Detail view module

Create a module of type Fahrzeug Manager Detailansicht as described in the documentation.

Examples

Vertical layout

Horizontal layout

Detail view

Update

You can easily update the theme with the Contao Manager. Then open the install tool and update the database.

Tip

A database backup beforehand never hurts!

Update to MATE theme 2.0

Version 2.0 of the MATE theme uses version 1.0.0 of the Materialize framework instead of version 0.100.2. If you made template, JavaScript or CSS customizations, you may have to make changes after the update, as e.g. CSS classes were renamed and functions have to be called differently. This new version fixes several bugs that occurred with newer browser versions.

You find a complete list of all changes in version 1.0.0 of the Materialize framework here.

Template: mod_mate_navbar.html5 and mod_mate_navbar_left.html5

Use data-target instead of data-activates
Change the class button-collapse to sidenav-trigger
Change the class side-nav to sidenav

MATE 1.x

<?php if($this->showMobileMenu == 1): ?>
    <a href="#" data-activates="mobile-menu<?= $this->id ?>" class="button-collapse"><i class="material-icons">menu</i></a>
<?php endif; ?>

<?php if($this->showMobileMenu == 1): ?>
    <ul id="mobile-menu<?= $this->id ?>" class="mobile-menu side-nav <?= $this->level ?>">
    <?= $this->mobileNav ?>
    </ul>
<?php endif; ?>

MATE 2.0

<?php if($this->showMobileMenu == 1): ?>
    <a href="#" data-target="mobile-menu<?= $this->id ?>" class="sidenav-trigger"><i class="material-icons">menu</i></a>
<?php endif; ?>

<?php if($this->showMobileMenu == 1): ?>
    <ul id="mobile-menu<?= $this->id ?>" class="mobile-menu sidenav <?= $this->level ?>">
    <?= $this->mobileNav ?>
    </ul>
<?php endif; ?>

Template: nav_mate_root.html5

Use data-target instead of data-activates

MATE 1.x

<?php if (!empty($item['subitems'])): ?> data-activates="nav<?= $this->id ?>dropdown<?= $item['id'] ?>"<?php endif; ?>

MATE 2.0

<?php if (!empty($item['subitems'])): ?> data-target="nav<?= $this->id ?>dropdown<?= $item['id'] ?>"<?php endif; ?>

Sidenav

The JavaScript call is now sidenav() instead of sideNav()

MATE 1.x

$(".sidenav").sideNav();

MATE 2.0

$(".sidenav").sidenav();

Select fields

The JavaScript call is now formSelect() instead of materialSelect()

MATE 1.x

$('select').material_select();

MATE 2.0

$('select').formSelect();

Radio buttons

If you customized the template form_radio.html5, an adjustment is necessary because the HTML structure changed slightly.

MATE 1.x

<?php if ($option['type'] == 'option'): ?>
    <span><input type="radio" name="<?= $option['name'] ?>" id="opt_<?= $option['id'] ?>" class="radio" value="<?= $option['value'] ?>"<?= $option['checked'] ?><?= $option['attributes'] ?>> <label id="lbl_<?= $option['id'] ?>" for="opt_<?= $option['id'] ?>"><?= $option['label'] ?></label></span>
<?php endif; ?>

MATE 2.0

<?php if ($option['type'] == 'option'): ?>
    <label id="lbl_<?= $option['id'] ?>" for="opt_<?= $option['id'] ?>">
        <input type="radio" name="<?= $option['name'] ?>" id="opt_<?= $option['id'] ?>" class="radio" value="<?= $option['value'] ?>"<?= $option['checked'] ?><?= $option['attributes'] ?>>
        <span><?= $option['label'] ?></span>
    </label>
<?php endif; ?>

Checkboxes

If you customized the template form_checkbox.html5, an adjustment is necessary because the HTML structure changed slightly.

MATE 1.x

<?php if ($option['type'] == 'option'): ?>
    <span><input type="checkbox" name="<?= $option['name'] ?>" id="opt_<?= $option['id'] ?>" class="checkbox" value="<?= $option['value'] ?>"<?= $option['checked'] ?><?= $option['attributes'] ?>> <label id="lbl_<?= $option['id'] ?>" for="opt_<?= $option['id'] ?>"><?= $option['label'] ?></label></span>
<?php endif; ?>

MATE 2.0

<?php if ($option['type'] == 'option'): ?>
    <label id="lbl_<?= $option['id'] ?>" for="opt_<?= $option['id'] ?>">
        <input type="checkbox" name="<?= $option['name'] ?>" id="opt_<?= $option['id'] ?>" class="checkbox" value="<?= $option['value'] ?>"<?= $option['checked'] ?><?= $option['attributes'] ?>>
        <span><?= $option['label'] ?></span>
    </label>
<?php endif; ?>

Date picker

The call is now datepicker() instead of pickadate()
Some option names have changed

MATE 1.x

$inputDatepicker = $('.datepicker').pickadate({
    selectMonths: true,
    selectYears: '150',
    max: new Date( new Date().getFullYear() + 30, new Date().getMonth(), new Date().getDate() ),
    closeOnSelect: true,
    format: 'dd.mm.yyyy',
    container: 'div.datepicker',
    labelMonthNext: 'Nexter Monat',
    labelMonthPrev: 'Vorheriger Monat',
    labelMonthSelect: 'Monat wählen',
    labelYearSelect: 'Jahr wählen',
    monthsFull: [ 'Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember' ],
    monthsShort: [ 'Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez' ],
    weekdaysFull: [ 'Sonntag', 'Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag' ],
    weekdaysShort: [ 'So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa' ],
    weekdaysLetter: [ 'S', 'M', 'D', 'M', 'D', 'F', 'S' ],
    today: 'Heute',
    clear: 'Löschen',
    close: 'OK',
    firstDay: 1
});
$inputDatepicker.pickadate('picker');

MATE 2.0

$('input.datepicker').datepicker({
    selectMonths: true,
    selectYears: '150',
    maxDate: new Date( new Date().getFullYear() + 30, new Date().getMonth(), new Date().getDate() ),
    autoClose: true,
    format: 'dd.mm.yyyy',
    container: 'div.datepicker',
    firstDay: 1,
    i18n: {
        nextMonth: 'Nexter Monat',
        previousMonth: 'Vorheriger Monat',
        labelMonthSelect: 'Monat wählen',
        labelYearSelect: 'Jahr wählen',
        months: [ 'Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember' ],
        monthsShort: [ 'Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez' ],
        weekdays: [ 'Sonntag', 'Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag' ],
        weekdaysShort: [ 'So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa' ],
        weekdaysAbbrev: ['S','M','D','M','D','F','S'],
        today: 'Heute',
        clear: 'Löschen',
        done: 'OK',
        cancel: 'Abbrechen'
    }
});

Time picker

The call is now timepicker() instead of pickatime()
Some option names have changed

MATE 1.x

$inputTimepicker = $('.timepicker').pickatime({
    default: 'now',
    fromnow: 0, 
    twelvehour: false,
    donetext: 'OK',
    cleartext: 'Reset',
    canceltext: 'Abbrechen',
    autoclose: false,
    ampmclickable: true,
    aftershow: function(){},
    container: 'div.timepicker'
});
$inputTimepicker.pickatime('picker');

MATE 2.0

$('input.timepicker').timepicker({
    defaultTime: 'now',
    fromNow: 0,
    twelveHour: false,
    autoClose: false,
    container: 'div.timepicker',
    i80n: {
        done: 'OK',
        clear: 'Löschen',
        cancel: 'Abbrechen'
    }
});

Issues

If you ran into problems during installation or setup, or you noticed a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check first whether your problem is already known.

MATE Isotope for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.9 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Our theme requires Contao 4.9 or higher and PHP 7.1.

Contao Manager

The theme can easily be installed via the Contao Manager. You find an installation guide here.

Installation

Note

The MATE Isotope Bundle can only be installed into an empty Contao installation and is compatible with Contao 4.9 or higher.

Tip

Steps

1 / Adjust composer.json

Install the MATE Isotope Bundle by editing the file composer.json in the Contao root directory. Add the following lines at the end of the file (as in the example composer.json below). Replace the domain and the password.

,
"repositories": [
  {
    "type": "composer",
    "url": "https://[DOMAIN]:[PASSWORT]@packages.contao.store"
  }
]

Add the following line at the end of require. Don’t forget the comma in the second-to-last line.

"contao-themes-net/mate-isotope-bundle": "^1.0"

Example of what composer.json should look like for Contao 4.13:

{
    "type": "project",
    "require": {
        "contao/calendar-bundle": "^4.13",
        "contao/comments-bundle": "^4.13",
        "contao/conflicts": "*@dev",
        "contao/faq-bundle": "^4.13",
        "contao/listing-bundle": "^4.13",
        "contao/manager-bundle": "4.13.*",
        "contao/news-bundle": "^4.13",
        "contao/newsletter-bundle": "^4.13",
        "contao-themes-net/mate-isotope-bundle": "^1.0"
    },
    "extra": {
        "contao-component-dir": "assets"
    },
    "scripts": {
        "post-install-cmd": [
            "@php vendor/bin/contao-setup"
        ],
        "post-update-cmd": [
            "@php vendor/bin/contao-setup"
        ]
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://BENUTZERNAME:PASSWORT@packages.contao.store"
        }
    ]
}

2 / Run Composer update

Now open the Contao Manager, click Update for all existing packages (i.e. only Contao) and run the update by clicking the button Apply changes at the bottom.

3 / Update the database

Then open the install tool and update the database. In the install tool you also have to create an admin user account.

You reach the install tool in the Contao Manager via the menu item Tools or via the URL: www.your-domain.com/contao/install.

4 / Synchronize the theme files

Log in to the back end with the user account you created and select the menu item MATE Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager under the folder mate and copies the SQL files for the database import into the templates folder.

5 / Synchronize the Isotope files

Select the menu item MATE Isotope Setup under CONTAO-THEMES-NET in the left navigation and click the button Synchronize files to create all product images and move the SQL files into the templates folder so that they can be imported.

6 / Empty the table tl_files

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’ in the MATE Theme Setup.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

7 / Import the attributes

In the install tool, import the template named mate_isotope_attributes.sql. Make sure to tick Do not truncate tables.

Then clear the cache.

When you open the install tool now, some new fields should be created. Update the database.

8 / Import the theme and Isotope demo data

In the install tool, import the template named mate_isotope_demo_contao_4.x.x.sql (depending on your Contao version). Make sure to tick Do not truncate tables.

For the import to work, Contao must be installed with the bundles for news, calendar, FAQ, newsletter, listing and comments.

If you don’t want to use these Contao bundles, you can uninstall them afterwards.

9 / Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

10 / Settings

Under Advanced CSS settings, select the class set materialize.json.

11 / Import the CSS

Add the following line to custom.scss (file manager, under mate/sass) so that the styling is loaded:

@import '../../../public/bundles/contaothemesnetmateisotope/scss/isotope';

Note

As of Contao 4.12 the publicly accessible subfolder was renamed from /web to /public. If your installation has a /web directory, use web instead of public in the import statement.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Customization

You find the Isotope manual here: User manual (German)

Order confirmation

Why are no order confirmation emails sent?

Filter

How can the filters be expanded only when a button is clicked?

Create a content element Grid-Start, select Inhaltscontainer (content container) as grid and the template ce_bs_gridStart_filterSidenav. Place the filter modules between the grid wrapper elements.

Grid start element:

Content elements:

Front end:

Product list

How can I change the number of products per row?

Product detail view

How can I display the image slider in the product detail view horizontally below the image?

Go to Templates and create a new template based on the original template iso_reader_mate.html5. Edit the template and uncomment the following line in line 12 (remove the slashes).

<?php $this->insert('gallery_slick_horizontal', $this->getData()); ?>

You can remove the line before it or comment it out with two slashes:

<?php //$this->insert('gallery_slick_vertical', $this->getData()); ?>

So that the product image takes up the full space, you can also select the gallery Detailansicht - Slider horizontal in the product reader module.

Images

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

contao:
    image:
        image_service: 'contao.image.imagine.gd'

contao:
    image:
        image_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Other

How do I get nicer invoices?

Install the extension isotope/isotope_documents.

The extension ships various templates that you can select in the back end for the respective document.

Update

You can update the theme easily via the Contao Manager. Then open the install tool and update the database.

If a problem occurs after the update, also have a look at our possible solutions.

Tip

A database backup beforehand never hurts!

Issues

If you ran into problems during installation or setup, or you found a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check beforehand whether your issue is already known.

NATURE Theme for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Contao 5

Contao system requirements

Version 2.0.0 of the NATURE theme requires at least Contao 5.0.0 and PHP 8.0.

Tip

We recommend Contao 5.3 with PHP version 8.3 or higher to achieve the best possible loading time with our theme!

Contao Manager

The NATURE theme is easy to install with the Contao Manager. You find a step-by-step installation guide here: NATURE theme installation.

License

Buy and register a license

The NATURE theme is available for free (with copyright notice) or with a paid license (without copyright notice).

After successful payment you receive an invoice by email and we will activate your domain shortly, so that you can register it in the Contao back end.

Until then you can already install and use the theme with the copyright notice.

Tip

As the holder of a paid license you get premium support if you have problems installing or setting up the theme.

Register the license

Note

If you bought a license and have already installed the theme, you can register it in the back end under the menu item Themes. Click Activate theme domain, enter your domain and then click Check Domain. If the domain was registered successfully, you see the message Domain registered. When you reload the page, it should look like the following screenshot.

If you only see the message “You can set a Theme Licence in Layout -> Themes.” when you click the button Activate theme domain, you have to edit the theme and enter nature in the field Theme Code (see the following screenshot). The input field for the domain should then be visible.

Remove the copyright notice

Once you have bought a license, you can remove the copyright notice, which is placed in an article, in the Contao back end.

Go to the article view, look for the article 02/03 Copyright-Hinweis under Nature Theme Elemente - 02_Footer (at the very end) and edit it via the pencil icon.

Installation

Still using Contao 4? You find the installation guide here.

Contao 4 installation guide

Note

The demo can only be imported into an empty Contao installation.

Note

If you have already created content on your site, see the following guide: Installation into an existing Contao installation.

Installation in Contao 5

Open the Contao Manager: www.your-domain.com/contao-manager.phar.php. In the Discover tab, enter NATURE Theme and click Add.

In the Packages tab you should now see a new package to be installed. Click the button Apply changes at the bottom to start the installation.

Once the installation is finished, click Update database.

Run all database migrations and click Continue. The first step creates all folders and files in the file manager.

Then the missing fields are created in the database.

In the last step the demo data is imported.

Done! When you open your site, you should already see the demo.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Mittwald: some images are not displayed Solution: switch your PHP version from FPM to CGI (under Tools > Software manager > Script languages).

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Contao 4

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Tip

Steps

1 / Install the NATURE Theme Bundle

First open the Contao Manager at the following URL: www.your-domain.com/contao-manager.phar.php. Select Discover, enter nature theme in the search field and add the package NATURE Theme.

Then switch to Packages, enter the version ^1.0 via the gear icon and start the installation of the theme with the button Apply changes. With the latest version the Contao Manager would otherwise install version 2.x, which is only compatible with Contao 5 and later.

2 / Update the database

Then open the install tool and update the database. You also have to create an admin user account in the install tool.

You can reach the install tool in the Contao Manager via the menu item Tools or at the URL: www.your-domain.com/contao/install.

3 / Synchronize the theme files and empty tl_files

Log in to the back end with the user account you created and select the menu item Nature Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager under the folder naturetheme and copies the SQL files for the database import into the templates folder.

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’. This step must be carried out before importing the database.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

4 / Import the database

If you chose the minimal Contao installation in the Contao Manager (without news, calendar, newsletter, comments, listing, FAQ), select the SQL file named minimal_installtool.sql.

If the database was imported successfully, you should get a message that a template was imported, as shown in the screenshot.

5 / Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

6 / Settings

Under Advanced CSS settings, select the class set bulma.json.

Known issues

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Mittwald: some images are not displayed Solution: switch your PHP version from FPM to CGI (under Tools > Software manager > Script languages).

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Customization

Customizing the theme

How to customize the theme – e.g. colors, fonts, font sizes, header or footer – and how to add your own CSS is explained in the section Customizing the styling.

By default all pages under Modules, Layouts and Elements are configured so that they are neither indexed by search engines nor appear in the results of the Contao search. You can change this per page at any time – with the fields Robots tag (under Meta data) and Do not search (under Search settings).

JavaScript customization

For your own JavaScript, it is best to create a separate file and include it in the page layout. This keeps updates of the original theme easy and your customizations cleanly separated.

Placing elements with your own insert tag

The page “Nature Theme Elemente” contains articles that you can include anywhere on your website with an insert tag. You find these articles by clicking Articles in the left menu and scrolling all the way down.

In the article settings of the article (via the wrench icon), select the matching Theme Helper Tag under Template settings. The field Page name lets you select a specific page – this is only necessary in a multi-domain installation.

You can then place the article with the following insert tag, e.g. in an HTML element or a template: e.g. {{theme::content::NATURE01/01}}.

How to define your own Theme Helper Tags is explained in the Theme Helper documentation.

Layouts

Under Themes → Page layouts there are four preconfigured layouts that you can assign to a page in the page settings under Layout settings:

One-column layout
Two-column layout with right column
Two-column layout with left column
Three-column layout

There are also special layouts in which the logo and navigation are stacked. This feature is available from NATURE theme version 1.7.0. To activate it, simply add the body class header-block-layout.

Header and footer

You can edit the logo in the article “01_Logo”, which you find under Nature Theme Elemente → 01_Header.

You edit the footer content in the articles under Nature Theme Elemente → 02_Footer.

Customizing the logo

The article “01_Logo” contains two logos: one for the light color scheme and one for the dark color scheme (dark mode). The second logo element gets the CSS class logo-light so that it is displayed correctly depending on the chosen color scheme or in dark mode.

Customizing the styling

After installing the theme, you find the SCSS files in the file manager under the path naturetheme/scss.

Depending on the installed theme version, there are two ways to make your own customizations:

Older theme versions: You use the files

custom.scss (for SCSS and CSS)
_custom_colors.scss (to change the base colors and choose a color scheme)
_custom_variables.scss (for more detailed adjustments such as fonts or colors of individual elements)

To change a variable, remove the comment characters (slashes) in front of the line in the respective file.

In both cases you can still add your own SCSS or CSS in custom.scss.

Tip

Note

Do not rename the theme folder naturetheme in the file manager, otherwise the SCSS files will no longer be loaded. You do not have to include the files in the page layout yourself, the theme already loads them automatically.

Color schemes

By default the NATURE theme comes with a light layout and a green primary color. You can also choose other color schemes:

Light color scheme / green primary color
Light color scheme / red primary color
Light color scheme / blue primary color
Dark color scheme / black and white
Dark color scheme / green primary color
Dark color scheme / red primary color
Dark color scheme / blue primary color

All of the color schemes above are adjusted for high contrast to ensure good readability and accessibility.

In addition there is a green and a blue color scheme that is not adjusted for high contrast. These come from an earlier theme version and are still included for backward compatibility.

@import 'color_schemes/nature_green_colors_contrast';
//@import 'color_schemes/nature_blue_colors_contrast';
//@import 'color_schemes/nature_red_colors_contrast';

//@import 'color_schemes/nature_dark_colors_contrast';
//@import 'color_schemes/nature_dark_green_colors_contrast';
//@import 'color_schemes/nature_dark_blue_colors_contrast';
//@import 'color_schemes/nature_dark_red_colors_contrast';

//@import 'color_schemes/nature_blue_colors';
//@import 'color_schemes/nature_red_colors';

Activating or deactivating dark mode

Modern operating systems and browsers support dark mode, which displays the user interface with dark backgrounds and lighter text colors – regardless of the device.

In the NATURE theme you activate dark mode by removing the comment characters (//) in front of the import line in _custom_variables.scss (or _custom_colors.scss in older versions):

//@import 'color_schemes/nature_dark_mode';

Variables

Important note If you use the latest version of the NATURE theme, you may wonder where _custom_colors.scss has gone. Don’t worry: as of NATURE version 2.5.0, a new installation of the NATURE theme only has _custom_variables.scss, which now contains all color and variable definitions.

What this means for you:

v2 (new installation from version 2.5.0): A new installation of the theme only has _custom_variables.scss with all color and variable settings. Use CSS variables for your customizations.
v1 (version older than 2.5.0 / update from a version older than 2.5.0): If you updated the NATURE theme or installed a version older than 2.5.0, both _custom_variables.scss and _custom_colors.scss remain. Use SCSS variables for your customizations.

Tip

ℹ️ How do I update my existing installation to the new version with CSS variables? As of version 2.5.0 the NATURE theme was thoroughly adapted for accessibility and switched to Bulma 1.x. If you want to use all current and future features, you should switch to the new version. You find a detailed guide here: Update from V1 to V2.

📁 Where to find the variables You find the file for adjusting the variables in the file manager under naturetheme/scss/_custom_variables.scss.

✅ Example: activating a variable

// Vorher (nicht aktiv):
//--bulma-primary: #5ca152;

// Nachher (aktiv):
--bulma-primary: #5ca152;

🧠 Important: two kinds of variables There are two basic kinds of variables, depending on where and how they are defined:

1. Global theme variables (:root) These variables apply site-wide and can be activated or adjusted directly in the :root block. They affect basic design values such as colors, font sizes or spacing.

Example:

:root {
  --bulma-primary: #5ca152;
  --bulma-font-size: 1.2rem;
}

✅ These values are then available everywhere in the theme as var(--bulma-primary) etc.

2. Component-specific variables in CSS classes Some variables only take effect within certain CSS classes or components, e.g. .navbar, .button, .pagination etc. This is because Bulma uses its own class styles for these components, which you have to override specifically.

Example:

.navbar {
  --bulma-navbar-background-color: #eaeaea;
}

⚠️ These variables must be set inside the respective CSS class, otherwise they have no effect.

🔧 The most important CSS variables Here is an overview of the most important CSS variables that you can adjust in naturetheme/scss/_custom_variables.scss.

Variable	Meaning
`--bulma-primary`	Primary color of the theme
`--bulma-primary-invert`	Contrast color to the primary color – e.g. for white text on a colored button
`--bulma-primary-bg-text`	Text in the primary color – e.g. for links or headlines on a light background

`--bulma-text`	Default text color
`--bulma-text-invert`	Contrast color for text on a dark background (e.g. –bulma-black)
`--bulma-link`	Link color
`--bulma-link-hover`	Link color on hover

`--bulma-background`	Page background color
`--bulma-boxes-background`	Background color of boxes (e.g. teaser, contact, news, event, form, breadcrumbs)
`--bulma-boxes-color`	Text color in boxes (e.g. teaser, contact, news, event, form, breadcrumbs)

`--bulma-info`	Background color for info boxes (see text elements on the demo page)
`--bulma-success`	Background color for success boxes
`--bulma-warning`	Background color for warning boxes
`--bulma-danger`	Background color for danger boxes

`--bulma-family-primary`	Primary font for body text
`--bulma-family-heading`	Font for headings

`--bulma-font-size`	Base font size for body text
`--bulma-body-line-height`	Line height for body text
`--bulma-font-weight`	Default font weight for text
`--bulma-strong-weight`	Font weight for elements
`--bulma-container-padding`	Padding of the container (left and right)
`--bulma-article-padding`	Vertical padding of articles or content areas
`--bulma-label-color`	Color of form labels

In our theme you can adjust many styles via SCSS variables. They are already prepared in the stylesheet, but commented out by default (with //). To activate or override a variable, simply remove the // at the beginning of the line.

Variables in _custom_colors.scss

Variable	Meaning
$primary	Primary color
$text	Text color
$link	Link color
$link-hover	Link color on hover
$background	Page background color
$boxes-background	Background color of boxes, teaser boxes, contact box, news boxes, event boxes, form fields, breadcrumb etc.
$boxes-color	Text color of boxes, teaser boxes, contact box, news boxes, event boxes, form fields, breadcrumb etc.
$info	Background color of the info box, see text elements on the demo page
$success	Background color of the success box, see text elements on the demo page
$warning	Background color of the warning box, see text elements on the demo page
$danger	Background color of the danger box, see text elements on the demo page

Variables in _custom_variables.scss

_custom_variables.scss already defines various variables to adapt the theme to your needs. The Bulma framework the theme is based on offers even more variables that you can define. You find them for the following elements in the Bulma documentation:

Breadcrumb Buttons Footer Forms Main navigation Modal dialog Pagination Subpage navigation Tables Tabs

Adding a font

If you want to use your own font, you can include it at the very top of _custom_variables.scss.

🔗 Recommendation: fonts via Google Webfonts Helper

A great way to include a font quickly and easily is the site:

👉 Google Webfonts Helper

There you can:

choose a font from the Google Fonts library,
select the font styles you need,
download a ZIP file with the font files,
and generate the matching @font-face CSS code right away.
Important: Under “Customize Folder prefix”, enter the path to your fonts folder, e.g. /files/naturetheme/fonts/.

📄 Example: adding the CSS to _custom_variables.scss Copy the generated CSS code from the website (e.g. for the font “Ubuntu”) and paste it at the very top of _custom_variables.scss:

/* ubuntu-regular - latin */
@font-face {
  font-display: swap;
  font-family: 'Ubuntu';
  font-style: normal;
  font-weight: 400;
  src: url('/files/naturetheme/fonts/ubuntu-v20-latin-regular.woff2') format('woff2');
}

Then assign the font in the CSS variables as follows:

:root {
    --bulma-family-primary: 'Ubuntu', sans-serif;
    --bulma-family-heading: 'Ubuntu', sans-serif;
}

$family-primary: 'Ubuntu', sans-serif;
$family-heading: 'Ubuntu', sans-serif;

Articles

CSS styles

In the article settings under “CSS style selection” you can choose between different predefined layout styles.

🖥️ Article with full screen width This style removes the page margin – the article is displayed across the full screen width, without a left and right margin.

🖥️ Article with full screen height This style makes the article at least as high as the screen. The content is centered vertically – ideal for an intro or a home page.

👉 You find examples on the demo page of the theme.

Changing background and text color

You can easily control the background and text color of an article with CSS classes. For example, the classes has-text-white and has-background-dark give you white text on a dark background.

👉 You find examples in the demo. 👉 For slanted edges with background colors and more details, see the detailed documentation on slanted edges.

You find a complete overview of all available color classes in the official Bulma documentation.

Pagespeed optimization

This page has helpful tips on optimizing the page speed of your website.

Activate the cache

For optimal performance you should activate the cache. You find a helpful guide here (German): The perfect .htaccess file for Contao

Serve images as WEBP

As of Contao 4.8 you can serve images as WEBP files in the image sizes. You activate this under: Themes > Edit the image sizes of the theme > Edit the image size settings > Expert settings.

When importing the demo data this feature is deactivated by default, as not all hosting packages support WEBP.

Use image sizes correctly

When you add images, always choose a suitable image size. This way only the image size actually needed is loaded and the page stays fast. The NATURE theme already provides suitable image sizes for news, events, sliders and other elements.

Activate SSL

Give your website more security and trust with HTTPS. You can usually activate this directly in your hosting package. Many providers offer free SSL certificates.

FAQ

Images

Why is an image not displayed?

The folder in the file manager may not be set to public. You can check this by editing the folder. Public must be ticked, otherwise the image is not displayed in the front end.

Why doesn’t the large view of an image open in a lightbox when I click it?

The theme has to load jQuery and the jQuery template j_colorbox. You can edit the layout in the back end under Themes via the third-to-last icon Edit the page layouts of theme ID 1.

Why are animated GIFs not displayed?

For animated GIFs, do not set an image size in the image settings, otherwise the animation is lost.

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

contao:
    image:
        imagine_service: 'contao.image.imagine.gd'

contao:
    image:
        imagine_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

How do I change the icons in the mobile navigation?

To show different icons (plus and minus signs) in the mobile navigation, adjust the template nav_default_nature.html5. The icons are included with Font Awesome and can be changed by changing the class names.

Look for the following places in the template:

<i class="fas fa-plus-square"></i> <i class="fas fa-minus-square"></i>

For example, to show a simple plus without a background, replace the class fa-plus-square with fa-plus.

To change the color as well, add a CSS rule to custom.scss.

.mod_navigation.navbar .navbar-menu.is-active  {
  .toggle-less i, .toggle-more i {
    color: #000;
  }
}

How do I make the navigation stick to the top of the screen when scrolling down?

Add the following CSS to custom.scss. You may then have to reload the page with Ctrl + F5 (cache).

.mod_navigation.navbar {
    position: fixed;
    transition: all .3s;
&amp;.stuck {
	height: 70px;
	
	.navbar-brand img {
		max-height: 40px;
	}
	
	.navbar-start {
	    padding: 0 70px;
	}
}
}

Now some jQuery code is needed. Either create a new JavaScript file (e.g. custom.js) and include it in the layout (under JavaScript -> External JavaScripts), or add the code directly in the layout in the field Custom JavaScript code (under JavaScript) (in that case with an opening <script> and a closing </script>).

jQuery(document).ready(function($) {
    stuckNavbar();
$(window).scroll(function () {
    stuckNavbar();
});

function stuckNavbar() {
	var scrollPos = $(window).scrollTop();
    if (scrollPos &gt; 0) {
        $(&#39;.mod_navigation.navbar&#39;).addClass(&#39;stuck&#39;);
    } else {
        $(&#39;.mod_navigation.navbar&#39;).removeClass(&#39;stuck&#39;);
    }
}
});

How do I add a search to the header?

Create a module

Create a module of type Search engine, select a redirect page and the module template mod_search_nature.

Adjust the template

Now duplicate the template nav_default_nature.html5 and rename it (e.g. to nav_default_nature_custom.html5). Select the template in the module of the main navigation (NAV / Hauptnavigation) in the template settings under Navigation template.

Edit the template and add the following line before the closing </div>. Replace ID with the ID of the search engine module.

<?php if($this->level == "level_1"): ?>{{insert_module::ID}}<?php endif; ?>

Styling

Finally, some SCSS is needed for the look. Edit custom.scss in the file manager under naturetheme/scss and add the following code:

header .mod_search {
    margin-left: 20px;
.control {
    height: 100%;
}

.formbody {
    display: flex;
}

.widget-submit {
    margin: 0;
}

.widget:not(:last-child) {
    margin-bottom: 0;
}

.widget-text {
    margin-right: 10px;
    
    input {
        height: 100%;
        border: none;
    }
}
}@media (max-width: 1023px) {
header .mod_search {
margin: 10px 0 0 10px;
}
}

The result

How do I show a header bar above the main navigation, e.g. for contact and address details?

Create an article

Create a new article under Nature Theme Elemente - 01_Header.

Edit the article settings, select NATURE01/02 as the Theme Helper Tag under Template settings and add the class header-top under Expert settings.

Add content

To show contact and address details, you can create the element Text and icon (under Contao Themes) and enter a text and select a Font Awesome icon.

Create a module

Go to Themes, edit the front end modules of the theme (gear icon) and create a new module of type Custom HTML code. Add the following insert tag:

{{theme::content::NATURE01/02}}

Edit the layout

Now edit the page layouts of the theme (right after the gear icon) and edit the layout where the header bar should be displayed. Under Front end modules - Included modules, add the module you just created at the very top and select Header as the layout section.

Styling

Finally, add the following SCSS code to custom.scss so that the header bar is displayed properly.

$headerTopSize: 35px;
body:not(.home):not(.contact) #header .inside {
padding-top: 140px;
}
.header-top {
position: absolute;
top: 0;
width: 100%;
height: $headerTopSize;
background: darken($navbar-background-color,10%);
left: 0;
z-index: 2;
color: $navbar-item-color;
font-size: .8em;
.block:not(:last-child) {
margin-bottom: 0;
}
.ce_ct_featureElement {
.icon {
width: inherit;
margin-right: 10px;
padding-bottom: 0;
}
.feature-text {
  width: inherit;
}

&amp;:not(:last-child) {
  margin-right: 30px;
}
}
.content {
display: flex;
align-items: center;
justify-content: center;
height: 100%;
}
.mod_navigation {
top: $headerTopSize;
}
}
@media (max-width: 1023px) {
.full-width-height-slider .text {
padding-top: 160px;
}
}
@media (max-width: 992px) {
.header-top {
display: none;
+ .mod_navigation {
  top: 0;
}
}
}

The result

How do I add a shortlink navigation at the edge of the screen?

Create a folder “Shortlinks” in the site structure and the pages inside it (e.g. as internal redirects). With the Font Awesome insert tags in the page name you can show icons.

Create a module of type Custom navigation and give it the class shortlinks.

Include the module in the footer of the layout.

Finally, we need some CSS for the styling, which you can add to custom.scss.

.shortlinks {
    position: fixed;
    top: 0;
    right: 0;
    z-index: 100;
    height: 100%;
    display: flex;
    align-items: center;
@media (max-width: 1023px) {
    display: none;
}

a {
    background: $link;
    display: block;
    color: #fff;
    width: 70px;
    height: 70px;
    display: flex;
    align-items: center;
    justify-content: center;
    border-top-left-radius: 5px;
    border-bottom-left-radius: 5px;
    margin: 25px 0;
    padding: 10px;
    
    &amp;:hover {
        background: $link-hover;
    }
    
    i {
        color: #fff;
        font-size: 2rem;
    }
}
}

This is what it should look like in the end:

How do I add the navigation effect of the MATE theme?

You can add the effect with the script Headroom.js, which you can download at wicky.nillia.ms/headroom.js.

Include headroom.min.js in the page layout under External JavaScripts and also add the following JavaScript in the page layout under Custom JavaScript code. Alternatively, you can of course move it to a separate JavaScript file.

<script>
var myElement = document.querySelector(".mod_navigation.navbar");
var headroom = new Headroom(myElement, {
 "offset": 600
});
headroom.init();
</script>

Finally, add the following CSS to custom.scss.

.headroom {
   will-change: transform;
   transition: transform 200ms linear;
}
.headroom–pinned {
transform: translateY(0%);
}
.headroom–unpinned {
transform: translateY(-100%);
}
.mod_navigation.navbar {
position: fixed;
transition: all .3s;
&.stuck {
height: 70px;
.navbar-brand img {
   max-height: 40px;
}

.navbar-start {
   padding: 0 70px;
}
}
}

Slider

How do I remove the border around the image in the home page slider?

Add the following CSS to custom.scss:

.full-width-height-slider .text img {
  border: none;
}

Other

How do I show a Google Maps map?

Install the extension Google Maps. In the back end you then find a menu item Google Maps where you can create your map.

With a content element (Media elements -> Google Map) you include the map at the desired place in an article. To show it e.g. in the header of the contact page, include it in the article Header.

You can enter the API key in the settings under Google Maps.

To display the map without spacing at the bottom, some CSS in custom.scss is necessary.

.dlh_googlemap.block:not(:last-child) {
	margin-bottom: 0;
}

This is what it could look like:

How do I prevent the theme CSS file from being cached?

Visitors who have already visited the website are usually served a cached file. If you want to prevent this, you can adjust the fe_page template.

Adjust the following template: fe_page_nature.html5.

It should look like this:

<link rel="stylesheet" type="text/css" media="all" href="<?php
// add stylesheets
$combiner = new Combiner();
$combiner->add('bundles/contaothemesnetnaturetheme/fonts/fontawesome/css/all.min.css');
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
$combiner->add('bundles/contaothemesnetnaturetheme/scss/nature_win.scss');
} else {
$combiner->add('bundles/contaothemesnetnaturetheme/scss/nature.scss');
}
echo $combiner->getCombinedFile(); ?>?date=<?= time() ?>">

Multidomain

If several domains in one Contao installation should use the NATURE theme, this is possible with a few workarounds.

The goal of this guide is for each domain to have its own custom.scss, _custom_colors.scss and _custom_variables.scss. You should have at least NATURE theme version 1.11.0 (up to Contao 4.13) or 2.1.0 (Contao 5 and later) installed.

Note

As of Contao 4.12 the publicly accessible subfolder was renamed from /web to /public. If your installation has a /web directory, use web instead of public in the following code examples.

1) Create the SCSS files

Create a folder in the file manager under naturetheme/scss (e.g. domain2). Copy the files custom.scss, _custom_colors.scss and _custom_variables.scss into this folder.

In _custom_colors.scss, adjust the paths of the color schemes as follows.

//@import '../../../../public/bundles/contaothemesnetnaturetheme/scss/color_schemes/nature_red_colors';
//@import '../../../../public/bundles/contaothemesnetnaturetheme/scss/color_schemes/nature_blue_colors';
//@import '../../../../public/bundles/contaothemesnetnaturetheme/scss/color_schemes/nature_dark_colors';

/*
 * comment line to disable the ios dark mode
 */

//@import '../../../../public/bundles/contaothemesnetnaturetheme/scss/color_schemes/nature_dark_mode';

//@import 'color_schemes/nature_red_colors';
//@import 'color_schemes/nature_blue_colors';
//@import 'color_schemes/nature_dark_colors';

/*
 * comment line to disable the ios dark mode
 */

//@import 'color_schemes/nature_dark_mode';

In the same folder, also create a file nature.scss with the following content.

@import '../../../../public/bundles/contaothemesnetnaturetheme/scss/bulma/utilities/initial-variables';

@import '../../../../public/bundles/contaothemesnetnaturetheme/scss/fonts';

@import "_custom_colors";
@import "../../../../public/bundles/contaothemesnetnaturetheme/scss/nature_colors";

@import "_custom_variables";
@import "../../../../public/bundles/contaothemesnetnaturetheme/scss/nature_variables";

@import "../../../../public/bundles/contaothemesnetnaturetheme/scss/nature_style";

@import 'custom';

This is what it should look like in the end:

2) Create a template

Under Templates, create a new template fe_page_nature.html5 and rename it (e.g. fe_page_nature_domain2.html5).

Look for the following line and add the name of the domain (domain2 in this example) inside getCombinedStylesheet().

<link rel="stylesheet" type="text/css" media="all" href="<?= ContaoThemesNet\NatureThemeBundle\ThemeUtils::getCombinedStylesheet('domain2');

3) Create a layout

Go to Themes and Edit the page layouts of the theme (4th icon from the right) and duplicate any layout. Edit the layout and select the fe_page template you just created under Expert settings (at the very bottom) in Page template.

4) Assign the layout to the page

Finally, assign the layout to a page.

Update to CSS variables

With version 2.5.0 the NATURE theme was made accessible, updated from Bulma 0.x to Bulma 1.x, and all SCSS variables were switched to CSS variables. This means a manual intermediate step is necessary when updating from an older version (< 2.5.0) to a newer version (≥ 2.5.0).

Requirements

Existing installation of the NATURE theme < 2.5.0
Update to Contao 5

1. Update the theme

Open the Contao Manager.
Update the NATURE theme to 2.5.0 or higher (recommended: latest version).

2. Changes to the SCSS files

As of version 2.5.0 the file _custom_colors.scss no longer exists. All color definitions are now in _custom_variables.scss.

📂 Old structure (< 2.5.0)

naturetheme/scss/
├── custom.scss
├── _custom_variables.scss
└── _custom_colors.scss

📂 New structure (≥ 2.5.0)

naturetheme/scss/
├── custom.scss
└── _custom_variables.scss

3. Create the new theme files

After the update to 2.5.0 or higher the site still works, but not all new features are available right away. You should therefore create the current theme files.

Complete re-import of the theme folder

In the file manager, rename the folder naturetheme, e.g. to naturetheme-alt.
In the Contao Manager, open System maintenance → Check database and run the database update.
The migration that creates the new theme files is now offered – run it.
A new folder naturetheme with the current files is created.

Moving images: If there were images in the old naturetheme folder, move them either into the new folder or into a separate image folder. References are kept if the images were added in Contao via “Add an image”.

New / old file structure:

Theme files migration:

4. Transfer your own customizations

If you made changes in custom.scss, _custom_colors.scss or _custom_variables.scss, you have to transfer them manually to the new files.

Important: V2 uses CSS variables instead of SCSS variables.

Example color variable

Before (V1 – SCSS):

$primary: #5ca152;

New (V2 – CSS variables):

:root {
  --bulma-primary: #5ca152;
}

CSS variables are used in code like this:

color: var(--bulma-primary);

Component-specific variables

Some variables are not defined in :root but within a component:

Before (V1 – SCSS):

$navbar-background-color: #eaeaea;

New (V2 – CSS variables):

.navbar {
  --bulma-navbar-background-color: #eaeaea;
}

5. Update SCSS customizations

If your custom.scss still uses SCSS variables ($variable), change them to the CSS variable format (var(--variable)).

Example:

/* Vorher */
background: $primary;

/* Neu */
background: var(--bulma-primary);

Accessibility

You find detailed tips, new features from version 2.5.0 and best practices for accessible design here: ♿ Accessibility in the NATURE theme

Direct download of the new variables file

You find the current _custom_variables.scss here: 📄 GitHub: _custom_variables.scss

If you want to adjust the files manually, the scss folder must also contain an empty file named .v2 to activate the V2 structure.

Accessibility

Accessibility in the NATURE theme (version 2.5.0 and later)

With version 2.5.0 the NATURE theme was thoroughly revised with regard to accessibility and switched to CSS variables (Bulma 1.x). To use these features, a manual intermediate step is necessary when updating from an older version (< 2.5.0) to a newer version (≥ 2.5.0). ➡️ Guide: Update to CSS variables

1. Header icons for contrast mode and font size

Version 2.6.0 adds controls to the header to:

toggle contrast mode (high contrast)
adjust the font size (links to the accessibility statement by default)

Settings

Edit the website root in the site structure.
Under WCAG settings (Web Content Accessibility Guidelines) you find two checkboxes:
- “Allow switching to high contrast mode”
- “Allow displaying the icon for changing the font size” These options are active by default in a fresh installation.

If you installed the theme from scratch

If you install the NATURE theme from version 2.6.0 and import the demo, the icons are already in the header.

If you have an existing installation

Create an article
- Under Articles, create a new article, e.g. “02 contrast and size” under Nature Theme Elemente -> 01_Header.
- In the article settings, select the Theme Helper Tag NATURE01/02 under Template settings.

Add content
- Create a text element in the article with the following content:
```
{{comp::contrast}} {{comp::size::barrierefreiheit.html#fontSize}}
```
- Add the CSS class wcag.

Including it in the template
- The article with the Theme Helper Tag NATURE01/02 is included automatically via the navigation template.
- If you have customized your own mod_navigation_nature.html5, add the insert tag there manually.

<div id="navbarMain" class="navbar-menu is-primary">
    <?= $this->items ?>
    {{theme::content::NATURE01/02}}
</div>

2. New accessible templates (version 2.5.0 and later)

To avoid redundant links (e.g. image, headline and button all linked), it is enough to link only the button. This improves keyboard navigation.

Adapted templates are available for various content elements such as teaser box, content box, feature element etc. These templates have the suffix _bf (German “barrierefrei”, accessible).

3. General accessibility tips

When creating content, pay attention to the following:

Provide alternative texts (alt tags) for images
Use meaningful link texts (not just “click here”)
Mind the contrast (text color/background color)
Use headings in a correct hierarchy
Use tables only for tabular data (not for layout)
Give forms label elements

4. Tools for testing accessibility

pdir Website Check – automatic check for accessibility and SEO.
WAVE Web Accessibility Evaluation Tool – browser extension for analyzing accessibility problems.
axe DevTools – developer tools for accessibility testing.
Contrast Checker – checks color contrast.

Slanted edges

Slanted edges for articles with a background color

Requirements

NATURE theme version 2.6.0 or later
V2 installation with CSS variables (not SCSS variables)
Contao 5
Bulma 1.x

This feature adds slanted edges to articles with background colors.

Slanted edges - CSS classes

Add the CSS classes for slanted edges in the article settings under the field CSS style selection. If you use a newer version of the theme demo, the classes can be selected there. Otherwise you can enter the classes directly in the CSS class field.

Slanted edge	CSS class
Slope at top ↖ (rises to the left)	`has-slope-top-left`
Slope at top ↗ (rises to the right)	`has-slope-top-right`
Slope at bottom ↘ (falls to the right)	`has-slope-bottom-right`
Slope at bottom ↙ (falls to the left)	`has-slope-bottom-left`

Background color classes

Slanted edges only work in combination with background colors. Assign one of the following classes to an article, for example:

Class	Background color (example)
`has-background-white`	hsl(0, 0%, 100%)
`has-background-black`	hsl(0, 0%, 4%)
`has-background-light`	hsl(0, 0%, 96%)
`has-background-dark`	hsl(0, 0%, 21%)
`has-background-primary`	hsl(171, 100%, 41%)
`has-background-link`	hsl(217, 71%, 53%)
`has-background-info`	hsl(204, 86%, 53%)
`has-background-success`	hsl(141, 71%, 48%)
`has-background-warning`	hsl(48, 100%, 67%)
`has-background-danger`	hsl(348, 100%, 61%)

More background shades

Class	Background color (example)
`has-background-black-bis`	hsl(0, 0%, 7%)
`has-background-black-ter`	hsl(0, 0%, 14%)
`has-background-grey-darker`	hsl(0, 0%, 21%)
`has-background-grey-dark`	hsl(0, 0%, 29%)
`has-background-grey`	hsl(0, 0%, 48%)
`has-background-grey-light`	hsl(0, 0%, 71%)
`has-background-grey-lighter`	hsl(0, 0%, 86%)
`has-background-white-ter`	hsl(0, 0%, 96%)
`has-background-white-bis`	hsl(0, 0%, 98%)

Example

You find an example page with slanted edges in our theme demo:

https://nature.contao-themes.net/layouts/schraege-kanten.html

There, articles without a background color and slope classes are placed between colored articles to create the effect.

Elements

This section explains all elements that the theme provides or that need adjusting, and how you can use them.

Buttons

Creating a button

To create a button, add an element of type “Hyperlink”.

🔧 Select the template

Up to Contao 4.13: select the template ce_hyperlink_button
Contao 5 and later: select the template content_element/hyperlink/button_nature

🎨 Styling the button

Under Advanced CSS classes you can add classes to customize the look of the button. You find an overview of possible styles in the Bulma documentation.

👉 You find examples of different buttons in the demo.

Content box

Placing the element

To add a content box, place an element of type Content Box.

To display several elements side by side, place them as described in the section Grid.

Changing colors

Under Advanced CSS classes you can set a class for the background color of the content box: .is-primary, .is-link, .is-info, .is-success, .is-warning or .is-danger. If you set no class, the box is displayed in the default color (like the first element in the screenshot below).

Examples

You find examples in the demo.

Content Slider

Placing the article

For a full-width slider – like on the home page – create a separate article. In the article settings, select the option Artikel mit voller Bildschirmbreite (article with full screen width) under Expert settings in CSS style selection.

Adding the elements

Place the two wrapper elements in the article: Content slider (wrapper start) and Content slider (wrapper end). Between them go one or more slider elements, depending on how many slides you want to show.

Style settings for the wrapper element

For the wrapper start element, select under CSS style selection:

Slider mit voller Breite und Höhe (full width and height) to show it full screen
Optional: Parallax-Slider to activate an animated parallax effect while scrolling

Configuring the slider elements

In the slider element you can add the following content:

Headline and text
Image or video
Link
Background image or video

Under CSS style selection you can also choose whether the text is displayed light (white) or dark (black) – depending on whether your background is rather dark or light. Without a selection, the text is displayed in black by default.

Example in the demo

You find a complete example slider in the demo.

Adjusting the slider height

Note

This feature is available from NATURE theme version 1.10.0.

You can adjust the height of the slider in _custom_variables.scss with the following CSS or SCSS variables:

Variant 1: full-screen slider

:root {
    --bulma-nature-slider-min-height: 100vh;
    --bulma-nature-slider-mobile-min-height: 100vh;
}

$nature-slider-min-height: 100vh; // Desktop
$nature-slider-mobile-min-height: 100vh; // Mobil

Grid

Arranging content side by side (grid system)

The NATURE theme is based on Bulma – a modern CSS framework that lets you display content flexibly side by side. On mobile devices it is automatically stacked.

Variant 1: classic grid (Contao 4 and later, all NATURE versions)

1. Place the content container

To display e.g. two text elements side by side, you need a wrapper: place two content elements of type Contao Themes (Inhaltscontainer Anfang) (content container start) and Inhaltscontainer Ende (content container end).

Assign the class .columns to the element Inhaltscontainer Anfang under Advanced CSS classes – this is the container class for the grid.

2. Define the columns

Between the wrapper elements, place the content elements that should appear side by side – e.g. two text elements. Under Advanced CSS classes, give each of these elements the class .column.

3. Additional options

With further Bulma classes you can control columns precisely: e.g. widths such as .is-half, .is-one-third, or responsive classes such as .is-full-mobile, .is-one-quarter-desktop. You can also control spacing and alignment.

👉 See: Bulma column documentation

Variant 2: smart grid & fixed grid (NATURE theme 2.5.0 and later with Bulma 1.x)

Since version 2.5.0 (only for new installations or if you updated to Bulma 1.x manually) two more modern grid variants are available:

Smart grid

Element: Element group
Class: .grid
Content elements are placed directly inside the group

See: Bulma smart grid

Fixed grid

Element: Element group
Class: .fixed-grid
Further classes possible: e.g. .has-2-cols, .has-1-cols-mobile
Inside the group, place another element group with the class .grid, which then contains the content elements

See: Bulma fixed grid

📌 The element group is a new content element in Contao 5, comparable to a wrapper start/end, but more modern and compact.

Header image

Placing the article

Place the header image in a separate article in the header. In the article settings, select Artikel mit voller Bildschirmbreite (article with full screen width) under Expert settings in CSS style selection.

Placing the element

To place a header image, use the element type Image and select the template ce_image_headerimage (up to Contao 4.13) or content_element/image/header_image_nature (Contao 5 and later) under Template settings.

CSS styles

Under CSS style selection you can optionally choose a darker image, white text and a larger header image.

Examples

You find examples in the demo: header image dark, header image light, large header image dark, large header image light.

Dark / normal header image:

Dark / large header image:

Light / normal header image:

Light / large header image:

Hero element

Placing the element

To add a hero element (text element with background), place an element of type Text and select the template ce_text_cthemes_simplebox_nature (up to Contao 4.13) or content_element/text/simplebox_nature (Contao 5 and later).

Changing colors

Under Advanced CSS classes you can select a class for the primary color if the hero element should be displayed in a different background color: .is-primary, .is-link, .is-info, .is-success, .is-warning and .is-danger. If no class is selected, it is displayed like the first element in the following screenshot.

Examples

You find examples in the demo.

Lists

For the element type List, besides an ordered and unordered list you can choose different templates:

content_element/list/alphabetic_lowercase: alphabetic, lowercase
content_element/list/alphabetic_uppercase: alphabetic, uppercase
content_element/list/roman_lowercase: Roman numerals, lowercase
content_element/list/roman_uppercase: Roman numerals, uppercase

ce_list_alphabetic_lowercase: alphabetic, lowercase
ce_list_alphabetic_uppercase: alphabetic, uppercase
ce_list_roman_lowercase: Roman numerals, lowercase
ce_list_roman_uppercase: Roman numerals, uppercase

You find examples in the demo.

Price table

Placing the element

To display a price table, place an element of type Preis-Tabelle (price table).

To highlight a box, fill in the field Label for highlighted box. To display several elements side by side, place them as described in the section Grid.

Examples

You find examples in the demo.

Shortlinks

Shortlinks (NATURE v2.6.0 and later)

With the NATURE theme version 2.6.0 and later (only with Contao 5 and Bulma 1.x / V2) you can use shortlinks – small linked icons fixed to the left or right edge of the screen.

Requirements

NATURE theme version 2.6.0 or later
V2 installation with CSS variables (not SCSS variables)
Contao 5
Bulma 1.x

Setting up shortlinks – step by step

1. Create an article

Create a new article, e.g. under “Nature Theme Elemente”.

In the article settings:

Under Template settings → select a Theme Helper Tag, e.g. NATURE03/01
Under Expert settings → CSS class, add one of the following position classes:

Position	CSS class
Left top	`shortlinks left-top`
Left center	`shortlinks left-center`
Left bottom	`shortlinks left-bottom`
Right top	`shortlinks right-top`
Right center	`shortlinks right-center`
Right bottom	`shortlinks right-bottom`

💡 If you imported the current demo, you can also select these classes via CSS style selection.

2. Add hyperlink elements

Now add as many content elements of type Hyperlink to the article as you like.

Field	Content
Link address	e.g. `tel:+49123456789` or `mailto:info@example.com`
Link text	Icon via a Font Awesome insert tag, e.g. `{{fa::phone}}`
Link title	e.g. `contact by phone`

👉 You find an explanation and a list of available insert tags here: Font Awesome Inserttag Bundle (GitHub)

3. Create a module

Create a new module under Themes → Modules:

Module type: Custom HTML
HTML content:

{{theme::content::NATURE03/01}}

📌 Make sure the Theme Helper Tag (NATURE03/01) matches the article.

4. Include the module in the page layout

Go to the page layout and open the include settings:

Go to Include settings
Under Included elements → add a new row
Section: Footer (layout section)
Module: select the shortlink module you created
Save

Example icons via insert tag

{{fa::phone}}      →  phone icon
{{fa::envelope}}   →  email icon
{{fab::facebook}}  →  Facebook icon
{{fab::instagram}} →  Instagram icon
{{fab::whatsapp}}  →  WhatsApp icon
{{fab::linkedin}}  →  LinkedIn icon
{{fab::pinterest}} →  Pinterest icon
{{fab::youtube}}   →  YouTube icon
{{fab::tiktok}}    →  TikTok icon
{{fab::github}}    →  GitHub icon

You find a complete overview of all available icons here: GitHub: Font Awesome Inserttag Bundle

Result

The shortlinks now appear fixed to the left or right edge of the screen, depending on the chosen position.

✅ Ideal for:

Phone or email contact
Links to social media
Quick access to certain sections of the page

Table

You can set the following classes for the element type Table:

table is-bordered: with borders
table is-striped: striped
table is-narrow: less spacing
table is-hoverable: with hover

You can also combine all classes, e.g.: table is-bordered is-striped is-narrow is-hoverable.

You find examples in the demo.

Tabs

Tab headers

First place an element of type Tabs-Reiter (tab header) for the individual tabs.

In the tab settings, always assign a unique value and a label.

Tab wrapper

Now place one element of type Tabs-Umschlag (Start) and one of type Tabs-Umschlag (Stop) for each tab. Place the content between the wrapper elements.

For the element type Tabs-Umschlag (Start), enter the corresponding value from the element Tabs-Reiter.

Example of the placed elements in the back end:

Example

You find examples in the demo.

Teaser box

Placing the element

To add a teaser box, place an element of type Teaser Box.

You find examples in the demo.

Sticky/full-height teaser box

For a teaser box as in the following screenshot, select the template ce_cthemes_teaserbox_fullheight. If you select Sticky Teaserbox under Expert settings in CSS style selection, the images “stick” to the top of the screen when scrolling down.

Teaser box with full-size background image

For a teaser box as in the following screenshot, select the template ce_cthemes_teaserbox_nature.

Text and icon

Placing the element

Place an element of type Text and icon.

You can define a headline, a text, the Font Awesome icon and optionally a link. You find a list of possible icons on the Font Awesome website. When you click an icon, you also see the classes at the top that you have to enter in the field Font Awesome 5 Icon (classes).

Element with background

If the element should have a background, as in the following screenshot, select ce_cthemes_feature_element_nature under Template settings.

Examples

You find examples in the demo.

Modules

Topics

Events/calendar

Event list

Templates:

event_teaser_nature: event list with images and teaser
event_list_nature: event list with teaser only
event_upcoming: simple list of events

Image sizes:

Events mit Teaser (einspaltiges Layout) – events with teaser (one-column layout)
Events mit Teaser (zweispaltiges Layout) – events with teaser (two-column layout)

Event reader

Templates:

event_full_nature: event details
event_full_nature_header: header image

Calendar

Templates:

cal_default_nature: normal calendar
cal_mini: mini calendar

Create a module

To add a modal dialog, go to the front end modules and create a new module of type Modal. There you can set a link, give it additional classes and edit the actual content of the modal dialog. You can include the module anywhere, e.g. in an article.

Example

Navigation templates:

nav_default_nature: main navigation
nav_default_nature_aside: subpage navigation

Custom templates:

mod_navigation_nature: main navigation
mod_navigation_nature_aside: subpage navigation

Note

This feature is only available from NATURE theme version 1.6.0.

To display a mega menu, select the template mod_navigation_nature_megamenu for the module type Navigation menu.

You can customize the mega menu with variables in _custom_variables.scss:

$megamenu-width: 100%; // Breite des Megamenü
$megamenu-right: 0px; // Abstand zum rechten Bildschirmrand
$megamenu-background-color: $boxes-background; // Hintergrundfarbe
$megamenu-background-color-home: $megamenu-background-color; // Hintergrundfarbe nur für die Startseite
$megamenu-item-width: 20%; // Breite der Spalten, z. B. 20% für 5 Spalten
$megamenu-padding: 20px 60px 5px 30px; // Innenabstand oben, rechts, unten, links
$megamenu-link-lvl2-color: #000; // Schriftfarbe Level 2
$megamenu-link-lvl2-color-hover: $primary; // Schriftfarbe Level 2 bei Mouse Hover
$megamenu-link-lvl3-color: #4a4a4a; // Schriftfarbe Level 3
$megamenu-link-lvl3-color-hover: $link-hover; // Schriftfarbe Level 3 bei Mouse Hover
$megamenu-border-color: $primary; // Rahmenfarbe

Further customization

Create a .js file, e.g. custom.js, with the following content. You can include the file in the page layout under External JavaScripts.

jQuery(document).ready(function($) {
  $('.megamenu .level_1 > .navbar-item').hover(function() {
    $('.navbar-dropdown.level_2').css('display', 'none');
    $(this).find('.navbar-dropdown.level_2').css('display', 'flex');
  });

  $('body').click(function() {
    $('.navbar-dropdown.level_2').css('display', 'none');
  });
});

News

News list

Templates:

news_latest_nature_col2: news list with images and teaser (two columns)
news_latest_nature_col3: news list with images and teaser (three columns)
news_short_nature: news list with teaser only
news_simple: simple list of news

Image sizes:

News / Zweispaltig (two columns)
News / Dreispaltig (three columns)

News reader

Templates:

news_full_nature: news details
news_full_nature_header: header image

Extensions

Topics

With the Social Feed Bundle you can display posts from Facebook and Instagram in the NATURE theme. Simply install the package named pdir/social-feed-bundle with the Contao Manager.

A guide on setting up the feed and placing the modules can be found on the following page: Social Feed documentation.

When setting up the news module, select news_social_feed_nature as the news template.

The social feed is already styled in the NATURE theme as shown in the following screenshots.

One column

Two columns

Three columns

Four columns

Multilingual websites

1 | Install the language switcher extension

First install the extension Sprachenwechsler (terminal42/contao-changelanguage) in the Contao Manager.

2 | Duplicate the site structure

Open the site structure and duplicate the website root including its subpages. After duplicating, all pages and articles are invisible, so you have to make every page and every article visible for a change to show in the front end.

In the page settings of the website root for the new language, enter the corresponding language code under DNS settings -> Language, e.g. en.

3 | Select the page in the main language

Edit each page of the new language and select the corresponding page in the main language under Language & translation.

4 | Create a module

Select Themes in the left navigation and edit the front end modules of the theme (gear icon). Create a new module of type Change language (under Miscellaneous). Further settings are not strictly necessary.

5 | Place the module in the layout

Select Themes in the left navigation again and edit the page layouts of the theme (to the right of the gear icon). In the corresponding layout, duplicate the first row under Front end modules and select the module you just created. The module must be at the very top and in the header.

6 | CSS for the display

Finally, add the following SCSS to custom.scss. You find it in the file manager under naturetheme/scss.

body:not(.home):not(.contact) #header .inside {
  padding-top: 140px;
}

nav.mod_changelanguage {
  position: absolute;
  top: 0;
  width: 100%;
  height: 40px;
  background: #000;
  left: 0;
  z-index: 2;
  display: flex;
  align-items: center;
  justify-content: flex-end;
  padding: 0 85px 0 50px;

  ul {
    display: flex;

    li {
      padding-left: 10px;
    }
  }

  + .mod_navigation {
    top: 40px;
  }
}

@media (max-width: 1023px) {
  .full-width-height-slider .text {
    padding-top: 160px;
  }

  nav.mod_changelanguage {
    padding: 0 20px;
  }
}

Example

In the end, as shown in the screenshot, a bar with the language switcher should appear above the main navigation.

Demo

You find a demo with the one-page navigation here.

Guide

Install the extension

Install the extension Onepage Navigation by Erdmann & Freunde with the Contao Manager and update the database.

Create a module

Create a module of type Artikelnavigation (Onepage) and select the template mod_onepage_navigation_nature under Module template.

Create a layout

Create a new layout or duplicate an existing one and select the module you just created under Included modules.

To keep the navigation at the top of the screen when scrolling down, add the following code snippets under Custom JavaScript code and Additional head tags. You can of course also move them to separate files and include the files in the layout.

Custom JavaScript code

<script>
jQuery(document).ready(function($) {
    stuckNavbar();
    
    $(window).scroll(function () {
        stuckNavbar();
    });
    
    function stuckNavbar() {
    	var scrollPos = $(window).scrollTop();
        if (scrollPos > 0) {
            $('.mod_navigation.navbar').addClass('stuck');
        } else {
            $('.mod_navigation.navbar').removeClass('stuck');
        }
    }
});
</script>

Additional head tags

<style>
.mod_navigation.navbar {
    position: fixed;
    transition: all .3s;
    
    &.stuck {
    	height: 70px;
    	
    	.navbar-brand img {
    		max-height: 40px;
    	}
    	
    	.navbar-start {
		    padding: 0 70px;
		}
    }
}
</style>

Assign the layout to the page

Assign the new layout to the page or the website root.

Edit the articles

Create an article for each menu item. In the article settings, tick Add as navigation item under One-page navigation.

Real Estate Module

The NATURE theme already comes with templates and stylesheets for the Real Estate Module (Maklermodul).

Documentation

The Real Estate Module documentation contains all information on installing and setting up the module.

Including the stylesheets

Add the following line to custom.scss (/files/naturetheme/sass) so that the list and detail view are displayed as in the screenshots.

@import 'maklermodul';

Setup

Create pages

First create one page each for the list view and the detail view.

Adjust the layout

If no breadcrumb should be displayed in the list and detail view, simply duplicate the one-column layout (under Themes) and remove the breadcrumb from Included modules. Then assign the layout to the pages under Layout settings.

List view module

Create a module of type Immobilienliste as described in the documentation.

Select the real estate template makler_list_nature
It is recommended to set an image size: e.g. 633 x 390px (matches the images in the demo)

Detail view module

Create a module of type Expose as described in the documentation.

Select the real estate template makler_details_extended_nature

Header image module

Create a module of type MaklerModul Kopfbild as described in the documentation.

Placing the modules

Place the modules for the list view and the exposé in the articles of the respective pages.

Under the page for the list view, create an article for the header image. Under Elements you find all notes on creating a header image.

Under the page for the exposé, also create an article for the header image and place the module of type MaklerModul Kopfbild there.

For the articles of the header image and the exposé, select Artikel mit voller Bildschirmbreite (article with full screen width) under CSS style selection in the article settings.

Examples

If you have carried out all steps as described, the list should be displayed as in the following screenshots.

List view with select filter

List view with button filter

Exposé

Issues

If you ran into problems during installation or setup, or you noticed a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check first whether your problem is already known.

ODD Theme for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Contao 5

Contao system requirements

Version 3.0.0 of the ODD theme requires at least Contao 5.0.0 and PHP 8.0.

Tip

We recommend Contao 5.3 with PHP 8.3 or higher to get the best possible loading time with our theme!

Contao Manager

The ODD theme can easily be installed via the Contao Manager. You find a step-by-step installation guide here: ODD theme installation.

License

Buy and register a license

The ODD theme is available for free (with copyright notice) or with a paid license (without copyright notice).

After successful payment (possible payment methods are PayPal, Sofortüberweisung or credit card) you receive an invoice by email and we will activate your domain shortly, so that you can register it in the Contao back end.

Until then you can already install and use the theme with the copyright notice.

Tip

As the holder of a paid license you get premium support if you have problems installing or setting up the theme.

Register the license

Note

If you bought a license and have already installed the theme, you can register it in the back end under the menu item Themes. Click Activate theme domain, enter your domain and then click Check Domain. If the domain was registered successfully, you see the message Domain registered. When you reload the page, it should look like the following screenshot.

If you only see the message “You can set a Theme Licence in Layout -> Themes.” when you click the button Activate theme domain, you have to edit the theme and enter 0.1 in the field Theme Code (see the following screenshot). The input field for the domain should then be visible.

Remove the copyright notice

Once you have bought a license, you can remove the copyright notice, which is placed in an article, in the Contao back end.

Go to the article view, look for the article 03 Copyright under Elemente > 03 Footer and edit it via the pencil icon.

Installation

Still using Contao 4? You find the installation guide here.

Contao 4 installation guide

Note

The demo can only be imported into an empty Contao installation.

Note

If you have already created content on your site, see the following guide: Installation into an existing Contao installation.

Installation in Contao 5

Open the Contao Manager: www.your-domain.com/contao-manager.phar.php. In the Discover tab, enter ODD Theme and click Add.

In the Packages tab you should now see a new package to be installed. Click the button Apply changes at the bottom to start the installation.

Once the installation is finished, click Update database.

Run all database migrations and click Continue. The first step creates all folders and files in the file manager.

Then the missing fields are created in the database.

In the last step the demo data is imported.

Done! When you open your site, you should already see the demo.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Contao 4

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.4 or higher.

Tip

Steps

1 / Install the ODD Theme Bundle

First open the Contao Manager at the following URL: www.your-domain.com/contao-manager.phar.php. Select Discover, enter odd theme in the search field and add the package ODD Theme.

Then switch to Packages, enter the version ^2.0 via the gear icon and start the installation of the theme with the button Apply changes. With the latest version the Contao Manager would otherwise install version 3.x, which is only compatible with Contao 5 and later.

2 / Update the database

Then open the install tool and update the database. In the install tool you also have to create an admin user account.

You reach the install tool in the Contao Manager via the menu item Tools or via the URL: www.your-domain.com/contao/install.

3 / Synchronize the theme files and empty the table ’tl_files'

Log in to the back end with the user account you created and select the menu item ODD Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager under the folder odd and copies the SQL files for the database import into the templates folder.

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’. This step must be carried out before importing the database.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

4 / Import the database

If you chose the minimal Contao installation in the Contao Manager (without news, calendar, newsletter, comments, listing, FAQ), select the SQL file named minimal_installtool.sql.

If the database was imported successfully, you should get a message that a template was imported, as in the following screenshot.

Alternatively, you can import the sql file with phpMyAdmin.

5 / Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

6 / Settings

Select the class set

In the settings under System -> Settings, select the class set bootstrap4.json in the tab Advanced CSS settings.

Done!
Your website should now show the theme’s demo content when you open your domain.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Customization

JavaScript customization

For your own JavaScript, it is best to create a separate file and include it in the theme.

Placing elements with your own insert tag

The page ODD Elements contains articles that you can include anywhere on your website with an insert tag. To get to the articles, click Articles in the left menu and scroll all the way down.

In the article settings (wrench icon) of the article, select the matching Theme Helper Tag under Template settings.

You can then add the article with the following insert tag in an HTML element or template, e.g. {{theme::content::ODD01/01}}.

How to define your own Theme Helper Tags is explained in the Theme Helper documentation.

Customizing the header

You find the header content in the articles under ODD Elements > 01 / Kopfzeile.

Customizing the logo

You replace the logo in the article 01/01 Logo.

You find the contact details and social media links in the article 01/02 Top Navbar, where you can change them.

Choosing between a straight or slanted header

How to activate the straight header is explained on the page Layouts.

You find the footer content in the articles under ODD Elements > 02 / Fußzeile. These articles are included in the modules Footer / Main and Footer / Copyright.

Customizing colors and fonts

After installing the theme, you find the SCSS files in the file manager under the path odd/scss.

Depending on the installed theme version, there are two ways to make your own customizations:

Older theme versions: You use the files

custom.scss (for SCSS and CSS)
_custom_colors.scss (to change the base colors and choose a color scheme)
_custom_variables.scss (for more detailed adjustments such as fonts or colors of individual elements)

To change a variable, remove the comment characters (slashes) in front of the line in the respective file.

In both cases you can still add your own SCSS or CSS in custom.scss.

Tip

Note

Do not rename the theme folder odd in the file manager, otherwise the SCSS files will no longer be loaded. You do not have to include the files in the page layout yourself, the theme already loads them automatically.

Color schemes

By default the ODD theme comes with a light layout and a green primary color. You can also choose other color schemes:

Light color scheme / green primary color
Light color scheme / blue primary color
Light color scheme / red primary color
Light color scheme / yellow primary color
Light color scheme / purple primary color
Light color scheme / pastel colors
Dark color scheme

All of the color schemes above are adjusted for high contrast to ensure good readability and accessibility.

In addition there is a green, blue and grey color scheme that is not adjusted for high contrast. These come from an earlier theme version and are still included for backward compatibility.

@import 'color_schemes/odd_green_colors_contrast';
//@import 'color_schemes/odd_blue_colors_contrast';
//@import 'color_schemes/odd_grey_colors_contrast';
//@import 'color_schemes/odd_red_colors_contrast';
//@import 'color_schemes/odd_yellow_colors_contrast';
//@import 'color_schemes/odd_purple_colors_contrast';
//@import 'color_schemes/odd_pastel_colors_contrast';

//@import 'color_schemes/odd_grey_colors';
//@import 'color_schemes/odd_blue_colors';

Variables

Important note If you use the latest version of the ODD theme, you may wonder where _custom_colors.scss has gone. Don’t worry: as of ODD version 3.7.0, a new installation of the ODD theme only has _custom_variables.scss, which now contains all color and variable definitions.

What this means for you:

v2 (new installation from version 3.7.0): A new installation of the theme only has _custom_variables.scss with all color and variable settings. Use CSS variables for your customizations.
v1 (version older than 3.7.0 / update from a version older than 3.7.0): If you updated the ODD theme or installed a version older than 3.7.0, both _custom_variables.scss and _custom_colors.scss remain. Use SCSS variables for your customizations.

Tip

ℹ️ How do I update my existing installation to the new version with CSS variables? As of version 3.7.0 the ODD theme was thoroughly adapted for accessibility. If you want to use all current and future features, you should switch to the new version. You find a detailed guide here: Update to CSS variables.

📁 Where to find the variables You find the file for adjusting the variables in the file manager under odd/scss/_custom_variables.scss.

✅ Example: activating a variable

// Vorher (nicht aktiv):
//--oddColor1: #A3CC00;

// Nachher (aktiv):
--oddColor1: #A3CC00;

🔧 The most important CSS variables Here is an overview of the most important CSS variables that you can adjust in odd/scss/_custom_variables.scss.

Variable	Meaning
`--oddColor1`	Primary color, light shade
`--oddColor2`	Primary color
`--oddColor3`	Primary color, dark shade
`--oddColor4`	Secondary color
`--oddColor5`	Secondary color, light shade
`--oddColor6`	Boxes and text
`--oddColor7`	Page background

Base colors in _custom_colors.scss

$oddColor1: Primary color, light shade $oddColor2: Primary color $oddColor3: Primary color, dark shade $oddColor4: Secondary color $oddColor5: Secondary color, light shade $oddColor6: Boxes and text $oddColor7: Page background

Adding a font

If you want to use your own font, you can include it at the very top of _custom_variables.scss.

🔗 Recommendation: fonts via Google Webfonts Helper

A great way to include a font quickly and easily is the site:

👉 Google Webfonts Helper

There you can:

choose a font from the Google Fonts library,
select the font styles you need,
download a ZIP file with the font files,
and generate the matching @font-face CSS code right away.
Important: Under “Customize Folder prefix”, enter the path to your fonts folder, e.g. /files/odd/fonts/.

📄 Example: adding the CSS to _custom_variables.scss Copy the generated CSS code from the website (e.g. for the font “Ubuntu”) and paste it at the very top of _custom_variables.scss:

/* ubuntu-regular - latin */
@font-face {
  font-display: swap;
  font-family: 'Ubuntu';
  font-style: normal;
  font-weight: 400;
  src: url('/files/odd/fonts/ubuntu-v20-latin-regular.woff2') format('woff2');
}

Then assign the font in the CSS variables in _custom_variables.scss as follows:

:root {
  --mainFont: 'Ubuntu', sans-serif;
  --headingFont: 'Ubuntu', sans-serif;
}

$mainFont: 'Ubuntu', sans-serif;
$headingFont: 'Ubuntu', sans-serif;

Layouts

Layout with straight header

By default the ODD theme comes with a slanted header. To activate the straight header, select a layout with a straight header in the page settings.

Among the modules there is a navigation module for the slanted and the straight header (Navigationsleiste mit Schräge and Navigationsleiste ohne Schräge), which is included in the respective layouts.

You find an example on the page Layout with straight header.

One- and multi-column layouts

Under Themes > Page layouts various layouts for one-, two- and three-column layouts with a slanted or straight header are already created, which you can assign in the page settings under Layout settings.

FAQ

Images

Why is an image not displayed?

The folder in the file manager may not be set to public. You can check this by editing the folder. Public must be ticked, otherwise the image is not displayed in the front end.

Why doesn’t the large view of an image open in a lightbox when I click it?

The theme has to load jQuery and the jQuery template j_colorbox. You can edit the layout in the back end under Themes via the third-to-last icon Edit the page layouts of theme ID 1.

Why are animated GIFs not displayed?

For animated GIFs, do not set an image size in the image settings, otherwise the animation is lost.

How do I add my own image to the social media icons in the header?

In the article 01/02 Top Navbar (at the very bottom under ODD Elements - 01/Kopfzeile), create a new element of type Image inside the content container (see screenshot 1).

In the element settings, set an image size, e.g. Fit the frame / 40px. Activate Overwrite metadata and set a link under Image link address. In the expert settings, also set the class icon (see screenshot 2).

Finally, add the following CSS code to custom.scss.

In the end it should look like the third screenshot.

Screenshot 1:

Screenshot 2:

Screenshot 3:

How do I define a second logo for the narrow navigation bar?

In the article 01/01 Logo (under ODD Elemente - 01 / Kopfzeile), add a second image element and give it e.g. the class stuck-logo (the second input field under Expert settings).

Now add the following CSS to custom.scss:

Contao 5.0 and later

.stuck-logo {
  display: none;
} 
.stuck .stuck-logo {
display: block;
}
.stuck .navbar-brand .content-image:not(.stuck-logo) {
display: none;
}

Up to Contao 4.13

.stuck-logo {
  display: none;
} 
.stuck .stuck-logo {
display: block;
}
.stuck .navbar-brand .ce_image:not(.stuck-logo) {
display: none;
}

A different logo should now be displayed when you scroll down from the top and the narrow navigation bar appears.

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

contao:
    image:
        imagine_service: 'contao.image.imagine.gd'

contao:
    image:
        imagine_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Labels & translations

How do I change the read-more link of events or translate it into other languages?

You can either edit the template event_list_odd.html5 or event_teaser_odd.html5 directly or override it in langconfig.php (only from ODD theme version 1.4.2).

Edit the file langconfig.php under system/config, or create it if it does not exist yet. You can override the text with the following line:

<?php
$GLOBALS['TL_LANG']['odd']['event_more_link'] = "Details";

Or as follows to override it e.g. in a specific language:

<?php
if ($GLOBALS['TL_LANGUAGE'] == 'en') {
    $GLOBALS['TL_LANG']['odd']['event_more_link'] = "Details";
}

Display

How do I remove the slanted edges?

Removing the slanted edges in the header

There are already several layouts to switch between a straight and a slanted header. Among the modules there is also a navigation module with and without a slant, which you can select in the layout under the included modules.

Removing the slanted edges of content elements

The page Elements with slanted edges shows how to adjust the slanted edges of content elements. You only have to remove the classes skw-**.

Edit the module Footer / Main and remove the class skw-tr.

For the newsletter area above the footer, edit the module Newsletter / Abonnieren / Startseite and remove the class skw-tl under Expert settings.

How do I prevent all headings from being displayed in uppercase?

Add the following CSS to custom.scss and then reload the page with Ctrl + F5:

h1, h2, h3, h4, h5, h6 {
	text-transform: inherit;
}

How do I remove the newsletter area above the footer?

You can deactivate the newsletter area in the corresponding page layout under Included modules with the eye icon or remove it with the cross.

Other

How do I show a Google Maps map?

Install the extension Google Maps. In the back end you then find a menu item Google Maps where you can create your map.

With a content element (Media elements -> Google Map) you include the map at the desired place in an article.

You can enter the API key in the settings under Google Maps.

This is what it could look like:

How do I prevent the theme CSS file from being cached?

Visitors who have already visited the website are usually served a cached file. If you want to prevent this, you can adjust the fe_page template.

Adjust the following template: fe_bootstrap_odd.html5.

It should look like this:

<link rel="stylesheet" type="text/css" media="all" href="<?php
// add stylesheets
$combiner = new Combiner();
$combiner->add('bundles/pdirthemeodd/bootstrap/dist/css/bootstrap.min.css');
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
$combiner->add('bundles/pdirthemeodd/scss/odd_win.scss');
} else {
$combiner->add('bundles/pdirthemeodd/scss/odd.scss');
}
echo $combiner->getCombinedFile(); ?>?date=<?= time() ?>">

Multidomain

If several domains in one Contao installation should use the ODD theme, this is possible with a few workarounds.

The goal of this guide is for each domain to have its own custom.scss, _custom_colors.scss and _custom_variables.scss.

Note

As of Contao 4.12 the publicly accessible subfolder was renamed from /web to /public. If your installation has a /web directory, use web instead of public in the following code examples.

1) Create the SCSS files

Create a folder in the file manager under odd/scss (e.g. domain2). Copy the files custom.scss, _custom_colors.scss and _custom_variables.scss into this folder.

In _custom_colors.scss, adjust the path of the color schemes as follows.

//@import '../../../../public/bundles/pdirthemeodd/scss/color_schemes/odd_grey_colors';
//@import '../../../../public/bundles/pdirthemeodd/scss/color_schemes/odd_blue_colors';

In the same folder, also create a file odd.scss with the following content.

@charset "UTF-8";

@font-face {
  font-family: 'Cabin';
  font-display: swap;
  src: local('Cabin'),
  url('/bundles/pdirthemeodd/fonts/Cabin/cabin-regular-webfont.woff2') format('woff2'),
  url('/bundles/pdirthemeodd/fonts/Cabin/cabin-regular-webfont.woff') format('woff'),
  url('/bundles/pdirthemeodd/fonts/Cabin/cabin-regular-webfont.ttf') format('ttf'),
  url('/bundles/pdirthemeodd/fonts/Cabin/cabin-regular-webfont.eot') format('eot');
}

@font-face {
  font-family: 'Muli';
  font-display: swap;
  src: local('Muli'),
  url('/bundles/pdirthemeodd/fonts/Muli/muli-regular-webfont.woff2') format('woff2'),
  url('/bundles/pdirthemeodd/fonts/Muli/muli-regular-webfont.woff') format('woff'),
  url('/bundles/pdirthemeodd/fonts/Muli/muli-regular-webfont.ttf') format('ttf'),
  url('/bundles/pdirthemeodd/fonts/Muli/muli-regular-webfont.eot') format('eot');
}

@import "../../../../public/bundles/pdirthemeodd/scss/_odd_colors";
@import "_custom_colors";
@import "../../../../public/bundles/pdirthemeodd/scss/_odd_variables";
@import "_custom_variables";

@import '../../../../public/bundles/pdirthemeodd/scss/style';

@import 'custom';

2) Create a template

Under Templates, create a new template fe_page_odd.html5 and rename it (e.g. fe_page_odd_domain2.html5).

In line 41, add the newly created folder from the file manager to getCombinedStylesheet().

<link rel="stylesheet" type="text/css" media="all" href="<?= ContaoThemesNet\ThemeOddBundle\ThemeUtils::getCombinedStylesheet('domain2'); ?>">

3) Create a layout

Go to Themes and Edit the page layouts of the theme and duplicate any layout. Edit the layout and select the fe_page template you just created under Expert settings (at the very bottom) in Page template.

4) Assign the layout to the page

Finally, assign the layout to a page (Layout settings -> Assign a layout).

5) ODD Elements

In the article settings of the header and footer content (under ODD Elements) you can select the corresponding page under Template settings so that the content of this article is actually used.

Update to CSS variables

With version 3.7.0 the ODD theme was made accessible and all SCSS variables were switched to CSS variables. This means a manual intermediate step is necessary when updating from an older version (< 3.7.0) to a newer version (≥ 3.7.0).

Requirements

Existing installation of the ODD theme < 3.7.0
Update to Contao 5

1. Update the theme

Open the Contao Manager.
Update the ODD theme to 3.7.0 or higher (recommended: latest version).

2. Changes to the SCSS files

As of version 3.7.0 the file _custom_colors.scss no longer exists. All color definitions are now in _custom_variables.scss.

📂 Old structure (< 3.7.0)

odd/scss/
├── custom.scss
├── _custom_variables.scss
└── _custom_colors.scss

📂 New structure (≥ 3.7.0)

odd/scss/
├── custom.scss
└── _custom_variables.scss

3. Create the new theme files

After the update to 3.7.0 or higher the site still works, but not all new features are available right away. You should therefore create the current theme files.

Complete re-import of the theme folder

In the file manager, rename the folder odd, e.g. to odd-alt.
In the Contao Manager, open System maintenance → Check database and run the database update.
The migration that creates the new theme files is now offered – run it.
A new folder odd with the current files is created.

Moving images: If there were images in the old odd folder, move them either into the new folder or into a separate image folder. References are kept if the images were added in Contao via “Add an image”.

4. Transfer your own customizations

If you made changes in custom.scss, _custom_colors.scss or _custom_variables.scss, you have to transfer them manually to the new files.

Important: V2 uses CSS variables instead of SCSS variables.

Example color variable

Before (V1 – SCSS):

$oddColor1: #b6cf92;

New (V2 – CSS variables):

:root {
  --oddColor1: #b6cf92;
}

CSS variables are used in code like this:

color: var(--oddColor1);

5. Update SCSS customizations

If your custom.scss still uses SCSS variables ($variable), change them to the CSS variable format (var(--variable)).

Example:

/* Vorher */
color: $oddColor1;

/* Neu */
color: var(--oddColor1);

Accessibility

You find detailed tips, new features from version 3.7.0 and best practices for accessible design here: ♿ Accessibility in the ODD theme

Direct download of the new variables file

You find the current _custom_variables.scss here: 📄 GitHub: _custom_variables.scss

If you want to adjust the files manually, the odd folder must also contain an empty file named .v2 to activate the V2 structure.

Accessibility

Accessibility in the ODD theme (version 3.7.0 and later)

With version 3.7.0 the ODD theme was thoroughly revised with regard to accessibility and switched to CSS variables. To use these features, a manual intermediate step is necessary when updating from an older version (< 3.7.0) to a newer version (≥ 3.7.0). ➡️ Guide: Update to CSS variables

1. New accessible templates (version 3.7.0 and later)

To avoid redundant links (e.g. image, headline and button all linked), it is enough to link only the button. This improves keyboard navigation.

Adapted templates are available for various content elements such as teaser box, content box etc. These templates have the suffix _bf (German “barrierefrei”, accessible).

2. General accessibility tips

When creating content, pay attention to the following:

Provide alternative texts (alt tags) for images
Use meaningful link texts (not just “click here”)
Mind the contrast (text color/background color)
Use headings in a correct hierarchy
Use tables only for tabular data (not for layout)
Give forms label elements

3. Tools for testing accessibility

pdir Website Check – automatic check for accessibility and SEO.
WAVE Web Accessibility Evaluation Tool – browser extension for analyzing accessibility problems.
axe DevTools – developer tools for accessibility testing.
Contrast Checker – checks color contrast.

Elements

Topics

Content Box

To add a content box, place an element of type Content Box.

To display several elements side by side, place them as described in the section Grid. You find an example in the ODD demo on the page Weitere ODD-Elemente.

Content Slider

The content slider must always be placed in its own article, which needs the classes slider and fullwidth under Expert settings. If the slider should also get a slant to the bottom right or left, give the article the class skw-br or skw-bl as well, see the table below.

In the article, place the elements Content-Slider (Umschlag Anfang) (wrapper start) and Content-Slider (Umschlag Ende) (wrapper stop). Between the wrapper elements, place one element of type Slider-Element per slide.

Add the image via the checkbox Add an image. If the slider should have a slant, also select the image size Slider mit Schräge (1920x900); for a slider without a slant, select the image size Slider (1920x750).

Reference table for the article classes:

Slider	Classes in the article	Screenshot
without slant	`slider fullwidth`
with slant bottom left	`slider fullwidth skw-bl`
with slant bottom right	`slider fullwidth skw-br`

You find an example with a content slider on the page Content-Slider or on the home page of the ODD demo.

Positioning the text box

You can adjust the position of the text box by adding a class.

top-left: top left
top-center: top center
top-right: top right
center-left: center left
center-center: center
center-right: center right
bottom-left: bottom left
bottom-center: bottom center
bottom-right: bottom right

Elements with slanted edges

The page Elemente mit Schrägen already contains various examples of elements with slanted edges.

Each section must be in its own article, which needs various classes:

primary-bg: background color
skw-tl: slant to the top left
skw-tr: slant to the top right
skw-bl: slant to the bottom left
skw-br: slant to the bottom right

For example, to give the article slants to the top right and bottom right (like the first example on the demo page), add the classes primary-bg skw-tr skw-br in the article settings under Expert settings.

Reference table for the article classes:

Slant	Classes in the article	Screenshot
top right - bottom right	`primary-bg skw-tr skw-br`
top left - bottom left	`primary-bg skw-tl skw-bl`
top left - bottom right	`primary-bg skw-tl skw-br`
top right - bottom left	`primary-bg skw-tr skw-bl`
top right	`primary-bg skw-tr`
bottom right	`primary-bg skw-br`
top left	`primary-bg skw-tl`
bottom left	`primary-bg skw-bl`

Grid

The theme uses Bootstrap 4, which lets you, among other things, display elements side by side and at the same time in a single column on mobile devices.

For example, to display two text elements side by side, first add one element each of type Contao Themes (Inhaltscontainer Anfang) (content container start) and Contao Themes (Inhaltscontainer Ende) (content container end). The content container start element needs the class row.

Between the wrapper elements, place two text elements and select .col-12 and .col-md-6 under Advanced CSS classes > Column widths for each. This means the elements are displayed in one column below a width of 768px and in two columns above it. How exactly to use the classes is explained in the Bootstrap 4 documentation.

You find an example in the ODD demo on the page Textelemente.

Header image

To place a header image, use the element type Image and select the template ce_image_headerimage_odd (up to Contao 4.13) or content_element/image/header_image_odd (Contao 5 and later) under Template settings.

Header image without slant

For a header image without a slant, select the image size Headerbild (1920x400). You have to place the header image in its own article and select the template mod_article_fullwidth in the article settings.

You find an example on the page Headerbild ohne Schräge.

Header image with slant to the left

For a header image with a slant to the left, select the image size Headerbild (1920x400). You have to place the header image in its own article, select the template mod_article_fullwidth in the article settings and add the class skw-bl under Expert settings.

You find an example on the page Headerbild mit Schräge nach links.

Header image with slant to the right

For a header image with a slant to the right, select the image size Headerbild (1920x400). You have to place the header image in its own article, select the template mod_article_fullwidth in the article settings and add the class skw-br under Expert settings.

You find an example on the page Headerbild mit Schräge nach rechts.

Headings

You find examples of the headings on the page Textelemente.

Underlined, left-aligned

To display the heading left-aligned and underlined, give the text element the class bordered-heading.

Underlined, centered

To display the heading centered and underlined, give the text element the classes bordered-heading and text-sm-center.

You can set the class text-sm-center under Advanced CSS classes > Alignment.

Underlined, right-aligned

To display the heading right-aligned and underlined, give the text element the classes bordered-heading and text-sm-right.

You can set the class text-sm-right under Advanced CSS classes > Alignment.

Hyperlinks

If you give a link the class btn, it is displayed as a button.

Pricing table

To display a pricing table, place an element of type Preis-Tabelle (pricing table).

To highlight a box, fill in the field Bezeichnung für Hervorgehobene Box (label for highlighted box). To display several elements side by side, place them as described in the section Grid. You find two examples in the ODD demo on the page Weitere ODD-Elemente.

Three columns

Two columns

Simple box

If you select the template ce_text_cthemes_simplebox under Template settings of a text element, it gets a white background as in the following screenshot.

To display several elements side by side, place them as described in the section Grid. You find an example in the ODD demo on the page Weitere ODD-Elemente.

Teaser Box

To add a teaser box, place an element of type Teaser Box.

Add the image via the checkbox Add an image. Select the image size Teaserboxen (350x200).

To display several elements side by side, place them as described in the section Grid. You find an example in the ODD demo on the page Weitere ODD-Elemente.

Text with icons

Place an element of type Text und Icon (text and icon).

You can define a headline, a text, the Font Awesome icon and optionally a link. You find a list of available icons on the Font Awesome website. When you click an icon, you also see the classes at the top that you have to enter in the field Font Awesome 5 Icon (Klassen).

You find an example in the ODD demo on the page Weitere ODD-Elemente.

Modules

This page explains all modules and how you can use them.

The following modules are explained on this page:

Events

Event list

Follow these steps to place an event list:

Select the module Event list (under Events)
Configure the settings (calendars, number of events etc.)
Select the event template (Template settings)
event_teaser_zeroone (event list with images)
event_list_zeroone (event list without images)
event_upcoming (simple event list with date and title only)
Select the custom template mod_eventlist_zeroone (Template settings)
Select the image size News & Events / Listenansicht (Image settings)
Add the CSS class columns (second input field) (Expert settings)
Include it in an article via the element type Module

Event reader

Follow these steps to place the event reader (detail view):

Select the module Event reader (under Events)
Select the calendars
Select the event template event_full_zeroone (Template settings)
Select the image size News & Events / Detailansicht (Image settings)
Include it in an article via the element type Module

Calendar

Follow these steps to place a calendar:

Select the module Calendar (under Events)
Configure the settings (calendars, first day of the week, redirect page etc.)
Select the calendar template (Template settings)
cal_default (regular calendar)
cal_mini (mini calendar)
Select the custom template mod_calendar_zeroone (Template settings)
Include it in an article via the element type Module

The ODD theme uses Headroom.js to hide or show the navigation when you scroll down or up. To deactivate this, edit the template fe_bootstrap_odd and delete or comment out the following line near the end of the file.

$combiner->add('bundles/pdirthemeodd/js/headroom.min.js');

<script charset="utf-8" src="<?php
    // add javascripts
    $combiner = new Combiner();
    $combiner->add('bundles/pdirthemeodd/bootstrap/dist/js/bootstrap.min.js');
    $combiner->add('bundles/pdirthemeodd/fontawesome/js/all.min.js');
    //$combiner->add('bundles/pdirthemeodd/js/headroom.min.js');
    $combiner->add('bundles/pdirthemeodd/js/scripts.min.js');
    echo $combiner->getCombinedFile();
?>"></script>

In the same way you could also deactivate Font Awesome by removing the following line.

$combiner->add('bundles/pdirthemeodd/fontawesome/js/all.min.js');

News

News list

Follow these steps to place a news list:

Select the module Newslist (under News)
Configure the settings (archives, number of items etc.)
Select the news template (Template settings)
news_latest_zeroone (news list with images)
news_short_zeroone (news list without images)
news_simple (simple news list with date/author and title only)
Select the custom template mod_newslist_zeroone (Template settings)
Select the image size News & Events / Listenansicht (Image settings)
Add the CSS class columns (second input field) (Expert settings)
Include it in an article via the element type Module

News reader

Follow these steps to place the news reader (detail view):

Select the module Newsreader (under News)
Configure the settings (archives, fields)
Select the news template news_full_zeroone (Template settings)
Select the image size News & Events / Detailansicht (Image settings)
Include it in an article via the element type Module

Follow these steps to place a newsletter form:

Select the module Subscribe or Unsubscribe (under Newsletter)
Configure the settings (channels, redirect etc.)
Select the newsletter template nl_default_zeroone (Template settings)
Include it in an article via the element type Module

Search engine

Follow these steps to place a search engine:

Select the module Search engine (under Applications)
Configure the settings
Select the custom template mod_search_zeroone (Template settings)
Include it in an article via the element type Module

Maklermodul

The ODD theme already ships templates and stylesheets for the Maklermodul (real estate module).

Documentation

The Maklermodul documentation contains all information on installing and setting up the Maklermodul.

Including the stylesheets

Add the following line to custom.scss (/files/odd/scss) so that the list and detail view are displayed as in the screenshots.

@import 'maklermodul';

Setup

Creating pages

First create one page each for the list view and the detail view.

List view module

Create a module of type Immobilienliste (property list) as described in the documentation.

Select the property template makler_list_odd
Select the image size Maklermodul / Listenansicht

Detail view module

Create a module of type Expose as described in the documentation.

Select the property template makler_details_extended_odd

Header image module

Create a module of type MaklerModul Kopfbild (header image) as described in the documentation.

Placing the modules

Place the modules for the list view and the exposé in the articles of the respective pages. For the header image, create another article placed in the header (above the article of the detail view).

For the articles of the header image and the detail view, select the template mod_article_fullwidth in the article settings (wrench icon) under Template settings.

Customizations

Always show the filters in the list view

If the filters in the list view should always be visible instead of only after clicking the button “Filter ausklappen”, you can achieve this with a small template change. Create the template makler_list_odd and remove the following two lines at around line 41:

<a href="<?= $this->staticListPage ?>" class="btn toggle-filter show-filter active">Filter ausklappen</a>
<a href="<?= $this->staticListPage ?>" class="btn toggle-filter hide-filter">Filter einklappen</a>

Examples

If you carried out all steps as described, the list should be displayed as in the following screenshots.

List view with button filter

List view with select filter

Exposé

Multilingual sites

To build a multilingual website with the ODD theme, you can install the extension Contao Multilingual Pages [i18nl10n]. Then you do not have to duplicate the site structure, only the elements that are displayed in different languages. You find documentation for Contao 3 here; there is none for Contao 4 yet.

Alternatively, you can create a site structure for each language without this extension. You find more about this in the Contao manual.

Contao Multilingual Pages [i18nl10n]

If you do not want to duplicate the site structure, install the extension exploreimpact/contao-i18nl10n with the Contao Manager.

In the website root of the site structure you can select the alternative languages under i18nl10n settings.

Under the menu item Multilingual pages, add the pages in the other languages. To create all pages, click L10N for all.

The elements now have the option to select the language under L10n settings. Select Neutral if the element should be displayed in all languages.

Duplicating the site structure

If you prefer to work with several site structures, select the corresponding website root under ODD Elements in the article settings under Template settings.

With the Social Feed Bundle you can display posts from Facebook and Instagram in the ODD theme. Simply install the package pdir/social-feed-bundle via the Contao Manager.

How to set up the Facebook stream and how to place the modules is explained on the following page: Social Feed documentation.

When setting up the news module, select news_social_feed_odd as the news template.

One column

Two columns

Three columns

Four columns

Update

You can update the theme easily via the Contao Manager. Then open the install tool and update the database.

Tip

A database backup beforehand never hurts!

Update from version 1.x to 2.x

When updating the theme from version 1 to 2, a few changes are necessary, because Contao Bootstrap and Bootstrap Grid are no longer dependencies of the theme in version 2.

Changing the page template

In the page layouts, the page template fe_page_odd (one column), fe_page_odd_left (two columns with left column), fe_page_odd_right (two columns with right column) or fe_page_odd_three_columns (three columns) must be selected (previously fe_bootstrap_odd).

For the navigation modules (e.g. Navigationsleiste mit Schräge and Navigationsleiste ohne Schräge), the module type must be changed to Navigation menu.

As module template, mod_navigation_odd_sloping (navigation with slant), mod_navigation_odd (without slant) or mod_navigation_odd_sloping_topright (slant in the opposite direction) must be selected.

As navigation template, nav_default_odd must be selected.

Adjusting the user modules

If the module types Registration or Personal data are used, member_grouped must be selected as the template (previously member_grouped_bs_odd).

Bootstrap gallery

If a Bootstrap gallery was used, the element type must be changed to a regular gallery.

Issues

If you ran into problems during installation or setup, or you found a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check beforehand whether your issue is already known.

ODD Isotope for Contao

Quick start

The theme documentation covers these topics:

Requirements

Note

The theme can only be installed into an empty Contao installation and is compatible with Contao 4.9 or higher.

Contao 4

Contao 4 requires a web server such as Apache or NGINX with PHP and MySQL support. Our theme requires Contao 4.9 or higher and PHP 7.1.

Contao Manager

The theme can easily be installed via the Contao Manager. You find an installation guide here.

Installation

Note

The ODD Isotope Bundle can only be installed into an empty Contao installation and is compatible with Contao 4.9 or higher.

Tip

Steps

1 / Adjust composer.json

Install the ODD Isotope Bundle by editing the file composer.json in the Contao root directory. Add the following lines at the end of the file (as in the example composer.json below). Replace the domain and the password.

,
"repositories": [
  {
    "type": "composer",
    "url": "https://[DOMAIN]:[PASSWORT]@packages.contao.store"
  }
]

Add the following line at the end of require. Don’t forget the comma in the second-to-last line.

"contao-themes-net/odd-isotope-bundle": "^1.0"

Example of what composer.json should look like for Contao 4.13:

{
    "type": "project",
    "require": {
        "contao/calendar-bundle": "^4.13",
        "contao/comments-bundle": "^4.13",
        "contao/conflicts": "*@dev",
        "contao/faq-bundle": "^4.13",
        "contao/listing-bundle": "^4.13",
        "contao/manager-bundle": "4.13.*",
        "contao/news-bundle": "^4.13",
        "contao/newsletter-bundle": "^4.13",
        "contao-themes-net/odd-isotope-bundle": "^2.0"
    },
    "extra": {
        "contao-component-dir": "assets"
    },
    "scripts": {
        "post-install-cmd": [
            "@php vendor/bin/contao-setup"
        ],
        "post-update-cmd": [
            "@php vendor/bin/contao-setup"
        ]
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://BENUTZERNAME:PASSWORT@packages.contao.store"
        }
    ]
}

2 / Run Composer update

Now open the Contao Manager, click Update for all existing packages (i.e. only Contao) and run the update by clicking the button Apply changes at the bottom.

3 / Update the database

Then open the install tool and update the database. In the install tool you also have to create an admin user account.

You reach the install tool in the Contao Manager via the menu item Tools or via the URL: www.your-domain.com/contao/install.

4 / Synchronize the theme files

Log in to the back end with the user account you created and select the menu item ODD Theme Setup under CONTAO-THEMES-NET in the left navigation. Then click the button Synchronize theme files. This creates all files in the file manager under the folder ODD and copies the SQL files for the database import into the templates folder.

5 / Synchronize the Isotope files

Select the menu item ODD Isotope Setup under CONTAO-THEMES-NET in the left navigation and click the button Synchronize files to create all product images and move the SQL files into the templates folder so that they can be imported.

6 / Empty the table tl_files

Then empty the database table ’tl_files’ by clicking the button Empty table ’tl_files’ in the ODD Theme Setup.

Note

Emptying the tl_files table deletes the image references. This is only necessary for the first installation of the theme.

7 / Import the attributes

In the install tool, import the template named odd_isotope_attributes.sql. Make sure to tick Do not truncate tables.

Then clear the cache.

When you open the install tool now, some new fields should be created. Update the database.

8 / Import the theme and Isotope demo data

In the install tool, import the template named odd_isotope_demo_contao_4.x.x.sql (depending on your Contao version). Make sure to tick Do not truncate tables.

For the import to work, Contao must be installed with the bundles for news, calendar, FAQ, newsletter, listing and comments.

If you don’t want to use these Contao bundles, you can uninstall them afterwards.

9 / Recreate the symlinks

Then switch back to the Contao back end, select the menu item System maintenance and recreate the symlinks by ticking Recreate the symlinks and then clicking the button Purge data.

10 / Settings

Under Advanced CSS settings, select the class set bootstrap4.json.

11 / Import the CSS

Add the following line to custom.scss (file manager, under odd/scss) so that the styling is loaded:

@import '../../../public/bundles/contaothemesnetoddisotope/scss/isotope';

Note

As of Contao 4.12 the publicly accessible subfolder was renamed from /web to /public. If your installation has a /web directory, use web instead of public in the import statement.

Notes

Error: This page isn’t working / The page redirected you too many times

Edit the website root and set the protocol under URL settings to http:// or https://, depending on how your site should be accessed.

Error: imagick not installed

If the error imagick not installed occurs with PHP 8.0, you can solve it with an adjustment in config.yml and clearing the cache afterwards. More information in the PDIR blog post (German)

Customization

You find the Isotope manual here: User manual (German)

Order confirmation

Why are no order confirmation emails sent?

Product list

How can I change the number of products per row?

How can I display the product lists with or without slanted edges?

To display the product list without slanted edges, select the module template mod_iso_productlist_odd in the module.

For a product list with slanted edges, select the template with the suffix _slanting.

How can I display the product lists as a slider?

To display the product list as a slider, select the module template mod_iso_productlist_odd_slider in the module.

For a product list with slanted edges, select the template with the suffix _slanting.

Content elements

How can I add or remove the white border of the teasers?

To display the teaser with a white border, add the class with-border to the element in the expert settings.

Images

Why are some images not displayed? (WEBP support)

If newer browsers try to load a WEBP image and it is not supported, an error may occur.

The error message may look something like this:

request.CRITICAL: Uncaught PHP Exception RuntimeException: "Image format "webp" is not supported in Imagine\Imagick\Imagine on this environment. Consider removing this format from contao.image.valid_extensions or switch the contao.image.imagine_service to an implementation that supports it.

Possible solutions:

#1 Update Imagine or have your host do it (use the latest version)

#2 Use an alternative image processing service

contao:
    image:
        image_service: 'contao.image.imagine.gd'

contao:
    image:
        image_service: 'contao.image.imagine.gmagick'

#3 Remove WEBP from the allowed file extensions

Add the following to config.yml and then clear the cache.

contao:
    image:
        valid_extensions:  
            - jpg
            - jpeg
            - gif
            - png
            - tif
            - tiff
            - bmp
            - svg
            - svgz

#4 Adjust the .htaccess

<IfModule mod_mime.c>
   AddType image/webp .webp
</IfModule>

Other

How do I get nicer invoices?

Install the extension isotope/isotope_documents.

The extension ships various templates that you can select in the back end for the respective document.

Update

You can update the theme easily via the Contao Manager. Then open the install tool and update the database.

If a problem occurs after the update, also have a look at our possible solutions.

Tip

A database backup beforehand never hurts!

Issues

If you ran into problems during installation or setup, or you found a display error of the theme in a particular browser, please create a new ticket at:

Ticket overview Create a new ticket

Note

Please check beforehand whether your issue is already known.

Moving a Contao theme to another server

This guide describes what to do if you want to move your theme to another server.

1. Backups

1.1 Back up the database

First back up the database. You can simply export the database with phpMyAdmin (available in your hosting account).

1.2 Back up the files

Back up the following folders:

/files
/templates

Back up the following files:

composer.json
composer.lock
system/config/localconfig.php
config.yml (in /config or /app/config)
parameters.yml (in /config or /app/config)
web/.htaccess (if customized)

If you have made other customizations, you may also need to back up the folder /contao or /src. If you still use old Contao 3 extensions, you may also need to back up folders in /system/modules. (You can ignore symlinks here.)

2. Install Contao and restore the backups

2.1 Restore the database backup

Create a new database and import the SQL file of the backed-up database.

2.2 Adjust parameters.yml

Edit the backed-up parameters.yml with an editor and replace the access data of the old database with that of the new database. All other parameters stay as they are.

parameters:
    database_host: localhost
    database_port: 3306
    database_user: DATENBANK_USER
    database_password: DATENBANK_PASSWORT
    database_name: DATENBANK_NAME

2.3 Install Contao

Now install Contao as usual with the file contao-manager.phar.php in the web folder.

Note

Important: do not update the database yet after the installation!

2.4 Restore all other backups

Now copy all backed-up files back to the right places. It is important that all files are copied back to the correct location, i.e. not into the web folder, but one level above it.

From Contao version 4.8, parameters.yml and config.yml go into the folder /config; for versions lower than 4.8, the files must be in the folder app/config.

2.5 Install the extensions

Once you have copied composer.json and composer.lock back to the right place and opened the Contao Manager, new packages should be shown under the menu item Packages. Click the button Apply changes in the footer to install all extensions.

2.6 Update the database

Once all extensions have been installed, open the install tool and update the database.

2.7 Open and check the website

Now open the website and check that everything works.

If problems remain, you can recreate the symlinks under system maintenance in the back end and clear the script and image cache. This is not strictly necessary, though.

Installation into an existing Contao installation

There are two ways for an existing Contao installation:

Theme installation

First install the corresponding theme with the Contao Manager, update the database and then synchronize the theme files on the Theme Setup page in the back end. Do not click the button “Empty table ’tl_files’” under any circumstances, otherwise all image references will be lost. You can skip the steps import database and recreate symlinks. You can still carry out the steps under Settings, though. You find more information on the steps on the Installation page of the respective theme in the navigation.

Import the theme CTO

To import the theme, go to the menu item Themes and click the Import button.

You find the cto file under product help. Download the file for your theme and your Contao version and import it.

A message should appear that the theme was uploaded successfully.

The new theme should now be visible under Themes.

You can now either continue with the next step and import the theme demo, or create the pages and content elements yourself.

Import the theme demo (optional)

With the Migration Bundle you can import the pages and articles of the theme demo. The Migration Bundle is easy to install with the Contao Manager.

First download the ZIP file for your theme and your Contao version from product help. Unzip it and move the subfolder to files/contentMigration/yourUser. For the MATE theme on Contao 4.9 this would be, for example, files/contentMigration/yourUser/mate_theme_contao_4.9. The theme folder should then contain all the model files.

Once the bundle is installed, you should see two new buttons Export and Import in the site structure. Select Import to import all pages and articles of the theme demo.

Select Full import as the import type and the correct folder name, and click Import.

A message should appear that pages, articles and content elements were imported successfully.

The pages of the theme should now be visible in the site structure.

Further adjustments

As the IDs of the content in the new installation differ from the demo, not everything can be assigned correctly. Further adjustments are therefore necessary.

Note

If you are not sure which modules or content go where, you could also set up the theme in a fresh Contao installation and compare it there.

Assign the page layout

In the page settings, select the correct page layout of the theme if it says Unknown option.

Assign missing modules

In the articles, select the correct module if the assignment is wrong.

Assign images

All images have to be selected again. Click into a content element and select an image if “Add an image” is ticked.

Create news, events, FAQ, newsletters and forms

News, events, FAQ, newsletters and forms have to be created manually; the current version of the Migration Bundle does not import them yet.

Assign archives

In the news, event, FAQ and newsletter modules, select the corresponding archive.

Assign forms

In the articles, assign the correct form to the form element (e.g. on the contact page).

Assign image sizes

Images may have been assigned the wrong image size. In that case, select the correct image size.

Redirect pages

For pages of type internal redirect, select the correct redirect page.

Grid start elements

This only applies to the MATE theme. In the articles, the grid stop element has to be reassigned to the grid start element. Click the pencil to edit it and select the correct parent element.

Contao

Themes

Extensions

Subsections of Contao

Extensions

Subsections of Extensions

Contao Advanced Classes

Subsections of Advanced Classes

Requirements

Contao 4

Contao Manager

Installation

Configuration

Select a class set

Custom set

Issues

AlleAktien Quantitativ for Contao

Subsections of AlleAktien Quantitativ

Requirements

Contao 4

Contao Manager

Configuration

Installation

1. Installation with the Contao Manager

2. Perform database update

Usage

1. What does the bundle offer?

Benefits:

2. How do I use it?

3. How are the insert tags structured?

4. What do the different charts look like?

QuoteChart

RevenueChart

RevenuePerShareChart

MarginsChart

DividendChart

DividendYieldChart

PayoutRatioChart

SharesOutstandingChart

ValuationChart

Issues

Amphtml for Contao

Subsections of Amphtml

Requirements

Contao 4

Contao Manager

Installation

Contao 4

Contao 3

Configuration

1 / Download the cto file

CSS customization

Issues

Animated Timeline for Contao

Subsections of Animated Timeline

Requirements

Contao 4

Contao Manager

Installation

1 / Open the Contao Manager

2 / Update the database

Configuration

1 / Placing the content elements

Wrapper elements

Timeline element

Demo

Issues

Business Reviews for Contao

Subsections of Business Reviews

Requirements

Contao 4

Contao Manager

Configuration

Installation

1 / Contao Manager aufrufen

2 / Hochladen der Zip-Datei

3 / Datenbank updaten

Issues

Contao Klaro

Subsections of Klaro