Wikipedia

Wikipedia:Lua/Modul/TemplateData/de

< Wikipedia:Lua | Modul | TemplateData
Vorlagenprogrammierung Diskussionen Lua Test Unterseiten
Modul Deutsch English

Modul: Dokumentation

TemplateData – Modul mit Hilfsfunktionen für die Vorlagendokumentation; namentlich mittels TemplateData.

Kernstück ist die verbesserte Präsentation auf der Vorlagendokumentationsseite.

Vorlagendokumentationsseite verbessern – MediaWiki ungenügend

Bearbeiten

Zur Präsentation der Vorlagenbeschreibung im VisualEditor hatte man sich entschieden, dass dort keinerlei Markup oder wirksame Verlinkungen möglich sein solle, um auch alle Tooltips immer einfach darstellen zu können. Das mag so nachvollziehbar sein, wiewohl selbst Tooltips seit langer Zeit Markup enthalten können.

  • In der Konsequenz wurde beschlossen, dass auch die Präsentation auf den Vorlagendokumentationsseiten niemals Markup oder wirksame Verlinkungen enthalten dürfe.
  • Das hatte dann zur Folge, dass auf den Vorlagendokumentationsseiten sehr oft zwei Parameterdokumentationen parallel gepflegt werden mussten: Eine mit Verlinkungen und optisch aufbereiteter Darstellung komplexer Zusammenhänge, auch verlinkter Bezugnahme von Parametern untereinander – und eine zweite, oft gleichen Inhalts, ohne Verlinkungen und als einfacher Text, nur für den VisualEditor.

Dieser Zustand ist unhaltbar.

Verbesserte Präsentation

Bearbeiten

Über die einfache, von MediaWiki unterstützte und im VisualEditor dargestellte Syntax hinaus können für die Vorlagendokumentationsseite die nachstehenden Möglichkeiten in den JSON-Code eingebracht werden. Sie wirken auf die als InterfaceText eingestuften Elemente, sind aber in vollem Umfang nur für description-Felder sinnvoll.

Wikilinks

  • Mit doppelten eckigen Klammern kann ganz normal verlinkt werden.
  • Im VisualEditor ist nur der Linktitel sichtbar, so wie er auch sonst angezeigt wird.

Weblinks (URL)

  • Offene URL werden wie üblich selbsttätig verlinkt; im VisualEditor erscheinen sie als normaler Text.
  • In einfache eckige Klammern eingeschlossene, betitelte Weblinks werden normal auf der Vorlagendokumentationsseite dargestellt; im VisualEditor entfällt die Betitelung und es wird die URL angezeigt, damit die Benutzer sie mit C&P übernehmen und in das Adressfeld des Browsers übertragen können. Anders geht es nicht.

Apostrophe ' für Kursiv- und Fettschrift

  • Können verwendet werden, wirken auf die Dokumentationsseite und fehlen im VisualEditor (Normalschrift).

HTML-Entities

  • Die nachfolgenden Entities können benutzt werden: &lt; &gt; &amp; &quot; &nbsp; sowie alle numerischen.

HTML-Tags

  • HTML-Tags (und die nicht vorab ersetzten MediaWiki-Elemente) werden für den VisualEditor entfernt; ansonsten bleiben sie wirksam.
  • Atttribute werden oft in " eingeschlossen; das kollidiert mit der JSON-Syntax. Es ist darauf zu achten, dass ' verwendet werden; bei Vorlageneinbindungen kann das ein Problem sein.

<noexport> … </noexport>

  • Die eingeschlossenen Bereiche werden nicht zum VisualEditor exportiert.
  • Komplexere Wikisyntax und umfangreiche Erläuterungen können auf die Dokumentationsseite beschränkt werden.
  • Innerhalb eines noexport-Bereichs wird die Zeilenstruktur des Quelltextes beachtet; ansonsten alles als in einer einzigen Zeile stehend aufgefasst, wie es dann auch im VisualEditor dargestellt würde.

Vorlagen

  • Insbesondere wenn der Vorlagenparameter JSON= benutzt wird, können Vorlagen überall in den JSON-Code eingestreut werden; deren expandierte Syntax könnte allerdings mit der JSON-Syntax kollidieren.

Weitere Effekte:

  • Gemäß dem Status (benötigt, vorgeschlagen, optional, veraltet) werden die Zeilen in Hellblau, Weiß, Grau und Blassrot unterlegt (oder anderweitig konfiguriert).
  • Bei der Sortierung nach Status wird diese Wichtigkeit berücksichtigt und nicht die alphabetische Folge der Schlüsselwörter.
  • Zwischenüberschriften können in die Parametertabelle eingefügt werden (mehr).
  • Scrollbare, höhenbegrenzte Parametertabelle möglich (mehr).
  • Dekoration einzelner Parameter möglich (mehr).
  • Jeder Parameter kann als Sprungziel adressiert werden; der Anker lautet templatedata:Parametername.
  • Fehlende Beschriftungen werden als Fehler herausgehoben.
  • Eine Wartungskategorie wird bei Fehlern ausgelöst.
  • Wenn keine Parameter vorhanden sind, ist auch das Element params:{} nicht erforderlich.
  • Globale vielsprachige Dokumentation von zentralem Ort abrufbar und lokal konfigurierbar.

Beseitigung von Nachteilen

Bearbeiten

Zwei Aspekte erwiesen sich 2013–2017 als besonders störend:

  1. Selbst wenn keinerlei Parameter definiert sind, wird grundsätzlich immer ein Tabellenkopf für eine Tabelle ohne Inhalt angezeigt; dies obendrein sortierbar.
    • Eine Reduktion wurde mit phab:T126150 abgelehnt; eine sortierbare Tabelle der Parameter wäre immer notwendig, auch wenn die Tabelle überhaupt keine Zeilen hätte und nur aus der Kopfzeile bestünde.
    • Diese Lächerlichkeit gab 2016 den Anlass zur Entwicklung dieses Moduls.
  2. Auch wenn die Problemstellung es grundsätzlich unmöglich macht, dass Vorgabewerte oder gar AutoValue-Spezifikationen jemals definiert werden können, wird bei jedem einzelnen Parameterwert eine inhaltsfreie sechszeilige Definitionsliste ausgegeben.

Aus den allgemeinen Kommentaren geht hervor, dass MediaWiki lediglich die Präsentation von TemplateData-Spezifikationen im VisualEditor für wichtig hält; dass aber auch irgendjemand die Vorlagen programmieren und pflegen muss und dass jemand die Vorlagenbeschreibung generieren und über die Schlichtfunktionalität im VisualEditor-Formular hinaus handhabbar machen muss, liegt außerhalb des Weltbildes.

  • phab:T125333 wurde schließlich nach zwei Jahren im September 2018 durch ein von der Community zugeliefertes und relativ schlichtes Patch aufgelöst.

Allgemeines Vorgehen

Bearbeiten
  • Es wird versucht, das JSON-Objekt (Zeichenkette) als übergebenen Vorlagenparameter zu lesen.
  • Falls das nicht gelingt, wird der Quelltext der aktuellen und der Dokumentationsseite auf <templatedata>-Elemente durchsucht.
  • Aus dem JSON-Objekt werden zwei Darstellungen gewonnen:
    1. Eine um Markup reduzierte, lokalisierte Version.
    2. Eine HTML-Struktur, grundsätzlich ähnlich der MediaWiki-Darstellung, ggf. mit Tabelle der Parameter.
  • Das Ergebnis der Vorlage ist eine sichtbare Dokumentation mit Markup; dahinter ein verborgenes <templatedata>-Element. Dieses wird für den Export wahrgenommen und entspricht den MediaWiki-Vorgaben.
    • Wenn die momentane Seite als Dokumentationsseite erkannt wurde, wird das verborgene <templatedata> unterdrückt, und diese Seite erscheint deshalb auch nicht eigenständig in Special:PagesWithProp/templatedata.

Syntaxunterschiede

Bearbeiten

In folgenden Punkten unterscheidet sich das übergebene JSON-Modell von der MediaWiki-Spezifikation:

  • Leeres params:{} – nicht erforderlich, bei MediaWiki Pflicht.
  • deprecated – auch mehrspachig möglich, nur Projektsprache wird exportiert; bei MediaWiki nur boolean oder string.
  • format – zusätzliche Schlüsselwörter möglich.
  • style – zusätzliche Dekorationen, nicht exportiert.

Funktionen für Vorlagen

Bearbeiten

Einzelfunktionen

Bearbeiten
f
Verbesserung der TemplateData-Präsentation; Verwendung in Vorlage:TemplateData
Parameter der umgebenden Vorlageneinbindung (alle optional):
1
JSON-Zeichenkette oder <templatedata>-Objekt
JSON
JSON-Zeichenkette
(Vorrang vor 1)
Vorsicht bei der Umwandlung mit Pipe-Symbolen: Pipes müssen als {{!}} maskiert werden, für doppelte geschweifte schließende Klammern bieten sich HTML-Entities an.
TOC
1 – Inhaltsverzeichnis nach der allgemeinen Zweckbeschreibung einfügen; ggf. vor einer Parameterliste
Beispiel
vertical
Höhenbeschränkung der Parameterliste, damit Scrollen erzwingen
Parameterwert ist eine CSS-Längeneinheit, sinnvollerweise in em
Beispiel: vertical=50em
Verwendungsbeispiel
lang
Sprachcode nach ISO 639 usw.
lazy
1 – Nur Präsentation, keinen wirksamen Datenblock generieren
Für allgemeine methodische Beschreibungen.
debug
1 – Erprobungsmodus
source
1 – JSON-Quelltext zur Kontrolle anzeigen
Parameter des #invoke zur projektspezifischen Anpassung (alle optional):
(weitgehend veraltet; siehe Konfiguration)
lang
Sprachcode nach ISO 639 usw.
debug
1 – Erprobungsmodus
failsafe
Versionsmanagement

Die Failsafe-Schnittstelle erlaubt den damit ausgerüsteten Modulen in globaler Verteilung

  • sicherzustellen, dass eine von einer Vorlage oder einem Modul benötigte Funktion in der lokalen Kopie eines Bibliotheksmoduls vorhanden ist, und ggf. auch in einer erforderlichen Mindestversion;
  • die globale Aktualisierung und Verknüpfung von Modulen über Wikidata zu verwalten.

Die Failsafe-Schnittstelle liegt sowohl auf Ebene der Vorlagen wie auch in direktem Lua-Zugriff vor.

Die Funktionen sind im Einzelnen (nicht alle werden bereits überall in vollem Umfang unterstützt):

Parameter
Wert Ergebnis aktuell
nichts
false 		lokale Version »2024-10-15«
Mindest­version Mindestversionsbezeichnung
Datum im ISO-Format

Es wird verglichen, ob das aktuelle Modul diese Version oder später erfüllt.

  • leer, falls Mindestversion nicht erfüllt
  • 2001-01-01 → »2024-10-15«
  • 2099-01-01 → »«
wikidata Versionsbezeichnung der globalen Mutter (d:Q46997995)
  • Versionsbezeichnung auf Wikidata
  • lokal, falls dort keine gefunden
 »2024-10-15«
item ID des Wikidata-Items
  • leer, falls nicht definiert
 »Q46997995«
~ Übereinstimmung der lokalen mit der auf Wikidata registrierten Versionsbezeichnung
  • leer, falls aktuell
  • Versionsbezeichnung auf Wikidata, falls ungleich
 »«
@ Ist die aktuelle (Modul-)Seite richtig mit Wikidata verknüpft?
  • leer, falls mit dem richtigen Item verknüpft
  • Item-ID, falls nicht
Der Rückgabewert ist in der Vorlagenprogrammierung leer und per Lua false; andernfalls die angegebene Zeichenkette.

Beispiele (Testseiten)

Bearbeiten

