Contao 4

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.

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.

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

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.

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)

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

.stuck-logo {
  display: none;
} 
.stuck .stuck-logo {
display: block;
}
.stuck .navbar-brand .content-image:not(.stuck-logo) {
display: none;
}

.stuck-logo {
  display: none;
} 
.stuck .stuck-logo {
display: block;
}
.stuck .navbar-brand .ce_image:not(.stuck-logo) {
display: none;
}

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. 

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

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

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

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

Labels & translations

<?php
$GLOBALS['TL_LANG']['odd']['event_more_link'] = "Details";

<?php
if ($GLOBALS['TL_LANGUAGE'] == 'en') {
    $GLOBALS['TL_LANG']['odd']['event_more_link'] = "Details";
}

Display

h1, h2, h3, h4, h5, h6 {
	text-transform: inherit;
} 

Other

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

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

1. Open the Contao Manager.
2. 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

1. In the file manager, rename the folder odd, e.g. to odd-alt.
2. In the Contao Manager, open System maintenance → Check database and run the database update.
3. The migration that creates the new theme files is now offered – run it.
4. 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.

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.

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.

Social Feed Bundle

Social Feed Bundle

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