Ausgabefilter

Ausgabefilter stellen eine Methode dar, um den Text zu verändern, den ein Platzhalter ausgibt. Dieser Weg ist oft einfacher als der Einsatz von vtCalc oder vtEcho. Die Schreibweise sieht so aus, dass vor der schließenden Klammer des Platzhalters ein Pipesymbol (|) und der Name des gewünschten Filters eingefügt wird, zum Beispiel:

{{Headline|strtoupper}}

Hiermit würden alle Buchstaben, die der Platzhalter Headline ausgibt, in Großbuchstaben umgewandelt.

Die Standard-Ausgabefilter (siehe unten) erwarten eine zusätzliche Angabe, die durch einen Doppelpunkt vom Filternamen abgetrennt wird, zum Beispiel:

{{Preis|num-en:2.,}}

Hiermit würde eine Preisangabe mit zwei Nachkommastellen, einem Punkt als Tausendertrennzeichen und einem Komma als Dezimaltrennzeichen ausgegeben.

Standard-Ausgabefilter

Folgende Ausgabefilter sind fest in Virthos eingebaut.

num

Interpretiert den Text als Zahl in deutscher Schreibweise (mit Komma als Dezimaltrennzeichen) und bringt diese in ein bestimmtes Format. Das Format wird als Zusatzangabe mit bis zu drei Zeichen angegeben:

Position	Bedeutung
1	Anzahl der Nachkommastellen (Vorgabe: 0)
2	Tausendertrennzeichen (Vorgabe: Punkt)
3	Dezimaltrennzeichen (Vorgabe: Komma)

Wenn die Formatangabe fehlt, liefert num eine Zahl ohne Nachkommastellen mit einem Punkt als Tausendertrennzeichen. Wenn Sie nur zwei Zeichen angeben, wird das zweite Zeichen als Dezimaltrennzeichen verwendet, und die Zahl wird ohne Tausendertrennzeichen ausgegeben.

num-en

Interpretiert den Text als Zahl in angelsäschischer Schreibweise (mit Punkt als Dezimaltrennzeichen) und bringt diese in ein bestimmtes Format. Das Format wird als Zusatzangabe mit bis zu drei Zeichen angegeben (siehe num).

date

Interpretiert den Text als Zeitangabe und bringt diese in ein bestimmtes Format. Bei der Zeitangabe kann es sich um einen Unix-Zeitstempel (Zahl der Sekunden seit dem 01.01.1970) handeln, um ein Datum in deutscher oder internationaler Schreibweise oder um eine relative Angabe in englischer Sprache wie "tomorrow" oder "+14 days". Welche Angaben im Einzelnen möglich sind, kann der Dokumentation der PHP-Funktion strtotime entnommen werden.

Das Format wird in der Schreibweise angegeben, wie sie von der PHP-Funktion date erwartet wird. Zum Beispiel:

{{Datum | date:YYYY-mm-dd }}

Von Version 3.8.7 bis 4.1.2 erlaubte Virthos auch Formatangaben in der Schreibweise der PHP-Funktion strftime, womit insbesondere deutsche Wochentags- und Monatsnamen möglich waren. Diese Funktion ist seit PHP 8.1 als veraltet markiert, deshalb verwendet Virthos seit Version 4.2.0 die IntlDateFormatter-Klasse für denselben Zweck. Die verwendbaren Codes sind hier dokumentiert. Um deutlich zu machen, dass lokalisierte Namen ausgegeben werden sollen, muss das erste Zeichen des Formatcodes ein Prozentzeichen sein. Dieses wird nicht mit ausgegeben.

Wenn der Virthos-Konfigurationsparameter systemLanguage auf "de" eingestellt ist, werden Wochentags- und Monatsnamen in deutscher Sprache ausgegeben, ansonsten in englischer. Um hiervon abzuweichen, können Sie mittels vtCalc und der PHP-Funktion setlocale explizit eine Sprache festlegen.

list

Interpretiert den Text als Wert einer vorgegebenen Werteliste und gibt den zugehörigen Beschreibungstext aus. Die Werteliste muss zuvor mittels vtSet als Objektliste in einer Variablen gespeichert werden, wobei jedes Objekt ein value- und ein text-Attribut erhalten muss. Der Name der Variablen wird dann im Ausgabefilter als Zusatzangabe notiert, zum Beispiel:

