How to: Eine Extension (hook) für TYPO3 programmieren

Vor ein paar Tage habe ich meine erste Extension (einen hook für comments) erfolgreich umgesetzt. Hier möchte ich die Vorgangsweise dafür erklären und beschreiben worauf man achten sollte.

1. Den Extesion Kickstarter installieren
Um eine Extension oder einen Hook zu erstellen, benötigt man zuerst ein allgemeines Grundgerüst. Die Erweiterung Extension Kickstarter ist ein praktisches Tool und für diesen Vorgang vorgesehen.

Die Extension wird aus dem TER heruntergeladen und im Extension Manager installiert. Danach gibt es hier einen neuen Menüpunkt: "make new extension".

2. Extension Key Festlegen
Jede Extension benötigt einen eindeutigen Extension Key (Namen). Falls man die Extension nicht veröffentlichen will, spielt die Namensgebung nicht so eine entscheidende Rolle. Möchte man hingegen die Extension der Typo3 Community zur Verfügung stellen, sollte man grundlegende Regeln für die Namensgebung unbedingt einhalten. Zusätzlich muss dann der Name der Extension auf der Typo3 Seite reserviert werden, was nur geht wenn man sich auf typo3.org registriert.

Ein wichtiger Tipp: Es wird empfohlen auf den Unterstrich "_" in der Namensgebung zu verzichten. Der Grund dafür ist, dass der Name für eine Extension zwar in Ordnung ist und er dadurch auch "lesbarer" wird, der Name der Extension als Klassennamen aber ohne Unterstrich auskommen muss. Heißt eure Extension zum Beispiel "simple_image_gallery", muss die Klasse der  Extension "tx_simpleimagegallery" benannt werden. Macht man hier Fehler wird die Klasse nicht aufgerufen und die Extension funktioniert nicht. Klassennamen können als nicht willkürlich vergeben werden. Die Typo3 Engine ist hier sehr pingelig, ob die Namensgebung stimmt.

Da ich die Extension "comments" mit einer Emailfunktion erweitern wollte, habe ich mich für den Namen "comments_email" entschieden. Ziel meiner Erweiterung war es eine Emailbenachrichtigung über jeden neuen Kommentar zu erhalten. Dies war zuvor nur möglich, wenn man sich entschied jeden einzelnen Kommentar auch zu bestätigen.

Nachdem der Extension Key gewählt wurde mit "Update" bestätigen. Mit "View result" kann man sehen welche Dateien nun erzeugt werden könnten und mit "WRITE" werden die angezeigten Dateien erstmal erzeugt und unter "typo3conf/ext/name_der_extension" abgelegt.

3. Benötigte Informationen im Kickstarter einfügen
Danach könne im Extension Kickstarter die verschiedensten Informationen zu der neuen Extension hinzugefügt werden. In meinem einfachen Fall habe ich nur folgende Daten eingegeben.

Unter General Info

• Title: Comments: email notification without approval
• Description: Offers the possibility to receive email notification about new comments without the need to approve each comment
• Category: Frontend
• State: Beta
• Dependencies: comments
• Author Name: Thomas Hirt 
• Author email: info(at)thomas-hirt.at

Danach wieder ein "Updaten" und ein "Write". Achtung alle Dateien mit einem kleinem Häckchen werden tatsächlich überschrieben.



4. Zusätzliche Dateien anlegen und Verzeichnis anpassen
Nachdem die Extension angelegt worden ist, kann man sie ganz gewöhnlich über den Extension Manager installieren. Da für meine Erweiterung auch eine "ext_localconf.php benötigt wird, habe ich diese manuell im Ordner "comments_email" angelegt.

Die Erweiterungsklasse "class.tx_commentsemail_hooks.php" habe ich in einen eigenen Ordner namens"pi1" hinzugefügt. Dort liegt auch eine neu angelegte Datei namens "locallang.xml" (Hier kannman unterschiedliche Übersetzungen anlegen). Zu bemerken ist hier, dass die Datei "class.tx_commentsemail_hooks.php" ohne Unterstrich "_" geschrieben werden muss! Ansonsten kanndie Klasse nicht aufgerufen werden.

Zusätzlich gibt es noch den Ordner "res". Hier habe ich das Template für den Emailversand abgelegt.





5. Den Hook ansprechen
Um einen Hook anzusprechen genügt eine einzige Zeile in der Datei ext_localconf.php der Extension:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['comments']['processSubmission'][$_EXTKEY] = 'EXT:comments_email/pi1/class.tx_commentsemail_hooks.php:tx_commentsemail_hooks->hookFunc';

Woher ich das weiß? Aus der Anleitung der Extension comments! Hooks existieren im gesamten Typo3 Code und werden auch von Extension Programmierern gerne zur Verfügung gestellt.

Dieser Aufruf baut sich nach folgendem Schem auf:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['comments'][hookName][$_EXTKEY] = 'EXT:yourextkey/class.tx_yourextkey_hooks.php:tx_yourextkey_hooks->methodName';

Auch hier muss ganz genau die Schreibweise eingehalten werden! Die Extension liegt zwar in dem Ordner "comments_email", aber die Klasse wird "tx_commentsemail_hooks" benannt.

Die Extension "comments" bietet Hooks an unterschiedlichsten Stellen des Programmcodes an. Ich habe mich nach Rückfragen (bei der englischen Typo3 Mailing Liste ) dafür entschieden den Hook "processSubmission" zu nutzen und dort mit meinem Code anzusetzen. Über die Mailing Liste hat mir auch  der Entwickler der Extension, Dmitry Dulepov, mit ein paar sehr Hilfreichen Tipps weitergeholfen.

6. Die Klasse erstellen
Dach wird die Datei "class.tx_commentsemail_hooks.php" bearbeitet. Der Grundaufbau sollte ungefähr wie folgt aussehen:

<?php
require_once(PATH_tslib . 'class.tslib_pibase.php');
class tx_commentsemail_hooks {   
    function hookFunc(&$params, &$pObj) {
    // Hier beginnt die eigentliche Funktion
    }
}
?>

Zuerst habe ich die Klasse "class.tslib_pibase.php" eincommentgebunden. Diese Klasse bildet die Basis für Frontend Plugins und enthält einige wichtige Funktionen. Sie befindet sich in dem Ordner "typo3/sysext/cms/tslib/" und ist dort ziemlich gut dokumentiert. Danach wird die eigentlich Klasse (ohne Underscore!) definiert. Die beiden Werte der Funktion "hookFunc" (&$params, &$pObj) habe ich aus der Dokumentation der Extension Comments entnommen. Ich kann zum Beispiel mit folgendem Aufruf nachsehen ob die Checkbox "Jeder Kommentar benötig eine Bestätigung:" angeklickt wurde:

$checkSpamProtect = $pObj->conf['spamProtect.']['requireApproval'];

Am besten man durchforstet mal mit var_dump($xy) die gegebenen Variablen. So kann man ganz gut sehen was darin gespeichert wurde. Falls euch der genau Code der Extension interessiert einfach im TER downloaden und nachsehen. Ich habe mir für meine Arbeit den Sourcecode von comments und comments_ic genauer angesehen und viel dabei gelernt.

Da ich jetzt auf den Geschmack gekommen bin habe ich mir auch gleich Dmitry Dulepovs Buch bestellt. Ich werden dann hier demnächst darüber Berichten.