Zum Inhalt springen

Hilfe:Vorlagenprogrammierung

Aus Wikonia

Die Vorlagenprogrammierung in einem Wiki bezeichnet das Erstellen und Aktualisieren des Wiki-Quelltextes der als Vorlagen genutzten Inhaltsseiten. Auf dieser Hilfeseite und den zugehörigen Unterseiten erklären wir die Grundlagen der Vorlagenprogrammierung für das Wikonia-Wiki von technischer Seite.

Hinweis:Falls du Informationen zur Nutzung und Einbindung von Vorlagen benötigst, findest du diese auf Hilfe:Vorlagen.

Die Programmierung von Vorlagen erfolgt direkt im Wiki selbst, es gibt keine Möglichkeit, den Vorlagencode extern zu testen, da die angewandte Programmiersprache die Wikisyntax selbst durch Erweiterung der Standardsyntax, durch [[../Parserfunktionen|Parserfunktionen]] und Module.

Hilfebereich bei Wikonia
Hilfebereich bei Wikonia

Hilfebereich

Benutzerkonto

Navigation & Suche

Seitenbearbeitung

Seitenorganisation

Vorlagen & Module

Diskussionen & Anträge

Gadgets

Phorge


Grundlegende Prinzipien[Bearbeiten | Quelltext bearbeiten]

Vorlagen werden über Transklusion in andere Wiki-Seiten eingebunden und dort dann expandiert. Der Hauptunterchied zwischen der normalen Transklusion einer beliebigen Wiki-Seite und der Vorlageneinbindung besteht darin, dass der Vorlagen-Namensraum speziell dafür gemacht ist, eingebunden zu werden und als Standardnamensraum in den Suchmasken auftaucht. Konkret bedeutet dies, dass der Aufruf von {{Vorlegenname}} ohne Angabe eines Namensraumes immer auf den Vorlagennamensraum zeigt, statt wie sonst üblich auf den Artikelnamensraum.

Außerdem wird der VisualEditor, sowie die Erweiterungen für den Wikitexteditor für die Suche im Vorlagen-Dialog nur den Vorlagen-Namensraum durchsuchen. Auch gibt es im nur Vorlagen-Namensraum noch das Tool für die Erstellung von TemplateData, das für die Dokumentation von Vorlagen ein wichtiger Bestandteil ist.

Grundsätzlicher Aufbau der Syntax[Bearbeiten | Quelltext bearbeiten]

Eine Vorlage unterscheidet sich in ihrem grundsätzlichen Aufbau von einer anderen Seite des Wikis erstmal nicht. Der einfachste, denkbare Ansatz einer Vorlage wäre ein einfaches Textfragment reproduzierbar auf vielen Seiten zu Platzieren. Simple Beispiele im Wikonia-Wiki wären alle Inhalte der Kategorie:Typografische Vorlagen, wie die Vorlage {{...}}, die lediglich die korrekte typografische Form der Ellipsis sicherstellt. Ihren gesamten Quellcode nehmen wir an dieser Stelle als Beispiel. 

<includeonly>…</includeonly><noinclude>
{{Dokumentation|subst=soll}}
</noinclude>

Alles wichtige, was die Vorlage selbst angeht passiert bereits innerhalb des Abschnitts <includeonly>…</includeonly>, der mit der Inlcude-Kennzeichnung zur exklusiven Transklusion gekennzeichnet wurde. Alles was a <noinclude> folgt, wird bei der Vorlageneinbindung komplett missachtet und geschieht nur auf de rVorlagenseite selbst. Konkret wird in diesem Fall noch die Standardvorlage {{Dokumentation}} mit einem Parameteraufruf eingebunden um die Dokumentationsseite einzubinden.

Komplexere Vorlagen verfolgen größere Ziele, so sind Infoboxen, viele UI-Elemente wir die Vorlagen {{Hilfebox}}, Navigationsbeusteine, wie die auf dieser Seite stehende {{HilfeNavigation}} zentrlal gesteeuerte Elemente.

