reading

Bibliografische Information der Deutschen Bibliothek
Die Deutsche Bibliothek verzeichnet diese Publikation in der Deutschen Nationalbibliografie; detaillierte Daten sind im Internet über http://dnb.ddb.de abrufbar.

Hinweis: Alle Angaben in diesem Buch wurden vom Autor mit größter Sorgfalt erarbeitet bzw. zusammengestellt und unter Einschaltung wirksamer Kontrollmaßnahmen reproduziert. Trotzdem sind Fehler nicht ganz auszuschließen. Der Verlag und der Autor sehen sich deshalb gezwungen, darauf hinzuweisen, dass sie weder eine Garantie noch die juristische Verantwortung oder irgendeine Haftung für Folgen, die auf fehlerhafte Angaben zurückgehen, übernehmen können. Für die Mitteilung etwaiger Fehler sind Verlag und Autor jederzeit dankbar. Internetadressen oder Versionsnummern stellen den bei Redaktionsschluss verfügbaren Informationsstand dar. Verlag und Autor übernehmen keinerlei Verantwortung oder Haftung für Veränderungen, die sich aus nicht von ihnen zu vertretenden Umständen ergeben. Evtl. beigefügte oder zum Download angebotene Dateien und Informationen dienen ausschließlich der nicht gewerblichen Nutzung. Eine gewerbliche Nutzung ist nur mit Zustimmung des Lizenzinhabers möglich.

Alle Rechte vorbehalten, auch die der fotomechanischen Wiedergabe und der Speicherung in elektronischen Medien. Das Erstellen und Verbreiten von Kopien auf Papier, auf Datenträgern oder im Internet, insbesondere als PDF, ist nur mit ausdrücklicher Genehmigung des Verlags gestattet und wird widrigenfalls strafrechtlich verfolgt.

Die meisten Produktbezeichnungen von Hard- und Software sowie Firmennamen und Firmenlogos, die in diesem Werk genannt werden, sind in der Regel gleichzeitig auch eingetragene Warenzeichen und sollten als solche betrachtet werden. Der Verlag folgt bei den Produktbezeichnungen im Wesentlichen den Schreibweisen der Hersteller.

Lektor: Franz Graser
EPUB-Bearbeitung und Konvertierung: www.goebel-software.com
Coverart & -design: www.ideehoch2.de

ISBN 978-3-645-22002-6

Inhaltsübersicht

1 Vorbereitung

1.1 Einleitung

2 Planung der Erweiterung

2.1 Anforderungen sammeln

2.2 Umsetzung des Entwurfs in TYPO3

3 Struktur einer Extension

3.1 Kategorien von Extensions

3.2 Dateistruktur einer Extension

4 Der Extension Kickstarter

4.1 Aufbau des Kickstarters

4.2 Dateien des Kickstarters

5 Das Frontend-Plugin

5.1 Ausgangsbasis

5.2 Frontend-Funktionen

5.3 Plugin-Konfiguration

5.4 Lokalisierung

5.5 Caching in Plugins

5.6 Der Plugin-Code

6 Backend-Programmierung

6.1 Das Backend-Formular

6.2 Das Backend-Modul

7 Fertigstellen der Extension

7.1 Code Review

7.2 Dokumentation

7.3 Veröffentlichen der Erweiterung

8 Project Coding Guidelines

8.1 Project Coding Guidelines

9 Die TYPO3-API

9.1 Die Programmierschnittstelle von TYPO3

10 Ausblick

10.1 Einschätzung

10.2 MVC als Entwurfsmuster

10.3 FLOW3 und Extbase

10.4 Fluid

10.5 Kickstarter

10.6 Zusammenfassung

Stichwortverzeichnis

1 Vorbereitung

1.1 Einleitung

Dieses Buch ist eine praxisorientierte Hilfe für alle, die den Schritt vom reinen TYPO3-Anwender hin zum Entwickler gehen wollen.

Im Laufe dieses Buches wird der Werdegang einer TYPO3-Extension Schritt für Schritt nachvollzogen – vom Einrichten einer passenden Entwicklungsumgebung bis hin zur Veröffentlichung im TYPO3-Repository.

