Hilfe:Vorlagen/Programmierung

Diese Hilfeseite gibt technische Hinweise, wie eine neue Vorlage und vergleichbar erstellt oder eine bestehende verbessert werden kann.

Vorausgesetzt ist, dass ihr Zweck sinnvoll und sie verständlich benannt worden ist.

Zur Anwendung (Einbindung) in die darstellende Seite siehe ausführlich: Einbindungssyntax

Seitenstruktur

Quelltext

Eine einfache Vorlagenseite hat die folgende Syntax:

<onlyinclude>Wirksame Programmierung</onlyinclude>

[[Kategorie:Vorlage:.........]]

Der Einschluss in onlyinclude stellt sicher, dass nicht unbeabsichtigt Leerzeichen oder Zeilenumbrüche das Ergebnis der Einbindung umgeben.
Außerhalb dieses Bereichs stehen organisatorische Angaben, die nicht eingebunden werden sollen, etwa die Kategorisierung der Vorlage selbst oder ihre Dokumentation.

Unterseiten

Die Stammseite kann Unterseiten haben. Dabei ist zu unterscheiden zwischen

ebenfalls allgemein einbindbaren Vorlagen, den Untervorlagen, und
begleitenden organisatorischen Seiten, die nicht oder nur einmalig zur Einbindung vorgesehen sind.

Zu den letzteren gehören die standardisierten Unterseiten-Namen

/Doku – Dokumentation
/Test – Beispiele für Einbindungen zur Demonstration der Wirkung und Überprüfung der planmäßigen Funktion
/Wartung – Organisation von Wartungsaufgaben
/styles und /styles.css – TemplateStyles
/Editnotice
/Preload

Sie sind mit entsprechenden Untervorlagen der Vorlage:Dokumentation zu kennzeichnen.

Untervorlagen

Eine Untervorlage ist dazu vorgesehen, inhaltlich wirksam in andere Seiten eingebunden zu werden. Dabei gibt es zwei Fälle:

nur intern, durch die eigentliche Vorlage, etwa für mehrfach auftretende Hilfsaufgaben oder um Pseudo-Variablen zu generieren (dafür wird traditionell der Name /core gewählt);
allgemein nutzbar, wobei eine Familie mit der Basis-Vorlage gebildet wird.

Ein Beispiel für letzteres wäre Vorlage:NavFrame und dazu Vorlage:NavFrame/Ende.

Ein anderes wäre eine Gruppe von drei zusammengehörenden Vorlagen zur Generierung und konsistenten Formatierung einer Tabelle:

Vorlage:XYZ-Tabelle – ergibt eine einzelne Tabellenzeile; häufigste Einbindung
Vorlage:XYZ-Tabelle/Kopf – Kopfzeilen mit den Spaltenüberschriften; einmalige Einbindung pro Tabelle
Vorlage:XYZ-Tabelle/Fuß – Fußbereich mit Legende usw.; einmalige Einbindung pro Tabelle

Es ist damit offensichtlich, dass diese drei Vorlagen unmittelbar zusammengehören.

Namensraum

Jede inhaltliche Seite kann technisch in andere eingebunden werden. Es ist nicht erforderlich, dass ihr Name mit Vorlage: beginnt.

Es gibt drei Gründe, warum einbindbare Seiten im Vorlagen-Namensraum angelegt werden:

Im Artikel-Namensraum sollen nur eigenständige enzyklopädische Artikel auffindbar sein und das Publikum nicht unversehens in die Eingeweide geraten.
Die Vorlage kann projektweit, in vielen Namensräumen sinnvoll eingesetzt werden.
Bei der Einbindung {{Beispielvorlage}} muss (und soll) der Vorlage:Beispielvorlage nicht Vorlage: vorangestellt werden.

Soll hingegen eine Einbindung nur innerhalb eines bestimmten Portals, einer Redaktion oder eines Wikiprojekts genutzt werden, dann soll diese Seite dort als Unterseite angelegt und gepflegt werden, hat hingegen nichts im allgemeinen Vorlagen-Namensraum der Community zu suchen.

Insbesondere Einbindungen ausschließlich für den Benutzernamensraum sollen auch nur von dort bedient werden. Es gibt den virtuellen „Benutzer:Vorlage“, der derartige Angebote verwaltet.

Ein anderer typischer Fall sind bei Projektseiten die Unterseiten /Intro – sie werden immer nur von ihrer Oberseite eingebunden und ermöglichen es, die sich selten ändernde Einführung aus der Archivierung und den Seitenversionen herauszuhalten, sie ggf. auch gesondert zu schützen und Veränderungen an der Einleitung mit einer unabhängigen Versionsgeschichte auszustatten.

Alle Ausführungen zur Programmierung einer Vorlage, etwa zu Parametern, gelten für alle anderen inhaltlichen Seiten anderer Namensräume sinngemäß genauso.

Weiterleitung

Bei Einbindung der Weiterleitung einer Vorlage auf eine aktuelle Programmierung werden alle Parameter genauso zugewiesen als ob die wirksame Vorlage eingebunden wäre.

Die Programmierung hat keinerlei Möglichkeit herauszufinden, ob sie direkt oder über eine Weiterleitung eingebunden wurde.

Parameter

Eine wohlüberlegte Abbildung des zu lösenden Problems auf verständlich benannte Parameter und deren intuitive Werte ist für eine gute Vorlage von entscheidender Bedeutung.

Namen von Parametern

Als Namen von Parametern kommen theoretisch alle Zeichen in Frage, mit folgenden Ausnahmen:

Pipe-Symbol | oder Gleichheitszeichen =.
Mehrfache geschweifte Klammern sowie auswertbare Syntax-Elemente wie etwa Einbindungen anderer Seiten.
Führende oder schließende Leerzeichen oder Zeilenumbrüche.
HTML-Kommentare.

