Manifest-Dateien

From Joomla! Documentation

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

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎italiano • ‎Nederlands
Copyedit.png
This Article Needs Your Help

This article is tagged because it NEEDS UPDATING. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


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

Das primäre Tag der Installationsdatei lautet:

<extension></extension>

Dieses Start- und Schluss-Tag ist jetzt für alle Erweiterungen gültig. Das neue Tag <extension> ersetzt das alte <install></install> von Joomla Joomla 1.5. Im Tag sind die folgenden Attribute 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.
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"

Bitte beachten Sie, dass die Sprachzeichenfolge gemäß den Übersetzungsstandards von Joomla! in doppelte Anführungszeichen eingeschlossen sein muss. Wichtiger Hinweis: Seit Joomla! 1.6 werden die Menüelemente der Komponente basierend auf der tatsächlichen Übersetzung des Schlüssels sortiert, den Sie in Ihrem XML-Manifest angeben. Das bedeutet, dass die Sortierreihenfolge korrekt ist, unabhängig davon, wie Sie Ihren Übersetzungsschlüssel benennen und in welcher Sprache die Site angezeigt wird. Grundsätzlich wurde in Joomla! 1.6 die falsche Sortierung des Komponenten-Menüs unter Joomla! 1.5 für die Mehrheit der (nicht englisch sprechenden) Joomla! Benutzer behoben.

Konfiguration

Stop hand nuvola.svg.png
Warning!

Das Element <config>, ein untergeordnetes Element von Root, beschreibt die Konfigurations-Optionen für die Erweiterung. Gegebenenfalls werden die Optionen vom entsprechenden Manager (Plugin-Manager, Module-Manager oder Template-Manager) angezeigt. Konfigurations-Optionen können auch in einer separaten Datei mit dem Namen config.xml definiert werden. Sein Root-Element sollte <config> heißen.

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.

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

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

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

Seit Joomla! 1.6 wird empfohlen, die Sprachdateien der Erweiterung im Erweiterungsordner abzulegen. Joomla! lädt dann automatisch die Sprachdateien der Erweiterung.

Mit dem Speichern der Sprachendateien im Sprachen-Ordner der Erweiterung werden die Sprachdateien der Erweiterung isoliert und geschützt. Ein Administrator entfernt beispielsweise eine Sprache aus der Joomla!-Installation. Die Sprachdateien der Erweiterung werden dabei jedoch nicht entfernt. Sie bleiben bestehen und sind, wenn die Sprache erneut installiert wird, wieder verfügbar.

Der Aufbau des Sprachordners ist für Frontend und Backend gleich. Sie geben sie in die Sprachkennzeichnung (z.B. en-GB) für jede Sprache in Ihrem Sprachordner ein, d.h. language/en-GB/. Sie müssen diese Ordner bei den Front-End als auch bei den Back-End Dateien anlegen.

In der Manifest-Datei fügen Sie einfach den 'language'-Ordner im Files-Abschnitt ein. Die Unterverzeichnisse werden für jede Sprache automatisch kopiert. Innerhalb der <files>-Gruppe fügen Sie einfach ein <files>-Element neben den Elementen in der <files>-Gruppe hinzu, wie in diesem Beispiel gezeigt:

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

Es ist erwähnenswert, dass beide Varianten zusammenarbeiten können. Hier ist ein Beispiel aus dem Core-Programm:

<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 Hauptordner vorhandenen .ini-Dateien haben Vorrang vor den Dateien im Erweiterungsordner/Sprache. Eine sys.ini-Datei wird beispielsweise immer aus den Core-Ordnern im Back-End geladen, sofern sie vorhanden ist, außer wenn eine Erweiterung installiert wird, die eine sys.ini-Datei in einem Sprachordner enthält. In diesem Fall und nur in diesem Fall zeigt die Datei sys.ini im Erweiterungsordner den übersetzten Inhalt bei der Installation an. Das ist sehr praktisch, da ein Entwickler zwei sys.ini-Dateien mit unterschiedlichen Inhalten haben kann. Eine Beschreibung der erfolgreichen Installation sowie z.B. ein Tutorial im Backend.

Außerdem ist es für Benutzer, die eine ini-Datei für eine Erweiterung benötigen und die nicht in der gewünschten Sprache angeboten wird, viel einfacher sie in den Hauptordnern zu platzieren. Es besteht kein Risiko, dass sie gelöscht wird, wenn die Erweiterung versehentlich oder aus einem anderen Grund deinstalliert wird.

Siehe auch:

Während der Entwicklung kann das Debuggen von Sprachen in der „Globalen Konfiguration“ von Joomla! aktiviert werden. So können Sie feststellen, ob Probleme auftreten. Ab Version 3.2 ist das erforderlich, um das Debuggen zu erleichtern, da en-GB, wenn nicht im Debug-Modus, 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:

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

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 einen Ort beschreiben, von dem Aktualisierungen abgerufen 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

As of Joomla 4.0.0 users can enter their download keys in the Update Sites list. This gives them a single place to manage the download keys. When a user is going to update an extension Joomla will check if there is a download key, if there is a download key Joomla will add the download key to the update url.

To support download keys you must include the dlid tag in the manifest file. The dlid tag takes 2 arguments:

  • prefix
  • suffix

The dlid tag will look like this in your manifest file:

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

The prefix will be added before the download key and the suffix after the download key. Using the example above the full query added to the download link will be:

dlid=KEY&amp;dummy=my.zip

The key is added before the onInstallerBeforePackageDownload event is triggered, so the full URL will be passed to the event.

Beispiele

Ein reales Beispiel finden Sie unter: the manifest of the Banner component in the latest version of Joomla! 3.6.4.

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