Created Plugin Tutorial (markdown)

Plugin-Tutorial.md

@@ -0,0 +1,57 @@
+Ich möchte hier anhand eines Gravatar Plugins für Jlog den Aufbau eines solchen verdeutlichen und die bisherigen Hooks vorstellen. Um als Plugin von Jlog erkannt zu werden müssen einige Sachen eingehalten werden. Der Dateiname muss die Endung _.jplug.php_ haben, der Dateiname ohne _.jplug.php_ muss genau so lauten wie der Klassenname (im Beispiel „Gravatar“ bei: `class Gravatar extends JlogPlugin`, da die Datei „Gravatar.jplug.php“ heißt) und sich direkt im Verzeichnis _plugins_ befinden. Wenn zum Plugin andere Dateien gebraucht werden, dürfen diese sich auch im _plugins_ Verzeichniss befinden.
+
+Wenn Daten abgespeichert werden, sollten sie im Verzeichnis _personal_ abgespeichert werden.
+
+## Beispielplugin
+
+    <?php
+    class Gravatar extends JlogPlugin {
+    /**
+     * @name:        Gravatar <jeenaparadies.net/webdesign/jlog/doc/index.php?n=Plugins.Gravatar>
+     * @author:      Jeena Paradies <jlog@jeenaparadies.net>
+     * @version:     1.0
+     * @date:        2005-12-04
+     */
+        function hook_showComment($comment, $data) {
+
+            $grav_url = JLOG_PATH."/img/gravatar.png";
+
+            if(!empty($data['email'])) {
+                $grav_url = "http://www.gravatar.com/avatar.php?gravatar_id=".md5($data['email']).
+                        "&amp;default=".urlencode($grav_url)."&amp;size=80";
+            }
+
+            $gravatar = '<img src="'.$grav_url.'" alt="" class="gravatar" />';
+
+            $search = "<p class='meta'>";
+
+            return str_replace($search, $gravatar.$search, $comment);
+        }
+    }
+    ?>
+
+## Erklärung
+
+In der ersten Zeile wird das Plugin so zu sagen angemeldet, somit kann es auf die Hooks zugreifen, die es gibt. Ein Plugin in Jlog ist, wenn das vielleicht schon jemand kennt, eine Kindsklasse von der Vaterklasse _JlogPlugin_. Das hat all die Vorteile, die Objektorientierte Programmierung mit sich bringt.
+
+Alle Hooks beginnen mit dem Keyword `hook_` gefolgt vom [Hook-Namen](Plugin-Hooks) in der CamelCase Schreibweise und sind Methoden der Vaterklasse _JlogPlugin_, die für die jeweilige Plugin-Instanz überschrieben werden. Um Kompatibilitätsprobleme in der Zukunft zu vermeiden sollte man keine eigenen Methoden mit diesem Keywort am Anfang benennen.
+
+Jedem Hook wird als erstes der fertige Text ausgegeben, der einfach durchgeschleift werden kann, und wenn möglich werden in den nächsten Parametern noch zusätzliche Daten übergeben. In unserem Beispiel wird das Array `$data` übergeben, welches die Daten, die über den Kommentator in der Datenbank abgespeichert sind, enthält.
+
+Das was ein Hook mit return zurückgibt, ersetzt in der Ausgabe den Text, der durchgeschleift werden sollte, was das Plugin dazwischen damit macht ist dem Pluginautor überlassen. Es gibt auch Hooks, die keinen Text durchschleifen und eher als EventHandler fungieren, diese werden ausgeführt wenn bestimmte Events eintreffen, wie: Neue Seite wird erstellt, statische Daten werden aktualisiert, etc.
+
+Der Artikel ist bestimmt noch lange nicht fertig und darf sehr gerne ergänzt werden. Falls Fragen auftauchen am besten per E-Mail an mailto:jlog@… und ich versuche sie hier einzubearbeiten. Das soll aber nicht heißen dass hier niemand etwas anrühren darf, sinnvolle Vorschläge sind absolut willkommen, vor allem wenn sie auch das Verständnis fördern.
+
+## Plugin-Administration
+
+Es gibt die Möglichkeit seinem Plugin ein Administrationsinterface zu geben, welches im Jlog Administrationscenter unter _admin/plugin.php_ zu bedienen ist. Dazu ist `hook_adminContent` gedacht. Alles was von diesem Hook per return zurückgegeben wird, wird im Administrationscenter auf der Pluginseite ausgegeben. Somit kann man richtige Software schreiben, die in Jlog intergriert ist ;-).
+
+## Plugins mit eigener Konfiguration
+
+Die Schnittstelle `hook_adminContent` lässt sich auch dazu nutzen, Plugins zu konfigurieren; somit brauchen nicht alle Einstellungen wie Pfade oder Datenbank-Parameter im Plugin „fest verdrahtet“ werden, sondern sind dynamisch anpassbar. Sofern die Konfigurationseinstellungen in einer Datei gespeichert werden, ist es sinnvoll, dies im Verzeichnis personal zu tun, weil dort auch Jlog variable Daten (Konfiguration, _subcurrent.inc.php_, RSS-Feeds) ablegt. Als Namenskonvention für Konfigurationsdateien scheint folgendes Schema sinnvoll (das ist bisher nicht festgelegt, betrachte es als Vorschlag):
+
+    settings.PLUGIN_NAME.inc.php
+
+*PLUGIN_NAME* ist dabei der Name des Plugins, also Klassenname oder Dateiname des Plugins.
+
+Beachte dabei, dass die Konfiguration im Plugin fehlerfrei eingebunden werden muss, d.h. das Plugin darf (sollte?) weder beendet werden noch eine Fehlermeldung produzieren, falls die Konfigurationsdatei nicht existiert, wie dies im Auslieferungszustand der Fall ist.