Help:TemplateData

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Help:TemplateData and the translation is 83% complete.
Other languages:
Bahasa Indonesia • ‎Cymraeg • ‎Deutsch • ‎English • ‎Ilokano • ‎Lëtzebuergesch • ‎Nederlands • ‎Oromoo • ‎Scots • ‎Tiếng Việt • ‎Türkçe • ‎Zazaki • ‎asturianu • ‎azərbaycanca • ‎català • ‎dansk • ‎emiliàn e rumagnòl • ‎español • ‎euskara • ‎français • ‎føroyskt • ‎galego • ‎hrvatski • ‎italiano • ‎lietuvių • ‎magyar • ‎occitan • ‎polski • ‎português • ‎português do Brasil • ‎română • ‎slovenčina • ‎slovenščina • ‎suomi • ‎svenska • ‎čeština • ‎Ελληνικά • ‎български • ‎македонски • ‎русский • ‎српски / srpski • ‎українська • ‎հայերեն • ‎ייִדיש • ‎עברית • ‎العربية • ‎تۆرکجه • ‎سنڌي • ‎فارسی • ‎پښتو • ‎अङ्गिका • ‎अवधी • ‎मराठी • ‎हिन्दी • ‎বাংলা • ‎ไทย • ‎ქართული • ‎中文 • ‎日本語 • ‎ꯃꯤꯇꯩ ꯂꯣꯟ • ‎한국어
PD Hinweis: Wenn Du diese Seite bearbeitest, stimmst Du zu, dass Deine Bearbeitungen unter CC0 veröffentlicht werden. Siehe Public Domain Help Pages für genauere Informationen.
PD

TemplateData ist eine Methode, Informationen über eine Vorlage und ihre Parameter zu speichern, so dass der VisualEditor sie in seinem Vorlageneditor abrufen und anzeigen kann und dadurch das Bearbeiten von Seiten mit dieser Vorlage zu vereinfachen. Sie werden zudem in Skripten, Tools und Helferlein verwendet.

Die TemplateData-Erweiterung ist in allen WMF-Wikis installiert. Wenn du ein eigenes Wiki hast, musst du Extension:TemplateData installieren.

Die TemplateData-Syntax ermöglicht es Benutzern einer Vorlagenseite kleine Mengen strukturierter Daten zu einer Vorlagenseite hinzuzufügen oder diese in die Vorlagenbeschreibung einzufügen (beispielsweise auf einer Vorlagen-Dokumentationsseite). Sobald eine Vorlage diese strukturierten Daten hat, können sie im VisualEditor ordentlich angezeigt werden. Obschon sich dies komplex anhören mag, ist es tatsächlich sehr einfach.

Vorlagendokumentations-Editor

Es gibt ein eingebautes Werkzeug, um TemplateData einfacher zu bearbeiten.

Um den Vorlagendokumentations-Editor zu verwenden, gehe zur Vorlagen-Seite (oder der zugehörigen Dokumentations-Unterseite) und klicke auf „(Quelltext) Bearbeiten“. Dann wird Dir direkt über dem offenen Bearbeitungsfenster ein Knopf mit dem Text „Vorlagendaten verwalten“ angezeigt:

Manage template documentation button for TemplateData 2014.png

Klicke auf diesen Knopf, um die grafische Benutzeroberfläche zum Bearbeiten von TemplateData aufzurufen.

Ein Bildschirmphoto des Vorlagendokumentations-Bearbeitungswerkzeugs

Der Editor ermöglicht das Hinzufügen von Vorlagenparametern und das Setzen der gebräuchlichsten Attribute. Wenn eine bearbeitete Seite bereits einen TemplateData-Block enthält, so wird die bereits dokumentierte Information automatisch angezeigt, wenn die entsprechende Seite im Vorlagendokumentations-Editor aufgerufen wird. Im ersten Kasten kannst du eine kurze Textbeschreibung der Vorlage hinzufügen oder korrigieren. Danach kannst du die Knöpfe „Parameter hinzufügen“ und „Empfohlene Parameter hinzufügen“ benutzen, um die Namen und Attribute der Parameter dieser Vorlage dokumentieren.

