100 Tipps für TYPO3 CMS

Patrick Lobacher Volker Krell 100 Tipps für TYPO3 CMS Typische Fehler erkennen und vermeiden 2. Auflage Open Source Press

Alle in diesem Buch enthaltenen Programme, Darstellungen und Informationen wurden nach bestem Wissen erstellt. Dennoch sind Fehler nicht ganz auszuschließen. Aus diesem Grunde sind die in dem vorliegenden Buch enthaltenen Informationen mit keiner Verpflichtung oder Garantie irgendeiner Art verbunden. Autor(en), Herausgeber, Übersetzer und Verlag übernehmen infolgedessen keine Verantwortung und werden keine daraus folgende Haftung übernehmen, die auf irgendeine Art aus der Benutzung dieser Informationen oder Teilen davon entsteht, auch nicht für die Verletzung von Patentrechten, die daraus resultieren können. Ebenso wenig übernehmen Autor(en) und Verlag die Gewähr dafür, dass die beschriebenen Verfahren usw. frei von Schutzrechten Dritter sind. Die in diesem Werk wiedergegebenen Gebrauchsnamen, Handelsnamen, Warenbezeichnungen usw. werden ohne Gewährleistung der freien Verwendbarkeit benutzt und können auch ohne besondere Kennzeichnung eingetragene Marken oder Warenzeichen sein und als solche den gesetzlichen Bestimmungen unterliegen. Dieses Werk ist urheberrechtlich geschützt. Alle Rechte, auch die der Übersetzung, des Nachdrucks und der Vervielfältigung des Buches oder Teilen daraus vorbehalten. Kein Teil des Werkes darf ohne schriftliche Genehmigung des Verlags in irgendeiner Form (Druck, Fotokopie, Mikrofilm oder einem anderen Verfahren), auch nicht für Zwecke der Unterrichtsgestaltung, reproduziert oder unter Verwendung elektronischer Systeme verarbeitet, vervielfältigt oder verbreitet werden. Bibliografische Information der Deutschen Nationalbibliothek Die Deutsche Nationalbibliothek verzeichnet diese Publikation in der Deutschen Nationalbibliografie; detaillierte bibliografische Daten sind im Internet über http://dnb.d-nb.de abrufbar. Copyright 2013 Open Source Press, München Gesamtlektorat: Dr. Markus Wirtz Satz: Open Source Press & Thomas Schraitle (AsciiDoc/DocBook/XSL-FO/XEP) Umschlaggestaltung: Olga Saborov ISBN: 978-3-95539-047-1 (E-Book PDF) ISBN: 978-3-95539-046-4 (gedruckte Ausgabe) http://www.opensourcepress.de

Inhaltsverzeichnis 1 Lizenzen, Planung und Systemadministration 13 1 TYPO3 steht unter einer freien Lizenz. Was ist erlaubt und was nicht?............................................... 14 2 Installation und Einsatzzweck der TYPO3-Instanz(en).......... 17 3 Entwerfen Sie eine langfristig angelegte Grundstruktur........ 21 4 Sammeln Sie Änderungen am Kern oder an fremden Extensions in Diff-Dateien........................................ 23 5 Fehler im Core was ist zu tun?.......................... 27 6 Dateien im Format T3X entpacken......................... 31 2 Installation, Upgrade und Update 37 7 Achten Sie auf eine korrekte Installation.................... 38 8 Zugriffsrechte im Dateisystem........................... 41 Lobacher, Krell 100 Tipps für TYPO3 CMS 5

Inhaltsverzeichnis 9 Probleme bei der Zeichenkodierung nach der Installation mit dem 1-2-3-Installer.................................... 43 10 Wichtige Einstellungen nach Abschluss des 1-2-3-Installers....................................... 47 11 Die Wartung des Systems............................... 51 12 Überblick über Major- und Minor-Versionen vor Upgrades..... 55 13 Der richtige Weg zum Backup............................ 60 14 Lokaler Server und Live-/Deployment-Server................ 65 15 Backend und/oder Frontend sind plötzlich verschwunden..... 67 16 Logfiles eine Übersicht................................ 70 3 Backend-Administration 75 17 Im Backend Rechte nicht nur auf Benutzerebene vergeben..... 75 18 Komplexere Rechtestrukturen durch Untergruppen........... 83 19 Admin-Rechte für mehrere Backend-Benutzer vermeiden...... 89 20 Bestimmte Rechte/Funktionen nur Admin-Usern zuweisen..... 91 21 Warum Admin-Funktionen für Redakteure sinnvoll sein können.............................................. 95 22 Leistungsfähige Suche im Backend....................... 103 23 Login-Screen ändern und dennoch upgradefähig bleiben..... 108 24 Backend vor größeren Arbeiten sperren................... 111 25 Arbeiten im Backend automatisieren..................... 113 www.opensourcepress.de 6

