Hilfe:Vorlagen/Erstellung

Aus ConanWiki
Zur Navigation springen Zur Suche springen


Namensraum[Quelltext bearbeiten]

Analog zu Benutzerseiten, Dateien oder Kategorien, werden Vorlagen von gewöhnlichen Wiki-Artikeln unterschieden. In ConanWiki steht hierfür der Namensraum Vorlage zur Verfügung. Seiten, die eine Vorlage repräsentieren, sind in diesem Namensraum anzulegen.

Eine Seite wird in einem bestimmten Namensraum angelegt, indem dieser als Präfix dem Titel der Seite vorangestellt wird: {{<Namensraum>:<Titel der Seite>}}. Um eine Seite als Vorlage anzulegen, ist diese demnach wie folgt zu benennen: {{Vorlage:<Name der Vorlage>}}.

Sichtbarkeit definieren[Quelltext bearbeiten]

Zu einer Vorlage kann die Sichtbarkeit einzelner Textblöcke aus der Vorlage definiert werden. Hierbei wird unterschieden, ob ein Textblock

  • nur auf der Vorlagenseite selbst sichtbar ist,
  • nur auf Seiten sichtbar ist, auf der die Vorlage eingebunden ist oder
  • sowohl auf der Vorlagenseite als auch auf den Seiten die die Vorlagen einbinden sichtbar ist.
<onlyinclude>
Wenn die Vorlage direkt betrachtet wird, haben <onlyinclude> und </onlyinclude> keine Wirkung auf alles, was dazwischen steht. Wenn die Vorlage jedoch auf einer anderen Seite eingebunden ist, wird ausschließlich angezeigt, was zwischen diesen beiden Tags steht. Außerhalb von <onlyinclude> können Dokumentationen und Kategorien in Vorlagen eingefügt werden, ohne dass diese in den Artikeln auftauchen. Es können auch mehrere nicht-verschachtelte <onlyinclude>-Blöcke in einer Vorlage stehen.
<includeonly>
Alles, was in einer Vorlage zwischen <includeonly> und </includeonly> steht, wird nur dann angezeigt, wenn die Vorlage auf einer anderen Seite eingebunden wird. Mit <includeonly> lassen sich zum Beispiel alle Seiten, die eine bestimmte Vorlage enthalten, automatisch einer Kategorie hinzufügen. <includeonly> kann auch innerhalb von <onlyinclude>-Blöcken stehen.
<noinclude>
Alles, was in einer Vorlage zwischen <noinclude> und </noinclude> steht, wird nur dann angezeigt, wenn die Vorlage selbst betrachtet wird und nicht auf einer Seite, auf der die Vorlage eingebunden ist. <noinclude> kann auch innerhalb von <onlyinclude>-Blöcken stehen. <onlyinclude> sollte zum Abgrenzen des eigentlichen Vorlagentextes von der Dokumentation, den Kategorien und Interwikilinks bevorzugt werden.

Sind in der Vorlage keine Vorgaben zur Sichtbarkeit definiert, ist standardmäßig der komplette Text der Vorlage immer sichtbar, also sowohl auf der Vorlagenseite als auch auf den Seiten, die die Vorlage einbinden.

Nachfolgend einige Beispiele für mögliche sinnvolle Vorgaben zur Sichtbarkeit:

Tag-Kombination Auf der Vorlagenseite Auf der einbindenden Seite Bemerkung
keine sichtbar sichtbar [1] [1] Nur, wenn kein onlyinclude-Block in der Vorlage ist.
<includeonly>…</includeonly> nicht sichtbar sichtbar [1] [1] Nur, wenn kein onlyinclude-Block in der Vorlage ist.
<noinclude>…</noinclude> sichtbar [2] nicht sichtbar [2] Auch innerhalb eines onlyinclude-Blocks.
<onlyinclude>…</onlyinclude> sichtbar sichtbar [3] [3] Text außerhalb des onlyinclude-Blocks wird nicht eingebunden.
Text 1
<onlyinclude>Text 2
<includeonly>Text 3</includeonly>
<noinclude>Text 4</noinclude>
</onlyinclude>Text 5
Text 1: sichtbar,
Text 2: sichtbar,
Text 3: nicht sichtbar,
Text 4: sichtbar,
Text 5: sichtbar
Text 1: nicht sichtbar,
Text 2: sichtbar,
Text 3: sichtbar,
Text 4: nicht sichtbar,
Text 5: nicht sichtbar