Basis dieses Buches ist TYPO3 in der Version 4.2.10.

Voraussetzungen

Folgende Voraussetzungen und Kenntnisse sollten Sie als Leser dieses Buches mitbringen:

Sicherer Umgang mit TYPO3

Sie sollten TYPO3 als Administrator kennen und verstehen. Grundwissen zum Thema Typoscript und TYPO3-Extensions sollte vorhanden sein.

Programmierkenntnisse

Die Programmiersprache für TYPO3 und seine Extensions ist PHP. Sie sollten daher solide Kenntnisse im Umgang mit PHP im Allgemeinen sowie mit Klassen und Objekten im Besonderen haben.

HTML-Kenntnisse

Die meisten Extensions erzeugen Ausgaben im Frontend. Sicherer Umgang mit HTML und CSS wird daher vorausgesetzt.

Einrichten von TYPO3 als Entwicklungsumgebung

Grundsätzlich lässt sich eine TYPO3-Extension mit nicht mehr als einem simplen Texteditor programmieren. Allerdings würde das nicht nur unnötige Zeit kosten, sondern auch viele Fehlerquellen öffnen. Eine sinnvoll eingerichtete TYPO3-Umgebung ist daher für die Extension-Entwicklung äußerst hilfreich. Im Folgenden werden einige Erweiterungen und Dokumentationen beschrieben, die Ihnen helfen, den Weg zur eigenen Extension zu ebnen.

Der Extension Kickstarter

Der Extension Kickstarter (kickstarter ) ist der Ausgangspunkt fast jeder Erweiterung. Er hilft, ein sauberes Grundgerüst für eine Extension aufzubauen – allerdings auch nicht mehr. Es handelt sich nämlich nicht um einen Editor, mit dem sich eine Extension nach dem Erstellen dauerhaft weiter pflegen lässt.

Wir werden den Kickstarter im Verlauf der Entwicklung unserer Erweiterung noch genauer kennenlernen.

Der Extension Development Evaluator

Die zweite hilfreiche TYPO3-Extension ist der Extension Development Evaluator (extdeveval ). Diese Erweiterung stellt eine Reihe von Funktionen zur Verfügung, um Ihre Erweiterung zu säubern und an die TYPO3-Richtlinien anzupassen. Außerdem stellt sie eine Dokumentation der TYPO3-Funktionen zur Verfügung.

Auch diese Erweiterung werden wir beim Aufbau unserer Extension einsetzen.

T3Dev

Die Erweiterung T3Dev (t3dev ) stellt ebenfalls einen Zugang zur Dokumentation zur Verfügung. Darüber hinaus enthält sie ein Tool zum Erstellen der XML-Strukturen für eine Flexform.

Dokumentationen

Die wichtigsten Dokumentationen zu TYPO3 stehen im Repository als »Extensions« zur Verfügung, auch wenn sie keinerlei Code enthalten. Stattdessen bringen sie die Dokumentation in Form einer OpenOffice-Datei auf Ihren Rechner, sodass die Informationen auch ohne Internet-Verbindung jederzeit zur Verfügung stehen.

Die Dokumentationen lassen sich mithilfe des Extension Managers problemlos installieren, indem Sie nach »doc_« suchen. Die wichtigsten Dokumentationen sind:

Dokumentation	Extension Key	Beschreibung
TSconfig	`doc_core_tsconfig`	Dokumentation der Typoscript-Konfiguration für Page und User TSConfig.
TSref	`doc_core_tsref`	Die Typoscript-Referenz
TYPO3 Coding Guidelines	`doc_core_cgl`	Guidelines für die Code-Entwicklung von TYPO3-Extensions
TYPO3 Core API	`doc_core_api`	Dokumentation der Programmierschnittstellen (APIs) von TYPO3
TypoScript Syntax and In-depth Study	`doc_core_ts`	Einführung in Typoscript

Tabelle 1.1: TYPO3-Dokumentationen

