Schreiben Sie ihr eigenes Modul

Werden Sie Sponsor für dieses Kapitel!

Geschrieben von Andrea Tarr

Module sind der Inhalt der "Seitenleiste" und zusätzliche Widgets. Sie funktionieren oft unabhängig von Komponenten und Datenbanken.

Das Neueste Nachrichten Modul zeigt beispielweise eine Liste der zuletzt veröffentlichten Artikel. Wie Sie in diesem Kapitel sehen werden, müssen Sie sich mit dem im libraries/joomla Ordner liegenden Joomla! Framework befassen. Joomla! benutzt objekt-orientiertes PHP und daher finden Sie im libraries/joomla Ordner eine Menge Klassen. Wenn Sie diese Klassen in Ihr Programm einfügen,  wird Ihnen Joomla! eine Menge Arbeit abnehmen.

Joomla! Programme zeichnen sich durch Konventionen aus. Es nimmt an, dass Sie Ihr Programm in einer bestimmten Weise strukturieren und Ihre Dateien und Klassen in einer bestimmten Weise benennen. Das ist der Bereich in dem Sie nicht besonders kreativ sein sollten.

Backend Module liegen im administrator/modules Odner und Frontend Module im modules Ordner. Innerhalb dieser Ordner verfügt jedes Modul über einen eigenen Ordner, dessen Name mit mod_ beginnt.

In unserem Beispiel geht es um eine Kontaktliste. Eine Liste von Niederlassungen. Der Code für dieses Modul hängt als Anhang am Ende des englischen Kapitels (Download). In Abbildung 1 sehen sie die Ausgabe der Komponente.

Abbildung 1: Kontaktliste

Im Backend können Sie die Kategorie auswählen und Anzahl der Kontakte, die Sie anzeigen wollen (Abbildung 2 Das Template in dieser Abbildung ist Hathor).

Abbildung 2: Kontaktliste - Optionen im Backend

Es gibt sechs Hauptdateien, teilweise in Unterordnern, innerhalb des modules/mod_contact_list Ordners. Zusätzlich zu diesen Dateien enthält jeder Ordner eine leere index.html Datei.

mod_contact_list.xml

Die mod_contact_list.xml Datei beschreibt das Modul, für welche Version Joomla! es geeignet ist, die Dateien, die benutzt werden und die möglichen Parametereinstellungen. Die Datei ist notwendig damit das Modul installiert werden kann. Hier ist der erste Teil der Datei, der eine Basisbeschreibung des Moduls enthält:

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" version="1.7" client="site" method="upgrade">
   <name>MOD_CONTACT_LIST</name>
   <author>Andrea Tarr</author>
	<creationDate>November 2011</creationDate>
	<copyright>Copyright (C) 2011 Tarr Consulting. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later</license>
	<authorEmail>atarr@tarrconsulting.com</authorEmail>
	<authorUrl>www.tarrconsulting.com</authorUrl>
   <version>1.0</version>
   <description>MOD_CONTACT_LIST_XML_DESCRIPTION</description>

Das <extension> Tag beschreibt den Typ des Moduls, die mindestens notwendige Joomla! Version und ob es ein Frontend-  (0) oder ein Backend Modul (1) ist. Das Attribut method="upgrade" bedeutet folgendes: Wenn bereits ein Module-Ordner mit dem gleichen Namen existiert, wird angenommen, dass es sich um eine frühere Version des Programms handelt. Das Modul wird dann einfach aktualisiert. Wenn Sie die Methode "install" benutzen, so verhindert ein bereits bestehender Ordner die Installation. Die <name> und <description> Tags benutzen Sprachstrings, die in der entsprechenden Sprachdatei übersetzt werden. Die Sprachdateien werden später in diesem Kapitel erklärt.

Der nächste Teil zeigt die benutzten Dateien. Während der Installation müssen diese Dateien an die richtigen Stellen kopiert werden. Wenn Sie Dateien in Ihrem Zip-Paket haben, die hier nicht eingetragen sind, werden diese bei der Installation ignoriert. Wenn Sie eine Datei eintragen, die nicht im Zip-Paket enthalten ist, wird das Modul nicht installiert.

    <files>
        <filename>mod_contact_list.xml</filename>
        <filename module="mod_contact_list">mod_contact_list.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>

Die Hauptmoduldatei wird durch das module Attribut gekennzeichnet. Der <folder> Tag kopiert alle Dateien und Unterordner.

Der nächste Bereich definiert die Parameter, die Sie im rechten Bereich der Moduladministration sehen. Diesen Bereich umschliesst ein <config> Tag. Die Parameter befinden sich in einem <fields> Tag mit dem Attribut name="params". Jeder Slider wird durch ein eigenes <fieldset> definiert. Zuerst wählen wir die Kategorie und die Anzahl der Artikel in den basic Parametern:

    <config>
        
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="catid"
                    type="category"
                    extension="com_contact"
                    multiple="true"
                    default=""
                    size="10"
                    label="JCATEGORY"
                    description="MOD_CONTACT_LIST_FIELD_CATEGORY_DESC" >
                </field>

                <field
                    name="count"
                    type="text"
                    default="5"
                    label="MOD_CONTACT_LIST_FIELD_ITEMS_LABEL"
                    description="MOD_CONTACT_LIST_FIELD_ITEMS_DESC" />

            </fieldset>    

Jeder dieser individuellen Parameter befindet sich in einem <field> Tag. Das name Attribut ist notwendig um die Parameter aus Ihrem Programm ansprechen zu können. Das type Attribut kennzeichnet den Typ des Feldes. Jeder dieser Typen ist im Joomla! Framework definiert. Gebräuchliche Typen sind text, list, editor, textarea, category, calendar, radio, checkbox, checkboxes, media, folderlist und filelist. Eine komplette Liste finden Sie in http://docs.joomla.org/Standard_form_field_types. Wie Sie eigene Typen definieren, ist beschrieben in http://docs.joomla.org/Creating_a_custom_form_field_type. Die Feldbeschriftungen und -beschreibungen werden in den globalen Sprachdateien oder in den entsprechenden Sprachdateien der Erweiterungen definiert.

In den folgenden advanced Parametern werden die Joomla! Standard Parameter beschrieben. Sie sollten diese Parameter in jedem Modul zur Verfügung stellen, ausser wenn Sie diese Parameter explizit nicht anbieten wollen. Bis auf moduleclass_sfx reicht es aus, den entspechenden Parametercode hier einzufügen. Um moduleclass_sfx zum funktionieren zu bringen, müssen Sie noch den Befehl <?php echo $moduleclass_sfx; ?> dem class Attribut in Ihrem HTML Layout hinzufügen in dem Sie ihm erlauben, diese spezielle Klasse zu benutzen.

            <fieldset
                name="advanced">

                <field
                    name="layout"
                    type="modulelayout"
                    label="JFIELD_ALT_LAYOUT_LABEL"
                    description="JFIELD_ALT_MODULE_LAYOUT_DESC" />

                <field
                    name="moduleclass_sfx"
                    type="text"
                    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
                    description="COM_MODULES_FIELD_MODULECLASS_SFX_DESC" />

                <field
                    name="cache"
                    type="list"
                    default="1"
                    label="COM_MODULES_FIELD_CACHING_LABEL"
                    description="COM_MODULES_FIELD_CACHING_DESC">
                    <option
                        value="1">JGLOBAL_USE_GLOBAL</option>
                    <option
                        value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
                </field>

                <field
                    name="cache_time"
                    type="text"
                    default="900"
                    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
                    description="COM_MODULES_FIELD_CACHE_TIME_DESC" />

                <field
                    name="cachemode"
                    type="hidden"
                    default="itemid">
                    <option
                        value="itemid"></option>
                </field>

            </fieldset>

Beendet wird die Datei durch das Schliesen aller Tags:

        </fields>
    </config>
</extension>

mod_contact_list.php

Diese Datei mod_contact_list.php ist die wichtigste Datei für unser Program. Sie arbeitet als Controller in der Model-View-Controller Struktur. So wie der Inhalt von der Präsentation durch unterschiedliche Dateien für HTML, CSS und JavaScript getrennt wird, trennen wir auch die Kontrolle über das Programm von dessen Daten (model) und der Anzeige (view). Die Datei beginnt mit der Überprüfung ob sie über Joomla! aufgerufen wurde oder direkt über das Verzeichnis:

<?php
/**
 * Contact List
 * 
 */
 
// no direct access
defined('_JEXEC') or die;

Alle .php Dateien sollten mit diesem Code beginnen.

Wir schreiben den Code, der die Daten anfordert in die helper.php Datei. Daher müssen wir diese Datei hier einbinden. Sie enthält eine Klassendefinition, daher benötigen wir das require_once Kommando. Das dirname(__FILE__) liefert uns den aktuellen Pfad der Datei und kann daher auch als Pfad für die helper.php Datei dienen. Denken Sie daran, dass eine Klassendefinition, wenn Sie in den Code eingelesen wird, zunächst nichts ausführt.

// Include the class of the syndicate functions only once
require_once(dirname(__FILE__).'/helper.php');

Als nächstes werden wir über einen statischen Aufruf der Klasse, die in helper.php definiert ist, die Daten anfordern und das Ergebnis in der Variable $list speichern. Die Variable $params ist ein Objekt, das alle Parameter enthält, die in der xml Datei definiert sind.

// Static call to the class
$list = modContactListHelper::getList($params);

In der nächsten Zeile räumen wir ein wenig auf. Da wir den Parameter module class suffix in unserem Layout benutzen, müssen wir zunächst sicherstellen, dass keine unerwünschten Zeichen enthalten sind. Wenn wir das Kommando an diese Stelle schreiben, stellen wir sicher, das es auch ausgeführt wird, falls ein Designer das Template überschreibt.

$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

Zum Schluss müssen wir noch den Framework Module Processor einbinden, der alles zusammenbaut und das HTML, dass auf der Template Datei (tmpl/default.php) basiert,  zurückgibt. Da dieses Kommando als include ausgeführt wird, sind alle Variablen noch sichtbar.

require(JModuleHelper::getLayoutPath('mod_contact_list'));

Das ist das letzte Kommando der Datei. Fügen Sie kein  ?> Tag ein. Joomla! überspringt alle PHP Ende Tags, weil Zeichen, die danach auftauchen unter Umständen Fehlermeldungen erzeugen würden.

helper.php

Wir benutzen die Datei helper.php um die benötigten Daten anzufordern. Wir beginnen wie gewohnt:

<?php
// no direct access
defined('_JEXEC') or die;

Wir wollen Kontakte auflisten, die sich in bestimmten Kategorien befinden. Da wir eine Tabelle aus einer bestehenden Komponente benutzen werden, die nach dem Joomla! Standard funktioniert, können wir bereits vorhandene Modell-Definitionen in unserem Programm benutzen. Dazu fügen wir den Teil des Joomla Frameworks ein, der Komponentenmodelle behandelt und binden die Modelle der com_contact Komponente statisch ein.

jimport('joomla.application.component.model');
JModel::addIncludePath(JPATH_ADMINISTRATOR.'/components/com_contact/models', 'ContactModel');

Jetzt wird es Zeit, die eigentliche Klasse zu definieren. Diese Klasse hat keine Eigenschaften und getList() ist die einzige Methode:

