Zum Inhalt springen

Hilfe:Vorlagen/TemplateData/JSON

Aus Wikonia

Auf dieser Hilfeseite wird inhaltlich detailierter auf die Verwendung von JSON im Zusammenhang mit der Vorlage TemplaeDate eingenagen. Es findet Anwendung in der Vorlagenprogrammierung und dient sowohl dem Zweck die Vorlagendokumentation ansprechender zu gestalten und die Darstellung konsistent zu halten, zudem wird es durch den VisualEditor genutzt um die Eingabemaske für das Einfügen von Vorlagen zu ermöglichen.

Diese Seite stellt eine Vertiefung des Themas dar und richtet sich primär an Personen, die sich mit der Programmierung von Vorlagen beschäftigen, oder ein Interesse daran haben, die Technik hinter Wikonia besser zu verstehen und zu erlernen. Einige Abschnitte dieser Hilfeseite setzen ein gewissen Grundverständnis für Syntax und Programmierung im Allgemeinen voraus. Es ist uns leider nicht möglich eine vollumfängliche Anleitung so anzubieten, dass sie allgemeinverständlich bleibt. Wo immer es uns möglich ist, haben wir über die Belegfunktion weitere Informationen und nützliche Seiten verlinkz, die einen tieferen Einblick in das Thema ermöglichen, um sich Grundwissen anzueignen.

Hilfebereich bei Wikonia
Hilfebereich bei Wikonia

Hilfebereich

Benutzerkonto

Navigation & Suche

Seitenbearbeitung

Seitenorganisation

Vorlagen & Module

Diskussionen & Anträge

Gadgets

Phorge


Kurzinformation zu JSON
Die JavaScript Object Notation, ist ein textbasiertes, strukturiertes Datenformat, dass in der Programmierung genutzt wird, um Daten zwischen verschiedenen Sofwareanwendungen auszutasuchen. Die grundlegende Struktur aus Datenpaaren und die einfache Syntax machen eine schnelle Adaption und Entwicklung von Schnittstellen möglich. Darüberhinaus ist seine reduzierte und konsistente Notation dennoch für den Entwickler nachvollziehbar und kann auch ohne Tools ausgelesen werden.[1]

Aufbau des TemplateData-Blocks[Bearbeiten | Quelltext bearbeiten]

Der TemplateData-Block, der durch die Tags <templatedata>…</templatedata> umschlossen wird erwartet als Format ein einziges JSON-Objekt, mit einem strukturierten Afbau. Es werden dabei nicht alle ANgaben vorrausgesetzt, ebenso ist die Reihenfolge nicht zwingend einzuhalten. Die später in den Beispielen auf dieser Seite dargestellte Reihenfolge hat sich derartig etabliert, da das in MediaWiki enthaltene Tool zur Ereugung eines solchen Blocks diese Reihenfolge vorgibt. Innerhalb des Datenobjekts können folgende Angaben gemacht werden.

Bezeichner Typ Format Beschreibung
description optional InterfaceText bzw. null Erschient als kurzer Einleitungstext in der Suchmaske der Vorlagenauswahl. Der Text sollte
  • wirklich kurz gehalten werden, da das Interface hier wenig platz bietet
  • eindeutig die Funktion der Vorlage benennen
  • keine unnötigen Formulierungen enthalten
params pflicht Objekt Enthält die eigentlihce Parameterinformationen, dabei wird für jeden Parameter ein einzelnes Unter-Objekt definiert.

Für Vorlagen, die keine Parameter beinhalten, ist die Übergabe eines leeren Objekts {} korrekt und wird erwartet.

format optional String Angabe des erwartenden Quelltext-Layouts für die Einbindung. Folgende Angaben sind üblich:
  • inline
  • block
  • Eigenes Format, durch Kennzeichnung von Zeilenumbrüchen als \n und Leerzeichen. Beispiel \n{{_\n |_=_\n}} → Vor und nach der Einbundung ein Zeilenumbruch, jeder Parameter steht in einer eigenen Zeile und ist um ein Zeichen eingerückt.
maps optional Objekt Zuätzliches Opjekt um Parameter für weitere Schnittstellen zuordnen zu können. Gegenwärtig gibt es dafür ausschließlich den Anwendungfall durch die Extension Citoid, die für Belegvorlagen genutzt wird.
paramOrder optional Objekt Ordungkriterum fpr die Anzeige der Parameter innerhalb des VisualEditors, falls diese von der Reihenfolge der gelisteten Parameter in params abweichen soll. Die Anzeige in der Dokumentation bleibt davon unberührt, dort erfolgt die Anzeige weiterhin nach der Reihenfolge, in der die Parameter innerhalb des Objekts params angegeben wurden.
sets optional Array Array von Objekten, die zu Sets - einer Art Unterformaular zusammengehören. Dies wird gegenwärtig nicht unterstützt.[i]