Nachfolgend einige Beispiele für nicht sinnvolle Kombinationen zur Sichtbarkeit:

Tag-Kombination Auf der Vorlagenseite Auf der einbindenden Seite Bemerkung
<includeonly>Text 1</includeonly>
<onlyinclude>Text 2</onlyinclude>
Text 1: nicht sichtbar,
Text 2: sichtbar
Text 1: nicht sichtbar,
Text 2: sichtbar
Wenn onlyinclude-Blöcke enthalten sind, werden Textblöcke außerhalb dieser nicht auf anderen Seiten eingebunden. Der Text 1 wird niemals angezeigt und diese Tag-Kombination ist demnach nicht sinnvoll.
<includeonly><onlyinclude>...
</onlyinclude></includeonly>
nicht sichtbar sichtbar Textblöcke innerhalb von includeonly-Blöcken werden außschließlich auf den einbindenden Seiten angezeigt. Der zusätzliche onlyinclude-Block macht demnach keinen Sinn und lediglich die Vorlage komplizierter.

Einfache Dynamisierung: Parameter definieren[Quelltext bearbeiten]

In Abschnitt "{{{refVorlageVerwenden}}}" wurde bereits angesprochen, dass Vorlagen parametrierbar sein können. Die Art und Weise der Parameterübergabe wird bei der Vorlagenerstellung definiert und kann im Nachhinein nur schwer geändert werden.

Innerhalb der Vorlage ist ein Platzhalter durch drei einschließende geschweifte Klammern gekennzeichnet; diese können entweder durchnummeriert oder durch frei gewählte Namen bezeichnet werden:

  • {{{Y}}}, wobei Y eine fortlaufende Nummer beginnend bei Eins ist, kennzeichnet einen anonymen Parameter.
  • {{{<Parametername>}}} kennzeichnet einen ausgezeichneten Parameter, der bei der Verwendung der Vorlage dediziert über seinen Namen angesprochen werden kann.

Nachfolgend ein kleines Beispiel, wie sich die beiden Parameterdefinitionen unterscheiden:

Anonyme und ausgezeichnete Parameter definieren

Beispielvorlage1:
Nach Auffassung {{{1}}}s ist der Täter {{{2}}}.
Beispielvorlage2:
Nach Auffassung {{{Detektiv}}}s ist der Täter {{{Täter}}}.

Die beiden Beispielvorlagen können wie folgt verwendet werden:

  • {{Beispielvorlage1|Kogoro Mori|Yoshihito Kureko}} -> Nach Auffassung Kogoro Moris ist der Täter Yoshihito Kureko.
  • {{Beispielvorlage2|Detektiv=Kogoro Mori|Täter=Yoshihito Kureko}} -> Nach Auffassung Kogoro Moris ist der Täter Yoshihito Kureko.

Das Ergebnis beider Vorlagen ist das gleiche. In Beispielvorlage1 ist jedoch implizit definiert, dass der Name des Detektivs immer als erster Parameter übergeben werden soll und der Name des Täters als zweiter Parameter. In Beispielvorlage2 hingegen ist über den zusätzlichen Parameternamen klar ersichtlich, welcher Parameter den Detektivnamen und welcher den Namen des Täters aufnimmt. In Beispielvorlage2 kann daher die Reihenfolge der Parameterübergabe ausgetauscht werden ohne die inhaltliche Aussage zu verändern, in Beispielvorlage1 geht dies nicht:

  • {{Beispielvorlage1|Yoshihito Kureko|Kogoro Mori}} -> Nach Auffassung Yoshihito Kurekos ist der Täter Kogoro Mori.
  • {{Beispielvorlage2|Täter=Yoshihito Kureko|Detektiv=Kogoro Mori}} -> Nach Auffassung Kogoro Moris ist der Täter Yoshihito Kureko.

 