Inhaltsverzeichnis 26 Das Backend richtig einrichten.......................... 118 27 Wenn man etwas gelöscht hat, ist es weg. Oder?............ 124 4 Die Arbeit mit Inhalten optimieren nicht nur für Redakteure 129 28 Single Table View mehrere Datensätze darstellen und bearbeiten.......................................... 130 29 Mehrere Datensätze kopieren oder verschieben............. 132 30 Rekursives Kopieren ermöglichen........................ 134 31 Datensätze zur Verwendung außerhalb von TYPO3 exportieren......................................... 135 32 Kurze Wege im Backend mithilfe von Lesezeichen........... 137 33 Mit RTE-htmlarea formatierten Text kopieren und einfügen.... 138 34 Einfügen von bereinigtem Text für den Redakteur obligatorisch machen............................................ 140 35 Bilder, die sich durch Anklicken vergrößern lassen, mit dem RichTextEditor einfügen............................... 141 36 Mehrfach auf einer Seite verwendete Inhalte zentral pflegen............................................ 145 37 Teile des Seitenbaums auf einer oder mehreren Seiten einbinden........................................... 149 38 Änderungen nachvollziehen und rückgängig machen........ 150 39 Interne Notizen nutzen................................ 152 Lobacher, Krell 100 Tipps für TYPO3 CMS 7

Inhaltsverzeichnis 5 TypoScript 157 40 So kommen Sie Tippfehlern auf die Schliche................ 158 41 Übersicht durch richtiges Klammern...................... 160 42 Dokumentieren Sie Ihren Code!.......................... 162 43 Fehler: Conditions in Klammern......................... 164 44 So verwenden Sie Conditions richtig...................... 168 45 COA_INT für ungecachte Bereiche....................... 174 46 Mehr Übersicht durch ausgelagerte Template-Dateien........ 176 47 Reihenfolge von TypoScript-Templates und Fehler beim Kopieren mit dem Operator <................................... 178 48 Mit dem Operator =< referenzieren statt kopieren........... 180 49 Sichere Menü-Erstellung............................... 182 50 Unterscheiden Sie Menüpunkte mit dem Optionsplit......... 187 51 Einfaches Ausklappmenü mit TypoScript und jquery......... 189 52 Das spezielle Menü rootline für einen Klickpfad............ 195 53 Reihenfolge der Abarbeitung bei stdwrap................. 198 54 Mit CONTENT per TypoScript Datensätze ausgeben.......... 200 55 Sicherheitslücken bei Benutzereingaben................... 203 56 Felder im Backend und HTML-Ausgabe bei Überschriften anpassen........................................... 206 www.opensourcepress.de 8

Inhaltsverzeichnis 57 Vorschau auf Unterseiten über ein Menü aus Teaserboxen..... 210 58 Unterschiedliche Seitenlayouts mit dem Dropdownmenü-Layout in den Seiteneigenschaften............................. 215 59 Seiteneigenschaften um eigene Felder erweitern............ 218 60 Aussehen von Inhaltselementen mit TypoScript und CSS ändern............................................. 224 61 HTML-Ausgabe von Standard-Inhaltselementen anpassen..... 228 62 Fallunterscheidungen, um angepasste HTML-Ausgaben auswählbar zu machen................................ 234 63 Veränderte Inhaltselemente als eigene hinzufügen........... 236 64 Bessere Bilderverwaltung mit FAL........................ 240 6 Templating die Verbindung zwischen HTML und TYPO3 249 65 HTML-Template in TYPO3 integrieren der klassische Weg.... 250 66 Marker und Subparts verändern das Template, daher kann man auch mit den Elementen also den Tags arbeiten......... 255 67 Passen Sie das Backend-Layout an....................... 257 68 Seitentemplates mit Fluid erste Schritte................. 266 69 Das Content-Objekt FLUIDTEMPLATE richtig verwenden....... 269 7 Mehrsprachigkeit 273 70 Die optimale Einrichtung einer mehrsprachigen Website...... 273 71 Übersicht beim Übersetzen............................. 279 Lobacher, Krell 100 Tipps für TYPO3 CMS 9