JSON-Format allgemein[Bearbeiten | Quelltext bearbeiten]

Der allgemeine Aufbau des JSON-Objekts folgt der Standardfefinition von JSON selbst.

  • Das Objekt selbst beginnt steht in einer Geschweiften Klammer {}.
  • Jede Zuweisung besteht aus der Komponente, gefolgt von einem Doppelpunkt : und dem Wert (Value).
    • Die Namenszuweisung selbst wird als Zeichenketter (String) formatiert, also in gerade, doppelte Anführungszeichen "..." eingschlossen.
    • Die Zuweisung eines weiteren Objekts als Wert ist möglich, dieses ist dann wiederum in geschweiften Klammern einzuschließen.
    • Jede Zeichenkette muss zwingend mit Anführungszeichen umschlossen sein.
  • Wenn nach der Zuweisung des Werts eine neu Zuweisung folgt, muss ein Komma , gesetzt werden. Auf die letzte Zuweisung innerhalbd es objekts folgt kein weiteres Komma.
  • Leerzeichen, Tabulatoren und Abstände außerhalb von Zeichenketten werden ignoriert und können zur lesbaren Einrückung genutzt werden.
  • Anführungszeichen, die innerhalb einer Zeichenkette auftreten sollen, müssen mit \" escaped werden. Sonderzeichen, besonders für die Typografie,können genutzt werden, erfordern aber teilweise ebenfalls einen vorangestellten Backskash, oder sollten durch Ihre Unicode-Darstellung ersetzt werden.

InterfaceText[Bearbeiten | Quelltext bearbeiten]

Als InterfaceText wird ein Text verstanden, der im Benutzerinterface des VisualEditors angezeigt wird, wenn eine Vorlage eingefügt wird.

Es sind zwei Datentypen möglich

  1. Eine Einfache Zeichenkette, die den Beschreibungstext enthält.
  2. Ein Objekt mit zwei Bestandteilen, wovon der erste jeweils ein Sprachcode ist, der abhängig von der Interface-Sprache angezeigt wird.
    • Gängige Sprachcodes sind z. B. de, de-ch oder en.
    • Für die Darstellung in der Dokumentation wird aufgrund des Caches jedoch nur die Standardsprache von Wikonia-Wiki dargestellt, dies kann nur umgangen werden, indem eine komplett eigenständige Unterseite für die Dokumentation in der jeweiligen Sprache angelegt wird, was wir gegenwärtig nicht vorsehen.

Generell ist die Übersetzung von Wikonia gegenwärtig (Stand 2025) nicht vorgesehen.

Info:Wie im gesamten JSON-Objekt ist kein Wikitext möglich und HTML-Formatierungen werden nicht unterstützt.

Parameter-Objekt[Bearbeiten | Quelltext bearbeiten]

Die Parameter-Definition ist die Hauptaufgabe des gesamten TemplateData-Elements. Für den Bezeichner params wir ein witeres Objekt erwartet, das für jeden definierten Parameter (oder zumindest jeden der Dokumentiert werden soll) einen eigenen Eintrag aufweist. 

{ "description": "Heer steht die Beschreibung der Vorlage",
  "params": { "Parameter1": { ... Details zu Parameter 1 ... },
              "Parameter1": { ... Details zu PArameter 2 ... },
              ...
            }
}

Pro Parameter können eine Vielzahl an möglichen Optionen definiert werden. Die im Beispiel gezeigten Bezeichner Parameter1 und Parameter2 entsprchen dabei den technischen PArameternamen,w ie sie in der Vorlagenprogrammierung vorkomme. Innerhalb der darauf folgenden geschweiften Klammern stehen die restlichen Angaben zum Parameter, welche die eigentliche Steuerung der Eingabemaske für den Visualeditor übernehmen. Alle Angaben sind optional, es ist aber sinnvoll, die Definition des Parameters so spezifisch wie möglich anzubieten, damit Nutzenden der Zugang zur Vorlagennutzung so leicht wie mööglich fällt.

Detailangaben für Parameter (optional)
Bezeichnung Komponente Typ Beschreibung
Bezeichnung label InterfaceText
null 		Kennzeichnung bzw. Name des Parameters im Dialogfenster. Solltemöglichst verständlich,aussagekräftig und kurz gehalten werden.
Beschreibung description InterfaceText
null 		Eine erweiterte Beschreibung, zum Beispiel welchen Einfluss er in der Vorlage hat, oder was genau als Eingabe erwartet wird.
Typ type string