<!--{{vtSet: Wochentage = '[
    { "value": "1", "text": "Montag" },
    { "value": "2", "text": "Dienstag" },
    { "value": "3", "text": "Mittwoch" },
    { "value": "4", "text": "Donnerstag" },
    { "value": "5", "text": "Freitag" }
]' }}-->

<p>eingeplant für: {{Wochentag | list:Wochentage }}</p>

calc (ab v3.8.7)

Interpretiert den Platzhalter als Zahl und verändert diese durch Addition, Subtraktion, Multiplikation oder Division. Dazu muss einer der Operatoren +, -, * oder / sowie ein Zahlenwert als Filterzusatz angegeben wird. Der calc-Filter wird automatisch angewendet, wenn die Filterangabe mit einem der vier Operatoren beginnt, darum kann der Name auch weggelassen werden.

ceil, floor, round (ab v3.8.7)

Diese drei Filter arbeiten genauso wie calc, nur mit dem Unterschied, dass sie das berechnete Ergebnis auf die nächst höhere (ceil) oder niedrigere (floor) Ganzzahl bzw. nach kaufmännischer Regel (round) runden.

mod (ab v3.8.7)

Interpretiert den Platzhalter als numerischen Wert und gibt den Rest aus, der verbleibt, wenn man diesen durch die als Filterzusatz übergebene Zahl dividiert.

%...

Wenn der Filter mit einem Prozentzeichen beginnt, wird die PHP-Funktion sprintf als Filter verwendet. Die Funktion bekommt als ersten Parameter (Formatierungs-String) die Filter-Zeichenkette übergeben, als zweiten den Platzhaltertext.

<p>{{vtGet:Anzahl|%'.06d}}</p>
<!-- gibt Anzahl sechstellig aus, ggf. mit vorangestellten Nullen -->

PHP-Funktionen als Ausgabefilter

Neben den Standard-Ausgabefiltern können Sie jede PHP-Funktion, die mit einem einzelnen Argument aufgerufen werden kann, als Filter verwenden. Die folgende Tabelle listet einige gebräuchliche PHP-Funktionen auf, die sich als Filter eignen:

Name	Funktion
`htmlentities`	wandelt alle geeigneten Zeichen in entsprechende HTML-Codes um
`htmlspecialchars`	wandelt Sonderzeichen in HTML-Codes um
`strlen`	gibt die Anzahl der Zeichen aus
`strtolower`	wandelt alle Buchstaben in Kleinbuchstaben um
`strtoupper`	wandelt alle Buchstaben in Großbuchstaben um
`urldecode`	ersetzt spezielle Zeichenfolgen, die in URLs vorkommen können, durch die ursprünglichen Sonderzeichen
`urlencode`	ersetzt Sonderzeichen, die in URLs nicht erlaubt sind, durch spezielle Zeichenfolgen
`utf8_decode`	konvertiert den Text von UTF8 nach ISO 8859-1 (Latin 1)
`utf8_encode`	konvertiert den Text von ISO 8859-1 (Latin 1) nach UTF8

Weitere Einzelheiten finden Sie in der PHP-Dokumentation.

Eigene Funktionen als Ausgabefilter

Sie können auch eigenen PHP-Funktionen schreiben und als Ausgabefilter verwenden. Eine solche Funktion bekommt als erstes Argument den Text übergeben, den der betreffende Platzhalter ausgibt, und als zweiten die zusätzlichen Parameter, die hinter dem Doppelpunkt notiert sind (oder eine leere Zeichenkette, falls es keine Parameter gibt). Die Funktion muss dann den Text zurückliefern, der an Stelle des eigentlichen Platzhaltertextes ausgegeben werden soll.

Das folgende Beispiel zeigt eine PHP-Funktion, die einen einfachen Filter definiert:

function first_chars( $text, $count )
{
    $count = empty( $count ) ? : 1 : (int) $count;
    return substr( $text, 0, $count );
}

Diese Funktion liefert die ersten Zeichen des übergebenen Textes zurück. Die Verwendung als Ausgabefilter könnte dann so aussehen:

<p>Kürzel: {{Vorname|first_chars:2}}{{Nachname|first_chars:2}}</p>

Damit Virthos einen selbst definierten Ausgabefilter nutzen kann, muss die PHP-Datei, in der die betreffende Funktion definiert ist, mittels vtLoad ins Template eingebunden werden. Alternativ können Sie die Datei auch mit Hilfe des Konfigurationsparameters includeFile einbinden.

Unterstützung

Die folgende Liste zeigt, in welchen VirthosTalk-Platzhaltern Ausgabefilter verwendet werden können: