Vorlage:Zeitraumübersicht Kosch/Doku

Die ist die Dokumentation für die Vorlage:Zeitraumübersicht Kosch. Sie wird dort ebenfalls angezeigt, weil die Dokumentation wie eine eigene Vorlage funktioniert und daher einfach eingebunden werden kann.

Was macht diese Vorlage?

Mit dieser Vorlage werden zu einem Jahr (oder einem kürzeren Zeitraum innerhalb eines Jahres) die jeweiligen Ereignisse und Briefspieltexte inklusive Gliederung angezeigt. Sie ist ein Koscher Ersatz für Vorlage:Zeitraumübersicht.

Wesentliche Unterschiede:

• Die Zeitleiste wird weggelassen (da das im KoschWiki anders gemacht wird).
• Die Abfrage Briefspielkarte wird weggelassen (da Koordinaten bisher selten eingetragen wurden).
• Schlachten und Turnieren werden zusätzlich abgefragt (nur für ein ganzes Jahr).
• Der Filter auf den Chroniktyp wird nur einmal angezeigt.
• Belehnungen, Geburten, Sterbefälle, Hochzeiten, Weihetage und sonstige Ereignisse werden separat abgefragt.
• Briefspieltexte, die das Jahr erwähnen, werden ebenfalls abgefragt (nur für ein ganzes Jahr).
• Sollte es falsch gesetzte Attribute geben, werden diese separat angezeigt - zusammen mit dem Hinweis, sie zu ändern und wie das geht (wenn ein ganzes Jahr abgefragt wird).
• Sollte es zu keinem Treffer kommen, bleibt der jeweilige Teil der Abfrage unsichtbar.

Die Vorlage

• fragt Schlachten und Turnier ab und listet die Ergebnisse auf
• ruft die Vorlage Vorlage:Abfrage Chronik auf
• listet die Ergebnisse von sechs Abfragen auf
• ruft die Vorlage Vorlage:Abfrage Briefspieltexte Kosch auf
• listet die Ergebnisse von drei Abfragen auf, wobei nach dem aventurischen Datum aufsteigend sortiert wird und die Abfragen auf die letzten 120, 12, bzw. 6 Texte beschränkt werden.
• Mit Hilfe von weiteren Parametern können sowohl die Sortierreihenfolge als auch die Anzahl der Texte angepasst werden.

Wie verwendet man diese Vorlage?

Die Vorlage verwendet Parameter, welche mit Standardwerten versehen werden, falls man nichts weiter angibt.

Im einfachsten Fall reicht es also aus, folgenden Code in eine Seite einzufügen:

{{Zeitraumübersicht Kosch}}

Ein Beispiel für den umgekehrten Extremfall, dass alle Parameter angegeben werden:

{{Zeitraumübersicht Kosch|DatumVon=01.01.1032|DatumBis=5.13.1032|Maximale Anzahl Texte=192|Maximale Anzahl Briefspieltext=36|Maximale Anzahl Fehler=12|Sortierung=aufsteigend}}

• Man kann jeden Parameter unabhängig von den anderen verwenden, also auch nur einen oder zwei angeben und den Rest weglassen.
• Es spielt keine Rolle, in welcher Reihenfolge man die Parameter angibt.

Parameter:

• DatumVon - Startdatum (Grenze inklusive). Standardwert ist "{{PAGENAME}}". Im GGP-Wiki werd bei der Angabe "1.1.<JAHR>" nicht Ereignisse und Briefspieltexte abgefragt, die irgendwann in einem Jahr geschehen sind.

• DatumBis - Enddatum (Grenze inklusive). Standardwert ist "5.13.{{PAGENAME}}". Beide Angaben müssen im selben Jahr liegen, weil ansonsten einige der Abfragen nicht funktionieren.

• Maximale Anzahl Texte - maximale Anzahl der Briefspieltexte, in denen das Attribut "Briefspiel-Zeitindex ist::" mit dem Artikel gesetzt wurde und dieses in den abgefragten Zeitraum fällt. Standardwert beträgt 120. Gibt es mehr als diese maximale Anzahl von Briefspieltexten, erscheint in der letzten Zeile der Tabelle unten rechts ein Link auf (… weitere Ergebnisse). Die Idee dahinter: In vielen Fällen reichen 120 Einträge aus. Liegt die Anzahl der gefundenen Briefspieltexte knapp darüber, ist es praktisch, die Grenze anpassen zu können. Ohne eine automatische Grenze wäre es gefährlich, die Vorlage auszuprobieren, weil das Ergebnis dann aus Hunderten von Briefspieltexten bestehen könnte, was die Seite sehr lang machen und deren Ladezeit ernorm in die Höhe treiben würde.

• Maximale Anzahl Briefspieltext - analog zu Maximale Anzahl Texte, nur dass hier das Attribut "Briefspieltext mit::" abgefragt wird und die maximale Anzahl der Ergebnisse auf 12 beschränkt wird.

• Maximale Anzahl Fehler - analog zu Maximale Anzahl Texte, nur dass hier alle anderen möglichen Attribute abgefragt werden (deren Setzung immer ein Fehler ist) und die maximale Anzahl der Ergebnisse auf 6 beschränkt wird.

• Sortierung Optionen: asc/desc/aufsteigend/absteigend - Standardwert ist "asc". Damit wird eingestellt, ob die Suchergebnisse nach aventurischer Zeit aufsteigend oder absteigend sortiert werden sollen und ob gleichzeitig durch den Filter die ältesten oder jüngsten Texte ausgegeben werden sollen. Dabei sind asc und aufsteigend bzw. desc und absteigend gleichwertig.

Einsatzzweck

In erster Linie in den Artikeln zu einem Jahr.

Der Artikel 1032 dient als Beispiel dafür, wie die Vorlage eingebunden wird und mehrere der möglichen Parameter gesetzt werden.

Technische Dokumentation

Absolut unwichtig für normale Benutzer, nur relevant für Vorlagen-Programmierer. Daher folgt reichlich technisches Vokabular!

Die Vorlage besteht grob aus zwei Teilen:

• Definition von Variablen, die Abfragen enthalten
• bedingte Anzeige der Ergebnisse

Zunächst wird eine Reihe von Variablen definiert, die für die folgenden Abfragen relevant werden.

• Für DatumVon wird der Wert des gleichnamigen Parameters geprüft. Ist dieser leer, wird "{{PAGENAME}}" verwendet. Ansonsten wird der Wert des Parameters übernommen, wobei führende Nullen aus jedem Vorkommen von "1." entfernt werden. (Das spielt später noch eine Rolle.)
• Für DatumBis wird der Wert des gleichnamigen Parameters geprüft. Ist dieser leer, wird "5.13.{{PAGENAME}}" verwendet. (Dass dies nicht äquivalent zur vorangegangenen Variable geschieht, liegt an einer Setzung aus dem GGP-Wiki. Für ein ganzes Jahr muss "<JAHR>" / "5.13.<JAHR>" verwendet werden, weil Ereignisse, die irgendwann im Jahr geschehen, dem 1.1. vorangestellt werden und damit nicht abgefragt werden, wenn der Zeitraum mit dem 1.1. eines Jahres beginnt.) Ansonsten wird der Wert des Parameters übernommen, wobei führende Nullen aus jedem Vorkommen von "5." entfernt werden. (Das spielt später noch eine Rolle.)

Nun folgen zwei weitere Variablen, die für diejenigen Abfragen relevant sind, die nur mit einer Jahresangabe (ohne Tage oder Monate) funktionieren.

• Für Jahr wird die Angabe hinter dem letzten Punkt von DatumVon genommen.
• Für Ende wird die Angabe hinter dem letzten Punkt von DatumBis genommen.

Jetzt werden die Variable DatumVon über eine switch-Anweisung erneut definiert. Hierbei wird der Wert der Kombination von DatumVon und DatumBis verwendet:

• 1.1.Jahr5.13.Ende - verwende Jahr (ohne führende 1en, so dass tatsächlich ein ganzes Jahr ausgewertet wird)
• 1.1.JahrEnde - verwende Jahr (ohne führende 1en, so dass tatsächlich ein ganzes Jahr ausgewertet wird)
• in jedem anderen Fall: DatumVon

DatumBis wird ebenfalls erneut definiert. Hier reicht nach der Setzung gerade jedoch eine einfache Fallunterscheidung. Falls die Kombination aus DatumVon und DatumBis der Kombination aus Jahr und Ende entspricht, dann setze DatumBis auf 5.13.Ende. Ansonsten behalte den bisherigen Wert von DatumBis.

Insgesamt setzt das die folgende Logik um: Falls (1.1.JAHR A oder JAHR A) UND (5.13.JAHR B oder JAHR B), dann auf JAHR A und 5.13.JAHR B umsetzen.

Die Von- und Bis-Angaben müssen für die Zeitangaben in Briefspieltexten (B) und Chronikereignissen (C) in das jeweils verwendete Format konvertiert werden. Ansonsten klappen Abfragen mit Eingrenzung des Zeitraums nicht.

Dazu werden verschiedene Funktionen des Datummoduls (Modul:Datum) aufgerufen.

• VonC und VonB haben DatumVon als Basis. Hier wird anders umgerechnet als in der ursprünglichen Vorlage (eine Sekunde früher!), weil ansonsten ein Text, der genau auf Mitternacht am 1. Praios datiert ist, nicht mit abgefragt wird.
• BisC und BisB haben DatumBis als Basis.

Damit sind alle benötigten Zeitangaben in den verschiedenen Formaten vorhanden und stehen für die eigentlichen Abfragen zur Verfügung.

