Joomla! Documentation™

Joomla! 

4.x

Joomla! 

3.x

Joomla! 

2.5

Innerhalb von Joomla gibt es Manifestdateien für alle Erweiterungen. Diese Dateien enthalten die allgemeinen Installationsinformationen sowie Parameter für die Konfiguration der Erweiterung. Seit Joomla! 2.5 gibt es nur sehr wenige Unterschiede zwischen den Manifest-Dateiformaten für die verschiedenen types of extensions, so dass jeder Typ auf die volle Leistung des Joomla! Installers zugreifen kann.

Namenskonventionen

Die Datei muss manifest.xml (Joomla-Versionen 2.5 und 3) oder <extension_name>.xml (Joomla-Versionen 2.5, 3 und 4) benannt werden und im Root-Verzeichnis des Installations-Pakets liegen.

Joomla 4.x: Wenn der Dateiname manifest.xml für das Erweiterungs-Manifest verwendet wird, schlägt das automatische Namespace-Mapping fehl. Siehe: https://github.com/joomla/joomla-cms/issues/37750

Die Syntax

Das Root-Element

General Information

Das primäre Tag der Installationsdatei lautet:

<extension></extension>

Dieses Start- und End-Tag ist für alle Erweiterungen gleich. Die folgenden Attribute sind innerhalb des Tags zulässig:

Attribute	Werte	anwendbar bei	Beschreibung
type	component file language library module package plugin template element	Alle Erweiterungen	Dieses Attribut beschreibt den Typ der Erweiterung für das Installationsprogramm. Basierend auf diesem Typ gelten weitere Anforderungen an Sub-Tags.
version	2.5 3.0	Alle Erweiterungen	Der String identifiziert die Joomla-Version für die diese Erweiterung entwickelt wurde. Er wird in nicht verwendet und wurde aus und höher entfernt.
method	install upgrade	Alle Erweiterungen	Der Standardwert install wird auch verwendet, wenn das method-Attribut nicht verwendet wird. Der Wert install bedeutet, daß das Installationsprogramm kontrolliert beendet wird, wenn vorhandene Dateien/Ordner der neuen Erweiterung gefunden werden.
client	site administrator	Module	Mit dem client-Attribut gibt man an, für welchen Anwendungs-Client (Front- oder Back-End) das neue Modul verfügbar ist.
group	string	Plugins	Der Gruppenname gibt an, für welche Plugin-Gruppe das neue Plugin verfügbar ist. Die vorhandenen Gruppen sind die Ordnernamen im Verzeichnis /plugins. Das Installationsprogramm erstellt neue Ordnernamen für Gruppennamen, die noch nicht existieren.

Metadaten

Die folgenden Elemente können zum Einfügen von Metadaten verwendet werden. Keines dieser Elemente ist erforderlich. Wenn sie vorhanden sind, müssen sie ein untergeordnetes Element des Root-Elements sein.

<name> – raw component name (e.g. com_banners). 
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
<element> – the internal name of the component. If omitted, name will be cleaned and used

Hinweis: Die <name> und <description> Tags sind ebenfalls übersetzbare Felder, so dass der Name und die Beschreibung der Erweiterung dem Benutzer in seiner Muttersprache angezeigt werden können.

Front-End Dateien

	<files folder="from-folder">
		<filename>example.php</filename>
		<folder>examples</folder>
	</files>

Dateien, die in das Front-End-Verzeichnis kopiert werden sollen, sollten im <files>-Element abgelegt werden. Sie können das optionale folder-Attribut verwenden, um ein Verzeichnis im ZIP-Paket anzugeben, aus dem kopiert werden soll. Jede zu kopierende Datei muss durch ein <filename>-Element dargestellt werden. Wenn Sie den gesamten Ordner auf einmal kopieren möchten, können Sie ihn mit <folder> definieren.

Bei Plugins sollte der Raw-Name des Plugins im plugin-Attribut des <filename>-Elements stehen, das auf die Datei mit der Klasse des Plugins verweist. Wenn Sie z.B. ein System-Plugin mit dem Namen „example“ (vollständiger Name plg_system_example) erstellt haben, dann verwenden Sie <filename plugin="example">example.php</filename>.

Medien Dateien

	<media folder="media" destination="com_example">
		<filename>com_example_logo.png</filename>
		<folder>css</folder>
		<folder>js</folder>
	</media>