Der „Datentyp“ des Parameterwertes für Gültigkeitsprüfungen und Design des Dialogfensters. Möglich sind:

  • "unknown" (Nicht definiert) – (Vorgabe)
  • "boolean" Boolwert (Wahrheitswert), also 0 für falsch und 1 für wahr.
  • "content" (Inhalt) – Wikitext, d. h. formatierter Text, Links, Bilder, usw.
  • "date" (Datum) – Datum/Zeit nach ISO 8601
  • "line" (Zeile) – Einzeiliger Text für ein einfaches Eingabefeld, wie ein Label oder ein Name.
  • "number" (Zahl) – Zahlenwert, mit dem mathematische Funktionen innerhalb der Vorlage realsisiert werden können.
  • "string" (Zeichenfolge) – beliebige Zeichenkette.
  • "url" (Zeichenfolge) – URL/Link zu einem Webobjekt.
  • "wiki-file-name" (Datei) – Name einer Datei im Wiki, ohne Präfix wie Datei:, File:; muss noch nicht existieren. [ii]
  • "wiki-page-name" (Seite) – Name einer Wiki-Seite; muss noch nicht existieren[ii]
  • "wiki-template-name" (Seite) – Name einer Vorlage; muss noch nicht existieren.[ii]
  • "wiki-user-name" (Benutzer) – Name eines Benutzers; muss noch nicht existieren.[ii]
  • "unbalanced-wikitext" (Unausgeglichener Wikitext) – Wikitext-Fragment, das nicht wohlgeformte Einzelbestandteile enthält
Erforderlich required boolean Erfordernis-Parameter
  • Mit dem Wert true wird festgelegt, dass der Parameter von der Vorlage als Pflichtwert behandelt wird.
Vorgeschlagen suggested boolean Erfordernis-Parameter
  • Mit dem Wert true, wird der optionale Parameter für die Eingabemaske als vorgeschlagen definiert und erscheint immer in der Feldauswahl.
Veraltet deprecated boolean
string 		Erfordernis-Parameter
  • Durch den Wert true, wird festgelegt, dass der Wert veraltet ist.
  • Stattdessen kann eine Zeichenkette, mit kurzer Begründung angegeben werden, die dann als Beschreibung in der Wertetabelle auftaucht, zum Beispiel als Warnung oder Hinweis, wie mit dem Parameter umzugehen ist, falls er noch vorhanden ist.
Beispiel example InterfaceText
null 		Mögliche Beispielwerte für den Parameter.
Standard default InterfaceText
null 		Standardwert, der in der Vorlagenprogrmmierung als Standardwert vorgeesehen wurde. Dieser Hinweis ist rein optisch und hat keine Auswirlungen auf die Vorlage selbst.
Werteliste suggestedvalues Array als [ , ] Durch das Array wird in der Benutzeroberfläche mögliche Auswahloptionen anzeigt, das Feld hat dann die Eigenschaften einer Dropdown-Box für den Anwender.
Autowert autovalue string Standardwert, mit dem der bislang leere Vorlagenparameterwert 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.
Aliasse aliases Array

Liste möglicher Alias-Bezeichnungen, die in der Vorlagenprogrammierung selbst festgelegt wurden. MEist um den Benutzerkomfort zu erhöhen, oder veraltete Parameter weiter zu untersützen.

– inherits string Technischer Name eines Paramter von dem die SPezifikation geerbt wird. Durch das setzen einzelner Werte, kann der vererbte Wert überschrieben werden.

Erfordernis-Paramer[Bearbeiten | Quelltext bearbeiten]

Mit der Kennzeichnung der Erfordernis eines Parameterwerts, lässt sich festlegen, wie die Oberfläche de VisualEditor den Parameter behandelt und die Darstellung der Dokumentationstabelle aussieht.

Grundsätzlich bestehen hierfür vier Varianten:

Variante und Farbkennzeichnung Bool-Wert
erforderlich required
vorgeschlagen suggested
optional kein Wert (Standard)
veraltet deprecated
Achtung:Die Angaben required und deprecated schließen sich gegenseitig aus und erzeugen eine Fehlermeldung in der Dokumentationstabelle.


Beispiel[Bearbeiten | Quelltext bearbeiten]

Ein einfaches Beispiel für eine imaginäre Vorlage mit dem Namen Wetter, die es so in diesem Wiki nicht gibt.

JSON-Objekt[Bearbeiten | Quelltext bearbeiten]