Zweck und Struktur[Bearbeiten | Quelltext bearbeiten]

  • Der Hauptzweck einer Vorlage ist Konsistenz. Wenn eine Vorlage innerhalb einer Seite benutzt wird, sieht die Darstellung überall gleich aus.
  • Eine Vorlage dient auch dazu den Pflegeaufwand gering zu halten. Eine Anpassung an einem Navigationselement, weil ein neuer Menüpunkt hinzukommt wird zentral an einer Stelle gepflegt, nicht auf allen 50 Seiten die Vorlage benutzen.
  • Da Vorlagen wiederum selbst Vorlagen beinhalten können, ist es möglich ein Art Pyramide zu bauen, in der eine Designvorlage das Layout einer Box bestimmt, die darauf aufbauende Strukturvorlage gibt die geforderte Struktur vor. Hierauf baut vielleicht noch eine Vorlage auf, die wiederum nur noch die Inhalte korrekt zuweist und so weiter.

Der Vorteil darin besteht nun, dass eine Anpassung des Designs sich durch alle Instanzen fortzieht, und letztendlich auf den Seiten sichtbar wird, ohne die Seiten selbst nochmal anzupassen.

Unterseiten und Untervorlagen[Bearbeiten | Quelltext bearbeiten]

Im Vorlagen-Namensraum sind Unterseiten möglich, diese können sowohl zur Funktionsergänzung, als auch zur Auslagerung bestimmter Inhalte genutzt werden.

Untervorlagen sollten dann erstellt werden, wenn

  • der in der Untervorlage ausgelagerte Code zu umfangreich ist, um in der Hauptvorlage zu verbleiben. Bei umfangreichen Vorlagenstrukturen kann dies die Wartung einzelner Komponenten deutlich vereinfachen, so können z. B. Textinhalte oder komplexere Konditionierungen auf mehrere Untervorlagen aufgeteilt werden.
  • der Code der Untervorlage nur in besonderen Fällen in die Hauptvorlage eingebunden werden muss, so wird ebenfalls ein modularer Aufbau erzielt. Dies entlastet den Parser und die Datenbank, da bei Änderungen an den Untervorlagen in großen Versionsverläufen gespeichert werden müssen.

Letztendlich gilt es hierbei das richtige Maß zwischen Wartbarkeit und Übersicht zu finden.

Mehr dazu:Versionsverläufe wirken kumulativ auf die Serverlast

Gewisse Unterseiten sind technisch oder organisatorisch erforderlich, hierfür haben sich Standards etabliert, die so eingehalten werden sollen, damit die Vorlagenstrukturen nachvollziehbar bleiben. Auch arbeiten einige Vorlagen damit, die Inhalte auf den benannten Unterseiten automatisch aufzufinden und einzubinden.

Benennungsstandards für Unterseiten
/Doku Dokumentation der Vorlage
/TemplateData TemplateData, falls nicht in der Dokumentation enthalten.
/Demo Weitere Demonstration, zum Beispiel für diverse Anwendungsfälle
/styles.css CSS-Definitionen als TemplateStyles

Parameter[Bearbeiten | Quelltext bearbeiten]

Um eine Vorlage so zu gestalten, dass sie die Inhalte beim Aufruf übermittelt bekommt, wird mit Parametern gearbeitet. Diese werden der Vorlage beim Aufruf im Stil von {{Vorlage|name=Bernd}} übergeben. In der Vorlage selbst wird der Parameter durch drei schweifte Klammern genutzt. Zum Beispiel würde der Vorlagencode 

<includeonly>
Hallo {{{name}}}! Schön, dass du da bist.
</includeonly>

den Namen, der übergeben wurde an der passenden Stelle in den Text einfügen.

Benannte Parameter[Bearbeiten | Quelltext bearbeiten]

Benannte Parameter verwenden einen eindeutigen Namen zur Identifizierung des übergebenen Wertes. Sie werden im Wikitext in der Form {{Vorlagenname|Name=Wert}} übergeben und im Vorlagencode über {{{Name}}} abgerufen.