In diesem Beispiel werden die aufgelistete(n) Datei(en) (/media/com_example_logo.png) und die Ordner (/media/css/ und /media/js/) nach /media/com_example/ kopiert, wobei bei Bedarf der Ordner com_example erstellt wird. Sie können das optionale folder-Attribut verwenden, um im ZIP-Paket ein Verzeichnis anzugeben aus dem kopiert werden soll (in diesem Fall media).

Erweiterungen sollten Assets in media speichern, die sie benötigen um über das Web erreichbar zu sein (JS, CSS, Bilder usw.). Unter anderem wurde diese Funktion hinzugefügt, um den Multi-Site-Support und die eventuelle Verlagerung von Code-Dateien (PHP) aus den im Web zugänglichen Bereichen des Servers zu beschleunigen.
Hinweis: Der media-Abschnitt wird nicht nach Erweiterungen vom Typ „package“ analysiert.

Ref:

• Google Groups - joomla-dev-cms thread
• Google Groups - joomla-dev-cms thread

Der Administrations-Abschnitt

	<administration>
		<!-- various elements -->
	</administration>

Der Administrationsbereich ist im <administration>-Element definiert. Da nur Komponenten für Site und Administrator gelten, können nur Manifest-Dateien von Komponenten dieses Element enthalten.

Back-End Dateien

Dateien, die in das Back-End-Verzeichnis kopiert werden sollen, sollten im Element <files> unter <administration> abgelegt werden. Mit dem optionalen folder-Attribut können Sie ein Verzeichnis im ZIP-Paket angeben, aus dem kopiert werden soll. Weitere Regeln finden Sie unter Front-End Dateien.

Menü-Links und Untermenüs

Versions-Hinweis: noch vor Joomla 3.4 führte das Fehlen eines <menu>-Tags in Ihrer XML-Manifestdatei immer dazu, dass ein Menüelement erstellt wurde. Dieser Fehler wurde in Joomla 3.4 behoben. Wenn Ihre Manifestdatei also kein <menu>-Tag enthält, wird für die Komponente kein Admin-Menüelement erstellt.

	<menu>COM_EXAMPLE</menu>
	<submenu>
		<!--
			Note that all & must be escaped to &amp; for the file to be valid
			XML and be parsed by the installer
		-->
		<menu link="anoption=avalue&amp;anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
		<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
	</submenu>

Der Text für das Hauptmenü-Element der Komponente wird im <menu>-Element definiert, einem untergeordneten Element von <administration>. Es kann auch ein <submenu>-Element vorhanden sein (ebenfalls ein untergeordnetes Element von <administration>), das noch weitere von <menu> definierte Menüelemente enthalten kann.

Darüber hinaus kann jedes <menu>-Element die folgenden Attribute definieren:

Attribute	Beschreibung
link	Ein Link, an den der Benutzer weitergeleitet werden soll, wenn auf das Menüelement geklickt wird. Alternativ kann auch „view” verwendet werden.
img	Der (relative) Pfad zu einem Bild (16x16 Pixel), das neben dem Menü-Element angezeigt wird. Muss auch eine URL-kompatible Datei sein (z.B. keine Leerzeichen)!
alt
view	Ein URL-Parameter, der dem Link hinzugefügt werden soll. Beispielsweise würde <menu view="cpanel">COM_EXAMPLE</menu> im XML-Manifest von com_example dazu führen, dass die URL des Menü-Elements index.php?option=com_example&view=cpanel lautet. Alternativ kann auch „link“ verwendet werden.

Der Wert innerhalb des Tags ist die Bezeichnung des Menüs. Anders als in Joomla! 1.5, können Sie keine Zeichenfolge in natürlicher Sprache verwenden. Wenn Sie beispielsweise „Example Component“ anstelle von COM_EXAMPLE eingeben, wird Ihr Komponentenname als Beispielkomponente im Menü angezeigt und Sie können keine Übersetzung bereitstellen. Um eine Übersetzung bereitzustellen, müssen Sie eine Datei mit dem Namen en-GB.com_example.sys.ini in administrator/languages/en-GB oder in administrator/components/com_example/language/en-GB erstellen (Sie können das <languages>-Tag des Manifests verwenden, um sie während der Installation zu kopieren). In letzterem Fall darf die Übersetzungsdatei nicht im <languages>-Tag enthalten sein. Solange Sie das Sprachverzeichnis in Ihrem <files>-Tag gespeichert haben, wird es bei der Installation der Komponente mitkopiert.

Der Inhalt dieser Datei sollte sein:

COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

Bitte beachten, dass der Sprachstring in doppelte Anführungszeichen eingeschlossen werden muss, wie es die Übersetzungsstandards von Joomla! vorsehen.

Joomla! 1.6 und spätere Versionen sortieren die Menüpunkte der Komponenten auf der Grundlage der tatsächlichen Übersetzung des Schlüssels, der im XML-Manifest angeben ist. Das bedeutet, dass die Sortierreihenfolge korrekt ist, unabhängig davon, wie der Übersetzungsschlüssel benannt ist und in welcher Sprache die Website angezeigt wird. Im Wesentlichen hat Joomla! 1.6 die falsche Sortierung des Komponentenmenüs unter Joomla! 1.5 für die Mehrheit der (nicht Englisch sprechenden!) Joomla!-Nutzer korrigiert.

Dashboard

General Information

Spezifiziert die Details für die Darstellung eines Dashboards für die Komponente im Administratorbereich der Website.

• Neben dem Administrator-Menüpunkt für die Komponente wird ein Dashboard-Symbol angezeigt.
• Das Dashboard-Symbol zeigt die Module an, die der Position des Administratormoduls cpanel-example zugeordnet sind.
• Der Titel und das Symbol, welche in der XML-Datei definiert sind, werden als Überschrift und Symbol am oberen Rand der Dashboard-Seite der Komponente verwendet.

	<dashboards>
		<dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard>
	</dashboards>

Konfiguration

Warning!

Das Element <config>, ein Kind des Root-Elements, beschreibt die Konfigurationsoptionen für die Erweiterung. Falls zutreffend, werden die Optionen vom entsprechenden Manager (Plugin-Manager, Modul-Manager oder Template-Manager) angezeigt. Konfigurationsoptionen für Komponenten werden in einer separaten Datei (config.xml) definiert. Ihr Root-Element sollte <config> lauten, Plugins und Module verwenden den Abschnitt <config> in der Manifest-Datei der Erweiterung.

Jedes Fieldset muss ein oder mehrere <field>-Elemente enthalten, die jeweils ein einzelnes form field mit einer Bezeichnung darstellen. Eine Liste der zulässigen Formularfeldtypen und Beispiele für XML-Formularfelddefinitionen finden Sie unter Standard-Formular-Feldtypen.

Namensraum

General Information

Festlegen des Namensraums, der für das automatische Laden des Plugins verwendet werden soll. Der angegebene Namensraum wird standardmäßig in das Stammverzeichnis der Erweiterung geladen. Optional kann jedoch ein "path"-Attribut zum Namensraum-Element hinzugefügt werden, um einen Unterpfad im Stammverzeichnis der Erweiterung anzugeben.

SQL

    <install>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.install.sql</file>
        </sql>
    </install>
    <uninstall>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
        </sql>
    </uninstall>

Im obigen Beispiel haben wir die SQL-Dateien im Ordner admin/sql des Installationspakets abgelegt. Sie müssen den sql-Ordner in die Administration-Dateien aufnehmen (wie unter Back-End Dateien beschrieben).

Sie können SQL während der Installation und/oder Deinstallation mit den Elementen <install> und <uninstall> ausführen. Ein <sql>-Element sollte als untergeordnetes Element dieser Elemente angezeigt werden. <sql> kann eine beliebige Anzahl von <file>-Elementen enthalten, die jeweils eine einzelne auszuführende SQL-Datei definieren. Ihre Datenbank-Treibertypen werden durch das Attribut driver, ihre Zeichensätze durch das Attribut charset beschrieben.

Update des SQL-Schemas

Seit 1.6 gibt es auch ein <update>-Tag, mit dem Sie eine Reihe von SQL-Dateien zum Aktualisieren des aktuellen Schemas bereitstellen können.

	<update>
		<schemas>
			<schemapath type="mysql">sql/updates/mysql</schemapath>
			<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
		</schemas>
	</update>

Um beispielsweise bei einer MySQL-Datenbank von Version 1.0.0 auf Version 1.0.1 zu wechseln, muss eine 1.0.1.sql-Datei im Ordner sql/updates/mysql erstellt und das <version>-Tag des Manifests aktualisiert werden auf

<version>1.0.1</version>

Die grundlegende Struktur des SQL-Ordners sieht folgendermaßen aus (angenommen, dass eine MySQL-Datenbank genutzt wird)

sql
 |-->example.install.sql
 |-->example.uninstall.sql
 |-->updates
     |-->mysql
        |-->1.0.1.sql

Ähnliche Dateien müssen für andere Versionen erstellt werden.

Sprach-Dateien

Seit Joomla! 1.5 mussten Entwickler von Erweiterungen die Sprach-Dateien im Joomla! Haupt-Sprachen-Ordner mit dem Tag <languages>...</languages> ablegen (siehe unten). Diese Methode kann immer noch in allen Joomla! Versionen verwendet werden.

<!-- Joomla! language tag -->
<languages folder="langfiles">
	<language tag="en-GB">en-GB.com_example.ini</language>
</languages>

Dennoch wird seit Joomla! 1.6 empfohlen, dass die Sprachdateien der Erweiterung in dessen Erweiterungsordner abgelegt werden sollen. Joomla! wird dann automatisch die Sprachdateien der Erweiterung laden.

Durch das Speichern der Sprach-Dateien der Erweiterung im Erweiterungsordner profitiert man von der Isolierung und dem Schutz der Sprach-Dateien der Erweiterung. Ein Administrator entfernt zum Beispiel eine Sprache aus seiner Joomla!-Installation. Die Sprach-Dateien der Erweiterung werden dabei nicht entfernt. Sie bleiben erhalten und sind verfügbar, falls die Sprache erneut installiert wird.

Die Struktur des Sprachordners für Frontend und Backend ist gleich. Man legt diese mit dem Sprach-Tag (z.B. en-GB) der jeweiligen Sprache im Sprachenverzeichnis ab, d.h. language/en-GB/. Diese Verzeichnisse müssen auch in den Frontend- und Backend-Dateien festgelegt werden.

In der Manifest-Datei muss lediglich das Verzeichnis language in den Abschnitt files eingefügt werden. Die Unterverzeichnisse für jede Sprache werden automatisch kopiert. Innerhalb der Gruppe <files> muss das Element <folder> neben den Elementen in der Gruppe <files> hinzugefügt werden, siehe dieses Beispiel:

<files>
	<filename plugin="alpha">alpha.php</filename>
	<folder>sql</folder>
	<folder>language</folder>
</files>

Hinweis: Beide Wege können nebeneinander funktionieren. Hier ist ein Beispiel aus dem Kern:

<files>
	<filename plugin="languagecode">languagecode.php</filename>
	<filename>index.html</filename>
	<folder>language</folder>
</files>
<languages>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>

Folgende Vorteile ergeben sich aus dieser Lösung:

Alle im Kernverzeichnis vorhandenen .ini-Dateien haben Vorrang vor den Dateien im Erweiterungsordner language/. Beispielsweise wird eine .sys.ini-Datei immer aus den Core-Ordnern im Back-End geladen, wenn sie vorhanden ist, außer bei der Installation einer Erweiterung, die eine .sys.ini-Datei in einem Sprachordner enthält. In diesem Fall und nur in diesem Fall zeigt die .sys.ini-Datei im Erweiterungsordner den übersetzten Inhalt zum Zeitpunkt der Installation an. Das ist sehr praktisch. Denn ein Entwickler kann zwei .sys.ini-Dateien mit unterschiedlichen Inhalten verwenden.

Ferner ist es für einen Benutzer, der eine .ini-Datei für eine Erweiterung benötigt, die nicht in der gewünschten Sprache angeboten wird, viel einfacher, sie in den Hauptverzeichnissen hinzuzufügen. Es besteht keine Gefahr, dass sie bei einer versehentlichen Deinstallation der Erweiterung oder aus einem anderen Grund gelöscht wird.

Siehe auch:

• Making non-core language packs
• Creating language packs for extensions in Joomla 2.5

Während der Entwicklung kann in der „globalen Konfiguration“ von Joomla! das Sprach-Debugging eingeschaltet werden. So kann man nachforschen, falls ein Problem auftritt. Ab 3.2 ist dies notwendig, um das Debuggen zu unterstützen, da bei inaktivem Debug-Modus „en-GB“ immer zuerst geladen wird, um die Anzeige von Konstanten zu verhindern.

Script Datei

    <scriptfile>example.script.php</scriptfile>

Ein optionale Script-Datei (PHP-Code, der vor, während und/oder nach der Installation, Deinstallation und Aktualisierung ausgeführt wird) kann mit Hilfe eines <scriptfile>-Elements definiert werden.

Diese Datei sollte eine Klasse mit dem Namen "<element_name>InstallerScript" enthalten, wobei <element_name> der Name der Erweiterung ist (z.B. com_componentname, mod_modulename usw.). Plugins müssen die Gruppe angeben (z.B. plgsystempluginname).

In und neuer ist die Klassenstruktur wie folgt:

<?php

use Joomla\CMS\Installer\InstallerAdapter;

class com_componentnameInstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 */
	public function __construct(InstallerAdapter $adapter)
	{
	}
	
	/**
	 * Called before any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function preflight($route, InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Called after any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function postflight($route, $adapter)
	{
		return true;
	}
	
	/**
	 * Called on installation
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function install(InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Called on update
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function update(InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Called on uninstallation
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 */
	public function uninstall(InstallerAdapter $adapter)
	{
		return true;
	}
}

?>

Seit Joomla 3.6 gibt es ein einfaches Skript, das man verwenden kann, anstatt ein eigenes Skript zu entwickeln: JInstallerScript enthält verschiedene hilfreiche Methoden, die in der Community häufig verwendet werden.

Bibliothek-Manifestdatei

General Information

Eine einfache Manifestdatei einer Bibliothek könnte wie folgt aussehen:

<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="4.0">
    <name>My Test library.</name>
    <libraryname>mytest</libraryname>
    <files>
        <folder>Classes</folder>
        <folder>language</folder>
        <filename>mytest.php</filename>
    </files>
</extension>

Damit wird die Bibliothek in den Ordner JPATH_SITE/libraries/mytest installiert.

Was ist, wenn in der Firma mehrere Bibliotheken existieren und diese unter dem Ordner JPATH_SITE/libraries/mycompany zusammengefasst werden sollen?

Ganz einfach: Der Name des Unternehmens wird in die libraryname-Eigenschaft der einzelnen Bibliotheken eingefügt, etwa so:

    <libraryname>mycompany/mylibrary1</libraryname>

    <libraryname>mycompany/mylibrary2</libraryname>

Diese Bibliotheken werden dann in den Ordnern JPATH_SITE/libraries/mycompany/mylibrary1 und JPATH_SITE/libraries/mycompany/mylibrary2 installiert.

Wenn mylibrary1 deinstalliert wird, bleibt mylibrary2 weiterhin auf der Website installiert.

Wenn script files mit solchen Firmenbibliotheken verwendet wird, sollte der Klassenname des Installationsprogramms wie folgt aussehen:

class mycompanymylibrary1InstallerScript

class mycompanymylibrary2InstallerScript

Update Server

    <updateservers>
        <server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
        <server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
    </updateservers>

Update-Server können im Element <updateservers> definiert werden, einem untergeordneten Element von Root. Dieses Element kann ein oder mehrere <server>-Elemente enthalten, die jeweils den Standort angeben, von dem Updates heruntergeladen werden sollen. Jeder <server> Eintrag kann folgende Attribute definieren:

Attribut	Werte	Beschreibung
type	extension collection	Der Typ des Update-Servers
priority	integer	Die Priorität des Update-Servers
name	string	Der Name des Update-Servers

weitere Informationen:

• Entwickeln einer MVC-Komponente/Hinzufügen eines Update-Servers
• Managing Component Updates in Joomla 2.5

Download Keys Unterstützung

Ab Joomla 4.0.0 können Benutzer ihre Download-Schlüssel in der Liste der Update-Sites eingeben. Dadurch haben sie einen zentralen Ort, um die Download-Schlüssel zu verwalten. Wenn ein Benutzer eine Erweiterung aktualisieren will, prüft Joomla, ob es einen Download-Schlüssel gibt. Wenn es einen Download-Schlüssel gibt, fügt Joomla den Download-Schlüssel zur Update-URL hinzu.

Um die Download-Schlüssel zu unterstützen, muss das Tag dlid in die Manifest-Datei aufgenommen werden. Das Tag dlid akzeptiert 2 Argumente:

• prefix
• suffix

Das Tag dlid wird in der Manifest-Datei wie hier dargestellt aussehen:

<dlid prefix="dlid=" suffix="&amp;dummy=my.zip"/>

Das Präfix wird vor dem Download-Schlüssel und das Suffix nach dem Download-Schlüssel eingefügt. Im Beispiel oben lautet die vollständige Abfrage, die dem Download-Link hinzugefügt wird, wie folgt:

dlid=KEY&dummy=my.zip

Der Schlüssel wird hinzugefügt, bevor das Event onInstallerBeforePackageDownload getriggert wird, sodass die vollständige URL dem Event übergeben wird.

Beispiele

Ein reales Beispiel findet man unter: the manifest of the Banner component in the latest version of Joomla! 3.9.16.

Einige weitere Beispiele finden Sie im eigenständigen Weblink-Repository:

• com_weblinks manifest
• mod_weblinks manifest
• plg_search_weblinks manifest
• tpl_protostar manifest (3.9.16)
• en-GB manifest (3.9.16)