Hilfe:TemplateData/Anwendung

TemplateData können im Quelltext einer Vorlage oder ihrer Dokumentationsseite angelegt und bearbeitet werden. Sie werden innerhalb eines <templatedata>-Bereichs als JSON-Daten eingetragen.

Diese Seite beschreibt die grundlegende Anwendung. Eine allgemeine Erläuterung findet sich unter Hilfe:TemplateData.

TemplateData anlegen

Zur Anlage von TemplateData wird ein <templatedata>-Bereich eingefügt:

<templatedata>
{
	"description": "Beschreibung der Vorlage.",
	"params": {
	},
	"format": "inline"
}
</templatedata>

Der Inhalt zwischen den beiden Tags muss gültiges JSON sein. Anführungszeichen, Kommata sowie geschweifte und eckige Klammern müssen deshalb vollständig und an der richtigen Stelle gesetzt werden.

TemplateData werden vorzugsweise auf der Dokumentationsseite einer Vorlage angelegt, sofern eine solche besteht.

Aufbau

Ein TemplateData-Block kann folgende Angaben auf der obersten Ebene enthalten:

Angabe	Bedeutung
description	Kurze Beschreibung der Vorlage
params	Beschreibung der einzelnen Vorlagenparameter
paramOrder	Festgelegte Reihenfolge der Parameter
sets	Zusammenfassung von Parametern zu Parametersätzen
format	Vorgesehene Formatierung der Vorlageneinbindung
maps	Zuordnung von Vorlagenparametern zu externen Datenverbrauchern

Für einfache Vorlagen werden regelmäßig nur description, params und format benötigt.

Parameter eintragen

Die von einer Vorlage verwendeten Parameter werden innerhalb des Objekts params beschrieben. Der Name eines Parameters muss mit dem im Vorlagenquelltext verwendeten Parameternamen übereinstimmen.

Beispiel:

"grund": {
	"label": "Begründung",
	"description": "Begründung, weshalb die Seite gelöscht werden soll.",
	"type": "content",
	"required": true
}

Mehrere Parameter werden durch Kommata voneinander getrennt:

"params": {
	"name": {
		"label": "Name",
		"description": "Name des Gegenstandes.",
		"type": "line"
	},
	"beschreibung": {
		"label": "Beschreibung",
		"description": "Nähere Beschreibung des Gegenstandes.",
		"type": "content"
	}
}

Nach dem letzten Parameter darf kein weiteres Komma stehen.

Angaben zu Parametern

Für einen Parameter können folgende Eigenschaften angegeben werden:

Angabe	Bedeutung
label	Kurze, verständliche Bezeichnung des Parameters
description	Erläuterung des Zwecks und des erwarteten Inhalts
required	Kennzeichnet einen für die Funktion der Vorlage erforderlichen Parameter
suggested	Kennzeichnet einen empfohlenen, aber nicht erforderlichen Parameter
deprecated	Kennzeichnet einen veralteten Parameter; kann einen Hinweis zur ersatzweisen Verwendung enthalten
aliases	Alternative Namen des Parameters
default	Fester Standardwert oder Beschreibung des von der Vorlage verwendeten Standardwerts
autovalue	Automatisch erzeugter Wert, der bei der Einbindung vorgeschlagen oder eingesetzt werden kann
example	Beispiel für einen möglichen Parameterwert
type	Art des erwarteten Inhalts
inherits	Übernimmt Eigenschaften eines anderen Parameters
suggestedvalues	Liste vorgeschlagener Werte

Nicht jede Eigenschaft muss für jeden Parameter verwendet werden. Regelmäßig sollten wenigstens label, description und type angegeben werden.

Datentypen

Der Datentyp eines Parameters wird mit type angegeben.

Typ	Verwendung
unknown	Unbestimmter Datentyp; wird angenommen, wenn kein Typ festgelegt ist
number	Zahlenwert ohne Tausender- oder Dezimaltrennzeichen
string	Allgemeine Zeichenfolge; Zeilenumbrüche sind möglich
line	Kurzer einzeiliger Text, etwa Namen oder Bezeichnungen
boolean	Wahrheitswert
date	Datums- oder Zeitangabe im ISO-8601-Format
url	Internetadresse
wiki-page-name	Name einer Wikiseite
wiki-file-name	Name einer Datei
wiki-template-name	Name einer Vorlage
wiki-user-name	Name eines Benutzers
content	Wikitext, etwa Fließtext, Links oder Bilder
unbalanced-wikitext	Unvollständiger Wikitext, der erst gemeinsam mit anderem Inhalt einen vollständigen Ausdruck bildet

Der Datentyp sollte danach gewählt werden, welche Art von Inhalt ein Autor regelmäßig in den Parameter eintragen soll.

Erforderliche Parameter

Ein Parameter wird mit

"required": true

als erforderlich gekennzeichnet.

Diese Kennzeichnung wirkt in den unterstützten Bearbeitungsoberflächen. Sie verhindert jedoch nicht zwingend, dass eine Vorlage mit leerem Parameter gespeichert oder eingefügt wird. Soll das Fehlen eines Wertes einen Fehler auslösen oder eine Funktion der Vorlage verhindern, muss dies zusätzlich im Quelltext der Vorlage geprüft werden.

Die Vorlage:Löschen verwendet dieses Prinzip für die Begründung eines Löschantrags:

"grund": {
	"label": "Begründung",
	"description": "Begründung, weshalb die Seite gelöscht werden soll.",
	"type": "content",
	"required": true
}

Zusätzlich prüft die Vorlage selbst, ob eine Begründung angegeben wurde. Fehlt sie, wird ein Fehlerhinweis ausgegeben und die Seite nicht der Kategorie der Löschkandidaten zugeordnet.

Empfohlene Parameter

Ein nicht erforderlicher, aber regelmäßig empfohlener Parameter kann mit

"suggested": true

gekennzeichnet werden.

Empfohlene Parameter können ohne Fehler ausgelassen werden.

Alternative Parameternamen

Alternative Namen eines Parameters werden mit aliases als Liste angegeben:

"aliases": [
	"Grund",
	"Begründung"
]

Die alternativen Namen müssen auch von der Vorlage selbst verarbeitet werden, sofern sie tatsächlich verwendet werden sollen. TemplateData allein erweitern nicht die Vorlagenlogik.

Vorgeschlagene Werte

Mit suggestedvalues können mögliche Werte vorgeschlagen werden:

"suggestedvalues": [
	"Monarchie",
	"Republik",
	"Diktatur"
]

Die Bearbeitungsoberfläche kann diese Werte zur Auswahl anbieten. Andere Werte können je nach Bearbeitungsoberfläche weiterhin zulässig sein.

Reihenfolge der Parameter

Mit paramOrder kann die Reihenfolge der Parameter festgelegt werden:

"paramOrder": [
	"name",
	"beschreibung",
	"datum"
]

Alle in paramOrder genannten Namen müssen als Parameter innerhalb von params beschrieben sein.

Formatierung der Vorlageneinbindung

Mit format wird angegeben, wie die Vorlageneinbindung im Wikitext angeordnet werden soll.

Für kurze Vorlagen kann verwendet werden:

"format": "inline"

Die Einbindung wird dabei grundsätzlich in einer Zeile dargestellt:

{{Beispiel|name=Eulenthal|art=Staat}}

Für umfangreichere Vorlagen kann verwendet werden:

"format": "block"

Die Parameter werden dabei grundsätzlich zeilenweise angeordnet:

{{Beispiel
| name = Eulenthal
| art = Staat
}}

Vollständiges Beispiel

Ein vollständiger TemplateData-Block kann beispielsweise wie folgt aussehen:

<templatedata>
{
	"description": "Kennzeichnet eine Seite als Löschkandidaten.",
	"params": {
		"grund": {
			"label": "Begründung",
			"description": "Begründung, weshalb die Seite gelöscht werden soll.",
			"type": "content",
			"required": true
		}
	},
	"paramOrder": [
		"grund"
	],
	"format": "inline"
}
</templatedata>

TemplateData bearbeiten

Bei der Bearbeitung bestehender TemplateData ist darauf zu achten, dass die beschriebenen Parameter mit dem tatsächlichen Quelltext der Vorlage übereinstimmen.

Das Entfernen eines Parameters aus den TemplateData entfernt ihn nicht aus der Vorlage. Umgekehrt schafft die Aufnahme eines Parameters in die TemplateData keine neue Funktion der Vorlage.

Nach Änderungen sollte geprüft werden, ob die Vorlagendokumentation, die TemplateData und die tatsächliche Funktionsweise der Vorlage weiterhin übereinstimmen.

Siehe auch

• Hilfe:TemplateData