Events

Einführung

Über Events können Funktionen im eCMS und Plugins durch eigene Funktionsaufrufe erweitert werden. Der im eCMS integrierte Configurable Event Dispatcher (CED) verwaltet und steuert die Events.

Funktionsweise des Event-Dispatchers

Der CED speichert in einer eigenen Datenbank-Tabelle registrierte Funktionen, sogenannte Actions, für Events. Aus performance-steigernden Gründen wird diese Konfiguration auch als Array an das eCMS zurückgegeben, damit dieses es selbst (serialisiert) speichern kann und später den CED schneller initialisieren kann.

Methoden em_dispatcher

Im Folgenden die wichtigsten Methoden der Klasse em_dispatcher

• event_execute (...)
  Löst einen Event aus und ruft die dazu registrierten Funktionen auf.
• action_create (...)
  Registriert eine neue Action-Aufruf für einen Event.
• action_delete (...)
  Löscht eine Action-Aufruf für einen Event.
• action_get (...)
  Liefert die registrierten Daten zu einer Action.
• action_getList (...)
  Liefert eine Liste von registrierten Actions zu unterschiedlichen Filter-Kriterien zurück

Ablauf: Event auslösen  - event_execute (...)

Nachfolgend Erklärungen beziehen sich auf eine Instanz des CEDs, bspw. im eCMS.

1. Von "irgendwoher" wird die Methode event_execute(...) des CEDs mit einem auszuösendem Event-Namen aufgerufen.
   Dieses "irgendwoher" ist der sogenannte "Sender", d.h. der ursprüngliche Auslöser des Events.
   Außerdem übergibt der Sender beliebige Daten, die den eventuell registrierten Funktionen gleich "hilfreich" sein könnten.
2. Der CED instanziiert ein Notification-Object (s.u.) für diesen Event und kopiert in dieses zusätzlich die zuvor übergebenen Daten.
3. Der CED überprüft in seiner Event-Config-Liste, ob zu diesem Event aufzurufende Funktionen hinterlegt sind.
4. Der CED ruft ggfs. diese Funktionen nacheinander auf und übergibt dabei per Referenz immer dasselbe Notification-Object.
   (Reihenfolge der Funktionsaufrufe kann nicht sicher festgelegt werden!)
   Die aufgerufenen Funktionen können die Daten im Notification-Object lesen und modifizieren.
5. Der CED returned das Notification-Object an den Funktionsaufrufer.

Der Event-Dispatcher im eCMS

Der Event-Dispatcher (Class em_dispatcher) ist im eCMS über

$eCMS->dispatcher

verfügbar.

Als Speichern-Callback-Methode hat die eCMS-Instanz ihre Methode site__site_saveEventStack(...) bei CED hinterlegt. Diese Callback-Methode wird vom CED aus immer aufgerufen, wenn Änderungen an der Event/Action-Konfiguration gemacht wurden. In diesem Aufruf erhält das eCMS aus der Dispatcher Class den fertigen Event-Stack und speichert diese in den eCMS-Site-XSettings, damit diese später dem CED für eine schneller Initialisierung übergeben werden können von eCMS.

Klasse em_event_notification

Das Event-Object wird vom CED beim Auslösen eines Events erzeugt und an die dazu registrierten Funktionen weitergereicht. Es dient primär als "Kommunikations-Object" dazu die Daten und das finale Result weiterzureichen.

• __construct (...)
  Dem Konstruktor wird der Event-Name,Sender und optional (empfohlen) ein Daten-Array mitübergeben.

• Generische getter- / setter-Methoden
  Damit können alle Elemente des internen Daten-Array innerhalb des em_event_notification-Objects gelesen bzw. gesetzt werden.
  Syntax: get<ElementName> ( ), set<ElementName> (<NewValue>)
  Beispiele:

  • getResult(...)

  • setResult(...)

• sender_getObject( )
  Liefert die Instanz des auslösenden Objects zurück (Back-Referenzierung)

• event_getName( )
  Liefert den Namen des ausgelösten Events zurück.

• action_skip( )
  Setzt das interne Flag im Event für den Sender, daß er seine Verarbeitung überspringen soll.

• action_isSkipped ( )
  Gibt den Status des internen Flags zurück. Dies würde üblicherweise vom Sender aus überprüft werden, nachdem dieser das Event ausgelöst hatte.

Mit Events programmieren

Neue Events erstellen