Inhaltsverzeichnis 72 Sprachpakete für Erweiterungen und Backend nachinstallieren...................................... 280 73 Übersetzungen mit _LOCAL_LANG anpassen............... 282 74 URL-Pfade einer mehrsprachigen Seite mit RealURL anpassen........................................... 284 75 Einfaches Menü zur Sprachwahl mit TypoScript............. 286 76 Sprachmenü aus Landesfahnen.......................... 288 8 Suchmaschinenoptimierung (SEO) 291 77 Default-Einstellungen nur bedingt SEO-tauglich............ 291 78 Meta-Daten im Hinblick auf SEO optimieren............... 297 79 Bei Fehlern den richtigen HTTP-Statuscode ausgeben........ 301 80 Fehler beim Seitentitel................................. 303 81 Bilder SEO-tauglich machen............................ 306 9 Suche 309 82 Die leistungsfähige Suchmaschine korrekt konfigurieren...... 309 83 Die Suchmaschine gibt keine Ergebnisse zurück............. 314 84 Zu viele Suchergebnisse eine sinnvolle Auswahl treffen..... 317 10 Erweiterungen 321 85 Aktualisieren Sie vor dem Import stets die Liste der Erweiterungen....................................... 322 www.opensourcepress.de 10

Inhaltsverzeichnis 86 Erweiterungen installieren, auch wenn die Verbindung fehlschlägt.......................................... 323 87 Statisches TypoScript-Template, ohne das keine Ausgabe erfolgt............................................. 324 88 Update einer Erweiterung: HTML-Template auslagern, um keine Anpassungen zu verlieren.............................. 326 89 Mehr Flexibilität bei Inhaltselementen mit Gridelements...... 330 90 Gridelemente mit Flexforms um selbst definierte Felder erweitern........................................... 336 11 Sicherheit und Performance 343 91 Klare Vorgehensweise bei Sicherheitslücken in TYPO3........ 343 92 Informieren Sie sich über Sicherheitslücken und führen Sie Updates durch....................................... 346 93 Sichern Sie ein neues TYPO3-System ausreichend ab......... 350 94 Die Datei LocalConfiguration.php sichern.................. 354 95 Fallunterscheidungen per linkvars........................ 355 96 Performance für nachvollziehbare Ergebnisse ermitteln....... 356 97 TYPO3 ist in der Default-Installation nicht gerade schnell..... 360 98 Cache-Performance optimieren.......................... 364 99 Steigerung der Performance durch einen PHP-Beschleuniger................................... 367 100 TypoScript als Performance-Killer....................... 370 Lobacher, Krell 100 Tipps für TYPO3 CMS 11

Inhaltsverzeichnis Index 375 www.opensourcepress.de 12

1 13Kapitel Lizenzen, Planung und Systemadministration TYPO3 ist ein hochkomplexes System, das nicht nur Anfängern immer wieder Probleme bereiten kann. Aber nicht nur die Technik bietet Stolperfallen, auch zu den sogenannten Soft Facts, wie Lizenz, Schreibweise, Netiquette usw., gibt es immer wieder Fragen, ebenso zur korrekten Planung eines TYPO3-Webauftritts und dem Handling von Änderungen und Updates. Im Folgenden wollen wir uns solche Fragen vornehmen, die auf Mailinglisten, in Foren, aber auch in Schulungen immer wieder auftauchen. Es geht vor allem um Vorbereitendes, Dinge, die man wissen und beachten sollte, bevor man die Installation des TYPO3-Systems und die Implementierung einer Website angeht. Lobacher, Krell 100 Tipps für TYPO3 CMS

1 Lizenzen, Planung und Systemadministration 1 TYPO3 steht unter einer freien Lizenz. Was ist erlaubt und was nicht? Oft hört oder liest man die folgenden oder ähnliche Aussagen: Man darf den TYPO3-Kommentar aus dem Quellcode der erzeugten Seite nicht entfernen. Man darf TYPO3 als angepasstes Produkt verkaufen. Man darf den Copyright-Hinweis aus dem TYPO3-PHP-Quellcode entfernen. Man darf mit TYPO3 kein Geld verdienen. Man muss den Quellcode (auch dem Kunden) immer mitgeben. Die Liste lässt sich beinah beliebig erweitern und zeigt schlicht, dass sich viele, die mit TYPO3 arbeiten, wenig mit der Lizenz auseinandergesetzt haben, unter der der TYPO3-Quellcode veröffentlicht wurde. Als TYPO3 vom Erfinder Kasper Skårhøj als Open-Source-Projekt der Community übergeben wurde (nachdem es zunächst als kommerzielles Produkt initiiert war), musste eine passende Open-Source-Lizenz gefunden werden und es gibt zahlreiche (sich oft nur in Details unterscheidende) Lizenzen! Für TYPO3 wurde die GNU General Public License (GPL)¹ in Version 2 gewählt. Die Wahl war naheliegend, schließlich ist die GPL bei Open-Source-Projekten sehr populär und damit auch weithin bekannt und erprobt. Die Lizenzvereinbarung finden Sie nach der Installation von TYPO3 im Root-Verzeichnis in den Dateien LICENSE.txt und GPL.txt. ¹ http://www.gnu.org/licenses/gpl.html www.opensourcepress.de 14