Wenn sich die Vorlagendokumentation auf einer Unterseite befindet, erscheint der Knopf „Empfohlene Parameter hinzufügen“ nur auf der Vorlagen(haupt)seite. Eine Möglichkeit ist das Bearbeiten der Vorlagenseite, im Vorlagendokumentations-Editor „Vorgeschlagene Parameter hinzufügen“ drücken und dann die TemplateData-Inhalte kopieren und in die Dokumentationsunterseite einfügen (zwischen den Markern <templatedata> und </templatedata>).

Falls die Vorlagenseite bearbeitungsgeschützt ist, kannst du den Vorlagencode in die Unterseite herüberkopieren, dort den Knopf „Empfohlene Parameter hinzufügen“ benutzen, die TemplateData-Inhalte kopieren, den Vorlagencode wieder aus der Unterseite löschen und dann die TemplateData-Inhalte einfügen. Um zu erfahren, wo in der Unterseite die TemplateData-Inhalte einzufügen sind, kannst du TemplateData bearbeiten, ohne etwas hinzuzufügen. Dann kannst du die Marker <templatedata> und </templatedata> ersetzen und ihre Inhalte an ihrer Statt einfügen.

Du kannst die Namen des Parameters, aller seiner Aliase, die Beschriftung und die Beschreibung auflisten, die dem Benutzer angezeigt werden. Du kannst auch ein Beispiel für die Benutzung des Parameters angeben. Das einzige erforderliche Feld ist der Name (das erste Feld in jeder Zeile), wo du den exakten, Groß- und Kleinschreibung berücksichtigenden Namen des Parameters eingeben musst. Im Aufklappmenü „Typ“ kannst du den Typ des Inhalts, den der Parameter erhalten soll wählen, wie Zeichenfolge (für unformatierte Text-Antworten), Seite (für Verweise zu anderen Seiten) oder Datei. Wenn die Vorlage einen Fehler anzeigen soll, wenn dieser Parameter leer gelassen wird, dann markiere ihn als „erforderlich“. Wenn der Parameter üblicherweise verwendet oder empfohlen wird, dann markiere ihn als „empfohlen“. Der „Parameterinformation Entfernen“-Knopf löscht den Parameter-Eintrag aus den TemplateData.

Bildschirmphoto des Vorlagendokumentations-Editors wenn ein zweiter Parameter hinzugefügt wird

Wenn Du mit der Dokumentation aller Parameter fertig bist, klicke auf „Anwenden“ um die vorformatierten TemplateData in das offene Bearbeitungsfenster einzufügen. Du musst noch mit dem normalen „Speichern“-Knopf unter dem Bearbeitungsfeld die Seite speichern.

Vorsicht: Der TemplateData-Editor wird die TemplateData entweder in die Vorlagen-Seite oder die Dokumentations-Unterseite einfügen. Du findest heraus, wo die TemplateData hinzugefügt werden, indem du die Seite zum Bearbeiten öffnest, in die du die TemplateData eingefügt haben möchtest. Wenn jedoch mehrere TemplateData-Blöcke in derselben Vorlage eingefügt werden, dann wird nur einer davon verwendet. Wenn bereits TemplateData in der Seite sind, dann musst du die Seite bearbeiten, in der die TemplateData zuvor platziert wurden, um zu vermeiden, aus Versehen mehrere Blöcke mit TemplateData zu produzieren.

Einschränkungen und Fragen

  • Fehlende Funktionen — TemplateData ist ein Beispiel für ein Werkzeug, das mit nur wenigen Merkmalen einführt wurde, in der Hoffnung, dass die Benutzer die Richtung der Entwicklung mitbestimmen. Wenn du neue Fuktionen für TemplateData anfragen möchtest, dann gib uns Bescheid.
  • Verzögerungen bei der Anzeige in Vorlagen — Nach dem Hinzufügen von TemplateData zu einer Vorlage sollten die Metadaten sofort nach dem Öffnen der Vorlage im VisualEditor sichtbar sein. Es kann allerdings mehrere Stunden dauern bis die Metadaten sichtbar werden. Du kannst mit einer leeren Bearbeitung an der Vorlagenseite (nicht der Dokumentations-Unterseite) eine Aktualisierung erzwingen. Um eine leere Bearbeitung durchzuführen, öffne die Vorlagenseite zur Bearbeitung und speichere ohne jegliche Änderungen und ohne einen Bearbeitungskommentar.
  • Bestehende Probleme — Eine Liste bestehender Fehler und Anträge für neue Funktionen sind im Fallbearbeitungssystem von Wikimedia.

