Hilfe:Vorlagen/Einbindungssyntax

Diese Hilfeseite erläutert für Fortgeschrittene die Details, wie eine Seiteneinbindung durch die Wiki-Software interpretiert wird.

Sie ist in {{…}} eingeschlossen.

Bezeichner der einzubindenden Seite

Die einzubindende Seite wird als erstes Element angegeben.

• Nur Zeichen wie Buchstaben, Ziffern und allerlei Sonderzeichen sind möglich; nicht aber eigenständige Syntaxkonstrukte wie Vorlageneinbindungen, Verlinkungen oder Parserfunktionen.
• Der Bezeichner muss somit als Seitenname im eigenen Wiki interpretierbar sein.
• Ein (führendes) # schließt das jedoch aus.
• Sofern kein Namensraum identifiziert wird, also ein Doppelpunkt den (auch leeren) vorangestellten Namensraum-Bezeichner abgrenzt, wird der Vorlagen-Namensraum angenommen.
• Falls es eine Parserfunktion gleichen Namens gibt, muss ggf. Vorlage: explizit vorangestellt werden; andernfalls wird die Parserfunktion ausgewertet.
  • Dabei würde der Bezeichner einer Parserfunktion alternativ durch einen Doppelpunkt beendet.
  • Vorlagen mit dem gleichen Namen wie eine Parserfunktion sollten jedoch strikt vermieden werden.
• Ist die identifizierte Seite nicht vorhanden, erscheint ein Rotlink, und eine Wartungskategorie wird ggf. ausgelöst.
• Falls es sich um eine Weiterleitung handelt, wird das Weiterleitungsziel eingebunden.

Aufteilung in Parameter

Folgt auf den Bezeichner der Vorlage ein Pipe-Symbol |, so werden bis zum Ende }} an den Pipes lauter einzelne Parameter abgetrennt.

• Dabei werden nur die offenen Pipes herangezogen.
• Das sind solche, die nicht innerhalb eines anderen Syntaxkonstrukts wie etwa [[…]] oder {{…}} auftreten.
• Die Pipe-Symbole müssen also unmittelbar im Wikitext mit derselben Sichtbarkeit wie {{ und }} geschrieben werden.

Zuweisung benannter Parameter

Falls innerhalb eines Parameters ein offenes Gleichheitszeichen gefunden werden kann, wird der Text links des ersten Gleichheitszeichens als Bezeichner interpretiert.

• Offene Gleichheitszeichen sind solche, die nicht innerhalb eines anderen Syntaxkonstrukts wie etwa [[…]] oder {{…}} auftreten. Diese sind bereits vorher ausgewertet worden.
• Das gilt nur, wenn dieser Bezeichner keine eigenständigen Syntaxkonstrukte wie etwa Vorlageneinbindungen, Verlinkungen, Parserfunktionen oder MediaWiki-Elemente enthält.
• Leerzeichen und gewisse andere Whitespace-Zeichen vor und nach dem Bezeichner werden dann ignoriert.
• Der resultierende Bezeichner muss mindestens ein Zeichen enthalten und wird dann zum Parameternamen.
• Konnte kein gültiger Bezeichner identifiziert werden, handelt es sich um einen „unbenannten Parameter“.
• Die Anzahl von Leerzeichen innerhalb von Parameternamen ist signifikant. Es ist strikt darauf zu achten, dass dann immer nur genau ein Leerzeichen in Programmierung und Einbindung verwendet wird, falls dies vorgesehen ist.
• Der Wert rechts vom Gleichheitszeichen gilt dann als Parameterwert.
• Leerzeichen, Zeilenumbruch und gewisse andere Whitespace-Zeichen vor und nach dem Parameterwert werden dann ignoriert; dies aber nur bei benanntem Parameter.
• Die Zuweisung darf auch den leeren Wert erhalten, was gültig gezählt wird.
  • Bei Definition eines Vorgabewertes Name|Vorgabe würde dann der leere Wert verwendet und nicht die Vorgabe.

Jeder Parametername darf nur einmal verwendet werden.

