Anmelden oder ein neues Benutzerkonto anlegen.

Dokumentation » Plugin API


Inhaltsverzeichnis

Plugin API

Diese Seite dokumentiert die API (Application Programming Interface), die vorhandenen Hooks und deren Anwendung


Hooks, Actions und Filters

Hooks werden von easyLink selbst bereitgestellt. Dabei handelt es sich um Ankerpunkte im Script an denen Sie einzelne Funktionen Ihres Plugins "einhaken" können. Die eingehakten Funktionen werden also bei erreichen der Hooks vom Script ausgeführt.

Man unterscheidet dabei zwischen 2 Arten von Hooks:

  1. Actions: Actions sind Hooks, die easyLink entweder an bestimmten Punkten im Script oder bei bestimmten Ereignissen startet. Über die Plugin API können Sie diesen Punkten ein oder mehrere PHP Funktionen zuweisen, dann dann entsprechend vom Script ausgeführt werden.
  2. Filter: Filter sind Hooks, die easyLink startet, bevor bestimmte Werte (Variablen) auf dem Bildschirm ausgegeben- oder in der Datenbank gespeichert werden. Über die Plugin API können Sie den jeweiligen Filtern eine oder mehrere PHP Funktionen zuweisen, die anschließend beim Aufruf des entsprechenden Filters zur Anwendung kommen.

Oftmals lassen sich bestimmte Ziele sowohl mit einem Action-Hook, als auch mit einem Filter-Hook erreichen. Es liegt daher an Ihnen abzuwägen, ob die gewünschten Änderungen durch eine bestimmte Aktion- oder bei der Ausgabe ausgelöst werden sollen.


Actions

Action-Hooks werden in easyLink durch spezielle Ereignisse ausgelöst. Das kann z.B. das Freischalten eines neuen Eintrages oder auch das Erreichen einer bestimmten Stelle im Scriptablauf sein. Ihr Plugin kann auf einen solchen Aufruf mit der Ausführung einer PHP Funktion reagieren, mit deren Hilfe Sie z.B. eine oder mehrere Aktionen einleiten könnten:

  1. Verändern Sie die Datenbank - Daten
  2. Versenden Sie eine E-Mail Nachricht
  3. Verandern Sie die Anzeige im Browser bzw. auf dem Bildschirm (Admin oder Benutzer)

Um dieses zu erreichen, sind folgende grundlegende Schritte notwendig:

  1. Erstellen Sie die PHP-Funktion, die beim Eintritt eines Ereignisses aufgerufen werden soll.
  2. Haken Sie Ihre Funktion mit Hilfe von AddAction() in einem bestimmten Action-Hook ein.
  3. Speichern Sie beides in einer Plugin-Datei und aktivieren Sie diese.


Erstellen einer Action Funktion

Der erste Schritt für die Nutzung von Actions ist die Erstellung einer PHP Funktion, die die von Ihnen gewünschten Funktionalitäten beinhaltet. Diese Funktion speichern Sie anschließend ein einer Plugindatei im Order /plugins/. Wenn Sie z.B. möchten, dass Ihre Freunde eine E-Mail bei Aktivierung eines Plugins bekommen, dann könnten Sie folgende Funktion nutzen: 

function MailFriends()  {
    $friends = 'friend1@domain.de,friend2@domain.de';
    
    mail($friends, "Ein Plugin wurde aktiviert", "Auf der Website http://www.domain.de wurde ein neues Plugin aktiviert.");
}

Natürlich macht eine solche Funktion nur wenig Sinn, denn warum sollten sich Ihre Freunde dafür interessieren, wenn Sie ein Plugin aktivieren? Aber mit diesem Beispiel läßt sich sehr gut das Prinzip von Action-Hooks erläutern und darum verwenden wir es hier.

Hinweis: Bitte beachten Sie, dass in anderen Plugins oder im Kern von easyLink bereits Funktionen mit dem gleichen Namen vorhanden sein können. In einem solchen Fall würde dieses zu einer Nameskollision und somit zu einem Funktionsabruch bei der Aktivierung des Plugins führen. Eine solches Problem können Sie ganz leicht durch umbennen Ihrer Funktion beseitigen.


Action Funktion im Kern einhaken

Wenn Sie Ihre Funktion definiert haben, besteht der nächste Schritt darin, diese in einem Hook des easyLink Kerns zu verankern. Um dieses zu tun, rufen Sie bitte die Funktion AddAction() auf. Diese Funktion steht Ihnen im gesamtem Script zur Verfügung. 

