WCF2: Das erste eigene Plugin

  • WCF 2

Achtung: Diese Seite ist nur noch Teil eines Archivs und wird in Zukunft entfernt.

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: Jedes Plugin hat mindestens eine 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

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <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">
  3. <packageinformation>
  4. <packagename>Example page</packagename>
  5. <packagename language="de">Beispielsseite</packagename>
  6. <packagedescription>The first own example page for Community Framework 2.</packagedescription>
  7. <packagedescription language="de">Die erste eigene Beispielsseite für Community Framework 2.</packagedescription>
  8. <version>1.0.0 Alpha 1</version>
  9. <date>2013-07-21</date>
  10. </packageinformation>
  11. <authorinformation>
  12. <author>KittBlog Stile</author>
  13. <authorurl>http://kittblog.com</authorurl>
  14. </authorinformation>
  15. <requiredpackages>
  16. <requiredpackage minversion="2.0.0 Alpha 1">com.woltlab.wcf</requiredpackage>
  17. </requiredpackages>
  18. <instructions type="install">
  19. <instruction type="file">files.tar</instruction>
  20. <instruction type="template">templates.tar</instruction>
  21. <instruction type="language">language/*.xml</instruction>
  22. </instructions>
  23. </package>
Alles anzeigen
Zeile 1: Die 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.xsd
Das 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:
  1. Wird das application-Attribut in der Installationsanweisung genutzt, werden die Dateien in das Verzeichnis der dort angegebenen Anwendung gespeichert.
  2. Dateien in einem Paket einer Endanwendungen werden auch in deren Verzeichnis installiert.
  3. 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

  1. <?php
  2. namespace wcf\page;
  3. /**
  4. * Shows the example page.
  5. *
  6. * @author KittBlog Stile
  7. * @copyright 2013 kittblog.com
  8. * @license LGPL
  9. * @package com.kittblog.wcf.examplepage
  10. */
  11. class ExamplePage extends AbstractPage { }
Alles anzeigen
Da das Plugin das Framework um eine Seite erweitert, muss auch selbiges als 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

  1. {include file='documentHeader'}
  2. <head>
  3. <title>{lang}wcf.page.example.title{/lang} - {PAGE_TITLE|language}</title>
  4. {include file='headInclude' sandbox=false}
  5. </head>
  6. <body id="tpl{$templateName|ucfirst}">
  7. {include file='header'}
  8. <header class="boxHeadline">
  9. <h1>{lang}wcf.page.example.title{/lang}</h1>
  10. </header>
  11. {include file='userNotice'}
  12. <div class="container marginTop">
  13. <ul class="containerList exampleList">
  14. <li class="exampleBox">
  15. <div>
  16. <div class="containerHeadline">
  17. <h3>{lang}wcf.page.example.secondTitle{/lang}</h3>
  18. <p>{lang}wcf.page.example.content{/lang}</p>
  19. </div>
  20. </div>
  21. </li>
  22. </ul>
  23. </div>
  24. {include file='footer'}
  25. </body>
  26. </html>
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 .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

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <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">
  3. <category name="wcf.page">
  4. <item name="wcf.page.example.title"><![CDATA[Beispielseite]]></item>
  5. <item name="wcf.page.example.secondTitle"><![CDATA[Diese Seite dient zum Beispiel]]></item>
  6. <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>
  7. </category>
  8. </language>
Zeile 1: Neben den bereits bei der 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

  1. .
  2. ├── files
  3. │ └── lib
  4. │ └── page
  5. │ └── ExamplePage.class.php
  6. ├── language
  7. │ ├── de.xml
  8. │ └── en.xml
  9. ├── templates
  10. │ └── example.tpl
  11. └── package.xml
  12. 5 directories, 5 files
Alles anzeigen
Da nun die Dateien unter files/ und templates/ gepackt werden müssen, würde die Verzeichnisstruktur nach dem Packen folgendermaßen aussehen:

Quellcode

  1. .
  2. ├── files
  3. │ └── lib
  4. │ └── page
  5. │ └── ExamplePage.class.php
  6. ├── files.tar
  7. │ └── lib
  8. │ └── page
  9. │ └── ExamplePage.class.php
  10. ├── language
  11. │ ├── de.xml
  12. │ └── en.xml
  13. ├── templates
  14. │ └── example.tpl
  15. ├── templates.tar
  16. │ └── example.tpl
  17. └── package.xml
  18. 5 directories, 7 files
Alles anzeigen
Wie man demnach sieht, sind die Verzeichnisse 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!

Dateien
Über den Autor
Ich bin Webentwickler in Stuttgart und administriere Server seit vielen Jahren. In diesem Blog erstelle ich hauptsächlich Tutorials für andere Webentwickler, Webdesigner und Serveradministratoren.
-------------------------------------------------------------------------------------------------------------------------------------
I’m a web developer in Stuttgart, Germany, and server administrator since many years. This blog mainly contains a tutorial set for other web developer, web designer and server administrators.

22.437 mal gelesen

