Wie auch schon unter Burning Board 3 kann man sein Burning Board 4 bzw. Community Framework 2 mit Plugins erweitern. Da sich jedoch einige Dinge geändert haben, gibt es nun ein einführendes Tutorial in die Plugin-Entwicklung unter Community Framework 2.
Weitere Abschnitte zu diesem Thema:
In diesem ersten Tutorial wird eine einfache Seite hinzugefügt, die letztendlich über
Alles anzeigen
Zeile 1: Die
Zeile 2: Das Paket trägt den Paketbezeichner (Paketnamen)
<application> steht für die jeweilige Anwendung, die das Plugin erweitert (z.B. Community Framework (wcf) oder Burning Board (wbb)).
<plugin> steht für die Funktion des Plugins. Hier wird die Seite (Page) "Example"
Der Paketbezeichner soll dabei helfen, schon ohne das Durchlesen der Dateien festzustellen, woher das Paket kommt und was es macht.
Die übrigen Inhalte (
Das ist übrigens bei jeder
Zeile 3: Der Beginn der allgemeinen Paketinformationen.
Zeile 4: Der angezeigte Name des Paketes - z.B. in der Paketverwaltung.
Zeile 5: Der angezeigte Name des Paketes - z.B. in der Paketverwaltung - speziell für die deutsche Sprache.
Zeile 6: Die Beschreibung des Paketes in ausführlicher Form.
Zeile 7: Die Beschreibung des Paketes in ausführlicher Form - speziell für die deutsche Sprache.
Zeile 8: Die Versionsangabe des Paketes.
Zeile 9: Das Erstell-/Änderungsdatum des Paketes.
Zeile 10: Ende der allgemeinen Paketinformationen.
Zeile 12: Der Beginn der Autorinformationen des Paketes.
Zeile 13: Der Name des Autors.
Zeile 14: Die URL zur Webseite des Autors.
Zeile 15: Ende der Autorinformationen.
Zeile 17: Der Beginn von Informationen zu benötigten Paketen*.
Zeile 18: Die Angabe des benötigten Paketes
Zeile 19: Ende der Informationen zu benötigten Paketen.
Zeile 21: Der Beginn der Installations-Anweisungen.
Zeile 22: Anweisung zur Installation von Dateien aus dem Archiv
Zeile 23: Anweisungen zur Installation von Templates aus dem Archiv
Zeile 24: Anweisungen zur Installation von Sprachvariablen aus dem Verzeichnis
Zeile 25: Ende der Installations-Anweisungen.
Zeile 26: Ende der
Beim Speichern muss immer darauf geachtet werden, dass sämtliche
Wie man demnach in den Zeilen 21-25 erkennen kann, benötigen wir auf jeden Fall eine
In der
Da in diesem Fall das Framework erweitert wird, wird die Datei dann auch unter
Ansonsten gelten folgende Regeln:
Die PHP-Klassendatei hat sich in Community Framework 2 stark vereinfacht. Eine bereits funktionierende Klasse sieht folgendermaßen aus:
Alles anzeigen
Da das Plugin das Framework um eine Seite erweitert, muss auch selbiges als
Der Kommentar-Header gibt die jeweiligen Informationen des Paketes aus der
Dann wird die Klasse
Die Zeilenenden sollten hierbei immer im UNIX-Format (LF) gespeichert werden.
Um zudem Kodierungsfehler zu vermeiden bzw. einen zu früh versendeten HTTP-Header, sollte der schließende PHP-Tag
In der
Die
Alles anzeigen
Allgemeines zu Templates ist hier zu finden:
Templates in Community Framework #1 - Die Einleitung - Artikel - KittBlog
Nun fehlen nur noch die Sprachvariablen.
Jede Sprache hat hierbei ihre eigene
In diesem Fall sieht die
Zeile 1: Neben den bereits bei der
Zeile 2: Die Sprachkategorie namens
Zeile 3-5: Es werden 3 neue Sprachvariablen hinzugefügt.
Zeile 6: Ende der Erweiterung der Sprachkategorie.
Zeile 7: Ende der Sprachdatei.
Wichtig ist auch immer die Organisation. Normalerweise sollte das Verzeichnis, in dem man das Paket erstellt und packt, nun folgendermaßen aussehen:
Verzeichnisse:
Dateien:
Der gesamte Verzeichnisbaum sollte folgendermaßen aussehen:
Alles anzeigen
Da nun die Dateien unter
Alles anzeigen
Wie man demnach sieht, sind die Verzeichnisse
Folgende Dateien und Verzeichnisse werden nun zu einem Paket zusammengepackt:
Verzeichnisse:
Dateien:
Das fertige Plugin muss als entweder als
Für die genauere Ansicht bzw. das bessere Verständnis habe ich das fertige Paket auch unten angehängt.
Das Ergebnis sollte dann folgendermaßen aussehen:
Bei Fragen u.ä. stehe ich natürlich jederzeit gerne zur Verfügung.
* Die Vergabe von benötigten Paketen ist gar nicht so einfach, wie man denken mag. Man sollte demnach vorsichtig sein, welche Pakete man hier referenziert. Es sollten immer alle Pakete, die benötigt werden, auch referenziert sein.
Beispiel: Ein Paket, das die Endanwendung Burning Board, also
** Hat man z.B. die Klassendatei ExtendedExample, die dann über
Weitere Abschnitte zu diesem Thema:
- Menüpunkt für die eigene Seite
- Der erste eigene Template-Listener
- Einstellungen für die eigene Seite
- Benutzer-Einstellungen für die eigene Seite
- Benutzergruppen-Einstellungen für die eigene Seite
- Konsistenz bei der Entwicklung
- Eigenes LESS richtig hinzufügen
- Ein updatefähiges Paket erstellen
- Zugriff auf die Datenbank
- Inhalte mit jQuery dynamisch manipulieren
- Zugriff auf die Datenbank – Teil 2
package.xml
, welche dem Framework grundlegende Informationen über das Paket gibt. Zu diesen Informationen gehören Beschreibung, Version, benötigte andere Pakete und die Installations-Anordnungen. Ohne diese Datei - oder wenn selbige fehlerhaft ist - kann ein Plugin nicht installiert werden.In diesem ersten Tutorial wird eine einfache Seite hinzugefügt, die letztendlich über
index.php/Example/
aufgerufen werden kann. Die dafür notwendige package.xml
sieht folgendermaßen aus: XML-Quellcode
- <?xml version="1.0" encoding="UTF-8"?>
- <package name="com.kittblog.wcf.examplepage" xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/maelstrom/package.xsd">
- <packageinformation>
- <packagename>Example page</packagename>
- <packagename language="de">Beispielsseite</packagename>
- <packagedescription>The first own example page for Community Framework 2.</packagedescription>
- <packagedescription language="de">Die erste eigene Beispielsseite für Community Framework 2.</packagedescription>
- <version>1.0.0 Alpha 1</version>
- <date>2013-07-21</date>
- </packageinformation>
- <authorinformation>
- <author>KittBlog Stile</author>
- <authorurl>http://kittblog.com</authorurl>
- </authorinformation>
- <requiredpackages>
- <requiredpackage minversion="2.0.0 Alpha 1">com.woltlab.wcf</requiredpackage>
- </requiredpackages>
- <instructions type="install">
- <instruction type="file">files.tar</instruction>
- <instruction type="template">templates.tar</instruction>
- <instruction type="language">language/*.xml</instruction>
- </instructions>
- </package>
package.xml
wird als XML-Datei in v1.0 erkannt und nutzt die Kodierung UTF-8.Zeile 2: Das Paket trägt den Paketbezeichner (Paketnamen)
com.kittblog.wcf.examplepage
. Er sollte immer folgendermaßen aufgebaut sein:tld.domain.<application>.<plugin>
. <application> steht für die jeweilige Anwendung, die das Plugin erweitert (z.B. Community Framework (wcf) oder Burning Board (wbb)).
<plugin> steht für die Funktion des Plugins. Hier wird die Seite (Page) "Example"
examplepage
hinzugefügt.Der Paketbezeichner soll dabei helfen, schon ohne das Durchlesen der Dateien festzustellen, woher das Paket kommt und was es macht.
Die übrigen Inhalte (
xmlns
, xmln:xsi
und xsi:schemaLocation
geben Informationen zur allgemeinen Struktur der XML-Datei. Diese muss normalerweise nicht geändert werden. Wer bereits etwas weiter in XML ist, der kann sich gerne die schemaLocation
ansehen, welche (in finaler Version) Informationen darüber bietet, was alles in der package.xml
möglich ist: woltlab.com/XSD/maelstrom/package.xsdDas ist übrigens bei jeder
.xml
-Datei so, die bei einer Plugin-Entwicklung genutzt wird.Zeile 3: Der Beginn der allgemeinen Paketinformationen.
Zeile 4: Der angezeigte Name des Paketes - z.B. in der Paketverwaltung.
Zeile 5: Der angezeigte Name des Paketes - z.B. in der Paketverwaltung - speziell für die deutsche Sprache.
Zeile 6: Die Beschreibung des Paketes in ausführlicher Form.
Zeile 7: Die Beschreibung des Paketes in ausführlicher Form - speziell für die deutsche Sprache.
Zeile 8: Die Versionsangabe des Paketes.
Zeile 9: Das Erstell-/Änderungsdatum des Paketes.
Zeile 10: Ende der allgemeinen Paketinformationen.
Zeile 12: Der Beginn der Autorinformationen des Paketes.
Zeile 13: Der Name des Autors.
Zeile 14: Die URL zur Webseite des Autors.
Zeile 15: Ende der Autorinformationen.
Zeile 17: Der Beginn von Informationen zu benötigten Paketen*.
Zeile 18: Die Angabe des benötigten Paketes
com.woltlab.wcf
(Community Framework 2) in mindestens Version 2.0.0 Alpha 1.Zeile 19: Ende der Informationen zu benötigten Paketen.
Zeile 21: Der Beginn der Installations-Anweisungen.
Zeile 22: Anweisung zur Installation von Dateien aus dem Archiv
files.tar
.Zeile 23: Anweisungen zur Installation von Templates aus dem Archiv
templates.tar
.Zeile 24: Anweisungen zur Installation von Sprachvariablen aus dem Verzeichnis
language/
Zeile 25: Ende der Installations-Anweisungen.
Zeile 26: Ende der
package.xml
.Beim Speichern muss immer darauf geachtet werden, dass sämtliche
.xml
-Dateien als UTF-8 ohne BOM (ANSI as UTF-8) und sämtliche andere Dateien (z.B. .tpl
oder .php
) in ANSI gespeichert werden müssen, um Kodierungsfehler zu vermeiden.Wie man demnach in den Zeilen 21-25 erkennen kann, benötigen wir auf jeden Fall eine
files.tar
, eine templates.tar
und mindestens eine .xml
im Verzeichnis language/
.In der
files.tar
befinden sich sämtliche Dateien, die ins Dateisystem gehören (Ausnahme: Templates). Für eine einfache Seite benötigt man hierbei lediglich eine einzelne PHP-Klassendatei, welche unter lib/page/
gespeichert werden muss. Ob hierbei das lib-Verzeichnis der Endanwendung (normal unter /
zu finden, also im Wurzelverzeichnis) oder das des Frameworks (normal unter wcf/
zu finden) gespeichert wird, hängt von den Paketabhängigkeiten ab.Da in diesem Fall das Framework erweitert wird, wird die Datei dann auch unter
wcf/lib/page/
zu finden sein.Ansonsten gelten folgende Regeln:
- Wird das
application
-Attribut in der Installationsanweisung genutzt, werden die Dateien in das Verzeichnis der dort angegebenen Anwendung gespeichert. - Dateien in einem Paket einer Endanwendungen werden auch in deren Verzeichnis installiert.
- Ansonsten wird standardmäßig das Verzeichnis des Community Framework genutzt.
Die PHP-Klassendatei hat sich in Community Framework 2 stark vereinfacht. Eine bereits funktionierende Klasse sieht folgendermaßen aus:
PHP-Quellcode
namespace
angegeben werden: wcf\page
Der Kommentar-Header gibt die jeweiligen Informationen des Paketes aus der
package.xml
zusätzlich wieder.Dann wird die Klasse
ExamplePage
erstellt, welche die Klasse AbstractPage
erweitert. Der Klassenname setzt sich immer aus dem Seitennamen (hier: Example
) und der Art der Klasse (hier: Page
) zusammen. Auch die Bezeichnung der Datei spiegelt das wider. Sie muss lauten: ExamplePage.class.php
. Der Seitenname fängt hierbei immer mit einem Großbuchstaben an. Im Paket ist die Datei dann unter lib/page/ExamplePage.class.php
vorhanden und wird zu einer files.tar
gepackt.Die Zeilenenden sollten hierbei immer im UNIX-Format (LF) gespeichert werden.
Um zudem Kodierungsfehler zu vermeiden bzw. einen zu früh versendeten HTTP-Header, sollte der schließende PHP-Tag
?>
nicht genutzt werden.In der
templates.tar
befinden sich sämtliche Templates eines Paketes. In diesem Fall wäre das nur die Datei example.tpl
. Damit trägt sie dieselbe Bezeichnung wie die Page-Klasse, wodurch sie auch automatisch als dieser zugehörig erkannt wird. Deshalb muss man sie in der Klassendatei selbst auch nicht nochmals extra referenzieren (was jedoch auch möglich ist, wenn man z.B. einen anderen Dateinamen für das Template nutzt). Der Dateiname fängt bei Templates allerdings immer klein an**.Die
example.tpl
sieht in diesem Fall folgendermaßen aus und fügt eine einfache Seite mit ein paar Sprachvariablen hinzu: Smarty-Template
- {include file='documentHeader'}
- <head>
- <title>{lang}wcf.page.example.title{/lang} - {PAGE_TITLE|language}</title>
- {include file='headInclude' sandbox=false}
- </head>
- <body id="tpl{$templateName|ucfirst}">
- {include file='header'}
- <header class="boxHeadline">
- <h1>{lang}wcf.page.example.title{/lang}</h1>
- </header>
- {include file='userNotice'}
- <div class="container marginTop">
- <ul class="containerList exampleList">
- <li class="exampleBox">
- <div>
- <div class="containerHeadline">
- <h3>{lang}wcf.page.example.secondTitle{/lang}</h3>
- <p>{lang}wcf.page.example.content{/lang}</p>
- </div>
- </div>
- </li>
- </ul>
- </div>
- {include file='footer'}
- </body>
- </html>
Templates in Community Framework #1 - Die Einleitung - Artikel - KittBlog
Nun fehlen nur noch die Sprachvariablen.
Jede Sprache hat hierbei ihre eigene
.xml
-Datei im Ordner language/
, die nach dem Sprachcode benannt wird, z.B. de.xml
oder en.xml
. Offiziell von WoltLab unterstützt werden Deutsch und Englisch. Nach Möglichkeit sollten demnach mindestens diese beiden Sprachen auch mitgeliefert werden.In diesem Fall sieht die
de.xml
folgendermaßen aus: XML-Quellcode
- <?xml version="1.0" encoding="UTF-8"?>
- <language xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/maelstrom/language.xsd" languagecode="de">
- <category name="wcf.page">
- <item name="wcf.page.example.title"><![CDATA[Beispielseite]]></item>
- <item name="wcf.page.example.secondTitle"><![CDATA[Diese Seite dient zum Beispiel]]></item>
- <item name="wcf.page.example.content"><![CDATA[Eine einfache Beispielseite, die mit einem einfachen Template-Code und Sprachvariablen alle Standards von Community Framework erfüllt und ohne viel Aufwand durch dieselben genutzten Klassen "wie aus einem Guss" wirkt. Das sollte beim Template-Design immer das Hauptaugenmerk sein.]]></item>
- </category>
- </language>
package.xml
genannten Informationen (xmlns
, xmln:xsi
und xsi:schemaLocation
) gibt es bei Sprachen noch das wichtige Attribut languagecode
. Dieses gibt an, welche Sprache die Datei beinhaltet und sollte denselben Inhalt haben wie der Dateiname.Zeile 2: Die Sprachkategorie namens
wcf.page
wird erweitert oder angelegt, falls noch nicht vorhanden.Zeile 3-5: Es werden 3 neue Sprachvariablen hinzugefügt.
Zeile 6: Ende der Erweiterung der Sprachkategorie.
Zeile 7: Ende der Sprachdatei.
Wichtig ist auch immer die Organisation. Normalerweise sollte das Verzeichnis, in dem man das Paket erstellt und packt, nun folgendermaßen aussehen:
Verzeichnisse:
files
, language
, templates
Dateien:
package.xml
Der gesamte Verzeichnisbaum sollte folgendermaßen aussehen:
Quellcode
files/
und templates/
gepackt werden müssen, würde die Verzeichnisstruktur nach dem Packen folgendermaßen aussehen: Quellcode
files/
und templates/
nicht innerhalb der .tar
-Dateien. Das ist sehr wichtig, da sie sonst nicht richtig entpackt werden können.Folgende Dateien und Verzeichnisse werden nun zu einem Paket zusammengepackt:
Verzeichnisse:
language
Dateien:
files.tar
, templates.tar
, package.xml
Das fertige Plugin muss als entweder als
.tar
oder .tgz
(bzw. .tar.gz
) gespeichert werden. Hierbei muss die package.xml
immer auf der untersten Ebene sein, also nicht in einem Unterordner. Ansonsten wird sie nicht gefunden. Zum Packen eignet sich unter Windows am besten 7-Zip.Für die genauere Ansicht bzw. das bessere Verständnis habe ich das fertige Paket auch unten angehängt.
Das Ergebnis sollte dann folgendermaßen aussehen:
Bei Fragen u.ä. stehe ich natürlich jederzeit gerne zur Verfügung.
* Die Vergabe von benötigten Paketen ist gar nicht so einfach, wie man denken mag. Man sollte demnach vorsichtig sein, welche Pakete man hier referenziert. Es sollten immer alle Pakete, die benötigt werden, auch referenziert sein.
Beispiel: Ein Paket, das die Endanwendung Burning Board, also
com.woltlab.wbb
erweitert, benötigt auch zwingend com.woltlab.wcf
, Community Framework.** Hat man z.B. die Klassendatei ExtendedExample, die dann über
index.php/ExtendedExample/
aufrufbar ist, so hätte das standardmäßig zugehörige Template den Namen extendedExample.tpl
. Sämtliche Sonderzeichen wie z.B. Bindestriche sind zu vermeiden!Teil 2: Menüpunkt für die eigene Seite
22.437 mal gelesen
ViperAC -
Für WSC 3.0/3.1 wird das wahrscheinlich nicht mehr funktionieren oder?