{
	"description": "Unechte Beispielvorlage, um die Definition eines JSON-Objekt zu imitieren. (Das ist übrigens die Bschreibung) ",
	"params": {
		"aktuell": {
			"aliases": [
				"1"
			],
			"label": "Aktuelles Wetter",
			"type": "line",
			"required": true
		},
		"temp": {
			"label": "Temperatur",
			"description": "Aktuelle Temperatur",
			"example": "21",
			"type": "number",
			"suggested": true
		},
		"symbol": {
			"aliases": [
				"icon"
			],
			"description": "Datei für die grafische Unterstützung",
			"example": "sonnig.svg",
			"type": "wiki-file-name",
			"suggested": true,
			"autovalue": "wetterfrosch.png"
		},
		"max": {
			"label": "Höchsttemperatur",
            "description" : "in Grad Celsuis",
			"type": "number"
		},
		"min": {
			"label": "Tiefsttemperatur",
			"inherits": "max"
		},
		"regen": {
			"label": "Regenwahrscheinlichkeit",
			"deprecated": true
		},
		"morgen": {
			"label": "Vorhersage",
			"type": "content",
			"deprecated": true,
			"suggested": true
		}
	},
	"format": "inline"
}
}

Dokumentationstabelle[Bearbeiten | Quelltext bearbeiten]

Das oben gezeigte BEispiel erzeugt mit der Verwendung der Vorlage {{TemplateData}} die folgende Ausgabe.

TemplateData
Unechte Beispielvorlage, um die Definition eines JSON-Objekt zu imitieren. (Das ist übrigens die Bschreibung)
ParameterBeschreibungTypStatus
Aktuelles Wetteraktuell
1		Einzeiliger Texterforderlich
Temperaturtemp
Aktuelle Temperatur
Beispiel
21
Zahlenwertvorgeschlagen
symbolsymbol
icon
Datei für die grafische Unterstützung
Beispiel
sonnig.svg
Autowert
wetterfrosch.png
Dateivorgeschlagen
Höchsttemperaturmax
in Grad Celsuis
Zahlenwertoptional
Tiefsttemperaturmin
in Grad Celsuis
Zahlenwertoptional
RegenwahrscheinlichkeitregenUnbekanntveraltet
VorhersagemorgenWikitextveraltet

Format: inline

Suggesting deprecated morgen

Erklärung zum Beispiel[Bearbeiten | Quelltext bearbeiten]

In der Tabelle ist folgendes zu beobachten:

Aliasse
Die Parameter aktuell und symbol haben jeweils ein definiertes Alias. Der Parameter aktuell wurde durch einen nummerierten (unbenannten) Alias ergänzt, für das Symbol existier noch der Zusatzname Icon.
Erforderlichkeiten
Es gibt nur einen Pflichtparameter aktuell (oder sein Alias 1.
Die Parameter temp und symbol sind optional, aber vorgeschlagen.
regen ist komplett optional.
Der Parameter regen wurde als veraltet gekennzeichnet, ebenso morgen, hier wurde jedoch durch die Zusatzangabe suggested eine Fehlermeldung ausgelöst, erkennbar am roten Rahmen und unterhalb der Tabelle.
Datentypen
Es sind verschiedene Datentypen im Einsatz, während der Parameter regen undefiniert ist.
Vererbung

Der Parameter min erbt einen Teil seiner Eigenschaften von max, mit Ausnahme seiner Bezeichnung (label)

Format
Als Format für die Einbindung in die Seite wurde hier inline, als in einer Zeile festgelegt, dies steht direkt unterhalb der Tabelle, noch vor der Fehlermeldung.


Werkzeuge und Wartung[Bearbeiten | Quelltext bearbeiten]

Vorlagen, die TemplateData zur Verfügung stellen, finden sich

Die Verwendung von TemplateData in dieser Wikipedia wird protokolliert unter:

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

Code valideren[Bearbeiten | Quelltext bearbeiten]

Neben installierter Entwicklungssoftware (IDE) gibt es noch eine Reihe an Online Tools, die JSON auf syntaktische Korrektheit prüfen können, exemplarisch sind hier ein paar Empfehlungen gelistet:

Weitere Informationen[Bearbeiten | Quelltext bearbeiten]

Weitere Informationen[Bearbeiten | Quelltext bearbeiten]

Anmerkungen

  1. ↑ Die Definition von Sets schadet der Vorlage nicht, da sie aber keine praktische Umsetzung im VisualEditor hat, ist ihr nutzen fraglich und wird demnach nicht empfohlen und wird auf dieser Hilfeseite nicht erläutert.
  2. ↑ a b c d Technisch gesehen handelt es sich bei Datei, Seite, Vorlage und Benutzer um das gleiche Feld. Die genaue Angabe bestimmt nur, welche Suchmaske im Interface angezeigt wird.

Webseiten und Quellen

  1. ↑ (25. Jun. 2025): JSON erklärt: Definition, Funktionsweise und Use Cases.. IONOS Digital Guide  (abgerufen am 29. Nov. 2025)

[[1]]

Abgerufen von „https://wiki.wikonia.net/index.php?title=Hilfe:Vorlagen/TemplateData/JSON&oldid=3096“