Vorteile
  1. Klarheit und Lesbarkeit: Der Zweck des übergebenen Wertes ist im Aufruf sofort ersichtlich, was die Wartbarkeit und das Verständnis des Quelltextes stark verbessert.
  2. Flexibilität der Reihenfolge: Die Reihenfolge der Parameter im Vorlagenaufruf spielt keine Rolle. Sie können beliebig vertauscht werden, ohne dass die Funktionalität beeinträchtigt wird.
  3. Selbstdokumentation: Sie dienen als eine Form der Selbstdokumentation der Vorlage.
  4. Nachvollziehbarkeit: Auch in der späteren Einbindung der Vorlage, zum Beispiel in einem Artikel lässt sich mit benannten Parametern schneller herausfinden, welcher Wert geändert oder aktualisiert werden muss.
Nachteile
  1. Mehraufwand beim Aufruf: Die Eingabe ist länger, da der Name und das Gleichheitszeichen (Name=) jedes Mal eingegeben werden müssen.
  2. Tippfehleranfälligkeit: Tippfehler im Namen führen dazu, dass der Parameterwert nicht erkannt wird.

Unbenannte Parameter[Bearbeiten | Quelltext bearbeiten]

Unbenannte Parameter oder auch nummerierte Paramerter genannt, nutzen die Position des Wertes im Vorlagenaufruf als Identifikator. Sie werden in der Form {{Vorlagenname|Wert1|Wert2|...}}übergeben und im Vorlagencode über {{{1}}}, {{{2}}}, etc. abgerufen.

Vorteile
  1. Kompaktheit und Schnelligkeit: Die Eingabe ist schnell und kurz, da nur die Werte (durch einen senkrechten Strich getrennt) eingegeben werden. Ideal für einfache Vorlagen mit wenigen Parametern.
  2. Einfache Zuweisung: Die numerische Zuweisung ist direkt und leicht zu verstehen.
Nachteile
  1. Streng gebundene Reihenfolge: Die Reihenfolge im Aufruf ist zwingend einzuhalten. Wenn ein Parameter übersprungen werden soll, muss ein leerer Wert übergeben werden (z. B. {|Wert1| |Wert3…), um die Position des nächsten Parameters nicht zu verschieben.
  2. Geringe Lesbarkeit: Der Zweck eines Wertes ist im Aufruf oft nicht erkennbar ({{Vorlagenname|Berlin|DE}}), was die Lesbarkeit für andere Benutzer erschwert.
  3. Wartungskomplexität: Das Hinzufügen oder Ändern der Reihenfolge von Parametern bricht alle bestehenden Aufrufe der Vorlage.

Alias[Bearbeiten | Quelltext bearbeiten]

Aliasing ist eine Technik, bei der eine Vorlage prüft, ob ein Parameter unter mehreren möglichen Namen oder Positionen übergeben wurde. Dies wird hauptsächlich genutzt, um Benutzernamen oder alte/neue Parameter zu unterstützen.

Die Syntax dafür ist, die Aliase durch senkrechte Striche zu trennen. Der Parser prüft dann von links nach rechts: Zielwert = Erstes gefundenes Element

Beispiel:Es soll möglich sein, dass entweder ID=..., Code=... oder den unbenannten Parameter 1=... verwendet werden kann.
{{{ID|{{{Code|{{{1}}}}}}}}}}
Vorteile
  1. Rückwärtskompatibilität: Ermöglicht es, alte Parameternamen zu entfernen, ohne bestehende Vorlagenaufrufe sofort zu brechen.
  2. Benutzerfreundlichkeit: Bietet dem Benutzer Flexibilität, da er den ihm bekannten Namen verwenden kann (z.B. Farbe vs. colour).
  3. Fehlertoleranz: Fängt einfache Tippfehler ab, indem z. B. der unbenannte Parameter als Fallback dient.
Nachteile
  1. Komplexität des Vorlagencodes: Die Klammer-Tiefe nimmt dramatisch zu, da jeder Alias eine zusätzliche Verschachtelungsebene ({{{...|...}}}) erfordert.
  2. Wartungsaufwand: Wenn ein Alias geändert werden muss, muss die gesamte Kette im Vorlagencode angepasst werden.
  3. Leistungsbeeinträchtigung: Bei sehr langen Ketten steigt die Parser-Laufzeit minimal, da mehr Parameter überprüft werden müssen.