2 Planung der Erweiterung

Am Anfang jedes Projekts steht eine sorgfältige Planung, und eine TYPO3-Extension macht hier keine Ausnahme – im Gegenteil. Da jede Erweiterung Bestandteil des umfangreichen und komplexen TYPO3-Systems wird, muss sie über die »normalen« Anforderungen an ein Software-Projekt hinaus auch noch die Regeln erfüllen, die TYPO3 vorgibt. Ohne diese Vorgaben wäre es kaum möglich, die Stabilität und Flexibilität von TYPO3 zu gewährleisten.

2.1 Anforderungen sammeln

Am Beginn jeder Planung steht das Sammeln der Anforderungen – noch unabhängig vom Weg der Implementierung. So banal das klingen mag, so häufig wird dieser wesentliche Schritt versäumt oder zumindest zu leichtfertig angegangen. Stattdessen entwickelt sich das endgültige Konzept oft erst bei der Implementierung bzw. der Vorstellung der ersten Funktionen. Allerdings bedeutet das meist unnötige Verzögerungen und führt zu nicht optimalen Ergebnissen, weil an bereits fertigen Funktionen nachträglich Anpassungen erfolgen müssen. Im schlimmsten Fall stellt sich heraus, dass die grundlegende Struktur falsch ist, was dann umfangreiche Umbauarbeit nach sich zieht.

Eine gute erste Planungsphase hilft auch, unterschiedliche Denkweisen auszugleichen. Einfaches Beispiel: Denkt ein Bankangestellter an eine Transaktion, dann meint er meistens den Transfer von Geld. Ein Programmierer hat dagegen bei diesem Begriff eher Datenbanken im Sinn. Es lohnt sich daher, solche Missverständnisse von vornherein auszuschließen und eine gemeinsame Sicht der Dinge zu schaffen.

Das Pflichtenheft der Beispiel-Extension

Hier kommt nun das erste Mal unsere Beispiel-Extension ins Spiel. Im Laufe des Buches wollen wir einen Event Manager entwickeln, eine Erweiterung also, mit der sich Veranstaltungen verwalten lassen. Die Ausgangssituation soll folgendermaßen aussehen:

Auf der Website sollen Veranstaltungen angekündigt werden, zu denen sich Besucher registrieren können.
Eine Veranstaltung wird beschrieben mit Titel, Ort und Zeit. Außerdem soll es eine ausführliche Beschreibung geben sowie eine Agenda und einen Anreißtext, beispielsweise für die Homepage.
Zu einer Veranstaltung gibt es Sponsoren. Auf der Seite einer Veranstaltung soll eine Liste der Sponsoren mit Name und Logo zu sehen sein, die jeweils mit einem kurzen Firmenprofil verlinkt werden.
Es gibt Haupt- und Nebensponsoren.
Die Registrierung der Besucher erfolgt per Online-Formular. Dabei ist zu berücksichtigen, dass eine Veranstaltung nur eine begrenzte Zahl von Plätzen hat.
Jede Registrierung soll eine Mail an einen Mitarbeiter der Firma auslösen. Darüber hinaus soll in der Website-Verwaltung zu jeder Veranstaltung eine Teilnehmerliste abrufbar sein.

Als ergänzende Faktoren kommen dazu:

Ein Sponsor kann mehrere Veranstaltungen bezuschussen. Das Firmenprofil soll in diesem Fall nicht jedes Mal neu erstellt werden.
Besucher, die sich bereits einmal registriert haben, sollen ihre Daten nicht neu eingeben müssen.

Es gibt natürlich noch weitere naheliegende Funktionen, die zu unserer Erweiterung passen würden. Wir werden sie hier aber nicht umsetzen, um den Rahmen nicht zu sprengen. Denkbare zusätzliche Funktionen wären:

Veranstaltungsreihen, also sich wiederholende Termine
Online-Bezahlfunktionen
Registrierte Besucher können sich nach der Veranstaltung online anmelden, um zusätzliche Daten abzurufen, etwa die Präsentationen.

Technische Anforderungen

Über das funktionelle Pflichtenheft hinaus gibt es einige technische Details, die häufig nicht zur Sprache kommen, aber auf jeden Fall berücksichtigt werden sollten. Dazu gehören:

Einfache Anpassbarkeit des Layouts
Einfache Konfiguration im Backend
Unterstützung für mehrsprachige Websites
Dokumentation

Insbesondere der letzte Punkt gilt als undankbare Aufgabe und wird oft nur kurz oder lieblos erfüllt. Erfahrene Auftraggeber bestehen auf einer guten Dokumentation, doch auch aus Sicht des Programmierers ist sie wichtig. Denn nahezu jedes Projekt holt die Entwickler irgendwann wieder ein, beispielsweise weil neue Funktionen implementiert werden sollen. Und auch wenn man den Code selbst geschrieben hat – ein Jahr später wirkt er so fremd, als hätte man ihn nie gesehen.

Die Datenbankstruktur

Die obigen Anforderungen müssen nun in eine Datenbankstruktur umgesetzt werden – zunächst noch unabhängig von TYPO3. Folgende Tabellen sollen die Grundlage bilden:

Veranstaltungen

Feld	Typ	Beschreibung
`title`	`varchar(100)`	Titel der Veranstaltung
`location`	`varchar(100)`	Ort der Veranstaltung
`date`	`date`	Termin
`teaser`	`tinytext`	Anreißtext
`description`	`text`	Beschreibung
`agenda`	`text`	Agenda
`seats`	`int`	Anzahl Plätze

Tabelle 2.1: Datenbanktabelle für die Veranstaltungen

Sponsoren

Feld	Typ	Beschreibung
`name`	`varchar(100)`	Name des Sponsors
`logo`	`tinytext`	Dateiname des Logos
`url`	`tinytext`	Link zur Website
`profile`	`text`	Firmenprofil

Tabelle 2.2: Datenbanktabelle für die Sponsoren

Teilnehmer

Feld	Typ	Beschreibung
`name`	`tinytext`	Name des Teilnehmers
`email`	`varchar(200)`	E-Mail-Adresse
`street`	`varchar(150)`	Straße / Hausnummer
`zipcode`	`varchar(10)`	Postleitzahl
`city`	`varchar(100)`	Ort
`country`	`varchar(100)`	Land

Tabelle 2.3: Datenbanktabelle für die Teilnehmer

Zu den reinen Datentabellen kommen noch zwei Kreuztabellen, in denen gespeichert wird, welcher Sponsor zu welcher Veranstaltung gehört und welcher Teilnehmer sich wo registriert hat. Kreuztabellen wählen wir deshalb, weil zwischen Veranstaltungen und Sponsoren eine m-zu-n-Beziehung besteht, d. h. eine Veranstaltung kann mehrere Sponsoren haben, ein Sponsor mehrere Veranstaltungen fördern. Das Gleiche gilt für Veranstaltungen und Teilnehmer. Gemäß den Normalisierungsregeln für Datenbanken sind in solchen Fällen Kreuztabellen das Mittel der Wahl.

Eine grafische Darstellung des Datenbankmodells sieht dann etwa so aus:

Bild 2.1 Der Entwurf für das Datenbankmodell

2.2 Umsetzung des Entwurfs in TYPO3

Nachdem die Datenstruktur feststeht, soll nun die Anpassung an die TYPO3-Umgebung erfolgen. Das beginnt mit der Suche nach dem richtigen Namen.

Der Extension Key

Erweiterungen werden von TYPO3 nicht zuletzt anhand des Namens verwaltet. Daher muss jede TYPO3-Extension eine eindeutige Bezeichnung erhalten, den Extension Key . Bei der Benennung von Extensions sind daher einige Regeln einzuhalten.