1 TYPO3 steht unter einer freien Lizenz. Was ist erlaubt und was nicht? Übrigens wird die Lizenz in jeder (!) Datei des TYPO3-Projekts im Header genannt. Dort befindet sich auch ein Hinweis darauf, wie mit dem Copyright-Hinweis des Quellcodes umzugehen ist: /*************************************************************** * Copyright notice * * (c) 1999-2013 Kasper Skårhøj (kasperyyyy@typo3.com) * All rights reserved * * This script is part of the TYPO3 project. The TYPO3 project is * free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * The GNU General Public License can be found at * http://www.gnu.org/copyleft/gpl.html. * A copy is found in the textfile GPL.txt and important notices to the license * from the author is found in LICENSE.txt distributed with these scripts. * * * This script is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * This copyright notice MUST APPEAR in all copies of the script! ***************************************************************/ Die letzte Zeile sagt es deutlich: Dieser Copyright-Hinweis muss in jeder Datei erhalten bleiben. Die GPL wiederum umfasst juristisch das, was das GNU-Projekt bzw. die Free Software Foundation als dessen organisatorische Vertretung als die vier Freiheiten definiert; sie bilden sozusagen das konzeptuelle Funda- Lobacher, Krell 100 Tipps für TYPO3 CMS 15

1 Lizenzen, Planung und Systemadministration ment der gesamten Free-Software-Bewegung. In der deutschen Übersetzung lauten diese vier Freiheiten:² Die Freiheit, das Programm für jeden Zweck zu benutzen (Freiheit 0). Die Freiheit, zu verstehen, wie das Programm funktioniert und wie man es für seine Ansprüche anpassen kann (Freiheit 1). Der Zugang zum Quellcode ist dafür Voraussetzung. Die Freiheit, Kopien zu verbreiten, so dass man seinem Nächsten weiterhelfen kann (Freiheit 2). Die Freiheit, das Programm zu verbessern und die Verbesserungen der Öffentlichkeit zur Verfügung zu stellen, damit die ganze Gemeinschaft davon profitieren kann (Freiheit 3). Der Zugang zum Quellcode ist dafür Voraussetzung. In der Praxis bedeutet das, dass für die Software keine Lizenzgebühren erhoben werden können. Zwar könnte man die Software verkaufen, doch da der Source-Code offenliegt und vom Kunden eingesehen werden kann, entbehrt dieses Geschäft einer vernünftigen Grundlage. Dienstleistungen zur Einrichtung, Konfiguration, Programmierung oder Erweiterung dürfen hingegen sehr wohl kommerziell angeboten werden und sind tatsächlich die Grundlage der meisten Firmen, die mit Open Source ihr Geld verdienen. Der im Quellcode von TYPO3 automatisch eingebrachte Copyright-Hinweis darf aber, rein juristisch betrachtet, entfernt werden. Allein schon aus Respekt vor dem Projekt und der Community sollte man ihn jedoch nicht entfernen eine Erweiterung um die eigene Leistung ist jedoch nicht unüblich und unkritisch zu bewerten. ² http://www.gnu.org/philosophy/free-sw.de.html www.opensourcepress.de 16

2 Installation und Einsatzzweck der TYPO3-Instanz(en) <!-- typovision GmbH digital communications www.typovision.de This website is powered by TYPO3 - inspiring people to share! TYPO3 is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. TYPO3 is copyright 1998-2013 of Kasper Skaarhoj. Extensions are copyright of their respective owners. Information and contribution at http://typo3.com/ and http://typo3.org/ --> 2 Installation und Einsatzzweck der TYPO3-Instanz(en) Will man beispielsweise nur eine einzige Website betreiben, ist der Fall klar: Man lädt das gesamte TYPO3-Paket herunter und installiert es, wie in Kapitel 2 dargestellt. Schwieriger wird das Ganze, wenn man mehrere TYPO3-Instanzen auf einem Server betreiben will. Sicherlich könnte man diese Instanzen in verschiedene Verzeichnisse installieren ein Problem ist dann zumindest, den Überblick nicht zu verlieren. Welche TYPO3-Version befindet sich wo, und mit welchen Extensions wurde die Instanz jeweils erweitert? Bei einem Security-Hinweis (Security Advisory bzw. SA), wie er von TYPO3 regelmäßig veröffentlicht wird, muss man in der Folge alle Verzeichnisse einzeln prüfen, ob die von der Sicherheitslücke betroffene TYPO3-Version oder Extension installiert ist. Wir raten darum grundsätzlich dazu, für alle Instanzen denselben Kern (Core) zu verwenden, und zwar aus folgenden Gründen: Lobacher, Krell 100 Tipps für TYPO3 CMS 17

