Manual for Contao 3.2
Table of Contents
1. Introduction 2. Installation i. Installing Contao ii. Using the Safe Mode Hack iii. Manual update iv. Live Update Service v. Moving an installation vi. Configuring the live server 3. Administration area i. Listing records ii. Editing records iii. Keyboard shortcuts 4. Managing pages i. Components ii. Themes iii. Style sheets iv. Modules v. Page layouts vi. Page types 5. Managing content i. Articles ii. News items iii. Events iv. RSS/Atom feed v. Newsletters vi. Forms vii. Comments viii. Templates ix. Insert tags 6. System administration i. Users and groups ii. Extensions iii. Maintenance 7. Data Container Arrays i. Reference ii. Palettes iii. Callbacks 8. Customizing Contao i. Bypass the internal cache ii. Custom configurations iii. Adding custom fields iv. Customizing TinyMCE v. Overriding class methods vi. Contao hooks 9. Extension Repository i. Adding an extension ii. Adding a release iii. Adding files iv. Adding files from a GitHub repository
1 Manual for Contao 3.2
v. Adding translations vi. Adding dependencies vii. Publishing an extension 10. Contao development i. Creating a new issue
2 Manual for Contao 3.2
Manual for Contao 3.2
This is the official manual for users and developers. You can always find the latest version on docs.contao.org.
Table of contents
Introduction Installation Installing Contao Using the Safe Mode Hack Manual update Live Update Service Moving an installation Configuring the live server Administration area Listing records Editing records Keyboard shortcuts Managing pages Components Themes Style sheets Modules Page layouts Page types Managing content Articles News items Events RSS/Atom feed Newsletters Forms Comments Templates Insert tags System administration Users and groups Extensions Maintenance Data Container Arrays Reference Palettes Callbacks Customizing Contao Bypass the internal cache Custom configurations Adding custom fields Customizing TinyMCE Overriding class methods Contao hooks
Introduction 3 Manual for Contao 3.2
Extension Repository Adding an extension Adding a release Adding files Adding files from a GitHub repository Adding translations Adding dependencies Publishing an extension Contao development Creating a new issue
Licence
The Contao documentation is licensed under a Creative Commons Attribution 3.0 License license (CC BY-NC-SA 3.0). If you want to redistribute a modified or unmodified version of the documentation, you can do so under the license terms.
If you contribute to the documentation, e.g. by creating pull requests, you grant us full usage rights of any content you create or upload. You also ensure that your content does not violate any third-party rights.
We are not claiming exclusive usage rights, therefore you are free to use your contributed content (e.g. texts or images) in any other project as well.
Introduction 4 Manual for Contao 3.2
Installation
The following chapters explain how to install and update Contao. You will learn how to use the Contao install tool, how to synchronize an existing installation via FTP, how to set up the Safe Mode Hack and how to configure a live server for Contao.
Installation 5 Manual for Contao 3.2
Installing Contao
First of all, download the latest Contao archive and extract it on your local computer. Move the files into the htdocs folder of your local installation (e.g. XAMPP) or upload them to your server with an FTP program (we recommend using WinSCP). Depending on your server configuration, the public folder is most likely called htdocs , httpdocs , html or public_html .
If you have SSH access, you can download and extract the archive with the following commands:
curl -L http://download.contao.org | tar -xzp
The Contao install tool
To open the Contao install tool, simply add /contao/install.php to the URL of your Contao installation. Note that the install tool is protected against brute force attacks and will be locked if a wrong password has been entered three times in a row. To remove the lock, open file system/config/localconfig.php in a text editor, find the following line and set it to 0 .
$GLOBALS['TL_CONFIG']['installCount'] = 0; // This will remove the automatic lock
Connecting to the database
Log into your server administration panel (e.g. "Plesk" or "cPanel") and create a new database for Contao. Then enter the login credentials in the Contao install tool. Note that the Contao default character set UTF-8 is written as UTF8 in MySQL!
Updating the database tables
Once you are connected to the database, Contao automatically checks its tables and displays a list of recommended changes in case they are not up to date. Make sure to read those recommendations carefully, because Contao only knows its own tables and will try to remove those of other applications eventually sharing the database. Confirm the changes and click the "Update database" button.
Importing a template
A template is a predetermined website with an exemplary page structure and different style-sheets to format the Contao core modules and content elements.
Since version 3.2.11, the sample web-page is no longer included in the download package. Depending on the version used, the new Contao Official Demo or the old Music Academy can be installed as an extension. Information on compatibility is available in the extension repository.
How to install the demo:
1. Create a new Contao installation with admin account 2. Log in as admin to the back end 3. Install the matching extension using the extension repository 4. Log out of the back end 5. Open the install tool again
To import a template, select the entry from the drop-down menu and click the "Import template" button.
When importing a template, existing data will be replaced!
Installing Contao 6 Manual for Contao 3.2
Creating an admin user
If you did not import a template, you have to create an admin user to log into the Contao back end. After you have created the account, the installation process is completed. The link in the lower right corner will take you to the administration area. If you have imported the example website, you can login as user "k.jones" with the password "kevinjones".
Installing the Contao Demo
See How to install the demo in the section Importing a template above.
Using search engine friendly URLs
If you are running an Apache server and are allowed to use mod_rewrite, you can make Contao generate search engine friendly URLs that look like static HTML documents. A set of default rewrite rules is stored in the .htaccess.default file in the Contao directory. Rename this file to .htaccess so the Apache server can handle it and then log into the back end and navigate to the system settings. Select "Rewrite URLs" in the "Front end configuration" section and save your changes. Now Contao generates static URLs like home.html instead of index.php?id=12 .
Installing Contao 7 Manual for Contao 3.2
Using the Safe Mode Hack
While trying to install Contao with the install tool, you might have seen a warning that the local configuration file is not writable.
File permission issues
The term "Safe Mode Hack" is actually misleading, because it implies that the problem was caused by the PHP safe_mode . However, it is caused by insufficient file permissions and can occur even if safe_mode is disabled, so it should be called "File Permission Hack" instead. PHP as an Apache module is typically run as wwwrun , www-data or nobody , whereas the files that you upload via FTP belong to you (e.g. web4 or ab5678 ). The server therefore denies the PHP script Contao access to those files.
Using FTP for file operations
To work around the permission problem, Contao establishes an FTP connection to modify files and folders. All you have to do is to enter your FTP login details. Take special care when entering the relative path from your FTP root directory to the Contao folder (e.g. html/ , public_html/ or httpdocs/ ).
A few directories still require write permissions, because PHP will access them directly:
assets/images
assets/images/*
system/logs
system/tmp
Using the Safe Mode Hack 8 Manual for Contao 3.2
The permissions (CHMOD 777) are set by the install tool automatically and do not have to be adjusted manually normally. Should it be necessary, please only adjust the three directories mentioned above – despite what you might have read in a tutorial or in the Contao forums!
Using the Safe Mode Hack 9 Manual for Contao 3.2
Manual update
When it comes to manually updating a Contao installation, you can either upload the whole Contao download archive to the server (replacing files) or you can upload only the files that have been modified since the last update (synchronizing files). Either way, you should always back up the following files and folders - just in case there is an error or you accidentally override them:
files/*
system/config/dcaconfig.php
system/config/initconfig.php
system/config/langconfig.php
system/config/localconfig.php
templates/*
This will back up your local configuration, your custom templates and your files.
Replacing files
Replacing the files of a Contao installation is pretty simple. Just unpack the Contao download archive on the server or extract it on your local computer and upload the files with an FTP client. Then restore the files that you have backed up and remove potential leftovers from earlier Contao versions.
Attention: If you have installed any third-party extensions, make sure to backup and restore them, too, or do not overwrite them at all. Otherwise you will have to reinstall the modules and depending on the extension you might eventually lose data!
Synchronizing files
To synchronize a Contao installation, you can either use the Unix diff utility or an FTP program. Unix utilities are typically used by server administrators only, so they will not be explained here. To synchronize files via FTP, open WinSCP and connect to the server. Backup the files mentioned above and then navigate to the Contao directory and click the "Synchronize files" button.
Manual update 10 Manual for Contao 3.2
Review the options carefully and make sure to choose "Preview changes", so you can check which files will be updated. Then confirm each file in the preview window and double check the files that are marked for deletion! Click "OK" to start the synchronization process.
Updating the database
After you have updated the Contao files, you need to update the database, too. Fortunately, the Contao install tool will do most of the work for you. Just open it and enter your password, then scroll down to the database section and confirm the changes.
Purge the internal cache
Finally you should also rebuild the internal cache (for DCA and language files). In the backend go to "Maintenance" and check "Purge the internal cache" in the "Purge data" section. Confirm the action by clicking on "Purge data".
You will now receive a message in the header asking to rebuild the internal cache. Click on "Build the cache" to cache the internal files.
Manual update 11 Manual for Contao 3.2
Live Update Service
The Contao Live Update Service is a commercial Contao add-on provided by iNet Robots, the company of the Contao founder and core developer, Leo Feyer. It allows you to update your installation with a only few clicks in the back end, without having to download a Contao archive or using an FTP program to replace or synchronize files.
Sign up for a Live Update ID
The Live Update includes the following features:
Arbitrary up- and downgrades to any Contao version Automatic database backup before the update Individual validation and completion of the Contao installation Comparison of the customized templates and the original files
Version selection
Template differences
Live Update Service 12 Manual for Contao 3.2
Troubleshooting
99% of all Live Update issues are caused by wrong file permissions. Contao requires write permissions to manage files and folders, therefore if the Live Update does not work properly, check your server configuration and make sure to set up the Safe Mode Hack as described in this user guide!
How to get support
If you are having problems activating your Live Update ID or receiving the update archive, please contact the iNet Robots support. If you are having problems configuring the Safe Mode Hack or using Contao, please choose a support option on the support page.
Live Update Service 13 Manual for Contao 3.2
Moving an installation
Moving a Contao installation from a local server to a live server is not much different from installing a fresh Contao version, except that you are using the files from your local installation instead of the Contao download archive and an SQL dump of your local database.
Uploading the files
Open your FTP program, connect to the target server and upload all files from your local Contao installation.
Exporting the database
The easiest way to create a MySQL dump is to use the database administration tool "phpMyAdmin". If you are a server administrator, you can also use the mysqldump utility of course. Log into "phpMyAdmin", choose the database that you want to export and click the "Export" tab in the top menu. It is important to adjust the export settings according to the screenshot below to minimize MySQL version compatibility problems.
Importing the database
Open "phpMyAdmin" on the target server and create a new database for Contao. Depending on the server configuration, you probably have to use the server administration panel (e.g. "Plesk" or "cPanel") to create new databases. Select the empty database and click the "Import" tab in the top menu. Then upload the SQL dump of your local database and start the
Moving an installation 14 Manual for Contao 3.2
import.
Adjusting the database configuration
Finally open the Contao install tool of the new installation (the password should be the same as for your local installation) and adjust the database configuration if necessary. Then go to the back end and log in with your username and password.
Moving an installation 15 Manual for Contao 3.2
Configuring the live server
This chapter is not about configuring a server in terms of installing Apache or compiling PHP, which you cannot do on a shared hosting account anyway. It explains how to check whether the Contao system requirements are met and how to enable PHP 5.
Contao system requirements
Contao requires a webserver like Apache or IIS with PHP and MySQL support. The minimum PHP version is 5.3.2 and the minimum MySQL version is 5.0. You also need the PHP extensions "GDlib" (image resizing), "DOM" (XML files), "SOAP" (Extension Repository) and optionally "mbstring" (multi-byte character handling) as well as "mcrypt" (data encryption). Contao has been tested successfully with all major browsers like Firefox (from version 2) or Internet Explorer (from version 8).
The Contao check
Download the Contao Check to find out whether your server meets the Contao system requirements. The script will check whether you can use the Extension Repository and the Live Update and whether you have to use the Safe Mode Hack or not. Depending on your system configuration, you can set up a new Contao installation with the web installer or validate an existing installation.
Extract the Zip file, upload the check folder to your Contao installation directory and open it in a web browser.
Download the Contao Check | Open the GitHub project
ISP-specific settings
There are a few major Internet Service Providers that require a little extra configuration to get Contao to work. Fortunately, they are just the exception from the rule. The ISP-specific settings are described in the Contao forum. If you are looking for hassle-free Contao hosting, check out the list of Contao hosting partners.
Configuring the live server 16 Manual for Contao 3.2
Administration area
To access the Contao administration area (back end) simply add /contao to the URL of your Contao website. The back end login is protected against brute force attacks, so if you enter a wrong password more than three times in a row, your account will be locked for 5 minutes. Please note that usernames and passwords are case-sensitive.
Administration area 17 Manual for Contao 3.2
Listing records
The Contao core engine supports three views: a simple list ("list view"), a list that is grouped by its parent table ("parent view") and a hierarchical list ("tree view"). These three views can be used to list the records of any table or related tables.
List view
The "list view" lists the records of a single table in a particular order. The results are usually grouped by their first letter.
Parent view
The "parent view" lists the records of a child table that are related to a particular record of a parent table. Parent-child relations are used a lot in Contao, e.g. for articles and content elements, news archives and news articles or style sheets and format definitions.
Listing records 18 Manual for Contao 3.2
Tree view
The "tree view" lists records and other resources like files and folders that are organized in a hierarchical structure. Contao supports listing single hierarchical tables (e.g. the site structure) as well as child tables that relate to hierarchical parent tables (e.g. articles and pages).
Listing records 19 Manual for Contao 3.2
Sorting and filtering data
Contao supports various ways to refine results so you do not lose track even if a table has several thousands of rows. A lot of listings can be filtered by one or more fields so they only show the records matching the filter criteria. Most listings additionally offer a full text search that even supports regular expressions. To keep the page loading time down to a minimum, Contao only shows 30 records at a time.
Listing records 20 Manual for Contao 3.2
Editing records
Editing data is one of the central functions of a Content Management System. Contao offers a lot of professional features that make the editing process as easy and comfortable as possible. You can revert back to earlier versions of a record, restore deleted records, move records via clipboard and even edit multiple records at once. Most of these functions can be accessed using the navigation icons.
List view icons
The "list view" being the simplest view only offers the four basic actions: edit, duplicate, delete and show.
Parent view icons
The "parent view" offers two additional navigation icons to control the order of the records. The order can also be changed via drag and drop. To do so, simply click on the navigation icon "Drag and drop" and drag it to its new position.
Editing records 21 Manual for Contao 3.2
Tree view icons
The "tree view" requires additional icons to handle the hierarchical structure. Besides duplicating a single record, it also supports duplicating a record with all its sub-records as well as pasting it after or into another record, so you can create a nested structure.
Editing records 22 Manual for Contao 3.2
Restoring prior versions
Contao automatically creates new versions of a record every time you save it. As soon as there is more than one version, a drop-down menu which allows you to revert back to a prior version appears at the top of the form. Simply choose a version and click the "Restore" button.
The icon to the right of the "Restore" button allows you to see the differences between two versions.
Editing records 23 Manual for Contao 3.2
Editing multiple records
The ability to edit more than one record at a time clearly makes Contao stand out from the variety of content management systems. Click the "Edit multiple" button to switch the editing mode, then select one or more records and choose the fields that you want to modify.
Editing records 24 Manual for Contao 3.2
Editing records 25 Manual for Contao 3.2
Editing records 26 Manual for Contao 3.2
Keyboard shortcuts
To speed up the workflow when working with Contao, there are several back end shortcuts which allow you to execute certain commands. You can e.g. trigger the "save" button at the end of a form by klicking it with your mouse or by using the keyboard shortcut [Alt]+[s] .
General keyboard shortcuts
Shortcut Button Explanation
[Alt]+[h] Home Go to the home page of the back end.
[Alt]+[q] Quit Quit the current back end session (log out).
[Alt]+[t] Top Go to the top of the page.
[Alt]+[b] Back Go back to the previous page.
[Alt]+[n] New record Create a new record.
[Alt]+[e] Edit multiple Switch to the "edit multiple" mode.
[Alt]+[f] Front end preview Open the front end preview in a new browser window.
Keyboard shortcuts in edit mode
Shortcut Button Explanation
[Alt]+ [s] Save Saves the current form.
[Alt]+ Save and Saves the current form and redirects to the previous page. [c] close
[Alt]+ Save and go Saves the current form and redirects to the parent page, e.g. from a content element [g] back to the article tree.
[Alt]+ Saves the current form and redirects to the child records view, e.g. when creating Save and edit [e] style sheets.
[Alt]+ Save and Saves the current form and creates a new record. [n] new
Keyboard shortcuts in "edit multiple" mode
Shortcut Button Explanation
[Alt]+[d] Delete multiple Deletes all selected records in "edit multiple" mode.
[Alt]+[x] Cut multiple Moves all selected records in "edit multiple" mode.
[Alt]+[c] Copy multiple Duplicates all selected records in "edit multiple" mode.
[Alt]+[v] Override multiple Overrides all selected records in "edit multiple" mode.
The keyboard shortcuts above only work on Windows in this form. Mac users have to use [Ctrl]+[⌥ Opt] instead of the [Alt] key together with the keyboard shortcut. In addition, Firefox on Windows deviates from the standard: you have to press [Alt]+[Shift] and the keyboard shortcut.
Keyboard shortcuts 27 Manual for Contao 3.2
Managing pages
The following chapters explain how to manage pages in Contao. Since Contao is a page-based content management system, pages and the site structure are the central elements of your website and any content that is not associated with a page can never be viewed.
Managing pages 28 Manual for Contao 3.2
Components
Understanding how pages, articles, content elements and modules relate to each other is the key to learning Contao. As mentioned before, the site structure is the central element of your website. Visitors of your website always request pages and not articles like in a node-based CMS.
The diagram shows that articles and layouts are the two most important page elements. Whereas articles store the content of a page, the page layout defines how it is displayed on the website. Contao layouts are CSS-based and of course do not use layout tables. The following chapters explain how to create style sheets and modules, how to combine them in a page layout and how to create pages that are using it.
Components 29 Manual for Contao 3.2
Themes
A website design typically consists of style sheets, front end modules, page layouts, files and templates, which you can manage in the Contao back end. The theme manager does not change this approach at all, it just adds an option to export and import those resources.
Themes versus front end templates
The main difference between themes and front end templates is that a front end template contains a fully preconfigured example website, including an example site structure, articles, content elements and even users and groups. A theme, in contrast, contains only the actual website design and can therefore be imported without losing any existing data.
Theme components
A theme is a group of style sheets, front end modules and page layouts, which are all stored in the database and automatically recognized by the theme exporter. You will learn more about those elements in the following chapters. A theme typically also includes images and other files from the files directory and optional custom templates from the templates directory. However, those resources are not automatically linked with the theme and therefore have to be added in the theme configuration to be included in the theme export.
Themes 30 Manual for Contao 3.2
Theme export and import
To export a theme, simply click on the export button and download the .cto file to your local computer. Although .cto is a proprietary file extension for Contao themes, the file is actually a ZIP archive that can be extracted with every program that handles .zip files. To reimport the theme, upload the .cto file to your Contao installation, open the theme manager and click on "Theme import". You can import multiple themes at once. After the import has been completed, you can assign the page layout(s) of the new theme in the site structure.
Themes 31 Manual for Contao 3.2
Style sheets
Accessible websites should always be styled using CSS, that is why Contao includes a "style sheets" module which allows you to manage format definitions in the back end. To reference the various Contao elements, you need to know their class names. Content element classes start with "ce_" (e.g. "ce_text") and module classes with "mod_" (e.g. "mod_search"). If you are not sure, simply look into the page source.
Every style sheet can be limited to one or more media types and/or to a particular Internet Explorer version, in case you need to fix one of its numerous bugs. Pay attention to the order of the format definitions, because later commands override earlier ones.
/* Set the general value first */ .mod_search { margin:24px; }
/* Then override it for IE7 */ *:first-child+html .mod_search { margin:18px; }
If the order was reversed, the general value would override the IE-specific margin.
Style sheets 32 Manual for Contao 3.2
Style sheets 33 Manual for Contao 3.2
Modules
Front end modules allow you to add almost any kind of functionality to your website. The Contao core includes modules to generate various navigation menus, handle user registration and authentication, search the website, import RSS feeds and many more. To create a module, log into the back end and choose "Themes" -> "Front end modules" in the navigation menu.
Module CSS class Description
Navigation menu mod_navigation Generates a navigation menu from the site structure.
Custom navigation mod_customnav Generates a custom navigation menu.
Breadcrumb navigation mod_breadcrumb Generates a breadcrumb navigation menu.
Quick navigation mod_quicknav Generates a drop-down menu from the site structure.
Quick link mod_quicklink Generates a custom drop-down menu.
Book navigation mod_booknav Generates a book navigation menu.
Article navigation mod_article_nav Generates a pagination menu to navigate articles.
Sitemap mod_sitemap Generates a list of all pages in the site structure.
Login form mod_login Generates a login form.
Automatic logout - Automatically logs out a user.
Personal data mod_personalData Generates a form to edit a user's personal data.
Registration mod_registration Generates a user registration form.
Lost password mod_password Generates a form to request a new password.
Close account mod_closeAccount Generates a form to delete a member account.
Newslist mod_newslist Adds a list of news items to the page.
Newsreader mod_newsreader Shows the details of a news item.
News archive mod_newsarchive Adds a news archive to the page.
News archive menu mod_newsmenu Generates a navigation menu to browse the news archive.
Calendar mod_calendar Adds a calendar to the page.
Event reader mod_eventreader Shows the details of an event.
Event list mod_eventlist Adds a list of events to the page.
Event list menu mod_eventmenu Generates a navigation menu to browse the event list.
Subscribe mod_subscribe Generates a form to subscribe to one or more channels.
Unsubscribe mod_unsubscribe Generates a form to unsubscribe from one or more channels.
Newsletter list mod_nl_list Adds a list of newsletters to the page.
Newsletter reader mod_nl_reader Shows the details of a newsletter.
FAQ list mod_faqlist Adds a list of frequently asked questions to the page.
FAQ reader mod_faqreader Shows the answer to a frequently asked question.
FAQ page mod_faqpage Shows the FAQ list and FAQ reader on the same page.
Form mod_form Adds a form to a page.
Modules 34 Manual for Contao 3.2
Search engine mod_search Adds a search form to a page.
Comments mod_comments Manage comments or guestbook entries.
Listing mod_listing Lists the records of a table.
Flash movie mod_flash Embeds a Flash movie into a page.
Article list mod_article_list Generates a list of articles of a column.
Random image mod_random_image Adds a random image to a page.
Custom HTML - Allows you to add custom HTML code.
RSS reader mod_rss_reader Adds an RSS feed to a page.
Access control
Each front end module can be protected so only guests or members of a particular group can see it on the website.
Modules 35 Manual for Contao 3.2
Page layouts
Page layouts determine the basic page setup, e.g. the number of columns or the overall width, and they define which front end modules are shown in which columns. They also allow you to include style sheets, to link to RSS or Atom feeds, to associate a Google Analytics ID and to add arbitrary JavaScript code that is required to control interactive elements and plugins. The Contao CSS framework automatically divides the browser window into several layout sections and shows the modules that have been assigned to them one below the other.
That implies that by the time you create a page layout, you have to have created all style sheets and front end modules that you want to include in it. Therefore it is recommended to create resources in the following order:
Create the necessary front end modules Create the necessary style sheets Optionally create news archives or calendars Create a new page layout and combine the components
Page layouts 36 Manual for Contao 3.2
Page types
The page type determines whether a page shows content, forwards to another page or defines the starting point of a new website within the page tree. Contao supports 6 different page types which are explained below.
Page Description type
Regular A regular page contains articles and content elements. It behaves like a static HTML page. page
External This type of page automatically redirects visitors to an external website. It works like a hyperlink. redirect
Internal This type of page automatically forwards visitors to another page within the site structure. redirect
Website This type of page marks the starting point of a new website within the site structure. root
403 If a user requests a protected page without permission, a 403 error page will be loaded instead. This Access page must be added on the first level inside your website root page. denied
404 Page If a user requests a non-existent page, a 404 error page will be loaded instead. This page must be not found added on the first level inside your website root page.
Multi-domain mode
Contao supports multiple websites within the site structure and automatically redirects visitors to a particular website root page depending on its DNS and language settings. Let us assume that you are running a bilingual corporate website which uses the domain "www.example.com" and a small private website which uses the domain "www.personal.example.org". You need three website root pages for that:
Type DNS Language code Fallback language
German corporate website none de no
English corporate website none en yes
Personal website www.personal.example.org de yes
The following table shows to which page a visitor will be redirected depending on the domain and his browser language.
Domain Browser language Redirect target
www.example.com English English corporate website
www.example.com German German corporate website
www.example.com Spanish English corporate website
www.personal.example.org irrelevant Personal website
Note that if we had not set the "language fallback" option, the personal website would only be available for German speaking users!
Access rights
Access rights determine what back end users are allowed to do with a page and its articles. It has nothing to do with
Page types 37 Manual for Contao 3.2
protected pages that can only be accessed by certain front end users! Similar to the Unix file permission system, there are three permission levels:
Access as the owner of a page Access as a member of the group that owns the page Access as an unprivileged user
Each level can have different permissions. By default, the owner of a page is allowed to edit the page itself as well as its articles, whereas a user of the group that owns a page is only allowed to edit articles. Unprivileged users have no writing permissions at all.
Page types 38 Manual for Contao 3.2
Managing content
The following chapters explain how to manage content in Contao. The Contao core supports many different content types like articles, news, events, newsletters or forms. Further content types like banners, tickets, products or recommendations are available in the Extension Repository. To create content, log into the back end and choose one of the modules in the Content section of the navigation menu.
Managing content 39 Manual for Contao 3.2
Articles
Articles are containers for content elements. Grouping content elements that belong together makes it easy to move, publish, copy, edit or export them all at once instead of one by one. Each article is associated with a particular page and layout section and therefore has a fixed position in the site structure and on the website. Contao optionally shows only the article teaser with a "Read more" link.
Content elements
Content elements are an easy and intuitive way to create content. Instead of just using a Rich Text Editor, Contao provides a separate element for each type of content like texts, lists, tables, hyperlinks, images or downloads. Here is an overview of the Contao core content elements:
Name CSS class Description
Headline ce_headline Generates a headline (h1 - h6).
Text ce_text Generates a rich text that can be formatted using TinyMCE.
HTML - Allows you to add custom HTML code.
List ce_list Generates an ordered or unordered list.
Table ce_table Generates an optionally sortable table.
Code ce_code Highlights code snippets and prints them to the screen.
Accordion (single element) ce_accordion Generates a single accordion element (with MooTools).
Accordion (wrapper start) ce_accordionStart Generates the opening part of the accordion wrapper.
Accordion (wrapper stop) - Generates the closing part of the accordion wrapper.
Content slider (wrapper start) ce_sliderStart Generates the opening part of the slider wrapper.
Content slider (wrapper stop) - Generates the closing part of the slider wrapper.
Hyperlink ce_hyperlink Generates a link to another website.
Top link ce_toplink Generates a link to jump to the top of the page.
Image ce_image Generates a stand-alone image.
Gallery ce_gallery Generates a lightbox image gallery.
Video/audio ce_player Generates a video or audio player.
YouTube ce_youtube Adds a YouTube video.
Download ce_download Generates a link to download a file.
Downloads ce_downloads Generates multiple links to download files.
Article - Includes another article.
Content element (parent class) Includes another content element.
Form ce_form Includes a form.
Module (parent class) Includes a front end module.
Article teaser ce_teaser Displays the teaser text of an article.
Comments ce_comments Adds a comment form to the page.
Articles 40 Manual for Contao 3.2
Access control
Each content element can be protected so only guests or members of a particular group can see it on the website.
Flash content
Flash content is a special type of content which is not shown in an article on the website but loaded into a dynamic Flash movie using "loadVars()". To allow communication between Contao and Flash, you have to add the following function to the root frame of your movie:
TextField.prototype._loadArticle = function(flashID) { tf = this;
// Enable HTML mode and remove content tf.html = true; tf.htmlText = "";
// Instantiate a new LoadVars object lv = new LoadVars(); lv["flashID"] = flashID; lv.sendAndLoad(URL + "flash.php", lv, "POST");
lv.onLoad = function(success) { if (success) { tf.htmlText = lv["content"]; } } }
// Load the Flash content "myArticle" into the text field "myTextBox" myTextBox._loadArticle("myArticle");
Importing a style sheet
The following ActionScript allows you to import a style sheet to format a dynamic text field:
TextField.prototype._addCSS = function(style_sheet) { tf= this; tf.styleSheet = null;
// Instantiate a new StyleSheet object st = new TextField.StyleSheet(); st.load(URL + style_sheet);
Articles 41 Manual for Contao 3.2
st.onLoad = function(success) { if (success) { tf.styleSheet = st; } } }
// Add the style sheet "basic.css" to the text box "myTextBox" myTextBox._addCSS("basic.css");
Note that Flash only supports a small subset of HTML tags, so some of your styles might not display correctly.
Articles 42 Manual for Contao 3.2
News items
The news/blog extension allows you to manage news items or blog posts and display them in the front end. Unlike articles that are associated with a particular page, news items are organized in news archives, which allows you to easily group, categorize or export them.
News archives
News archives are used to group and/or categorize news items. Each archive can relate to a certain language or a particular topic.
Front end modules
Front end modules are used to display news items on the website. They can be configured with the "Modules" module in the back end and have to be added to an article or page layout to actually show up on the website. The news/blog extension includes four front end modules:
Module CSS class Description
Newslist mod_newslist Adds a list of news items to a page.
Newsreader mod_newsreader Shows the details of a news item.
News archive mod_newsarchive Adds a news archive to a page.
News archive menu mod_newsarchiveMenu Generates a navigation menu to browse the news archive.
Permalinks
Each news item has a unique URL (permalink) that can be used to reference it:
http://www.example.com/news/items/james-wilson-returns.html
The above URL requests the news item "james-wilson-returns" via the page "news". Remember that Contao is a page- based CMS, so if the page "news" did not exist or if it did not include the news reader module, the news item would not be displayed.
News items 43 Manual for Contao 3.2
Events
The calendar extension allows you to manage events and display them in a calendar or event list on the website. Unlike articles that are associated with a particular page, events are organized in calendars, which allows you to easily group, categorize or export them.
Calendars
Calendars are used to group and/or categorize events. Each calendar can relate to a certain language or a particular topic.
Front end modules
Front end modules are used to display events on the website. They can be configured with the "Modules" module in the back end and have to be added to an article or page layout to actually show up on the website. The calendar extension includes four front end modules:
Module CSS class Description
Calendar mod_calendar Adds a calendar to the page.
Event reader mod_eventreader Shows the details of an event.
Event list mod_eventlist Adds a list of events to the page.
Event list menu mod_eventmenu Generates a navigation menu to browse the event list.
Permalinks
Each event has a unique URL (permalink) that can be used to reference it:
http://www.example.com/event-reader/events/final-exams.html
The above URL requests the event "final-exams" via the page "events". Remember that Contao is a page-based CMS, so if the page "events" did not exist or if it did not include the event reader module, the event would not be displayed.
Events 44 Manual for Contao 3.2
RSS/Atom feed
This feature can be used for news archives and calendars. Here is an example with the calendars list.
Settings
One or several calendars can be grouped and exported as an RSS or Atom feed. It goes the same for news archives. At the same time, you can choose to export only the teasers or full articles of each event or news.
RSS/Atom feed 45 Manual for Contao 3.2
XML files
The XML files are generated automatically in the share directory of your Contao installation. In this example : share/events.xml .
RSS/Atom feed 46 Manual for Contao 3.2
Newsletters
The newsletter extension allows you to manage and send newsletters and optionally display them on the website. Unlike articles that are associated with a particular page, newsletters are organized in channels, which allows you to easily group or categorize them.
Recipients
Newsletter subscriptions are normally handled by the respective front end modules, so you do not have to manage recipients manually. For data privacy reasons, Contao requires Double Opt-In subscriptions and stores only the e-mail address of the subscriber.
In case you already have a list of recipients, you can import them into Contao from a CSV file.
Personalized newsletters
Insofar as you are sending newsletters to registered members, you can personalize them with so called "Simple Tokens". Simple tokens are similar to insert tags and can be used in both the HTML and the text content of a newsletter.
Dear ##firstname## ##lastname##,
Please check and update your personal data:
Street: ##street## Postal: ##postal## City: ##city## Phone: ##phone## E-mail: ##email##
The Administrator
In contrast to insert tags, however, simple tokens do not only allow you to insert data of the member table tl_member , but also to realize simple if-else statements to e.g. specify the salutation.
{if gender=="male"} Dear Mr ##lastname##,
Newsletters 47 Manual for Contao 3.2
{elseif gender=="female"} Dear Mrs ##lastname##, {else} Dear Sirs, {endif}
[newsletter content]
{if phone==""} Please update your contact details and enter your phone number. {endif}
The Administrator
Sending newsletters
Especially on shared hosting servers, there are typically limitations regarding the script execution time and/or the number of e-mails that can be sent per minute. Contao tries to work around both problems by splitting the sending process into several cycles to prevent script timeouts and adding a custom waiting time between each cycle to control the number of e- mails per minute.
Front end modules
Front end modules are used to handle subscriptions and to optionally display newsletters on the website. They can be configured with the "Modules" module in the back end and have to be added to an article or page layout to actually show up on the website.
Module CSS class Description
Newsletters 48 Manual for Contao 3.2
Subscribe mod_subscribe Generates a form to subscribe to one or more channels.
Unsubscribe mod_unsubscribe Generates a form to unsubscribe from one or more channels.
Newsletter list mod_nl_list Adds a list of newsletters to the page.
Newsletter reader mod_nl_reader Shows the details of a newsletter.
Permalinks
Each newsletter has a unique URL (permalink) that can be used to reference it:
http://www.example.com/newsletters/items/james-wilson-returns.html
The above URL requests the newsletter "james-wilson-returns" via the page "newsletters". Remember that Contao is a page-based CMS, so if the page "newsletters" did not exist or if it did not include the newsletter reader module, the newsletter would not be displayed.
Newsletters 49 Manual for Contao 3.2
Forms
The built-in form generator can be used to create interactive forms that are sent via e-mail or stored in the Contao database. Uploaded files can be sent as e-mail attachment or stored in the Contao files directory. The form generator supports four different data formats:
Format Description
Raw The form data will be sent as plain text message with each field in a new line. data
XML The form data will be attached to the e-mail as an XML file. file
CSV The form data will be attached to the e-mail as a CSV file. file
Ignores all fields except email, subject, message and cc (carbon copy) and sends the form data like it E-mail had been sent from a mail client. File uploads are allowed.
Form fields
Similar to content elements, Contao provides a separate element for each type of form field like text fields, password fields, select menus, file uploads, hidden fields or submit buttons. Here is an overview of the Contao core form fields:
Field CSS class Description
Headline headline A custom field to insert a section headline.
Explanation explanation A custom field to insert an explanation text.
HTML code - A custom field to insert HTML code.
A container for form fields with an optional legend (only available for Fieldset - tableless forms).
Text field text A single-line input field for a short or medium text.
A single-line input field for a password. Contao automatically adds a Password field password confirmation field.
Textarea textarea A multi-line input field for a medium or long text.
Select menu select/multiselect A single- or multi-line drop-down menu.
Radio button radio A list of multiple options from which one can be selected. menu
Checkbox checkbox A list of multiple options from which any can be selected. menu
File upload upload A single-line input field to upload a local file to the server.
Hidden field - A single-line input field that is not visible in the form.
Security A simple math question to verify that the form is being submitted by a captcha question human (CAPTCHA).
Submit field submit A button to submit the form.
Front end module
The front end module is used to display forms on the website. They can be configured with the "Modules" module in the
Forms 50 Manual for Contao 3.2
back end and have to be added to an article or page layout to actually show up on the website. The form generator extension includes one front end module:
Module CSS class Description
Form mod_form Adds a form to a page.
Content element
The content element is used to display forms on the website. They can be configured with the "Form" content element in the back end and have to be added to an article to actually show up on the website. The form generator extension includes one content element:
Content element CSS class Description
Form ce_form Includes a form.
Forms 51 Manual for Contao 3.2
Comments
Comments are another form of content that you can manage from the back end. Comments must be enabled in the calendar and news archive preferences.
Front end module
The front end module is used to display comments on the website. They can be configured with the "Modules" module in the back end and have to be added to an article or page layout to actually show up on the website. The comments extension includes one front end module:
Module CSS class Description
Comments mod_comments Manage comments or guestbook entries.
Content element
The content element is used to display comments on the website. They can be configured with the "Comments" content element in the back end and have to be added to an article to actually show up on the website. The comments extension includes one content element:
Content element CSS class Description
Comments ce_comments Adds a comment form to the page.
BBCode
You can allow the front end users to use the BBCode markup language.
Contao supports the following tags:
BBCode Definition
[b][/b] Replaces the tag with a bolded text.
[i][/i] Replaces the tag with an italicized text.
[u][/u] Replaces the tag with an underlined text.
[img][/img] Replaces the tag with an image (Add an URL between the tags).
[code][/code] Replaces the tag with a monospaced text.
[color=#ff0000][/color] Replaces the tag with a colored text.
[quote][/quote] Replaces the tag with a quoted text.
Replaces the tag with a quoted text and the author name (e.g. John wrote: [quote=John]Hello[/quote] Hello).
[url][/url] Replaces the tag with a link.
[url=http://][/url] Replaces the tag with a link (insert the URL as the parameter)
[email][/email] Replaces the tag with a mailto link.
[[email protected]] Replaces the tag with a mailto link (insert the e-mail address as the [/email] parameter).
Comments 52 Manual for Contao 3.2
Templates
A template is mainly composed of HTML and PHP code. It is used to structure a piece of content of a module or a content element, etc. For example, the template news_full.html5 displays the full content of a news item whereas the template news_short.html5 displays only a portion of this content.
The templates are located in their own modules. For example, news_full.html5 is located under system/modules/news/templates/news .
If you edit this file directly in this folder, it will be overwritten the next time you will update Contao and you will lose all your changes. To avoid this, Contao allows you to modify the templates directly from the back end. In this case, the file is duplicated and your changes will be preserved during each update.
Create a new folder and add one or more templates you want to edit. Subsequently, do not forget to attach the folder to the theme as explained in the paragraph Theme components.
A template can be a part of the structure of a module, a content element, a form, etc. and that is why they are prefixed. They can be easily grouped, ordered and recognized. For example: the prefix j_ means "jQuery" and nl_ means "newsletter".
Templates 53 Manual for Contao 3.2
Insert tags
Insert Tags are wildcards that are replaced with dynamic content when a page is printed to the screen. They e.g. allow you to show the current date, address a front end user by his name or include a file. Insert tags can be used almost anywhere in Contao, even on cached pages.
Link elements
The following Insert Tags allow you to link to another page or article using its ID or alias.
Insert Tag Description
{{link::*}} This tag will be replaced with a link to an internal page (replace * with the page ID or alias).
{{link::back}} This tag will be replaced with a link that points to the last visited page. It can also be used as {{link_open::back}} , {{link_url::back}} or {{link_title::back}} (see below).
{{link::login}} This tag will be replaced with a link to the login page of the currently logged in front end user (if any).
{{link_open::12}}Click {{link_open::*}} Will be replaced with the opening tag of a link to an internal page: here{{link_close}} .
{{link_open::12}}Click {{link_close}} Will be replaced with the closing tag of a link to an internal page: here{{link_close}} .
{{article::*}} This tag will be replaced with a link to an article (replace * with the article ID or alias).
{{article_open::12}}Click {{article_open::*}} Will be replaced with the opening tag of a link to an article: here{{link_close}} .
Click {{article_url::*}} This tag will be replaced with the URL of an article: here .
Click {{article_title::*}} This tag will be replaced with the title of an article: here .
{{news::*}} This tag will be replaced with a link to a news item (replace * with the news ID or alias).
{{news_open::12}}Click {{news_open::*}} Will be replaced with the opening tag of a link to a news article: here{{link_close}} .
Click {{news_url::*}} This tag will be replaced with the URL of a news article: here .
Click {{news_title::*}} This tag will be replaced with the title of a news article: here .
{{news_feed::*}} This tag will be replaced with the URL of a news feed (replace * with the news feed ID).
{{event::*}} This tag will be replaced with a link to an event (replace * with the event ID or alias).
{{event_open::12}}Click {{event_open::*}} Will be replaced with the opening tag of a link to an event: here{{link_close}} .
Click {{event_url::*}} This tag will be replaced with the URL of an event: here .
Click {{event_title::*}} This tag will be replaced with the title of an event: here .
Insert tags 54 Manual for Contao 3.2
{{calendar_feed::*}} This tag will be replaced with the URL of a calendar feed (replace * with the calendar feed ID).
{{faq::*}} This tag will be replaced with a link to a frequently asked question (replace * with the FAQ ID or alias).
{{faq_open::12}}Click {{faq_open::*}} Will be replaced with the opening tag of a link to a question: here{{link_close}} .
Click {{faq_url::*}} This tag will be replaced with the URL of a question: here .
Click {{faq_title::*}} This tag will be replaced with the title of a question: here .
User properties
The following Insert Tags allow you to display any property of the currently logged in user.
Insert Tag Description
{{user::firstname}} This tag will be replaced with the first name of the currently logged in user.
{{user::lastname}} This tag will be replaced with the last name of the currently logged in user.
{{user::company}} This tag will be replaced with the company name of the currently logged in user.
{{user::phone}} This tag will be replaced with the phone number of the currently logged in user.
{{user::mobile}} This tag will be replaced with the mobile number of the currently logged in user.
{{user::fax}} This tag will be replaced with the fax number of the currently logged in user.
{{user::email}} This tag will be replaced with the e-mail address of the currently logged in user.
{{user::website}} This tag will be replaced with the web address of the currently logged in user.
{{user::street}} This tag will be replaced with the street name of the currently logged in user.
{{user::postal}} This tag will be replaced with the postal code of the currently logged in user.
{{user::city}} This tag will be replaced with the city of the currently logged in user.
{{user::country}} This tag will be replaced with the country of the currently logged in user.
{{user::username}} This tag will be replaced with the username of the currently logged in user.
Page properties
The following Insert Tags allow you to display any property of the current page.
Insert Tag Description
{{page::id}} This tag will be replaced with the ID of the current page.
{{page::alias}} This tag will be replaced with the alias of the current page.
{{page::title}} This tag will be replaced with the name of the current page.
{{page::pageTitle}} This tag will be replaced with the title of the current page.
{{page::language}} This tag will be replaced with the language of the current page.
{{page::parentAlias}} This tag will be replaced with the alias of the parent page.
{{page::parentTitle}} This tag will be replaced with the name of the parent page.
{{page::parentPageTitle}} This tag will be replaced with the title of the parent page.
Insert tags 55 Manual for Contao 3.2
{{page::mainAlias}} This tag will be replaced with the alias of the parent main page.
{{page::mainTitle}} This tag will be replaced with the name of the parent main page.
{{page::mainPageTitle}} This tag will be replaced with the title of the parent main page.
{{page::rootTitle}} This tag will be replaced with the name of the website.
{{page::rootPageTitle}} This tag will be replaced with the title of the website.
Environment variables
The following Insert Tags allow you to display environment variables like the page name or the request string.
Insert Tag Description
{{env::host}} This tag will be replaced with the current host name.
{{env::url}} This tag will be replaced with the host name and the protocol.
{{env::path}} This tag will be replaced with the current base URL including the path to the Contao directory.
{{env::request}} This tag will be replaced with the current request string.
{{env::ip}} This tag will be replaced with the IP address of the current visitor.
{{env::referer}} This tag will be replaced with the URL of the last page visited.
{{env::files_url}} This tag will be replaced with the static URL of the files directory.
{{env::assets_url}} This tag will be replaced with the static URL of the assets directory.
Include elements
The following Insert Tags allow you to include various resources like articles, modules or files from the "templates" directory.
Insert Tag Description
{{insert_article::*}} This tag will be replaced with the referenced article (replace * with the article ID or alias).
{{insert_content::*}} This tag will be replaced with the referenced content element (replace * with the element ID).
{{insert_module::*}} This tag will be replaced with the referenced module (replace * with the module ID).
{{insert_form::*}} This tag will be replaced with the referenced form (replace * with the form ID).
{{article_teaser::*}} This tag will be replaced with the teaser of an article (replace * with the article ID).
{{news_teaser::*}} This tag will be replaced with the teaser of a news item (replace * with the news ID).
{{event_teaser::*}} This tag will be replaced with the teaser of an event (replace * with the event ID).
This tag will be replaced with the content of a file from the "templates" directory (replace * {{file::file.php? {{file::*}} with the file name). You can also provide arguments: arg1=val&arg2=val}} . You can also retrieve the path of a file from the database with its UUID: {{file::6939a448-9b30-11e4-bcba-079af1e9baea}} .
Miscellaneous
The following Insert Tags allow you to perform miscellaneous tasks like adding the current date or including lightbox images.
Insert Tag Description
Insert tags 56 Manual for Contao 3.2
{{date}} This tag will be replaced with the current date according to the global date format.
{{date::*}} This tag will be replaced with the current date according to a custom date format.
{{last_update}} This tag will be replaced with the date of the last update according to the global date format.
{{last_update::*}} This tag will be replaced with the date of the last update according to a custom date format.
{{email::*}} This tag will be replaced with a clickable and encrypted link to an e-mail address.
{{email_open::*}} This tag will be replaced with a clickable and encrypted link to an e-mail address. However, the closing will not be added.
{{email_url::*}} This tag will be replaced by the encrypted e-mail address only.
This tag can be used to mark foreign words within a text: {{lang::fr}}Au revoir{{lang}} . It {{lang::*}} will be replaced with Au revoir and adds the xml:lang="fr" attribute if the doctype is XHTML.
{{abbr::World Wide Web}}WWW{{abbr}} {{abbr::*}} Mark abbreviations in a text: . It will be replaced with WWW .
Mark acronyms in a text: {{acronym::Multipurpose Internet Mail Extensions}}MIME{{acronym}} . {{acronym::*}} It will be replaced with MIME .
{{ua::*}} Output properties of the user agent: {{ua::browser}} . It will e.g. be replaced with "chrome".
This tag will be completely removed if the page language does not match the tag language. {{iflng::*}} You can use it to define language-specific labels: {{iflng::en}}Your name{{iflng::de}}Ihr Name{{iflng}} .
This tag will be completely removed if the page language matches the tag language. You can {{ifnlng::*}} use it to define language-specific labels: {{ifnlng::de}}Your name{{ifnlng}}{{iflng::de}}Ihr Name{{iflng}} .
This tag will be replaced with the thumbnail of an image (replace * with the database ID, UUID or a file system path): {{image::58ca4a90-2d30-11e4-8c21-0800200c9a66? width=200&height=150}} . width: Thumbnail width, {{image::*}} height: Thumbnail height, alt: Alternative text, class: CSS class, rel: rel-attribute (e.g. "lightbox"), mode: Mode ("proportional", "crop" or "box").
This tag will be replaced with a translated label. The first parameter is a language file name CNT LNG {{label::CNT:au}} {{label::*}} or an acronym such as (countries) or (languages). Examples: displays "Australia" and {{label::tl_article:title:0}} displays "Title". Note that only the first colon is a double colon.
{{version}} This tag will be replaced with the current Contao version (e.g. 3.2.7).
{{request_token}} This tag will be replaced with the request token of the current session.
{{toggle_view}} Adds the link which allows you to switch between mobile and desktop layout.
{{br}} This tag will be replaced with the HTML
tag (line break).
Insert tag flags
Using flags, insert tags can be further processed. For example, the value can be passed to specific PHP methods. Multiple flags can be applied:
{{ua::browser|uncached}} {{page::title|decodeEntities|strtoupper}}
Available flags:
Insert tags 57 Manual for Contao 3.2
Flag Description More information
uncached Do not replace insert tag when the page is cached
refresh Do not cache the insert tag, even if it is used multiple times on the same page
addslashes Quote a string with slashes PHP function
stripslashes Remove the slashes from a quoted string PHP function
standardize Standardize the output (e.g. for a page alias or CSS class)
ampersand Convert ampersands to HTML entities
specialchars Convert special characters to HTML entities
nl2br Inserts HTML line breaks before all newlines in a string PHP function
nl2br_pre Same as nl2br , but keeps line breaks in
tagsstrtolower Make a string lowercase PHP function
utf8_strtolower Unicode-aware lowercase conversion
strtoupper Make a string uppercase PHP function
utf8_strtoupper Unicode-aware uppercase conversion
ucfirst Make a string's first character uppercase PHP function
lcfirst Make a string's first character lowercase PHP function
ucwords Uppercase the first character of each word in a string PHP function
trim Strip whitespace from the beginning and end of a string PHP function
rtrim Strip whitespace from the end of a string PHP function
ltrim Strip whitespace from the beginning of a string PHP function
utf8_romanize Romanize the output
strrev Reverse a string PHP function
encodeEmail Encode email addresses in the output see String::encodeEmail
decodeEntities Decodes HTML entities in the output see String::decodeEntities()
number_format Formats a number (without decimal places) see System::getFormattedNumber()
currency_format Formats a currency (two decimal places) see System::getFormattedNumber()
readable_size Convert file sizes to human readable format see System::getReadableSize()
Insert tags 58 Manual for Contao 3.2
System administration
The following chapters explain how to administrate Contao. Besides installing and updating the application, an administrator is responsible for creating users and groups, managing additional modules and maintaining the system.
System administration 59 Manual for Contao 3.2
Users and groups
Contao distinguishes between back end users ("users"), who can log into the administration area, and front end users ("members"), who can log into the website. Unlike administrators, who have access to all pages and elements by default ("allow all"), regular users cannot access any resource that has not been explicitly allowed in their profile or in the profile of one of the groups they belong to ("deny all").
Users
Each user can be associated with multiple groups and automatically inherits their permissions. All permissions are additive, which means that a user inherits the sum of permissions of all groups he belongs to. If group A grants a certain right, you cannot revoke it in group B.
Pagemounts
Pagemounts define which pages of the site structure a user is allowed to see. The screenshot below shows the site structure in the view of Helen Lewis. Although the website contains a lot more pages, she can only see three, because only the "Courses" page has been mounted in the settings of the "Editors" group. Note that although Helen Lewis is allowed to see three pages, she can only edit one of them!
Being able to see a page does not include the right to edit it (or its articles). Remember that page permissions are set in the site structure, so to enable a page for a user, you have to mount it in his profile and grant access to it in the site structure.
Filemounts
Similar to pagemounts, filemounts define which folders a user is allowed to see. Below is a screenshot of the file manager in the view of Helen Lewis. She is only allowed to see the "campus" folder, whereas administrators can see the whole files directory ( files ).
Users and groups 60 Manual for Contao 3.2
Allowed fields
As mentioned at the beginning, regular users do not have any default permissions at all ("deny all"), which also implies that they cannot access any form fields. Even if they are e.g. allowed to access the news module, the form to create a new entry will be empty until the administrator enables one or more fields of the tl_news table in the group settings.
Members
Users and groups 61 Manual for Contao 3.2
Managing members (front end users) is a lot easier than managing back end users, because there are no pagemounts or allowed fields. Member management is mainly required to control access to protected pages, which is implemented on group level. Depending on the website configuration, registered members will be able to see protected pages or access protected downloads that are not available to guests.
Users and groups 62 Manual for Contao 3.2
Extensions
Extensions are an essential part of Contao, because they allow you to add extra functionality. There are more than 1,400 extensions available in the Contao Extension Repository, which you can browse directly in the back end. Communication with the repository server is done via SOAP, so you need to enable the PHP SOAP extension to use the service (if not enabled by default).
Extension catalog
The "extension catalog" module allows you to browse the extension list and to install extensions at the push of a button. Use the filter and sorting options to find a particular extension and click the info icon or extension title to open the details page and install the module.
The details page contains a description of the extension and important information regarding system requirements, versions and dependencies from other modules. Click the "Install" button to download and install the extension.
Extensions 63 Manual for Contao 3.2
Contao will automatically download and install the extension and update the database if necessary.
Extensions 64 Manual for Contao 3.2
Extension manager
The "extension manager" module allows you to update and uninstall extensions. It automatically checks for updates and notifies you if a new version is available. Many extensions also include links to an online manual and/or forum thread where you can get support.
To uninstall an extension, simply click the uninstall icon and follow the instructions. The extension manager will remove all files and folders and update the database if necessary. Note that this action cannot be undone and the tables cannot be restored!
Extensions 65 Manual for Contao 3.2
Manual installation
In case the PHP SOAP extension is not available on your server, you can also install Contao extensions manually. Find the respective module in the extension list and download the .zip archive of the latest release. Then unzip the files and copy them to your local or remote Contao directory. Finally, check the database with the Contao install tool.
Extensions 66 Manual for Contao 3.2
Maintenance
Most of the maintenance jobs in Contao are executed automatically by the Periodic Command Scheduler, so you can focus on your actual work. Even the tasks in the maintenance module are carried out automatically, however sometimes it is necessary to trigger them manually.
Purging data
Besides the user generated content, Contao stores a lot of system data which is used to restore deleted records, revert back to prior versions, search the website or decrease the page loading time. You can purge this data manually e.g. to remove old thumbnails from the image cache or to recreate the XML sitemap files after you have modified the site structure.
Rebuilding the search index
Pages are usually added to the search index automatically when they are viewed in the front end (unless you are logged into the back end at the same time), so you do not need to worry about the search index. However if you have changed a large number of pages, it is more convenient to update them all at once instead of opening them one by one in the browser. In this case you can rebuild the search index manually.
Maintenance 67 Manual for Contao 3.2
Maintenance 68 Manual for Contao 3.2
Data Container Arrays
Data Container Arrays (DCAs) are used to store table meta data. Each DCA describes a particular table in terms of its configuration, its relations to other tables and its fields. The Contao core engine determines by this meta data how to list records, how to render back end forms and how to save data. The DCA files of all active module are loaded one after the other (starting with "backend" and "frontend" and then in alphabetical order), so that every module can override the existing configuration. The system/config/dcaconfig.php file is included at the end.
Data Container Arrays 69 Manual for Contao 3.2
Reference
A Data Container Array is devided into six sections. The first section stores the general table configuration like relations to other tables. The second and third section determine how records are listed and which operations a user is allowed to execute. The fourth section defines different groups of form fields which are called "palettes" and the last two sections describe the input fields in detail.
Table configuration
The table configuration describes the table itself, e.g. which type of data container is used to store the data or how it relates to other tables. Also you can enable versioning or define what happens to child records when data is being edited or deleted.
Key Value Description
&$GLOBALS['TL_LANG'] The label is used with page or file trees and typically includes label ( string ) reference to the language array.
Parent table ptable Name of the related parent table (table.pid = ptable.id). ( string )
ctable Child tables ( array ) Name of the related child tables (table.id = ctable.pid).
Data Container Table (database table), File (local configuration file) or Folder (file dataContainer ( string ) manager).
closed true/false ( boolean ) If true, you cannot add further records to the table.
notEditable true/false ( boolean ) If true, the table cannot be edited.
notDeletable true/false ( boolean ) If true, records in the table cannot be deleted.
notSortable true/false ( boolean ) If true, records in the table cannot be sorted.
notCopyable true/false ( boolean ) If true, records in the table cannot be duplicated.
If true, records in the table cannot be created but can be notCreatable true/false ( boolean ) duplicated.
Activates the "save and edit" button when a new record is added switchToEdit true/false ( boolean ) (sorting mode 4 only).
If true, Contao saves the old version of a record when a new enableVersioning true/false ( boolean ) version is created.
If true, Contao will not duplicate records of the current table when doNotCopyRecords true/false ( boolean ) a record of its parent table is duplicated.
If true, Contao will not delete records of the current table when a doNotDeleteRecords true/false ( boolean ) record of its parent table is deleted.
Callback function Calls a custom function when a DataContainer is initialized and onload_callback ( array ) passes the DataContainer object as argument.
Callback function Calls a custom function after a record has been updated and onsubmit_callback ( array ) passes the DataContainer object as argument.
Callback function Calls a custom function when a record is deleted and passes the ondelete_callback ( array ) DataContainer object as argument.
Callback function Calls a custom function when a record is moved and passes the oncut_callback ( array ) DataContainer object as argument. Added in version 2.8.2.
Calls a custom function when a record is duplicated and passes Callback function oncopy_callback the insert ID and the DataContainer object as argument. Added ( array ) in version 2.8.2.
Reference 70 Manual for Contao 3.2
Calls a custom function when a new version of a record is Callback function onversion_callback created and passes the table, the insert ID and the ( array ) DataContainer object as argument.
Calls a custom function when a version of a record is restored Callback function onrestore_callback and passes the insert ID, the table, the data array and the ( array ) version as argument.
Table configuration sql Describes table configuration, e.g. 'keys' => array ( 'id' => ( array ) 'primary', 'pid' => 'index' )
Listing records
The listing array defines how records are listed. The Contao core engine supports three different views: "list view", "parent view" and "tree view". You can configure various sorting options like filters or the default sorting order and you can add custom labels.
Sorting
Key Value Description
0 Records are not sorted 1 Records are sorted by a fixed field 2 Records are sorted by a switchable field 3 Records are sorted by the parent table Sorting mode mode 4 Displays the child records of a parent record (see style sheets ( integer ) module) 5 Records are displayed as tree (see site structure) 6 Displays the child records within a tree structure (see articles module)
1 Sort by initial letter ascending 2 Sort by initial letter descending 3 Sort by initial two letters ascending 4 Sort by initial two letters descending 5 Sort by day ascending Sorting flag 6 Sort by day descending flag ( integer ) 7 Sort by month ascending 8 Sort by month descending 9 Sort by year ascending 10 Sort by year descending 11 Sort ascending 12 Sort descending
search show the search records menu sort show the sort records menu filter show the filter records menu Panel layout panelLayout limit show the limit records menu. ( string ) Separate options with comma (= space) and semicolon (= new line) like sort,filter;search,limit .
Default sorting fields One or more fields that are used to sort the table. values ( array )
Header fields One or more fields that will be shown in the header element (sorting headerFields ( array ) mode 4 only).
Tree icon Path to an icon that will be shown on top of the tree (sorting mode 5 icon ( string ) and 6 only).
Root nodes IDs of the root records (pagemounts). This value usually takes care of root ( array ) itself.
Query filter Allows you to add custom filters as arrays, e.g. array('status=?', filter ( array ) 'active') .
true/false
Reference 71 Manual for Contao 3.2
( boolean )
Callback This function will be called instead of displaying the default paste paste_button_callback function buttons. Please specify as array('Class', 'Method') . ( array )
Callback This function will be called to render the child elements (sorting mode child_record_callback function 4 only). Please specify as array('Class', 'Method') . ( array )
CSS class child_record_class Allows you to add a CSS class to the parent view elements. ( string )
Labels
Key Value Description
One or more fields that will be shown in the list (e.g. array('title', fields Fields ( array ) 'user_id:tl_user.name') ).
If true Contao will generate a table header with column names (e.g. showColumns true/false ( boolean ) back end member list)
format Format string ( string ) HTML string used to format the fields that will be shown (e.g. %s ).
Number of characters maxCharacters Maximum number of characters of the label. ( integer )
Callback function Call a custom function instead of using the default group header group_callback ( array ) function.
Callback function label_callback Call a custom function instead of using the default label function. ( array )
Operations
The operations array is divided into two sections: global operations that relate to all records at once (e.g. editing multiple records) and regular operations that relate to a particular record only (e.g. editing or deleting a record).
Global operations
Key Value Description
&$GLOBALS['TL_LANG'] label Button label. Typically a reference to the global language array. ( string )
URL fragment URL fragment that is added to the URI string when the button is href ( string ) clicked (e.g. act=editAll ).
class CSS class ( string ) CSS class attribute of the button.
Additional attributes attributes Additional attributes like event handler or style definitions. ( string )
Callback function Call a custom function instead of using the default button function. button_callback ( array ) Please specify as array('Class', 'Method') .
Regular operations
Key Value Description
&$GLOBALS['TL_LANG'] label Button label. Typically a reference to the global language array. ( string )
URL fragment URL fragment that is added to the URI string when the button is href ( string )
Reference 72 Manual for Contao 3.2
href ( string ) clicked (e.g. act=edit ).
icon Icon ( string ) Path and filename of the icon.
Additional attributes attributes Additional attributes like event handler or style definitions. ( string )
Callback function Call a custom function instead of using the default button function. button_callback ( array ) Please specify as array('Class', 'Method') .
Fields
The fields array defines the columns of a table. Depending on these settings, the Contao core engine decides which type of form field to load, whether a user is allowed to access a certain field and whether a field can be used as sort or filter criteria.
Key Value Description
&$GLOBALS['TL_LANG'] label Field label. Typically a reference to the global language array. ( string )
Default value default Default value that is set when a new record is created. ( mixed )
If true the field will be excluded for non-admins. It can be enabled exclude true/false ( boolean ) in the user group module (allowed excluded fields).
If true the field will be included in the search menu (see "sorting search true/false ( boolean ) records" -> "panelLayout").
If true the field will be included in the sorting menu (see "sorting sorting true/false ( boolean ) records" -> "panelLayout").
If true the field will be included in the filter menu (see "sorting filter true/false ( boolean ) records" -> "panelLayout").
1 Sort by initial letter ascending 2 Sort by initial letter descending 3 Sort by initial X letters ascending (see length) 4 Sort by initial X letters descending (see length) 5 Sort by day ascending Sorting mode 6 Sort by day descending flag ( integer ) 7 Sort by month ascending 8 Sort by month descending 9 Sort by year ascending 10 Sort by year descending 11 Sort ascending 12 Sort descending
Sorting length Allows to specify the number of characters that are used to build length ( integer ) sorting groups (flag 3 and 4).
text Text field password Password field textarea Textarea select Drop-down menu checkbox Checkbox radio Radio button radioTable Table with images and radio buttons imageSize Two text fields with drop-down menu inputUnit Text field with small unit drop-down menu trbl Four text fields with a small unit drop-down menu inputType Field type ( string ) chmod CHMOD table pageTree Page tree fileTree File tree tableWizard Table wizard timePeriod Text field with drop-down menu listWizard List wizard optionWizard Option wizard moduleWizard Module wizard
Reference 73 Manual for Contao 3.2
options Options ( array ) Options of a drop-down menu or radio button menu.
Callback function Callback function that returns an array of options. Please specify options_callback ( array ) as array('Class', 'Method') .
Get options from a database table. Returns ID as key and the field foreignKey table.field ( string ) you specify as value.
&$GLOBALS['TL_LANG'] Array that holds the options labels. Typically a reference to the reference ( string ) global language array.
&$GLOBALS['TL_LANG'] Array that holds the explanation. Typically a reference to the explanation ( string ) global language array.
Executes a custom function instead of using the default input field Callback function input_field_callback routine and passes the the DataContainer object and the label as ( array ) arguments.
Field configuration eval Various configuration options. See next paragraph. ( array )
Callback function Call a custom function and add its return value to the input field. wizard ( array ) Please specify as array('Class', 'Method') .
Database field Describes data type and its database configuration, e.g. sql definition ( string ) varchar(255) NOT NULL default ''
Configuration of relation Describes relation to parent table (see paragraph "relations"). relations ( array )
These functions will be called when the field is loaded. Please Callback functions specify each callback function as array('Class', 'Method') . load_callback ( array ) Passes the field's value and the data container as arguments. Expects the field value as return value.
These functions will be called when the field is saved. Please specify each callback function as array('Class', 'Method') . Callback functions save_callback Passes the field's value and the data container as arguments. ( array ) Expects the field value as return value. Throw an exception to display an error message.
Evaluation
The evaluation array configures a particular field in detail. You can e.g. create mandatory fields, add a date picker or define the rows and columns of a textarea. You can also modify the field appearance or enable data encryption. Each field can be validated against a regular expression.
Key Value Description
true/false helpwizard If true the helpwizard icon will appear next to the field label. ( boolean )
true/false mandatory If true the field cannot be empty. ( boolean )
Maximum maxlength length Maximum number of characters that is allowed in the current field. ( integer )
Minimum minlength length Minimum number of characters that have to be entered. ( integer )
true/false fallback If true the field can only be assigned once per table. ( boolean )
alias expects a valid alias
allows alphanumeric characters only (including full
Reference 74 Manual for Contao 3.2
alnum allows alphanumeric characters only (including full stop [.] minus [-], underscore [_] and space [ ])
allows alphabetic characters only (including full stop alpha [.] minus [-] and space [ ])
date expects a valid date
datim expects a valid date and time
allows numeric characters only (including full stop [.] digit and minus [-])
email expects a valid e-mail address
emails expects a valid list of valid e-mail addresses Regular extnd disallows #&()/<=> rgxp expression ( string ) folderalias expects a valid folder URL alias
expects a valid "friendly name format" e-mail friendly address
language expects a valid language code
locale expects a valid locale (e.g. "de-CH")
expects a valid phone number (numeric characters, phone space [ ], plus [+], minus [-], parentheses [()] and slash [/])
prcnt allows numbers between 0 and 100
url expects a valid URL
time expects a valid time
Columns cols Number of columns (textarea fields only). ( integer )
Rows rows Number of rows (textarea fields only). ( integer )
true/false Make the input field multiple. Applies to text fields, select menus, radio multiple ( boolean ) buttons and checkboxes. Required for the checkbox wizard.
Size size Size of a multiple select menu or number of input fields. ( integer )
Style style attributes Style attributes (e.g. border:2px ). ( string )
Rich text tinyMCE use file config/tinyMCE.php . rte editor file tinyFlash use file config/tinyFlash.php . ( string ) You can add your own configuration files too.
true/false submitOnChange If true the form will be submitted when the field value changes. ( boolean )
true/false nospace If true whitespace characters will not be allowed. ( boolean )
true/false allowHtml If true the current field will accept HTML input. ( boolean )
true/false preserveTags If true no HTML tags will be removed at all. ( boolean )
true/false If true HTML entities will be decoded. Note that HTML entities are always decodeEntities ( boolean ) decoded if allowHtml is true.
Reference 75 Manual for Contao 3.2
doNotSaveEmpty true/false If true the field will not be saved if it is empty. ( boolean )
true/false If true the field will always be saved, even if its value has not changed. alwaysSave ( boolean ) This can be useful in conjunction with a load_callback.
true/false spaceToUnderscore If true any whitespace character will be replaced by an underscore. ( boolean )
true/false unique If true the field value cannot be saved if it exists already. ( boolean )
true/false encrypt If true the field value will be stored encrypted. ( boolean )
true/false If true a trailing slash will be added to the field value. If false, an existing trailingSlash ( boolean ) trailing slash will be removed from the field value.
true/false If true files and folders will be shown. If false, only folders will be shown. files ( boolean ) Applies to file trees only.
true/false Removes the radio buttons or checkboxes next to folders. Applies to file filesOnly ( boolean ) trees only.
File Limits the file tree to certain file types (comma separated list). Applies to extensions extensions file trees only. ( string )
Path path Custom root directory for file trees. Applies to file trees only. ( string )
Input field checkbox allow multiple selections fieldType type radio allow a single selection only ( string ) Applies to file and page trees only.
true/false If true a blank option will be added to the options array. Applies to drop- includeBlankOption ( boolean ) down menus only.
Label blankOptionLabel Label for the blank option (defaults to - ). ( string )
true/false chosen Native selects enhanced with Chosen. ( boolean )
true/false findInSet Sort by the actual option values instead of their labels. ( boolean )
true/false datepicker If true the current field has a date picker. ( boolean )
true/false colorpicker If true the current field has a color picker. ( boolean )
true/false If true the current field can be edited in the front end. Applies to table feEditable ( boolean ) tl_member only.
personal personal data address address details Group name feGroup contact contact details ( string ) login login details (table tl_member only) You can also define your own groups.
true/false feViewable If true the current field is viewable in the member listing module. ( boolean )
true/false doNotCopy If true the current field will not be duplicated if the record is duplicated. ( boolean )
true/false If true the field value will be hidden (it is still visible in the page source hideInput ( boolean ) though!).
true/false If true the current field will not be shown in "edit all" or "show details" doNotShow ( boolean ) mode.
Reference 76 Manual for Contao 3.2
true/false isBoolean Indicates that a particular field is boolean. ( boolean )
true/false disabled Disables the field (not supported by all field types). ( boolean )
true/false readonly Makes the field read only (not supported by all field types). ( boolean )
Delimiter The choice of this field will not be stored as serialized string but rather as csv ( string ) given delimiter-separated list. Example: 'eval' => array('csv'=>',')
Relations
Relations describe, how database fields are related to other tables. Define the referenced table in the foreignKey key. Relations provide model classes to load referenced data sets efficiently and developer friendly. (see Model::getRelated() ).
Key Value Description
hasOne Value references a child data set Type of relation hasMany Value references some child data sets (serialized) type ( string ) belongsTo Value references a parent data set (e.g. pid ) belongsToMany Value references some parent data sets (serialized)
Load behaviour lazy Loading referenced records only when necessary (default, saves RAM) load ( string ) eager Loading referenced records automatically (saves database calls)
Reference 77 Manual for Contao 3.2
Palettes
A palette is a group of form fields which are required to edit a record. A palette typically does not include all columns of a table but only the ones that belong to a particular module or content element. Palettes can change dynamically depending on the user's permissions or type of element and certain subparts of the form (called subpalettes) can be loaded interactively via Ajax.
Defining groups
A palette is a string of field names which are concatenated with either a semicolon (;) or a comma (,). Whereas the comma is just used to separate the field names, the semicolon indicates the beginning of a new fieldset, which can be expanded and collapsed.
The above example is defined by the following code:
Palettes 78 Manual for Contao 3.2
{title_legend},headline,alias,author;{date_legend},date,time;{teaser_legend:hide},subheadline,teaser
The title_legend and date_legend placeholders will be replaced with the corresponding labels from the "TL_LANG" array.
$GLOBALS['TL_LANG']['tl_news']['title_legend'] = 'Title and author'; $GLOBALS['TL_LANG']['tl_news']['date_legend'] = 'Date and time';
Arranging fields
The Contao back end uses a simple two-column grid system to arrange input fields within their groups. You can apply the following CSS classes in the evaluation section of the Data Container Array as tl_class (e.g. 'tl_class'=>'w50 wizard' ).
tl_class Description
w50 Set the field width to 50% and float it ( float:left ).
clr Clear all floats ( clear:both ).
wizard Shorten the input field so there is enough room for the wizard button (e.g. date picker fields).
long Make the text input field span two columns.
m12 Add a 12 pixels top margin to the element (used for single checkboxes).
Palettes 79 Manual for Contao 3.2
Callbacks
Callback functions are based on the event dispatcher pattern. You can register one or more callbacks for a certain event and when the event is triggered, the callback functions are being executed. Callbacks allow you to customize the program flow of the Contao core engine.
Global callbacks
Callback Description
Is executed when the DataContainer object is initialized. Allows you to e.g. check permissions onload_callback or to modify the Data Container Array dynamically at runtime.
Is executed when a back end form is submitted. Allows you to e.g. modify the form data before onsubmit_callback it is written to the database (used to calculate intervals in the calendar extension).
ondelete_callback Is executed before a record is removed from the database.
oncut_callback Is executed after a record has been moved to a new position.
oncopy_callback Is executed after a record has been duplicated.
Listing callbacks
Callback Description
Allows for individual paste buttons and is e.g. used in the site structure to disable buttons paste_button_callback depending on the user's permissions (requires an additional command check via load_callback).
child_record_callback Defines how child elements are rendered in "parent view".
group_callback Allows for individual group headers in the listing.
Allows for individual labels in the listing and is e.g. used in the user module to add status label_callback icons.
Operations callbacks
Callback Description
Allows for individual navigation icons and is e.g. used in the site structure to disable buttons button_callback depending on the user's permissions (requires an additional command check via load_callback).
Field callbacks
Callback Description
Allows you to define an individual function to load data into a drop-down menu or checkbox options_callback list. Useful e.g. for conditional foreinKey-relations.
Allows for the creation of individual form fields and is e.g. used in the back end module input_field_callback "personal data" to generate the "purge data" widget. Attention: the field is not saved automatically!
load_callback Is executed when a form field is initialized and can e.g. be used to load a default value.
Is executed when a field is submitted and can e.g. be used to add an individual validation save_callback routine.
Callbacks 80 Manual for Contao 3.2
Customizing Contao
Customizability is one of the most important features of any application and particularly Content Management Systems. Contao provides many options to adjust the configuration, customize fields and labels, add own code snippets or even create new extensions. You can control almost any behaviour of the Contao core without even touching its files, so you do not have to reapply your changes after every update.
Customizing Contao 81 Manual for Contao 3.2
Bypass the internal cache
Before developing extensions for Contao, you should bypass the internal cache. If you want to bypass the internal cache, navigate to "System" -> "Settings" and enable the checkbox "Bypass the internal cache" under "Global configuration".
As soon as the site goes into production, you should uncheck "Bypass the internal cache" in order to minimize the response time.
Bypass the internal cache 82 Manual for Contao 3.2
Custom configurations
The Contao configuration is stored in one big array that is divided into three sections: the system configuration, the data container configuration and the language configuration. The configuration array is built at run-time and contains only those parts that are required to generate a certain page. Contao does not waste time and memory parsing a lot of redundant configuration files.
Customizing the system configuration
The system configuration is stored in the config.php files of the various Contao modules. If you want to customize it, apply your changes to the system/config/localconfig.php file, so they will not be overridden on the next update. Most parameters can be set in the back end in the settings module and will be written to the local configuration file automatically, so you hardly ever need to edit it manually.
// Disable the extension creator unset($GLOBALS['BE_MOD']['devtools']['extension']);
### INSTALL SCRIPT START ### $GLOBALS['TL_CONFIG']['debugMode'] = false; $GLOBALS['TL_CONFIG']['displayErrors'] = false;
Make sure to store your changes above the INSTALL SCRIPT START line, otherwise they will be removed by the settings module. And never use the config.php file to store configuration parameters, because this file might be overridden on updates!
Customizing the data container configuration
Contao uses Data Container Arrays to store table meta information. The data container configuration is stored in the dca folders of the various Contao modules. Apply your changes to the system/config/dcaconfig.php file so they will not be overridden on the next update.
// Make company a mandatory field in the members table $GLOBALS['TL_DCA']['tl_member']['fields']['company']['eval']['mandatory'] = true;
// Make sure that company names consist of alphanumeric characters only $GLOBALS['TL_DCA']['tl_member']['fields']['company']['eval']['rgxp'] = 'alnum';
// Allow only admins to use include content elements if (!BackendUser::getInstance()->isAdmin) { unset($GLOBALS['TL_CTE']['includes']); }
As you see, the dcaconfig.php file is a good place to store minor modifications to the Contao configuration. If you need to make a lot of changes, you should consider encapsulating them in a custom extension so you do not lose track.
Customizing labels and translations
Labels and translations are stored in the languages folders of the various Contao modules. Each language is identified by its ISO-639-1 language code. Apply your changes to the system/config/langconfig.php file so they will not be overridden on the next update.
// Change a label for all languages
Custom configurations 83 Manual for Contao 3.2
$GLOBALS['TL_LANG']['MSC']['goBack'] = '«';
// Change a label for a particular language only if ($GLOBALS['TL_LANGUAGE'] == 'de') { $GLOBALS['TL_LANG']['tl_layout']['column'] = 'Bereich'; } elseif ($GLOBALS['TL_LANGUAGE'] == 'fr') { $GLOBALS['TL_LANG']['tl_layout']['column'] = 'Section'; }
Of course changes to the language array can also be encapsulated in a custom module, which is recommended if there are a lot of them.
Custom configurations 84 Manual for Contao 3.2
Adding custom fields
Let us assume that you want to add a customer number to the members table. Adding a custom field to a Contao table requires to change more than just one file, therefore it is recommended to create a custom module in the system/modules directory. Remember that modules are loaded in alphabetical order, so do not name your extension custom if you want to override settings of the news extension.
Extending the DCA
Create the file dca/tl_member.php in your module folder and add the meta data for the new field so Contao knows how to handle it.
Since Contao 3 you can also specify directly the corresponding fields and their configuration for the database in the DCA under sql . The SQL details are not sent to the database but they are used to calculate the difference between the Contao specifications and the actual database tables.
// Modify the palette $GLOBALS['TL_DCA']['tl_member']['palettes']['default'] = str_replace ( 'company', 'customer_number,company', $GLOBALS['TL_DCA']['tl_member']['palettes']['default'] );
// Add the field meta data $GLOBALS['TL_DCA']['tl_member']['fields']['customer_number'] = array ( 'label' => &$GLOBALS['TL_LANG']['tl_member']['customer_number'], 'exclude' => true, 'inputType' => 'text', 'eval' => array('mandatory'=>true, 'rgxp'=>'digit', 'maxlength'=>8), 'sql' => "varchar(8) NOT NULL default ''" );
If you do not understand the code above, you might want to read the chapter on Data Container Arrays.
After adding or modifying a field in the DCA you should visit the Contao install tool in order to update your database tables.
Adding a translation
Create the file languages/en/tl_member.php in your module folder and add the English labels for the new field:
$GLOBALS['TL_LANG']['tl_member']['customer_number'] = array ( 'Customer number', 'Please enter the 8-digit customer number.' );
Now you can enter a customer number in the "members" module which can contain up to 8 digits. If the field is left blank or contains any non-digit characters, Contao will not save the value and show an error message instead.
Adding custom fields 85 Manual for Contao 3.2
Customizing TinyMCE
This page explains how to customize the Rich Text Editor and save the changes so they will not be overridden on the next Contao update. Note that Contao does not include all TinyMCE plugins by default, so if you want to use a certain plugin that is not part of the Contao distribution, download it from the TinyMCE project website and move it into the assets/tinymce/plugins folder.
The image above shows the default Rich Text Editor configuration file system/config/tinyMCE.php . To create a custom configuration file, simply copy it and rename it e.g. to tinyCustom.php . Then apply your changes and save the new file. The last step is to adjust the data container configuration in the system/config/dcaconfig.php file and tell Contao to which fields the custom file shall be applied.
// Use the custom RTE configuration for text elements $GLOBALS['TL_DCA']['tl_content']['fields']['text']['eval']['rte'] = 'tinyCustom';
Customizing TinyMCE 86 Manual for Contao 3.2
Overriding class methods
Let us assume that you want to modify the behaviour of the navigation module to always display even if there are no sub- pages and the module would not be shown at all. In this case a note shall be printed to inform the user that there are no sub-pages. Of course we will try to preserve as much of the original navigation class as possible, so future updates do not require maintenance. Module and content element classes can be assigned dynamically in the Contao system configuration, which allows you to easily replace them with your own versions.
Creating a custom class
The default navigation class behaves pretty much like we want it to, except that the generate() method hides the module if there are no sub-pages. Therefore all we need to change is this particular method, so the best practice is to extend the original class and simply override it. To do so, create a new xcustom/ModuleMyNavigation.php file and define the custom class ModuleMyNavigation :
// xcustom/ModuleMyNavigation.php class ModuleMyNavigation extends ModuleNavigation { public function generate() { // Execute the original method $buffer = parent::generate();
if (empty($buffer)) { $buffer = 'There are no subpages'; }
return $buffer; } }
Registering a custom class
Module and content element classes can be assigned dynamically in the Contao system configuration, which allows you to easily replace them with your own versions. The names of the module classes are stored in the global FE_MOD array.
// xcustom/config/config.php $GLOBALS['FE_MOD']['navigationMenu']['navigation'] = 'ModuleMyNavigation';
Thanks to the dynamic configuration, Contao automatically loads the new class upon the next request and the navigation module prints the "There are no subpages" notice instead of not displaying at all. The modification is update-safe and does not require maintenance.
Overriding class methods 87 Manual for Contao 3.2
Contao hooks
Hooks work similar to the callback functions of the Data Container Array. You can register one or more functions for a certain event and when the event is triggered, the callback functions are executed. Hooks allow you to add custom functionality to the core. activateAccount
The "activateAccount" hook is triggered when a new front end account is activated. It passes the user object as argument and does not expect a return value. It is available from version 2.4.3.
// config.php $GLOBALS['TL_HOOKS']['activateAccount'][] = array('MyClass', 'myActivateAccount');
// MyClass.php public function myActivateAccount(Database_Result $objUser) { // Do something } activateRecipient
The "activateRecipient" hook is triggered when a new newsletter recipient is added. It passes the e-mail address, the recipient IDs and the channel IDs as argument and does not expect a return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['activateRecipient'][] = array('MyClass', 'myActivateRecipient');
// MyClass.php public function myActivateRecipient($strEmail, $arrRecipients, $arrChannels) { // Do something } addComment
The "addComment" hook is triggered when a comment is added. It passes the ID of the record and the data array as arguments and does not expect a return value. It is available from version 2.8.2.
// config.php $GLOBALS['TL_HOOKS']['addComment'][] = array('MyClass', 'myAddComment');
// MyClass.php public function myAddComment($intId, $arrSet) { // Do something } addCustomRegexp
The "addCustomRegexp" hook is triggered when an unknown regular expression is found. It passes the name of the regexp, the current value and the widget object as arguments and expects a boolean return value. It is available from version 2.6.2.
Contao hooks 88 Manual for Contao 3.2
// config.php $GLOBALS['TL_HOOKS']['addCustomRegexp'][] = array('MyClass', 'myAddCustomRegexp');
// MyClass.php public function myAddCustomRegexp($strRegexp, $varValue, Widget $objWidget) { if ($strRegexp == 'postal') { if (!preg_match('/^0-9{4,6}$/', $varValue)) { $objWidget->addError('Field ' . $objWidget->label . ' should be a postal code.'); }
return true; }
return false; } addLogEntry
The "addLogEntry" hook is triggered when a new log entry is added. It passes the message, the function and the action as arguments and does not expect a return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['addLogEntry'][] = array('MyClass', 'myAddLogEntry');
// MyClass.php public function myAddLogEntry($strText, $strFunction, $strAction) { // Do something } checkCredentials
The "checkCredentials" hook is triggered when a login attempt fails due to a wrong password. It passes the username and password as well as the user object as arguments and expects a boolean return value. It is available from version 2.6.0.
// config.php $GLOBALS['TL_HOOKS']['checkCredentials'][] = array('MyClass', 'myCheckCredentials');
// MyClass.php public function myCheckCredentials($strUsername, $strPassword, User $objUser) { // Check against a global database if ($this->checkGlobalDbFor($strUsername, $strPassword)) { return true; }
return false; } closeAccount
The "closeAccount" hook is triggered when a user closes his account. It passes the user ID, the operation mode and the module as arguments and does not expect a return value. It is available from version 2.8.0.
// config.php
Contao hooks 89 Manual for Contao 3.2
$GLOBALS['TL_HOOKS']['closeAccount'][] = array('MyClass', 'myCloseAccount');
// MyClass.php public function myCloseAccount($intId, $strMode, $objModule) { if ($strMode == 'close_delete') { // Do something } } compileDefinition
The "compileDefinition" hook is triggered when a format definition of a style sheet is written. It passes the configuration array as argument and expects a string as return value. It is available from version 2.9.4.
// config.php $GLOBALS['TL_HOOKS']['compileDefinition'][] = array('MyClass', 'myCompileDefinition');
// MyClass.php public function myCompileDefinition($arrRow) { if (isset($arrRow['border-radius'])) { return "\nborder-radius:" . $arrRow['border-radius'] . ";"; }
return ''; } compileFormFields
The "compileFormFields" hook is triggered before a form field is loaded. It passes an array of FormFieldModel objects, the form ID and the form object as arguments and expects the array of FormFieldModel objects as return value. With this Hook form fields can be adjusted dynamically before display. It is available from version 3.2.
// config.php $GLOBALS['TL_HOOKS']['compileFormFields'][] = array('MyClass', 'myCompileFormFields');
// MyClass.php public function myCompileFormFields($arrFields, $formId, $this) { if ($formId == 'my_form_id') { foreach ($arrFields AS $objFields) { if($objFields->name == 'my_form_field_1') { // Do something } } }
return $arrFields; } createDefinition
The "createDefinition" hook is triggered when a format definition of a style sheet is imported. It passes the key and value, the original format definition and the data array as arguments and expects an array or "false" as return value. It is available from version 2.9.4.
Contao hooks 90 Manual for Contao 3.2
// config.php $GLOBALS['TL_HOOKS']['createDefinition'][] = array('MyClass', 'myCreateDefinition');
// MyClass.php public function myCreateDefinition($strKey, $strValue, $strDefinition, $arrSet) { if ($strKey == 'border-radius') { return array('border-radius'=>$strValue); }
return false; } createNewUser
The "createNewUser" hook is triggered when a new front end user registers on the website. It passes the ID of the new user and the data array as arguments and does not expect a return value. It is available from version 2.2.0.
// config.php $GLOBALS['TL_HOOKS']['createNewUser'][] = array('MyClass', 'myCreateNewUser');
// MyClass.php public function myCreateNewUser($intId, $arrData) { // Modify the record } executePreActions
The "executePreActions" hook is triggered on Ajax requests that do not require a DCA object. It passes the name of the action as argument and does not expect a return value. It is available from version 2.6.1.
// config.php $GLOBALS['TL_HOOKS']['executePreActions'][] = array('MyClass', 'myExecutePreActions');
// MyClass.php public function myExecutePreActions($strAction) { if ($strAction == 'update') { // Do something } } executePostActions
The "executePostActions" hook is triggered on Ajax requests that require a DCA object. It passes the name of the action and the data container object as arguments and does not expect a return value. It is available from version 2.6.1.
// config.php $GLOBALS['TL_HOOKS']['executePostActions'][] = array('MyClass', 'myExecutePostActions');
// MyClass.php public function myExecutePostActions($strAction, DataContainer $dc) { if ($strAction == 'update') { // Do something } }
Contao hooks 91 Manual for Contao 3.2
generateBreadcrumb
The "generateBreadcrumb" hook allows to modify the breadcrumb navigation. It passes the navigation items and the frontend module as arguments and expects the items as return value. It is available from version 2.10.0.
// config.php $GLOBALS['TL_HOOKS']['generateBreadcrumb'][] = array('MyClass', 'myGenerateBreadcrumb');
// MyClass.php public function myGenerateBreadcrumb($arrItems, \Module $objModule) { return $arrItems; } generateFrontendUrl
The "generateFrontendUrl" hook is triggered when a front end URL is recreated. It passes the page object, the parameter string and the default URL as arguments and expects a string as return value. It is available from version 2.5.8.
// config.php $GLOBALS['TL_HOOKS']['generateFrontendUrl'][] = array('MyClass', 'myGenerateFrontendUrl');
// MyClass.php public function myGenerateFrontendUrl($arrRow, $strParams, $strUrl) { return str_replace('.html', '.xml', $strUrl); } generatePage
The "generatePage" hook is triggered before the main layout ("fe_page") is compiled. It passes the page object, the layout object and a self-reference as arguments and does not expect a return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['generatePage'][] = array('MyClass', 'myGeneratePage');
// MyClass.php public function myGeneratePage(\PageModel $objPage, \LayoutModel $objLayout, \PageRegular $objPageRegular) { // Do something } getAllEvents
The "getAllEvents" hook allows you to modify the result sets of calendar and event modules. It passes the current result set, the IDs of the parent items and the start and end time as arguments and expects a result set (array) as return value. It is available from version 2.6.4.
// config.php $GLOBALS['TL_HOOKS']['getAllEvents'][] = array('MyClass', 'myGetAllEvents');
// MyClass.php public function myGetAllEvents($arrEvents, $arrCalendars, $intStart, $intEnd, Module $objModule) { ksort($arrEvents); return $arrEvents;
Contao hooks 92 Manual for Contao 3.2
} getAttributesFromDca
The "getAttributesFromDca" hook allows you to modify form field attributes. It passes the current widget attributes and a DataContainer object as arguments and expects an array of arguments as return value. It is available from version 3.2.RC1.
// config.php $GLOBALS['TL_HOOKS']['getAttributesFromDca'][] = array('MyClass', 'myGetAttributesFromDca');
// MyClass.php public function myGetAttributesFromDca($arrAttributes, $objDca) { // Do something
return $arrAttributes; } getContentElement
The "getContentElement" hook is triggered when a content element is rendered. It passes the database object and the buffer string as arguments and expects a buffer string as return value. It is available from version 2.9.0.
// config.php $GLOBALS['TL_HOOKS']['getContentElement'][] = array('MyClass', 'myGetContentElement');
// MyClass.php public function myGetContentElement(Database_Result $objElement, $strBuffer) { return $strBuffer; } getImage
The "getImage" hook is triggered when a thumbnail is generated and allows you to add a custom routine. It passes the path, the width and height, the mode, the cache name and the file object as arguments and expects a path as return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['getImage'][] = array('MyClass', 'myGetImage');
// MyClass.php public function myGetImage($image, $width, $height, $mode, $strCacheName, $objFile) { return MyImage::generateThumbnail($image, $widht, $height, $mode); } getPageIdFromUrl
The "getPageIdFromUrl" hook is triggered when the URL fragments are evaluated. It passes the array of URL fragments as argument and expects an array of URL fragments as return value. It is available from version 2.5.4.
// config.php $GLOBALS['TL_HOOKS']['getPageIdFromUrl'][] = array('MyClass', 'myGetPageIdFromUrl');
// MyClass.php
Contao hooks 93 Manual for Contao 3.2
public function myGetPageIdFromUrl($arrFragments) { return array_unique($arrFragments); } getPageLayout
The "getPageLayout" hook is executed before initializing the frontend template. It passes the page model, the layout object and a reference to the page object and does not expect a return value. It is available from version 3.1.0.
// config.php $GLOBALS['TL_HOOKS']['getPageLayout'][] = array('MyClass', 'mygetPageLayout');
// MyClass.php public function mygetPageLayout(\PageModel $objPage, \LayoutModel $objLayout, \PageRegular $objPageRegular) { // Do something } getSearchablePages
The "getSearchablePages" hook is triggered when the the search index is rebuilt. It passes the array of pages and the ID of the root page as arguments and expects an array of absolute URLs (!) as return value. It is available from version 2.2.0.
// config.php $GLOBALS['TL_HOOKS']['getSearchablePages'][] = array('MyClass', 'myGetSearchablePages');
// MyClass.php public function myGetSearchablePages($arrPages, $intRoot) { return array_merge($arrPages, array('Additional pages')); } initializeSystem
The "initializeSystem" hook is triggered when the system is initialized. It is available from version 3.1.RC1.
// config.php $GLOBALS['TL_HOOKS']['initializeSystem'][] = array('MyClass', 'myInitializeSystem');
// MyClass.php public function myInitializeSystem() { // Do something } importUser
The "importUser" hook is triggered when a username cannot be found in the database. It passes the username, the password and the table name as arguments and expects a boolean return value. It is available from version 2.7.RC1.
// config.php $GLOBALS['TL_HOOKS']['importUser'][] = array('MyClass', 'myImportUser');
// MyClass.php public function myImportUser($strUsername, $strPassword, $strTable) { if ($strTable == 'tl_member')
Contao hooks 94 Manual for Contao 3.2
{ // Import user from an LDAP server if ($this->importUserFromLdap($strUsername, $strPassword)) { return true; } }
return false; } isVisibleElement
The "isVisibleElement" hook is triggered when checking if an element should be visible in the front end or not. An "element" in this case means either an article, a front end module or a content element. In contrast to the other three hooks "getArticle", "getFrontendModule" and "getContentElement" one can prevent generating the complete markup. The hook passes the model of the instance and the current visibility state as arguments and expects the new visibility state as return value. Available from version 3.2.RC1.
// config.php $GLOBALS['TL_HOOKS']['isVisibleElement'][] = array('MyClass', 'myIsVisibleElement');
// MyClass.php public function myIsVisibleElement($objElement, $blnIsVisible) { if ($objElement instanceof ContentElement) { // Check if this content element can be shown if ($this->myElementCanBeShownInFrontend($objElement)) { return true; } }
// Otherwise we don't want to change the visibility state return $blnIsVisible; } listComments
The "listComments" hook is triggered when comments are listed in the back end. It passes the current record as argument and expects a string as return value. It is available from version 2.8.RC2.
// config.php $GLOBALS['TL_HOOKS']['listComments'][] = array('MyClass', 'myListComments');
// MyClass.php public function myListComments($arrRow) { return '' . $arrRow['title'] . ''; } loadFormField
The "loadFormField" hook is triggered when a form field is loaded. It passes the widget object, the form ID and the form data as arguments and expects a widget object as return value. It is available from version 2.5.0.
// config.php $GLOBALS['TL_HOOKS']['loadFormField'][] = array('MyClass', 'myLoadFormField');
// MyClass.php
Contao hooks 95 Manual for Contao 3.2
public function myLoadFormField(Widget $objWidget, $strForm, $arrForm) { $objWidget->class = 'myclass'; return $objWidget; } loadDataContainer
The "loadDataContainer" hook is triggered when a DCA file is loaded. It passes the file name as argument and does not expect a return value. It is available from version 2.8.2.
// config.php $GLOBALS['TL_HOOKS']['loadDataContainer'][] = array('MyClass', 'myLoadDataContainer');
// MyClass.php public function myLoadDataContainer($strName) { // Do something } loadLanguageFile
The "loadLanguageFile" hook is triggered when a language file is loaded. It passes the file name and the language as arguments and does not expect a return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['loadLanguageFile'][] = array('MyClass', 'myLoadLanguageFile');
// MyClass.php public function myLoadLanguageFile($strName, $strLanguage) { // Do something } outputBackendTemplate
The "outputBackendTemplate" hook is triggered when a back end template is printed to the screen. It passes the template content and the template name as arguments and expects the template content as return value. It is available from version 2.6.0.
// config.php $GLOBALS['TL_HOOKS']['outputBackendTemplate'][] = array('MyClass', 'myOutputBackendTemplate');
// MyClass.php public function myOutputBackendTemplate($strContent, $strTemplate) { if ($strTemplate == 'be_main') { // Modify output }
return $strContent; } outputFrontendTemplate
The "outputFrontendTemplate" hook is triggered when a front end template is printed to the screen. It passes the template content and the template name as arguments and expects the template content as return value. It is available from version
Contao hooks 96 Manual for Contao 3.2
2.6.0.
// config.php $GLOBALS['TL_HOOKS']['outputFrontendTemplate'][] = array('MyClass', 'myOutputFrontendTemplate');
// MyClass.php public function myOutputFrontendTemplate($strContent, $strTemplate) { if ($strTemplate == 'fe_page') { // Modify output }
return $strContent; } parseBackendTemplate
The "parseBackendTemplate" hook is triggered when a back end template is parsed. It passes the template content and the template name as arguments and expects the template content as return value. It is available from version 2.6.0.
// config.php $GLOBALS['TL_HOOKS']['parseBackendTemplate'][] = array('MyClass', 'myParseBackendTemplate');
// MyClass.php public function myParseBackendTemplate($strContent, $strTemplate) { if ($strTemplate == 'be_main') { // Modify output }
return $strContent; } parseFrontendTemplate
The "parseFrontendTemplate" hook is triggered when a front end template is parsed. It passes the template content and the template name as arguments and expects the template content as return value. It is available from version 2.6.0.
// config.php $GLOBALS['TL_HOOKS']['parseFrontendTemplate'][] = array('MyClass', 'myParseFrontendTemplate');
// MyClass.php public function myParseFrontendTemplate($strContent, $strTemplate) { if ($strTemplate == 'ce_text') { // Modify output }
return $strContent; } parseTemplate
The parseTemplate hook is called before the parsing process of a template. It receives a Template instance (can be FrontendTemplate or BackendTemplate ) as the only parameter and does not expect any return value. Added in version 2.10.0.
Contao hooks 97 Manual for Contao 3.2
// config.php $GLOBALS['TL_HOOKS']['parseTemplate'][] = array('MyClass', 'myParseTemplate');
// MyClass.php public function myParseTemplate($objTemplate) { if ($objTemplate->getName() == 'mod_html') { // Modify object } } postDownload
The "postDownload" hook is triggered after a file has been downloaded with the download(s) element. It passes the file name as argument and does not expect a return value. It is available from version 2.4.6.
// config.php $GLOBALS['TL_HOOKS']['postDownload'][] = array('MyClass', 'myPostDownload');
// MyClass.php public function myPostDownload($strFile) { // Do something } postLogin
The "postLogin" hook is triggered after a front end member or back end user has logged in. It passes the user object as argument and does not expect a return value.
// config.php $GLOBALS['TL_HOOKS']['postLogin'][] = array('MyClass', 'myPostLogin');
// MyClass.php public function myPostLogin(User $objUser) { // Do something } postLogout
The "postLogout" hook is triggered after a front end member or back end user has logged out. It passes the user object as argument and does not expect a return value.
// config.php $GLOBALS['TL_HOOKS']['postLogout'][] = array('MyClass', 'myPostLogout');
// MyClass.php public function myPostLogout(User $objUser) { // Do something } postUpload
The "postUpload" hook is triggered after a user has uploaded one or more file in the back end. It passes an array of filenames as argument and does not expect a return value. It is available from version 2.6.4.
Contao hooks 98 Manual for Contao 3.2
// config.php $GLOBALS['TL_HOOKS']['postUpload'][] = array('MyClass', 'myPostUpload');
// MyClass.php public function myPostUpload($arrFiles) { // Do something } prepareFormData
The "prepareFormData" hook is triggered after a form has been submitted. It passes the form data array, the form labels array and the form object as arguments and does not expect a return value. This way the data can be changed or extended, prior to execution of actions like email distribution or data storage. It is available from version 3.0.0.
// config.php $GLOBALS['TL_HOOKS']['prepareFormData'][] = array('MyClass', 'myPrepareFormData');
// MyClass.php public function myPrepareFormData(&$arrSubmitted, $arrLabels, $objForm) { // Do something } printArticleAsPdf
The "printArticleAsPdf" hook is triggered when an article is exported as PDF. It passes the article text and the article object as arguments and does not expect a return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['printArticleAsPdf'][] = array('MyClass', 'myPrintArticleAsPdf');
// MyClass.php public function myPrintArticleAsPdf($strArticle, Database_Result $objArticle) { // Do something exit; } processFormData
The "processFormData" hook is triggered after a form has been submitted. It passes the form data array, the Data Container Array and the files array as arguments and does not expect a return value. It is available from version 2.4.4.
// config.php $GLOBALS['TL_HOOKS']['processFormData'][] = array('MyClass', 'myProcessFormData');
// MyClass.php public function myProcessFormData($arrPost, $arrForm, $arrFiles) { // Do something } removeOldFeeds
The "removeOldFeeds" hook is triggered when old XML files are being removed from the Contao directory. It does not pass an argument and expects an array of file names to preserve as return value. It is available from version 2.5.8.
Contao hooks 99 Manual for Contao 3.2
// config.php $GLOBALS['TL_HOOKS']['removeOldFeeds'][] = array('MyClass', 'myRemoveOldFeeds');
// MyClass.php public function myRemoveOldFeeds() { return array('custom.xml'); } removeRecipient
The "removeRecipient" hook is triggered when a newsletter recipient is removed. It passes the e-mail address and the channel IDs as argument and does not expect a return value. It is available from version 2.8.RC1.
// config.php $GLOBALS['TL_HOOKS']['removeRecipient'][] = array('MyClass', 'myRemoveRecipient');
// MyClass.php public function myRemoveRecipient($strEmail, $arrChannels) { // Do something } replaceInsertTags
The "replaceInsertTags" hook is triggered when an unknown insert tag is found. It passes the insert tag as argument and expects the replacement value or "false" as return value. It is available from version 2.6.0.
// config.php $GLOBALS['TL_HOOKS']['replaceInsertTags'][] = array('MyClass', 'myReplaceInsertTags');
// MyClass.php public function myReplaceInsertTags($strTag) { if ($strTag == 'mytag') { return 'mytag replacement'; }
return false; } reviseTable
The "reviseTable" hook is triggered when Contao removes orphan records from a table. It passes the name of the current table, the IDs of all new records, the name of the parent table and the names of all child tables as arguments and does expect a boolean return value (returning "true" will cause the current page to be reloaded). It is available from version 2.6.4.
// config.php $GLOBALS['TL_HOOKS']['reviseTable'][] = array('MyClass', 'myReviseTable');
// MyClass.php public function myReviseTable($table, $new_records, $parent_table, $child_tables) { // Do something } setNewPassword
Contao hooks 100 Manual for Contao 3.2
The "setNewPassword" hook is triggered after a new password has been set. It passes the user object and the encrypted password as arguments and does not expect a return value. It is available from version 2.2.3.
// config.php $GLOBALS['TL_HOOKS']['setNewPassword'][] = array('MyClass', 'mySetNewPassword');
// MyClass.php public function mySetNewPassword($objUser, $strPassword) { // Do something } validateFormField
The "validateFormField" hook is triggered when a form field is submitted. It passes the widget object and the form ID as arguments and expects a widget object as return value. It is available from version 2.5.0.
// config.php $GLOBALS['TL_HOOKS']['validateFormField'][] = array('MyClass', 'myValidateFormField');
// MyClass.php public function myValidateFormField(Widget $objWidget, $intId) { if ($objWidget instanceof FormPassword) { // Do something }
return $objWidget; }
Contao hooks 101 Manual for Contao 3.2
Extension Repository
To publish your own extension in the Extension Repository, you need a contributor's account. Once you are logged in, you can access the developer interface of the Extension Repository through the "Manage extensions" and "Manage translations" links.
Extension Repository 102 Manual for Contao 3.2
Adding an extension
To add a new extension, follow the "Manage extensions" link and click the "Add extension" button. You will be redirected to a form where you can enter the extension details. The yellow box above contains important information about naming conventions, which you should read carefully.
The following categories are currently available:
Category Description
Application The extension is an autonomous application.
Plugin The extension is a PHP or JavaScript library.
Theme The extension is a theme for the back end.
Utility The extension is a utility program for the back end.
Widget The extension is a form widget.
Translation The extension is a translation for a version of Contao.
Bundle A set of extensions that can be installed simultaneously.
Other The extension does not fit in any of the above categories.
Adding an extension 103 Manual for Contao 3.2
Adding a release
After you have created the extension, you can add a first release. Every new version of the extension will be stored as separate release. Open the release manager with the respective navigation icon and click the "Add release" button.
Version numbers in the Extension Repository consist of three numeric blocks that indicate the major, minor and maintenance version (e.g. 1.0.0 ) as well as a textual development status (e.g. beta1 ).
Status Description
alpha1 - alpha3 Indicates that the release is an alpha version.
beta1 - beta3 Indicates that the release is a beta version.
rc1 - rc3 Indicates that the release is a release candidate.
stable Indicates that it is a stable release for productional systems.
Adding a release 104 Manual for Contao 3.2
Adding files
Next you have to add files to the new release. Open the file manager and click the "Add/update files" button. You can upload single files or complete .zip archives. Make sure to choose the correct target directory so the file paths are correct after the upload.
Adding files 105 Manual for Contao 3.2
Adding files from a GitHub repository
The files can also be imported from a GitHub repository, if you have tagged the release and pushed the tag to the central GitHub repository.
Enter the HTTPS URL of the GitHub repository in the settings.
You can also specify the root folder name of your repository. In this case, the files and folders outside of this root folder will be ignored during the import.
If you select a tag, its files will be downloaded automatically and are then available just like after a manual upload.
Adding files from a GitHub repository 106 Manual for Contao 3.2
Adding translations
Before you can publish an extension, you have to create at least one translation. Open the translation manager and click the "Add language" button. It is recommended to always create an English translation, because back end users generally only see extensions in the extension manager which are available in their language or in English (fallback language).
Completed translations can be published by clicking the respective navigation icon.
Adding translations 107 Manual for Contao 3.2
Adding dependencies
Maybe one of your extensions uses the functionality of another one like e.g. cron jobs. To run your extension, it is therefore required to install the cron extension, which is usually referred to as dependency. Those dependencies can be stored in the Extension Repository, so all required modules are installed automatically when you install a particular extension.
First choose the extension that you want to add as dependency and confirm your choice by clicking the "Continue" button. Then select the minimum and maximum version that is known to work with your extension.
Adding dependencies 108 Manual for Contao 3.2
Publishing an extension
After you have created at least one release, uploaded at least one file, published at least one translation and added the necessary dependencies, you can publish the extension with the respective navigation icon. Note that you cannot remove the extension anymore once it has been published. To check if everything works as expected, log into the back end and make a test installation with the extension manager.
Publishing an extension 109 Manual for Contao 3.2
Contao development
The Contao development website, which is the base of the ongoing development of Contao, is available at github.com/contao. It e.g. contains a journal of past changes and future features (milestones) as well as a ticket system to report issues or request new features. It also supports browsing the Contao code repository, where you can see exactly which files have changed.
Contao development 110 Manual for Contao 3.2
Creating a new issue
First of all, please note that you have to be logged in to create new tickets. Registration on GitHub is free. Then log into your account and click "New Issue" in the main navigation.
Always describe possible problems in detail and let us know how to reproduce them in the online demo or in our development environment. If a problem occurs only in your installation but not in the online demo, please refer to the forums.
Creating a new issue 111