> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # DC- (free parameters and session parameters) > The template's free variables: store a value, bracket on it, and trim, convert, encode or sign it along the way. WEBSALE templates have no variables in the sense of a programming language. What they have instead are the free DesignControl parameters: named slots into which you put any value so you can output it later or bracket on it. There are two kinds, and they differ in exactly one respect. | Prefix | Lifetime | Used for | | - | - | - | | `DC-FP` | the template on which the value is set | intermediate results within one page | | `DC-SP` | the entire session | values still needed on subsequent pages | Everything else is identical. Both understand the same suffixes, both are written the same way, both behave the same way. This page therefore describes both together and writes `DC-FPX` wherever `DC-SPX` applies equally. > [!NOTE] > > The `X` in the tag name is a placeholder that you fill in yourself. `DC-FP1`, `DC-FPfarbe` and `DC-FPmeinWert` are three different parameters. Digits, letters and combinations of both are allowed, up to 20 characters long. ## The pattern in three steps A free parameter is set, used and released again. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_reset~ ~DC-FP1_set(Blau)~ ~DC-FP1~ {DC-FP1(Blau)} Dieser Bereich erscheint, weil der Wert "Blau" ist. {/DC-FP1(Blau)} {!DC-FP1(Blau)} Dieser Bereich erscheint bei jedem anderen Wert. {/!DC-FP1(Blau)} ``` > [!WARNING] > > A parameter only applies from the point at which it is set. A bracket further up in the source code does not see the value. This is the most common reason why a query "doesn't work". > [!NOTE] > > The comparison in the brackets is case-insensitive. `{DC-FP1(Blau)}` also applies to the values `blau` and `BLAU`. The same goes for the tag name itself and for all suffixes: `~DC-FP1_HexEncode~` and `~DC-FP1_hexencode~` are the same tag. ### Brackets without a parameter mean "is filled" If you leave the brackets empty, the tag only checks whether any value is set at all. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FPnaehrwerte_set($PR-Brennwert$)~ {DC-FPnaehrwerte} {/DC-FPnaehrwerte} ``` > [!NOTE] > > This is the usual way to combine several conditions into one switch: set the same tag in several places, then bracket on it once. ## The complete example A nutrition table should only appear if at least one of four custom product data fields is filled. The query has to enclose the entire block, so the switch is set beforehand. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FPnaehrwerte_reset~ {PR-Brennwert}~DC-FPnaehrwerte_set(ja)~{/PR-Brennwert} {PR-Fett}~DC-FPnaehrwerte_set(ja)~{/PR-Fett} {PR-Kohlenhydrate}~DC-FPnaehrwerte_set(ja)~{/PR-Kohlenhydrate} {PR-Eiweiss}~DC-FPnaehrwerte_set(ja)~{/PR-Eiweiss} {DC-FPnaehrwerte(ja)}

Nährwertangaben je 100 g

