Manifest-Dateien

From Joomla! Documentation

This page is a translated version of the page Manifest files and the translation is 97% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎italiano • ‎Nederlands • ‎中文(台灣)‎
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 oder <extension_name>.xml benannt werden und steht im Root-Verzeichnis des Installations-Paket.

Die Syntax

Das Root-Element

Info non-talk.png
General Information

The new tag <extension> replaces the old <install></install> from Joomla Joomla 1.5

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 Joomla 3.x nicht verwendet und wurde aus Joomla 4.0 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:

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

	<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"

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards.

Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.


Dashboards

Info non-talk.png
General Information

This code only works in Joomla 4.0 and later

Specifies the details for displaying a dashboard for the component in the Administrator area for the site.

  • It will make a dashboard icon appear next to the administrator menu item for the component
  • The dashboard icon will click through to display modules assigned to the cpanel-example administrator module position
  • The title and icon defined in the XML file will be used as the header and icon at the top of the component's dashboard page.
	<dashboards>
		<dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard>
	</dashboards>


Konfiguration

Stop hand nuvola.svg.png
Warning!

Die Komponenten unterstützen in der Manifest-Datei keine Konfigurationsdefinitionen. Das war eine Möglichkeit, die in Joomla! 1.5 implementiert wurde. Konfigurationsoptionen für mehrere Ebenen können mit der Datei config.xml definiert werden. Wie diese zu der Komponente hinzugefügt werden kann, steht im Tutorial zur Entwicklung einer MVC-Komponente.

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.

Namespace

Info non-talk.png
General Information

This code only works in Joomla 4.0 and later

Specify the namespace to be used for autoloading the plugin. The given namespace will autoload to the root directory of your extension by default however you can optionally add a "path" attribute to the namespace element to specify a subpath within your extensions root directory.

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:

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 Ihrer Erweiterung ist (z.B. com_componentname, mod_modulename usw.). Plugins müssen die Gruppe angeben (z.B. plgsystempluginname). Bibliotheks-Pakete unterstützen keine Skriptdateien. Die Struktur der Klasse ist wie folgt:

This file should contain a class named "<element_name>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins must state the group (e.g. plgsystempluginname).

In Joomla 4.0 and later the structure of the class is as follows:

<?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;
	}
}

?>

Note that since Joomla 3.6 Joomla has shipped a basic script that you can use instead of shipping your own from scratch JInstallerScript which contains various helper methods commonly used through the community.

Library Manifests

Info non-talk.png
General Information

The section is based on Joomla 4.0 and later

A simple library manifest might look like this:

<?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>

This will install the library into the JPATH_SITE/libraries/mytest folder.

What if your company has several libraries and you want to group them together under folder JPATH_SITE/libraries/mycompany?

Simple - include your company name in the libraryname property of each library like this:

    <libraryname>mycompany/mylibrary1</libraryname>
    <libraryname>mycompany/mylibrary2</libraryname>

These libraries will then be installed in the JPATH_SITE/libraries/mycompany/mylibrary1 and JPATH_SITE/libraries/mycompany/mylibrary2 folders.

Uninstalling mylibrary1 will still leave mylibrary2 installed on your site.

When using script files with such company libraries the installer class name should look like this:

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:

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&amp;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: