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. Es wurde im Frühsommer 2013 weltweit gestartet.

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

Verwendung[Bearbeiten]

Die Kodierungen werden in <templatedata>...</templatedata> eingeschlossen.

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.

Der Inhalt des TemplateData-Elements ist Code in JSON; syntaktisch ein Bestandteil von JavaScript. In diesem Bereich wird Wikitext nicht expandiert; das bedeutet, dass Syntax-Elemente wie andere Tags, Vorlagen oder Verlinkungen nicht ausgewertet werden.[1]

Der Inhalt des in den Wikitext eingebetteten Bereichs wird auf der Dokumentationsseite in Form einer Tabelle dargestellt, durch die im Prinzip die hergebrachte Parameterdokumentation ersetzt werden kann. Voraussetzung ist die syntaktische und semantische Richtigkeit.

Um Redundanz und Inkonsistenzen zu vermeiden, muss diese Tabelle im Kopfbereich der Vorlagen als übersichtliche Zusammenstellung sichtbar sein. Es kann sein, dass die Kurzbeschreibungen bei einer komplexeren Vorlage noch weiterer Erläuterungen bedürfen; in diesem Fall kann das im nachfolgenden Wikitext vertieft und etwa durch Beispiele ergänzt werden. Auch ein umfangreicherer Einleitungsabschnitt kann der spartanischen Zweckbeschreibung vorangehen. Um TemplateData, zusätzliche Erläuterungen zu den Parametern sowie Beispiele und Kopiervorlage konsistent halten zu können, muss dies auch geschlossen im Wikitext einer einzigen Seite zusammengestellt sein.

Weil zu einer Vorlage nur eine gültige Spezifikation existieren kann, darf auch immer nur ein TemplateData-Element vorhanden sein. (Es würde nur die letzte Definition einer Seite ausgewertet.)

Ein Nutzer und aktueller Anlass ist der VisualEditor.

Aktualisierung[Bearbeiten]

Nach einer inhaltlichen Änderung der Informationen sollte ein Null-Edit auch auf der Vorlagenseite erfolgen, damit auch diese im Cache umgehend aktualisiert wird und die Metadaten baldmöglichst allen Werkzeugen zur Verfügung stehen.

Struktur des JSON-Objekts[Bearbeiten]

Das 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 nicht erlaubt.

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
Komponente JS-Datentyp Beschreibung
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.
description InterfaceText
null
Eine kurze Erläuterung zum Parameter.
type string

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

  • "unknown" (Vorgabe)
  • "number" – lässt sich als Zahl interpretieren
  • "string" – beliebige Zeichenkette
  • "line" – kurzer Text, wie er in einzeiligem <input> vorkommen kann (Name, Label)
  • "content" – Wikitext, d.h. formatierter Text, Links, Bilder, usw.
  • "wiki-file-name" – geeignet als Dateiname ohne Präfix wie Datei:, File: usw.; muss noch nicht existieren
  • "wiki-page-name" – geeignet als Seitenname; muss noch nicht existieren
  • "wiki-user-name" – geeignet als Benutzername; muss noch nicht existieren
  • "unbalanced-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"
required boolean true, falls es sich bei diesem Vorlagenparameter um einen Pflichtparameter handelt.
suggested boolean true, falls dieser Vorlagenparameter in den meisten Fällen erwartet wird bzw. standardmäßig angezeigt werden soll.
default string 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.
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
aliases Array of strings

Liste von Aliasnamen. Ein Aliasname ist ein in der Vorlagenprogrammierung verwendeter Alternativname, der genauso wirksam ist wie die Standardform.[2] 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.

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 2013) ist noch keine Realisierung in der Benutzeroberfläche des VisualEditor ersichtlich.[3]

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.

Kopiervorlage[Bearbeiten]

{{TemplateData|<templatedata>
{ "description": "... Zweck ...",
  "params": { "1": { "label":       "Bedeutung von 1",
                     "description": "Kurzbeschreibung zu 1",
                     "type":        "string",
                     "required":    true
                   },
              "2": { "label":       "Bedeutung von 2",
                     "description": "Kurzbeschreibung zu 2",
                     "type":        "string",
                     "required":    false
                   }
            }
}             
</templatedata>}}

Oder aber durch Einfügen der folgenden Zeile im Einleitungsbereich der Dokumentationsseite:

{{subst:TemplateDataGenerator}}

und anschließendes Auslösen von Vorschau zeigen – es erscheint ein JSON-Objekt usw. mit allen vorkommenden Parametern. Dieses wird kopiert, ersetzt die Einbindung und kann danach weiter ausgefüllt und angepasst werden. Das würde auch geschehen, wenn man die Seite versehentlich speichert; es belastet aber nur unnötig die Versionsgeschichte.

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; Vorgabe: Name der aktuellen Seite",
                     "type":        "string",
                     "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“; Vorgabe: „Sammlung von Bildern, Videos und Audiodateien“",
                     "type":        "string",
                     "required":    false
                   }
            }
}
</templatedata>}}


TemplateData

Verlinken einer Kategorie auf Wikimedia Commons

Vorlagenparameter
Parameter Beschreibung Typ Standard Status
Commons-Kategorie 1 Die zu verlinkende Commons-Kategorie; Vorgabe: Name der aktuellen Seite string leer optional
Deutscher Name 2 Angezeigter Name der Kategorie auf Deutsch, wenn abweichend string leer optional
Sammlung von … 3 s = „Sammlung von Bildern“; Vorgabe: „Sammlung von Bildern, Videos und Audiodateien“ string leer 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 Standard Status
Anker-1 1 Fragmentbezeichner string leer erforderlich
Anker-2 2 Weiterer Fragmentbezeichner string leer optional
Anker-3 3 Weiterer Fragmentbezeichner string leer optional
Anker-4 4 Weiterer Fragmentbezeichner string leer optional
Anker-5 5 Weiterer Fragmentbezeichner string leer optional
Anker-6 6 Weiterer Fragmentbezeichner string leer 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 Standard Status
Sortierung sort1 Alphabetische Sortierung, wenn Ziffer 1 angegeben string 0 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 Standard Status
Username user1 User name of person who forgot to sign their comment. wiki-user-name leer erforderlich
Date date2 Zeitpunkt, zu dem der Kommentar geschrieben wurde; im Datumsformat JJJJ-MM-TT. unknown leer vorgeschlagen
Year year keine Beschreibung number leer optional
Month month keine Beschreibung number leer optional
Day day keine Beschreibung number leer optional
Comment comment keine Beschreibung unknown leer optional

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.

Tag-Attribute[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.

CSS[Bearbeiten]

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

style= ist zurzeit wirkungslos.

Hilfsmittel und Hilfen[Bearbeiten]

Die Verwendung von TemplateData in dieser Wikipedia wird protokolliert unter:

Die syntaktische Gültigkeit des Codes kann vor dem Speichern mit JavaScript-Validierern überprüft werden.

  • In der Seitenvorschau wird entweder die erwartete Tabelle gezeigt, oder das Feld rot ausgefüllt.
  • Der Code kann kopiert werden auf die Seite jshint.com – er wird mittels JSHint analysiert und zeigt die fehlerhaften Zeilen.
    • Wenn bei Vorschau der Dokumentationsseite die Fehlermeldung Syntaxfehler in JSON erscheint, aber mit diesem Werkzeug kein Fehler im JSON-Code gefunden wurde, dann stimmt etwas mit dem abschließenden Tag nicht (etwa vergessener Schrägstrich).

Mit vorübergehendem Einfügen von {{subst:TemplateDataGenerator}} in die Dokumentationsseite lässt sich ein Grundgerüst generieren; siehe Kopiervorlage.

Sonstige:

Grenzen der Funktionalität[Bearbeiten]

TemplateData ist exemplarisch für ein Werkzeug, das mit wenigen Funktionen zur Verfügung gestellt wurde. Dies in der Hoffnung, dass Benutzer die Weiterentwicklung mit beeinflussen. Wenn du diesbezüglich Wünsche hast, dann kannst du es über Bugzilla mitteilen oder mitteilen lassen (Bugzilla-Kategorie).

  • Eine Liste bekannter Bugs und Anfragen zur Funktionalitätserweitung findet sich im Bugzilla-Status.

Weitere Informationen[Bearbeiten]

 MediaWiki: Extension:TemplateData – Technische Dokumentation (englisch)
  • Vorlage:TemplateData – Kennzeichnung generierter Dokumentationsblöcke
  • spec.templatedata.json Syntaktische Beschreibung bei der Implementierung (englisch)
  • Vorlage:TemplateDataGenerator – automatische Generierung mittels Lua
  • Vorlagenmeister – früherer Ansatz, über eine XML-Spezifikation; mit einem Eingabeformular
    • Optimal wäre es, den Vorlagen-Meister statt mit den bisherigen XML-Daten mit der TemplateData-Struktur zu füttern.

Anmerkungen[Bearbeiten]

  1. Unbenommen bliebe, für vielfach auftretende ähnliche Dokumentationen (etwa Flagicons) über #tag: eine gemeinsame Seite einzubinden und diese dann auch mit einem Parameter zu versehen.
  2. 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.
  3. Sinnvolle Anwendungen wären:
    • Datum (Tag, Monat, Jahr)
    • Uhrzeit (Stunde, Minuten, Sekunden, Millisekunden, Zeitzone)
    • Koordinate (Grad, Minuten, Sekunden, Himmelsrichtung)