Options

Define template options.

With options, you define settings in the template that can then be maintained in the Admin Interface without having to adjust the template again. For example, you can control whether the icon of a payment method is displayed in the footer.

An option always goes through the same process: define → maintain in the Admin Interface → read in the template. This page describes how to define options. The $wsOptions module reads the maintained values.

---

​

Basics

​

Syntax

An option is defined with the option statement, a unique name, and the details after with:

{{ option "stringValue" with {"type": "String"} }}

Defines an option named stringValue of type String. This creates a text field in the Admin Interface. The value entered there is output in the template via $wsOptions.get("stringValue"). Each option has exactly one type, which determines the input form in the Admin Interface.

​

Uniqueness and lifecycle

Each option may only be defined once. If two options with the same name are defined in different templates or at different places in the same template, an error occurs.

The defined options are available after the templates have been compiled successfully. If options are removed from the template, they only disappear from the Admin Interface after the templates are compiled again.

​

Static values only

Only static values are possible in the definition. For example, you cannot use variables, operators, or functions. The following examples are therefore not possible:

Example	Why it is invalid
{{ var $name = "invalidOption1"; option $name with {"type": "String" }}	Variables are not allowed as an option name.
{{ var $type = "String"; option "invalidOption2" with {"type": $type }}	Variables are not allowed in the details either.
{{ option "invalidOption3" with {"type": "Str" + "ing" }}	Operators are not allowed.
{{ option upper("invalidOption4") with {"type": "String" }}	Functions are not allowed.

​

Display label and description

You can edit the display label and description of individual options in the Admin Interface or via the REST API. They are used for display only and have no other function.

---

​

Option types

Each option has a type that determines the input form in the Admin Interface.

​

String

Displayed as a text field in the Admin Interface.

Example

{{ option "freeShippingHint" with {"type": "String"} }}

This creates a text field in the Admin Interface in which an editor enters a note about free delivery (for example “Free shipping from €50”). In the template, $wsOptions.get("freeShippingHint") then outputs exactly this text.

---

​

Bool

Displayed as an on/off switch in the Admin Interface. Suitable, for example, for switching a behavior or a display element on or off.

Example

{{ option "showTrustBadges" with {"type": "Bool"} }}

This creates an on/off switch in the Admin Interface. If it is set to “On”, $wsOptions.get("showTrustBadges") returns the value true, otherwise false. This is useful, for example, for showing or hiding the trust badges in the template.

---

​

Int

Expects an integer. Optionally, you can set value limits via min and max.

Example

{{ option "productsPerRow" with {"type": "Int", "min": 2, "max": 6} }}

This creates a number field in the Admin Interface that only accepts integers from 2 to 6. If an editor enters 4, $wsOptions.get("productsPerRow") returns the value 4, for example to display four products per row.

---

​

Float

Expects a decimal number. As with Int, you can optionally specify min and max.

Example

{{ option "minRatingForBadge" with {"type": "Float", "min": 0, "max": 5} }}

This creates an input field for a decimal number from 0 to 5 in the Admin Interface. If an editor enters 4.5, $wsOptions.get("minRatingForBadge") returns this value, for example as the minimum rating from which a “Top rated” badge appears.

---

​

Enum

Allows selection from a predefined list. The allowed values are defined via values.

Example

{{ option "teaserLayout" with {"type": "Enum", "values": ["grid", "list", "slider"]} }}

This creates a selection field with the three values grid, list, and slider in the Admin Interface. If an editor selects slider, $wsOptions.get("teaserLayout") returns the value slider, for example to display the teasers as a slider instead of a grid.

---

​

Binding options to configurations

With attachTo, you bind an option to a configuration node, for example payment.payment for the payment methods:

{{ option "showPaymentIconInFooter" with {"type": "Bool", "attachTo": "payment.payment"} }}

This has two effects:

• The setting can be edited directly in the respective configuration in the Admin Interface.
• For freely creatable configurations, such as one configuration per payment method, the setting can differ per node. For example, you can disable it for “Prepayment” and enable it for “Google Pay”. You read the value maintained this way in the template via $wsOptions.get(name, nodeId), where nodeId is the ID of the configuration node.

Specifically: if the switch is enabled for “Prepayment” in the Admin Interface but not for “Google Pay”, $wsOptions.get("showPaymentIconInFooter", "payment.payment.bill") returns true for the prepayment node and false for the Google Pay node. The footer icon therefore only appears for prepayment.

The configuration node ID is not the id field within a configuration (the “technical ID”). The objects that provide the correct nodeId are listed under $wsOptions.

---

​

Display in the Admin Interface

Via displayOptions.location, you define where in the clickable configuration interfaces of the Admin Interface the option appears:

{{ option "paymentInfoText" with {"type": "String", "attachTo": "payment.payment", "displayOptions": {"location": "payment.content"}} }}

As a result, the text field of this option appears in the Admin Interface directly in the “Content” section of the respective payment method and not in the general “Template options” section.

location only works in combination with attachTo. Without a matching attachTo, the setting has no effect.

Currently allowed values (the list will be extended as further interfaces are added):

Configuration	Location	Display
payment.payment	payment.image	In the “Image” section of the payment method configuration.
payment.payment	payment.content	In the “Content” section of the payment method configuration.

If location is not specified, the option appears in a general “Template options” section of the respective configuration node.

---

​

Reading values

The $wsOptions module describes how to read the maintained option values in the template, both for global options and for options bound to configuration nodes.