Ob ein Parameter besser anonym oder mit einem Namen ausgezeichnet ist, entscheidet der Vorlagenentwickler bei Einführung des Parameters. Nachfolgende Hinweise können bei der Entscheidung helfen:

  • Anonyme Parameter bieten sich an, wenn
    • die Übergabe-Reihenfolge egal ist
    • die Anzahl der übergebenen Parameter beliebig ist / nicht von vornherein eingeschränkt sein soll
    • alle übergebenen Parameter gleich behandelt werden sollen

Ein gutes Beispiel hierfür sind Formatierungsvorlagen, die auf alle an sie übergebenen Parameter die gleiche Formatierungsvorgaben anwenden, bspw. den Text des Parameters als Link darstellen. In einer solchen Vorlage wird der erste Parameter gleich dem letzten behandelt und je nach Anwendungskontext wird an die Vorlage nur ein Parameter übergeben und ein anderes Mal sind es zwei oder mehr.

  • Ausgezeichnete Parameter bieten sich an, wenn
    • die Übergabe-Reihenfolge nicht egal ist
    • ein Parameter dediziert angesprochen oder ausgewertet werden soll
    • die übergebenen Parameter unterschiedlich behandelt werden sollen

Ein gutes Beispiel hierfür sind die Infoboxen. Hier wird ein Wert einem bestimmten Parameter zugewiesen, der innerhalb der Vorlage dediziert ausgewertet werden soll. Beispielsweise soll in der Infobox für Manga-Kapitel die Kapitelnummer nicht in dem Datumsfeld für die deutsche Erstveröffentlichung angezeigt werden. Durch die Parameternamen wird einerseits der Vorlagencode selbst besser lesbar und andererseits die Verwendung der Vorlage einfacher; Verwechslungen zwischen einzelnen Parametern können besser vermieden werden.

Wird ein Parameter nachträglich in eine bestehende Vorlage eingefügt, bietet es sich an, diesen entsprechend der anderen bereits vorhandenen Parameter ebenfalls anonym bzw. ebenfalls ausgezeichnet mit einem Namen zu definieren.

Hinweis: Nachträglich eingeführte Parameter werden auf Seiten, die die Vorlage bereits eingebunden hatten nicht automatisch verwendet, sofern kein Standardwert definiert ist. Es müssen demnach entweder die verwendenden Seiten entsprechend geändert werden oder die Änderung der Vorlage hat zunächst keine Auswirkungen auf einbindende Seiten.

Parameter mit Vorbelegung[Quelltext bearbeiten]

Ein Parameter kann innerhalb der Vorlage mit einem Standardwert vorbelegt werden. Hierzu wird der Parameter wie folgt angegeben: {{{<Parametername>|<Standardwert>}}}. Der senkrechte Strich („|“) trennt hierbei den Namen des Parameters und dessen Vorbelegung. Eine Vorbelegung kann zum Beispiel in Textbausteinen dazu verwendet werden, dass diese auch bei fehlender Parameterübergabe einen Sinn ergeben.

Parameter mit Vorbelegung

Beispielvorlage2:
Nach Auffassung {{{Detektiv|des Detektiv}}}s ist der Täter {{{Täter|noch unbekannt}}}.
  • {{Beispielvorlage2|Detektiv=Kogoro Mori|Täter=Yoshihito Kureko}} -> Nach Auffassung Kogoro Moris ist der Täter Yoshihito Kureko.
  • {{Beispielvorlage2}} -> Nach Auffassung des Detektivs ist der Täter noch unbekannt.

 

