Was ist der Zweck der templateDetails.xml-Datei?

From Joomla! Documentation

This page is a translated version of the page What is the purpose of the templateDetails.xml file? and the translation is 97% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Nederlands • ‎português do Brasil • ‎русский

Die templateDetails.xml-Datei wird für Joomla!-Templates benötigt, sie liegt im Wurzelverzeichnis jedes Templates des Joomla!-Templateverzeichnisses. Die XML-Datei enthält grundsätzliche Meta-Daten, die Joomla! zur Anzeige als Template-Option im Backend benötigt. Sie enthält weitere Meta-Daten über das Template, dessen Autor, verwendet Dateien und Verzeichnisse. Sie definiert Sprachdateien, Parameter und Einstellungen für das Backend.

Die templateDetails.xml-Datei verwendet ein einfaches XML-Format und -Struktur. Die XML-Daten der Datei sind in Abschnitte unterteilt und formatiert, die unterschiedlichen Teile und Parameter zu rendern. Die XML-Daten werden von mächtigen Werkzeugen des Joomla!-Core gelesen und geparsed, für die Template-Registrierung gerendert und für die Anzeige in der Templateverwaltung erstellt. Damit haben Templateentwickler eine recht einfache Methode, Zuordnungen, Einstellungen und Parameter für das Template zu erzeugen.

Die Umsetzung der templateDetails.xml unterscheidet sich zwischen Templates, von einfach bis komplex, je nach Template-Ausstattung. "Protostar", das Standard-Template in Joomla3 ist ein ausgezeichnetes Beispiel für die Verwendung der Datei. Die einzelnen Abschnitte der Datei werden unten erklärt.

XML Format

Die ersten 2 Zeilen jeder templateDetails.xml-Datei definieren XML-Format und Doctype.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 2.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/2.5/template-install.dtd">

Die nächste Zeile wird ebenso benötigt da sie Joomla! mitteilt, dass die Daten der Datei für eine Erweiterung, hier ein Template, verwendet werden. Alle Templatedaten sind im <extension>-Tag, der mit </extension> schließt.

<extension version="3.1" type="template" client="site">

Grundlegende Details

Der erste Abschnit enthält überlicherweise Informationen des Entwicklers über das Template. Informationen wie Namen, Daten, Kontakt, Copyright, Versionsnummer und eine einfache Beschreibung sind üblich. Die Daten werden in der Templateverwaltung in der Liste der Templates verwendet und können auch in der Bearbeitungsseite des Templates angezeigt werden.

Grundlegende Details des Templates in Templates > Templates

Template Details-Beispiel

Protostar XML-Code für grundlegende Details:

<extension version="3.1" type="template" client="site">
	<name>protostar</name>
	<version>1.0</version>
	<creationDate>4/30/2012</creationDate>
	<author>Kyle Ledbetter</author>
	<authorEmail>admin@joomla.org</authorEmail>
	<copyright>Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.</copyright>
	<description>TPL_PROTOSTAR_XML_DESCRIPTION</description>

Die letzte Codezeile, die Beschreibung, enthält einen Sprachschlüssel und keine Beschreibung. Der Schlüssel referenziert eine Sprachdatei des Templates, in der die Beschreibung definiert und geschrieben ist. Das ist die bevorzugte Methode für öffentlich verbreitete Joomla!-Erweiterungen, um internationale Sprachunterstzützung zu gewährleisten. Die Beschreibung für Übersetzungen direkt einzugeben ist möglich. Die Sprachdateien sin auch im Sprachabschnitt der templateDetails.xml definiert, der später besprochen wird.

Templatebeschreibung im Protostar-Editor

Template Details-Beispiel

Verzeichnisstruktur

Alle Verzeichnisse aus der Templateinstallation werden angezeigt. Verzeichnisse und Dateien des Wurzelverzeichnisses während der Installation werden angezeigt. Dateien in Verzeichnissen werden automatisch eingeschlossen. Jedes Verzeichnis enthält volle Pfadinformationen, das im Template-Wurzelverzeichnis beginnt. Der Administrator-Installer verwendet diese Informationen während der Installation.

