Syntax

VirthosTalk ist eine Makrosprache, mit der sich Platzhalter und Anweisungen in HTML- und andere Arten von Textdateien einbinden lassen. Welche Platzhalter und Anweisungen zur Verfügung stehen, ist in der Funktionsreferenz beschrieben. Im Folgenden sind die allgemeinen Regeln zusammengefasst, die beim Schreiben von VirthosTalk-Funktionen zu beachten sind.

Grundregeln

VirthosTalk-Elemente lassen sich an beliebige Stellen in den HTML-Code eines Templates einbinden, nicht nur in den Rumpf, sondern auch in den Kopfbereich, in Stildefinitionen und in JavaScript-Funktionen. Damit ein VirthosTalk-Element als solches erkannt und richtig verarbeitet wird, müssen Sie es in doppelt geschweifte Klammern einschließen:

... {{VirthosTalk-Element}} ...

Beim Verarbeiten wird das VirthosTalk-Element mitsamt den geschweiften Klammern aus dem Quellcode entfernt und --- falls es sich um einen Platzhalter handelt --- durch einen anderen Wert ersetzt. Der umgebende Code wird dabei nicht verändert.

Wenn ein VirthosTalk-Element unmittelbar von HTML-Kommentarzeichen umgeben ist, werden diese Kommentarzeichen beim Verarbeiten ebenfalls aus dem Quellcode entfernt:

... <!--{{VirthosTalk-Element}}--> ...

Beachten Sie, dass sich vor der öffnenden und nach der schließenden geschweiften Klammer kein Leerzeichen befinden darf, da die Kommentarzeichen andernfalls nicht aus dem Code entfernt würden. Dies könnte dann zu unerwünschten Ergebnissen führen.

Ob ein VirthosTalk-Element in Kommentarzeichen eingeschlossen ist oder nicht, spielt für die Verarbeitung keine Rolle. Der Quellcode eines HTML-Templates bleibt aber übersichtlicher, wenn Sie Platzhalter grundsätzlich ohne und Anweisungen grundsätzlich mit Kommentarzeichen schreiben, wie es auch in den Codebeispielen der Fall ist.

Bitte beachten Sie: Wenn Sie JavaScript- oder PHP-Code in ein Template einbinden, müssen Sie sicherstellen, dass darin nicht zwei geschweifte Klammern unmittelbar aufeinanderfolgen, weil das Template sonst nicht korrekt verarbeitet werden kann. Fügen Sie zwischen den Klammern einfach ein Leerzeichen oder einen Zeilenumbruch ein.

Funktionsnamen und Parameter

Ein VirthosTalk-Element besteht mindestens aus einem Funktionsnamen. Dieser wird manchmal durch zusätzliche Angaben, die sogenannten "Parameter" ergänzt. Um deutlich zu machen, wo der Funktionsname endet und die Parameter beginnen, wird ein Doppelpunkt gesetzt:

{{Funktionsname: Parameter}}

Handelt es sich um mehr als einen Parameter, werden diese durch Komma voneinander getrennt:

{{Funktionsname: Parameter1, Parameter2, Parameter3 }}

Wenn eine Funktion viele mögliche Parameter besitzt, lassen sich diese der Einfachheit halber mit eindeutigen Namen versehen:

{{Funktionsname: Name1 = "Wert1", Name2 = "Wert2", Name3 = "Wert3" }}

Der Wert eines Parameters kann wahlweise in einfache oder doppelte Anführungszeichen eingeschlossen werden; innerhalb eines Elements dürfen Sie aber nicht beide Schreibweisen mischen. Wenn die Parameter benannt sind, spielt es keine Rolle, in welcher Reihenfolge sie stehen.

Platzhalter innerhalb von Parametern

Viele VirthosTalk-Funktionen erlauben es, den Wert eines Parameters durch einen oder mehrere Platzhalter anzugeben oder durch eine Mischung von Platzhaltern und festen Werten. Bei einer solchen Verschachtelung werden die inneren Platzhalter nur mit einfach geschweiften Klammern geschrieben:

{{Funktionsname: {Platzhaltername} }}

oder, wenn es sich um einen benannten Parameter handelt:

{{Funktionsname: Name1 = "{Platzhaltername}" }}

Wird ein unbenannter Parameter durch einen Platzhalter angegeben, sollte hinter ihm wie im obigen Beispiel ein Leerzeichen eingefügt werden, damit nicht drei schließende Klammern aufeinanderfolgen.

Beachten Sie, dass VirthosTalk keine Mehrfach-Verschachtelung erlaubt. Sie können also nicht innerhalb eines Platzhalters, der in einfach geschweifte Klammern eingeschlossen ist, abermals einen Platzhalter als Parameter verwenden:

FALSCH: {{Funktionsname: Name1 = "{Platzhalter1: {Platzhalter2} }" }}

Das gewünschte Ergebnis lässt sich aber mit Hilfe von vtCapture und vtResult erreichen:

{{vtCapture}}{{Platzhalter1: {Platzhalter2} }}{{vtEndCapture}}   
{{Funktionsname: Name1="{vtResult}"}}

Ausgabefilter

Viele VirthosTalk-Platzhalter erlauben es, einen sogenannten Ausgabefilter zu verwenden, um den ausgegebenen Wert zu verändern. Der Ausgabefilter wird vor der schließenden Klammer durch ein Pipesymbol (|) angegeben:

{{Funktionsname: Parameter | Ausgabefilter }}

Falls keine Parameter existieren, wird der Ausgabefilter unmittelbar nach dem Funktionsnamen eingefügt. Der Doppelpunkt entfällt in diesem Fall:

{{Funktionsname | Ausgabefilter }}

Manche Filter lassen sich durch einen Zusatz in ihrem Verhalten beeinflussen. Ein solcher Zusatz wird durch einen Doppelpunkt vom Filternamen abgetrennt:

{{Funktionsname | Ausgabefilter: Zusatz }}

Welche Platzhalter die Ausgabefilterung unterstützen, welche Filter zur Verfügung stehen und was sie im Einzelnen bewirken ist im Artikel Ausgabefilter beschrieben.

Codeblöcke

Manche VirthosTalk-Funktionen bestehen aus zwei Anweisungen, die einen Codeblock einschließen. Der Name der zweiten Anweisung entspricht in solchen Fällen dem der ersten, nur dass er mit vtEnd statt mit vt beginnt, zum Beispiel

<!--{{vtUse: / }}--> ... <!--{{vtEndUse}}-->

Wenn Sie die zweite Anweisung vergessen oder den Namen falsch schreiben, führt dies bei der Verarbeitung des Templates oft zu einem PHP-Parse-Error oder dazu, dass lediglich eine leere Seite im Webbrowser angezeigt wird. Das gleiche gilt, wenn Sie Blockanweisungen falsch verschachteln, das heißt, wenn Sie zum Beispiel erst den äußeren und dann den inneren Block beenden.

Einbindung von PHP-Code

Virthos Master erlaubt es, neben VirthosTalk-Funktionen auch eigenen PHP-Code in ein Template einzubinden. Dies geschieht mit derselben Schreibweise, mit der PHP-Code auch in gewöhnliche HTML-Dateien eingebunden wird:

... <?php ... ?> ...

Bitte beachten Sie, dass die Kurzschreibweise mit <? ... ?> innerhalb eines Virthos-Templates nicht zulässig ist, unabhängig davon, wie die PHP-Umgebung auf dem Server konfiguriert wurde.

Innerhalb Ihres PHP-Codes müssen Sie zwei Dinge beachten:

Erstens dürfen nicht zwei öffnende oder zwei schließende geschweifte Klammern unmittelbar aufeinanderfolgen (das heißt, VirthosTalk-Platzhalter und -Anweisungen sind innerhalb des PHP-Codes unzulässig). Wenn die Klammern den Anfang oder das Ende eines Codeblocks markieren, können Sie einfach ein Leerzeichen oder einen Zeilenumbruch dazwischen einfügen. Falls die Klammern innerhalb einer String-Konstanten vorkommen, können Sie diese in zwei verkettete Konstanten zerlegen:

$var = 'VirthosTalk-Funktionen beginnen mit "{{"';      // führt zu einem Fehler
$var = 'VirthosTalk-Funktionen beginnen mit "{' . '{"'; // funktioniert fehlerfrei

Zweitens müssen relative Dateipfade mit ./ oder ../ beginnen. Andernfalls würde die automatische Pfadersetzung angewendet, mit der Virthos alle Ressourcenpfade durch absolute HTTP-URLs ersetzt.

Neben vollständigen PHP-Codeblöcken können Sie mittels vtCalc und vtEcho auch einfache PHP-Ausdrücke in Ihre Templates einbinden. Dies ist oft übersichtlicher und funktioniert auch in Virthos Basic und Pro. Außerdem können Sie VirthosTalk-Platzhalter in die PHP-Ausdrücken einbinden. Wenn Sie komplexere PHP-Funktionen nutzen wollen, empfiehlt es sich, diese in eigene Dateien auszulagern und bei Bedarf mittels vtLoad in das aktuelle Template zu laden.