1 Lizenzen, Planung und Systemadministration Alle Dateien des TYPO3-Kerns liegen an einer definierten Stelle. Man kann Extensions nun ebenfalls für alle Instanzen global installieren (im Verzeichnis typo3/ext/) und hat diese damit ebenfalls nur ein Mal auf dem System. Sicherheitsupdates lassen sich schnell einspielen, da man nur einen Kern und gegebenenfalls eine Extension updaten muss. Ein Upgrade der TYPO3-Version ist zudem ebenfalls einfacher. Auch das Backup wird durch den zentralisierten Kern vereinfacht. Um einen solch zentralisierten Kern zu verwenden, müssen Sie wie folgt vorgehen (Details zur konkreten Installation erläutern wir im nächsten Kapitel): 1. Anlegen eines Verzeichnisses, das den TYPO3-Kern enthält, z. B. /var/ typo3/typo3_src-6.1.0. Dort befinden sich nun die Verzeichnisse typo3 und t3lib sowie die Datei index.php. 2. Anlegen der Document-Root-Verzeichnisse für die Domains. 3. Dort hinein kopieren Sie das Dummy-Paket.³ Es enthält die Verzeichnisse fileadmin, uploads, typo3conf sowie typo3temp. 4. Im Dummy-Paket sind bereits symbolische Links zu verschiedenen Verzeichnissen enthalten. Wichtig ist in unserem Fall nur der symbolische Link zum Verzeichnis typo3_src. Löschen Sie diesen wie folgt ³ http://www.typo3.org/downloads www.opensourcepress.de 18

2 Installation und Einsatzzweck der TYPO3-Instanz(en) und legen Sie ihn neu an. Anschließend installieren Sie TYPO3 wie gewohnt (und in Kapitel 2 erklärt). Löschen des symbolischen Links und erneutes Anlegen desselben (Pfad zur TYPO3-Version muss natürlich individuell angepasst werden): shell$ cd /pfad/zu/ihrem/document/root shell$ rm typo3_src shell$ ln -s /var/typo3/typo3_src-6.1.0 typo3_src Nun können Sie beliebig viele Instanzen von TYPO3 verwenden mit nur einem einzigen Kern. Es wäre jetzt, wie erwähnt, praktisch, wenn Sie auch oft benötigte Extensions nur ein Mal und nicht in jeder Instanz installieren müssten. Dafür nutzt TYPO3 sogenannte globale Extensions. Lokale Extensions befinden sich direkt in der Instanz im Verzeichnis typo3conf/ext/ Globale Extensions befinden sich im Kern im Verzeichnis typo3/ext/ System-Extensions befinden sich ebenfalls im Kern im Verzeichnis typo3/sysext/ System-Extensions sollte man tunlichst nicht anfassen, da sie direkt mit dem Kern zusammenarbeiten, optimal auf ihn abgestimmt sind und ein Verändern in aller Regel Instabilität und Fehler zur Folge hat. Die Verwendung globaler Extensions wird angeraten, da diese Extensions so nur ein Mal auf dem System vorhanden und (ähnlich wie beim zentralisierten Kern) leichter zu pflegen sind. Um überhaupt globale Extensions Lobacher, Krell 100 Tipps für TYPO3 CMS 19

1 Lizenzen, Planung und Systemadministration installieren zu können, müssen Sie im Install Tool die Option [EXT][allowGlobalInstall] im Bereich All configurations setzen. Abbildung 1.1: So können globale Extensions installiert werden Nun können Sie während der Installation einer Extension im Extension Manager (bzw. Erweiterungs-Manager) auswählen, ob Sie diese global oder lokal installieren wollen. Abbildung 1.2: Auswahl bei der Installation Hinweis Durch den Umbau des Extension Manager ab der Version 6.0.x fehlt dort aktuell die Auswahl, ob man die Extension lokal oder global installieren möchte. Dies ist ein Bug, der in einer der nachfolgenden Versionen eventuell bereits behoben wurde. Man kann sich aber dadurch www.opensourcepress.de 20

3 Entwerfen Sie eine langfristig angelegte Grundstruktur helfen, dass man die Extension wie gewohnt (lokal) installiert und dann in den Pfad typo3/ext/ umkopiert. 3 Entwerfen Sie eine langfristig angelegte Grundstruktur Vor allem für TYPO3-Neulinge ist die Versuchung groß, ein Projekt zu beginnen, ohne zuvor eine klare Struktur für Dateien, Templates etc. zu definieren. Irgendwann merkt man dann, dass man nicht den optimalen Weg eingeschlagen hat, und muss in der Folge umstellen, umorganisieren, umkopieren Gerade am Anfang ist es daher wichtig, eine Grundstruktur für Projekte zu finden, die langfristig trägt. Hier hat sich Folgendes bewährt: Dateistruktur im Verzeichnis fileadmin/ Jede TYPO3-Instanz greift zum Aufbau der Website hauptsächlich auf das Verzeichnis fileadmin/ zu. Daher sollte dieses eine wohlüberlegte Struktur haben; das hat folgende Vorteile: Man weiß sofort, wo sich welche Datei befindet, was u.a. die Pflege erleichtert. Andere Entwickler finden sich sofort im Projekt zurecht. Lobacher, Krell 100 Tipps für TYPO3 CMS 21

