AltCurrency- (Alternative currency) - WEBSALE Dokumentation

A shop bills in one currency but can additionally show its prices to the visitor in a second one. That is exactly what the tags in this group do: they output prices, totals, and costs converted, without changing anything about the billing. Which second currencies are available and which factor is used for conversion is defined in the shop.config in the <AlternativeCurrency> section.

Not all tags in this group carry the prefix AltCurrency-. They are spread across the prefixes WS-, FORM-, BT-, PR-, BD-, and BASKET- and are grouped here because together they form one function. Within the brackets for shipping and payment costs, there are also local tags without a prefix.

Guide: Alternative currency · Reference: AlternativeCurrency section

Two rules that apply to almost all tags

The currency parameter

Most tags accept a three-letter currency ISO code as a parameter. Without a parameter, they convert into the currency the visitor has currently selected. With a parameter, they convert into the specified currency, regardless of the selection.

Preis in der gewählten Währung: ~PR-AltCurrencyPrice~
Preis in Schweizer Franken:     ~PR-AltCurrencyPrice(CHE)~

The passed currency must be defined in the <AlternativeCurrency> section of the shop.config. If it is not, there is no conversion factor and the range remains empty.

If you output a price with a currency parameter, the parameter also belongs on the symbol. ~PR-AltCurrencyPrice(CHE)~ ~WS-AltCurrencySymbol~ writes the franc amount with the symbol of the currently selected currency. The correct form is ~PR-AltCurrencyPrice(CHE)~ ~WS-AltCurrencySymbol(CHE)~.

When a range applies

With ordinary price tags, the range applies if a value is present. With the AltCurrency tags, this is different: the range applies if a conversion factor exists, even if the converted amount is 0.

{PR-AltCurrencyPrice}
   Preis: ~PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~
{/PR-AltCurrencyPrice}

{!PR-AltCurrencyPrice}
   Für dieses Produkt liegt kein Preis in der gewählten Währung vor.
{/!PR-AltCurrencyPrice}

The negative range thus answers the question “no second currency set”, not “price is zero”. That is the right condition for these tags, because without a conversion factor there is simply nothing to display.

A complete example

The selection list, the price in both currencies, and the switch together:

{WS-AltCurrency}

   <form action="~FORM-AltCurrency~" method="post">
      ~WS-AltCurrencyList~
      <input type="submit" name="~BT-AltCurrency~" value="Währung wechseln">
   </form>

   <p>
      ~PR-Price~ ~WS-CurrencySymbol~
      <span>entspricht ~PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~</span>
      <span>Umrechnungsfaktor: ~WS-AltCurrencyRate~</span>
   </p>

{/WS-AltCurrency}

{!WS-AltCurrency}
   ~PR-Price~ ~WS-CurrencySymbol~
{/!WS-AltCurrency}

Always show both amounts and clearly mark the converted one as a conversion. Orders are placed and billed in the shop currency. If the franc amount stands alone, the visitor takes it for the invoice amount.

You only need the form FORM-AltCurrency if the selection list is outside of FORM-Product or FORM-Basket. If it is inside one of these two forms, the button with BT-AltCurrency is sufficient.

The currency itself

Tag	Parameter	Single tag	Range tag	Negative range tag	Permitted in
`WS-AltCurrency`	yes	yes	yes	yes	all templates
`WS-AltCurrencyISO`	yes	yes	yes	yes	all templates
`WS-AltCurrencySymbol`	yes	yes	yes	yes	all templates
`WS-AltCurrencyRate`	yes	yes	yes	yes	all templates
`WS-AltCurrencyList`	–	yes	yes	yes	product detail view, basket page
`FORM-AltCurrency`	–	yes	–	–	product detail view, basket page
`BT-AltCurrency`	–	yes	–	–	product detail view, basket page

None of these tags can be used as a loop tag.

WS-AltCurrency

Outputs the selected alternative currency as text. With a parameter, you check which currency is selected.

{WS-AltCurrency}

   Alternative Währung: ~WS-AltCurrency~

   {WS-AltCurrency(GBR)}
      Bereich, wenn die gewählte alternative Währung GBR ist.
   {/WS-AltCurrency(GBR)}

   {!WS-AltCurrency(GBR)}
      Bereich, wenn die gewählte alternative Währung nicht GBR ist.
   {/!WS-AltCurrency(GBR)}

{/WS-AltCurrency}

{!WS-AltCurrency}
   Es wurde keine alternative Währung gewählt.
{/!WS-AltCurrency}

The outer range is the most important one on this entire page. Everything related to the second currency belongs inside it. Without it, empty amounts and a lone currency symbol appear on the page as soon as no second currency is selected.

WS-AltCurrencyISO