Unbeschadet der theoretischen Möglichkeiten soll der Name selbsterklärend sein, zumindest den Sinn nahelegen und Verwechslungen mit anderen Parametern vermeiden.

Einzelne Wörter können schlicht die Bedeutung angeben.
Mehrteilige oder zusammengesetzte Begriffe werden besser zu einem einzigen „Wort“ zusammengezogen und mittels CamelCasing gegliedert und die Komponenten enträtselbar gekürzt. Dadurch entsteht eine unverwechselbare Zeichenkette, nach der in Quelltexten eindeutig gesucht werden kann und die nicht zu lang wird.
Zu Groß- oder Kleinschreibung gibt es keine Regeln oder Forderungen.
- Nur Kleinschreibung wird bevorzugt, um den Namen mit möglichst wenig Tastendrücken schreiben zu können.
- Normale Groß- und Kleinschreibung ergibt leicht verständliche Begriffe.
- Nur Großschreibung hebt sich bei Einbindung und in der Programmierung besser ab.
Sinnvolle und in vielen anderen Vorlagen mit gleicher Bedeutung übliche Namen sollten übernommen werden; womöglich auf solche Standardnamen migriert werden.

Syntax

Der bei der Einbindung zugewiesene Wert ist innerhalb der Programmierung durch Einschluss des Namens in dreifache geschweifte Klammern {{{}}} verfügbar.

Diese dreifachen Klammern haben Vorrang vor den doppelten der Seiteneinbindung.
Die unbenannten Parameter erhalten ihre laufende Nummer 1 2 3 … als „Name“.
Wenn dem Namen ein Pipe-Symbol | nachgestellt wird, dann kann zwischen | und }}} ein Vorgabewert angegeben werden für den Fall, dass dieser Parameter bei der Einbindung überhaupt nicht erwähnt wurde.

Beispiele:

{{{Hugo}}} – ein Parameter, dem bei der Einbindung über |Hugo=Wert ein Wert zugewiesen werden kann.
- Wurde kein |Hugo= vereinbart, ergibt sich die Zeichenkette {{{Hugo}}} selbst.
{{{5|}}} – ein Parameter, dem über |5=Wert oder nach fünf Pipe-Symbolen ein Wert zugewiesen werden kann.
- Wurde das nicht vereinbart, ergibt sich eine leere Zeichenkette.
{{{Multi|Single}}} – ein Parameter, dem über |Multi= ein Wert zugewiesen werden kann. Es ergeben sich folgende drei Auswertungen:
- Keine Erwähnung liefert Single
- |Multi= liefert eine leere Zeichenkette
- |Multi=42 liefert 42

Das letztgenannte Verhalten ist nicht intuitiv und soll nicht für die Nutzung nach außen verwendet werden. Vorgabewerte sind anders sicherzustellen. Wird eine Vorlageneinbindung mittels VisualEditor bearbeitet, dann gibt es keine Kontrolle über den entstehenden Quelltext und die Fälle können auch nicht unterschieden oder auch nur verstanden werden.

Bei der Vorlagenerstellung ist darauf zu achten, dass Konstrukte vermieden werden, die bei leeren Parameterwerten zu Darstellungsfehlern führen können. Dies betrifft insbesondere die Kursiv- und Fettschrift der Parameterinhalte.

