Manual for Contao 3.4 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. Markdown x. 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 1 Manual for Contao 3.4 iv. Adding files from a GitHub repository v. Adding translations vi. Adding dependencies vii. Publishing an extension 10. Contao development i. Creating a new issue 2 Manual for Contao 3.4 Manual for Contao 3.4 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 Markdown 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 Introduction 3 Manual for Contao 3.4 Contao hooks 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.4 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.4 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.4 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.4 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.4 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.4 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.