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

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

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

CONVERT Theme for Contao

Subsections of CONVERT Theme

Requirements

Contao 4

Contao Manager

License

Buy and register a license

Register the license

Remove the copyright notice

Installation

Installation in Contao 5

Notes

Subsections of Installation

Contao 4

Steps

1 / Install the CONVERT Theme Bundle

2 / Update the database

3 / Synchronize the theme files and empty tl_files

4 / Import the database

5 / Recreate the symlinks

6 / Settings

Notes:

Customization

Header and footer

Customizing the styling

Color schemes

Variables

Dark mode

Adding a font

Subsections of Customization

FAQ

Images

Image on top

Image on the left

Image on the right

Image below, overlapping

Possible solutions:

Other

Update

Issues

Known issues

# 1 An error occurred when opening the front end

# 2 Unknown insert tag {{ua::browser|attr}}