Zum Hauptinhalt springen
WEBSALE-Templates kennen keine Variablen im Sinne einer Programmiersprache. Was es stattdessen gibt, sind die freien DesignControl-Parameter: benannte Ablagefächer, in die Sie einen beliebigen Wert legen, um ihn später wieder auszugeben oder darauf zu klammern. Davon gibt es zwei Sorten, die sich in genau einem Punkt unterscheiden. Alles andere ist identisch. Beide verstehen dieselben Zusätze, beide werden gleich geschrieben, beide verhalten sich gleich. Diese Seite beschreibt deshalb beide zusammen und schreibt DC-FPX dort, wo DC-SPX genauso gilt. Das X im Tag-Namen ist ein Platzhalter, den Sie selbst füllen. DC-FP1, DC-FPfarbe und DC-FPmeinWert sind drei verschiedene Parameter. Ziffern, Buchstaben und Kombinationen daraus sind erlaubt, höchstens 20 Zeichen lang.

Das Muster in drei Schritten

Ein freier Parameter wird gesetzt, benutzt und wieder freigegeben.
Ein Parameter gilt erst ab der Stelle, an der er gesetzt wird. Eine Klammerung weiter oben im Quelltext sieht den Wert nicht. Das ist der häufigste Grund dafür, dass eine Abfrage “nicht funktioniert”.
Der Vergleich in den Klammern achtet nicht auf Groß- und Kleinschreibung. {DC-FP1(Blau)} greift auch bei den Werten blau und BLAU. Dasselbe gilt für den Tag-Namen selbst und für alle Zusätze: ~DC-FP1_HexEncode~ und ~DC-FP1_hexencode~ sind dasselbe Tag.

Klammern ohne Parameter heißt “ist gefüllt”

Lassen Sie die Klammern leer, prüft das Tag nur, ob überhaupt ein Wert gesetzt ist.
Das ist der übliche Weg, mehrere Bedingungen zu einem Schalter zusammenzufassen: An mehreren Stellen dasselbe Tag setzen, danach einmal darauf klammern.

Das vollständige Beispiel

Eine Nährwerttabelle soll nur dann erscheinen, wenn mindestens eines von vier selbstdefinierten Produktdatenfeldern gefüllt ist. Die Abfrage muss den ganzen Block umschließen, der Schalter wird deshalb vorher gesetzt.

FP oder SP

Nehmen Sie DC-FP, solange der Wert die Seite nicht verlässt. Das ist der Normalfall. DC-SP brauchen Sie, wenn der Wert auf einer Folgeseite noch da sein muss, beispielsweise eine Auswahl, die der Käufer auf der Produktseite trifft und die im Warenkorb noch gelten soll.
Der Unterschied kehrt sich beim Zurücksetzen um. Ein DC-FP verschwindet mit dem Template von selbst, ein zweites Template beginnt wieder mit leerem Fach. Ein DC-SP bleibt die ganze Session über gesetzt. Wollen Sie ihm auf einer anderen Seite einen neuen Wert geben, müssen Sie ihn dort erst mit ~DC-SPX_reset~ leeren.
Für die Anzahl der DC-SP-Parameter gibt es eine konfigurierbare Obergrenze. Wird sie überschritten, legt der Shop keinen weiteren Parameter mehr an, schreibt einen kritischen Fehler ins Protokoll und das Tag bleibt wirkungslos. Für DC-FP gilt diese Grenze nicht.

Die Ausgabe ist HTML-codiert

Jeder freie Parameter wird bei der Ausgabe HTML-codiert. Setzen Sie ~DC-FP1_set(&)~, erscheint in der Seite &.
Bei Domains, URLs und allem, was in ein href-Attribut oder in JavaScript soll, führt das zu Überraschungen. Der Schutz ist gewollt: Er verhindert, dass fremde Eingaben als HTML ausgeführt werden.
Nur wenn Sie den Wert wirklich unverändert brauchen und selbst sicherstellen, dass er unbedenklich ist, heben Sie die Codierung für genau eine Ausgabe auf.
Referenz: WS-DisableXSSProtectionOnce

