Hilfe:TemplateData

aus Wikipedia, der freien Enzyklopädie
Wechseln zu: Navigation, Suche
Hilfe > Bausteine > Vorlagen > TemplateData

Dieses Element ermöglicht die Generierung von Angaben über Vorlagen, mit denen sich gültige Einbindungen überprüfen lassen und automatische Dokumentationen und Anwendungshinweise erstellt werden können.

Grundprinzip[Bearbeiten]

Die als TemplateData vereinbarten Informationen über den Zweck der Vorlage und vor allem die detaillierte Beschreibung der Parameter haben zwei Anwendungsbereiche:

  • Erstellung einer standardisierten Dokumentationsseite oder eines wesentlichen Teils davon
  • Auswertung und automatische Generierung von Eingabeformularen für die Parameter nebst automatisierter Gültigkeitsprüfung der Werte schon bei der Eingabe. Dafür gibt es zurzeit zwei Anwendungen:
    1. VisualEditor – aktueller Anlass für die Entwicklung.
    2. Vorlagenmeister – früherer Ansatz, über eine XML-Spezifikation; mit einem Eingabeformular zum Einfügen in den Quelltext der Wikiseite. Falls keine (detailliertere) XML-Beschreibung für eine bestimmte Vorlage vorhanden ist, wird ersatzweise die TemplateData-Struktur zur Produktion eines Eingabeformulars und zur Gültigkeitsprüfung der Eingabedaten herangezogen.

Das Grundprinzip wurde üblichen Software-Dokumentationswerkzeugen entnommen; ist etwa an die mit javadoc zu gewinnenden Informationen angelehnt.

Technisch werden die TemplateData in einem <templatedata>...</templatedata>-Element kodiert, das im Abschnitt Struktur des JSON-Objekts beschrieben wird. Der Inhalt wird von der Software automatisch in Form einer Tabelle dargestellt, durch die im Prinzip die hergebrachte Parameterdokumentation ersetzt werden kann. Voraussetzung ist die syntaktische und semantische Richtigkeit.

Diese werden mit der Vorlagendefinition in Verbindung gebracht. In der deutschsprachigen Wikipedia sollte dies immer auf der Dokumentationsseite /Doku geschehen und nicht direkt im Quelltext der Vorlagenprogrammierung.

  • In der Versionsgeschichte der eigentlichen Programmierung sollen ausschließlich Änderungen an der wirksamen Programmierung erscheinen, niemals jedoch nachrangige Formulierungsverbesserungen an der Dokumentation; diese gehört deshalb auf die Unterseite /Doku.

Dabei wird das Element <templatedata>...</templatedata> immer in eine {{TemplateData}} eingeschlossen, die für eine Umrahmung und eine Verlinkung mit dieser Hlfeseite sorgt.

Die Inhalte von TemplateData sind dafür vorgesehen, in universell nutzbarem Format einfache und kurze Texte bereitzustellen; etwa in Tooltips oder automatisierten Dokumentationssystemen unabhängig vom Wikiprojekt. Elaborierte und komplexe Darstellungen müssen nach wie vor in gesondertem Wikitext aufbereitet werden.

Formulargestützte Erstellung und Bearbeitung[Bearbeiten]

Schritt 1: Vorlagendokumentations-Editor aufrufen[Bearbeiten]

Auf Vorlagen- oder deren Dokumentationsseiten kann das TemplateData-Element automatisch erzeugt werden indem man in den Bearbeitungsmodus geht und dort auf den Knopf Vorlagendaten verwalten am Seitenkopf klickt. Auf die gleiche Weise können bestehende TemplateData-Elemente nachträglich bearbeitet werden.

Wichtig: Wenn ein neues TemplateData-Element erstellt werden soll, sollte immer zuerst die Vorlagenseite entsprechend aufgerufen werden, da nur so der nachfolgende Editor alle Parameter der Vorlage automatisch finden und importieren kann. Das wie nachfolgend beschrieben am Ende erzeugte templatedata-Element sollte dann auf die entsprechende Dokumentationsseite kopiert und die Änderungen an der Vorlagenseite verworfen werden.

Schritt 2: Parameter automatisch importieren lassen oder manuell hinzufügen[Bearbeiten]

Abbrechen
Anwenden
Vorlagendokumentations-Editor
Sprache hinzufügen
DeutschBlack triangle.svg

Sprache

Vorlagenbeschreibung (de)

Kurzbeschreibung der Vorlage


Parameterreihenfolge

 
Parameter1
 
Parameter2
 
Parameter3
 