Fallbackwerte (Standardwerte)[Bearbeiten | Quelltext bearbeiten]

Ein Fallback-Wert (oder Standardwert) ist ein definierter Wert, der verwendet wird, wenn ein Parameter nicht übergeben wurde oder leer ist. Dies verhindert, dass die Vorlage unvollständige oder fehlerhafte Ergebnisse liefert.

Die Syntax hierfür ist, den Standardwert nach dem letzten senkrechten Strich innerhalb des Parameter-Tags zu platzieren.

Beispiel:Wenn der Parameter Farbe fehlt, soll automatisch blau verwendet werden.
{{{Farbe|blau}}}
Vorteile
  1. Robustheit: Die Vorlage liefert immer ein Ergebnis, selbst wenn der Benutzer vergisst, einen optionalen Parameter zu übergeben.
  2. Code-Minimierung: Es erspart oft die Notwendigkeit von Prüfungen, da der Default-Wert die Fehlerbehandlung übernimmt.
Mögliche Probleme
  1. Leere Werte: Das Problem entsteht, wenn kein Fallback-Wert angegeben wird (z. B. {{{1}}}), und der Parameter nicht übergeben wird. Der Parser gibt dann den Parameter-Namen selbst aus, d. h., der Text {{{1}}} erscheint unformatiert in der Ausgabe. Dies ist extrem unschön und verwirrend für den Leser.
  2. Zerstörte Wikisyntax: Wenn kein Wert übergeben wurde, kann der Parser gerade bei Formatierungen ein Problem verursachen, so wird ''{{1}}'' bei der leeren Übergabe dafür sorgen, dass der Parser statt der Auszeichnung in kursiver Schrift das hier sieht '''', was in der Ausgabe zu dazu führt, dass die drei aufeinanderfolgenden Hochkommas als Fettschrift interpretiert werden, die dann aber nicht mehr endet, weil die abschließenden ''' fehlen.
Hinweis
Um das Auftreten von nowiki>{{{1}}} im Live-Text zu verhindern, sollte jeder optionale Parameter in einer Vorlage immer einen Fallback-Wert enthalten, selbst wenn dieser nur ein leerer String ist (z. B. {{{1|}}}).


Steuerungsstrukturen[Bearbeiten | Quelltext bearbeiten]

Besonders wertvoll werden Vorlagen, wenn sie für den Benutzenden „mitdenken“, das heißt wenn sie selbst einen Teil der Arbeit abnehmen und Zustände Anhand der Parameter korrekt erkennen und ihre Ausgabe anpassen. Der Anspruch scheint simpel: „wenn dies, dann das“.

Info:In der Informatik spricht man hier auch von Bedingten Anweisungen. .

Die gute Nachricht ist, dass genau das mit Parserfunktionen und Magischen Wörtern möglich ist. Die schlechte Nachricht ist allerdings, man muss es dem Parser erst einmal beibringen und die Wikisyntax ist an dieser Stelle keine vollwertige Programmiersprache. Vieles ist möglich, sieht dann aber im Quelltext direkt aus wie ein Unfall an dem ein Lastwagen voller geschweifter Klammern beteiligt war.

Wer das nicht glaubt, darf sich an diesem Beispiel erfreuen: 

