Hilfe:TemplateData

Themenübersicht > Wikisyntax > Tags > 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.

VerwendungBearbeiten

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.

AktualisierungBearbeiten

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-ObjektsBearbeiten

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.

InterfaceTextBearbeiten

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-ObjektBearbeiten

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
  • "string/line" – kurzer Text, wie er in einzeiligem <input> vorkommen kann (Name, Label)
  • "string/wiki-user-name" – geeignet als Benutzername; muss noch nicht existieren
  • "string/wiki-page-name" – geeignet als Seitenname; muss noch nicht existieren
required boolean true, falls es sich bei diesem Vorlagenparameter um einen Pflichtparameter handelt.
suggested boolean true, falls es sich bei diesem Vorlagenparameter um einen Parameter handelt, der nicht benutzt werden muss, aber empfohlen wird.
default string Standardwert des optionalen Parameters; oder Rückfallwert
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-ObjekteBearbeiten

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-FormatBearbeiten

  • 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.

KopiervorlageBearbeiten

{{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.

BeispieleBearbeiten

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

Vorlage:ThBearbeiten

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

{{TemplateData|<templatedata>
{
	"params": {
		"1": {
                       "label": "Text",
                       "description": "fremdsprachiger Text",
                       "default": "",
                       "type": "string",
                       "required": true
                      },		
                "w": {
                       "label": "Wikivoyage Transkription",
                       "description": "Deutsche Umschrift des Textes",
                       "default": "",
                       "type": "string",
                       "required": false,
                       "suggested": false
                      },
		"b": {
                       "inherits" : "w",
                       "label": "Bedeutung",
                       "description": "Deutsche Bedeutung des Textes",
                      },
		"a": {
                       "inherits" : "w",
                       "label": "Aussprache",
                       "description": "Lokale Aussprache (wenn sie von der Transkription abweicht)"
                      },
		"i": {
                       "inherits" : "w",
                       "label": "IPA",
                       "description": "Schreibweise im IPA-Alphabet"
                      },
		"audiodatei": {
                       "inherits" : "w",
                       "label": "Audiodatei",
                       "description": "Audiodatei für die Sprachausgabe des Textes",
                       "type": "wiki-file-name"
                      },
		"inKlammern": {
                       "label": "inKlammern",
                       "description": "Soll der Text in Klammern gesetzt werden?",
                       "default": "ja",
                       "type": "string",
                       "required": false,
                       "suggested": true
                      },
		"vertikal": {
                       "label": "vertikal",
                       "description": "Soll der Text in Klammern vertikal geschrieben werden?",
                       "default": "ja",
                       "type": "string",
                       "required": false,
                       "suggested": false
                      }
	},
	"description": "Die Vorlage weist fremdsprachigen Text aus.",
        "format": "inline"
}
</templatedata>}}


... Zweck ...
ParameterBeschreibungTypStatus
Bedeutung von 11
Kurzbeschreibung zu 1
Zeichenfolgeerforderlich
Bedeutung von 22
Kurzbeschreibung zu 2
Zeichenfolgeoptional

... Zweck ...

Vorlagenparameter

ParameterBeschreibungTypStatus
Bedeutung von 11

Kurzbeschreibung zu 1

Zeichenfolgeerforderlich
Bedeutung von 22

Kurzbeschreibung zu 2

Zeichenfolgeoptional

"inherits" – Vorlage:AnkerBearbeiten

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>}}


... Zweck ...
ParameterBeschreibungTypStatus
Bedeutung von 11
Kurzbeschreibung zu 1
Zeichenfolgeerforderlich
Bedeutung von 22
Kurzbeschreibung zu 2
Zeichenfolgeoptional

... Zweck ...

Vorlagenparameter

ParameterBeschreibungTypStatus
Bedeutung von 11

Kurzbeschreibung zu 1

Zeichenfolgeerforderlich
Bedeutung von 22

Kurzbeschreibung zu 2

Zeichenfolgeoptional

"aliases" – Vorlage:TemplateDataGeneratorBearbeiten

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>}}


... Zweck ...
ParameterBeschreibungTypStatus
Bedeutung von 11
Kurzbeschreibung zu 1
Zeichenfolgeerforderlich
Bedeutung von 22
Kurzbeschreibung zu 2
Zeichenfolgeoptional

... Zweck ...

Vorlagenparameter

ParameterBeschreibungTypStatus
Bedeutung von 11

Kurzbeschreibung zu 1

Zeichenfolgeerforderlich
Bedeutung von 22

Kurzbeschreibung zu 2

Zeichenfolgeoptional

"sets" – unsignedBearbeiten

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": "string/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 YYYY-MM-DD."
},
"aliases": ["2"]
},
"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"]
}
]
}


... Zweck ...
ParameterBeschreibungTypStatus
Bedeutung von 11
Kurzbeschreibung zu 1
Zeichenfolgeerforderlich
Bedeutung von 22
Kurzbeschreibung zu 2
Zeichenfolgeoptional

... Zweck ...

Vorlagenparameter

ParameterBeschreibungTypStatus
Bedeutung von 11

Kurzbeschreibung zu 1

Zeichenfolgeerforderlich
Bedeutung von 22

Kurzbeschreibung zu 2

Zeichenfolgeoptional

Abfrage über die APIBearbeiten

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-AttributeBearbeiten

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

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

CSSBearbeiten

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 HilfenBearbeiten

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:

  • JSHint
    • 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ätBearbeiten

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.

Siehe auchBearbeiten

AnmerkungenBearbeiten

  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)