{PR-Brennwert} {/PR-Brennwert} {PR-Fett} {/PR-Fett} {PR-Kohlenhydrate} {/PR-Kohlenhydrate} {PR-Eiweiss} {/PR-Eiweiss}
Brennwert in kcal~PR-Brennwert~
Fett~PR-Fett~
Kohlenhydrate~PR-Kohlenhydrate~
Eiweiß~PR-Eiweiss~
{/DC-FPnaehrwerte(ja)} ``` ## FP or SP Use `DC-FP` as long as the value does not leave the page. That is the normal case. You need `DC-SP` when the value must still be there on a subsequent page, for example a selection the buyer makes on the product page that should still apply in the basket. > [!WARNING] > > The difference is reversed when resetting. A `DC-FP` disappears with the template on its own; a second template starts again with an empty slot. A `DC-SP` stays set for the whole session. If you want to give it a new value on another page, you must first clear it there with `~DC-SPX_reset~`. > [!NOTE] > > There is a configurable upper limit for the number of `DC-SP` parameters. If it is exceeded, the shop no longer creates further parameters, writes a critical error to the log, and the tag has no effect. This limit does not apply to `DC-FP`. ## The output is HTML-encoded Every free parameter is HTML-encoded on output. If you set `~DC-FP1_set(&)~`, `&` appears on the page. > [!WARNING] > > With domains, URLs and anything that goes into an `href` attribute or into JavaScript, this leads to surprises. The protection is intentional: it prevents third-party input from being executed as HTML. Only if you really need the value unchanged and have made sure yourself that it is harmless should you lift the encoding for exactly one output. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~WS-DisableXSSProtectionOnce~~DC-FP1~ ``` Reference: WS-DisableXSSProtectionOnce ## Taking values from other tags `DC-FPX_set()` accepts not only fixed text but also the result of another single tag. To do this, replace its tildes with dollar signs. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP2_set($PR-Name$)~ ~DC-FP2~ ``` The name of the parameter can also come from a tag. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP$WS-OTP1$_set(wert)~ ``` > [!WARNING] > > A name formed this way cannot be read back the same way. `~DC-SPvar_set($DC-FP$WS-OTP1$$)~` does not work because the nested dollar signs cannot be resolved. The four touched tags further below exist for this purpose. ## The suffixes All suffixes work on the value currently stored in the parameter. What matters is whether a suffix **changes** the stored value or only **outputs** it in modified form. | Behavior | Suffixes | | - | - | | change the stored value | `_set()`, `_reset`, `_append()`, `_replace()`, `_slice()`, `_truncate()`, `_extractTaggedData()`, `_convertToEncoding()`, `_touppercase`, `_tolowercase` | | output without changing the value | `_length`, `_IndexOf()`, `_RIndexOf()`, `_urlencoding`, `_urldecoding`, `_base64encoding`, `_base64decoding`, `_HexEncode`, `_HexDecode`, `_jsonencoding`, `_linknameencoding`, `_encodeISO2HTML`, `_StripHTML`, `_encrypt()`, `_hash()` | | check or remember | `_contains()`, `_verifyChecksum()`, `_touch` | > [!NOTE] > > This distinction saves most debugging. `~DC-FP1_touppercase~` outputs nothing but converts the stored value to uppercase. Only the subsequent `~DC-FP1~` displays it. Conversely, `~DC-FP1_base64encoding~` leaves the value untouched and only outputs the encoded version. ### Changing the value #### \_set() Stores the value. An existing value is replaced. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(Blau)~ ~DC-FP2_set($PR-Name$)~ ``` #### \_reset Clears the slot. Afterwards, the same parameter can be set again. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(Blau)~ ~DC-FP1~ ~DC-FP1_reset~ ~DC-FP1_set(Rot)~ ~DC-FP1~ ``` > [!NOTE] > > `_reset` is written without brackets. The older notation `DC-FPX_reset()` can still be found in cross-references in the previous documentation. #### \_append() Appends to the existing value. This is the way around the 128-character limit that applies to every WEBSALE tag. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_reset~ ~DC-FP1_append(IPPME14135_DEAA,IPPME14135_DENA,)~ ~DC-FP1_append(IPPME14135_EUAA,IPPME14135_EUNA,)~ ~DC-FP1_append(IPPME14135_CHAA,IPPME14135_CHNA)~ {DC-CompareStringInList($BASKET-PR-Number$,"$DC-FP1$")} Sonderhinweis für diese Artikelnummern {/DC-CompareStringInList($BASKET-PR-Number$,"$DC-FP1$")} ``` > [!WARNING] > > If a tag is longer than 128 characters, the shop no longer processes it but outputs the tag name as plain text. A long list therefore belongs piece by piece in a parameter and from there, as tag-in-tag, in the actual tag. #### \_replace() Searches and replaces. Two comma-separated arguments: first the string to search for, then its replacement. If the second argument is empty, the string is deleted. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(wort1 wort2 wort3 wort1)~ ~DC-FP1_replace(wort2,wort5)~ ~DC-FP1~ ~DC-FP2_set(wort1 wort2 wort3 wort1)~ ~DC-FP2_replace(wort1,)~ ~DC-FP2~ ``` Special characters that the parser itself uses belong in quotation marks. | Task | Notation | | - | - | | replace comma with period | `~DC-FP1_replace(",",.)~` | | double quotes with single quotes | `~DC-FP1_replace("""," ' ")~` | | transcribe umlaut | `~DC-FP1_replace(ä,ae)~` | > [!WARNING] > > The comma separates the two arguments. A comma that is to be searched for or inserted must therefore be in quotation marks; otherwise, the shop reads three arguments and discards the tag. #### \_slice() Cuts out a section. Counting starts at 0; the first number is included, the second is not. If the second number is missing, the cut goes to the end. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(SCHALTER)~ ~DC-FP1_slice(2,6)~ ~DC-FP2_set(SCHALTER)~ ~DC-FP2_slice(3)~ ``` Both arguments support tag-in-tag. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FPvon_set(0)~ ~DC-FPbis_set(5)~ ~DC-FP1_slice($DC-FPvon$,$DC-FPbis$)~ ``` #### \_truncate() Truncates after the specified number of characters. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(abcdefg)~ ~DC-FP1_truncate(3)~ ~DC-FP1~ ``` #### \_extractTaggedData() Cuts out what is between two markers. Both arguments support tag-in-tag. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(Inhalt AInhalt B)~ ~DC-FP1_extractTaggedData(,)~ ~DC-FP1~ ``` #### \_convertToEncoding() Converts the character set. First the source, then the target character set. Useful when data goes to an external system that expects a different character set. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set($A-FirstName$)~ ~DC-FP1~ ~DC-FP1_urlencoding~ ~DC-FP1_convertToEncoding($WS-Charset$,UTF-8)~ ~DC-FP1~ ~DC-FP1_urlencoding~ ``` #### \_touppercase and \_tolowercase Convert the stored value to uppercase or lowercase letters. Neither outputs anything itself. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(Blau)~ ~DC-FP1_touppercase~ ~DC-FP1~ ``` ### Outputting the value #### \_length Outputs the number of characters. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(abcdefg)~ ~DC-FP1_length~ ``` #### \_IndexOf() and \_RIndexOf() Output the position of a string: `_IndexOf()` that of the first occurrence, `_RIndexOf()` that of the last. Counting starts at 0; not found results in -1. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(sometext)~ ~DC-FP1_IndexOf(t)~ ~DC-FP1_RIndexOf(t)~ ~DC-FP1_IndexOf(z)~ ``` Both can also be used as brackets. The positive area appears if the string was found. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {!DC-FP1_IndexOf(y)} Kein y enthalten. {/!DC-FP1_IndexOf(y)} ``` #### Encodings Seven suffixes output the value in a different encoding without changing it. | Suffix | Output | | - | - | | `_urlencoding` | for use as a value in a URL | | `_urldecoding` | URL encoding resolved again | | `_base64encoding` | Base64 | | `_base64decoding` | Base64 resolved again | | `_HexEncode` | hexadecimal | | `_HexDecode` | hexadecimal resolved again | | `_jsonencoding` | converted to UTF-8 and safely encoded as a JSON string | ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set($A-Street1$)~ Zum Retourenformular ``` ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set($BASKET-PR-Name$)~ "Name": "~DC-FP1_jsonencoding~" ``` #### \_linknameencoding Outputs the value according to the rules you have defined in the `` section of the shop configuration `shop.config` for the readable part of your URLs. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set($CAT-RobotName$)~ ~URL-Homepage~/~DC-FP1_linknameencoding~?websale8=~WS-ShopID~.~WS-SubShopID~&ci=~CAT-Index~ ``` Reference: `` section #### \_encodeISO2HTML Outputs all characters outside ASCII as decimal HTML entities. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(testü)~ ~DC-FP1_encodeISO2HTML~ ``` #### \_StripHTML Outputs the value without HTML markup and without quotation marks. Intended for fields that require plain text, for example a meta description. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FPbeschreibung_set($PR-Description$)~ ``` > [!NOTE] > > The stored value remains unchanged. A later `~DC-FPbeschreibung~` outputs the version with HTML again. #### \_encrypt() and \_hash() Output the value encrypted or as a checksum so that it can be passed securely to an external system. The stored value remains unchanged. `_encrypt()` expects two arguments, optionally a third. | Argument | Values | | - | - | | Method | `blowfish` | | Output encoding | `b64` or `hex` | | ID of the configuration entry (optional) | an entry from the `` section of `shop.config` | ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_encrypt(blowfish,hex)~ ~DC-FP1_encrypt(blowfish,b64,meinPartner)~ ``` `_hash()` expects three arguments, optionally a fourth. | Argument | Values | | - | - | | Algorithm | `SHA256` or `SHA512` | | Output encoding | `b64` or `hex` | | ID of the configuration entry | an entry from the `` section of `shop.config` | | Length (optional) | truncates the output after this many characters | ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP2_hash(sha256,hex,uploadlink,16)~ ``` > [!NOTE] > > The content of the parameter is hashed with the secret from the configuration appended. The result is encoded and output. > [!WARNING] > > Without a third parameter, `_encrypt()` falls back on `DCFPXEncryptBlowfishPW` from the `` section. This entry is deprecated. Always create new encryptions with a dedicated ID in the `` section. Reference: `` section ### Checking #### \_contains() Applies if the specified string occurs anywhere in the value. Unlike `DC-CompareStringInList()`, no complete match is required. Case does not matter. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP5_set($CAT-Name$)~ {DC-FP5_contains(hemd)} {/DC-FP5_contains(hemd)} {!DC-FP5_contains(hemd)} {/!DC-FP5_contains(hemd)} ``` > [!NOTE] > > This lets you address a group of categories by their name instead of maintaining category indexes by hand. If a new shirt category is added, the bracket applies without any change to the template. #### \_verifyChecksum() Checks the checksum of an invoice or address number from the D\&G merchandise management system. The argument is `DuG-AdrNr` or `DuG-ReNr`. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FPorderNumber_set($WS-OTPorder$)~ ~DC-FPuserNumber_set($WS-OTPnumber$)~ {DC-FPorderNumber_verifyChecksum(DuG-ReNr)} {DC-FPuserNumber_verifyChecksum(DuG-AdrNr)} {/DC-FPuserNumber_verifyChecksum(DuG-AdrNr)} {/DC-FPorderNumber_verifyChecksum(DuG-ReNr)} ``` > [!WARNING] > > Only the check digit is verified, not whether the transaction exists. The tag does not replace a sign-in or an authorization check. Guide: Displaying order details without sign-in ## Passing on names and values A parameter whose name itself comes from a tag cannot be read directly. For this purpose, there is `_touch` and the three associated retrieval tags: `_touch` remembers the name and value of the most recently addressed parameter, and afterwards you retrieve both individually. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP$WS-OTP1$_set(wert)~ ~DC-FP$WS-OTP1$_touch~ ~DC-SPkey_set($DC-FP_lastKeyTouched$)~ ~DC-SPval_set($DC-FP_lastValueTouched$)~ ``` Two further tags hold the most recent search result. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ~DC-FP1_set(randomtext)~ ~DC-FP1_IndexOf(r)~ ~DC-FP1_IndexOf(n)~ ~DC-FP_lastIndexOfTouched~ ``` | Tag | Returns | | - | - | | `DC-FP_lastKeyTouched` | the name of the most recently touched parameter | | `DC-FP_lastValueTouched` | its value | | `DC-FP_lastIndexOfTouched` | the last result of `_IndexOf()` | | `DC-FP_lastRIndexOfTouched` | the last result of `_RIndexOf()` | > [!NOTE] > > The four tags exist separately for both kinds: `DC-FP_lastKeyTouched` and `DC-SP_lastKeyTouched` keep their own memory. A `_touch` on a `DC-FP` does not change the memory on the `DC-SP` side. ## Limits | Limit | Value | | - | - | | Length of the tag name | 20 characters | | Length of a WEBSALE tag in the source code | 128 characters, can be worked around with `_append()` | | Number of `DC-SP` parameters | configurable in the shop configuration | > [!WARNING] > > When the upper limit for `DC-SP` parameters is reached, the shop does not create any more. The tag then has no effect, and the log contains a critical error with the number reached. If a selection suddenly disappears on subsequent pages, check the log. ## Tags with other prefixes | Tag | Purpose | Prefix | | - | - | - | | `WS-DisableXSSProtectionOnce` | lifts the HTML encoding for the next output | WS- | | `WS-F…` | free parameters passed to the shop call as URL parameters | WS- | | `WS-OTP1…` | one-time parameters from the called address | WS- | | `DC-CompareStringInList()` | compares a value with a list of complete matches | DC- | ## The tags at a glance The table applies equally to `DC-FPX` and `DC-SPX`. | Tag | Single tag | Area tag | Negative area tag | Loop tag | | - | - | - | - | - | | `DC-FPX` | yes | yes | yes | – | | `DC-FPX_set()` | yes | – | – | – | | `DC-FPX_reset` | yes | – | – | – | | `DC-FPX_append()` | yes | – | – | – | | `DC-FPX_touch` | yes | – | – | – | | `DC-FPX_replace()` | yes | – | – | – | | `DC-FPX_slice()` | yes | – | – | – | | `DC-FPX_truncate()` | yes | – | – | – | | `DC-FPX_extractTaggedData()` | yes | – | – | – | | `DC-FPX_convertToEncoding()` | yes | – | – | – | | `DC-FPX_touppercase` | yes | – | – | – | | `DC-FPX_tolowercase` | yes | – | – | – | | `DC-FPX_length` | yes | – | – | – | | `DC-FPX_IndexOf()` | yes | yes | yes | – | | `DC-FPX_RIndexOf()` | yes | yes | yes | – | | `DC-FPX_urlencoding` | yes | – | – | – | | `DC-FPX_urldecoding` | yes | – | – | – | | `DC-FPX_base64encoding` | yes | – | – | – | | `DC-FPX_base64decoding` | yes | – | – | – | | `DC-FPX_HexEncode` | yes | – | – | – | | `DC-FPX_HexDecode` | yes | – | – | – | | `DC-FPX_jsonencoding` | yes | – | – | – | | `DC-FPX_linknameencoding` | yes | – | – | – | | `DC-FPX_encodeISO2HTML` | yes | – | – | – | | `DC-FPX_StripHTML` | yes | – | – | – | | `DC-FPX_encrypt()` | yes | – | – | – | | `DC-FPX_hash()` | yes | – | – | – | | `DC-FPX_contains()` | – | yes | yes | – | | `DC-FPX_verifyChecksum()` | – | yes | yes | – | | `DC-FP_lastKeyTouched` | yes | yes | yes | – | | `DC-FP_lastValueTouched` | yes | yes | yes | – | | `DC-FP_lastIndexOfTouched` | yes | yes | yes | – | | `DC-FP_lastRIndexOfTouched` | yes | yes | yes | – | All tags are permitted on all templates. > [!NOTE] > > The previous documentation does not list six suffixes for `DC-SP` that exist for `DC-FP`: `_jsonencoding`, `_length`, `_tolowercase`, `_touppercase`, `_urldecoding` and `_verifyChecksum`. In the shop, the same code processes both prefixes, so all suffixes are equally available for `DC-SP`. ## Related topics * Guide: Using free parameters * Reference: DC- (counters and calculations) * Reference: DC- (loops) * Reference: DC- (comparisons and other tags) * Basics: Tag basics ## Related topics - [DC- (date and time)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/datum-und-zeit.md) - [DC- (cookie data)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/cookie-daten.md) - [DC- (comparisons and other tags)](https://dokumentation.websale.de/en/v8s/referenz/tags/dc/vergleiche.md) - [EJD- (JSON interface)](https://dokumentation.websale.de/en/v8s/referenz/tags/ejd.md) - [Using free parameter tags](https://dokumentation.websale.de/en/v8s/fortgeschrittene-designtechniken/freie-parameter-tags-verwenden.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.