Der richtige Ort für TemplateData

TemplateData sollte auf der Seite sein, die es beschreibt, oder in diese eingebunden sein. In einer Vorlage sollte es üblicherweise in <noinclude> -Marker eingeschlossen werden. Bei normaler Anzeige einer Seite zeigt es automatisch erzeugte Dokumentation wie im #Beispiel ersichtlich.

Struktur von TemplateData

Die Struktur von TemplateData basiert auf dem JSON-Standard. Beachte, dass alle TemplateData-Beschreibungen aus einfachem Text bestehen müssen (kein Wikitext, keine Verweise oder ähnliches).

Der wichtigste Inhalt ist ein Paar <templatedata>-Marker irgendwo auf der Dokumentationsunterseite, zum Beispiel folgendermaßen:

<templatedata>
{
    ...       // TemplateData steht hier
}
</templatedata>

Dies teilt der Software mit, dass alles zwischen den Markern TemplateData ist und bei Verwendung der Vorlage referenziert werden sollte.

Beispiel

Die Beschreibungen in TemplateData folgen einer normalen Gestaltung. Angenommen du hast eine Vorlage namens „Commons“ zur Verknüpfung einer Commons-Kategorie zu einem Thema. Es hat eine Pflichtangabe: den Namen der Kategorie auf Commons. Die TemplateData wäre ähnlich folgendem Beispiel:

<templatedata>
{
    "description": "Eine Vorlage zur Verknüpfung einer Commons-Kategorie zu einem Artikel",
    "params": {
        "1": {
            "label": "Commons-Kategorie",
            "description": "Die Commons-Kategorie, die du verknüpfen willst.",
            "default": "Category:CommonsRoot",
            "type": "string",
            "required": true
        }
    }
}
</templatedata>

Dies würde in der Vorlage folgendermaßen angezeigt:

Eine Vorlage zur Verknüpfung einer Commons-Kategorie über einen Artikel

Template parameters

ParameterDescriptionTypeStatus
Commons-Kategorie1

Die zu verknüpfende Commons-Kategorie.

Default
Category:CommonsRoot
Stringrequired

Beschreibung und Parameter

description Der erste Parameter ist eine Beschreibung, die die Funktion der Vorlage beschreibt.
"description": "Eine Vorlage zum Verweisen auf eine Commons-Kategorie",
format Es folgt "format", was beschreibt wie die Wikitext-Repräsentation der Vorlage gestaltet sein sollte. Dies kann entweder auf die Standardformate "inline" (Voreinstellung) und "block" oder ein angepasstes Format eingestellt werden; siehe Beispiele weiter unten.

Wenn der Parameter auf "inline" gesetzt wird, so erzeugt es eine Wikitext-Darstellung ohne Leerzeichen wie in folgendem Beispiel:

{{Foo|bar=baz|qux=quux}}

Wenn der Parameter auf "block" eingestellt wird, wird eine Darstellung mit Zeilenumbrüchen und einzelnen Leerzeichen zwischen jeden Teilen erzeugt:

{{Foo
| bar = baz
| qux = quux
}}
"format": inline
params Es gibt einen "params"-Marker, der anzeigt, dass folgende Abschnitte jeden Parameter der Vorlage behandeln.

Alle folgenden Parameter sind im "params"-Abschnitt aufgeführt.

"params": {
    ...    // Parameter gehören hier hin
}
  Im der erste Marker im Unterabschnitt jedes Parameters ist der Name des Vorlagenparameters innerhalb der Vorlage.

Wenn der Parameter einen Namen hat, beispielsweise {{{Kategorie-Verknüpfung}}}, so wäre dieser Marker "Kategorie-Verknüpfung".

Ist der Parameter „unbenannt“, also nur eine Zahl wie {{{1}}}, so wäre der Marker "1".

Alle Informationsschnippsel über diesen Parameter werden in den Abschnitt nach dem Parametername aufgenommen.

"1": {     // Name des Parameters
    ...    // Informationen über den Parameter hier hin
}
label Danach kommt ein menschenlesbarer Titel für den Parameter zur Anzeige im Vorlageneditor in "label".
"label": "Commons-Kategorie",
description Danach kommt die "description": Diesmal handelt es ich um eine Beschreibung der Parameter, nicht der gesamten Vorlage.
"description": "Die Commons-Kategorie, die du verknüpfen willst.",
default Danach kommt "default". Einige Vorlagen haben einen Vorgabewert, der verwendet wird, falls nichts anderes angegeben wird. Dieser Punkt sagt dem Benutzer was der Vorgabewert dieses Parameters ist.

Wenn kein Vorgabewert existiert, kannst du diesen Parameter ignorieren.

"default": "Category:CommonsRoot",
type Danach haben wir "type", was die Interpretation des Parameters im Vorlageneditor bestimmt. Dies kann sein:
  • "string": eine Anzahl Zeichen, so wie dieser Satz;
  • "number": eine Anzahl von Ziffern;
  • "boolean": '0' for false, '1' for true, '' for unknown;
  • "wiki-user-name": eine Anzahl Zeichen, die einen Benutzernamen darstellen;
  • "wiki-page-name": eine Anzahl Zeichen, die einen Seitentitel darstellen.
  • "wiki-file-name": ein Dateiname.

Other types include: "unknown", "date", "url", "wiki-template-name", "content", "unbalanced-wikitext", "line"

"type": "string",
required Es folgt "required", was entweder auf true oder auf false gesetzt werden kann.

Dies bestimmt lediglich ob der Parameter verpflichtend ausgefüllt werden muss. Falls nichts angegeben ist, wird false angenommen.

"required": true
suggested Es gibt "suggested", was auf true oder false gesetzt werden kann.

Dies ist ein Status für Parameter, die nicht ‚erforderlich‘ aber als wertvoll empfohlen sind, aber nicht vom Benutzer erzwungen werden. Falls nichts angegeben ist, wird false angenommen.

"suggested": true
deprecated Schließlich gibt es "deprecated", wofür true, false oder eine Zeichenfolge angegeben werden kann, die beschreibt, was der Benutzer stattdessen tun soll.

Dies ist ein Status für Parameter, die erstmal weiter bestehen aber nichtmehr benutzt werden sollten. Grund könnte eine Umstellung von einem Parametersatz auf einen anderen sein. Falls nichts angegeben ist, wird false angenommen.

"deprecated": "Please use 'publicationDate' instead."

Drücke „speichern“, wenn du fertig bist. Wenn du Fehler gemacht hast wird das Speichern verhindert (was störend ist, aber Funktionsstörungen verhindert). Sollten Fehler auftreten, dann erkläre auf der Rückmeldungsseite was du tun wolltest und wir werden dir gerne helfen.

Note that if you are abusing a hack template to dynamically generate TemplateData, it cannot be checked for errors before saving.

Beachte dass jeder Informationsschnippsel in Anführungszeichen gesetzt wird (außer true und false) und vom nächsten mit einem Komma abgetrennt wird (sofern es nicht der letzte ist).

Custom formats

When editing custom format strings in the TemplateData editor you can either type \n or press the enter key to represent a newline; in either case it will display as in the entry field.

Examples of formats you can use
Objective Format string Output
Inline formatting {{_|_=_}}
inline
{{Foo|bar=baz|qux=quux}}{{Bar}}
Block formatting {{_\n| _ = _\n}}
block
{{Foo
| bar = baz
| qux = quux
}}{{Bar
}}
No space before the parameter name,

each template on its own line

\n{{_\n|_ = _\n}}\n
{{Foo
|bar = baz
|qux = quux
}}
{{Bar
}}
Indent each parameter {{_\n |_ = _\n}}
{{Foo
 |bar = baz
 |qux = quux
}}{{Bar
}}
Align all parameter names to a given length {{_\n|_______________ = _\n}}\n
{{Foo
|bar             = baz
|qux             = quux
|veryverylongparameter = bat
}}
{{Bar
}}
Pipe characters at the end of the previous line {{_|\n _______________ = _}}
{{Foo|
  bar             = baz|
  qux             = quux}}{{Bar}}