Dann werden Schlachten und Turniere abgefragt - ähnlich wie in der Vorlage:Abfrage Schlachten und Vorlage:Abfrage Turniere, nur mit dem Unterschied, dass hier das Attribut "Jahr ist::" bezogen auf die Variable "Jahr" abgefragt wird. Die beiden Abfrage werden überhaupt nur aufgerufen, wenn tatsächlich ein gesamtes Jahr als Zeitraum gewählt wurde. Das wird darüber geprüft, dass "DatumVon" und "DatumBis" der Variable "Ende" und "5.13." und der Variable "Jahr" entsprechen. Dass "Ende" und "Jahr" in der umgekehrten Reihenfolge stehen, hat zur Folge, dass nur abgefragt wird, wenn Start und Ende im selben Jahr liegen.

Danach werden sechs Variablen namens Herrscher, Tsatag, Borontag, Traviabund, Weihetag und Ereignis definiert, deren Inhalt jeweils über einen Aufruf der Vorlage Vorlage:Abfrage Chronik bestimmt wird. Der Zeitraum wird auf den Wert der Variablen "VonC" und "BisC" eingegrenzt, der Typ entsprechend der Variable.

Falls mindestens eine der sechs Variablen mit Inhalt gefüllt wurde, es also mindestens einen Treffer insgesamt gab, wird entsprechend die Leiste mit den Knöpfen gesetzt, mit denen die Art der Ereignisse vom jeweiligen Leser flexibel aus- und wieder eingeblendet werden kann.

Falls es mindestens ein entsprechendes Ereignis gab, wird das jeweilige Ergebnis ausgegeben zusammen mit der entsprechenden Überschrift zweiter Ordnung sowie der Formatierung, die notwendig ist, um die Ereignisse je nach Art ausblenden zu können. Da das Ergebnis der Abfrage Chronik auch ohne Treffer nicht leer ist (Zeilenumbruch), wird nicht die Befüllung der Variablen an sich abgefragt, sondern die Position der Angabe "BF:", da jeder Treffer mindestens einmal diesen Text enthält.

Schließlich werden drei Variablen namens Texte, Erwähnungen und Unrest definiert, deren Inhalt jeweils über einen Aufruf der Vorlage Vorlage:Abfrage Briefspieltexte Kosch bestimmt wird. Für den Parameter Abfrage wird dabei gefiltert auf das Attribut "Briefspiel-Zeitindex ist:" zwischen "VonB" und "BisB", "Briefspiel-Zeitindex ist:" mit der Variable "Jahr", alle anderen besonderen Attribute mit der Variable "Jahr". Im zweiten Fall wird außerdem abgefragt, dass der Briefspieltext selbst außerhalb des Jahres liegt (weil er sonst bereits mit der ersten Abfrage abgedeckt wurde). In den letzten zwei Fällen wird die Abfrage überhaupt nur aufgerufen, wenn tatsächlich ein gesamtes Jahr als Zeitraum gewählt wurde. Das wird darüber geprüft, dass "DatumVon" und "DatumBis" der Variable "Ende" und "5.13." und der Variable "Jahr" entsprechen. Dass "Ende" und "Jahr" in der umgekehrten Reihenfolge stehen, hat zur Folge, dass nur abgefragt wird, wenn Start und Ende im selben Jahr liegen.

Der erste Fall wird durch die Datierung des Briefspieltextes abgedeckt. Der zweite Fall ist das, was in einem Briefspieltext gesetzt werden muss für ein erwähntes Jahr. Entsprechend ist jedes andere Attribut ein Fehler, so dass auf alle anderen Attribute für die Fehlerauswertung abgefragt wird.

Hierbei wird der Wert des Parameters Sortierung ausgewertet - oder asc verwendet, falls dieser nicht gesetzt wurde. Als Begrenzung für die Abfragen wird entweder die Zahl verwendet, die in der Variable Maximale Anzahl Texte, Maximale Anzahl Briefspieltext bzw. Maximale Anzahl Fehler festgelegt wurde, oder 120 (Briefspieltext im angegebenen Zeitraum), 12 (Erwähnung) bzw. 6 (Fehler).

Falls mindestens eine der drei Variablen mit Inhalt gefüllt wurde, es also mindestens einen Treffer insgesamt gab, wird entsprechend die Überschrift zweiter Ordnung Briefspieltexte gesetzt zusammen mit den Knöpfen, mit denen die Anzahl der Ergebnisspalten vom jeweiligen Leser flexibel zwischen eins und drei umgeschaltet werden kann.

Falls es mindestens einen Briefspieltext mit angegebenen Zeitraum, eines Erwähnung oder einen Fehler gab, wird das jeweilige Ergebnis ausgegeben zusammen mit der Formatierung, die notwendig ist, um die Anzahl der Ergebnisspalten verändern zu können. Bei falsch gesetzten Attributen gibt es außerdem noch jeweils eine Überschrift dritter Ordnung, die auf bestehende Fehler hinweist und wie man sie ändern kann.

Zum Schluss wird das Attribut "Zeitindex ist=" auf den Wert der Variable VonC gesetzt.