Outputs the three-letter ISO code of the alternative currency. With a parameter, the tag works like WS-AltCurrency.

ISO-Code: ~WS-AltCurrencyISO~

WS-AltCurrencySymbol

Outputs the currency symbol of the alternative currency.

Place this tag after every converted amount, not WS-CurrencySymbol. The latter returns the symbol of the shop currency, and then a euro sign appears after the franc amount.

WS-AltCurrencyRate

Outputs the conversion factor from the shop currency into the alternative currency.

1 ~WS-CurrencySymbol~ entspricht ~WS-AltCurrencyRate~ ~WS-AltCurrencySymbol~

The factor belongs visibly on the page if you show converted prices. It makes it traceable how the second amount comes about and makes clear that it is a conversion and not a separate price.

WS-AltCurrencyList

Outputs a ready-made selection list with all configured alternative currencies.

FORM-AltCurrency

Returns the address for a separate form containing the selection list. It is not needed if the selection list is inside FORM-Product or FORM-Basket.

BT-AltCurrency

Returns the name of the button used to submit the currency selection via FORM-Product or FORM-Basket.

<input type="submit" name="~BT-AltCurrency~" value="Währung wechseln">

Product prices

All tags in this group accept a currency ISO code and are permitted as a single tag, range tag, and negative range tag in all templates, but not as a loop tag.

Tag	Purpose
`PR-AltCurrencyPrice`	Price, gross or net depending on the `<VAT>` section of the `shop.config`
`PR-AltCurrencyNetPrice`	Net price
`PR-AltCurrencyGrossPrice`	Gross price
`PR-AltCurrencyVAT`	VAT amount of the product
`PR-AltCurrencySetPrice`	Price of a set
`PR-AltCurrencyGrossSetPrice`	Gross price of a set
`PR-AltCurrencySetVAT`	VAT amount of a set

{PR-AltCurrencyPrice}
   ~PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~
{/PR-AltCurrencyPrice}

PR-AltCurrencyPrice follows the shop’s setting; the two explicit variants do not. In a gross shop, PR-AltCurrencyPrice shows the same value as PR-AltCurrencyGrossPrice; in a net shop, the same as PR-AltCurrencyNetPrice. Use the explicit variant only where the value must be fixed regardless of the shop setting.

Tiered prices

Tag	Purpose
`BD-AltCurrencyPrice`	Tiered price
`BD-AltCurrencyDiscount`	Tiered price discount

Both accept a currency ISO code, can be used as a single tag and in both range forms, and are only permitted on the product detail view (ws_product.htm). Guide: Product prices, section Tiered prices

Basket and order

These tags also accept a currency ISO code and are permitted as a single tag and in both range forms in all templates.

Basket totals

Tag	Purpose
`BASKET-AltCurrencySubTotalSum`	Value of goods
`BASKET-AltCurrencySubTotalNet`	Net value of goods
`BASKET-AltCurrencySubTotalGross`	Gross value of goods
`BASKET-AltCurrencySubTotalVAT`	VAT on the value of goods
`BASKET-AltCurrencyValueOfGoods`	Total value of goods of all products in the basket
`BASKET-AltCurrencyTotalVAT`	VAT of the entire order
`BASKET-AltCurrencyOrderTotal`	Final amount of the purchase

{WS-AltCurrency}
   Endbetrag: ~BASKET-OrderTotal~ ~WS-CurrencySymbol~
   (entspricht ~BASKET-AltCurrencyOrderTotal~ ~WS-AltCurrencySymbol~)
{/WS-AltCurrency}

The final amount is where a second currency is most easily misunderstood. State explicitly which currency is used for billing, and put the amount in the shop currency first.

Basket items

Tag	Purpose
`BASKET-PR-AltCurrencyPrice`	Price per unit
`BASKET-PR-AltCurrencySum`	Total price of the item
`BASKET-PR-AltCurrencySetPrice`	Unit price of a set
`BASKET-PR-AltCurrencySetSum`	Total price of a set

{@BASKET-PR-Data}
   ~BASKET-PR-Name~
   ~BASKET-PR-AltCurrencyPrice~ ~WS-AltCurrencySymbol~ je Stück
   ~BASKET-PR-AltCurrencySum~ ~WS-AltCurrencySymbol~ gesamt
{/@BASKET-PR-Data}

Web-to-print additional costs

For the additional costs of a web-to-print design, the same four values exist on three levels: on the product, per basket item, and as a total across the basket.