{{#if: {{{code|{{{lang|}}}}}} 
| {{#switch: {{#titleparts: {{uc:{{{code|{{{lang|}}}}}}}} | 1 | 1}}
  | DE = {{#ifexpr: 
    {{#if: {{#sub:{{uc:{{{code|{{{lang|}}}}}}}}|-4}} AND 
    {{#iferror: {{#expr: {{#sub:{{uc:{{{code|{{{lang|}}}}}}}}|-4|4}} + 0 }} 
    | 0 
    | 1
    }}
  | <span style="color:green;">Gültiger Code gefunden.</span>
  | #default = <span style="color:red;">Formatfehler oder unbekanntes Präfix.</span>
}}
| **ACHTUNG:** Kein Wert übergeben, nutze Standardwert 'de'.
}}

Falls du dich fragst, was der Code da eigentlich macht: Er gibt sicher den Sprachcode aus dem Titel einer Seite zurück, oder aktzptiert einen übergebenen Parameter code oder lang. Wobei sichergestellt wird, dass der Wert für den Vergleich immer klein geschrieben wird und ein Fallback auf de stattfindet, falls keine Auswertung erfolgreich ist.

Kleine Entwarnung
Nicht alle Vorlagen sind derartig kompliziert geschrieben, wir können dich als ermutigen, die Grundzüge der Parserlogik zu verstehen → siehe: Parserfunktionen

Module und Lua[Bearbeiten | Quelltext bearbeiten]

Wie bereits erwähnt, stoßen bedingte Anweisungen in der Parserlogik in speziellen Anwendungsfällen an ihre Grenzen. Viele der in höheren Programmiersprachen genutzten Möglichkeiten, für Berechnungen, Zeichenkettenverarbeitung, Arrays und Mehrdimensionalität und Schleifenverarbeitung sind da nur einige Beispiele.

Zwar gibt es theoretisch eine Konfigurationseinstellung, die weitere Parserfunktionen insbesondere für Zeichenketten freigibt, diese sind bei Wikonia aber aus gutem Grund deaktiviert, was auch aus gutem Grund der Standardeinstellung entspricht. Sie sind viel zu Lastintensiv für den Server und nahezu ungetestet, da selbst die großen Wikis sie nicht nutzen.

Für solche Zwecke kann aber auf Lua, als höhere Programmiersprache zurück gegriffen werden, die sich über den Modul-Namensraum in das Wiki einbinden lässt. Module werden direkt auf dem Server und noch vor der Übergabe an den Parser ausgeführt und nur deren Resultat wird in die Seite eingebunden, dies reduziert die Lastspitzen für den eigentlich zur Inhaltsdarstellung ausgelegten Parser enorm.

Fehlerauswertung[Bearbeiten | Quelltext bearbeiten]

Für die Wartung von Vorlagen ist es gelegentlich entscheidend, dass Fehlermeldungen zentral gesammelt werden und angezeigt werden. Im haben wir uns dazu entschlossen hier zwei in der Praxis erprobte Mittel zu kombinieren.

Fehlermeldungen[Bearbeiten | Quelltext bearbeiten]

Bei der Programmierung der Vorlage muss die Fehlermeldung bereits vorgesehen sein, sie wird per <span class="error">Hier die Fehlermelung</span> in HTML erzeugt. Es kann auch die Vorlage {{Fehlermeldung}} dafür genommen werden, die etwas Tipparbeit ersparen kann. Wichtig ist dabei, die Fehler im richtigen Fall abzufangen und die Meldung auszugeben. Da der Text der Fehlermeldung groß und rot dargestellt wird, sollte sie nicht ausufernd lang formuliert sein.

Fehlerkategorien[Bearbeiten | Quelltext bearbeiten]

Um schnell Wartungsarbeiten zu überblicken und fehlerhafte Vorlegeneinbindungen zu erfassen, gib es zusätzlich Wartungskategorien. Diese folgen dem gleichen Namensschema Kategorie:Vorlagenfehler/Vorlage:<name der Vorlage>. Diese werden regelmäßig durch die Mitglieder der Vorlagenmanufaktur, oder andere (ja auch du?) aufgerufen und geprüft.

  • Erstelle die Fehlerkategorie, wenn du die Vorlage fertig gestellt hast und binde dort {{Wartungskategorie}} ein, damit die Kategorie korrekt einsortiert und markiert wird, da sie leer und versteckt sein sollte, werden hier automatisch die richtigen Hilfe:Magische Wörter gesetzt.
  • In der Vorlagendokumentation füge die Vorlage {{Vorlagenfehler-Wartungskat}} ein, damit auch hier erkenntlich ist, welche Kategorie(n) zu dieser Vorlage gehören.
  • Eine Vorlage kann mehrere Wartungskategorien als Unter-Kategorie haben, falls verschiedene Fehler abgefangen werden müssen.

Wartungskategorien werden generell nur eingeloggten Benutzern angezeigt, die diese Funktion in ihren Einstellungen aktiviert haben.

Abgerufen von „https://wiki.wikonia.net/index.php?title=Hilfe:Vorlagenprogrammierung&oldid=3103“