Handbuch für Contao 3.4 Inhaltsverzeichnis 1. Einleitung 2. Installation i. Contao installieren ii. Den Safe Mode Hack verwenden iii. Manuelles Update iv. Live Update Service v. Eine Installation umziehen vi. Den Live-Server konfigurieren 3. Administrationsbereich i. Datensätze auflisten ii. Datensätze bearbeiten iii. Backend-Tastaturkürzel 4. Seiten verwalten i. Komponenten ii. Themes iii. Stylesheets iv. Module v. Seitenlayouts vi. Seitentypen 5. Inhalte verwalten i. Artikel ii. Nachrichten iii. Termine iv. RSS-/Atom-Feed v. Newsletter vi. Formulare vii. Kommentare viii. Templates ix. Markdown x. Inserttags 6. Systemadministration i. Benutzer und Gruppen ii. Erweiterungen iii. Systemwartung 7. Data Container Arrays i. Referenz ii. Paletten iii. Callbacks 8. Contao anpassen i. Internen Cache umgehen ii. Konfiguration anpassen iii. Eigene Felder hinzufügen iv. TinyMCE anpassen v. Methoden überschreiben vi. Contao-Hooks 9. Das Extension Repository i. Eine Erweiterung anlegen ii. Eine Freigabe hinzufügen iii. Die Dateien hochladen 1 Handbuch für Contao 3.4 iv. Dateien aus einem GitHub-Repository hinzufügen v. Eine Übersetzung hinzufügen vi. Abhängigkeiten speichern vii. Die Erweiterung veröffentlichen 10. Contao-Entwicklungsprozess i. Tickets erstellen 2 Handbuch für Contao 3.4 Handbuch für Contao 3.4 Dies ist das offizielle Handbuch für Anwender und Entwickler. Die neuste Version ist unter docs.contao.org erhältlich. Inhaltsverzeichnis Einleitung Installation Contao installieren Den Safe Mode Hack verwenden Manuelles Update Live Update Service Eine Installation umziehen Den Live-Server konfigurieren Administrationsbereich Datensätze auflisten Datensätze bearbeiten Backend-Tastaturkürzel Seiten verwalten Komponenten Themes Stylesheets Module Seitenlayouts Seitentypen Inhalte verwalten Artikel Nachrichten Termine RSS-/Atom-Feed Newsletter Formulare Kommentare Templates Markdown Inserttags Systemadministration Benutzer und Gruppen Erweiterungen Systemwartung Data Container Arrays Referenz Paletten Callbacks Contao anpassen Internen Cache umgehen Konfiguration anpassen Eigene Felder hinzufügen TinyMCE anpassen Methoden überschreiben Einleitung 3 Handbuch für Contao 3.4 Contao-Hooks Das Extension Repository Eine Erweiterung anlegen Eine Freigabe hinzufügen Die Dateien hochladen Dateien aus einem GitHub-Repository hinzufügen Eine Übersetzung hinzufügen Abhängigkeiten speichern Die Erweiterung veröffentlichen Contao-Entwicklungsprozess Tickets erstellen 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. Einleitung 4 Handbuch für Contao 3.4 Installation Die folgenden Abschnitte erklären die Installation und Aktualisierung von Contao. Sie lernen wie man das Contao-Installtool verwendet, wie man eine Installation per FTP synchronisiert, wie man den Safe Mode Hack einrichtet und wie man einen Webserver für Contao konfiguriert. Installation 5 Handbuch für Contao 3.4 Contao installieren Laden Sie sich zunächst das aktuelle Contao-Archiv herunter und entpacken Sie es auf Ihrem lokalen Rechner. Verschieben Sie die Dateien in das htdocs -Verzeichnis Ihrer XAMPP-Installation oder kopieren Sie sie mit einem FTP- Programm (z.B. WinSCP) auf Ihren Server. Der Basisordner heißt wahrscheinlich htdocs , httpdocs , html oder public_html . Wenn Sie SSH-Zugriff auf den Server haben, können Sie alternativ folgende Befehle verwenden: curl -L http://download.contao.org | tar -xzp Das Contao-Installtool Um das Contao-Installtool aufzurufen, hängen Sie einfach /contao/install.php an die URL Ihrer Contao-Installation an. Beachten Sie, dass das Installtool mit einem Passwort gegen Brute Force-Attacken geschützt ist und gesperrt wird, wenn dreimal hintereinander ein falsches Passwort eingegeben wurde. Um diese Sperre aufzuheben, öffnen Sie die Datei system/config/localconfig.php in einem Texteditor, finden Sie die folgende Zeile und setzen Sie sie auf 0 . $GLOBALS['TL_CONFIG']['installCount'] = 0; // Hebt die automatische Sperre auf Datenbankverbindung herstellen Melden Sie sich an der Administrationsoberfläche Ihres Servers (z.B. "Plesk" oder "cPanel") an und erstellen Sie eine neue Datenbank für Contao. Geben Sie die Zugangsdaten im Contao-Installtool ein und beachten Sie die abweichende Schreibweise UTF8 anstatt UTF-8 in MySQL! Tabellen aktualisieren Contao prüft bei der Installation die Tabellen der Datenbank und gibt eine Liste empfohlener Änderungen aus, wenn diese nicht aktuell sind. Lesen Sie diese Empfehlungen aufmerksam, denn Contao kennt nur seine eigenen Tabellen und wird versuchen, vermeintlich nicht benötigte Tabellen anderer Programme "aufzuräumen". Bestätigen Sie die Änderungen durch Anklicken der "Datenbank aktualisieren"-Schaltfläche. Ein Template importieren Ein Template ist eine vorkonfigurierte Webseite, die eine beispielhafte Seitenstruktur und verschiedene Stylesheets zur Formatierung der Contao Core-Module und -Inhaltselemente enthält. Seit Version 3.2.11 ist die Beispiel-Webseite nicht mehr im Downloadpaket enthalten. Abhängig von der eingesetzten Version kann die neue Contao Official Demo oder die alte Music Academy als Erweiterung installiert werden. Aufschluss über Kompatibilität gibt das Erweiterungsverzeichnis. Vorgehen zur Installation der Demo: 1. Eine frische Contao Installation mit Admin-Account erstellen 2. Als Admin im Backend anmelden 3. Passende Erweiterung über das Extension Repository hinzufügen 4. Als Admin vom Backend abmelden 5. Installtool erneut aufrufen Contao installieren 6 Handbuch für Contao 3.4 Um ein Template zu importieren, wählen Sie den Eintrag aus dem Drop-Down-Menü und klicken Sie auf die "Template importieren"-Schaltfläche. Beim Import eines Templates werden bestehende Daten überschrieben! Administrator-Konto erstellen Wenn Sie kein Template importiert haben, müssen Sie ein Administrator-Konto erstellen, damit Sie sich am Contao- Backend anmelden können. Danach ist der Installationsprozess abgeschlossen. Der Link unten rechts leitet Sie zur Backend-Anmeldung weiter. Wenn Sie die Beispielwebseite importiert haben, können Sie sich dort als Benutzer "k.jones" mit dem Passwort "kevinjones" anmelden. Contao Demo installieren Siehe Vorgehen zur Installation der Demo im Abschnitt Ein Template importieren weiter oben. Suchmaschinenfreundliche URLs verwenden Wenn Sie einen Apache-Webserver haben und mod_rewrite verwenden dürfen, können Sie Contao dazu veranlassen, suchmaschinenfreundliche URLs zu generieren, die wie statische HTML-Seiten aussehen. Die dazu benötigten Rewrite- Regeln sind in der .htaccess.default -Datei im Contao-Verzeichnis gespeichert. Benennen Sie diese Datei um in .htaccess , damit sie vom Apache-Server erkannt wird, und rufen Sie anschließend das Modul "Einstellungen" im Contao- Backend auf. Wählen Sie die Option "URLs umschreiben" in der Gruppe "Frontend-Einstellungen" aus und speichern Sie Ihre Änderungen. Contao generiert jetzt statische URLs wie z.B. home.html anstatt index.php?id=12 . Contao installieren 7 Handbuch für Contao 3.4 Den Safe Mode Hack verwenden Eventuell haben Sie beim Aufruf des Contao-Installtools die Mitteilung erhalten, dass die lokale Konfigurationsdatei nicht beschreibbar ist. Dateizugriffsrechte Die Bezeichnung "Safe Mode Hack" ist eigentlich nicht korrekt, da sie impliziert, dass das Problem durch den PHP safe_mode verursacht würde. Tatsächlich wird es jedoch von unzureichenden Dateizugriffsrechten verursacht und tritt auch bei deaktiviertem safe_mode auf, daher sollte es richtiger "File Permission Hack" heißen. PHP als Apache-Modul läuft normalerweise als Benutzer wwwrun , www-data oder nobody , wohingegen die Dateien, die Sie per FTP hochgeladen haben, Ihrem Benutzer (z.B. web4 oder ab5678 ) gehören. Der Server verweigert Benutzern grundsätzlich den Zugriff auf fremde Dateien und macht auch für das PHP-Skript Contao keine Ausnahme. FTP für Dateioperationen verwenden Um das Rechteproblem zu umgehen, baut Contao eine FTP-Verbindung auf und legt die Ressourcen unter dem FTP- Benutzer an. Sie müssen dafür nur Ihre FTP-Zugangsdaten im Installtool eintragen. Achten Sie dabei besonders auf den korrekten relativen Pfad vom FTP-Basisordner zum Contao-Verzeichnis (z.B. html/ , public_html/ oder httpdocs/ ). Ein paar wenige Verzeichnisse benötigen trotz Safe Mode Hack Schreibrechte, weil PHP direkt auf sie zugreift: assets/images assets/images/* Den Safe Mode Hack verwenden 8 Handbuch für Contao 3.4 system/logs system/tmp Die Schreibrechte (CHMOD 777) werden vom Installtool automatisch gesetzt und müssen in der Regel nicht manuell nachgearbeitet werden. Falls dies doch einmal notwendig sein sollte, passen Sie bitte nur diese drei Verzeichnisse an – auch wenn Sie in einem Tutorial oder dem Contao-Forum etwas anderes gelesen haben sollten! Den Safe Mode Hack verwenden 9 Handbuch für Contao 3.4 Manuelles Update Bei der manuellen Aktualisierung einer Contao-Installation können Sie entweder das komplette Contao-Archiv auf den Server übertragen (Dateien ersetzen) oder nur die geänderten Dateien hochladen (Dateien synchronisieren).