Hinweis: Wird ein Parameter an mehreren Stellen in der Vorlage verwendet, macht es Sinn, diesen entweder immer oder nie mit einem Standardwert zu belegen, es ist jedoch nicht erforderlich.

Leere Parameter[Quelltext bearbeiten]

Ein Parameter darf auch leer sein. Ein leerer Parameter ist aber nicht automatisch gleichbedeutend mit einer leeren Zeichenkette, also einem Leertext. Damit ein leerer Parameter bei Verwendung einer Vorlage auch als leerer Text angezeigt wird, wird dieser als Standardwert vorbelegt. Hierzu wird der Parameter wie folgt angegeben: {{{<Parametername>|}}}.

Leere Parameter zulassen

Beispielvorlage4:
Herzlich Willkommen {{{Benutzername}}}.
Beispielvorlage5:
Herzlich Willkommen {{{Benutzername|}}}.
  • {{Beispielvorlage4}} -> Herzlich Willkommen {{{Benutzername}}}.
  • {{Beispielvorlage5}} -> Herzlich Willkommen .

 

Erweiterte Dynamisierung: Funktionen[Quelltext bearbeiten]

Eine weitere Möglichkeit der Dynamisierung ist, komplexe Aufgabenstellungen in Teilaufgaben zu zerlegen und die Teilaufgaben zu lösen. Dadruch ist es umgekehrt möglich, die gelösten Teilprobleme in unterschiedlichen Kontexten zu verwenden. Die Lösung eines solchen Teilproblems kann als Funktion beschrieben werden.

Eine Funktion hat immer einen Namen, optional einen oder mehrere Eingabeparameter und genau einen Rückgabewert. Einige Funktionen, die Fragen zu einem Wiki-System beantworten, sind bereits Bestandteil der MediaWiki-Basisinstallation. Eine Übersicht über diese Basisfunktionen ist in der Wikipedia-Hilfe zu finden.

  • Beispiel 1: {{SORTIERUNG:<Sortierschlüssel>}}: diese Funktion übernimmt die Sortierung der Artikel innerhalb einer Kategorie.

Funktionen können auch als Vorlagen beschrieben werden. Sie können in anderen Vorlagen oder direkt in Artikeln über ihren Namen aufgerufen werden. In ConanWiki sind Vorlagen, die eine Funktion beschreiben, in die Kategorie:Vorlage:Funktion eingeordnet.

  • Beispiel 2: Vorlage:KB:Diese Vorlage bekommt als Eingabeparameter eine Kapitelnummer aus dem Detektiv Conan-Manga und gibt die Nummer des entsprechenden Manga-Bandes zurück, in dem das Kapitel zu finden ist.

Nachfolgend werden Erweiterungen vorgestellt, die bei der Erstellung von Vorlagen hilfreich sind. Da diese generell für Wiki-Systeme gültig und im Internet bereits gute dokumentiert sind, wird für die vertiefende Lektüre in der Regel auf entsprechende Dokumentationen verwiesen.

Erweiterung: Variablen[Quelltext bearbeiten]

Variablen sind, ähnlich wie Parameter, Platzhalter und bieten die Möglichkeit, eine Vorlage in einem gewissen Rahmen flexibel auf verschiedene Anwendungsfälle reagieren zu lassen. Wie die nachfolgenden beiden Beispiele zeigen, sind Variablen nicht auf den Einsatz in Vorlagen beschränkt.

  • Beispiel 3: Auf dieser Hilfeseite sind die Überschriften als Variablen definiert. Damit ist es möglich sehr bequem auf einzelne Abschnitte der Hilfeseite zu referenzieren. Werden die Überschriften im Rahmen zukünftiger Bearbeitungen zu dieser Hilfeseite angepasst, so bleibt die Referenzierung weiterhin korrekt. Es ist nicht notwendig, die gesamte Hilfeseite manuell zu prüfen.
  • Beispiel 4: Die Nummerierung der Beispiele auf dieser und anderen Hilfeseiten ist über eine Variable abgebildet, die die Anzahl der bisher im Dokument enthaltenen Beispiele als nummerischen Wert gespeichert hat. Wird irgendwo auf der Seite ein neues Beispiel hinzugefügt, wird zuvor der Wert dieser Zählervariable um eins erhöht. Wird irgendwo auf der Seite ein Beispiel entfernt, wird auch die zugehörige Inkrementation der Zählervariable entfernt. Auch können die Beispiele dadurch beliebig mit einander getauscht oder an andere Positionen der Hilfeseite verschoben werden. Es ist nicht notwendig, anschließend die gesamte Hilfeseite manuell auf eine korrekte Nummerierung der Beispiele zu prüfen.

