Informationen für Pluginentwickler für 3.1

      Informationen für Pluginentwickler für 3.1

      In der letzten Zeit haben wir viele neue Funktionen von Burning Board 3.1 vorgestellt. Diese Funktionen benötigten natürlich auch diverse Umbaumaßnahmen "unter der Haube". Für alle Entwickler wollen wir Hinweise geben, worauf sie möglicherweise achten sollten, wenn sie ihre Anwendungen und Plugins an die neue Technik anpassen wollen.

      Ich beschäftige mich beispielsweise gerade damit unseren Kalender auf WCF 1.1 anzupassen. Ich möchte euch zeigen, welche Dinge ich beim Kalender anpassen musste.


      Installation und Abhängigkeiten

      Der erste Schritt ist natürlich erstmal den Kalender im neuen System zu installieren. Hier können potentiell die ersten Fehler auftreten, da sich die Pakete geändert haben können. Beim Kalender habe ich beispielsweise das Paket Mitgliederliste als Abhängigkeit enthalten. Diese Abhängigkeit habe ich entfernt, da es dieses Paket nicht mehr gibt. (Es wurde in das allgemeine Profilpaket integriert.)

      Nachdem ich alle Abhängigkeiten geprüft hatte, konnte ich den Kalender schon mal problemlos installieren.


      HeaderMenu -> PageMenu

      Der Kalender fügt einen Menüpunkt bei der Installation hinzu. Da wir die Menüpunktverwaltung umgebaut haben, gibt es keine headermenu.xml mehr. Auch die HeaderMenu-Klassen sind nun veraltet und sollten nicht mehr verwendet werden. An dessen Stelle tritt nun das neue PageMenu mit der entsprechenden pagemenu.xml. Ich musste hier den Eintrag <position>header</position> ergänzen.

      In den PHP-Klassen habe ich alles auf die PageMenu-Klasse umgestellt.


      Iconpfade

      Mit WCF1.1 wird es möglich sein eigene Iconsets zu definieren. Hierbei muss man nur einen eigenen Ordner anlegen, diesen im Stil verknüpfen und dann beliebige Icons in diesen Ordner legen. Das System ist so intelligent, dass fehlende Icons automatisch durch die Standardicons ersetzt werden. Diese Intelligenz muss man allerdings auch in den Templates ansprechen.

      Bislang habt ihr Icons so eingebunden:

      HTML Source Code

      1. <img src="{@RELATIVE_WCF_DIR}icon/nameDesIconsM.png" />
      2. <img src="icon/nameDesIconsM.png" />

      Nun nutzt ihr den Templatebefehl {icon}

      HTML Source Code

      1. <img src={icon}nameDesIconsM.png{/icon}" />


      Es ist keine Pflicht die Templates entsprechend umzustellen. Es ist aber sehr empfehlenswert, wenn die Benutzer eigene Icons verwenden können sollen. Es gibt allerdings ein paar Stellen, wo ihr die Pfade in jedem Fall anpassen müsst. Das sind alle XML-Dateien (PIP). (Bspw. UserCPMenu, PageMenu etc)

      Hier wurde bislang wie folgt auf ein Icon verwiesen:

      XML Source Code

      1. <icon>icon/nameDesIconsM.png</icon>


      jetzt nur noch so:

      XML Source Code

      1. <icon>nameDesIconsM.png</icon>



      Templateanpassungen

      Es gab an einigen Stellen größere Template- und CSS-Änderungen. Hier müsst ihr alle Seiten durchschauen, ob es nun Darstellungsfehler, Javascriptfehler oder sogar Ausführungsfehler aufgrund fehlender Anpassungen gibt.


      Das neue Benutzerprofil

      Der Kalender setzt einen Eventlistener auf das Benutzerprofil. Hier gab es die größten Änderungen, daher sollte jedes Plugin eingehend geprüft werden, welches etwas mit dem Benutzerprofil macht. In meinem Fall musste ich im Eventlistener nur eine Codezeile ändern:

      PHP Source Code

      1. // vorher
      2. $eventObj->user->userID
      3. // nachher
      4. $eventObj->frame->getUser()->userID


      Wenn ihr etwas anzeigen lasst, müsst ihr mit Sicherheit auch die Template ändern. Hierbei solltet ihr euch immer an dem bestehenden Code orientieren, um eine möglichst gleiche Ansicht zu gewährleisten.


      Suche

      Es gab einige Anpassungen an der Such-API, die man berücksichtigen sollte, wenn man beispielsweise einen eigenen durchsuchbaren Nachrichtentyp hat, wie bei mir die Termine.

      Die Änderungen waren hierbei notwendig, da es nun auch möglich ist eine bestehende Suche zu bearbeiten. Hier gibt es bei einigen Methoden des Interfaces SearchableMessageType Änderungen in der Parameterliste. Diese gilt es nun zu berücksichtigen.


      Seitenleiste bei Beiträgen

      Die Seitenleiste, die man bei Beiträgen sieht, wurde generalisiert. Man kann nun die neue Sidebar nutzen und hat so gewährleistet, dass sie bei jedem Beitragstypen gleich aussieht. (Beispielsweise Forenbeitrag und Termin). Hier gibt es neue Schnittstellen, beispielsweise die Statusicons, die man verwenden kann. Eine Nutzung ist nicht zwingend notwendig, aber sehr zu empfehlen. Jedes Plugin, was etwas in der aktuellen Seitenleiste bei Beiträgen ändert, muss sich das neue System genau ansehen und die neuen Schnittstellen nutzen.


      Modulsteuerung

      Da es möglich ist, dass bestimmte Features als Modul abgeschaltet werden können, sollte man dies auch im eigenen Code berücksichtigen. Dies betrifft sowohl die PHP-Klassen, als auch die Templates. Im Kalender musste ich die Module PM, Attachment, Smilies und Signatur berücksichtigen.

      Es stehen hierfür Konstanten zur Verfügung, die zur Abfrage genutzt werden können, bspw:

      PHP Source Code

      1. if (MODULE_PM) {
      2. // use pm system
      3. }
      4. else {
      5. // do something else
      6. }

      Vereinfachungen für Entwickler

      Es gibt ein paar kleine nette Neuerungen, die dem Entwickler die Arbeit einfacher machen. Man muss dieses nicht berücksichtigen, kann es aber natürlich gerne tun.

      Rechteabfrage


      Die einfache Rechteabfrage, ob eine Seite betreten werden darf ist nun nichtmehr an die ACPForm gebunden, sondern ist in der AbstractPage. Das verkürzt den Code ein wenig:

      Vorher:

      PHP Source Code

      1. class DemoPage extends AbstractPage {
      2. public function show() {
      3. WCF::getUser()->checkPermission('name.der.berechtigung');
      4. parent::show();
      5. }
      6. }


      Nachher:

      PHP Source Code

      1. class DemoPage extends AbstractPage {
      2. public $neededPermissions = 'name.der.berechtigung';
      3. }


      Exceptions im Autoloader

      Das lästige Einbinden der Exceptions am Fehlerort entfällt, da Exceptions nun über __autoload nachgeladen werden.

      Vorher:

      PHP Source Code

      1. require_once(WCF_DIR.'lib/system/exception/PermissionDeniedException.class.php');
      2. throw new PermissionDeniedException();


      Nachher:

      PHP Source Code

      1. throw new PermissionDeniedException();


      Objekte per AJAX löschen (Inline-Delete)

      Im WCF 1.1 habt ihr nun die Möglichkeit Löschaufrufe per AJAX abzuschicken und das Element elegant auszublenden.

      Das zu löschende Element muss die CSS Klasse "deletable" besitzen und der Link, der normalerweise zur Löschaktion führt muss die Klasse deleteButton besitzen.

      Beispiel:

      Smarty-Template

      1. <tr class="deletable">
      2. <td>Lorem Ipsum, dolor sit amet.<td>
      3. <td><a href="index.php?action=ObjectDelete&objectID={@$object->objectID}&t={SECURITY_TOKEN}{@SID_ARG_2ND}" class="deleteButton"><img src="{icon}deleteS.png{/icon}" alt="" longdesc="Eigener Text"/></a></td>
      4. </tr>


      Dies repräsentiert eine Tabellenzeile mit 2 Spalten, wovon eine einen Löschbutton enthält. Klickt man auf diesen Button wird der Text aus longdesc in einer Bestätigungsnachrich angezeigt. Lässt man longdesc weg, wird ein Standardtext angezeigt. Bei Bestätitgung der Löschung wird die gesamte Zeile mit dem Effect.Fade ausgeblendet und die URL des Links mit einem AJAX-Request aufgerufen.

      Verwendung des ImageViewers

      Wer den ImageViewer (Lightbox-Effekt) verwenden möchte, muss dazu folgende Schritte tun:

      Abhängigkeit ergänzen (Nicht notwendig, wenn ihr euch ins das Burning Board Paket einpluggt):

      XML Source Code

      1. <requiredpackage
      2. file="requirements/com.woltlab.wcf.imageViewer.tar">com.woltlab.wcf.imageViewer</requiredpackage>


      ImageViewer Template includen:

      {include file='imageViewer'}


      Nun müsst ihr nur noch Eure verlinkten Bilder richtig auszeichnen:
      Beispiel: Ihr habt ein Bild als Thumbnail und verlinkt es mit dem Orginal:

      HTML Source Code

      1. <!-- ohne Imageviewer -->
      2. <a href="Link zum Orginal" title="Name des Bildes"><img src="tumbnail.jpg" alt="" /></a>
      3. <!-- mit Imageviewer -->
      4. <a href="Link zum Orginal" title="Name des Bildes" class="enlargable"><img src="tumbnail.jpg" alt="" /></a>
      Einige Pluginentwickler waren bereits so fleißig ihre Pakete an die neuen WCF 1.1 bzw. Burning Board 3.1 Pakete anzupassen. Dabei sind einige Fehler gemacht worden, mit wirklich unschönen Konsequenzen.

      1. Pakete die WCF 1.1 Beta-Pakete als Requirement mitbringen, sollten selbst niemals stable sein sondern ebenfalls Beta. Ansonsten werden sie als normales Paketupdate angezeigt, was aber momentan keinen Sinn macht, da man nicht auf die Beta 1 Pakete updaten kann.

      2. Das ist eigentlich eine grundsätzliche Regel: Man sollte niemals 2 Pakete in der gleichen Version hochladen. Wenn man in einem Paket beispielsweise zusätzliche optionale Pakete mitliefern möchte, aber sonst nichts geändert hat, muss man dennoch eine andere Versionsnummer wählen.