Eine Serie von Testseiten illustriert praktische Beispiele.

Funktionen für Lua-Module

Bearbeiten

Einige Funktionen können auch über require() in andere Module eingebunden werden: 

local lucky, TemplateData = pcall( require, "Modul:TemplateData" )
if type( TemplateData ) == "table" then
    TemplateData = TemplateData.TemplateData()
else
    -- Fehlerfall; TemplateData enthält Fehlermeldung
    return "<span class='error'>" .. TemplateData .. "</span>"
end
TemplateData.failsafe(atleast)
  1. atleast
    optional
    nil oder Mindestversion oder "wikidata"
Rückgabewert: string oder false
TemplateData.getPlainJSON(adapt)
Reduktion der verfeinerten JSON-Informationen auf MediaWiki-JSON
  1. adapt
    string, mit JSON (verfeinert)
Rückgabewert: string, mit JSON (MediaWiki)
TemplateData.test(adapt, arglist)
Simulation der Vorlagenfunktion
  1. adapt
    table, #invoke-Parameter
  2. arglist
    table, Vorlagenparameter
Rückgabewert: string

Verwendung

Bearbeiten

Abhängigkeiten

Bearbeiten

Konfiguration

Bearbeiten

Ein lokales Modul Modul:TemplateData/config, sofern vorhanden, ermöglicht Anpassungen an das lokale Projekt.

Es wird eine table per mw.loadData erwartet. Die optionalen Komponenten sind:

catProblem
Titel einer Fehlerkategorie bei ungültigem Parameterwert etc.
classMultiColumns
Klasse für mehrspaltige Listen.
column-multiple
classNoNumTOC
Klasse für das Inhaltsverzeichnis; insbesondere um die Nummerierung zu unterdrücken.
nonumtoc
classTable
table mit Klassen für die Parameter-Tabelle.
{ "wikitable" }
cssParams
table mit CSS für die Formatierung einzelner Parameter
cssParWrap
table mit CSS für die Formatierung der gesamten Tabelle
docpageCreate
Schema zur Bildung von Unterseiten-Namen
%s/Doku
docpageDetect
Muster zur Erkennung von Unterseiten-Namen
/Doku$
help*********
Linkziele für kontextsensitive Hilfe zu Details
helpAliases
helpBoolean
helpContent
helpDate
helpDefault
helpFile
helpFormat
Linkziele für Hilfe zum Quelltext-Layout
helpLine
helpNumber
helpPage
helpString
helpTemplate
helpURL
helpUser
msgDescMiss
Lokalisierung: Beschwerdetext bei fehlender description
permit
table mit Spezifikation für die Eigenschaften einzelner Parameter; Komponenten:
boole
table mit Spezifikation für die boolean-Darstellung
Zwei Komponenten true und false – jeweils eine table:
css
table mit CSS für diese Werterklärung
lead
true – Wert 0 bzw. 1 vorangestellt zeigen
false – Wert 0 bzw. 1 nachgestellt zeigen
show
Werterklärung; string oder false zur Unterdrückung
css
table mit Spezifikationen für die Darstellung der Parametertabelle; Komponenten:
tablehead
table mit CSS für den Tabellenkopf
required
table mit CSS für required
suggested
table mit CSS für suggested
optional
table mit CSS für optional
deprecated
table mit CSS für deprecated
tStylesMultiColumns
TemplateStyles-Oberseite für mehrspaltige Listen
"column-multiple"
Vorlage:column-multiple/styles.css
tStylesTOCnum
TemplateStyles-Oberseite für Inhaltsverzeichnis ohne Nummerierung
"TOC nonum"
Vorlage:TOC nonum/styles.css

Internationalisierung

Bearbeiten
  • Soweit möglich, werden Systemnachrichten benutzt, die auch die MediaWiki-Extension verwendet.
  • Die sonstigen Anpassungen an das momentane Projekt sind über die Konfiguration möglich.
Abgerufen von „https://de.wikipedia.org/w/index.php?title=Wikipedia:Lua/Modul/TemplateData/de&oldid=249488746“