Joomla! Plugin Tutorial - Erstellung eines Content Plugins |
Geschrieben von Steffen | |
Montag, 1. März 2010 | |
Sie wollen also wissen, wie man prinzipiell ein Joomla-Plugin für die eigenen Wünsche erstellt. Hier ist ein möglicher erster Einstieg in die Programmierung eines Content Plugins für Joomla 1.5. Ziel dieses Tutorials ist es, eine Einführung in die Erstellung von Joomla-Plugins zu geben und das prinzipielle Vorgehen bei der Entwicklung eines eigenen Plugins an Hand eines Beispiels näher zu beleuchten.
Im Rahmen des Tutorials werden zwei Content Plugins entstehen:
Prinzipiell ist dies gar nicht so schwierig, wie man denken könnte. Gut, beim ersten Mal geht’s vielleicht noch nicht so flüssig von der Hand. Hat man jedoch sein erstes Plugin erfolgreich allein geschrieben und die Vorteile dieser kleinen Helfer für sich entdeckt, werden einem bestimmt mehr Einsatzmöglichkeiten einfallen. Joomla Plugins - Die ultimativen ProblemlöserFür alle die noch ein paar Hintergrundinfos zu den nützlichen kleinen Helfern benötigen, denen sei der folgende Exkurs an Herz gelegt. Alle anderen dürfen diesen Teil gern überspringen. Joomla! Plugins dienen unterschiedlichen Zwecken. So, wie Module dafür erstellt werden, Daten auf der Webseite in verschiedenen Darstellungen auszugeben, werden Plugins erstellt, um die auszugebenen Daten zu manipulieren oder auch zusätzliche Funktionalitäten für Joomla zu erstellen. Die Anzahl dieser Typen ist rein theoretisch fast unbegrenzt. Von Hause aus nutzt Joomla ein Reihe von sogenannten Core-Plugin-Typen. Sie befinden sich im Verzeichnis /plugins/. Zu ihnen gehören folgende Typen: Wofür gibt es verschiedene Plugin-Typen?
Authentication
Content
Editor
Editor-XTD
Search
System
User
XML-RPC "Die Fingerübung" oder das dümmste Plugin der WeltDamit Sie schon am Anfang ein kleines Erfolgserlebnis haben, setzen wir in ein paar wenigen Schritten unser erstes Content-Plugin um, das nichts weiter tun wird, als am Anfang jedes auszugegeben Joomla-Artikels einen Satz einzufügen. Sagen wir "Joomla-Plugins sind super."
Etwas Technisches Ein Plugin ist in Joomla eine Klasse, die von der JPlugin-Klasse abgeleitet wird. Das Interessante daran ist, dass ein Plugin und seine Funktion(en) damit automatisch in die Joomla-Verarbeitung eingebunden werden. Beim Aufruf einer Seite unser Joomla-Webseite werden alle vorhanden Plugins praktischerweise automatisch geladen. In der Übergangsphase von Joomla 1.0 zu 1.5 wurden Plugins nicht als Klassen und deren Funktionen umgesetzt, sondern nur als eigenständige Funktionen, die mittels der Methode registerEvent unserer Joomla-Seite angemeldet werden mussten. Das sah dann z. B. so aus: <?php $mainframe->registerEvent( 'onPrepareContent', 'plgContentChangeContent' ); ... ?> Diese Vorgehensweise dürfen Sie sich aber gar nicht erst aneignen!
Das
Joomla-Framework sollte möglichst immer objektorientiert genutzt
werden. Das erreichen wir bei unserer Plugin-Umsetzung, indem im
Plugin-Code keine eigenständigen Funktionen programmiert werden, sondern
dass diese in einer eigenen Klasse "verpackt werden", die – wie weiter
oben bereits erwähnt – von der Joomla-Klasse JPlugin abgeleitet ist. class plgContentDemo extends JPlugin { ... } Dadurch brauchen Sie sich auch nicht um die Registrierung der Plugin-Funktionen am System kümmern. Und auch die Überprüfung, ob unser Plugin überhaupt aktiviert ist, fällt weg. Dies erledigt alles Joomla. Die nötigsten DateienAuch wenn zu einem Plugin eine Vielzahl von Dateien gehören können, so sind nur 2 davon elementar wichtig, damit ein Plugin in Joomla funktioniert. Bei der Benennung der Dateien müssen bestimmte durch Joomla vorgegebene Namenskonventionen eingehalten werden. Bevor wir uns die zwei nötigen Dateien etwas genauer ansehen, ist zu entscheiden, von welchem Typ das Plugin sein wird. Da wir nur den Inhalt (Content) verändern wollen, wird es wohl ein Plugin des Typs Content sein. Eigene Typen werden einfach zu Joomla hinzugefügt, indem man im Ordner /plugins/ einen Unterordner anlegt, der genau wie der neue Typ heißt. Die Dateien eines Plugins werden dann im entsprechenden Ordner des Plugin-Typs gepspeichert. Schauen wir uns für unser Plugin an, was in den beiden wichtigsten Dateien enthalten ist. Das erste Plugin soll einfach Mal den Namen "Demo" bekommen. Für den Namen eines Plugins gibt's keine Einschränkungen, aber er sollte sinnvoller Weise nur alphanumerische Werte und Underlines verwenden. Steht der Name des Plugins fest, dann ergeben sich daraus die Namen für bestimmte Teile unseres Plugins, so z. B. der Name unserer von JPlugin abgeleiteten Klasse. Der Name des Plugins muss zwingend auch für die Namen der beiden wichtigsten Dateien verwendet werden. Die eine Datei ist also eine php-Datei namens demo.php, welche natürlich den notwendigen Php-Code enthalten wird. Als zweite Datei gibt's dann noch die XML-Datei demo.xml, welche Metadaten, die Definition von Parametern des Plugins, sowie auch Installationsinformationen für Joomla bereitstellen wird. Das Grundgerüst unserer ersten Plugin-Datei demo.php schaut so aus: <?php // Sicherstellen, dass die Datei nur innerhalb Joomlas aufgerufen wird. defined( '_JEXEC' ) or die( 'Restricted access' ); jimport( 'joomla.plugin.plugin' ); /** * Demo Content Plugin * Definition unserer Plugin-Klasse. */ class plgContentDemo extends JPlugin { function plgContentDemo( &$subject, $params ) { // führe ein paar notwendige Initialisierungen durch parent::__construct( $subject, $params ); } Wie jede in Joomla verwendete php-Datei sollte auch unsere Plugin-php-Datei unbedingt mit der Prüfung defined( '_JEXEC' ) beginnen. So wird sichergestellt, dass die Datei nicht einfach per URL aufgerufen werden kann. Sicherlich will kein Programmierer selbst eine Sicherheitslücke für Angreifer auftun. Die Wichtigkeit dieser Überprüfung kann nicht oft genug betont werden. Um unsere Plugin-Klasse von der JPlugin-Klasse Joomlas ableiten zu können, laden wir mit der jimport()-Anweisung den Joomla-Code für diese Klasse. Dann folgt schon der Rumpf unserer Plugin-Klasse. Sehr wichtig ist die Namenskonvention dieser Klasse. Der Name einer Plugin-Klasse setzt sich immer aus folgenden drei Teilen zusammen:
Genau so muss unsere Klasse heißen, damit das Plugin vom Joomla-Framewok gefunden wird.
Der zweite und dritte Teil des
Klassennames sollte immer mit einem Großbuchstaben beginnen, auch wenn
dies nicht zwingend erforderlich ist. So ist er für jeden einfacher
lesbar. Für das "Demo"-Plugin ergibt sich dann der Klassenname plgContentDemo.
Jetzt kommt die Funktion onPrepareContent, von der im Beispiel
Gebrauch gemacht werden soll. Dort wird der entscheidende
Php-Code platziert. Die Funktion hat den selben Namen, wie das Event
(Ereignis), über das wir informiert werden und auf das wir reagieren
wollen. Die Joomla-Komponente com_content, die in Joomla für die
Beiträge zuständig ist, löst dieses Event (Ereignis) bei der
Vorbereitung auszugebenen Inhalts aus. Bevor also
ein Artikel erscheint, können verschiedene Plugins darüberjagen, falls
sie sich alle für dieses Event angemeldet haben. Auch manch' andere Komponente löst genau das
selbe Event aus (z. B. EventList und ZOO). Unsere Funktion onPrepareContent wird
automatisch von Joomla beim Laden unseres Plugins für das gleichnamige
Event (Ereignis) angemeldet. Somit wird unser Code innerhalb der
Plugin-Funktion bei dem Event onPrepareContent abgearbeitet. Content-Plugin-EventsEreignisse (Events), die Content-Plugins aufrufen sind: onPrepareContent (nutzen wir in unserem Beispiel)
onAfterDisplayTitle
onBeforeDisplayContent
onAfterDisplayContent
onBeforeContentSave
onAfterContentSave
Auf die vom Beispiel
nicht genutzten Events (Ereignisse) sei hier nicht weiter eingegangen.
Genauso wenig soll hier näher auf die Events anderer Core-Plugin-Typen
eingegangen werden, die von Joomla in bestimmten Situationen ausgelöst
werden. Auf diese Events kann man natürlich auch mit eigenen Plugins des
entsprechenden Typs reagieren. Über all diese weiteren Events
(Ereignisse) der Core-Plugin-Typen kann man sich auf der entsprechenden
Seite von joomla.org noch näher informieren. Plugin-Tutorial auf
joomla.org Nun ein Blick auf die genauso wichtige zweite Datei "demo.xml" an: <?xml version="1.0" encoding="utf-8"?> <install version="1.5" type="plugin" group="content"> <name>Content - Demo Plugin</name> <author>Steffen Drewlo</author> <creationDate>Februar 2010</creationDate> <copyright>Copyright (C) 2010 B01 - Tom Bohacek</copyright> <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license> <authorEmail> Diese E-Mail Adresse ist gegen Spam Bots geschützt, Sie müssen Javascript aktivieren, damit Sie es sehen können </authorEmail> <authorUrl>www.bohacek.de</authorUrl> <version>0.9</version> <description>DESC DEMO PLUGIN</description> <files> <filename plugin="demo">demo.php</filename> </files> <params> <param name="texttoadd" type="text" size="40" default="Joomla-Plugins sind super." label="TEXT TO ADD" description="PARAMDESC TEXT TO ADD" /> <param name="textbold" type="radio" default="1" label="SHOW TEXT BOLD" description="PARAMDESC SHOW TEXT BOLD"> <option value="0">No</option> <option value="1">Yes</option> </param> </params> </install> Ich dachte, dass unser Demo-Content-Plugin vielleicht gleich noch mit zwei Parametern zum Konfigurieren versehen werden sollte. Das ist recht einfach und lässt das Plugin flexibler werden.Dazu müssen nur zwei "<param ...>"-Attribute in der Xml-Datei für unser Plugin mitangelegt werden. Und schon kann man dann später im Backend für das Plugin einstellen, welcher Text denn vor jeden Beitragstext eingefüfgt werden soll und auch, ob dieser eingefügte Text fett dargestellt wird. Die einzelnen Strukturen dieser xml-Datei haben bestimmte Bedeutungen. Manche sind selbsterklärend (so wie <author>). Von den anderen nachfolgend die wichtigsten Bereiche: <install>Mit diesem Xml-Tag und seinen Attributen werden wichtige Dinge für Joomlas Installationsvorgang definiert. Der Typ muss bei Plugins immer "plugin" sein. Der Plugin-Typ muss ebenfalls immer angegeben werden und entspricht dem Typ unseres Plugins, also "content". Wenn man das Plugin installieren können soll, ohne eine ältere Vorgängerversion des Plugins vorher deinstallieren zu müssen, so muss dann zusätzlich method="upgrade" angegeben werden. Alte Dateien werden dann einfach überschrieben. <name>Am besten sollte der Name des Plugins mit seinem Typ beginnen, gefolgt von einem Bindestrich und dem eigentlichen Namen des Plugins. Dieser Text wird in der Auflistung der Plugins im Backend angezeigt und ist in der angegeben Form einfach sprechender. Diese Schreibweise muss nicht benutzt werden, ist allerdings sehr verbreitet und empfiehlt sich daher.
<files>
<params> In unserer Plugin-Funktion "onPrepareContent" steht folgender Code: function onPrepareContent( &$article, &$params, $limitstart ) { // wir laden die Parameter des Plugins $plugin =& JPluginHelper::getPlugin('content', 'demo'); $pluginParams = new JParameter( $plugin->params ); // wir lesen den Text aus, der eingefügt werden soll $textToAdd = $pluginParams->get( 'texttoadd', 'NO TEXT' ); // wir überprüfen, ob der einzufügende Text fett dargestellt werden soll $textBold = $pluginParams->get( 'textbold', 0 ); if($textBold) { $textToAdd = '<strong>'.$textToAdd.'</strong>'; } // wir fügen den Text an den Anfang des Artikels $article->text = $textToAdd .' - '. $article->text; return true; }
So nun steht der vollständige Code unseres Demo-Content-Plugin. Es hat die - zugegeben nicht wahnsinnig aufregende
Das Plugin greift unmittelbar vor der Darstellung von Joomla-Beiträgen ein, da vor der Aufbereitung der anzuzeigenden Inhalte (Contents) ein Event (Ereignis) "onPrepareContent"von der Komponente "com_content" abgefeuert wird, auf das wir in Installation, Aktivierung und KonfigurationHaben wir alle Dateien des Plugins erstellt, so brauchen wir sie nur noch in ein Zip-Archiv verpacken. Sollten Dateien unseres Plugins auch in Unterverzeichnissen gespeichert sein, so werden diese einfach mit in das Zip-Archiv gepackt. Die zum Plugin gehörigen Dateien werden dann von Joomla allerdings nur korrekt installiert, wenn sie in der xml-Datei unseres Plugins mitangegeben sind (wie weiter oben näher beschrieben). Das muss nicht für jede einzelne Datei von den genutzten Unterverzeichnissen des Plugins geschehen. Es können auch mit einem sogenannten "FOLDER-tag" (z.B. <folder>test</folder>) gleich alle Dateien eines Verzeichnisses eingebunden werden.
Hier die installierbare Archivdatei des Demo-Content-Plugins zum Download: Nach der Installation muss das Plugin noch im Backend aktiviert werden. Es findet sich unter dem Menüpunkt Erweiterungen->Plugins. Wenn die Werte für die Parameter des Plugins geändert werden sollen, klickt man einfach auf den Plugin-Namen. QuickFaq Tag Plugin - Mal was sinnvollesNun haben Sie Ihr erstes Plugin hoffentlich erfolgreich umgesetzt. Der praktische Nutzen ist allerdings fraglich. Deshalb hier ein schöneres Beispiel aus der Praxis. Wir hatten bei einem Kunden die Anforderung, dass die auf dessen Webseite eingesetzte QuickFaq-Komponente durch ein Plugin mit den Joomla-Beiträgen verknüpft werden sollte. Und zwar sollten alle Begriffe, die in Beiträgen vorhanden waren und in QuickFaq als Stichworte (sogenannte Tags) definiert wurden zu Links "umgebaut" werden. Diese Links sollten auf die entsprechende Ansicht von QuickFaq verweisen, in der alle mit einem Tag/Stichwort verknüpften Quick-Faq-Einträge angezeigt werden. Das Ganze natürlich mit dem QuickFaq eigenem Router für optimale SEO. Dieser Kundenwunsch war mit einem eigenen Content-Plugin wunderbar und extrem schnell umsetzbar. Wir nannten das zukünftige Plugin "quickfaqtaglinks". Die verwendete Joomla-Klasse, welche wir zu erstellen hatten, musste dementsprechend "plgContentQuickFaqTaglinks" heißen. Wir haben zu den zwei wichtigen Plugin-Dateien noch zwei zusätzliche Sprachdateien erstellt. Damit unterstützt das Plugin auch unterschiedliche Sprachen in Front- und Backend. Die installierbare Zip-Archivdatei für das QuickFaqTaglinks-Plugin enthält also 4 Dateien:
Im Quellcode zu dem QuickFaqTaglinks-Plugin kann man sich auch anschauen, wie in Plugins ein Datenbankzugriff realisiert wird. Dies war in diesem Fall notwendig, um von der QuickFaq-Komponente die Tags/Stichworte samt ihrer eindeutigen Id zu ermitteln. Die IDs wurden für die Verlinkung zur entsprechenden QuickFaq-Ansicht benötigt. Sollten einige der Leser das QuickFaqTaglinks-Plugin ausprobieren oder auch dauerhaft einsetzen, so freue ich mich darüber und bin für Kommentare offen. Download: QuickFaq Taglink Plugin Ich hoffe mein erstes Tutorial hat Ihnen dabei geholfen, die ersten Hürden bei der Erstellung eigener Plugins zu nehmen. Sollten Ihnen bestimmte Punkte, die ich behandelt habe, nicht verständlich genug sein, so bin ich für Hinweise dankbar. Lesezeichen setzen Hits: 63894 Kommentar schreiben
|