Werte aus anderen Tags übernehmen

DC-FPX_set() nimmt nicht nur festen Text, sondern auch das Ergebnis eines anderen Einzel-Tags. Dafür ersetzen Sie dessen Tilden durch Dollarzeichen.
Auch der Name des Parameters darf aus einem Tag kommen.
Ein so gebildeter Name lässt sich nicht auf demselben Weg wieder auslesen. ~DC-SPvar_set($DC-FP$WS-OTP1$$)~ funktioniert nicht, weil die verschachtelten Dollarzeichen nicht auflösbar sind. Dafür gibt es die vier Touched-Tags weiter unten.

Die Zusätze

Alle Zusätze arbeiten auf dem Wert, der gerade im Parameter liegt. Entscheidend ist dabei, ob ein Zusatz den gespeicherten Wert verändert oder ihn nur in veränderter Form ausgibt. Diese Unterscheidung erspart die meisten Fehlersuchen. ~DC-FP1_touppercase~ gibt nichts aus, sondern macht den gespeicherten Wert groß. Erst das nachfolgende ~DC-FP1~ zeigt ihn an. Umgekehrt lässt ~DC-FP1_base64encoding~ den Wert unangetastet und gibt nur die codierte Fassung aus.

Den Wert verändern

_set()

Legt den Wert ab. Ein vorhandener Wert wird ersetzt.

_reset

Leert das Fach. Danach kann derselbe Parameter neu gesetzt werden.
_reset wird ohne Klammern geschrieben.

_append()

Hängt an den vorhandenen Wert an. Das ist der Weg um die 128-Zeichen-Grenze herum, die für jedes WEBSALE-Tag gilt.
Wird ein Tag länger als 128 Zeichen, verarbeitet der Shop es nicht mehr, sondern gibt den Tag-Namen im Klartext aus. Eine lange Liste gehört deshalb stückweise in einen Parameter und von dort als Tag-in-Tag in das eigentliche Tag.

_replace()

Sucht und ersetzt. Zwei kommagetrennte Argumente: erst die gesuchte Zeichenkette, dann ihr Ersatz. Bleibt das zweite Argument leer, wird gelöscht.
Sonderzeichen, die der Parser selbst benutzt, gehören in Anführungszeichen.
Das Komma trennt die beiden Argumente. Ein Komma, das gesucht oder eingesetzt werden soll, muss deshalb in Anführungszeichen stehen, sonst liest der Shop drei Argumente und verwirft das Tag.

_slice()

Schneidet einen Ausschnitt heraus. Gezählt wird ab 0, die erste Zahl gehört dazu, die zweite nicht mehr. Fehlt die zweite Zahl, geht der Schnitt bis zum Ende.
Beide Argumente sind Tag-in-Tag-fähig.

_truncate()

Kürzt nach der angegebenen Zeichenzahl.

_extractTaggedData()

Schneidet heraus, was zwischen zwei Markierungen steht. Beide Argumente sind Tag-in-Tag-fähig.

_convertToEncoding()

Wandelt den Zeichensatz. Erst der Ausgangs-, dann der Zielzeichensatz. Nützlich, wenn Daten an ein Fremdsystem gehen, das einen anderen Zeichensatz erwartet.

_touppercase und _tolowercase

Wandeln den gespeicherten Wert in Groß- beziehungsweise Kleinbuchstaben. Beide geben selbst nichts aus.

Den Wert ausgeben

_length

Gibt die Zeichenzahl aus.

_IndexOf() und _RIndexOf()

Geben die Position einer Zeichenkette aus, _IndexOf() die des ersten, _RIndexOf() die des letzten Vorkommens. Gezählt wird ab 0, nicht gefunden ergibt -1.
Beide lassen sich auch klammern. Der positive Bereich erscheint, wenn die Zeichenkette gefunden wurde.

Codierungen

Sieben Zusätze geben den Wert in einer anderen Codierung aus, ohne ihn zu verändern.

_linknameencoding