AddAction( 'hookname', 'functionsname', [priorität], [argumente] );
  1. hookname ist die Bezeichnung des Hooks in den Ihre Funktion eingehakt werden soll. Die verschiedenen Hooks werden durch die Kernengine selbst bereitgestellt und können in der Regel nicht modifiziert werden.
  1. functionsname ist der Name der Funktion, die an der Stelle von hookname ausgeführt werden soll. Es kann sich dabei um eine Standard PHP Funktion, eine der easyLink Kernfunktionen oder um eine von Ihnen in einem Plugin definierte Funktion handeln.
  1. priorität ist ein Integerwert (Standard: 10) mit dem Sie die Reihenfolge der Ausführung bestimmen können. Niedrige Werte entsprechen einer früheren Ausführung und höhere Werte einer späteren Ausführung. Funktionen mit gleicher Priorität werden in der Reihenfolge ausgeführt, in der sie dem Hook zugewiesen wurden.
  1. argumente ist ein Integerwert (Standard: 1) mit dem Sie die Anzahl der Argumente Ihrer Funktion definieren können. Dieser Parameter ist sehr nützlich, da einige Hooks mehrere Parameter zulassen.


Für unser Beispiel würden wir also die folgende Zeile in die Plugin-Datei schreiben: 

AddAction('ActivatePlugin', 'MailFriends');

Ebenso einfach lassen sich Actions von den jeweiligen Hook wieder trennen. Lesen Sie bitte dazu den entsprechenden Abschnitt.


Installation und Aktivierung

Der letzte Schritt um in Plugins mit Actions zu arbeiten, ist die Installation des Codes selbst. Um bei unserem Beispiel zu bleiben, speichern die Ihre erstellte Funktion und den oben beschriebenen Aufruf zusammen in einer Datei. Diese Datei kopieren Sie anschließend und in das Verzeichnis /plugins/ und damit ist die meiste Arbeit auch schon erledigt.

Nun können Sie Ihr neues Plugin ganz bequem im Adminbereich aktivieren.


Aktuelle Hooks für Actions

Eine aktuelle Liste der vorhandenen Action-Hooks finden Sie hier: Plugin API/Action Referenz

Filter

Aktuelle Hooks für Filter

Eine aktuelle Liste der vorhandenen Filter-Hooks finden Sie hier: Plugin API/Filter Referenz


Actions und Filter entfernen

In einigen Fällen kann es unter Umständen auch notwendig sein, dass Sie bestimmte in easyLink bereits vorhandene oder durch Plugins hinzugefügte Actions und Filter wieder deaktivieren müssen. Dieses können Sie ganz bequem über den folgenden Aufruf machen: 

RemoveFilter('filter_hook', 'function');

oder 

RemoveAction('action_hook', 'function');

So wurde der Aufruf von RemoveFilter('SearchIP', 'HideIPAdress'); z.B. dafür sorgen, dass die IP Adressen der Livesuche bei der Ausgabe nicht mehr maskiert werden.

Hinweis: Sofern eine Funktion mit einer anderen Prioriät als 10 mit dem Hook verbunden wurde, so müssen Sie die entsprechende Priorität auch beim Aufruf von RemoveFilter() oder RemoveAction() angeben. Grundsätzlich sollten Sie jedoch keine Funktionen von Hooks entfernen, wenn Sie nicht zu 100% wissen, was Sie da tun, denn ansonsten könnten Sie ungewollt massive Sicherheitslücken im Script öffnen.


Default - Filter

Einige Hooks werden von easyLink bereits von Anfang an mit bestimmten Funktionen belegt. Diese Standardzuweisung finden Sie in der Datei /lib/plugin/PluginAPI.class unter der Methode PluginAPI::SetDefaultFilter. Sofern Sie eine Standardzuweisung entfernen möchten, bietet es sich an, dieses über ein gesondertes Plugin zu tun.

Eine weitere und wahrscheinlich auch die sicherste Methode um alle Standardzuweisungen in der Software zu finden, ist die Möglichkeit die easyLink Kernfunktionen bzw. deren Quelltext nach den Aufrufen von AddFilter und AddAction zu durchsuchen.


Diese Funktionen können Sie überschreiben

Neben den oben beschrieben Hooks (Action und Filter) haben Sie auch die Möglichkeit, das Verhalten von easyLink über bestimmte Funktionen zu steuern. Diese Funktionen werden von easyLink nur dann in den Speicher geladen, wenn sie nicht bereits zuvor in einem Plugin definiert wurden.

Alle überschreibaren Funktionen befinden sich in der Datei: /lib/plugin/Plugable.func.php

Eine Dokumentation zu einigen der Funktionen finden Sie in der Funktions Referenz

  • AddNoFollow
  • checkForbiddenEmail
  • checkForbiddenIP
  • ConvertLinkToTag
  • ConvertSmilieTag
  • getAvatar
  • getCategory
  • getCategoryChildren
  • getCategoryDropDown
  • getCategoryNavTrail
  • getCategoryParents
  • getCategoryTableRows
  • getSmilieList
  • getSubcatsFromCategory
  • getvCardsFromCategory
  • HideEMailAdress
  • HideIPAdress
  • HighlightKeywords
  • MakeClickable
  • MakeEmailClickableCallback
  • MakeUrlClickableCallback
  • ParseMetaTags
  • ReplaceBadwords
  • SanitizeSearchString
  • SanitizeTitle
  • UpdateCategoryCount
  • UpdatePagerank

Externe Informationen

Einige Informationen zu PluginAPI finden Sie auch in unserem Blog:

Von „http://doku.mountaingrafix.at/index.php?title=Plugin_API“