Kommentare 29

  • ViperAC -

    Für WSC 3.0/3.1 wird das wahrscheinlich nicht mehr funktionieren oder? :-/

  • Fighter456 -

    Dann hast du am Ende wohl ein Whitespace in deiner Datei hinter dem abschließenden PHP-Tag gehabt.

    Informationen über den fehlenden schließenden PHP-Tag findest du über die Suchmaschine deiner Wahl unter dem Suchwort „Instruction separation”.

  • LordHelix -

    Eine Stunde gesucht und endlich gefunden. Ich verstehe aber einfach nicht wieso.

    das abschließende ?> in der PHP Datei führt zu einem Fehler das die Seite nicht aufgerufen werden kann.

    Hier wird schondarauf hingewiesen, ich kannte das vorher nicht.
    Bitte kläre mich auf wieso das so ist und ob ich das IMMER weglassen kann.

  • DragonGun -

    Wie müssten denn CSS Anweisungen hinzugefügt werden?

    Edit: Hat sich erledigt, Flo hat mir geholfen :)
    Als LESS Datein in den Ordner "style" welche in "files.tar" aufgerufen wird.

  • Black Rider -

    Ich weiß nicht, ob der seit der Umstellung der Webseite auf Community Framework 2 jemals funktionierte. Auf GitHub gibt es die Datei aber:
    github.com/WoltLab/WCF/blob/master/XSD/package.xsd

  • CCFF -

    Dieser Link funktioniert nicht mehr: woltlab.com/XSD/maelstrom/package.xsd

    Grüße, CCFF

  • Black Rider -

    Auch unter Burning Board 4.1 funktioniert es noch problemlos. Lediglich der Seitenaufruf ist ein anderer: index.php?example/

  • creme_yT -

    Kann es sein, dass das alles beim wbb 4.1.x nicht mehr funktioniert?
    Selbst wenn ich deine Vorlage runterlade, scheint es nicht zu funktionieren. Hat sich da etwas geändert?

  • Black Rider -

    Nein, das gibt es leider aktuell nicht.

  • René Overbeck -

    Ist es möglich eure Tutorials auch als PDF anzubieten? Würde mir gerne mal eure Artikel ausführlich in den Pausen (auf der Arbeit) durchlesen, aber ich habe da keine Internetverbindung, wenn ich diesen Artikel als PDF drucken möchte, ist leider aus den Code-Blöcken nur die Hälfte dabei, wegen dem Scrollbalken :(

  • Fighter456 -

    Dazu musst du die Controller-Klasse (ExamplePage.class.php) (inklusive des Klassennamens innerhalb des Quellcodes in der Datei) und das Template umbenennen.

  • FileX -

    Ich bin echt zu dumm dafür die Seite "/index.php/Example/" in z.B. "/index.php/Beispiel/" anzuzeigen, den Rest hab ich verstanden. Kann mir das jemand erklären für jemanden der sich eine zeitlang zurück aus dem Netz gezogen hat?

  • MarvelousGenki -

    Hab folgendes probiert:
    7zip, Console, Stuffit, Keka, TarPit

    Werde mal im Forum nen Thread dazu öffnen und beide Dateien hoch laden.

  • Black Rider -

    Mit was und wie genau packst du es denn?
    Eventuell wäre das Forum auch dafür besser geeignet, da man hier besser auf das Problem eingehen könnte.

  • MarvelousGenki -

    Gibt es irgend welche bestimmten Richtlinien für das Komprimieren der Pakete?
    Ich kann egal ob auf Mac oder Windoof machen was ich will, das selbstgeschriebene Plugin lässt sich nicht installieren:

    Das angegebene Archiv ist kein gültiges Paket.

    An meinem Code kann es aber nicht liegen, da ich zum Test dein zum Download angebotenes Beispielplugin herunter geladen habe. Wenn ich es so installiere klappts. Wenn ich es allerdings einmal entpacke und dann selbst packe, kommt der Fehler wieder, auch wenn dein Plugin an sich unberührt bleibt.

  • Sporny -

    Okay, mein eigentlicher Fehler war, dass ich den Teil nach mehreren gescheiterten Versuchen einfach überlesen habe ^^

    Dazu kam noch, dass die Klassendatei auf ".php.php" geendet hat....
    Jetzt ist erstmal Zeit fürs Bett... einfach zu spät.

    Vielen Dank für die Hilfe :)

  • Black Rider -

    Das steht in der fünften Zeile unter der Klassendatei. ;)

  • Sporny -

    Woraus ich noch nicht ganz schlau werde ist:

    Wo wird die URL "index.php/Example" festgelegt?

    Habe nun etliches versucht, bekomme aber immer eine Fehlermeldung (sobald ich einen Anderen Namen haben will)

  • Stricted2 -

    siehe hier: github.com/WoltLab/WCF/blob/ma…ge/AbstractPage.class.php

  • Tillout -

    Hallo,
    wieso hast du z.B. in der Klassen Erweiterung AbstractPage gewählt. Was ist das für ein Class und woher kommt die, was machst die und so weiter .

  • Black Rider -

    acptemplates.tar

  • Grex -

    Danke für die Erklärung, aber wie funktioniert das mit den ACP Templates?, hab bis jetzt leider nicht bei einem Plugin nachsehen können, da es auf die alte Methode gemacht wurde (acptemplates.tar)

    Danke und Lg
    Grex

  • Fighter456 -

    Die Installationsroutine erwartet bei den files und templates grundsätzlich ein Archiv.

    Hättest du übrigens durch einen einfachen Selbstversuch herausfinden können. ;)

  • Tester -

    Danke für das super Tutorial. Muss ich eigentlich Template-Files immer packen, auch wenn ich nur eins habe oder könnte ich in derpackage.xml auch auf ein tpl statt auf ein tar-File verweisen?

  • CIA JOE -

    In meine erlesene Bookmarksammlung aufgenommen. 8)

  • michaelk -

    Vielen Dank Matze. Sehr informativ.