Events müssen nirgendwo vorab registriert oder konfiguriert werden. Es reicht einfach einen Event mit seinem Event-Namen auszulösen. Auch das Registrieren von eigenen Funktionen zu einem Event kann ohne weitere Vorbereitungen durchgeführt werden.

Innerhalb der Core-Logik des eCMSs, also in dessen PHP-Methoden, wird häufig direkt am Anfang einer Methode ein PRE-Event ausgelöst, über welchen Parameter geändert werden können oder eventuell auch die Ausführung der eigentlichen Methode übersprungen werden kann.

Des Weiteren gibt es häufig dann auch noch ein Event, ohne PRE-Postfix, der dann am Ende der Methode ausgelöst wird und primär dazu dient das bis dahin vorliegende Methoden-Ergbenis-Array anzureichern, weiter zu verarbeiten oder abzuwandeln.

// PRE-Events:
	"<function-name, lowercased>_pre"
 
	// (POST-) Events:
	"<function-name, lowercased>"

Events triggern

Events können prinzipiell an jeder beliebigen Stelle ausgelöst werden. Sinnvollerweise werden Events an den Stellen ausgelöst, die tendenziell später durch Plugins erweitert werden könnten.

Wird ein Event ausgelöst, kann man beliebige Daten übergeben, die man den eventuell registrierten Funktionen zur Verfügung stellen möchte.

Nachfolgend das Standard-Implementierung-Beispiel, für die Integation eines Pre- und Post-Events in eine eCMS-Methode.

public function my_method ($params)
	{
	    // Pre Event Dispatcher
	    $preEvent = $this->eCMS->dispatcher->event_execute('my_method_pre', array('params'=>$params, 'result'=>array('status'=>true,'msg'=>null)));
 
	    if ($preEvent->action_isSkipped()==true){
	        // Methoden-Ausführung gecancelt
	        return $preEvent->getResult();
	    } else {
	        // übernimmt ggf. geänderte Parameter und Result, falls Message-Stack aus Pre-Event zurückgeliefert wurde
	        $params=$preEvent->getParams();
	        $R=$preEvent->getResult();
	    }
 
 
	    /**
	     *
	     * hier der eigentliche Inhalt / Source-Code der Methode "my_method"
	     *
	     */
 
	    // Post Event Dispatcher
	    $postEvent = $this->eCMS->dispatcher->event_execute('my_method', array('result'=>$R, 'params'=>$params));
 
	    return $postEvent->getResult();
	}

Im zweiten Parameter von "event_execute(...)" können beliebige Daten übergeben werden. Aus dem Event-Notification-Object könne diese über die Methode "get<filedname>()" ausgelesen und über die Methode "set<filedname>()" ins Notification-Object zurück gespeichert werden.

Event Callbacks

Eine eigene Callback-Funktion kann eine eCMS-Methode (in einem Plugin), eine static Class-Methode oder eine einfache Funktion sein.

An die Callback-Funktion wird nur ein Parameter eine Instanz der Klasse em_event_notification übergeben. In der Instanz sind alle Event-Daten enthalten, die beim Aufruf des Event-Action-Prozess ( event_execute) übergeben wurden. Über die Methode "get<fieldname>()" können die Inhalte abfragt werden und mit der Methode "set<fieldname>()" können geänderte Inhalte zurück geschrieben werden.

Das folgende Beispiel erweitert das Result eine Methode:

function my_event_action ($event)
	{
	    // bisherige "Result"-Daten aus Event-Object holen:
	    $r = $event->getResult();
 
	    // Daten modifizieren / eigene Aktionen durchführen...
	    $r['data']['xfield']=array(); // do something!
 
	    // Modifizierte Daten zurückschreiben in das Event-Object:
	    $event->setResult($r);
	}

Eigene Callback-Funktionen müssen geänderte Event-Instanzen nicht explizit returnen, da dies zuvor per Referenz übergeben wurde.

Die eCMS Instance kann über die Methode "sender_getObject" holt werden.

// Layout aus eCMS abfragen
	$event->sender_getObject()->layout->layout_get(array('l_label'=>$event->getLayoutLabel()));

Damit eine eigene Funktion überhaupt durch den Event-Dispatcher aufgerufen werden kann, muss diese natürlich vorab dort für den gewünschten Event registriert werden.

Dies geschieht mit folgendem Aufruf:

$eCMS->dispatcher->action_create( array(
	     'de_event' => '<EventName>',
	     'de_action_type' = 'method', // Optionen sind: "method", "function", "static-function"
	     'de_action' = > '<AMethodNameOfSenderObject>'
	));