class modContactListHelper
{
    /**
     * Retrieves the list of contacts
     *
     * @param array $params An object containing the module parameters
     * @access public
     */    
    public function getList($params)
    {

Die  Methode beginnt mit dem Einlesen der globalen Informationen durch einen statischen Aufruf der Application. Dieser Aufruf ersetzt das alte global $mainframe aus früheren Joomla! Versionen.

		$app = JFactory::getApplication();

Als nächstes lesen wir die Datenbankverbindung ein:

		$db = JFactory::getDbo();

Jetzt müssen wir eine Instanz aus  den Kontakten erzeugen. Wir benutzen dazu einen statischen Aufruf von JModel und übergeben die Komponente (Contacts) und den Klassenpräfix (ContactModel). Beim Anwenden eines Modells ist es wichtig zu wissen, in welchem Status es sich befindet (beispielsweise welche Filter gesetzt wurden). Wenn Sie ein Modul erstellen, benötigen Sie normalerweise keine Filter, die den Status einer Komponente verändern. Daher teilen wir mit ignore_request mit, dass es nicht notwendig ist, den Status zu speichern.

		// Get an instance of the generic contact model
		$model = JModel::getInstance('Contacts', 'ContactModel', array('ignore_request' => true));

Als nächstes lesen wie die Parameter der Applikation:

		$appParams = JFactory::getApplication()->getParams();
		$model->setState('params', $appParams);

Dann setzen wir die Filter, abhängig von den Moduleparametern. Den Start der Liste (list.start) setzen wir auf auf 0 um mit dem ersten Ergebnis zu beginnen. Das Ende setzen wir auf den Anzahlparameter der in den Moduleinstellungen festgelegt wird. Den filter.published setzen wir auf 1 um nur veröffentlichte Kontakte zu erhalten. Im list.select Filter geht es um die Namen der Felder, deren Werte wir benutzen wollen.

		$model->setState('list.start', 0);
		$model->setState('list.limit', (int) $params->get('count', 5));
		
		$model->setState('filter.published', 1);

		$model->setState('list.select', 'a.id, a.name, a.catid' . 
				', a.address, a.suburb, a.postcode, a.state, a.telephone ' .
				', a.published, a.access, a.ordering, a.language'.
				', a.publish_up, a.publish_down');

Der nächste Filter betrifft die ACL, um sicherzustellen, dass nur Kontakte angezeigt werden, die der jeweilige Besucher sehen darf:

		$access = !JComponentHelper::getParams('com_contact')->get('show_noauth');
		$authorised = JAccess::getAuthorisedViewLevels(JFactory::getUser()->get('id'));
		$model->setState('filter.access', $access);

Jetzt filtern wir nach der Kategorie, gemäss den Werten aus den Moduleinstellungen. Denken Sie daran, das es sich um ein Array handelt, wenn wir beliebig viele Werte in der xml Datei erlauben.

		$model->setState('filter.category_id', $params->get('catid', array()));

Der letzte Filter betrifft die Sprache und die Sortierung der Kontakte in der Liste.

		$model->setState('filter.language',$app->getLanguageFilter());
		$model->setState('list.ordering', 'ordering');
		$model->setState('list.direction', 'ASC');

Zum Schluss rufen wir die getItems() Methode im $model Objekt auf. Da wir die getItems() Methode aus der Kontakt Komponente benutzen, müssen wir keine eigene Methode schreiben, sondern können die bereits existierende Methode benutzen. Alles, was wir tun mussten, war die gewünschten Filter zu beschreiben. Wir erhalten eine Werteliste zurück und schliessen die Methode und die Klasse. Beachten Sie, dass wir wieder kein schliessendes PHP Tag einfügen

		$items = $model->getItems();
		      
		return $items;
    }
}

tmpl/default.php

Alles was wir jetzt noch tun müssen, ist das HTML für die Anzeige der Daten zu schreiben. Durch die Trennung und Speicherung der HTML Ausgabe in einer separaten Layout Datei ermöglichen wir Designern unsere Vorgaben nach ihren Wünschen zu überschreiben (Template Overrides). Die Datei beginnt wie alle php Dateien, die wir verwenden, mit einem Check ob sie durch Joomla! aufgerufen worden ist:

<?php
/**
 * Contact List Module Entry Point
 */ 

// no direct access
defined('_JEXEC') or die; ?>

Dann fügen wir das HTML für die Anzeige der Liste ein. Es ist eine gute Idee, die gesamte Ausgabe von einen <div> container umschliessen zu lassen, damit Designer (oder Sie) individuelle Formatierungen für das Modul hinzufügen können. Hier ist auch ein guter Platz für das module class suffix. Wenn Sie den PHP Code innerhalb von class direkt nach dem Modultyp einfügen, bieten Sie dem Designer die grösstmögliche Freiheit.