Gibt den Wert nach den Regeln aus, die Sie im Abschnitt <LinkNameEncoding> der Shopkonfiguration shop.config für den sprechenden Teil Ihrer URLs festgelegt haben.
Referenz: Abschnitt <[LinkNameEncoding](/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/grundlagen-und-technik#linknameencoding)>

_encodeISO2HTML

Gibt alle Zeichen außerhalb von ASCII als dezimale HTML-Entität aus.

_StripHTML

Gibt den Wert ohne HTML-Auszeichnung und ohne Anführungszeichen aus. Gedacht für Felder, die reinen Text verlangen, beispielsweise eine Meta-Beschreibung.
Der gespeicherte Wert bleibt dabei unverändert. Ein späteres ~DC-FPbeschreibung~ gibt wieder die Fassung mit HTML aus.

_encrypt() und _hash()

Geben den Wert verschlüsselt beziehungsweise als Prüfsumme aus, damit er gesichert an ein Fremdsystem übergeben werden kann. Der gespeicherte Wert bleibt unverändert. _encrypt() erwartet zwei Argumente, optional ein drittes.
_hash() erwartet drei Argumente, optional ein viertes.
Gehasht wird der Inhalt des Parameters mit angehängtem Geheimnis aus der Konfiguration. Das Ergebnis wird codiert und ausgegeben.
Ohne dritten Parameter greift _encrypt() auf DCFPXEncryptBlowfishPW aus dem Abschnitt <Basic> zurück. Dieser Eintrag ist veraltet. Legen Sie neue Verschlüsselungen immer mit einer eigenen ID im Abschnitt <DesignControl> an.
Referenz: Abschnitt <[DesignControl](/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/grundlagen-und-technik#designcontrol)>

Prüfen

_contains()

Greift, wenn die angegebene Zeichenkette irgendwo im Wert vorkommt. Anders als DC-CompareStringInList() wird kein vollständiger Treffer verlangt. Groß- und Kleinschreibung spielt keine Rolle.
Damit lässt sich eine Kategoriegruppe über ihren Namen ansprechen, statt Kategorie-Indizes von Hand zu pflegen. Kommt eine neue Hemden-Kategorie dazu, greift die Klammerung ohne Änderung am Template.

_verifyChecksum()

Prüft die Prüfsumme einer Rechnungs- oder Adressnummer der Warenwirtschaft von D&G. Das Argument ist DuG-AdrNr oder DuG-ReNr.
Geprüft wird nur die Prüfziffer, nicht die Existenz des Vorgangs. Das Tag ersetzt keine Anmeldung und keine Berechtigungsprüfung.
Wegweiser: Bestelldetails anzeigen ohne Login

Namen und Werte weiterreichen

Ein Parameter, dessen Name selbst aus einem Tag stammt, lässt sich nicht direkt auslesen. Dafür gibt es _touch und die drei zugehörigen Abruf-Tags: _touch merkt sich Name und Wert des zuletzt angesprochenen Parameters, danach holen Sie beides einzeln ab.
Zwei weitere Tags halten das jüngste Suchergebnis fest.
Die vier Tags gibt es für beide Sorten getrennt: DC-FP_lastKeyTouched und DC-SP_lastKeyTouched führen eigene Merker. Ein _touch auf einem DC-FP verändert den Merker der DC-SP-Seite nicht.

Grenzen

Wird die Obergrenze für DC-SP-Parameter erreicht, legt der Shop keinen weiteren an. Das Tag bleibt dann wirkungslos, und im Protokoll steht ein kritischer Fehler mit der erreichten Anzahl. Fällt eine Auswahl auf Folgeseiten plötzlich weg, lohnt der Blick ins Protokoll.

Tags anderer Präfixe

Die Tags im Überblick

Die Tabelle gilt für DC-FPX und DC-SPX gleichermaßen. Zulässig sind alle Tags auf allen Templates. Für DC-SP gibt es dieselben Zusätze wie für DC-FP: _jsonencoding, _length, _tolowercase, _touppercase, _urldecoding und _verifyChecksum. Im Shop verarbeitet dieselbe Programmstelle beide Präfixe, alle Zusätze stehen deshalb für DC-SP genauso zur Verfügung.

Verwandte Themen