Level	Tags
Product	`PR-AltCurrencyW2PCost()`, `PR-AltCurrencyW2PNetCost()`, `PR-AltCurrencyW2PGrossCost()`, `PR-AltCurrencyW2PVAT()`
Basket item	`BASKET-PR-AltCurrencyW2PCost()`, `BASKET-PR-AltCurrencyW2PNetCost()`, `BASKET-PR-AltCurrencyW2PGrossCost()`, `BASKET-PR-AltCurrencyW2PVAT()`
Basket total	`BASKET-AltCurrencyW2PTotal()`, `BASKET-AltCurrencyW2PTotalNet()`, `BASKET-AltCurrencyW2PTotalGross()`, `BASKET-AltCurrencyW2PTotalVAT()`

All twelve tags can be used as a single tag and in both range forms, accept a currency ISO code, and are not loop tags. The meaning of the four variants is the same on every level: without a suffix, the value according to the shop setting; Net and Gross explicitly net or gross; VAT the VAT portion. On the product:

{PR-AltCurrencyW2PCost}
   Zusatzkosten für die Gestaltung: ~PR-AltCurrencyW2PCost~ ~WS-AltCurrencySymbol~
{/PR-AltCurrencyW2PCost}

{PR-AltCurrencyW2PCost(CHE)}
   Zusatzkosten in Schweizer Franken: ~PR-AltCurrencyW2PCost(CHE)~ ~WS-AltCurrencySymbol(CHE)~
{/PR-AltCurrencyW2PCost(CHE)}

{!PR-AltCurrencyW2PCost}
   Es fallen keine Zusatzkosten an.
{/!PR-AltCurrencyW2PCost}

Per basket item, within the item loop:

{@BASKET-PR-Data}
   {BASKET-PR-AltCurrencyW2PCost}
      Zusatzkosten: ~BASKET-PR-AltCurrencyW2PCost~ ~WS-AltCurrencySymbol~
   {/BASKET-PR-AltCurrencyW2PCost}
{/@BASKET-PR-Data}

As a total across the basket, within the basket bracket:

{BASKET-PR-Data}
   {BASKET-AltCurrencyW2PTotal}
      Gesamtkosten der Gestaltung: ~BASKET-AltCurrencyW2PTotal~ ~WS-AltCurrencySymbol~
   {/BASKET-AltCurrencyW2PTotal}
{/BASKET-PR-Data}

The difference between the two basket levels lies in the @. The item tags belong in the loop {@BASKET-PR-Data}, the total tags in the bracket {BASKET-PR-Data} without a loop.

Guide: Web-to-print products

Local tags for shipping and payment costs

Within the display of shipping methods and chargeable additional services, separate local tags without a prefix apply. They are only available there.

Tag	Single tag	Range tag	Negative range tag	Purpose
`AltCurrencyCost`	yes	yes	yes	Costs, gross or net depending on `shop.config`
`AltCurrencyGrossCost`	yes	–	–	Gross costs
`AltCurrencyNetCost`	yes	–	–	Net costs
`AltCurrencyISO`	yes	–	–	ISO code of the alternative currency
`AltCurrencySymbol`	yes	–	–	Currency symbol of the alternative currency

In addition, the same values exist in the shop currency as Cost, GrossCost, NetCost, WS-Currency, and WS-CurrencySymbol.

{AltCurrencyCost}
   Versandkosten: ~AltCurrencyCost~ ~AltCurrencySymbol~
{/AltCurrencyCost}

{!AltCurrencyCost}
   Versandkosten: ~Cost~ ~WS-CurrencySymbol~
{/!AltCurrencyCost}

AltCurrencyCost is the only one of these tags that can also be used as a range tag. It is therefore the switch with which you bracket the entire display in the alternative currency in or out. The other four are pure single tags and return nothing without a conversion factor.

These tags do not accept a currency parameter. They always convert into the currently selected currency.

Guide: Creating shipping methods · Guide: Creating payment methods

Guide: Alternative currency
Guide: Product prices
Reference: AlternativeCurrency section

​Two rules that apply to almost all tags

​The currency parameter

​When a range applies

​A complete example

​The currency itself

​WS-AltCurrency

​WS-AltCurrencyISO

​WS-AltCurrencySymbol

​WS-AltCurrencyRate

​WS-AltCurrencyList

​FORM-AltCurrency

​BT-AltCurrency

​Product prices

​Tiered prices

​Basket and order

​Basket totals

​Basket items

​Web-to-print additional costs

​Local tags for shipping and payment costs

​Related topics

Two rules that apply to almost all tags

The currency parameter

When a range applies

A complete example

The currency itself

WS-AltCurrency

WS-AltCurrencyISO

WS-AltCurrencySymbol

WS-AltCurrencyRate

WS-AltCurrencyList

FORM-AltCurrency

BT-AltCurrency

Product prices

Tiered prices

Basket and order

Basket totals

Basket items

Web-to-print additional costs

Local tags for shipping and payment costs

Related topics