1 Lizenzen, Planung und Systemadministration Weil man dieselbe Struktur in allen Projekten verwendet, fällt der Wechsel vom einen zum anderen Projekt leichter. Erstellt man TypoScript, in dem Pfade hart kodiert sind, kann man die Skripte ohne Veränderung in verschiedenen Instanzen verwenden. Hier der Vorschlag für eine sinnvolle Verzeichnisstruktur: redaktion/ hier legen die Redakteure ihre Dateien ab site/ Hauptverzeichnis für alle Dateien, die den Aufbau der Website betreffen site/css/ CSS-Dateien site/img/ Bilder und Grafiken site/js/ JavaScript und jquery site/php/ PHP-Dateien (z.b. für UserFunc) site/templates/ HTML-Templates www.opensourcepress.de 22

4 Sammeln Sie Änderungen am Kern oder an fremden Extensions in Diff-Dateien site/ts/ TypoScript-Dateien 4 Sammeln Sie Änderungen am Kern oder an fremden Extensions in Diff-Dateien Im Grunde sollte man im TYPO3 Core oder in einer nicht selbst geschriebenen Extension keine Änderung vornehmen. Allerdings gibt es immer wieder Fälle, in denen dies unumgänglich wird etwa wenn der Core einen Fehler hat, man einen Hook benötigt, der in der Extension noch nicht eingebaut ist, oder wenn unter Zeitdruck etwas für den Kunden fertiggestellt werden soll. Gerade hier kommt es darauf an, diese Änderung hundertprozentig nachvollziehbar und möglichst fehlerfrei zu dokumentieren. Natürlich könnte man nun die Änderung in einem Textfile dokumentieren, das hat aber zwei große Nachteile: Erstens kann es in der Dokumentation, wird sie von Hand vorgenommen, zu Fehlern kommen, zweitens ist es dann unmöglich, die Änderung automatisiert wieder einzuspielen, etwa, wenn man den Core aktualisiert hat. Es bietet sich an, das Verfahren zu verwenden, mit dem auch TYPO3-Kernentwickler arbeiten. Lobacher, Krell 100 Tipps für TYPO3 CMS 23

1 Lizenzen, Planung und Systemadministration Erstellung eines Diff-Files Prinzipiell können Sie hier zwei Strategien verfolgen: Entweder Sie erstellen ein sogenanntes Diff-File⁴ pro Datei oder für Ihre gesamte Installation. Wenn Sie das Diff-File für die gesamte Installation anlegen, also für alle Files auf einmal, sind Sie anschließend nicht mehr in der Lage, nur Teile wieder einzuspielen, da immer das ganze File verwendet wird. Erstellen Sie das Diff auf File-Basis, erhalten Sie ggf. sehr viele Dateien (abhängig davon, wie viel Sie ändern), die Sie verwalten müssen. Man kann keiner Strategie generell den Vorzug geben; unser Beispiel zeigt das Vorgehen mit einer einzigen Datei. Legen Sie zunächst immer eine Kopie der Datei an, die Sie ändern wollen. Wir wollen die Datei typo3/sysext/cms/tslib/index_ts.php verändern und dort, wo das Admin-Panel angezeigt wird, zusätzlich einen Dump des Array TSFE ausgeben. Wir kopieren also zunächst die Datei index_ts.php nach index_ts_orig_20130518.php. Der Zusatz orig zeigt, dass es sich um das Original handelt (das wir nicht mehr anfassen werden). Jetzt passen wir den Code der Datei typo3/sysext/cms/tslib/index _ts.php an, so dass ein Array-Dump des TSFE ausgegeben wird. Dazu fügen wir folgenden Code (nach ca. Zeile 238) hinzu: echo '<pre>'.print_r($tsfe,1).'</pre>'; Um ein Diff zu erzeugen, wechseln wir anschließend in das Document- Root-Verzeichnis (wir gehen hier von /var/www/htdocs/ aus, dieser Pfad kann, je nach Servervariante, anders lauten) und verwenden das Kommando diff wie folgt: ⁴ Ein Diff enthält die Code-Unterschiede zwischen zwei Dateien (also meist Original und Änderung) in maschinenlesbarer Form. www.opensourcepress.de 24

