DC- (free parameters and session parameters)

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.

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.

~DC-FP1_reset~                <!-- Fach leeren, falls oben schon belegt -->
~DC-FP1_set(Blau)~            <!-- Wert hineinlegen -->
~DC-FP1~                      <!-- Wert ausgeben: Blau -->

{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)}

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”.

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.

~DC-FPnaehrwerte_set($PR-Brennwert$)~

{DC-FPnaehrwerte}
   <!-- erscheint, sobald irgendein nicht leerer Wert gesetzt ist -->
{/DC-FPnaehrwerte}

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.

~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)}
   <h2>Nährwertangaben je 100 g</h2>
   <table>
      {PR-Brennwert}
      <tr><td>Brennwert in kcal</td><td>~PR-Brennwert~</td></tr>
      {/PR-Brennwert}
      {PR-Fett}
      <tr><td>Fett</td><td>~PR-Fett~</td></tr>
      {/PR-Fett}
      {PR-Kohlenhydrate}
      <tr><td>Kohlenhydrate</td><td>~PR-Kohlenhydrate~</td></tr>
      {/PR-Kohlenhydrate}
      {PR-Eiweiss}
      <tr><td>Eiweiß</td><td>~PR-Eiweiss~</td></tr>
      {/PR-Eiweiss}
   </table>
{/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.

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~.

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.

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.

~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.

~DC-FP2_set($PR-Name$)~
~DC-FP2~

The name of the parameter can also come from a tag.

~DC-FP$WS-OTP1$_set(wert)~

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`

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.

~DC-FP1_set(Blau)~
~DC-FP2_set($PR-Name$)~

_reset

Clears the slot. Afterwards, the same parameter can be set again.

~DC-FP1_set(Blau)~
~DC-FP1~            <!-- Blau -->
~DC-FP1_reset~
~DC-FP1_set(Rot)~
~DC-FP1~            <!-- Rot -->

_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.

~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$")}

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.

~DC-FP1_set(wort1 wort2 wort3 wort1)~
~DC-FP1_replace(wort2,wort5)~
~DC-FP1~                             <!-- wort1 wort5 wort3 wort1 -->

~DC-FP2_set(wort1 wort2 wort3 wort1)~
~DC-FP2_replace(wort1,)~
~DC-FP2~                             <!-- wort2 wort3 -->

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)~`

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.

~DC-FP1_set(SCHALTER)~
~DC-FP1_slice(2,6)~      <!-- DC-FP1 enthält jetzt HALT -->

~DC-FP2_set(SCHALTER)~
~DC-FP2_slice(3)~        <!-- DC-FP2 enthält jetzt ALTER -->

Both arguments support tag-in-tag.

~DC-FPvon_set(0)~
~DC-FPbis_set(5)~
~DC-FP1_slice($DC-FPvon$,$DC-FPbis$)~

_truncate()

Truncates after the specified number of characters.

~DC-FP1_set(abcdefg)~
~DC-FP1_truncate(3)~
~DC-FP1~                <!-- abc -->

_extractTaggedData()

Cuts out what is between two markers. Both arguments support tag-in-tag.

~DC-FP1_set(<a>Inhalt A</a><b>Inhalt B</b>)~
~DC-FP1_extractTaggedData(<a>,</a>)~
~DC-FP1~                                      <!-- Inhalt A -->

_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.

~DC-FP1_set($A-FirstName$)~
~DC-FP1~ ~DC-FP1_urlencoding~                   <!-- Jörg   J%f6rg -->

~DC-FP1_convertToEncoding($WS-Charset$,UTF-8)~
~DC-FP1~ ~DC-FP1_urlencoding~                   <!-- JÃ¶rg   J%c3%b6rg -->

_touppercase and _tolowercase

Convert the stored value to uppercase or lowercase letters. Neither outputs anything itself.

~DC-FP1_set(Blau)~
~DC-FP1_touppercase~
~DC-FP1~               <!-- BLAU -->

Outputting the value

_length

Outputs the number of characters.

~DC-FP1_set(abcdefg)~
~DC-FP1_length~        <!-- 7 -->

_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.

~DC-FP1_set(sometext)~
~DC-FP1_IndexOf(t)~      <!-- 4 -->
~DC-FP1_RIndexOf(t)~     <!-- 7 -->
~DC-FP1_IndexOf(z)~      <!-- -1 -->

Both can also be used as brackets. The positive area appears if the string was found.

{!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

~DC-FP1_set($A-Street1$)~
<a href="https://transportunternehmen.example/?street=~DC-FP1_urlencoding~">Zum Retourenformular</a>
<!-- ergibt bei "An den Rampen 23": ...?street=An%20den%20Rampen%2023 -->

~DC-FP1_set($BASKET-PR-Name$)~
"Name": "~DC-FP1_jsonencoding~"

_linknameencoding

Outputs the value according to the rules you have defined in the <LinkNameEncoding> section of the shop configuration shop.config for the readable part of your URLs.

~DC-FP1_set($CAT-RobotName$)~
~URL-Homepage~/~DC-FP1_linknameencoding~?websale8=~WS-ShopID~.~WS-SubShopID~&ci=~CAT-Index~

Reference: <LinkNameEncoding> section

_encodeISO2HTML

Outputs all characters outside ASCII as decimal HTML entities.

~DC-FP1_set(testü)~
~DC-FP1_encodeISO2HTML~   <!-- test&#252; -->

_StripHTML

Outputs the value without HTML markup and without quotation marks. Intended for fields that require plain text, for example a meta description.

~DC-FPbeschreibung_set($PR-Description$)~
<meta name="description" content="~DC-FPbeschreibung_StripHTML~">

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 `<DesignControl>` section of `shop.config`

~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 `<DesignControl>` section of `shop.config`
Length (optional)	truncates the output after this many characters

~DC-FP2_hash(sha256,hex,uploadlink,16)~

The content of the parameter is hashed with the secret from the configuration appended. The result is encoded and output.

Without a third parameter, _encrypt() falls back on DCFPXEncryptBlowfishPW from the <Basic> section. This entry is deprecated. Always create new encryptions with a dedicated ID in the <DesignControl> section.

Reference: <DesignControl> 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.

~DC-FP5_set($CAT-Name$)~

{DC-FP5_contains(hemd)}
   <!-- greift bei "Langarm-Hemden", "sportliche Hemden", "Kurzarmhemd" -->
{/DC-FP5_contains(hemd)}

{!DC-FP5_contains(hemd)}
   <!-- alle übrigen Kategorien -->
{/!DC-FP5_contains(hemd)}

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.

~DC-FPorderNumber_set($WS-OTPorder$)~
~DC-FPuserNumber_set($WS-OTPnumber$)~

{DC-FPorderNumber_verifyChecksum(DuG-ReNr)}
   {DC-FPuserNumber_verifyChecksum(DuG-AdrNr)}
      <!-- beide Nummern sind plausibel -->
   {/DC-FPuserNumber_verifyChecksum(DuG-AdrNr)}
{/DC-FPorderNumber_verifyChecksum(DuG-ReNr)}

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.

~DC-FP$WS-OTP1$_set(wert)~                 <!-- bei Aufruf mit &otp1=123 entsteht DC-FP123 -->
~DC-FP$WS-OTP1$_touch~                     <!-- merkt Name und Wert, gibt nichts aus -->

~DC-SPkey_set($DC-FP_lastKeyTouched$)~     <!-- DC-SPkey enthält nun 123 -->
~DC-SPval_set($DC-FP_lastValueTouched$)~   <!-- DC-SPval enthält nun wert -->

Two further tags hold the most recent search result.

~DC-FP1_set(randomtext)~
~DC-FP1_IndexOf(r)~         <!-- 0 -->
~DC-FP1_IndexOf(n)~         <!-- 2 -->
~DC-FP_lastIndexOfTouched~  <!-- 2 -->

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()`

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

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.

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.

Guide: Using free parameters
Reference: DC- (counters and calculations)
Reference: DC- (loops)
Reference: DC- (comparisons and other tags)
Basics: Tag basics

​The pattern in three steps

​Brackets without a parameter mean “is filled”

​The complete example

​FP or SP

​The output is HTML-encoded

​Taking values from other tags

​The suffixes

​Changing the value

​_set()

​_reset

​_append()

​_replace()

​_slice()

​_truncate()

​_extractTaggedData()

​_convertToEncoding()

​_touppercase and _tolowercase

​Outputting the value

​_length

​_IndexOf() and _RIndexOf()

​Encodings

​_linknameencoding

​_encodeISO2HTML

​_StripHTML

​_encrypt() and _hash()

​Checking

​_contains()

​_verifyChecksum()

​Passing on names and values

​Limits

​Tags with other prefixes

​The tags at a glance

​Related topics

The pattern in three steps

Brackets without a parameter mean “is filled”

The complete example

FP or SP

The output is HTML-encoded

Taking values from other tags

The suffixes

Changing the value

_set()

_reset

_append()

_replace()

_slice()

_truncate()

_extractTaggedData()

_convertToEncoding()

_touppercase and _tolowercase

Outputting the value

_length

_IndexOf() and _RIndexOf()

Encodings

_linknameencoding

_encodeISO2HTML

_StripHTML

_encrypt() and _hash()

Checking

_contains()

_verifyChecksum()

Passing on names and values

Limits

Tags with other prefixes

The tags at a glance

Related topics