3 Hooks, Aktionen und Trigger

Transkript

1

2 Bei der Arbeit mit Drupal soll oftmals dann etwas passieren, wenn ein bestimmtes Ereignis eintritt. Ein Siteadministrator möchte beispielsweise eine erhalten, wenn eine Nachricht eingestellt wird, oder ein Benutzer soll gesperrt werden, wenn bestimmte Wörter in einem Kommentar auftauchen. Dieses Kapitel beschreibt, wie Hooks für bestimmte Drupal-Ereignisse definiert werden, sodass Ihr eigener Code ausgeführt wird, wenn diese Ereignisse auftreten. 3.1 Grundlagen von Ereignissen und Triggern Während Drupal seine Arbeit verrichtet, durchläuft das Programm eine Abfolge von Ereignissen. Beim Eintreten dieser internen Ereignisse können Module mit der Ablaufsteuerung von Drupal zusammenwirken. Tabelle 3.1 zeigt einige der Ereignisse von Drupal. Ereignis Erstellen eines Nodes Löschen eines Nodes Anzeigen eines Nodes Erstellen eines Benutzerkontos Aktualisieren eines Benutzerprofils Anmelden Abmelden Typ Node Node Node Benutzer Benutzer Benutzer Benutzer Tabelle 3.1: Beispiele für Drupal-Ereignisse Drupal-Entwickler bezeichnen diese internen Ereignisse als Hooks, denn wenn ein solches Ereignis eintritt, erlaubt Drupal den Modulen, sich in den Ausführungspfad»einzuklinken«. In den vorangegangenen Kapiteln sind Ihnen bereits einige Hooks begegnet. Zur typischen Modulentwicklung gehört die Entscheidung, auf welche Drupal-Ereignisse Sie reagieren, d.h., welche Hooks Sie in Ihrem Modul implementieren möchten.

3 Angenommen, Sie haben gerade eine Website gestartet, die auf einem Computer in Ihrem Keller ausgeführt wird. Sobald die Site erfolgreich wird, möchten Sie sie an eine große Firma verkaufen und steinreich werden. In der Zwischenzeit wünschen Sie jedes Mal eine akustische Benachrichtigung, wenn sich ein Benutzer anmeldet. Da Ihre Katze schläft und die Töne als störend empfinden würde, entscheiden Sie sich dafür, das Signal zunächst mit einem einfachen Protokolleintrag zu simulieren. Sie schreiben daher schnell eine.info-datei und stellen Sie in das Verzeichnis sites/all/modules/custom/beep/beep.info: ; $Id$ name = Beep description = Simuliert einen Signalton. package = Drupal Entwickler Buch core = 6.x Dann wird es Zeit, sites/all/modules/custom/beep/beep.module zu schreiben: <?php // $Id$ * Simuliertes Signal function beep_beep() { watchdog('beep', 'Beep!'); Es schreibt die Meldung Beep! in die Protokolldatei von Drupal. Das soll fürs Erste reichen. Als Nächstes soll Drupal ein Signal ausgeben, wenn sich ein Benutzer anmeldet. Das können wir einfach erreichen, indem wir hook_user() in unserem Modul implementieren und die Operation login abfangen: * Implementierung von hook_user(). function beep_user($op, &$edit, &$account, $category = NULL) { if ($op == 'login') { beep_beep(); Sehen Sie, das war einfach. Wie wäre es mit einem weiteren Signal, wenn neuer Inhalt hinzugefügt wird? Das ist möglich, wenn wir hook_nodeapi() in unserem Modul implementieren und die Operation insert abfangen: * Implementierung von hook_nodeapi(). 72