Unten die Datei- und Verzeichnisstruktur des Standardtemplate "Protostar". Sie ist eine Standard-Dateistruktur für ein grundlegendes Joomla!-Template.

	<files>
		<filename>component.php</filename>
		<filename>error.php</filename>
		<filename>favicon.ico</filename>
		<filename>index.php</filename>
		<filename>templateDetails.xml</filename>
		<filename>template_preview.png</filename>
		<filename>template_thumbnail.png</filename>
		<folder>css</folder>
		<folder>html</folder>
		<folder>images</folder>
		<folder>img</folder>
		<folder>js</folder>
		<folder>language</folder>
		<folder>less</folder>
	</files>

Datei- und Verzeichnisansicht des J3-Protostar

J3 protostar file structure en.jpg

Modulpositionen

Vverfügbare Module Positionen des Templates sind in diesem Bereich definiert.

Die Modulpositionen des Standardtemplate "Protostar":

	<positions>
		<position>banner</position>
		<position>debug</position>
		<position>position-0</position>
		<position>position-1</position>
		<position>position-2</position>
		<position>position-3</position>
		<position>position-4</position>
		<position>position-5</position>
		<position>position-6</position>
		<position>position-7</position>
		<position>position-8</position>
		<position>position-9</position>
		<position>position-10</position>
		<position>position-11</position>
		<position>position-12</position>
		<position>position-13</position>
		<position>position-14</position>
		<position>footer</position>
	</positions>

Die Positionsliste werden vom <positions>-Tag umschlossen. Jeder <position>-Tag erzeugt eine Modulposition, die im Modul und anderen Bereichen verfügbar ist, in denen Modulpositionen gewählt werden.

Das simple Format der Positionen ermöglicht einfache Anpassungen. Beispiel: Eine neue Modulposition mit <position>-Tag innerhalb des <positions>-Tag und eigenem Namen, kleingeschrieben, kein Leerzeichen. Damit wird nur die Position hinzugefügt, zusätzliches Entwickeln in anderen Templatedateien ist nötig, um die Position im Frontend zu rendern.

Sprachen

Templates können Sprachdateien enthalten, um statischen Text im Template zu übersetzen. Das Sprachverzeichnis wie die beiden enthaltenen Dateien sind definiert. Auch wenn das Verzeichnis früher definiert ist, brauchen die Dateien eigene Definitionen. Die Methode sagt Joomla!, wo die Sprachdateien mit den vom Template benutzten Strings liegen.

Die erste Sprachdatei enthält Text, den Benutzer sehen. Die zweite Datei mit der .sys oder system-Erweiterung enthält Text für den Administrationsbereich.

Das Sprachverzeichnis und die Dateistruktur des Standardtemplate "Protostar".

	<languages folder="language">
		<language tag="en-GB">en-GB/en-GB.tpl_protostar.ini</language>
		<language tag="en-GB">en-GB/en-GB.tpl_protostar.sys.ini</language>
	</languages>

Sprachstrings werden in Templates und durchgehend in Joomla! für die Anpassungen der internationalen Sprachunterstützung. Damit können Entwickler und Benutzer relativ einfach Text in Templates und Erweiterungen selbst übersetzen. Joomla! prüft die Sprachdateien auf Sprachstrings und lädt sie in der gewählten Sprache. In diesem Beispiel gibt es nur Dateien für Englisch (en-GB), jede Übersetzung kommt vom Entwickler oder Benutzer, damit sie Joomla! verwenden kann.

Mehr Information zu Sprachdateien

Parameter

Protostar: Parameter des "Erweitert"-Tab

Das Template kann Anzeigeoptionen und andere Parameter haben, die der Administrator in der Templateverwaltung wählen kann. Beispiel: Im Standardtemplate "Protostar" können Farben, Schriften und Logos gewählt werden. Die Parameter im "Erweitert"-Tab werden durch XML-Parameter definiert und erzeugt.

