ÖsterreichWiki:Lua/Modul/TemplateData/de: Unterschied zwischen den Versionen

Aus ÖsterreichWiki
Zur Navigation springen Zur Suche springen
wp>PerfektesChaos
(k)
wp>Wullawoop
(AZ: Die Seite wurde geleert.)
Zeile 1: Zeile 1:
{{LuaModuleDoc}}
<onlyinclude>'''<code>TemplateData</code>''' – Modul mit Hilfsfunktionen für die [[Hilfe:Vorlagendokumentation|Vorlagendokumentation]]; namentlich mittels [[Hilfe:TemplateData|TemplateData]].


Kernstück ist die verbesserte Präsentation auf der Vorlagendokumentationsseite.
== {{Anker|improveMW}} Vorlagendokumentationsseite verbessern – MediaWiki ungenügend ==
Zur Präsentation der Vorlagenbeschreibung im [[Hilfe:VisualEditor|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&nbsp;– und eine zweite, oft gleichen Inhalts, ohne Verlinkungen und als einfacher Text, nur für den VisualEditor.
Dieser Zustand ist unhaltbar.
=== {{Anker|enhancedJSON}} Verbesserte Präsentation ===
Ü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. <section begin="JSONenhanced" />Sie wirken auf die als [[Hilfe:TemplateData/JSON #InterfaceText|InterfaceText]] eingestuften Elemente, sind aber in vollem Umfang nur für <code>description</code>-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''' ([[Uniform Resource Locator|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''' <code>'</code> 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: <code style="white-space: nowrap">&amp;lt; &amp;gt; &amp;amp; &amp;quot; &amp;nbsp;</code> 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 <code>"</code> eingeschlossen; das kollidiert mit der JSON-Syntax. Es ist darauf zu achten, dass <code>'</code> verwendet werden; bei Vorlageneinbindungen kann das ein Problem sein.
<code>&lt;noexport></code> … <code>&lt;/noexport></code>
* Die eingeschlosenen 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 <code>JSON=</code> 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.
* Bei der Sortierung nach Status wird diese Wichtigkeit berücksichtigt und nicht die alphabetische Folge der Schlüsselwörter.
* Jeder Parameter kann als Sprungziel adressiert werden; der Anker lautet <code>templatedata:</code>''Parametername''.
* Fehlende Beschriftungen werden als Fehler herausgehoben.
* Eine Wartungskategorie wird bei Fehlern ausgelöst.
* Wenn keine Parameter vorhanden sind, ist auch das Element <code>params:{}</code> nicht erforderlich.
=== Beseitigung von Nachteilen ===
Zwei Aspekte erwiesen sich 2013–2017 als besonders störend:
# 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|Task=126150}} 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.
# 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.
#* {{Phab|Task=T125333}} / {{Phab|Task=T137443}} / {{Phab|Task=T160254}}  / {{Phab|Task=T52512}}<section end="JSONenhanced" />
#* MediaWiki lässt sich noch nicht einmal mehr zu Stellungnahmen herab.
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.
== Allgemeines Vorgehen ==
* Es wird versucht, das JSON-Objekt (Zeichenkette) als übergebener Vorlagenparameter zu lesen.
* Falls das nicht gelingt, wird der Quelltext der aktuellen und der Dokumentationsseite auf <code>&lt;templatedata></code>-Elemente durchsucht.
* Aus dem JSON-Objekt werden zwei Darstellungen gewonnen:
*# Eine um Markup reduzierte, lokalisierte Version.
*# 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 <code>&lt;templatedata></code>-Element. Dieses wird für den Export wahrgenommen und entspricht den MediaWiki-Vorgaben.
** Wenn die momentane Seite als Dokumentationsseite erkannt wurde, wird das verborgene <code>&lt;templatedata></code> unterdrückt, und diese Seite erscheint deshalb auch nicht eigenständig in [[Special:PagesWithProp/templatedata]].
== {{Anker|Vorlage}} Funktionen für Vorlagen ==
=== Einzelfunktionen ===
; f  {{Anker|f}}
: Verbesserung der TemplateData-Präsentation; Verwendung in [[Vorlage:TemplateData]]
: ''Parameter der umgebenden Vorlageneinbindung (alle optional):''<section begin="templatePar" />
::; 1
::: JSON-Zeichenkette oder <code>&lt;templatedata></code>-Objekt
::; JSON
::: JSON-Zeichenkette
::: (Vorrang vor '''1''')
::: Vorsicht bei der Umwandlung mit Pipe-Symbolen: Pipes müssen als <code><nowiki>{{!}}</nowiki></code> maskiert werden, für doppelte geschweifte schließende Klammern bieten sich HTML-Entities an.
::; TOC
::: <code>1</code> – Inhaltsverzeichnis nach der allgemeinen Zweckbeschreibung einfügen; ggf. vor einer Parameterliste
::: [[Wikipedia:Lua/Modul/TemplateData/TOC|Beispiel]]
::; lazy
::: <code>1</code> – Nur Präsentation, keinen wirksamen Datenblock generieren
::: Für allgemeine methodische Beschreibungen.
::; debug
::: <code>1</code> – Erprobungsmodus<section end="templatePar" />
: ''Parameter des'' <code>#invoke</code> ''zur projektspezifischen Anpassung (alle optional):''
::; cat
::: Titel einer Fehlerkategorie bei ungültigem Parameterwert etc.
::; debug
::: Erprobungsmodus, falls angegeben und ungleich <code>0</code>
::; docpageCreate
::: Schema zur Bildung von Unterseiten-Namen; <code>%s/Doku</code>
::; docpageDetect
::: Muster zur Erkennung von Unterseiten-Namen; <code>/Doku$</code>
::; msgDescMiss
::: Lokalisierung: Beschwerdetext bei fehlender <code>description</code>
: ''Rückgabewert:'' HTML-Code; und/oder Fehlermeldung, ggf. mit <code>class="error"</code>
; failsafe  {{Anker|failsafe}}
: Versionsbezeichnung: <code>{{#invoke:TemplateData|failsafe}}</code>
: Optionaler Zusatzparameter <code>1</code> – Mindestversionsbezeichnung
:: ''Rückgabewert:'' Leer, falls Mindestversionsbezeichnung nicht erfüllt
=== Beispiele (Testseiten) ===
Eine Serie von [[Wikipedia:Lua/Modul/TemplateData/Test|Testseiten]] illustriert praktische Beispiele.</onlyinclude>
== {{Anker|Lua}} Funktionen für Lua-Module ==
Einige Funktionen können auch über <code>require()</code> in andere Module eingebunden werden:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>
; TemplateData.[[#failsafe|failsafe]](atleast)
:# atleast<br />''optional''<br />''nil'' oder Mindestversion
: Rückgabewert: ''string'' oder ''false''
; TemplateData.getPlainJSON(adapt)
: Reduktion der verfeinerten JSON-Informationen auf MediaWiki-JSON
:# adapt<br /> ''string'', mit JSON (verfeinert)
: Rückgabewert: ''string'', mit JSON (MediaWiki)
; TemplateData.test(adapt, arglist)
: Simulation der Vorlagenfunktion
:# adapt<br /> ''table'', <code>#invoke</code>-Parameter
:# arglist<br /> ''table'', Vorlagenparameter
: Rückgabewert: ''string''
== Verwendung ==
* [[Vorlage:TemplateData]]
== Abhängigkeiten ==
* [[Wikipedia:Lua/Modul/Multilingual|Multilingual]]
* [[Wikipedia:Lua/Modul/Text|Text]]
* [[Wikipedia:Lua/Modul/WLink|WLink]]   
== Internationalisierung ==
* Soweit möglich, werden Systemnachrichten benutzt, die auch die MediaWiki-Extension verwendet.
** {{Phab|project=ETDA|file=i18n/de.json}}
* Die sonstigen Anpassungen an das momentane Projekt sind über <code>#invoke</code>-Parameter möglich.
[[Kategorie:Wikipedia:Lua/Modul/Dokumentation|TemplatePar]]

Version vom 24. November 2017, 22:21 Uhr

Abgerufen von „https://oesterreichwiki.org/w/index.php?title=ÖsterreichWiki:Lua/Modul/TemplateData/de&oldid=204517“