Nachfolgend eine kleine Übersicht über ausgewählte Eigenschaften zu Parametern und Variablen:

Eigenschaft Parameter Variable
Funktion dienen als Schnittstelle zur Vorlage, um Werte aus dem Kontext außerhalb der Vorlage an die Vorlage zu übergeben dienen innerhalb der Vorlage dazu, Werte zu definieren und mehrfach zu verwenden oder sie zu verändern
Veränderbarkeit Werte werden innerhalb der Vorlage nicht verändern Werte können innerhalb der Vorlage verändert werden
Zugriff werden außerhalb der Vorlage mit Werten belegt;
Werte können innerhalb der Vorlage abgefragt werden
werden innerhalb der Vorlage mit Werten belegt;
Werte können innerhalb der Vorlage abgefragt werden

Im Rahmen von MediaWiki-Systemen sind Variablen Bestandteil der Erweiterung Variables. Diese Erweiterung ist in ConanWiki installiert und kann verwendet werden.

Um eine Variable zu definieren oder mit einem Wert zu belegen, wird die folgende Syntax verwendet:

{{#vardefine:<Name der Variable>|<optionale Vorbelegung>}}

Um den Wert einer Variable abzurufen wir die folgende Syntax verwendet:

{{#var:<Name der Variable>}}

Erweiterung: Parser-Funktionen[Quelltext bearbeiten]

Als Parser-Funktionen werden die Funktionen der MediaWiki-Erweiterung ParserFunctions herausgehoben. Diese Erweiterung ist in ConanWiki installiert und kann verwendet werden.

Mit dieser Erweiterung ist es u. a. möglich, bedingte Abfragen, Existensprüfungen oder mathematische Berechnungen durchzuführen.

Automatisches Hochzählen der Beispiele in einer Hilfeseite

Im Abschnitt zun der MediaWiki-Erweiterung Variables wurde bereits angesprochen, dass für die Nummerierung der Beispiele auf den Hilfeseiten eine Zählervariable definiert ist, die mit jedem Beispiel um eins erhöht wird. Diese schrittweise Erhöhung ist mithilfe der Parser-Dunktion expr abgebildet.

Syntax: {{#vardefine:countExample|{{#expr:{{#var:countExample}} + 1}} }}

Die Variable selbst trägt den Namen countExample.

  • {{#vardefine:countExample: die Variable soll mit einem neuen Wert belelgt werden
  • {{#expr:{{#var:countExample}} + 1}}: der neue Wert der Variable ist der Rückgabewert der expr-Funktion
    • {{#var:countExample}}: bisheriger Wert der Variable

 

Eine Übersicht über die Funktionen dieser Erweiterung finden sich in der Hilfe zur Erweiterung. Eine deutsche Erläuterung zu den Funktionen ist auch in der Wikipedia-Hilfe zur Vorlagenprogrammierung zu finden.

Erweiterung: Wiederholungen[Quelltext bearbeiten]

Mit der MediaWiki-Erweiterung Loops können Wiederholungen abgebildet werden. Diese Erweiterung ist in ConanWiki installiert und kann verwendet werden.

Dokumentation[Quelltext bearbeiten]

Vorlagen sind bei der Erstellung oder Bearbeitung immer entsprechend zu dokumentieren. Dies erhöht einerseits die Wartbarkeit der Vorlage selbst und andererseits wird damit der Anwender einer Vorlage bei der Einbindung auf einer Seite unterstützt.

  • Beispiel 5: Vorlage:Infobox Kapitel: Neben den einleitenden Bemerkungen sind ein Abschnitt zur Verwendung mit Parameterübersicht und eine Kopiervorlage enthalten.

Bei Erstellung einer Vorlage sind die folgenden Informationen anzugeben:

  • Beschreibung, was die Funktion und das Ziel der Vorlage ist
  • Verwendungshinweis
    • Wann ist die Vorlage einzusetzen bzw. wann nicht
    • Wie kann die Vorlage verwendet werden
    • Falls die Vorlage parametrierbar ist: Übersicht über die möglichen Parameter der Vorlage mit kurzer Erläuterung
  • Vorschau / Anwendungsbeispiele (optional)
  • Kopiervorlage (optional)

Bei Bearbeitung einer Vorlage sind folgende Änderungen zu dokumentieren:

  • Neue Parameter sind in die Parameterübersicht mit einer kurzen Erläuterung aufzunehmen bzw. es ist eine Parameterübersicht anzulegen
  • Entfallene Parameter sind in der Parameterübersicht als obsolet oder veraltet zu kennzeichnen
  • Geänderte oder ergänzte Funktionsweisen sind zu beschreiben und ggf. mit einem Beispiel zu verdeutlichen
  • Bereits vorhandene Anwendungsbeispiele oder Kopiervorlagen sind auf Korrektheit zu prüfen und ggf. an die durchgeführten Änderungen anzupassen
  • Nach dem Speichern der durchgeführten Änderungen an der Vorlage ist die Vorschau zu prüfen (insbesondere bei Textbausteinen wichtig) und ggf. durch ein touch, ein erneutes Speichern ohne Änderungen zu tätigen, zu aktualisieren

Die Dokumentation kann in der Regel auf der Vorlagenseite selbst erfolgen. Damit sie nicht auf den einbindenden Seiten angezeigt wird, wird die Dokumentation in einen noinclude-Block eingeschlossen oder außerhalb der onlyinclude-Blöcke gesetzt.

Ausführliche oder sehr komplexe Dokumentationen können auch auf eine Unterseite zur Vorlage ausgelagert werden. Die Dokumentation soll in diesem Fall auf einer Seite mit dem Titel Vorlage:<Name der Vorlage>/Doku erstellt werden. Eingebunden wird die Dokumentation dann wie eine Vorlage auf der Seite der Vorlage, die sie dokumentiert:

<noinclude>{{Vorlage:<Name der Vorlage>/Doku}}</noinclude>.

Kategorisierung[Quelltext bearbeiten]

Siehe auch: Hilfe zu Kategorien

Abschließend ist die Vorlage zu kategorisieren. Hierfür sind eine oder mehrere passende Unterkategorien aus Kategorie:Vorlage anzugeben. Im Abschnitt "" sind die einzelnen Unterkategorien in ConanWiki im Überblick dargestellt. Diese Kurzbeschreibungen finden sich auch auf den Seiten der jeweiligen Kategorien und sollen beim Einordnen oder Finden von Vorlagen unterstützen. Eine Einsortierung von Vorlagen in Artikelkategorien ist nicht erwünscht.

Bei der Kategorisierung von Vorlagen ist zu beachten, dass dies innerhalb von noinclude-Blöcken oder außerhalb von onlyinclude-Blöcken geschieht, damit nur die Vorlage der Kategorie zugeordnet wird und nicht alle Seiten, in denen die Vorlage verwendet wird: <noinclude>[[Kategorie:Vorlage:<Unterkategorie>]]</noinclude>.

Soll eine Sortierung vorgegeben werden, ist der Sortierschlüssel direkt beim Setzen der Kategorie anzugeben: [[Kategorie:Vorlage:<Unterkategorie>|<Sortierschlüssel>]].