Parameter4


Vorlagenparameter

 
Parameter1
Beschreibung des 1. Parameters
 
Parameter2
Beschreibung des 2. Parameters
 
Parameter3
Beschreibung des 3. Parameters
 
Parameter4
Beschreibung des 4. Parameters
Parameter hinzufügen

Nach dem Klick auf den Knopf erscheint der rechts abgebildete Vorlagendokumentations-Editor, der im Abschnitt Vorlagenparameter die gefunden Parameter auflistet, die mit einem Klick auf vorgeschlagene Parameter hinzufügen importiert werden können, die dann alle wie rechts beispielhaft abgebildet aufgelistet werden.

Die einzelnen Abschnitte sind:

Sprache
Hiermit kann die Dokumentationssprache der Vorlage geändert werden in dem mit einem Klick auf Sprache hinzufügen eine neue hinzugefügt oder aus dem Auswahlliste eine bestehende ausgewählt werden kann. Generell ist dies jedoch nicht notwendig und sollte auf Deutsch belassen werden.
Vorlagenbeschreibung (de)
In diesem Abschnitt sollte eine knappe einzeilige Beschreibung der Vorlage eingegeben werden, die dann im VisualEditor neben dem jeweiligen Vorlagennamen aufgeführt wird.
Parameterreihenfolge
Hier werden alle gefunden Parameter aufgeführt und deren Reihenfolge ausgegeben. Bei einem Parameterimport kann die Reihenfolge evtl. durcheinander sein und hier mittels Drag and Drop korrigiert werden. Die Reihenfolge beeinflusst, dabei nicht die Auflistung der Parameter im Vorlagen-Formular des VisualEditors, sondern auch im endgültigen Quelltext. Die Reihenfolge der Parameter sollte daher stets mit der von evtl. Beispielen, Kopierschnipseln usw. der jeweiligen Vorlagendokumentation übereinstimmen.
Vorlagenparameter
Diese wichtigste Abschnitt listet alle gefunden Parameter und deren Kurzbeschreibung, sowie vorhanden. Mit einem Klick auf den jeweiligen Parameter können bzw. bei einem neuen TemplateData-Element müssen hier die Zusatzinformationen (Metadaten) der Parameter hinzugefügt werden. Dabei erscheint ein weiteres Formular wie nachfolgend abgebildet.
Parameter hinzufügen
Am Ende des Formulars befindet sich ein weiter Knopf mit weitere Parameter hinzugefügt werden können, falls der automatische Import diese übersehen hat oder die Vorlage nachträglich um weitere Parameter ergänzt wurde.
Anwenden
Änderungen übernehmen und TemplateData-Element ausgeben.

Schritt 3: Parameter beschreiben[Bearbeiten]

Zurück
Vorlagendokumentations-Editor
Name
 
Aliasse (durch Kommas getrennt)
 
Bezeichnung (de)
 
Beschreibung (de)
 
Beispiel (de)
 
Typ (de)
 
Standard (de)
 
Autowert
 
Veraltet
 
Erforderlich
 
Vorgeschlagen
 
Parameterinformationen entfernen

Das Vorlagenparameter-Formular besitzt folgende Felder:

Name
Bezeichnet den primären Namen des Parameters, d. h. denjenigen der am Ende ausgegeben werden soll. Unbenannte Parameter bekommen eine Nummer, die deren Position in der Vorlage angibt.
Aliasse
Listet die alternativen Namen des Parameters auf, wobei die einzelnen Einträge durch Kommas getrennt werden müssen. Hinweis: Wenn die Parameter automatisch importiert wurden, werden für alternativen Namen im vorigen Formular ebenfalls Einträge angelegt, da die Importmechanismus nicht erkennen kann, ob ein Parametername eine Alternativbezeichnung oder ein eigenständiger Parameter ist. Diese falschen Parametereinträge müssen in diesem Formular mit einem Klick auf den Knopf Parameterinformationen entfernen am Formularende gelöscht werden und deren Namen im Aliasse-Feld des korrekten Parametereintrags eingetragen werden.
Bezeichnung
Falls von dem Parameternamen nicht automatisch auf die Funktion geschlossen werden kann, kann hier eine verständlichere Bezeichnung angegeben werden, die im VisualEditor verwendet werden soll.
Beschreibung
Eine Beschreibung der Funktion des Parameters. Hinweis: Die Beschreibung unterstützt keine Wikitext-Sprachelemente wie Links, Formatierungen, usw., so dass auf diese verzichtet werden muss.
Beispiel
In diesem Feld kann ein Beispielwert angegeben werden, der im VisualEditor bei noch leeren Parametern anfangs angezeigt wird, damit der Vorlagennutzer erkennen kann, wie ein gültiger Eintrag aussehen muss.
Typ
Hier kann der Datentyp des Parameters angegeben werden, d. h. welche Werte der Parameter akzeptiert. Dabei kann nach folgende Checkliste vorgegangen werden, d. h. der Parameter erlaubt:
  1. Wikitext, z. B. Wikilinks, Formatierungen → Inhalt
  2. nur Name einer Medien- bzw. Bilddatei ohne Präfix (z. B. Datei:, Bild:, …) → Datentyp Datei
  3. nur Benutzername → Benutzer
  4. nur Artikel- oder sonstiger Seitenname → Seite
  5. nur Zahl, idealerweise ohne Tausendertrennzeichen und mit Punkt . als Dezimaltrenner → Nummer
  6. nur Datum nach ISO 8601, d. h. üblicherweise JJJJ-MM-TT → Datum
  7. nur Wahrheitswert mit 0 = Nein und 1 = Ja → Boolesch
  8. akzeptiert nicht wohlgeformten Wikitext, z. B. schließendes Tag ohne öffnendes Tag und umgekehrt → Unausgeglichener Wikitext
  9. sonstiger einzeiliger Text → Zeile
  10. sonstiger mehrzeiliger Text → Zeichenfolge
  11. unbekannt → Nicht definiert
Standard
Hier kann angegeben werden, welcher Wert von der Vorlage implizit angenommen wird, wenn der Parameter nicht ausgefüllt wird. Beispielsweise nutzen viele Infobox-Vorlagen den Seitentitel als Überschrift oder verwenden für Bilder eigene Bildgrößen (z. B. 200px) und besitzen einen Extra-Parameter mit dem dieses Verhalten überschrieben werden kann. In diesen Fällen kann dann bei diesen Parametern hier "Seitentitel" oder "200px" angegeben werden.
Autowert
Hier kann angegeben werden mit welchem Wert ein noch leerer Vorlagenparameter vorausgefüllt werden soll, der dann auch im Quelltext abgespeichert wird.
Veraltet
Gibt an, ob der Parameter veraltet ist. Wenn ein Parameter als veraltet markiert wurde, dann erscheint ein zusätzliches Eingabefeld in dem ein kurzer Hinweis angegeben werden sollte, wie weiter verfahren werden soll, z. B. welcher Parameter statt dessen genutzt werden sollte.
Erforderlich
Gibt an ob der Parameter unbedingt notwendig ist, damit die Vorlage ordnungsgemäß funktioniert.
Vorgeschlagen
Vorgeschlagene Parameter sind solche, deren Nutzung empfohlen wird, d. h. jene die am häufigsten verwendet werden. Diese werden im VisualEditor immer angezeigt und müssen nicht erst ergänzt werden und werden am Ende auch immer im Quelltext ausgegeben, selbst wenn sie nicht ausgefüllt wurden.
Parameterinformationen entfernen
Hiermit kann der Parameter gelöscht werden. Dies sollte nur gemacht werden, wenn der Parameter entweder aus der Vorlage vollständig entfernt wurde oder ein Alternativname eines bestehenden Parameters ist. Parameter die nicht mehr verwendet werden sollten und nur aus Kompatibilitätsgründen noch von der Vorlage unterstützt werden, sollten statt dessen als Veraltet markiert werden.
Zurück
Änderungen übernehmen und zur Parameterübersicht zurückkehren.

Schritt 4: Änderungen übernehmen[Bearbeiten]

Nachdem alle Parameter beschrieben wurden, kann im Hauptformular auf Anwenden geklickt werden, woraufhin das TemplateData-Element erstellt wird. Falls die Vorlage eine Dokumentationsseite besitzt und man wie Eingangs beschrieben das TemplateData-Element auf der Vorlagenseite erzeugt hat, bitte das Element auf die Dokumentationseite kopieren und die Änderungen an der Vorlagenseite verwerfen.

Nach einer inhaltlichen Änderung der Informationen kann man optional einen Null-Edit auf der Vorlagenseite tätigen, damit auch diese im Cache umgehend aktualisiert wird und die Metadaten baldmöglichst allen Werkzeugen zur Verfügung stehen.

Struktur des TemplateData-Objekts[Bearbeiten]