• Bei einer wiederholten Zuweisung gilt nur die letzte gefundene Zuweisung.
• Der Fall wird jedoch in einer Wartungskategorie protokolliert.
• Weil auch für Menschen unklar ist, ob die letzte oder eine frühere Zuweisung beabsichtigt ist, sollten diese Dubletten bereinigt werden; auch für spätere Änderung des Wertes an einer Stelle, ohne zu bemerken, dass später dieser Wert wieder überschrieben wird.

Zuweisung unbenannter Parameter

Sofern kein benannter Parameter identifiziert wurde, handelt es sich um eine unbenannte Zuweisung.

• Sie werden auch als „Positionsparameter“ oder „stellungsgebundene Parameter“ bezeichnet.
• Als Parametername werden intern die fortlaufenden Nummern der unbenannten Zuweisungen generiert.
• Der Parameterwert ist der gesamte Parameterwert, einschließlich Leerzeichen, Zeilenumbruch und ggf. anderer Whitespace-Zeichen vor und nach dem Parameterwert.
  • Darin unterscheiden sich unbenannte und benannte Parameter.
  • In der Programmierung muss dann ggf. die „Trimmung“ des Wertes nachgeholt werden.

Es sollten immer zuerst alle unbenannten Zuweisungen und anschließend die benannten Zuweisungen geschrieben werden, um Probleme zu vermeiden.

• Gutes Vorlagendesign verwendet unbenannte Parameter in erster Linie für Pflichtparameter, maximal einen optionalen Parameter zum Schluss, um Verwirrung zu vermeiden (außer, wenn alle Parameter eine austauschbar gleiche Bedeutung haben).

Numerische Parameternamen

Zuweisungen wie 1= oder 5= können unbenannte Zuweisungen ersetzen.

• Danach sollten aber keine unbenannten Zuweisungen mehr auftreten, oder rückwirkend bereits erfolgte Zuweisungen umdefiniert werden, weil sonst Absicht und Interpretation durch die Software nicht mehr nachvollziehbar sind.

Komplexe Parameterwerte

Vor der Übermittlung an die Programmierung der Vorlage werden alle Parameterwerte vollständig ausgewertet, also alle enthaltenen Vorlageneinbindungen oder Parserfunktionen sind durch ihr Resultat ersetzt worden.

Reihenfolge der Parameter

Es sollten immer zuerst alle unbenannten Zuweisungen und anschließend die benannten Zuweisungen geschrieben werden.

• Die Reihenfolge der benannten Parameter ist für die Software bedeutungslos.
• Für Menschen ist hingegen eine gewisse Logik in der Reihenfolge sinnvoll, um Zuweisungen an der erwarteten Stelle vorzufinden und sie nicht dupliziert anzugeben und vorhandene Werte wahrzunehmen. Diese Abfolge ergibt sich aus der Vorlagendokumentation; diese wiederum sollte einer inhaltlichen Logik folgen.

Zuweisung leerer Parameterwerte

Grundsätzlich macht es für die Wiki-Software einen Unterschied, ob ein leerer Wert durch || bzw. durch |x=| vereinbart wurde, oder ob ein Parameter völlig weggelassen wird.

• Gute Programmierungen sollten jedoch beides gleich behandeln.
• Im VisualEditor lassen sich die beiden Situationen nicht unterscheiden.
• Es ist unzulässig, einen Bedeutungsunterschied zu erwarten.

Syntax-Zeichen im Parameterwert

Vor allem die Zeichen | = und }} sind ein Problem, wenn sie im Parameterwert sichtbar sein sollen. Es gibt verschiedene Möglichkeiten, um die Interpretation in der Einbindungssyntax zu umgehen:

Pipe-Symbol |

HTML-Entity |

Parserfunktion {{!}}

Gleichheitszeichen =

Nur bei unbenannten Zuweisungen relevant.

HTML-Entity =

Parserfunktion {{=}}

Numerischen Parameternamen verwenden, wodurch es zu einer benannten Zuweisung wird.

Klammern }}

HTML-Entity } maskiert eine Klammer }

Siehe auch: Probleme bei der Benutzung von Vorlagen