Für Extensions, die nur für eine Installation verwendet werden sollen, muss die Eindeutigkeit des Namens nur innerhalb des Systems hergestellt sein. Wenn Sie sicher sind, dass eine Erweiterung nur für ein bestimmtes Projekt von Interesse ist und nicht allgemein verfügbar sein soll, nehmen Sie daher einfach einen Namen Ihrer Wahl und setzen das Präfix user_ davor. Damit ist klar, dass diese Extension nicht aus dem öffentlichen Repository für Erweiterungen stammen kann. Vom Extension Key abgeleitete Bezeichner für Tabellen usw. ergeben sich dann wie in der folgenden Tabelle angegeben:

	Regel	Beispiel
Extension Key	Frei wählbar, aber mit Präfix `user_`	`user_myextension`
Datenbank-Tabellen und -Felder	mit dem Präfix der Erweiterung	`user_myextension_images user_myextension_categories`
Backend-Modul	enthält keine Unterstriche, beginnt mit `u`	`umyextension`
PHP-Klassen	Klassennamen werden gebildet wie Datenbank-Tabellen und Felder, die Dateien dazu erhalten den Vorsatz `class.`	`class.myextension_pi1.php`

Tabelle 2.4: User Extension Keys und abgeleitete Bezeichner

Soll eine Erweiterung dagegen der TYPO3-Gemeinde zur Verfügung gestellt, sprich ins TYPO3 Extension Repository (TER) geladen werden, muss der Extension Key weltweit eindeutig sein.

Um dies sicherzustellen, werden Extension Keys im TER registriert. Dabei werden neben der Eindeutigkeit auch noch einige formale Kriterien für den Aufbau des Keys geprüft.

Diese sind:

Der Key darf nur aus Buchstaben, Ziffern und dem Unterstrich (_) bestehen.
Der Key darf nicht mit einem reservierten Präfix wie tx, u, tt_ oder sys_ beginnen – auch wenn im Repository aus historischen Gründen noch Extensions wie tt_news oder tt_address zu finden sind.
Da aus dem Key Bezeichner für Module abgeleitet werden, indem die Unterstriche entfernt werden, muss der Key auch in diesem Fall eindeutig bleiben. Unter anderem deswegen wird für neue Extensions empfohlen, von vornherein keine Unterstriche im Extension Key zu verwenden.
Da aus dem Extension Key auch der Verzeichnisname in TYPO3 abgeleitet wird, sollten keine Großbuchstaben verwendet werden. Dies würde je nach Betriebssystem zu Komplikationen führen.

Damit ergeben sich folgende Bezeichner in der Extension:

	Regel	Beispiel
Extension Key	Vom TER zugewiesen bzw. akzeptiert	`myextension`
Datenbank-Tabellen und -Felder	Name der Erweiterung, versehen mit dem Präfix `tx_`	`tx_myextension_images tx_myextension_categories`
Backend-Modul	enthält keine Unterstriche, beginnt mit `tx`	`txmyextension`
PHP-Klassen	Klassennamen werden gebildet wie Datenbank-Tabellen und Felder, die Dateien dazu erhalten den Vorsatz `class.`	`class.tx_myextension_pi1.php`

Tabelle 2.5: TER Extension Keys und abgeleitete Bezeichner

Neben den formalen Kriterien gibt es auch einige »weiche« Anforderungen. So soll der Key den Zweck der Extension beschreiben, gleichzeitig aber nicht zu lang sein. Im Repository finden Sie viele Extensions, die mit einem Kürzel für den Autor beginnen. Das wird nicht empfohlen, lässt sich aber manchmal nicht vermeiden, wenn man eine Erweiterung in einer Kategorie schreibt, in der es schon einige andere gibt. Besser ist es aber, wenn Ihre Extension eine Eigenart aufweist, die im Extension Key benutzt werden kann.

Für unseren Event Manager wären also gute Extension Keys:

eventmanager
eventmgr
eventmanagement

Nicht zu empfehlen wären dagegen:

emgr (zu kurz)
my_manager (keine Beschreibung, Unterstrich)
event_and_sponsor_management (lang, viele Unterstriche)

Veröffentlichen von Extensions

Selbst wenn beim Schreiben einer Erweiterung zunächst nicht geplant ist, die Extension im TER zu veröffentlichen, sollten Sie diesen Schritt auf jeden Fall aus zwei Gründen mit einplanen:

Zum einen ist es mit viel Aufwand verbunden, den Namen einer Extension nachträglich zu ändern. Der Extension Key wird für Verzeichnis- und Dateinamen ebenso benutzt wie für Datenbanktabellen. Und selbst wenn die Erweiterung zu speziell ist, um für andere von Nutzen zu sein: Sie können sie als privat oder als Test markieren und sie so im TER ablegen, ohne den Zugriff für andere freizuschalten.

Zum anderen lebt TYPO3 nicht zuletzt von der Vielzahl an Erweiterungen. Wenn eine Extension also von allgemeinem Interesse sein könnte, sollte sie auch im TER vorhanden sein.

Alle Erweiterungen, die Sie schreiben, unterliegen wie TYPO3 selbst automatisch der GPL (GNU General Public License). Das zwingt Sie zwar nicht zur Veröffentlichung, doch sollten Sie sich im Klaren sein, dass der Quellcode Ihrer Extension von jedem benutzt und weiterbearbeitet werden darf, der Zugriff darauf hat.

Um eine Extension im Repository veröffentlichen zu können, benötigen Sie einen Login auf der Website TYPO3.org. Hier können Sie ein persönliches Profil hinterlegen, sind aber nicht dazu gezwungen. Nach der Anmeldung können Sie auf der Seite https://TYPO3.org/extensions/extension-keys/ einen Extension Key registrieren.

Bild 2.2 Das Registrieren eines Extension Keys geht schnell und einfach

Das Repository prüft, ob der Key die Vorgaben erfüllt und ob er frei ist. Falls ja, wird er eingetragen, andernfalls erhalten Sie eine Fehlermeldung.

Tipp: Wenn Sie einen Extension Key reservieren wollen, recherchieren Sie vorher im Repository, welche Namen bereits benutzt werden. Allerdings kann es passieren, dass ein Extension Key reserviert ist, obwohl keine Extension dazu im Repository angeboten wird.

Einmal reservierte Extension Keys können Sie über die oben genannte Website im Abschnitt »Manage keys« auch verwalten. Sie sehen dort, wann der letzte Upload der Extension erfolgt ist. Auch eine Löschfunktion für Ihre Extension Keys ist hier zu finden. Allerdings lässt sich ein Key nur dann komplett löschen, wenn er noch nie benutzt wurde, d. h. wenn noch keine Extension mit diesem Key ins Repository eingestellt wurde.

Wenn Sie eine Extension nicht mehr weiter verwalten wollen, aber ein anderer User sich dazu bereit erklärt hat, können Sie die Rechte an einem Extension Key auch einem anderen User übertragen.

Von den oben genannten brauchbaren Keys waren bereits einige vergeben, für die hier vorgestellte Erweiterung wurde daher der Key eventmanagement reserviert. Nach den Empfehlungen von TYPO3 ist er mit 15 Zeichen etwas zu lang, doch abgesehen davon erfüllt er alle Anforderungen.

Anpassung der Datenbankstruktur

Wir wissen bereits, dass unsere Extension eine Datenbank benötigt, und haben die gewünschte Struktur bereits bestimmt. Da aber diese Struktur in die bereits bestehende von TYPO3 integriert werden soll, müssen einige Anforderungen erfüllt werden.

TYPO3-eigene Felder

Jede TYPO3-Tabelle hat einige Felder, die für die Verwaltung durch TYPO3 wichtig sind. Zwingend sind hierbei zunächst nur uid und pid.

uid (Unique ID) ist die eindeutige Kennzeichnung jedes Eintrags. Dabei handelt es sich um ein sogenanntes Autoincrement-Feld, das automatisch hochzählt.

pid (Page ID) bestimmt, auf welcher Seite des TYPO3-Baums der Inhalt platziert wird. Eine 0 steht für den Beginn des Baums, den root level.

Wie wir später sehen werden, lassen sich beim Anlegen der Tabelle im Kickstarter weitere Optionen aktivieren, die in folgenden Feldern verwaltet werden: