Extension Points

Was sind Extension Points bzw Extensions?

Extension Points (aka EPs) sind Schnittstellen im Code, die es ermöglichen ohne Änderungen an den Redaxo Originaldateien eigene Funktionen (Extensions) in den Programmablauf “einzuklinken”, und damit gegebene Funktionalität zu erweitern bzw. zu verändern. EPs findet man sowohl im Redaxo Core (siehe Auflistung), als auch in vielen Addons.

Wie benutzt man EPs, wie definiert man eigene Extensions?

Den passenden EP finden

Zunächst muß man den zur geplanten Funktionalität passenden EP finden.. dies ist naturgemäß abhängig davon was man in welchem Kontext erreichen will. Eine Liste der Redaxo Core EPs incl. Infos darüber an welcher Stelle dieser EP im Scriptablauf steht, welche Daten im EP übermittelt bzw. zurückerwartet werden ist weiter unten zu finden.
Welche EPs es in Addons gibt ist der Dokumentation des jeweiligen Addons zu entnehmen.

Eigene Funktion als Extension am EP registrieren

Hat man einen geeigneten EP gefunden, muß man die eigene Extension am EP registrieren, indem man dem EP den Namen der eigenen (Callback)Funktion als string übergibt. Dies geschieht nach folgendem grundsätzlichen Schema:

rex_register_extension('EP_NAME','meine_extension');

function meine_extension($params)
{
// Je nach EP und Funkionalität des eigenen Codes:
// 1. Code ausführen ohne auf Daten des EPs zurückzugreifen.. der EP
// dient nur als trigger
// 2. Daten des EPs im eigenen Code verwenden ohne Rückgabe in den EP
// 3. Daten des EPs bearbeiten und zum EP zurückschicken
}

Daten die im EP zur Verfügung stehen

Ob bzw. welche Daten/Parameter im EP zur Verfügung stehen hängt vom jeweiligen EP ab und ist der untenstehenden Dokumentation zu entnehmen. Sofern Daten übergeben werden, werden sie von der Extension als Funktionsvariable $params entgegengenommen. Das Array $params ist per Konvention aufgeteilt in:

  • Datenteil $params["subject"] – dies ist (je nach EP) jener Teil der Daten, der an den EP in modifizierter Form zurückgegeben werden kann.
  • Parameterteil $params["irgendein_key"] – dies sind zusätzliche, nicht manipulierbare und nicht rückgebbare Informationen die vom EP zur Verfügung gestellt werden.

Daten an den EP zurückübermitteln

Sofern dies vom EP erwartet bzw. unterstützt wird, finden sich die manipulierbaren Daten wie bereits erwähnt in $params["subject"]. Diese Daten werden dann nach der Bearbeitung an den EP zurückübermittelt:

rex_register_extension('EP_NAME','meine_extension');

function meine_extension($params)
{
$subject = $params['subject'];
// Bearbeitung von $subject..
return $subject;
}

Hinweis: Falls man $params["subject"] nicht verändert hat, ist es nicht notwendig es wieder an den EP zurückzuschicken. Im Redaxo Core wird geprüft ob Daten aus dem EP zurückkommen, und falls nicht, werden die Originaldaten unverändert weiterverwendet.

Codebeispiel: EIn konkretes Beispiel für die Verwendung von EPs findet sich im Teil 5 des AddOn Tutorials

Definition eigener EPs

Die Definition eigener EPs (z.b. in einem Addon) geschieht mittels rex_register_extension_point():

rex_register_extension_point
(
$extensionPoint, // Name des EPs
$subject, // Daten
$params, // Parameter (optional, default: array())
$read_only // Schreibschutz für Daten von $subject (optional, default: false)
)

Subject und Parameter

Welche Daten bzw. Parameter man im EP übermittelt, bzw. ob man welche zurückerwartet ist vom Einsatzzweck des geplanten EPs abhängig. Entscheidend ist es, die Daten hinsichtlich ihrer Bedeutung entsprechend zu verteilen:

  • $subject ist für die eigentlichen “Nutz“daten, welche – sofern nicht das optionale flag $read_only auf true gesetzt wurde – von der Extension zurückerwartet werden.
  • $params ist für “Begleit“parameter zuständig. Diese können von der Extension grundsätzlich nur gelesen, also nicht verändert werden.

Um die veränderten Daten zurückzuerhalten schreibt man sie als return der Extension zurück in $subject:

$subject = rex_register_extension_point('EP_NAME',$subject,$params);

Fallstrick: Timing

Bei der Definition eigener EPs (z.b. in einem Addon) muß man folgenden Umstand hinsichtlich des Timings beachten: Obwohl man erwarten könnte, daß man erst einen ExtensionPoint registrieren muß, um dann daran eine Extension anzudocken, verhält es sich genau umgekehrt:
Die Registrierung einer Extension muß vor der Registrierung des zugehörigen ExtensionPoints erfolgen.

Sollte der Fall eintreten, daß eine Extension nach ihrem EP registriert wird, wird sie schlicht nicht ausgeführt. Typisches Beispiel für solch einen Fall wäre z.b. der Plan ein Addon mit Plugins zu erstellen, wo die Plugins einen EP im Addon nutzen sollen: Da die config-Datei des Plugins nach jener des Addons included wird, kommt somit die Registrierung der Extension zu spät.

Abhilfe

In der Regel wird es nicht möglich sein eine Extension früher zu registrieren, folglich muß man dafür den eigentlichen EP im Scriptverlauf “nach hinten” verschieben. Eine Möglichkeit dies zu erreichen, wäre wiederum einen EP in Anspruch zu nehmen, und zwar ADDONS_INCLUDED. Wie der Name andeutet, wird dieser ausgeführt, sobald alle config Dateien der aktivierten Addons (und ihrer Plugins) bereits included wurden, sprich auch die Extension die bis dato zu spät kam.

D.h. man registriert für ADDONS_INCLUDED einen callback, und erst in diesem registriert man seinen eigenen EP:

rex_register_extension('ADDONS_INCLUDED','mein_ep_kommt_spaeter');

function mein_ep_kommt_spaeter()
{
// ..
$subject = rex_register_extension_point('MEIN_EP',$subject,$params);
}