Inline style with more spaces, must be at start of line \n{{_ | _ = _}}
{{Foo | bar = baz | qux = quux}}
{{Bar }}
Template at the start of a line, indent-aligned parameters, pipe beforehand \n{{_ |\n _______________ = _}}
{{Foo |
  bar             = baz |
  qux             = quux}}
{{Bar}}

Parameter-Aliase

Einige Vorlagen erlauben mehrere Namen für den selben Parameter.

Zum Beispiel könnte statt {{Commons|category=Apples}} auch {{Commons|Apples}} oder {{Commons|link=Apples}} geschrieben werden.

Um diese Information in TemplateData aufzunehmen musst du nur die Aliase zu den Informationen des jeweiligen Parameters hinzufügen.

    "params": {
        "Kategorie": {
            ...
            "aliases": ["1", "Verknüpfung"]
        }

Automatisch auszufüllende Werte

Du kannst für Parameter Werte angeben, die automatisch ausgefüllt werden, wenn ein Benutzer eine Vorlage zu einer Seite hinzufügt. Zum Beispiel benötigen viele Wartungsvorlagen das Hinzufügedatum. Wenn du für das Datum einen angibst Automatikwert angibst, so wird das Datum automatisch ausgefüllt.

Um diese Information in TemplateData aufzunehmen musst du nur den Automatikwert den Parameterinformationen hinzufügen. Dann ist die Verwendung mit dem Präfix subst: ratsam, um die Werte einmalig fest, statisch eintragen zu lassen.

    "params": {
        "Datum": {
            ...
            "autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"
        }

Mehrere Parameter

Wenn du mehrere Parameter hast, dann wiederhole einfach jeden Abschnitt (beginnend mit dem „1“-Marker) und fülle es aus wie du denkst. Beachte dass bei mehreren Parametern diese folgendermaßen mit Kommata getrennt werden müssen:

"params": {
    "1": {
        ...
    },      // beachte das Komma hier
    "2": {
        ...
    },      // und hier
    "3": {
        ...
    }
}

Ähnliche Parameter

Wenn eine Vorlage mehrere Parameter hat, können manchmal einige gleichartig sein. Dann musst du nur für den ersten vollständige Angaben machen und die weiteren können diese übernehmen.

    "params": {
        "Thema1": {
            "label": "Thema",
            "description": "Ein auf der Begriffsklärungsseite aufgeführtes Thema",
            "type": "string"
        },
        "Thema2": {
            "inherits": "Thema1"
        },
        "Thema3": {
            "inherits": "Thema1"
        },
    }

Leere Kopiervorlage

Du kannst die folgende leere Kopiervorlage verwenden, um einer Vorlage neue TemplateData hinzuzufügen. Es sind nur die gebräuchlichsten Marker enthalten.

<templatedata>
{
    "description": "",
    "params": {
        "1": {
            "label": "",
            "description": "",
            "type": ""
        },
        "2": {
            "label": "",
            "description": "",
            "type": ""
        }
    }
}
</templatedata>

Errors

Syntax Error in JSON / Bad JSON format

Due to a long standing bug, users using the old wikitext editor are able to save pages which have certain types of invalid JSON, such as duplicate keys or trailing commas (details: task T128029). However if you attempt to save this page in a JavaScript based editor, such as VisualEditor or the 2017 Wikitext editor, you will see an error message "Syntax error in JSON," as the JavaScript parser is stricter and doesn't allow invalid JSON. Additionally, if you attempt to open up such invalid JSON with the Template Data GUI editor, you will see the error message, "Bad JSON format." To fix these errors, you can enter the JSON block into an external JSON validator, such as https://jsonlint.com/, and it will highlight the problematic commas and keys so they can be removed.

Weitere Werkzeuge

Help:Extension:TemplateWizard
A toolbar dialog window for entering template wikitext via an form built from TemplateData.
TemplateData Wizard
Ein Werkzeug zur Erzeugung von TemplateData mit einer interaktiven Oberfläche.
Skeleton TemplateData generator
Ein Werkzeug, das den Wikiquellcode einer Vorlage einließt, alle benutzten Parameter zu erkennen versucht und dann ein Rohdokument mit den aufgelisteten Parametern ausgibt.
JSONLint
Ein Werkzeug, das handgeschriebenes JSON überprüfen und Syntaxfehler aufzeigen kann.