Manual for Contao 3.5
Total Page:16
File Type:pdf, Size:1020Kb
Table of Contents Table of contents Introduction 1.1 Installation 1.2 Installing Contao 1.2.1 Using the Safe Mode Hack 1.2.2 Manual update 1.2.3 Live Update Service 1.2.4 Moving an installation 1.2.5 Configuring the live server 1.2.6 Administration area 1.3 Listing records 1.3.1 Editing records 1.3.2 Keyboard shortcuts 1.3.3 Managing pages 1.4 Components 1.4.1 Themes 1.4.2 Style sheets 1.4.3 Modules 1.4.4 Page layouts 1.4.5 Page types 1.4.6 Managing content 1.5 Articles 1.5.1 News items 1.5.2 Events 1.5.3 RSS/Atom feed 1.5.4 Newsletters 1.5.5 Forms 1.5.6 Comments 1.5.7 Templates 1.5.8 Markdown 1.5.9 Insert tags 1.5.10 System administration 1.6 Users and groups 1.6.1 Extensions 1.6.2 Maintenance 1.6.3 1 2 Introduction Manual for Contao 3.5 This is the official manual for users and developers. You can always find the latest version on docs.contao.org. 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. 3 Installation 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. 4 Installing Contao 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). Make sure to upload the hidden .htaccess.default file and replace its name with .htaccess . Depending on your server configuration, the public folder is most likely called htdocs , httpdocs , html or public_html . If you have SSH access to your server, you can download and extract the archive directly on the command line, e.g. with curl . Depending on the version you want to install, adjust the URLs as described. Latest version of Contao (4.x): curl -L http://download.contao.org | tar -xzp LTS version of Contao (3.5): curl -L http://download.contao.org/lts | tar -xzp A specific version (e.g. 3.5.2): curl -L http://download.contao.org/3.5.2 | 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. 5 Installing Contao 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. Danger When importing a template, existing data will be replaced! 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 . 6 Using the Safe Mode Hack 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 7 Using the Safe Mode Hack 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! 8 Manual update 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 system/config/pathconfig.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! If you use the Composer client to manage your extensions, you also have to backup the folder /composer in the root directory. 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. 9 Manual update Review the options carefully and make sure to choose "Preview changes", so you can check which files will be updated.