Template-Parameter sind innerhalb des <config>-Tag, der ein <fields>-Tag mit einem name attribute der "params" enthält. Innerhalb des <fields>-Tag werden Parametergruppen und einzelne Parameter definiert. Der <fieldset>-Tag erzeugt Parametergruppen. Einzelne Parameter definiert der <field>-Tag.

Jedes <fieldset> und jeder <field>-Parameter in einem <fieldset> braucht einen eigenständigen, durch name attribute definierten Namen. Dieser Name definiert die Parameter und leitet die Einstellungen an die Frontend-Dateien. Jeder Parameter soll ein label attribute und description attribute enthalten. Der Labeltext wird mit dem Parameter in den Einstellungen angezeigt, um die Einstellung zu erklären, weitere Informationen kann die Beschreibung enthalten.

Ein Parameterfeld kann praktisch jeder Typ von Form-Input mit zugehörigen Optionen sein, die mit type attribute gewählt werden. Jede notwendige Option wie Optionsbuttons oder Auswahlen werden mit <option>-Tags definiert. CSS-Klassennamen werden mit class attribute, Standardparameter-Einstellungen mit default attribute definiert.

Unten sind die Parameter-Definitionen des Standardtemplate "Protostar". Alle Labels, Beschreibungen und Optionen nutzen Sprachstring-Definitionen der Sprachdateien wie oeben erklärt und manche vom Joomla!-Core selbst, damit sie in unterschiedliche Sprachen übersetzt werden können.

	<config>
		<fields name="params">
			<fieldset name="advanced">
				<field name="templateColor" class="" type="color" default="#08C"
					label="TPL_PROTOSTAR_COLOR_LABEL"
					description="TPL_PROTOSTAR_COLOR_DESC" />

				<field name="templateBackgroundColor" class="" type="color" default="#F4F6F7"
					label="TPL_PROTOSTAR_BACKGROUND_COLOR_LABEL"
					description="TPL_PROTOSTAR_BACKGROUND_COLOR_DESC" />

				<field name="logoFile" class="" type="media" default=""
					label="TPL_PROTOSTAR_LOGO_LABEL"
					description="TPL_PROTOSTAR_LOGO_DESC" />
					
				<field name="sitetitle"  type="text" default=""
					label="JGLOBAL_TITLE"
					description="JFIELD_ALT_PAGE_TITLE_LABEL"
					filter="string" />

				<field name="sitedescription"  type="text" default=""
					label="JGLOBAL_DESCRIPTION"
					description="JGLOBAL_SUBHEADING_DESC"
					filter="string" />

				<field name="googleFont"
					type="radio"
					class="btn-group btn-group-yesno"
					default="1"
					label="TPL_PROTOSTAR_FONT_LABEL"
					description="TPL_PROTOSTAR_FONT_DESC"
				>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>

				<field name="googleFontName" class="" type="text" default="Open+Sans"
					label="TPL_PROTOSTAR_FONT_NAME_LABEL"
					description="TPL_PROTOSTAR_FONT_NAME_DESC" />

				<field name="fluidContainer"
					type="radio"
					class="btn-group btn-group-yesno"
					default="0"
					label="TPL_PROTOSTAR_FLUID_LABEL"
					description="TPL_PROTOSTAR_FLUID_DESC"
				>
					<option value="1">TPL_PROTOSTAR_FLUID</option>
					<option value="0">TPL_PROTOSTAR_STATIC</option>
				</field>
			</fieldset>
		</fields>
	</config>

Das "Protostar"-Template illustriert die unterschiedlichen Möglichkeiten, XML in einem Template zu nutzen, es gibt aber noch weitere. Hier umschließt der <fieldset name="advanced">-Tag alle Parameter und verwendet name attribute zum Erzeugen des "Erweitert"-Tab im Interface. Für einen weiteren Tab ist nur ein zusätzlicher <fieldset>-Tag mit anderem name attribute nötig. So sind die nötigen Tabs und Parameter für ein Template recht simpel zu erzeugen.

Additional Resources