Hinweis: Dieser Abschnitt beschreibt die zugrundeliegende Datenstruktur des TemplateData-Objekts als technische Hintergrundinformation. Wenn die im vorigen Abschnitt genannte formulargestützte Erstellung und Bearbeitung genutzt wird, können dieser und die folgenden Abschnitte daher übersprungen werden.

Das in <templatedata>...</templatedata> eingebettete JSON-Objekt (root) muss mindestens eine Komponente params haben. Zusätzlich sollte eine kurze Vorlagenbeschreibung mitgeliefert sein.

description
Optional
Kurzbeschreibung der Vorlage
Muss als Überschrift geeignet sein; also nur ultrakurz in wenigen Stichworten den Zweck nennen. Es sollte nur der eigentliche Zweck benannt werden, Einleitungsformalitäten wie „Vorlage zur“ sind redundant und sollten wegen beschränkten Platzes im Interface unterbleiben.
params
Objekt, das für jeden Vorlagenparameter ein Parameter-Objekt enthält.
Pflichtangabe; aber {} ausreichend für eine parameterlose Vorlage.
  • Typ: Objekt
sets
Optional
Array mit Set-Objekten, auf die für Parametergruppen Bezug genommen wird.
  • Typ: Array

Andere als diese drei Komponenten sind in diesem Objekt auf der Dokumentationsseite nicht erlaubt.

Bei Abfragen über die API wird allerdings eine weitere Komponente zurückgeliefert:

paramOrder
Automatisch generiert
Array mit den Komponenten-Bezeichnern im Parameter-Objekt, und zwar in der Reihenfolge, in der die Parameter in einer Benutzeroberfläche präsentiert werden sollen.
Es wird automatisch anhand der physischen Abfolge in <templatedata> gebildet.
Das Array ist erforderlich, weil die Reihenfolge von Komponenten in einem Objekt beliebig und nicht vorhersagbar ist.

InterfaceText[Bearbeiten]

Der InterfaceText ist ein für Menschen lesbarer Text, der in der Vorlagendokumentation angezeigt wird.

Er kann in zwei Varianten auftreten:

  • Zeichenkette mit dem Text selbst.
  • Objekt mit Komponenten, wobei jeweils einem Sprachcode (wie de oder de-ch oder en) der entsprechende Text zugeordnet wird.
    • In der Darstellung auf der Dokumentationsseite der Vorlage wird die Projektsprache genutzt, da eine konstante Aufbereitung im Cache hinterlegt wird. uselang= ist hier also wirkungslos.
    • Dynamische Auswertungen des JSON-Objektes sehen alle Sprachvarianten und können bei intelligenter Programmierung die bevorzugte Sprache des Benutzers berücksichtigen.

Wie im gesamten JSON-Objekt ist kein Wikitext möglich; auch HTML-Formatierungen werden nicht umgesetzt.

Parameter-Objekt[Bearbeiten]

Das Parameter-Objekt ist das Kernstück der Definition.

  • Weil es zum Auffinden ungültiger Parameterzuweisungen benutzt werden kann, müssen alle zulässigen Parameter einbezogen werden.
  • Zukünftig nicht mehr erwünschte Parameternamen können als deprecated (veraltet) gekennzeichnet werden.

Die Komponente params des TemplateData-Objekts ist ein Objekt, bei dem jedem Namen eines Vorlagenparameters eine Einzelspezifikation zugewiesen wird:

{ "description": "Zweck der Vorlage",
  "params": { "ParameterA": { ... Einzelspezifikation A ... },
              "ParameterB": { ... Einzelspezifikation B ... },
              usw. usw.
            }
}
Einzelspezifikation; alle Komponenten optional
Bezeichnung Komponente JS-Datentyp Beschreibung
Bezeichnung label InterfaceText
null
Eine kurze Beschreibung für den Parameter.
Der eigentliche Parametername kann stark abgekürzt oder lediglich eine Nummer sein.
Es sollte versucht werden, sich auf zwei Dutzend Zeichen zu beschränken.
Beschreibung description InterfaceText
null
Eine kurze Erläuterung zum Parameter.
Typ type string

Der „Datentyp“ des Parameterwertes (alle Vorlagenparameter sind Zeichenketten) für Gültigkeitsprüfungen. Einer von:

  • "unknown" (Nicht definiert) – (Vorgabe)
  • "boolean" (Boolesch) - Wahrheitswert, d. h. 0 für nein und 1 für ja
  • "content" (Inhalt) – Wikitext, d. h. formatierter Text, Links, Bilder, usw.
  • "date" (Datum) – Datum/Zeit nach ISO 8601
  • "line" (Zeile) – kurzer Text, wie er in einzeiligem <input> vorkommen kann (Name, Label)
  • "number" (Zahl) – lässt sich als Zahl interpretieren
  • "string" (Zeichenfolge) – beliebige Zeichenkette
  • "wiki-file-name" (Datei) – geeignet als Dateiname ohne Präfix wie Datei:, File: usw.; muss noch nicht existieren
  • "wiki-page-name" (Seite) – geeignet als Seitenname; muss noch nicht existieren
  • "wiki-user-name" (Benutzer) – geeignet als Benutzername; muss noch nicht existieren
  • "unbalanced-wikitext" (Unausgeglichener Wikitext) – Wikitext-Fragment, das nicht wohlgeformte Einzelbestandteile enthält, z. B. {{echo|before=<u>|after=</u>}}

Veraltet aber weiterhin funktionsfähig sind die folgenden Codes, die baldmöglichst ersetzt werden sollten:

  • "string/line" – jetzt nur "line"
  • "string/wiki-page-name" – jetzt nur "wiki-page-name"
  • "string/wiki-user-name" – jetzt nur "wiki-user-name"
