diff --git a/Plugin-Hooks.md b/Plugin-Hooks.md new file mode 100644 index 0000000..cb9ad3e --- /dev/null +++ b/Plugin-Hooks.md @@ -0,0 +1,181 @@ +Diese Referenz listet sämtliche Plugin-Hooks von Jlog auf und dokumentiert diese. Hooks sind die Schnittstellen zwischen Plugins und Jlog und werden bei bestimmten Ereignisse (z.B. „neuer Kommentar“) aufgerufen. Sie soll so geschrieben sein, dass man mit Hilfe des [Plugin-Tutorials](Plugin-Tutorial) und den bisherigen [Plugins](Plugins) selbst schnell neue Plugins erstellen kann. + +## TODO + +Du bist herzlich dazu eingeladen, die Referenz zu erweitern. + +doTeaser, permalink, xmlrpcPermalink, countComments, commentorMail, previewComment, dispatchLogin, loginForm, adminMenu, adminList + +## Hooks für die Jlog-Seiten +### hook_body + +Mit Hilfe dieses Hooks lässt sich die komplette Anzeige einer Jlog-Seite manipulieren. Dieser Hook wird nach dem Verarbeiten des Templates aufgerufen, d.h. eigene Template-Erweiterungen stehen hier dann zur Verfügung. Es können aber auch zusätzliche Informationen eingefügt oder bestehende entfernt werden. + +**Parameter:** +* $body, der komplette HTML-Code bis dahin + +**Rückgabe:** $body mit eigenen Veränderungen + +### hook_doEntry + +Dieser Hook wird aufgerufen, nachdem die HTML-Darstellung eines Artikels („der Inhalt“) komplett erstellt worden ist und bevor dieser HTML-Code an den Browser gesendet wird. Die Funktion hat Zugriff auf diesen HTML-Code, so dass ein Postprocessing durchgeführt werden kann oder zum Anhängen von Code für weitere Informationen (z.B. Anhänge oder „Digg this“). + +**Parameter:** + +* $output enthält den HTML-Code für die Ausgabe +* $dbData enthält sämtliche Artikelinformationen aus der Datenbank +* $cc ist die Anzahl an Kommentaren +* $section "weblog" oder "page" + +**Rückgabe:** $output erweitert mit eigenem HTML-Code + +## Hooks zur Erweiterung von BBCode +### hook_bbcode + +Mit Hilfe dieses Hooks können weitere, eigene BBCode-Tags in Jlog definiert und benutzt werden. Der Hook wird bei der Ausgabe eines Artikels für den kompletten Text des Beitrags aufgerufen. + +**Parameter:** +* $bbcode, die globale BBCode-Verwaltung + +**Rückgabe:** Das um eigene Parser erweiterte BBCode-Objekt $bbcode. + +Innerhalb der Methode kann mit `$bbcode->addCode()` und `$bbcode->addParser()` ein neuer Parser hinzugefügt werden. Was dabei zu beachten ist und wie die BBCode-Methoden funktionieren ist in der Dokumentation der [StringParser-Klasse](http://christian-seiler.de/projekte/php/bbcode/) beschrieben. + +### hook_bbccomments + +Siehe [hook_bbcode][hook_bbcode]. + +## Hooks beim Aktualisieren von Artikeln +### hook_insertEntry + +Dieser Hook wird beim Abspeichern eines neuen Artikels aufgerufen und erhält als Argument alle Werte des „Admin-Forms“. Damit ist ein Zugriff auf eventuell zusätzlich hinzugefügte Formularfelder möglich (siehe [hook_adminForm][hook_adminForm]). + +**Parameter:** + +* $id ist die ID des neuen Artikels +* $form_input enthält die bereits für SQL maskierten Formularwerte + +**Rückgabe:** `void` + +### hook_updateEntry + +Analog zu [hook_insertEntry][hook_insertEntry] wird dieser Hook beim Aktualisieren eines Artikels mit den Formularwerten aufgerufen. + +**Parameter:** + +* $id ist die ID des neuen Artikels +* $form_input enthält die bereits für SQL maskierten Formularwerte + +**Rückgabe:** `void` + +### hook_onUpdate + +Dieser Hook wird beim Aktualisieren eines Artikels (ändern oder neuen anlegen) aufgerufen. So ist es z.B. möglich, auf diese Weise eigene, erweiterte Newsfeeds zu erstellen oder andere Aktionen auszuführen, die über einen aktualisierten Artikel informiert werden sollten. + +**Parameter:** +* $data, enthält die Daten der RSS-Feeds _personal/rss.xml_ in `$data['rss']`, _personal/rss-full.xml_ in `$data['rss_full']` sowie der _personal/subcurrent.inc.php_ in `$data['sub']`. + +**Rückgabe:** Daten, die Jlog anschließend speichern soll, am Besten $data unverändert. + +## Hooks für Kommentare +### hook_commentForm + +Mit Hilfe dieser Methode wird das Formular zur Eingabe eines Kommentars manipuliert (z.B. um weitere BBCodes erweitert). + +**Parameter:** +* $form, enthält den Standard-XHTML-Code für das Eingabeformular + +**Rückgabe:** Die XHTML-Oberfläche des Formulars + +**Beispiel:** [plugins/code-for-comments](Plugin-Code-for-Comments) + +Um das Formular lediglich zu erweitern, muss $form Teil der Rückgabe sein, andernfalls wird das Formular komplett ersetzt. + +### hook_newComment + +Dieser Hook wird vor dem Eintragen eines neuen Kommentars in die Datenbank aufgerufen, damit man in irgendeiner Weise auf den Beitrag reagieren kann. Das [Akismet-Plugin](Plugin-Akismet) führt damit z.B. eine Spam-Prüfung durch. + +**Parameter:** +* $form, enthält die rohen POST-Daten des Formulars beim Absenden des Kommentars + +**Rückgabe:** Am Besten $form + +### hook_showComment + +Dieser Hook wird bei der Ausgabe eines Kommentares aufgerufen, so dass dessen Anzeige erweitert oder verändert werden kann (z.B. für Avatare). + +**Parameter:** + +* $comment, enthält den XHTML-Code zur Anzeige eines Kommentares +* $data, enthält alle „Felder“ eines Kommentares als Array-Elemente +* $nr ist die (angezeigte?) Nummer des aktuellen Kommentars + +**Rückgabe:** Der XHTML-Code, der den Kommentar darstellt. + +**Beispiel:** [plugins/gravatar-implementation](Plugin-Gravatar) + +### hook_updateComment + +Jlog ruft diese Methode beim Aktualisieren eines Kommentars auf. + +**Parameter:** +* $data enthält die Daten des HTML-Formulars + +**Rückgabe:** Am Besten $data + +### hook_deleteComment + +Beim Löschen eines Kommentars wird diese Methode aufgerufen, damit z.B. mit dem Kommentar verknüpfte Informationen entfernt werden können. + +**Parameter:** +* $id des Kommentars + +**Rückgabe:** wahrscheinlich am Besten $id + +### hook_adminMail + +Der Administrator wird beim Eingang eines neuen Kommentars per Email darüber informiert. Dieser Hook ermöglicht es Plugins, vorher einzugreifen und z.B. diese Mail bei Spam zu unterdrücken oder Ergänzungen vorzunehmen. + +**Parameter:** + +* $mail ist bis Jlog 1.1.2 ein assoziatives Array mit Informationen zur Mail an den Admin, ab 1.1.3 ein Objekt der Klasse _Jlog_Mail_ +* $blogentry enthält alle Informationen zum betreffenden Blogartikel +* $id enthält seit Jlog 1.1.3 die ID des Kommentars + +**Rückgabe:** Das Objekt in $mail + +**Beispiel:** [branches/plugins/CommentModeration.jplug.php ](Plugin-CommentModeration) + +## Hooks für den Adminbereich +### hook_adminContent + +Diese Methode steht im Admincenter unter dem Navigationspunkt _Plugins_ zur Verfügung: Wählt man dort ein Plugin aus, wird genau diese Methode des Plugins aufgerufen und dessen Rückgabe als XHTML angezeigt. Der Hook bietet sich für Plugins an, die das Admincenter um Funktionen erweitern sollen oder zur Konfiguration von Plugins. + +**Parameter:** +* $output, enthält den Standardtext, der angezeigt wird, falls das Plugin keine Ausgabe hat. + +**Rückgabe:** Der anzuzeigende XHTML-Code als string. + +### hook_adminForm + +Analog zu den oben genannten Hooks zur Veränderung der Eingabeformulare für Kommentare, lässt sich mit Hilfe dieser Methode die Eingabemaske des Administrators für Beiträge (im Adminbereich unter _Inhalte_ zu finden) erweitern. + +**Parameter:** + +* $form, der XHTML-Code des Formulars +* $data, die übermittelten Formularwerte, sofern vorhanden (z.B. beim Ändern eines Artikels) + +**Rückgabe:** Der XHTML-Code für das Formular, mit dem der Admin Beiträge bearbeitet + +**Beispiel:** [plugins/admin-no-bbcode](Plugin-No-BBCode-for-Admin) + +### hook_commentAdminList + +Beim Auflisten aller Kommentare im Admin-Center wird dieser Hook für jeden Kommentar aufgerufen. + +**Parameter:** +* $comment enthält den HTML-Code der Tabellenzeile $data sind die Daten („Felder“) des Kommentars aus der Datenbank + +**Rückgabe:** der HTML-Code, der in der Tabelle gezeigt werden soll + +**Beispiel:** [plugins/CommentModeration](Plugin-CommentModeration) \ No newline at end of file