ungeeignete Syntax: ''{{{Parameter|}}}'' oder '''{{{Parameter|}}}'''; bei leeren Parametern wird die Wikisyntax zu '''' oder ''''''; dies erzeugt dann unerwünschte Fett- und Fettkursivschrift im nachfolgenden Text.

Probleme können auch auftreten, wenn Inlinetags um Parameter gelegt werden, in deren Inhalten Aufzählungen, Textblöcke oder Zeilenumbrüche vorkommen können.

ungeeignete Syntax: {{{Parameter|}}} oder {{{Parameter|}}}; hier sollte stattdessen div verwendet werden, falls der Parameterwert ein Block-Element sein kann oder soll.

Benannt oder unbenannt?

Ziel ist es, den Quelltext lesen zu können, und ohne Rückgriff auf die Vorlagendokumentation eine ungefähre Vorstellung davon zu bekommen, welche Wirkung die Vorlage dieses Namens haben wird und was die einzelnen Parameterwerte bedeuten. Auch ohne jahrelang in einem Spezialgebiet tätig zu sein.

Benannte Parameterwerte vermindern auch den Aufwand zur Trimmung.

Gleichheitszeichen in Parameterwerten machen für die Verwendung Probleme, stören aber bei benannte Parametern nicht, was ein weiterer Grund ist, sie zu benennen.

Falls gleichzeitig unbenannte und benannte Parameter möglich sind, dann sollen zuerst alle unbenannten in Einbindung und Dokumentation auftreten, erst danach die benannten.

„Unbenannt“ wäre für Pflichtparameter geeignet, bei denen die Bedeutung klar ist und die eine innere Logik für ihre Reihenfolge mitbringen. Bei unterschiedlicher Bedeutung (anders als in Vorlage:max) darf nur der allerletzte unbenannte Parameter optional sein, wenn überhaupt. Eine Situation, nach der die stellungsgebundenen optionalen Parameter durch leere || übersprungen werden sollen, um weiter hinten doch noch eine Wertzuweisung zu erreichen, ist eine sehr fehleranfällige und deshalb zu eliminierende Kinderkrankheit aus der Anfängerzeit.

Unbenannte Parameter sind nur scheinbar „einfacher“ als benannte, ziehen tatsächlich aber vielfältige Folgeprobleme sowohl bei der Verwendung wie auch in der Programmierung wie auch in der langfristigen Pflege nach sich.

Unbenannte Parameter

In der Frühzeit der Wikipedia waren in den allerersten Vorlagen unbenannte Parameter sehr beliebt. Damals gab es noch keine Einzeldokumentationen zu Vorlagen, damit auch keine Kopiervorlagen, über die sich mit wenigen Mausklicks ein Schema für die Quelltext-Einbindung zum Ausfüllen einfügen ließ; geschweige denn Werkzeuge, die Formulare für die Dateneingabe anboten. Man versuchte, mit möglichst wenig Tastenbetätigungen für den Namen der Vorlage und die Parameterzuweisungen ein Ergebnis zu erzielen. Es gab auch nur wenige Dutzend Vorlagen mit wenigen Parametern, deren Bedeutung auswendig gelernt wurde. Heute, mit über 130.000 einbindbaren Vorlagen und vielfältigen Parametern ist das ein Alptraum, und das Vorgehen ist nicht intuitiv und deshalb sehr fehleranfällig.

Unbenannte Parameter, so sie denn überhaupt noch eingesetzt werden, stehen am Anfang der Parameterliste und sind primär für Pflichtparameter zu verwenden; also die Schlüsselinformation, ohne die die Vorlage überhaupt nicht nutzbar wäre oder die ansonsten die Kernbedeutung trägt. Das ist meist nur für einen, höchstens zwei unbenannte Parameter möglich. Sobald die Parameter optional werden und nur gelegentlich angegeben werden, ist es äußerst verwirrend, sich zur siebten Option durchzählen zu müssen und entsprechend viele Pipe-Symbole als leere Zuweisungen zwischenzuschalten.

Nicht gemeint ist hierbei, wenn beliebig viele Parameter alle die gleiche Bedeutung haben, etwa in Vorlage:min oder Vorlage:Anker.

Bei der Angabe ohne den Parameternamen („Ziffer gleich“) kommt es zu Problemen für die Anwender, wenn der Parameterinhalt ein Gleichheitszeichen enthält. Der Wert würde ignoriert werden, weil alles bis zum ersten Gleichheitszeichen als Parametername interpretiert werden muss. Bei benannten Parametern kann dies nie auftreten. Aus diesem Grund werden projektweite Basisvorlagen, bei denen der Parameter formatierte und komplexe Inhalte enthalten kann, auf benannte Parameter wie Inhalt= oder Text= migriert.

Falls ein unbenannter Parameter bei der Einbindung nur zwischen Pipe-Symbolen als | Wert | angegeben wird, bleiben die umgebenden Leerzeichen dem Wert erhalten; er wird nicht „getrimmt“.

Benannte Parameter

Deren Wert wird immer „getrimmt“.

Ebenfalls getrimmt wird ein eigentlich unbenannter Parameter, falls bei der Einbindung die Form |2=Wert verwendet wird statt einfach nur der Wert als | Wert |.

Zur Namensgebung siehe oben.

Aliasnamen

Wenn ein und derselbe Wert von unterschiedlich identifizierten Parametern bestimmt werden kann, so werden diese „Alias“ genannt.

Aliasnamen sind in der deutschsprachigen Wikipedia sehr ungern gesehen, und sie werden langfristig möglichst vermieden und eliminiert. In zwei Fällen kann ein Alias sinnvoll sein:

Wenn ein bisher im Bestand vorhandener Name durch einen anderen ersetzt werden soll, etwa weil dieser verständlicher ist und auch mit anderen Vorlagen für die gleiche Bedeutung harmonisiert. Der bisherige Name wird dann zum Alias; die Maßnahme ist temporär und müsste irgendwann abgeschlossen sein, auch wenn sich das über Jahre hinziehen könnte. Neue Einbindungen sollen nur noch den neuen Namen verwenden.
Wenn ein in anderen (fremdsprachigen) Wikis verwendeter Name zunächst unterstützt werden soll, damit der kopierte Quelltext bei einer Übersetzung erst einmal funktioniert. Dieser Alias wird dann zwar unbefristet verstanden, soll aber bei Gelegenheit in den wirklichen Namen überführt werden.

Zu jedem Wert soll es nur einen Haupt-Namen geben; alle anderen Varianten sind ein Alias. Auswertungen des gesamten Bestandes und Suche nach Wertzuweisungen sollten erfolgreich sein, wenn nach dem eigentlichen Namen analysiert wird. Jede Variante verkompliziert das enorm.

Bei längerfristig parallel unterhaltenen Namen müsste eigentlich zu jedem Alias eine Abfrage auf Doppelzuweisung programmiert werden, die eine Fehlersituation auslöst, falls beiden Varianten ein aktueller Wert zugewiesen wurde, und womöglich gar unterschiedliche. Wenn ohnehin beabsichtigt ist, den Alias baldmöglichst zu eliminieren, kann das entfallen.

Absolut unerwünscht ist es, bei einer neuen Programmierung einen bunten Strauß an Aliasnamen zu vereinbaren. Dahinter steckt die Idee, bei der Anwendung könne man aufs Geratewohl irgendeine Schreibweise verwenden, und die würde dann auch zum Erfolg führen. Das hat sich jedoch als nicht zielführend erwiesen:

Es lassen sich überhaupt nicht alle vorstellbaren Schreibweisen abdecken; einige sind nicht programmtechnisch unterlegt und bleiben deshalb wirkungslos.
Es müsste für jede Kombination eine Überprüfung programmiert werden, ob nicht womöglich zwei verschiedenen Schreibweisen Werte zugewiesen wurden, gar unterschiedlich.
Die Auswertung und Suche in den Einbindungen wird massiv erschwert.
Die Programmierung der Vorlage wird erheblich verkompliziert.
Skripte und Bots, die etwas umstellen sollen, bekommen deutliche Probleme.
Alle, die nachfolgend mit der Vorlage und ihren Einbindungen zu tun haben, müssen auswendig lernen, welche Schreibweisen zulässig sind und welche nicht. Das Manöver spart also einmalig bei der Einbindung einige Sekunden, die es braucht, um den korrekten Namen herauszufinden, und bindet in den folgenden Jahrzehnten bei jeder Einbindung erneut bei allen anderen viele Ressourcen, um mit der Situation umzugehen.
Allein die robuste Ermittlung des Vorgabewerts wird bei einem Aliasnamen mühsam, bei mehreren Aliasnamen und wenn mehrfach erforderlich wie etwa in #if-Konstruktionen hier oder dort irgendwann unbeherrschbar.

Wenn ein Aliasname als solcher dokumentiert wird, dann müssen alle Varianten in der Programmierung absolut gleichartig behandelt werden, auch wenn die erstgenannte Schreibung bevorzugt wird.

Sobald der Name einen Unterschied macht, etwa durch zusätzliche Auslösung einer Wartungskategorie, ist er auch separat als „veraltet“ zu dokumentieren.

Vorgabewert

Eine robuste Bereitstellung eines Vorgabewerts (default) erfolgt mittels #if:

{{#if: {{{Dings|}}} | {{{Dings}}} | Vorgabewert}}

Anders als die Basis-Syntax suggeriert, hat dieser Ausdruck den Vorgabewert immer dann, wenn der Parameter Dings nicht oder mit leerer Zuweisung angegeben wurde.

Viele Programmierungen aus den allerersten Jahren hatten sich darauf verlassen, dass niemals jemand eine leere Zuweisung tippen würde, weil es damals noch keine Einzel-Dokumentationen mit Kopiervorlagen gab.

Es ist unzulässig, einen Bedeutungsunterschied zu erwarten zwischen einem überhaupt nicht oder einem mit leerer Zuweisung angegebenen Parameter.

Im VisualEditor lassen sich die beiden Situationen nicht unterscheiden.

Leere Angabe

Wenn einmal absichtlich der Vorgabewert völlig unterdrückt werden soll, so ist vor allem bei Text-Werten ein - (U+002D) üblich, um diese Situation zu kennzeichen, weil - fast nie ein sinnvoller Wert für einen Text ist (außer mal bei Vorlage:Zeichen oder Vorlage:Taste).

Damit wird deutlich gemacht, dass hier bewusst weder Wertzuweisung noch Vorgabewert wirken sollen, während ein leerer oder fehlender Parameterwert keine besonderen Absichten verrät. Realisiert werden kann dies mittels #ifeq:

{{#ifeq: {{{Dings}}} | - | | Präsentation von {{{Dings}}}}}

Falls bei der Einbindung |Dings=- angegeben wurde, ist das Ergebnis eine leere Zeichenkette; andernfalls erfolgt eine Verarbeitung des Wertes, ggf. auch mit einem Vorgabewert.

Einbindung anderer Elemente im Parameterwert

Pipe-Symbole | und Gleichheitszeichen = innerhalb von Verlinkungen, Medieneinbindungen, Seiten-(Vorlagen-)einbindungen oder Parserfunktionen sowie MediaWiki-Tags werden vor Auswertung der Parameterliste von den umgebenden Syntaxelementen konsumiert.
Wenn ein Pipe-Symbol Bestandteil des Werts sein soll, muss es mittels der Funktion {{!}} maskiert werden. Diese wird bei der Übergabe einmalig ausgewertet und liefert dann das Pipe-Symbol.
HTML-Kommentare werden vor der Weitergabe eliminiert.
Andere Seiteneinbindungen (Vorlagen) und Parserfunktionen werden vor der Weitergabe ausgewertet und deren Ergebnis zum Teil des Parameterwerts.

Ergebnis der Einbindung

Zeichen	Entity
`;`	`;`
`:`	`:`
`*`	`*`
`#`	`#`
Leerzeichen	` `
Zeilenumbruch	` `
Pipe \|	`{{!}}`

Das Ergebnis einer Seiteneinbindung („Expansion“) ist schlicht der Wikitext, der sich ergibt, nachdem alle Ausdrücke ausgewertet wurden und alle aktuellen Parameterwerte ihre Platzhalter ersetzt haben.

Das Ergebnis einer Seiteneinbindung ist nicht „getrimmt“, es enthält also alle führenden oder schließenden Leerzeichen oder Zeilenumbrüche.
- Damit hier keine unerwünschten Effekte entstehen, ist wie beim Quelltext angegeben der beabsichtigte Bereich in onlyinclude einzuschließen. Dadurch werden dazwischenliegende Zeichen besser erkennbar und verschiedene Fehler vermieden.
Dem Ergebnis einer Seiteneinbindung wird aber ein Zeilenumbruch vorangestellt, falls dieses netto mit ; : * # {| beginnt.
- Das zielte darauf ab, damit Aufzählungen und Listen und Tabellen zu kennzeichnen. Andernfalls wäre dies wegen der Trimmung nicht möglich.
- Soll ein sichtbares derartiges Zeichen erscheinen, muss der Beginn des Ergebnisses zuvor in ein entsprechendes Entitiy gewandelt werden (siehe Tabelle rechts).
- Ein bereits getrimmter Wert kann mittels nowiki1@TemplUtl gemäß der nebenstehenden Tabelle abgesichert werden.
- Soll das Zeichen tatsächlich syntaktisch wirksam sein, etwa das # als Fragmentbezeichner in einer URL oder ein CSS-Farbwert, dann ist die Konstruktion nur dieses Anhängsels grundsätzlich nicht möglich. Es muss ggf. eine weitere Komponente der URL als Parameter übergeben und immer als Beginn des Ergebnisses geliefert werden; andernfalls kann keine URL zustandekommen, oder es müsste nachträglich der Zeilenumbruch aus der zusammengestellten URL eliminiert werden.

Das Ergebnis der Seiteneinbindung mit einer bestimmten Signatur an Parameterzuweisungen wird im Cache abgelegt. Bei zukünftigen Einbindungen mit dieser Parameterkonstellation wird dieser Wikitext komplett aus dem Speicher abgerufen und ersetzt die Einbindung, egal auf welcher Seite sie auftritt – es sei denn, es wären seitenabhängige Funktionen aktiviert, wodurch ggf. Nummer des Namensraums oder Seitentitel zum Teil der Signatur werden müssen. Nach Veränderung der Programmierung werden hingegen alle hinterlegten Resultate ungültig und eliminiert, ebenso die gespeicherten Wikitexte der Seiten, die darauf aufbauten.

Nützliche Wikisyntax

Verschiedene in sonstigen Texten ungewöhnliche bis unerwünschte Wikisyntax ist wichtig für eine Programmierung:

Hilfe:Parserfunktionen
Kategorie:Vorlage:Funktion zu Zeichenketten, Datum, Zahlenangaben und vielen Detailfragen.

Für jede komplexere Vorlage wird die Nutzung der Kontrollstruktur-Funktionen unverzichtbar sein.

Außerdem gibt es:

Module TemplUtl und TemplatePar speziell für die Vorlagenprogrammierung;
Bibliotheksmodule mit unterstützenden Funktionen für spezielle Aufgaben;
Umsetzung mittels Lua.

Fehlersituationen

Durch falsche oder ganz fehlende Parameterwerte, aber auch durch andere Situationen wie eine Einbindung im falschen Namensraum, fehlende erwartete andere (Vorlagen-)seiten oder fehlende Substitution kann es zu aktuellen Problemen dieser Einbindung kommen.

Modernisierte Programmierungen analysieren ihre Probleme und machen sich bemerkbar. Das ist jedoch recht aufwändig und aus Kapazitätsgründen nur bei projektweit besonders häufig eingebundenen Vorlagen nachzurüsten.

Fehler anzeigen

An den meisten Stellen der Darstellung kann ein Element mit einer Fehlermeldung angezeigt werden.

Wenn das Ergebnis der Vorlage kein dargestellter Inhalt ist, sondern ein Syntaxkonstrukt, das innerhalb der Syntax eines anderen Elements auftritt, etwa weil CSS-Code oder ein Teil einer URL generiert wird, ist keine Fehlermeldung möglich.
Die Fehlermeldung sollte in direkter Syntax programmiert werden, also ohne Nutzung irgendwelcher externer Service-Vorlagen, damit die Auswirkungen auf die umgebende Syntax offensichtlich und nachvollzeihbar sind.
Eine Fehlermeldung sollte die class="error" deklarieren. Damit wird sie für MediaWiki und Hilfswerkzeuge erkennbar. Außerdem soll dies eine Darstellung in roter und etwas vergrößerter Schrift bewirken.
Fehlermeldungen lassen sich so gestalten, dass sie dem normalen Publikum und weniger erfahrenen Gruppen verborgen bleiben, und nur erfahrenere Benutzerkonten mit Sichterrechten oder Angehörige einer Redaktion oder eines Wartungsteams sie wahrnehmen können. Nur diese können und sollen die Ursache zielgerichtet beheben, während Reparaturversuche durch Unkundige womöglich mehr schaden. Wer einen Artikel nur lesen möchte, würde ohnehin bloß gestört werden.
Eine Fehlermeldung kann auf dargestellte Seiten in bestimmten Namensräumen – etwa nur enzyklopädische Artikel oder ohne Benutzer- und Diskussionsseiten – beschränkt werden.

Beispiel:

{{#ifeq: {{#expr: {{{Jahr|0}}} > {{LOKALES_JAHR}} }} | 1 |
<span class="error editoronly" style="display:none">Fehler in [[Vorlage:Dings]] – Jahr {{{Jahr}}} liegt in der Zukunft.</span>{{#ifeq: {{NAMESPACENUMBER}} | 0 | [[Kategorie:Wikipedia:Vorlagenfehler/Vorlage:Dings]]}} }}

Wenn der Inhalt des Parameters Jahr größer ist als LOKALES_JAHR, wird eine Fehlermeldung generiert (in …).
Die Fehlermeldung erhält die Klasse error und wird dadurch in roter Schrift auch für Software markiert.
Die Fehlermeldung wird aber unsichtbar gemacht: display:none
Die Fehlermeldung wird aber sichtbar gemacht, falls das aktuelle Benutzerkonto Sichterrechte hat: editoronly
Wenn die momentane Seite im Artikel-Namensraum liegt (NAMESPACENUMBER), dann wird eine Wartungskategorie ausgelöst.
Die Analyse ist noch nicht narrensicher; auf einer übergeordneten Ebene müsste zuvor noch abgesichert werden, dass Jahr ein numerischer Wert ist, weil der numerische Vergleich > in #expr ansonsten selbst zum Problem wird.

Fehler überwachen

Die Auslösung einer Wartungskategorie ist die sicherste und effizienteste Möglichkeit, um die korrekte Verwendung von Vorlagen zu überwachen.

Kategorie:Wikipedia:Vorlagenfehler ist die Oberkategorie hierfür.
Die Auslösung einer Wartungskategorie wird angemeldeten Benutzerkonten in der Seitendarstellung sowie in der Analyse der Quelltextbearbeitung angezeigt, falls sie diese Option aktiviert haben. Damit wird darauf aufmerksam gemacht, selbst wenn keine Fehlermeldung zu sehen ist oder dieser Abschnitt der Seite nicht durchgelesen wurde.
In der Beschreibung einer Wartungskategorie können Hinweise zu auslösenden Situationen, zur Fehlerbeseitigung, zu verursachenden Vorlagen gegeben werden.
Es lässt sich überwachen, ob eine Wartungskategorie zurzeit leer ist oder problematische Fälle enthält, und daraus Meldungen in beliebigen Seiten (etwa Benutzer- oder Projektseiten) in grün oder rot darstellen.
In einer Oberkategorie lässt sich überwachen, welche Vorlagen des eigenen Interessengebiets momentan ein Problem melden, wie etwa hier.

In den frühen Jahren wurden Verlinkungen auf nicht existierende Seiten generiert, und diese Seiten wurden dann daraufhin ausgewertet, welche anderen Seiten damit verlinkt wären.

Das bietet jedoch keinen der Vorteile der Wartungskategorien.
In den ersten Jahren wurde allerdings propagiert, dass Kategorien ausschließlich zur thematischen Erschließung enzyklopädischer Artikel benutzt werden dürften.
In der Kategorie:Vorlage:nur Wartung sind Zusammenstellungen teils auch nach dieser Methode erfasst.

Unter bestimmten Bedingungen, wenn das Problem innerhalb nicht dargestellter Syntaxkonstrukte auftritt, könnte das Auslösen der Einbindung einer bestimmten nicht existierenden Seite allerdings der einzige Weg sein, um eine Fehlersituation zu kommunizieren.

Bedingte Einbindung

Mit diesen drei Tags lässt sich die Einbindung steuern:

<noinclude>…</noinclude>: In der Quellseite wird alles angezeigt, der Text zwischen den Tags wird aber nicht in die einbindende Seite übernommen.; Damit können Vorgabewerte für die Präsentation als Vorlagenseite selbst die fehlenden Einbindungsparameter simulieren.; Wichtig auch bei Anträgen zum Löschen.
<onlyinclude>…</onlyinclude>: In der Quellseite wird alles angezeigt, in der einbindenden Seite aber nur der eingeschlossene Text darin und sonst nichts.; Alle anderen Bereiche werden für die Einbindung ignoriert.; Es ist der sicherste Weg, genau den beabsichtigten Teil einer Vorlagenprogrammierung einzubinden, nicht aber irrtümlich noch Leerzeichen oder gar Zeilenumbrüche anzuhängen.; Die Quellseite wird außerhalb dieses Bereichs kategorisiert, die Zielseite wird aber dadurch nicht mitkategorisiert.
<includeonly>…</includeonly>: Der Text darin wird nur in der einbindenden Seite angezeigt, aber nicht in der Quellseite.; Damit kann man zum Beispiel die einbindende Seite kategorisieren, die Quellseite kommt aber nicht in diese Kategorie.; Dadurch werden in Vorlagen Darstellungen der Vorlagenseite selbst ausgeschlossen, die nur bei Einbindung mittels Pflichtparametern sinnvoll sind, ansonsten aber Fehlermeldungen und Syntaxbruchstücke zeigen würden.

Expansion

Die Auflösung aller Einbindungen sowie ggf. die Auswertung aller elementaren Parserfunktionen nennt sich „Expansion“.

Anschließend ist im Wikitext nur noch einige Basis-Syntax vorhanden, zur Kursiv- und Fettschreibung, für Verlinkungen sowie Verweise auf komplexe Syntaxstrukturen.

Substitution

Eine Substitution aller eingebundener Seiten ist möglich. Jedoch sind die meisten Vorlagen nicht dafür vorbereitet und würden unübersichtliche Mengen unbrauchbarer Syntax zurücklassen. Alle Konstrukte müssen einzeln für eine geplante Substitution vorbereitet werden, und dies auch erprobt sein, bevor eine Vorlage zur Substitution freigegeben werden kann.

Leerzeichen: Werte trimmen

Insbesondere bei unbenannten Parametern,^[1] gelegentlich auch bei anderen Konstrukten wie {{{A|}}} {{{B|}}} {{{C|}}} oder bestimmten Resultaten von Parserfunktionen könnten Leerzeichen, Zeilenumbrüche (allgemein: „Whitespace“) vor oder nach dem Wert die Funktionalität oder Darstellung stören. Die Entfernung solcher Zeichen wird als „trimmen“ bezeichnet.

Vor allem bei Konstruktion einer URL sind Leerzeichen problematisch. Sie würden bewirken, dass die URL an dieser Stelle abbricht.^[2]

In den frühen Jahren der Wikipedia wurden die Quelltexte händisch und in einem Stück mit wenigen unbenannten Parametern getippt: {{Beispielvorlage|42|4662}}. Sie fangen oft nicht das heutzutage verbreitete Layout ab, bei denen zur besseren Verteilung auf die Quelltextzeilen gern Leerzeichen vor oder um Pipe-Symbole | eingefügt werden, oder gar die Einbindung auf mehrere Zeilen verteilt wird.

Zeitgemäße Vorlagen müssen so programmiert sein, dass sie sich sowohl bei Leerzeichen oder Zeilenumbrüchen wie auch bei leeren Parameterwerten so verhalten wie intuitiv erwartet – dass dies schlicht ignoriert wird.

Die effizienteste Methode zum Trimmen ist das Konstrukt {{#if:trim|{{{1|}}}}} – es liefert immer den Wert von {{{1|}}}, da trim immer „wahr“ ist. Weil der Parameter {{{1|}}} aber innerhalb einer Parserfunktion verwendet wird, ist der Wert derjenige von {{{1|}}} ohne führende und schließende Leerzeichen. Das Schlüsselwort trim zeigt der Nachwelt den Zweck dieser auf den ersten Blick unsinnigen Konstruktion an.

Jeglicher Versuch der Trimmung löst allerdings bei einem Aufzählungszeichen ;:*# zu Beginn des Wertes einen vorangestellten Zeilenumbruch aus; siehe Ergebnis.

Der Aufwand beim Umgang mit ungetrimmten Werten ist neben der unmittelbaren Nachvollziehbarkeit ein wesentlicher Grund, warum statt unbenannter Parameter besser benannte zu verwenden sind.

Alle normalen Versuche zur Trimmung, sowohl bei benannten Parametern wie auch mittels einer Parserfunktion, reagieren immer nur auf „ASCII-Whitespace“ (Leerzeichen U+0020, Tabulator U+0008, Zeilenumbruch U+0010). Die MediaWiki-Software behandelt „Unicode-Whitespace“, beginnend mit einem geschützten Leerzeichen aller Breiten, „nullbreiten“ Zeichen, „bidi“, die ebenfalls unsichtbar sind oder wie ein Leerzeichen wirken, als regulären Text.

Beim Zusammensetzen von Texten aus Wörtern können Leerzeichen erwünscht sein; durch   lassen sie sich vor unbeabsichtigter Entfernung schützen.

Beispiel: Tabellen

Das nachstehende Codebeispiel erläutert am Beispiel einer fiktiven Infobox, wie die Elemente der Vorlagensyntax zusammenwirken, um abhängig vom entsprechenden Parameter der Einbindung eine Zeile der Infobox zu generieren.

}}{{#if: {{{Geschwindigkeit|}}} | <nowiki />
   {{!}}-
   !style="text-align:left"{{!}} Geschwindigkeit
   {{!}} {{{Geschwindigkeit}}} km/h
}}{{#if: {{{Passagiere|}}} |

{{#if: … }} – Abfrage, ob bei der Einbindung eine Zuweisung |Geschwindigkeit= auf einen konkreten Wert erfolgte.
- Falls ja, wird der nachfolgende Bereich wirksam.
- Falls nein, ist dieser ganze Bereich nicht existent.
- Die Einrückung des dazwischenliegenden Bereichs dient der Verdeutlichung und kann im produktiven Einsatz genauso vorgenommen werden.
- #if: ist eine Wenn-Dann-Verzweigung.
{{{Geschwindigkeit|}}} – der Wert, der bei |Geschwindigkeit= zugewiesen wurde.
- Falls dieser Parametername überhaupt nicht vorkam, bewirkt in |}}} das Pipe-Symbol vor den schließenden Klammern, dass der Wert „leer“ ist.
- Falls eine leere Zuweisung erfolgte, ist der Bereich {{{Geschwindigkeit| zugewiesen worden aber leer.
- Falls eine nicht-leere Zuweisung erfolgte, ist der Wert von {{{Geschwindigkeit|}}} eben dieser Wert und nicht leer.
{{#if: {{{Geschwindigkeit|}}} | – Wenn Geschwindigkeit nicht leer ist, wird nach diesem Pipe-Symbol weiter eingebunden; falls leer, so geht es nach }} weiter.
<nowiki /> – dies bewirkt, dass der anschließende Zeilenumbruch erhalten bleibt.
- Andernfalls würde der Inhalt des if-Bereichs getrimmt werden, wodurch die Tabellensyntax nicht erkannt würde, die am Zeilenanfang stehen muss.
{{!}}- – wird zu |- expandiert.
- Ein Pipe-Symbol würde auf die if-Verzweigung wirken, und den Sonst-Pfad der Verzweigung kennzeichnen.
- Mittels {{!}} wird das Pipe-Symbol vor der if-Struktur versteckt. Nach Expansion ist es aber ein normales | und für die Tabellensyntax wirksam.
- Hier wird auch die Tabellensyntax für die Tabellenzeile nicht generiert, wenn kein Wert zugewiesen würde. Eine etwas lässigere Programmierung könnte lauter Tabellenzeilen ohne Zellen schaffen, was ebenfalls nicht dargestellt würde, aber bei einer Expansion zunächst etwas seltsame Syntax liefert.
!style="text-align:left"{{!}} Geschwindigkeit – die linke Spalte der Infobox.
- Über ! deklariert als Zeilen-Überschrift.
- Mit style="text-align:left" wird die linksbündige Ausrichtung der Überschrift-Zelle festgelegt.
- {{!}} – wird wieder zu | expandiert, wie vor.
- Geschwindigkeit ist der sichtbare Text.
{{!}} {{{Geschwindigkeit}}} km/h – die rechte Spalte der Infobox.
- {{!}} – wird wieder zu | expandiert, wie vor.
- {{{Geschwindigkeit}}} ist der Parameterwert, von dem wir bereits wissen, dass er nicht leer angegeben wurde.
- km/h ist einfacher Text, der dargestellt wird.
}} – schließt die Abfrage zu Geschwindigkeit.
}}{{#if: – beginnt direkt, ohne eingestreute Zeichen, die Abfrage nach dem nächsten Parameter.
{{#if: {{{Passagiere|}}} | – gleiche Konstruktion von vorne; jetzt für die Anzahl der Passagiere.

Falls bei der Einbindung |Geschwindigkeit=200 zugewiesen wurde, expandiert der Bereich wie folgt:

   |-
   !style="text-align:left"| Geschwindigkeit
   | 200 km/h

Testen

Bei der Quelltextbearbeitung von Vorlagen (und Modulen) gibt es am Ende des Bearbeitungsformulars ein weiteres Textfeld, in das ein Seitenname eingegeben werden kann.

Diese Seite lässt sich dann in der Vorschau so anzeigen, als ob die momentane Vorlagenprogrammierung bereits wirksam ist.
Damit lassen sich insbesondere die Testseiten für Vorlagen oder deren Verwendungsbeispiele gegen eine veränderte Programmierung prüfen (bevor die Änderung gespeichert würde).

Spielwiesen

Kurzzeitige Experimente können durch Bearbeiten der Vorlage:Spielwiese ausprobiert werden.

Jede eigene Benutzerseite kann auch zur unbefristeten Erprobung von Vorlagenprogrammierungen angelegt und unter entsprechendem Namen auf anderen Seiten mit Parametern eingebunden werden (allerdings nicht in produktiven Seiten, insbesondere nicht in enzyklopädischen Artikeln).

Wenn die Auswirkungen von Änderungen an Vorlagen mit komplexeren Abhängigkeiten überprüft werden sollen, z. B. an Vorlagen, die wiederum von anderen Vorlagen verwendet werden, bietet sich die Spezial:Vorlagenspielwiese mit dem unter Hilfe:Vorlagenspielwiese beschriebenen Anwendungsfall an.

Vorlagen expandieren

Vorlagen mit Parserfunktionen können auf der Spezialseite Vorlagen expandieren getestet werden.

Dabei wird die Einbindung der Vorlage mit ihren Parametern in das „Eingabefeld“ kopiert:

{{Infobox Orte in Lampukistan

| Name = <!-- Vorgabe: Lemma -->

| Wappen =

| Gründung = 1958

| Einwohner = 2006

}}

Über das Feld „Kontexttitel“ kann optional ein Seitenname übergeben werden, der den seitenabhängigen Kontext (das Lemma) {{PAGENAME}} konfiguriert:

BeispielOrt

Im Beispiel führt dies dazu, dass in der Vorschau oberhalb der Infobox nicht „ExpandTemplates“, sondern „BeispielOrt“ angezeigt wird.

Weitere Informationen finden sich unter mw:Help:ExpandTemplates (englisch).

Dokumentation

Siehe: Hilfe:Vorlagendokumentation zu den Einzelheiten.

Jede nicht-triviale Vorlage soll mit einer Dokumentation ausgestattet werden.

Trivial wäre eine Vorlage ohne Parameter, deren Funktionalität offensichtlich ist.

Bei Navigationsleisten mit schlüssiger Namensgebung würde sich die Funktionalität hinreichend aus ihrem Namen ergeben; dann mag auf eine Dokumentation verzichtet werden.

Kategorisierung

Jede Basis-Vorlage (abgesehen von Unterseiten) ist an mindestens einer Stelle in Kategorie:Vorlage: zu kategorisieren.

Löschen

Beim Einfügen eines SLA oder Löschantrags ist unbedingt darauf zu achten, dass sie in <noinclude> eingeschlossen werden; andernfalls würden sämtliche jetzt oder später einbindenden Seiten ebenfalls entsprechend kategorisiert.

Ein SLA durch das erstellende Benutzerkonto wird üblicherweise diskussionslos umgesetzt, wenn es keine produktiven Einbindungen mehr gibt. Andere SLA müssen geeignet begründet werden, und es sollen keine Einbindungen außer im Rahmen der Vorlagendoku selbst auftreten.

Für einen regulären Löschantrag mit Diskussion ist nicht erforderlich, dass bereits Einbindungen ersetzt werden; dies geschieht ggf. erst nachträglich nach entsprechender LD/LP, und nach Abschluss der Aufräumarbeiten kann das ggf. nochmals über einen SLA vollendet werden.

Grenzen und Lua

Die Vorlagensyntax ist historisch gewachsen und war ursprünglich nur zur Transklusion konstanter Textbausteine vorgesehen gewesen, die noch nicht einmal Parameter hatten. Diese „Programmiersprache“ ist nicht darauf angelegt, komplexe Aufgaben zu lösen, etwa über Schleifen, unbegrenzt viele Parameter oder die Definition lokaler Variablen.

2013 wurde mit Lua eine Möglichkeit bereitgestellt, in einer höheren Programmiersprache alle im Wiki-Kontext möglichen Aufgaben effizient zu lösen. Allerdings bedarf das der Einarbeitung und Erfahrung, um wartungs- und zukunftsfähige Programmierungen bereitzustellen, und es gibt nur wenige andere Projektbeteiligte, die eine solche Programmierung dann pflegen könnten. Sofern möglich, sollte innerhalb der Vorlagensyntax verblieben werden, die zumindest rudimentär durch Tausende in der Wikipedia aktualisiert werden kann.

Das Problem der fehlenden Definitionsmöglichkeit für interne Variablen ist über Untervorlagen lösbar: Ein einmalig vorverarbeiteter und durch komplexe Aktionen generierter Wert wird als Parameter an eine Untervorlage übergeben. In der Programmierung der Untervorlage ist es nunmehr ein einfacher Parametername und kann übersichtlich in Ausdrücken auch mehrfach genutzt werden, ohne jeweils den Wert kompliziert neu bilden zu müssen.

Effizienzfragen können bei der ersten selbst erstellten Vorlage außer Acht gelassen werden. Bei Vorlagen, die in viele Seiten eingebunden werden, oder aber viele kritische Funktionen nutzen, kann eine spätere Optimierung ratsam sein.

Anmerkungen

↑ Benannte Parameterwerte sind per Definition immer getrimmt.
↑ Sollen Leerzeichen wirksame Bestandteile von URL sein, bietet sich urlencode an.

[1] Benannte Parameterwerte sind per Definition immer getrimmt.

[2] Sollen Leerzeichen wirksame Bestandteile von URL sein, bietet sich urlencode an.

[1]

[2]