4 Sammeln Sie Änderungen am Kern oder an fremden Extensions in Diff-Dateien shell$ cd /var/www/htdocs shell$ diff -ru typo3/sysext/cms/tslib/index_ts_orig.php \ typo3/sysext/cms/tslib/index_ts.php > index_ts_20130518.diff Der Befehl diff erzeugt nun die Differenz zwischen Original-Datei und der veränderten Datei und legt sie in der Datei index_ts_20130518.diff ab. Wenn Sie nicht mit einem auf Unix basierenden Betriebssystem (wie Linux oder Mac OS X) arbeiten und Ihnen der Befehl diff nicht zur Verfügung steht, finden Sie auf SourceForge⁵ die entsprechenden Utilities für Windows. Inspizieren wir die erzeugte Datei, sehen wir, wie die Änderungen in der Datei gespeichert wurden: --- typo3/sysext/cms/tslib/index_ts_orig.php 2013-04-30 08:24:20.000000000 +0200 +++ typo3/sysext/cms/tslib/index_ts.php 2013-05-18 09:06:33.000000000 +0200 @@ -236,6 +236,7 @@ if (is_object($be_user) && $BE_USER->isAdminPanelVisible() && $TSFE->isBackendUserLoggedIn()) { $TSFE->content = str_ireplace('</head>', $BE_USER->adminPanel->getAdminPanelHeaderData(). '</head>', $TSFE->content); $TSFE->content = str_ireplace('</body>', $BE_USER->displayAdminPanel(). '</body>', $TSFE->content); + echo '<pre>'.print_r($tsfe,1).'</pre>'; } if ($sendtsfecontent) { echo $TSFE->content; // ************* ⁵ http://gnuwin32.sourceforge.net/packages/diffutils.htm und http:// gnuwin32.sourceforge.net/packages/patch.htm Lobacher, Krell 100 Tipps für TYPO3 CMS 25

1 Lizenzen, Planung und Systemadministration Die ersten beiden Zeilen geben die beiden als Parameter übergebenen Dateien an (also Original und veränderte Version). Da wir zuerst die Originaldatei angegeben haben, müssen wir bei zukünftigen Differenzen darauf achten, diese Reihenfolge nicht mehr zu ändern. Anschließend kommt eine Zeile, die den Block der Änderung anzeigt. Diese beschreibt, in welchen Zeilen der entsprechende Block in beiden Dateien beginnt und, durch ein Komma getrennt, wie lang er in der jeweiligen Datei ist. Es folgen drei Zeilen vor der Änderung und drei Zeilen nach der Änderung. Dazwischen findet man, markiert mit einem Minuszeichen, alle Zeilen, die im geänderten File nicht mehr vorhanden sind, und, markiert mit einem Pluszeichen, alle Zeilen, die im geänderten File hinzugekommen sind. Haben Sie in einer Datei mehrere Änderungen an verschiedenen Stellen vorgenommen, erhalten Sie für jede Änderung einen solchen Block. Vor jedem Block ist zudem eine Zahlenangabe zu sehen, die die Zeilennummer der Änderung angibt in unserem Fall Zeilennummer 236. Patchen des Quellcodes mit dem Diff-File Die mittels diff erstellten Differenzen können Sie nun in Form des erzeugten Files archivieren. Wenn Sie dann den TYPO3-Kern zum Beispiel auf eine neue Version aktualisiert haben, müssen Sie die Differenz wieder einspielen, weil durch das Update Ihre Änderungen natürlich verloren gegangen sind. Dazu wechseln Sie in das Root-Verzeichnis der Installation und geben die folgenden Befehle ein: shell$ cd /var/www/htdocs shell$ patch --dry-run -u -p0 < index_ts_20130518.diff www.opensourcepress.de 26

5 Fehler im Core was ist zu tun? Die Ausgabe dieses Befehls, auf die wir hier verzichtet haben, zeigt Ihnen nur, was passieren würde, denn die Option --dry-run verhindert, dass tatsächlich Änderungen vorgenommen werden. In unserem Beispiel wäre die Ausgabe etwa patching file typo3/sysext/cms/tslib/index_ts.php Wenn Sie nach dieser Kontrolle sicher sind, dass alles seine Richtigkeit hat, können Sie den Schalter --dry-run weglassen und den Befehl noch einmal anwenden erst dann wird das File wirklich geändert. 5 Fehler im Core was ist zu tun? Wenn Sie sicher sind, einen Bug im TYPO3-Kern gefunden zu haben, sollten Sie dies öffentlich machen, damit er so schnell wie möglich gefixt werden kann. Falls Sie dazu in der Lage sind, sollten Sie zudem einen Patch erstellen. Bug-Report verfassen Zunächst gilt es, einen Bug-Report zu verfassen. Dieser sollte (in englischer Sprache) folgende Informationen enthalten: Eine detaillierte Problembeschreibung Wo/Wann tritt der Fehler auf? Was wurde stattdessen für ein Ergebnis erwartet? Lobacher, Krell 100 Tipps für TYPO3 CMS 27

1 Lizenzen, Planung und Systemadministration Falls Screenshots möglich sind, sollte man diese dem Bug-Report beilegen. Gibt es für das Problem relevante Konfigurationseinstellungen? Gibt es einen Work-Around? Reichen Sie den Bug-Report auf http://forge.typo3.org ein. Wenn Sie im Bug-Tracker selbst einen Eintrag anlegen wollen, müssen Sie sich zunächst einen Account anlegen. Klicken Sie dazu auf Register rechts oben. Sie werden daraufhin zu typo3.org weitergeleitet, wo Sie Ihren Account anlegen können. Anschließend können Sie sich über den Menüpunkt Sign in rechts oben einloggen. Abbildung 1.3: Erfolgreiches Login Nun müssen Sie sich erst das Projekt aussuchen, zu dem Sie einen Bug- Report verfassen wollen. Dazu geben Sie z.b. links in die Suche Project title search die ersten Buchstaben ein, warten, welche Vorschläge Sie bekommen, und wählen einen aus. Gleich darüber finden Sie ein Menü mit den wichtigsten Projekten. So können Sie dort z.b. auf TYPO3 CMS www.opensourcepress.de 28

5 Fehler im Core was ist zu tun? klicken und anschließend auf den Link Core, wenn Sie einen Bug im TYPO3 CMS Core melden wollen. Um zunächst einmal zu ermitteln, ob schon ein ähnlicher Bug gefunden und gemeldet wurde, bietet sich die Suche rechts oben an. Abbildung 1.4: Forge Screen Sobald Sie Ihr Projekt gefunden haben, verändert sich die horizontale Navigation und zeigt alle Optionen, die in diesem Projekt möglich sind. Insbesondere ist es nun möglich, einen Bug-Report unter dem Menüpunkt New Issue anzulegen. Lobacher, Krell 100 Tipps für TYPO3 CMS 29

1 Lizenzen, Planung und Systemadministration Abbildung 1.5: New Issue Link in der Navigation Tragen Sie in dem erscheinenden Formular möglichst alle benötigten Informationen ein und klicken Sie anschließend auf Create, um den Bug- Report abzuschicken. Merken Sie sich die eindeutige Bug-Nummer (ID) diese hat das Nummernzeichen als Präfix. Den Fehler beheben und in den Core bringen Da Sie den Fehler entdeckt und sich damit eventuell schon länger beschäftigt haben, kann es sein, dass Sie bereits eine Lösung für das Problem haben. Dann sollten Sie zusätzlich zum Bug-Report einen Patch einreichen. Sie benötigen dafür zunächst eine Kopie des aktuellen TYPO3-Source- Codes aus dem Git Repository. Diese können Sie in der Linux- und Mac- OS-X-Konsole wie folgt herunterladen für Windows bietet sich z. B. das Programm msysgit⁶ an. Im Folgenden gehen wir davon aus, dass Sie den TYPO3 CMS Core verändern wollen.⁷ git clone --recursive git://git.typo3.org/typo3v4/core.git ⁶ ⁷ http://msysgit.github.io/ Weitere Git-Repositories finden Sie unter http://git.typo3.org www.opensourcepress.de 30

6 Dateien im Format T3X entpacken Führen Sie dann die Änderung am TYPO3 Core durch, anschließend können Sie mit diff prüfen, was Sie geändert haben (vgl. git diff Fassen Sie nun die Änderungen in einer Diff-Datei zusammen geben Sie als bugnummer die ID ein, die Sie beim Bug-Report erhalten haben: shell$ git diff > bugnummer.diff Nun fügen Sie dem Bug-Report die Diff-Datei hinzu. Beachten Sie den Bug in der Folgezeit besonders aufmerksam. Es werden eventuell Fragen gestellt oder aber Kommentare dazu abgegeben. Hier sollten Sie besonders schnell reagieren können. Wird der Patch nun irgendwann in den Core übernommen, ist das Problem gelöst und Ihr Name taucht im Changelog auf. 6 Dateien im Format T3X entpacken Das Daten-Format T3X wurde eingeführt, um Datei- und Verzeichnisstrukturen möglichst schnell und einfach zu übertragen. So wird das Format beispielsweise dafür benutzt, um Extensions zu einer Datei zusammenzuführen und mit dem Extension Manager zu übertragen. So kann man z.b. im Extension Manager eine Extension als T3X (oder ab TYPO3 CMS 6.0 auch als ZIP) abspeichern, wenn man auf das entsprechende Icon klickt.⁸ ⁸ Auch auf http://typo3.org/extensions/repository/ können Sie alle Extensions als T3X herunterladen. Lobacher, Krell 100 Tipps für TYPO3 CMS 31