<div class="contact_list<?php echo $moduleclass_sfx; ?>">

Zum Schluss erstellen wir eine unsortierte Liste und führen eine Schleife aus ($list) um alle Zeilen anzuzeigen. Am Ende der Datei wird der </div> Tag geschlossen.

<ul>
<?php foreach ($list as $item) :?>
	<li><h4><?php echo htmlspecialchars($item->name); ?></h4>
	<p><?php echo nl2br(htmlspecialchars($item->address)); ?><br />
	<?php echo htmlspecialchars($item->suburb); ?>, 
	<?php echo htmlspecialchars($item->state); ?> 
	<?php echo htmlspecialchars($item->postcode); ?><br />
	<?php echo htmlspecialchars($item->telephone); ?></p></li>
<?php endforeach; ?>
</ul>
</div>

language/en-GB/en-GB_mod_contact_list.ini

Dies ist die Hauptsprachdatei für ihr Modul. In Ihrem Programm stehen alle Sprachvariablen in Grossbuchstaben mit dem Präfix MOD_CONTACT_LIST. Die Sprachstrings werden mit einem Gleichheitszeichen zugeordnet und in doppelte Hochkomma eingeschlossen. Diese Struktur ist anders als in Joomla! 1.5. Sie ist erheblich schneller, erlaubt aber keine Leerzeichen in der Variable. Da es sich um eine ini Datei handelt, benötigen Sie kein jexec or die Kommando am Anfang.

; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_CONTACT_LIST="Contact List"
MOD_CONTACT_LIST_FIELD_CATEGORY_DESC="Select Contacts from a specific Category or Categories."
MOD_CONTACT_LIST_FIELD_ITEMS_DESC="The number of Contacts to display within this module"
MOD_CONTACT_LIST_FIELD_ITEMS_LABEL="Number of Contacts"
MOD_CONTACT_LIST_XML_DESCRIPTION="The Contact List will display a fixed number of contacts from a specific category or categories."

language/en-GB/en-GB_mod_contact_list.sys.ini

Die letzte Datei ist die sys.ini Sprachdatei. Diese Datei wird nur bei der Installation, beim Update und im Backend genutzt und benötigt nur diese drei Variablen. In den drei Fällen werden viele Erweiterungen auf dem Bildschirm dargestellt die unter Umständen jeweils riesige Sprachdateien haben. Wenn Sie die kleinen sys.ini Dateien hinzufügen erhöhen Sie auch die Geschwindigkeit der Darstellung.

; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_CONTACT_LIST="Contact List"
MOD_CONTACT_LIST_XML_DESCRIPTION="The Contact List will display a fixed number of contacts from a specific category or categories."
MOD_CONTACT_LIST_LAYOUT_DEFAULT="Default"

index.html

Sie sollten immer eine index.html Datei in jeden Ordner einstellen um durch einen öffentlichen Zugriff die eventuelle Darstellung eine Inhaltsverzeichnisses durch den Webserver zu vermeiden. Das Datei kann etwa so aussehen:

<!DOCTYPE html><title></title>

Installationspaket des Moduls

Da wir bereits die xml Datei erstellt haben, müssen wir zur Erstellung eines Installationspaketes nur alle Dateien und Ordner in ein Zip Archiv komprimieren. Achten Sie darauf nur die Dateien und Ordner innerhalb des mod_contact_list Ordners zu komprimieren, nicht den jedoch den übergeordneten mod_contact_list Ordner selbst.

Wenn Ihre Dateien bereits in der Joomla! Installation vorliegen, können Sie die Funktion Überprüfen (Erweiterungen-> Überprüfen) nutzen, um das Modul zu installieren. Klicken Sie auf das Überprüfen Icon um nach Erweiterungen zu suchen die noch nicht installiert sind. Wenn ihr Modul angezeigt wird, kreuzen Sie die Checkbox an und klicken auf das Installieren Icon.