4 3.2 Grundlagen von Aktionen function hook_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) { if ($op == 'insert') { beep_beep(); Was ist, wenn wir ein Signal wünschen, sobald ein Kommentar hinzugefügt wird? Nun, wir könnten hook_comment() implementieren und die Operation comment abfangen, doch lassen Sie uns zunächst etwas nachdenken. Im Wesentlichen führen wir immer wieder dieselbe Sache aus. Wäre es nicht gut, wenn wir eine grafische Benutzeroberfläche hätten, auf der wir die Aktion der Signalausgabe mit jedem beliebigen Hook und jeder beliebigen Operation verknüpfen könnten? Genau das macht das eingebaute Triggermodul von Drupal. Es gibt Ihnen die Möglichkeit, eine Aktion mit einem bestimmten Ereignis zu verknüpfen. Im Code wird ein Ereignis als eine eindeutige Verbindung aus Hook und Operation definiert, wie z.b.»hook user, Operation login«, oder»hook nodeapi, Operation insert«. Bei jedem Auftreten dieser Operationen können Sie mit trigger.module eine Aktion auslösen. Um Verwirrungen vorzubeugen, sollten wir unsere Ausdrücke klarstellen: Ereignis (Event): Im allgemeinen Verständnis der Programmierung bezeichnet dieser Ausdruck in der Regel eine Nachricht, die von einer Komponente eines Systems an andere Komponenten gesendet wird. Hook: Diese in Drupal verwendete Technik ermöglicht es Modulen, sich in den Ausführungsfluss»einzuklinken«. Operation: Bezeichnet den Prozess, der innerhalb eines Hooks ausgeführt wird. Die Operation login ist z.b. eine Operation des user-hooks. Trigger: Bezeichnet eine Kombination aus einem Hook und einer Operation, mit der eine oder mehrere Aktionen verknüpft werden können. Beispielsweise kann die Aktion der Signalausgabe mit der Operation login des user-hooks verknüpft werden. 3.2 Grundlagen von Aktionen Eine Aktion ist etwas, das Drupal tut. Hier sehen Sie einige Beispiele: Einen Node auf die Titelseite befördern Einen Node von»nicht veröffentlicht«in»veröffentlicht«ändern Einen Benutzer löschen Eine versenden Jedes dieser Beispiele hat eine klar definierte Aufgabe. Programmierer werden in der vorstehenden Liste die Ähnlichkeit mit PHP-Funktionen bemerken. Beispielsweise können Sie eine senden, indem Sie die Funktion drupal_mail() in includes/ 73

5 mail.inc aufrufen. Aktionen ähneln Funktionen, weil sie Funktionen sind Funktionen, die Drupal prüfen und lose mit Ereignissen koppeln kann (mehr dazu in Kürze). Lassen Sie uns jetzt das Triggermodul untersuchen Die Benutzeroberfläche für Trigger Aktivieren Sie unter VERWALTEN > STRUKTURIERUNG > MODULE das Triggermodul. Rufen Sie dann VERWALTEN > EINSTELLUNGEN > TRIGGER auf. Sie sollten eine Benutzeroberfläche wie in Abbildung 3.1 sehen. Abbildung 3.1: Die Benutzeroberfläche zur Triggerzuweisung Beachten Sie die Registerkarten am oberen Rand. Sie entsprechen Drupal-Hooks! In Abbildung 3.1 sehen Sie die Registerkarte INHALT und damit die Operationen für den Hook nodeapi. Sie haben alle ausführliche Namen beispielsweise heißt die Operation delete des Hooks nodeapi»nachdem ein Beitrag gelöscht wurde«. Somit wird jede 74

6 3.2 Grundlagen von Aktionen Operation des Hooks angezeigt, wobei Sie ihr eine Aktion wie»beitrag auf der Startseite anzeigen«zuweisen können. Alle verfügbaren Aktionen sind in der Dropdownliste»Aktion auswählen«aufgeführt. Hinweis Nicht alle Aktionen sind für alle Trigger verfügbar, da einige Aktionen in bestimmten Zusammenhängen keinen Sinn haben. Sie würden z.b. die Aktion»Beitrag auf der Startseite anzeigen«nicht mit dem Trigger»Nachdem ein Beitrag gelöscht wurde«ausführen. Je nach Ihrer Installation können einige Trigger»Für diesen Trigger sind keine Aktionen vorhanden.«anzeigen. Tabelle 3.2 zeigt einige Triggernamen und ihre entsprechenden Hooks und Operationen. Hook Operation Triggername comment insert Nach dem Speichern eines neuen Kommentars comment update Nach dem Speichern eines aktualisierten Kommentars comment delete Nach dem Löschen eines Kommentars comment view Wenn ein Kommentar von einem authentifizierten Benutzer angesehen wird cron run Wenn Cron läuft nodeapi presave Wenn ein neuer Beitrag gespeichert oder ein bestehender Beitrag aktualisiert wird nodeapi insert Nachdem ein neuer Beitrag gespeichert wurde nodeapi update Nachdem ein aktualisierter Beitrag gespeichert wurde nodeapi delete Nachdem ein Beitrag gelöscht wurde nodeapi view Wenn Inhalt von einem angemeldeten Benutzer angesehen wird taxonomy insert Nachdem ein neuer Begriff in der Datenbank gespeichert wird taxonomy update Nachdem ein aktualisierter Begriff in der Datenbank gespeichert wird taxonomy delete Nachdem ein Begriff gelöscht wurde user insert Nachdem ein Benutzerprofil erstellt wurde user update Nachdem ein Benutzerprofil aktualisiert wurde user delete Nachdem ein Benutzer gelöscht wurde Tabelle 3.2: Wie Hooks, Operationen und Trigger in Drupal 6 zusammenhängen 75

7 Hook Operation Triggername user login Nachdem sich ein Benutzer angemeldet hat user logout Nachdem sich ein Benutzer abgemeldet hat user view Wenn ein Benutzerprofil angezeigt wird Tabelle 3.2: Wie Hooks, Operationen und Trigger in Drupal 6 zusammenhängen (Forts.) Eine erste Aktion Was müssen wir tun, damit unsere Signalfunktion eine vollwertige Aktion wird? Es sind die folgenden zwei Schritte auszuführen: 1. Informieren Sie Drupal darüber, welche Trigger die Aktion unterstützen soll. 2. Erstellen Sie die Funktion für die Aktion. Der erste Schritt wird durch die Implementierung von hook_action_info() erreicht. Für unser Signalmodul sollte sie wie folgt aussehen: * Implementierung von hook_action_info(). function beep_action_info() { $info['beep_beep_action'] = array( 'type' => 'system', 'description' => t('beep annoyingly' 'configurable' => FALSE, 'hooks' => array( 'nodeapi' => array('view', 'insert', 'update', 'delete' 'comment' => array('view', 'insert', 'update', 'delete' 'user' => array('view', 'insert', 'update', 'delete', 'login' 'taxonomy' => array('insert', 'update', 'delete' ); return $info; Der Funktionsname ist beep_action_info( da wir wie bei anderen Hookimplementierungen den Namen unseres Moduls (beep) zusammen mit dem des Hooks (action_info) verwenden. Wir geben ein Array zurück, das für jede Aktion im Modul einen Eintrag enthält. Da wir nur eine Aktion schreiben, haben wir nur einen Eintrag, dessen Schlüssel der Name der Funktion ist, die die Aktion ausführt: beep_beep_action(). Es ist praktisch, beim Lesen des Codes zu wissen, wann eine Funktion eine Aktion ist, sodass wir an den Namen unser Funktion beep_beep() die Endung _action anhängen, was zu beep_beep_action() führt. 76

8 3.2 Grundlagen von Aktionen Werfen wir nun einen genaueren Blick auf die Schlüssel unseres Arrays. type: Die Art der Aktion, die Sie schreiben. Drupal nutzt diese Information, um Aktionen in der Dropdownliste der Oberfläche für die Triggerzuweisung zu kategorisieren. Mögliche Typen sind system, node, user, comment und taxonomy. Um zu bestimmen, welche Art von Aktion Sie schreiben, können Sie sich fragen:»mit welchen Objekten arbeitet diese Aktion?«(Wenn die Antwort unklar ist oder»viele verschiedene Objekte!«lautet, verwenden Sie den Typ system.) description: Der benutzerfreundliche Name der Aktion, der in der Dropdownliste der Oberfläche für die Triggerzuweisung angezeigt wird. configurable: Bestimmt, ob die Aktion Parameter übernimmt oder nicht. hooks: In diesem Array aus Hooks müssen die einzelnen Einträge die Operationen angeben, die die Aktion unterstützt. Mithilfe dieser Informationen bestimmt Drupal, wo es angebracht ist, die möglichen Aktionen in der Oberfläche für die Triggerzuweisung anzuzeigen. Wir haben unsere Aktion für Drupal beschrieben, sodass wir sie nun erstellen können: * Simuliert ein akustisches Signal. Eine Drupal-Aktion. function beep_beep_action() { beep_beep(); Das war nicht zu schwierig, oder? Bevor wir weitermachen, sollten Sie beep_user() und beep_nodeapi() löschen, bzw. auskommentieren, da wir Trigger und Aktionen anstelle direkter Hookimplementierungen nutzen werden Zuweisen der Aktion Nun schauen wir uns VERWALTEN > STRUKTURIERUNG > TRIGGER erneut an. Wenn Sie alles richtig gemacht haben, sollte Ihre Aktion in der Benutzerschnittstelle verfügbar sein, wie in Abbildung 3.2 zu sehen ist. 77

9 Abbildung 3.2: Die Aktion sollte in der Benutzerschnittstelle Triggers auswählbar sein Ändern der von einer Aktion unterstützten Trigger Wenn Sie die Werte ändern, die definieren, welche Operationen diese Aktion unterstützt, können Sie in der Benutzerschnittstelle eine Änderung der Verfügbarkeit sehen. Die Aktion»Beep«ist z.b. nur dann für den Trigger»Nachdem ein Beitrag gelöscht wurde«verfügbar, wenn Sie beep_action_info() wie folgt ändern: * Implementierung von hook_action_info(). function beep_action_info() { $info['beep_beep_action'] = array( 'type' => 'system', 'description' => t('beep annoyingly' 'configurable' => FALSE, 'hooks' => array( 'nodeapi' => array('delete' ); return $info; 78

10 3.2 Grundlagen von Aktionen Aktionen, die alle Trigger unterstützen Wenn Sie Ihre Aktion nicht auf einen bestimmten Trigger oder eine Menge von Triggern beschränken möchten, können Sie angeben, dass sie alle Trigger unterstützt: * Implementierung von hook_action_info(). function beep_action_info() { $info['beep_beep_action'] = array( 'type' => 'system', 'description' => t('beep annoyingly' 'configurable' => FALSE, 'hooks' => array( 'any' => TRUE, ); return $info; Erweiterte Aktionen Es gibt im Wesentlichen zwei Arten von Aktionen: solche, die Parameter übernehmen, und solche, die keine übernehmen. Die Aktion»Beep«, mit der wir gearbeitet haben, übernimmt keine Parameter. Wenn sie ausgeführt wird, ertönt ein Signal, und das war's. Aber es kommt häufig vor, dass Aktionen etwas mehr Kontext benötigen. Eine Aktion»Sende eine «muss wissen, an wen sie die senden soll und wie der Betreff und die Nachricht selbst lauten. Eine solche Aktion benötigt einige Einstellungen aus einem Konfigurationsformular und wird erweiterte Aktion oder auch konfigurierbare Aktion genannt. Einfache Aktionen übernehmen keine Parameter, benötigen kein Konfigurationsformular und werden automatisch bei der Aktivierung des entsprechenden Moduls vom System zur Verfügung gestellt (über VERWALTEN > EINSTELLUNGEN > MODULE). Sie teilen Drupal mit, dass Sie eine erweiterte Aktion verfasst haben, indem Sie in der hook_action_info()-implementierung Ihres Moduls den Schlüssel configurable auf TRUE setzen, ein Formular zur Konfiguration der Aktion sowie einen optionalen Validierungs- und einen erforderlichen Übermittlungshandler bereitstellen, um das Formular zu verarbeiten. Die Unterschiede zwischen einfachen und erweiterten Aktionen sind in Tabelle 3.3 zusammengefasst. 79

11 Einfache Aktion Erweiterte Aktion Parameter Nein a Erforderlich Konfigurationsformular Nein Erforderlich Verfügbarkeit Automatisch Es muss eine Instanz der Aktion unter Verwendung der Einstellungsseite für Aktionen erstellt werden. Wert des Schlüssels configure FALSE TRUE in hook_action_info() Tabelle 3.3: Unterschiede zwischen einfachen und erweiterten Aktionen a. Die Parameter $object und $context sind bei Bedarf verfügbar. Lassen Sie uns eine erweiterte Aktion erstellen, die mehrere Tonsignale ausgibt. Die Anzahl der Signale soll in einem Konfigurationsformular angegeben werden können. Zunächst müssen wir Drupal mitteilen, dass diese Aktion konfigurierbar ist. Dazu fügen wir in der Implementierung des Hooks action_info von beep.module einen Eintrag für unsere neue Aktion ein. * Implementierung von hook_action_info(). function beep_action_info() { $info['beep_beep_action'] = array( 'type' => 'system', 'description' => t('beep annoyingly' 'configurable' => FALSE, 'hooks' => array( 'nodeapi' => array('delete' ); $info['beep_multiple_beep_action'] = array( 'type' => 'system', 'description' => t('beep multiple times' 'configurable' => TRUE, 'hooks' => array( 'any' => TRUE, ); return $info; 80

12 3.2 Grundlagen von Aktionen Lassen Sie uns schnell unter VERWALTEN > EINSTELLUNGEN > AKTIONEN überprüfen, ob wir die Implementierung korrekt durchgeführt haben. Tatsächlich erscheint die Aktion als Auswahlmöglichkeit in der Dropdownliste für die erweiterten Aktionen, wie Abbildung 3.3 zeigt. Abbildung 3.3: Die neue Aktion erscheint als Auswahlmöglichkeit Nun müssen wir ein Formular bereitstellen, damit der Administrator auswählen kann, wie viele Signaltöne er wünscht. Dazu definieren wir ein oder mehrere Felder unter Verwendung der Formular-API von Drupal. Außerdem schreiben wir Funktionen zur Validierung und Übermittlung des Formulars. Die Namen der Funktionen basieren auf der in hook_action_info() definierten Aktions-ID. Sie lautet für die hier betrachtete Aktion beep_multiple_beep_action, und wenn wir gemäß der Konvention ein _form an die Formulardefinition anhängen, erhalten wir beep_multiple_beep_action_form. Drupal erwartet eine Validierungsfunktion, deren Name aus der Aktions-ID plus _validate gebildet wird (beep_multiple_beep_action_validate sowie eine Übermittlungsfunktion mit der Endung _submit (beep_multiple_beep_action_submit). * Formular für eine konfigurierbare Drupal-Aktion, die einen * mehrfachen Piepton ausgibt. 81

13 function beep_multiple_beep_action_form($context) { $form['beeps'] = array( '#type' => 'textfield', '#title' => t('number of beeps' '#description' => t('enter the number of times to beep when this action executes.' '#default_value' => isset($context['beeps'])? $context['beeps'] : '1', '#required' => TRUE, ); return $form; function beep_multiple_beep_action_validate($form, $form_state) { $beeps = $form_state['values']['beeps']; if (!is_numeric($beeps)) { form_set_error('beeps', t('please enter a numeric value.')); else if ((int) $beeps > 10) { form_set_error('beeps', t('that would be too annoying. Please choose fewer than 10 beeps.')); function beep_multiple_beep_action_submit($form, $form_state) { return array( 'beeps' => (int) $form_state['values']['beeps'] ); Die erste Funktion beschreibt das Formular. Wir definieren lediglich ein einzelnes Textfeld, damit der Administrator die Anzahl der Signaltöne eingeben kann. Wenn der Administrator sich entscheidet, die erweiterte Aktion»Beep multiple times«hinzuzufügen, wie in Abbildung 3.3 gezeigt wird, verwendet Drupal unser Formularfeld, um ein vollständiges Formular zur Konfiguration der Aktion anzuzeigen, was in Abbildung 3.4 zu sehen ist. Drupal hat dem Konfigurationsformular ein Beschreibungsfeld hinzugefügt. Der Wert dieses Felds ist veränderbar und wird anstelle der Standardbeschreibung verwendet, die im Hook action_info definiert wurde. Das ist sinnvoll, denn wir könnten eine erweiterte Aktion erstellen, die zwei Signaltöne ausgibt, und ihr die Beschreibung»2 mal piepen«geben, sowie eine weitere, die fünf Pieptöne ausgibt und die Beschreibung»5 mal piepen«erhält. Auf diese Weise können wir den Unterschied zwischen den beiden erweiterten Aktionen erkennen, wenn wir sie einem Trigger zuweisen möchten. Erweiterte Aktionen können demnach auf eine für den Administrator sinnvolle Art und Weise beschrieben werden. 82

14 3.2 Grundlagen von Aktionen Abbildung 3.4: Das Konfigurationsformular für die Aktion»Beep multiple times«tipp Diese beiden Aktionen»2 mal piepen«und»5 mal piepen«können als Instanzen der Aktion»mehrfach piepen«bezeichnet werden. Die Validierungsfunktion ist eine der üblichen Formularvalidierungsfunktion von Drupal (weitere Informationen zur Formularvalidierung erhalten Sie in Kapitel 10). In diesem Fall führen wir eine Überprüfung durch, um sicherzustellen, dass der Benutzer tatsächlich eine Zahl eingegeben hat und diese Zahl nicht allzu hoch ist. Der Rückgabewert der Übermittlungsfunktion gilt eigens für Aktionskonfigurationsformulare. Er sollte ein Array mit den Feldern als Schlüssel sein, die uns interessieren. Die Werte dieses Arrays sind für die Aktion verfügbar, wenn sie ausgeführt wird. Die Beschreibung wird automatisch gehandhabt, sodass wir nur das verwendete Feld zurückgeben müssen, d.h., die Anzahl der Pieptöne. Nun ist es an der Zeit, die erweiterte Aktion selbst zu schreiben: * Konfigurierbare Aktion. Gibt die angegebene Anzahl von * Tonsignalen aus. function beep_multiple_beep_action($object, $context) { 83

15 for ($i = 0; $i < $context['beeps']; $i++) { beep_beep(); Sie sehen, dass die Aktion zwei Parameter übernimmt, $object und $context. Das steht im Gegensatz zu der zuvor geschriebenen einfachen Aktion, die keine Parameter verwendete. Hinweis Einfache Aktionen können dieselben Parameter übernehmen wie konfigurierbare. Da PHP Parameter ignoriert, die an eine Funktion übergeben werden, aber nicht in ihrer Signatur erscheinen, können wir einfach die Signatur unserer einfachen Aktion von beep_beep_action() auf beep_beep_action($object, $context) ändern, wenn wir etwas über den aktuellen Kontext wissen müssen. Alle Aktionen werden mit den Parametern $object und $context aufgerufen. 3.3 Den Kontext für Aktionen verwenden Wir haben festgestellt, dass die Signatur für Aktionen example_action($object, $context) lautet. Lassen Sie uns jeden dieser Parameter ausführlich untersuchen. $object: Viele Aktionen wirken auf eins der eingebauten Objekte von Drupal: Nodes, Benutzer, Vokabularbegriffe usw. Wird eine Aktion von trigger.module ausgeführt, so wird das gerade behandelte Objekt im Parameter $object an die Aktion übergeben. Soll z.b. eine Aktion ausgeführt werden, wenn ein neuer Node erstellt wird, enthält dieser Parameter das Node-Objekt. $context: Eine Aktion kann in vielen verschiedenen Kontexten aufgerufen werden. Aktionen geben durch Definition des Schlüssels hooks in hook_action_info() an, welche Trigger sie unterstützen. Aber Aktionen, die mehrere Trigger unterstützen, benötigen eine Möglichkeit, den Kontext zu bestimmen, in dem sie aufgerufen werden. Auf diese Weise kann eine Aktion je nach Kontext unterschiedlich reagieren Wie das Trigger-Modul den Kontext vorbereitet Betrachten wir ein Beispiel. Angenommen, Sie betreiben eine Website, die kontroverse Streitfragen präsentiert. Das Geschäftsmodell besteht darin, dass die Benutzer für die Registrierung zahlen und nur einen einzigen Kommentar auf der Website hinterlassen dürfen. Sobald sie ihren Kommentar eingetragen haben, werden sie gesperrt und müssen erneut bezahlen, um die Sperrung aufzuheben. Ungeachtet der wirtschaftlichen Aussichten für eine solche Site konzentrieren wir uns darauf, wie wir das 84

16 3.3 Den Kontext für Aktionen verwenden mit Triggern und Ereignissen einrichten können. Wir benötigen eine Aktion, die den aktuellen Benutzer sperrt. Wenn wir user.module untersuchen, stellen wir fest, dass Drupal bereits die passende Aktion bereithält: * Implementierung von hook_action_info(). function user_action_info() { return array( 'user_block_user_action' => array( 'description' => t('block current user' 'type' => 'user', 'configurable' => FALSE, 'hooks' => array( 'user_block_ip_action' => array( 'description' => t('ban IP address of current user' 'type' => 'user', 'configurable' => FALSE, 'hooks' => array( ); Diese Aktionen sind jedoch nicht auf der Triggerzuweisungsseite zu sehen, weil sie keine unterstützten Hooks deklarieren der Schlüssel hooks ist lediglich ein leeres Array. Wenn wir das nur ändern könnten! Aber das können wir. Vorhandene Aktionen mit drupal_alter() ändern Wenn Drupal den Hook action_info ausführt, sodass alle Module die verfügbaren Aktionen deklarieren können, gibt das Programm ihnen auch eine Möglichkeit, diese Information zu ändern auch Informationen, die andere Module bereitstellen. Im Folgenden sehen Sie, wie wir die Aktion»Aktuellen Benutzer sperren «für den Trigger zum Einfügen von Kommentaren verfügbar machen: * Implementierung von hook_drupal_alter(). Wird von Drupal nach * hook_action_info() aufgerufen, sodass Module das Array * action_info verändern können. * array $info * Das Ergebnis des Aufrufs von hook_action_info() für alle Module. function beep_action_info_alter(&$info) { // Macht die Aktion "Aktuellen Benutzer sperren " für den // Trigger zum Einfügen von Kommentaren verfügbar. // Wenn bereits andere Module das Array verändert haben, // lassen wir diese bestehen; wir stellen lediglich sicher, 85

17 // dass die Operation 'insert' vorhanden ist. // Andernfalls weisen wir sie zu. if (isset($info['user_block_user_action']['hooks']['comment'])) { array_merge($info['user_block_user_action']['hooks'] ['comment'], array('insert')); else { $info['user_block_user_action']['hooks']['comment'] = array('insert'); Als Endergebnis lässt sich die Aktion»Aktuellen Benutzer sperren«jetzt zuweisen, wie Abbildung 3.5 zeigt. Abbildung 3.5: Zuweisen der Aktion»Aktuellen Benutzer sperren «an den Trigger zum Einfügen von Kommentaren Einrichten des Kontextes Aufgrund der von uns zugewiesenen Aktion wird der aktuelle Benutzer gesperrt, wenn er einen neuen Kommentar hinzugefügt hat. Lassen Sie uns genauer anschauen, wie das geschieht. Wir wissen bereits, dass Drupal Module über das Auftreten bestimmter Ereignisse informiert, indem es einen Hook auslöst. In diesem Fall handelt es sich um den Hook comment. Da ein neuer Kommentar hinzugefügt wird, wird die Operation insert ausgeführt. Das Trigger-Modul implementiert den Hook 86

18 3.3 Den Kontext für Aktionen verwenden comment. Innerhalb des Hooks ermittelt es mithilfe einer Datenbankabfrage, ob diesem Trigger irgendwelche Aktionen zugewiesen sind. Die Datenbank übergibt ihm die Information über die von uns zugewiesene Aktion»Aktuellen Benutzer sperren«. Nun ist das Trigger-Modul bereit, die Aktion auszuführen, die die standardmäßige Funktionssignatur example_action($object, $context) hat. Doch wir haben ein Problem. Die Aktion, die ausgeführt werden soll, hat den Typ user, nicht comment. Sie erwartet als übergebenes Objekt ein user-objekt! Doch hier wird eine user-aktion im Kontext eines comment-hooks aufgerufen. Der Hook hat Informationen über den Kommentar erhalten, aber nicht über den Benutzer. Was sollen wir tun? Das Trigger-Modul bestimmt, dass unsere Aktion eine user-aktion ist und lädt das von ihr erwartete Objekt $user. Im Folgenden sehen Sie Code aus modules/trigger/trigger.module, der diesen Vorgang zeigt: * Wenn eine Aktion in einem Kontext aufgrufen wird, die nicht mit * ihrem Typ übereinstimmt, muss das Objekt, das die Aktion * erwartet, abgerufen werden. Wird z.b. eine Aktion für Nodes * im comment-hook aufgerufen, ist das Node-Objekt nicht verfügbar, * da der comment-hook es nicht übergeben hat. Daher laden wir hier * das Objekt, das die Aktion erwartet. * $type * Die Art von Aktion, die aufgerufen wird $comment * Der über den comment-hook übergebene Kommentar * Das von der aufgerufenen Aktion erwartete Objekt function _trigger_normalize_comment_context($type, $comment) { switch ($type) { // Eine Aktion, die mit Nodes arbeitet, wird in einem comment- // Kontext aufgerufen. case 'node': return node_load($comment['nid']); // Eine Aktion, die mit Benutzern arbeitet, wird in einem // comment-kontext aufgerufen. case 'user': return user_load(array('uid' => $comment['uid'])); Wenn der vorstehende Code für unsere user-aktion ausgeführt wird, tritt der zweite Fall ein, sodass das user-objekt geladen und dann unsere user-aktion ausgeführt wird. Die Information, die der comment-hook kennt (beispielsweise der Betreff des Kommentars) wird der Aktion im Parameter $context übergeben. Beachten Sie, dass die Aktion die ID des Benutzers erst im Objekt und dann im Kontext sucht und schließlich auf den globalen $user zurückfällt: 87

19 * Implementierung einer Drupal-Aktion. * Sperrt den aktuellen Benutzer. function user_block_user_action(&$object, $context = array()) { if (isset($object->uid)) { $uid = $object->uid; elseif (isset($context['uid'])) { $uid = $context['uid']; else { global $user; $uid = $user->uid; db_query("update {users SET status = 0 WHERE uid = %d", $uid); sess_destroy_uid($uid); watchdog('action', 'Blocked user %name.', array('%name' => check_plain($user->name))); Aktionen müssen eine gewisse Intelligenz besitzen, weil sie nicht viel darüber wissen, was bei ihrem Aufruf geschieht. Daher sind die besten Kandidaten für Aktionen einfach, ja elementar. Das Triggermodul übergibt im Kontext stets den aktuellen Hook und die aktuelle Operation. Diese Werte sind in $context['hook'] und $context['op'] gespeichert. Dieser Ansatz bietet eine standardisierte Methode zur Übergabe von Informationen an eine Aktion. 3.4 Untersuchen des Kontextes Die Tatsache, dass der Hook und die Operation im Kontext verfügbar sind, ist außerordentlich wertvoll. Ein Beispiel für eine Aktion, die das sehr stark ausnutzt, ist» senden«. Es ist eine Aktion vom Typ system, die vielen verschiedenen Triggern zugewiesen werden kann. Die Aktion» senden«ermöglicht es, beim Erstellen der bestimmte Token zu ersetzen. So können Sie z.b. den Titel eines Nodes in den Text der einfügen oder den Autor des Nodes als Empfänger festlegen. Doch je nachdem, welchem Trigger die Aktion zugewiesen wird, ist der Empfänger möglicherweise nicht verfügbar. Wird z.b. im user-hook eine gesendet, ist kein Node und somit auch kein Autor eines Nodes als Empfänger verfügbar. Die Aktion» senden«in modules/system/system.module verbringt einige Zeit damit, den Kontext zu untersuchen, um zu bestimmen, was verfügbar ist. Im folgenden Code stellt sie sicher, dass sie einen Node hat, damit mit einem Node verbundene Ersetzungen stattfinden können: 88

20 3.5 Wie Aktionen gespeichert werden * Implementierung einer konfigurierbaren Drupal-Aktion. * Verschickt eine . function system_send_ _action($object, $context) { global $user; switch ($context['hook']) { case 'nodeapi': // Da dies keine Aktion vom Typ 'node' ist (sondern vom Typ // 'system' wird der Node nicht als $object übergeben, // ist aber weiterhin in $context verfügbar. $node = $context['node']; break; case 'comment': // Der comment-hook stellt in $context die nid zur // Verfügung. $comment = $context['comment']; $node = node_load($comment->nid); case 'user': // Da dies keine Aktion vom Typ 'user' ist, wird das user- // Objekt nicht als $object übergeben, ist aber weiterhin // in $context verfügbar. $account = $context['account']; if (isset($context['node'])) { $node = $context['node']; elseif ($context['recipient'] == '%author') { // Wenn wir keinen Node haben, haben wir keinen Autor // des Nodes. watchdog('error', 'Cannot use %author token in this context.'); return; break; default: // Direkter Aufruf. $node = $object; Wie Aktionen gespeichert werden Aktionen sind Funktionen, die zu einer bestimmten Zeit ausgeführt werden. Einfache Aktionen haben keine konfigurierbaren Parameter. Beispielsweise gab die von uns erstellte Aktion»Beep«lediglich einen Piepton aus und benötigte keine weiteren Informationen (obwohl $object und $context natürlich bei Bedarf verfügbar sind). Stellen Sie diese Aktion der Erweiterten gegenüber. Die Aktion»Mehrfach piepen«musste 89

21 wissen, wie oft sie den Signalton ausgeben soll. Andere erweiterte Aktionen, z.b.» senden«, benötigen noch mehr Informationen: den Empfänger und den Betreff der usw. Diese Parameter müssen in der Datenbank gespeichert werden Die Tabelle actions Wenn der Administrator eine Instanz einer erweiterten Aktion erstellt, werden die im Konfigurationsformular eingegebenen Informationen serialisiert und im Feld parameters der Tabelle actions gespeichert. Ein Eintrag für die einfache Aktion»Beep«würde wie folgt aussehen: aid: 'beep_beep_action' type: 'system' callback: 'beep_beep_action' parameters: description: Piep Im Gegensatz dazu lautet der Eintrag für eine Instanz der Aktion»Mehrfach piepen«folgendermaßen: aid: 2 type: 'system' callback: 'beep_beep_action' parameters: (serialisiertes Array, das den Parameter beeps mit seinem Wert enthält, d.h. die Anzahl der Signaltöne) description: 5 mal piepen Unmittelbar vor dem Ausführen einer erweiterten Aktion wird der Inhalt des Felds parameters deserialisiert und in den Parameter $context aufgenommen, der an die Aktion übergeben wird. Somit erhält beep_multiple_beep_action() die Anzahl der Signaltöne in der Instanz unserer Aktion»mehrfach piepen«als $context['beeps'] Aktions-IDs Beachten Sie den Unterschied zwischen den Aktions-IDs der beiden Tabelleneinträge im vorstehenden Abschnitt. Die Aktions-ID der einfachen Aktion ist der tatsächliche Funktionsname. Doch offensichtlich können wir diesen Namen nicht zur Kennzeichnung erweiterter Aktionen verwenden, da mehrere Instanzen derselben Aktion gespeichert werden. Daher wird stattdessen eine numerische Aktions-ID verwendet (die in der Datenbanktabelle als aid gespeichert wird). Die Ausführungs-Engine für Aktionen bestimmt anhand der Aktions-ID, ob sie gespeicherte Parameter für eine Aktion ermitteln muss. Ist die ID nicht numerisch, wird die Aktion einfach ausgeführt, ohne die Datenbank abzufragen. Das geht sehr schnell. Drupal verwendet dasselbe Verfahren in index.php, um Inhalt von Menükonstanten zu unterscheiden. 90

22 3.6 Eine Aktion direkt mit actions_do() aufrufen 3.6 Eine Aktion direkt mit actions_do() aufrufen Das Trigger-Modul stellt nur eine Möglichkeit zum Aufruf von Aktionen dar. Sie können ein gesondertes Modul erstellen, das Aktionen aufruft, und die Parameter selbst vorbereiten. In diesem Fall ist actions_do() das empfohlene Verfahren für den Aufruf. Die Funktion hat die folgende Signatur: actions_do($action_ids, &$object, $context = array( $a1 = NULL, $a2 = NULL) Lassen Sie uns diese Parameter untersuchen: $action_ids: Die auszuführenden Aktionen, entweder eine einzelne Aktions-ID oder ein entsprechendes Array $object: Das Objekt, an dem die Aktion ausgeführt wird, sofern vorhanden $context: Assoziatives Array mit Informationen, die die Aktion möglicherweise nutzen möchte, z.b. Parameter für erweiterte Aktionen $a1 und $a2: Optionale zusätzliche Parameter, die an die Aktion übergeben werden, sofern actions_do() sie erhält Hier sehen Sie, wie wir unsere einfache Aktion»Beep«mit actions_do() aufrufen können: $object = NULL; // $object ist ein notwendiger Parameter, der aber // in diesem Fall nicht verwendet wird actions_do('beep_beep_action', $object); Und hier folgt der Aufruf der erweiterten Aktion»Mehrfach piepen«: $object = NULL; actions_do(2, $object); Wir können sie auch aufrufen und die Abfrage der gespeicherten Parameter wie folgt umgehen: $object = NULL; $context['beeps'] = 5; actions_do('beep_multiple_beep_action', $object, $context); 91

23 Hinweis Vollblut-PHP-Entwickler fragen sich vielleicht:»warum soll man überhaupt Aktionen verwenden? Warum ruft man die Funktion nicht direkt auf oder implementiert lediglich einen Hook? Warum quält man sich mit versteckten Parametern im Kontext, nur um sie wieder abzurufen, anstatt traditionelle PHP-Parameter zu verwenden?«die Antwort lautet, dass der Siteadministrator selbst den Code wiederverwenden kann, wenn Aktionen mit einer sehr allgemeinen Funktionssignatur eingesetzt werden. Auch wenn der Administrator keine PHP-Kenntnisse besitzt, muss er keinen PHP-Entwickler damit beauftragen, eine Funktion zum Versenden einer zu erstellen, wenn ein neuer Node hinzugefügt wird. Er verbindet einfach die Aktion» senden«mit dem Trigger, der beim Speichern eines neuen Nodes ausgelöst wird, und braucht niemanden um Hilfe zu bitten. 3.7 Eigene Trigger mit hook_hook_info() definieren Woher weiß Drupal, welche Trigger zur Anzeige in der Benutzeroberfläche verfügbar sind? Auf seine typische Weise lässt es Module Hooks definieren, die angeben, welche Hooks das Modul implementiert. Im folgenden Beispiel sehen Sie die Implementierung von hook_hook_info() aus comment.module. Hier werden die Triggerbeschreibungen definiert. * Implementierung von hook_hook_info(). function comment_hook_info() { return array( 'comment' => array( 'comment' => array( 'insert' => array( 'runs when' => t('after saving a new comment' 'update' => array( 'runs when' => t('after saving an updated comment' 'delete' => array( 'runs when' => t('after deleting a comment') 'view' => array( 'runs when' => t('when a comment is being viewed by an authenticated user') ); 92

24 3.7 Eigene Trigger mit hook_hook_info() definieren Wenn wir ein Modul namens monitoring.module installiert hätten, das in Drupal einen neuen Hook mit der Bezeichnung monitoring-hook einführt, könnte es seine beiden Operationen (overheating und freezing) wie folgt beschreiben: * Implementierung von hook_hook_info(). function monitoring_hook_info() { return array( 'monitoring' => array( 'monitoring' => array( 'overheating' => array( 'runs when' => t('when hardware is about to melt down' 'freezing' => array( 'runs when' => t('when hardware is about to freeze up' ); Nach der Aktivierung dieses Monitoring-Moduls greift Drupal die neue Implementierung von hook_hook_info() auf und ändert die Triggerseite ab, sodass sie eine gesonderte Registerkarte für den neuen Hook enthält, wie Abbildung 3.6 zeigt. Natürlich ist das Modul selbst weiterhin dafür verantwortlich, die Hooks mit module_invoke() oder module_invoke_all() und die Aktionen auszulösen. In diesem Beispiel muss das Modul module_invoke_all('monitoring', 'overheating') aufrufen. Anschließend muss es hook_monitoring($op) implementieren und die Aktionen mit actions_do() auslösen. Eine einfache Implementierung finden Sie in trigger_cron() aus modules/trigger/ trigger.module. Abbildung 3.6: Der neu definierte Trigger erscheint als Registerkarte in der Benutzerschnittstelle 93

25 Zwar kann ein Modul mehrere neue Hooks definieren, doch erstellt nur derjenige Hook eine neue Registerkarte in der Benutzerschnittstelle, der dem Modulnamen entspricht. In unserem Beispiel definierte das Monitoring-Modul den monitoring-hook. Wenn es noch einen anderen Hook definiert hätte, wäre dieser weder auf der Monitoring-Registerkarte sichtbar, noch hätte er eine eigene. Ein Hook, der nicht mit dem Modulnamen übereinstimmt, ist jedoch weiterhin auf verfügbar. 3.8 Trigger zu bestehenden Hooks hinzufügen Es kann manchmal vorkommen, dass Sie Trigger zu einem bestehenden Hook hinzufügen möchten, wenn Ihr Code um eine neue Operation erweitert wird. Betrachten Sie den Fall, dass Sie den Hook nodeapi um eine neue Operation ergänzen wollen. Angenommen, Sie haben ein Modul geschrieben, das alte Nodes archiviert und sie in ein Data Warehouse verschiebt. Dafür können Sie einen kompletten neuen Hook definieren, was durchaus angebracht wäre. Aber da diese Operation an einem Node stattfindet, können Sie stattdessen eine archive-operation im Hook nodeapi auslösen, damit alle Operationen, die den Inhalt betreffen, auf derselben Registerkarte in der Benutzerschnittstelle für Trigger erscheinen. Der folgende Code fügt einen zusätzlichen Trigger hinzu: * Implementiert einen neuen Trigger, der in der Node-Registerkarte erscheint. function archiveoffline_hook_info() { $info['archiveoffline'] = array( 'nodeapi' => array( 'archive' => array( 'runs when' => t('when the post is about to be archived' ); return $info; Der neue Trigger ist jetzt am Ende der Liste auf der Verwaltungsseite für Trigger unter VERWALTEN > STRUKTURIERUNG > TRIGGER verfügbar, wie in Abbildung 3.7 zu sehen ist. 94

26 3.8 Trigger zu bestehenden Hooks hinzufügen Abbildung 3.7: Der zusätzliche Trigger (»When the post is about to be archived«) erscheint in der Benutzerschnittstelle Das Menüsystem von Drupal nutzt den ersten Schlüssel in der Implementierung von hook_hook_info( um automatisch eine Registerkarte auf der Verwaltungsseite für Trigger zu erstellen. Drupal benennt die Registerkarte mit dem Modulnamen, der in der zugehörigen.info-datei definiert wird (siehe die unbenutzte Registerkarte ARCHIVE OFFLINE in Abbildung 3.7). Aber unser neuer Trigger muss nicht auf seine eigene Registerkarte gestellt werden. Wir haben ihn absichtlich auf der Registerkarte INHALT platziert, indem wir dem Hook nodeapi unsere eigene Operation hinzugefügt haben. Mithilfe von hook_menu_alter() können wir die unerwünschte Registerkarte entfernen (in Kapitel 4 erhalten Sie weitere Informationen darüber, wie dieser Hook funktioniert). Der folgende Code ändert die automatisch erstellte Registerkarte vom Typ MENU_LOCAL_TASK (den Drupal standardmäßig als Registerkarte darstellt) in den Typ MENU_CALLBACK, den Drupal nicht anzeigt: 95

27 * Implementierung von hook_menu_alter(). function archiveoffline_menu_alter(&$items) { $items['admin/build/trigger/archiveoffline']['type'] = MENU_CALLBACK; Damit die Funktion archiveoffline_menu_alter() in Kraft tritt, müssen Sie VERWALTEN > STRUKTURIERUNG > MODULE aufrufen, sodass die Menüs neu erstellt werden. 3.9 Zusammenfassung Nach der Lektüre dieses Kapitels sollten Sie die folgenden Dinge beherrschen: Aktionen zu Triggern hinzufügen Eine einfache Aktion schreiben Eine erweiterte Aktion und das zugehörige Konfigurationsformular schreiben Erklären, was ein Kontext ist Erklären, wie Aktionen den Kontext verwenden können, um ihr Verhalten zu ändern Erklären, wie Aktionen gespeichert, abgerufen und ausgeführt werden Ihre eigenen Hooks definieren und sie als Trigger anzeigen lassen 96