Erforderlich required boolean true, falls es sich bei diesem Vorlagenparameter um einen Pflichtparameter handelt.
Wenn ein Parameter als notwendig markiert ist, kann man dieses Feld nicht löschen, wenn man eine neue Vorlage hinzufügt, oder eine bestehende Vorlage bearbeitet.
Vorgeschlagen suggested boolean true, falls dieser Vorlagenparameter in den meisten Fällen erwartet wird bzw. standardmäßig angezeigt werden soll.
Beispiel example InterfaceText
null
Mögliche Beispielwerte für den Parameter.
Standard default InterfaceText
null
Standardwert, den die Vorlage annimmt, wenn der entsprechende Parameter nicht ausgefüllt wird. Dies ist lediglich eine visuelle Hilfe, d. h. wenn der entsprechende Parameter nicht vom Benutzer ausgefüllt wird und ein default-Wert angegeben ist, wird dieser beim Speichern nicht als Standardwert übernommen, sondern der Parameter bleibt leer.
Autowert autovalue string Standardwert mit dem der Vorlagenparameter ausgefüllt werden soll, z. B. {{subst:#time:Y-m-d}} wenn ein Parameter mit dem aktuellen Datum (im Format JJJJ-MM-TT) ausgefüllt werden soll.
inherits string Name eines anderen Parameters, dessen Spezifikation als Basis für diesen Parameter geerbt werden soll. Zusätzlich angegebene Komponenten überschreiben diese Ausgangswerte.
deprecated boolean
string
  • true, falls veraltet
  • Zeichenkette, mit kurzer Begründung für den Anlass; etwa als Tooltip
Aliasse aliases Array of strings

Liste von Aliasnamen. Ein Aliasname ist ein in der Vorlagenprogrammierung verwendeter Alternativname, der genauso wirksam ist wie die Standardform.[1] Für einen reinen Aliasnamen wird keine gesonderte Einzelspezifikation angelegt.
Wenn zusätzliche Informationen erforderlich sind, ist eine gesonderte Einzelspezifikation zu benutzen und ggf. als "deprecated" zu markieren.

Die Spalte Bezeichnung gibt den Namen dieses Parameter im eingebauten Vorlagendokumentations-Editor wieder. Falls diese "–" ist, dann kann diese über den Editor nicht angegeben werden.

Set-Objekte[Bearbeiten]

Das Array sets kann Objekte mit der folgenden Struktur enthalten:

Komponente Datentyp Beschreibung
label InterfaceText Eine kurze Bezeichnung für den Parametersatz.
Es sollte versucht werden, sich auf zwei Dutzend Zeichen zu beschränken.
params Array Ein Array mit Namen von Parametern in diesem Set.
Es muss sich um Bezeichner handeln, die im Parameter-Objekt definiert sind.

Zurzeit (Sommer 2015) ist noch keine Realisierung in der Benutzeroberfläche des VisualEditor ersichtlich.[2]

JSON-Format[Bearbeiten]

  • Eine Zuweisung besteht aus dem Namen der Komponente, einem Doppelpunkt : und dem zugewiesenen Wert.
  • Während dies bei allgemeinen JavaScript-Objekten nicht erforderlich ist, muss in JSON der Name in Anführungszeichen " eingeschlossen werden.
  • Jedes Objekt ist in geschweifte Klammern {} einzuschließen.
  • Als Wert kann ebenfalls ein neues Objekt auftreten.
  • Zeichenketten sind in " einzuschließen.
  • In einem Objekt aufeinanderfolgende Zuweisungen (=Komponenten) werden durch Kommata getrennt. Nach der letzten Komponente darf kein Komma stehen.
  • Leerzeichen und Zeilenumbrüche außerhalb von Zeichenketten sind beliebig.
  • Soll im Text " vorkommen, muss es durch \" escaped werden; ein einzelner \ ist als \\ anzugeben.
  • Das allereinfachste zulässige TemplateData-Element wäre damit:
    <templatedata>{"params":{}}</templatedata>

Ein geeigneter Einrückungsstil sollte die Lesbarkeit für Menschen sichern.

Die syntaktische Gültigkeit wird bei der Seitenvorschau überprüft; bei Syntaxfehlern das Feld rot ausgefüllt. Die Technik-Werkstatt hilft weiter.

Code-Beispiele[Bearbeiten]

Ein einfacheres und ein komplexeres Beispiel für die Definition und die Darstellung auf der Dokumentationsseite.

Vorlage:Commonscat[Bearbeiten]

Der nachstehende Code bewirkt die darunter wiedergegebene Tabelle, wie sie für {{Commonscat}} benutzt wird. Daraus wird diese für Werkzeuge abrufbare Struktur erzeugt.

{{TemplateData|<templatedata>
{ "description": "Verlinken einer Kategorie auf Wikimedia Commons",
  "params": { "1": { "label":       "Commons-Kategorie",
                     "description": "Die zu verlinkende Commons-Kategorie",
                     "default":     "(Name der aktuellen Seite)",
                     "type":        "wiki-page-name",
                     "required":    false
                   },
              "2": { "label":       "Deutscher Name",
                     "description": "Angezeigter Name der Kategorie auf Deutsch, wenn abweichend",
                     "type":        "string",
                     "required":    false
                   },
              "3": { "label":       "Sammlung von …",
                     "description": "s = „Sammlung von Bildern“",
                     "default":     "Sammlung von Bildern, Videos und Audiodateien",
                     "type":        "string",
                     "required":    false
                   }
            }
}
</templatedata>}}


TemplateData

Verlinken einer Kategorie auf Wikimedia Commons

Vorlagenparameter
Parameter Beschreibung Typ Status
Commons-Kategorie 1

Die zu verlinkende Commons-Kategorie

Standard
(Name der aktuellen Seite)
Beispiel
leer
Autowert
leer
wiki-page-name optional
Deutscher Name 2

Angezeigter Name der Kategorie auf Deutsch, wenn abweichend

Standard
leer
Beispiel
leer
Autowert
leer
string optional
Sammlung von … 3

s = „Sammlung von Bildern“

Standard
Sammlung von Bildern, Videos und Audiodateien
Beispiel
leer
Autowert
leer
string optional

"inherits" – Vorlage:Anker[Bearbeiten]

Der nachstehende Code bewirkt die darunter wiedergegebene Tabelle (Vorlage:Anker). Hier wird für die wiederholten optionalen Parameter die Komponente "inherits" genutzt. Daraus wird diese für Werkzeuge abrufbare Struktur erzeugt.

{{TemplateData|<templatedata>
{ "description": "Linkziel(e) zu einem Abschnitt oder einem Element in dieser Wiki-Seite vereinbaren",
  "params": { "1": { "label":       "Anker-1",
                     "description": "Fragmentbezeichner",
                     "type":        "string",
                     "required":    true },
              "2": { "label":       "Anker-2",
                     "inherits":    "1",
                     "description": "Weiterer Fragmentbezeichner",
                     "required":    false },
              "3": { "label":    "Anker-3",
                     "inherits": "2" },
              "4": { "label":    "Anker-4",
                     "inherits": "2" },
              "5": { "label":    "Anker-5",
                     "inherits": "2" },
              "6": { "label":    "Anker-6",
                     "inherits": "2" }
            }
}
</templatedata>}}


TemplateData

Linkziel(e) zu einem Abschnitt oder einem Element in dieser Wiki-Seite vereinbaren

Vorlagenparameter
Parameter Beschreibung Typ Status
Anker-1 1

Fragmentbezeichner

Standard
leer
Beispiel
leer
Autowert
leer
string erforderlich
Anker-2 2

Weiterer Fragmentbezeichner

Standard
leer
Beispiel
leer
Autowert
leer
string optional
Anker-3 3

Weiterer Fragmentbezeichner

Standard
leer
Beispiel
leer
Autowert
leer
string optional
Anker-4 4

Weiterer Fragmentbezeichner

Standard
leer
Beispiel
leer
Autowert
leer
string optional
Anker-5 5

Weiterer Fragmentbezeichner

Standard
leer
Beispiel
leer
Autowert
leer
string optional
Anker-6 6

Weiterer Fragmentbezeichner

Standard
leer
Beispiel
leer
Autowert
leer
string optional

"aliases" – Vorlage:TemplateDataGenerator[Bearbeiten]

Der nachstehende Code bewirkt die darunter wiedergegebene Tabelle (Vorlage:TemplateDataGenerator). Hier wird für die alternative Variante des Sortierungs-Parameters die Komponente "aliases" genutzt. Daraus wird diese für Werkzeuge abrufbare Struktur erzeugt.

{{TemplateData|<templatedata>
{ "description": "Erstellt aus der Vorlagenprogrammierung ein Grundgerüst für die Dokumentation der vorkommenden Parameter mittels TemplateData",
  "params": { "sort":
              { "label":       "Sortierung",
                "description": "Alphabetische Sortierung, wenn Ziffer 1 angegeben",
                "type":        "string",
                "required":    false,
                "default":     "0",
                "aliases":     [ "1" ]
              }
            }
}
</templatedata>}}


TemplateData

Erstellt aus der Vorlagenprogrammierung ein Grundgerüst für die Dokumentation der vorkommenden Parameter mittels TemplateData

Vorlagenparameter
Parameter Beschreibung Typ Status
Sortierung sort1

Alphabetische Sortierung, wenn Ziffer 1 angegeben

Standard
0
Beispiel
leer
Autowert
leer
string optional

"sets" – unsigned[Bearbeiten]

Der nachstehende Code bewirkt die darunter wiedergegebene Tabelle, in der die Komponente "sets" verwendet wird. (vorläufig bis deutschsprachiger Ersatz):

{
	"description": "Label unsigned comments in a conversation.",
	"params": {
		"user": {
			"label": "Username",
			"type": "wiki-user-name",
			"required": true,
			"description": "User name of person who forgot to sign their comment.",
			"aliases": ["1"]
		},
		"date": {
			"label": "Date",
			"description": {
				"en": "Timestamp of when the comment was posted, in YYYY-MM-DD format.",
				"de": "Zeitpunkt, zu dem der Kommentar geschrieben wurde; im Datumsformat JJJJ-MM-TT."
			},
			"aliases": ["2"],
			"suggested": true
		},
		"year": {
			"label": "Year",
			"type": "number"
		},
		"month": {
			"label": "Month",
			"inherits": "year"
		},
		"day": {
			"label": "Day",
			"inherits": "year"
		},
		"comment": {
			"required": false
		}
	},
	"sets": [
		{
			"label": "Date",
			"params": ["year", "month", "day"]
		}
	]
}


TemplateData

Label unsigned comments in a conversation.

Vorlagenparameter
Parameter Beschreibung Typ Status
Username user1

User name of person who forgot to sign their comment.

Standard
leer
Beispiel
leer
Autowert
leer
wiki-user-name erforderlich
Date date2

Zeitpunkt, zu dem der Kommentar geschrieben wurde; im Datumsformat JJJJ-MM-TT.

Standard
leer
Beispiel
leer
Autowert
leer
unknown vorgeschlagen
Year year

keine Beschreibung

Standard
leer
Beispiel
leer
Autowert
leer
number optional
Month month

keine Beschreibung

Standard
leer
Beispiel
leer
Autowert
leer
number optional
Day day

keine Beschreibung

Standard
leer
Beispiel
leer
Autowert
leer
number optional
Comment comment

keine Beschreibung

Standard
leer
Beispiel
leer
Autowert
leer
unknown optional

Hilfsmittel und Hilfen[Bearbeiten]

Die Verwendung von TemplateData in dieser Wikipedia wird protokolliert unter:

  • Special:PagesWithProp/templatedata
  • Kategorie:Vorlage:mit TemplateData – Besser lesbar und würde keine Weiterleitungen aufzählen; dafür sind momentan zwangsläufig Vorlagenprogrammierung und Dokumentationsseite aufgeführt.
    • Die Kategorisierung zählt nur Verwendungen auf, die in {{TemplateData}} eingeschlossen sind. Die Aufzählung der Seiten mit der templatedata-Eigenschaft auf der Spezialseite muss identisch sein mit den Doku-Seiten in der Kategorie.

Debugger / Validierer[Bearbeiten]

Die syntaktische Gültigkeit des Codes kann vor dem Speichern überprüft werden; in der Seitenvorschau wird entweder die erwartete Tabelle gezeigt, oder im Fehlerfall das Feld rot ausgefüllt.

  • Wenn bei Vorschau der Dokumentationsseite die Fehlermeldung Syntaxfehler in JSON erscheint, aber mit den Werkzeugen kein Fehler im JSON-Code gefunden wurde, dann stimmt etwas mit dem abschließenden Tag nicht (etwa vergessener Schrägstrich).

Speziell für JSON-Code eignet sich:

  • jsonlint.com – der Code kann auf diese Seite kopiert werden und zeigt die fehlerhaften Zeilen.

Jeder andere JavaScript-Validierer kann ebenso zur ersten Fehlersuche verwendet werden.

Generatoren[Bearbeiten]

Alternativ zum eingebauten Vorlagendokumentations-Editor:

  • liefert das Benutzerskript jsonXMLutils aus der Vorlagenprogrammierung oder aber der Kopiervorlage einer älteren Dokumentation oder dem Quelltext einer beliebigen Einbindung ein Grundgerüst.
    • Nebenbei formatiert es auch den JSON-Code und analysiert ihn auf bestimmte mutmaßliche inhaltliche Fehler.
    • Eine XML-Struktur für den Vorlagenmeister kann aus jeder mit TemplateData ausgestatteten Vorlagendokumentation generiert werden.
  • kann mit dem vorübergehendem Einfügen von {{subst:TemplateDataGenerator}} in die Dokumentationsseite ebenfalls ein Grundgerüst generiert werden.
  • gibt es ein Benutzerskript in der französisch- und englischsprachigen Wikipedia mit einem alternativen Dialogmenü: fr:User:Ltrlg/scripts/TemplateDataEditor.js bzw. en:User:NicoV/TemplateDataEditor. Dieses befindet sich jedoch auf einem älteren Stand und unterstützt daher nicht alle Datentypen oder den „Vorgeschlagen“-Parameter (suggested), dafür aber den deprecated- und den inherited-Parameter.

Bei anhaltenden Problemen hilft die Technik-Werkstatt weiter.

Sonstiges[Bearbeiten]

Die TemplateData-Verwendung wurde im Frühsommer 2013 weltweit gestartet.

Abfrage über die API[Bearbeiten]

Mittels der API kann zu einer Vorlage die gültige Definition zu einer Vorlage abgefragt werden. Damit stehen sie anderen Software-Werkzeugen zur Verfügung.

Die spezifische API-Syntax ist automatisch generiert abrufbar, aber nicht sehr aussagekräftig.

Ein Aufruf für die durch Software unmittelbar nutzbare Form wäre action=templatedata&titles=Template:Commonscat – in einer menschenfreundlicher formatierten Darstellung siehe oben.

Anpassung der Darstellung der Parametertabelle[Bearbeiten]

Für das Tag <TemplateData> sind zurzeit keine eigenen Attribute vorgesehen.

Die Standard-Attribute id= class= style= werden nicht beanstandet; sind jedoch zurzeit wirkungslos.

Die optische Darstellung der auf der Dokumentationsseite angezeigten Tabelle kann angepasst werden.

Selektor Element
.mw-templatedata-doc-wrap Gesamte Beschreibung
.mw-templatedata-doc-desc Aufgabenbeschreibung
.mw-templatedata-doc-params Tabelle
.mw-templatedata-doc-param-name Parametername
.mw-templatedata-doc-param-type Parametertyp
.mw-templatedata-doc-muted Standardwert

Funktionswüsche und Bugs[Bearbeiten]

Wenn du Wünsche hast, dann kannst du es über Phabricator mitteilen (Phabricator-Kategorie) oder mitteilen lassen. Das gleiche gilt für Bugmeldungen.

Weitere Informationen[Bearbeiten]

 MediaWiki: Extension:TemplateData – Technische Dokumentation (englisch)

Anmerkungen[Bearbeiten]

  1. Beispiele in der Vorlage:
    {{{Stadt|{{{city|}}}}}}
    oder
    {{{5|{{{Sonderfall|}}}}}}
    Dann ist city ein Alias für Stadt und Sonderfall ein Alias für den fünften unbenannten Parameter.
  2. Sinnvolle Anwendungen wären:
    • Datum (Tag, Monat, Jahr)
    • Uhrzeit (Stunde, Minuten, Sekunden, Millisekunden, Zeitzone)
    • Koordinate (Grad, Minuten, Sekunden, Himmelsrichtung)