Template engine

The WEBSALE template language offers a powerful and flexible way to individually design the frontend of an online shop. Dynamic content such as product or user data can be seamlessly embedded in HTML templates, and language-dependent texts or complex conditions can be taken into account. This documentation conveys the basic functions and tools that are frequently used in daily work when designing online shops. From the use of variables to the application of loops and conditions and the use of modifiers, it describes how content can be designed and adjusted dynamically.

WEBSALE template engine

The WEBSALE template engine is used for the complete creation and design of the storefront. You do not need knowledge of programming languages such as PHP or Java, nor knowledge of database access, to create and customize your individual WEBSALE online shop. With the WEBSALE template engine, dynamic content in the online shop can be easily displayed — entirely without complex backend logic. As a template manager, you can fully focus on HTML, CSS, and JavaScript and embed dynamic data such as product information, user profiles, or prices with the help of our template engine and template language.

Basics and syntax of the WEBSALE template engine

In the WEBSALE template environment, all templates are based on standard HTML files with the extensions .htm or .html, which are stored within the shop’s directory structure. Within these HTML files, so-called template tags can be used to embed dynamic content or language-dependent texts in the frontend. Template tags allow the inclusion of:

Text snippets for language-dependent content.
Placeholders for dynamic content such as product data, user data, or shop functions.

Text snippets

Text snippets are used to centrally manage language-dependent texts such as button labels or headings and to insert them into templates. Their syntax is simple and unambiguous:

%%TextSnippetName%%

Example: “Add to cart” button

<button type="button">%%AddToCart%%</button>

Text snippets are used not only in templates but also in configurations, provided that language-dependent texts for the frontend output are stored there, for example display texts or descriptions. More information about using text snippets in configurations can be found in the Configurations section. The %%TextSnippetName%% notation requires that the name is already known when the template is created. When the templates are published, the shop replaces it with the text. If the name is only determined when the page is called, for example because it is built from a status code of an external system, use the translate function instead:

{{= translate("shop.basket.addButton") }}

Placeholders (for dynamic content)

Placeholders are used to embed dynamic data that is provided by the backend at runtime. The syntax is HTML-like and uses double curly braces {}:

{{= $variable }}

Example: Product name and product description

<h1>{{= $myProduct.name}}</h1>
<p>{{= $myProduct.description }}</p>

The template engine interprets these placeholders and replaces them at runtime with the corresponding values from the system.

Standard escaping

The WEBSALE template engine has built-in standard escaping that is automatically applied to all dynamically embedded content. This ensures that HTML or JavaScript code contained, for example, in product data or CMS content is not interpreted but displayed as plain text. Many contents in the shop — e.g., product descriptions, CMS articles, or other editorial texts — contain HTML for formatting. To prevent these contents from being unintentionally executed as actual HTML code, automatic escaping is applied during output with {{= ... }}. Example: Standard escaping enabled

{{= $product.description }}

Content in the shop data:

<p><strong>Super breathable</strong> – ideal for sports and leisure. Now available in the <em>latest generation</em>.</p>

Output in the browser:

&lt;p&gt;&lt;strong&gt;Super breathable&lt;/strong&gt; – ideal for sports and leisure. Now available in the &lt;em&gt;latest generation&lt;/em&gt;.&lt;/p&gt;

The HTML code is not interpreted but displayed as normal text. This protects against unintended code execution. If content is to be deliberately output as HTML — for example because product texts or CMS content contain HTML and should be rendered correctly — escaping can be deactivated in a targeted manner. To do this, an exclamation mark ! is used instead of =:

{{! $product.description }}

Output in the browser:

<p><strong>Super breathable</strong> – ideal for sports and leisure. Now available in the <em>latest generation</em>.</p>

Now the HTML code is correctly interpreted and rendered. Important: Disabling escaping should only be done for trusted content — for example, for data from your own product backend or CMS. Content that originates, for example, from customer form inputs should not be output unfiltered without escaping.

Variables

With the WEBSALE template language, you can output the data provided by the shop system. Each page rendered by the template engine receives the data needed to display the requested content. This data is stored in so-called template variables. All template variables can be called via the template language with a $ followed by the variable name. Variable names can be chosen freely. There are also system variables that begin with $ws and whose names are predefined. Examples include the modules $wsProducts and $wsCategories. A complete overview of the WEBSALE system variables and further information about variables in general can be found in the variables overview.

Setting & using variables

Example: New variable

{{ var $myProduct = $wsProducts.load('1234') }}

New variables are always defined with the var keyword. In this example, the function $wsProducts.load('1234') loads the data of the product with the product ID 1234. This is stored in the variable $myProduct and can be used later. Example: Using the variable

{{ var $myProduct = $wsProducts.load('1234') }}

<h1>{{= $myProduct.name }}</h1>
<p>{{= $myProduct.description }}</p>
<p>Price: {{= $myProduct.price }} €</p>

Variables that have been defined once can be used in any place in the template. In this case:

The product data is stored in $myProduct.
The product name, description, and price are dynamically inserted into the template.

Example: Nested variable

{{ var $myProduct = $wsProducts.load('1234') }}

<img src="{{= $myProduct.custom.mainImage.thumbnail }}" alt="Product image">

Variables can also be nested to access specific values within complex data structures such as objects or arrays. Nesting is always done with dots . between the individual levels. In this example:

$myProduct is the main variable for the product.
custom references custom data of the product.
mainImage indicates the main image of the product. The field name is an example and depends on the product data fields created in the shop.
thumbnail accesses the smaller version of the image.

A complete list of all variables and their descriptions can be found in the variables overview.

Scope of variables

The scope of a variable defines where it can be used in the template. Variables that are defined outside of scope statements such as if or foreach are valid throughout the entire template:

{{ var $myCategory = $wsCategories.loadCategory('5678') }}

<h2>{{= $myCategory.name }}</h2>
{{ if $myCategory.active }}
    <p>This category is active.</p>
{{ /if }}

Variables defined within scope statements only exist within that scope:

{{ foreach $myProduct in $wsCategories.loadProducts('5678') }}
    <h3>{{= $myProduct.name }}</h3>
    <p>{{= $myProduct.price }} €</p>
{{ /foreach }}

<p>{{= $myProduct.name }}</p>  -> $myProduct is not valid outside the loop

Modifiers

Sometimes it is not enough to simply output the content of a variable. The value must first be changed or adjusted. This is exactly what so-called modifiers are for. Modifiers can be applied to any variable to change its content. To do so, add a | (pipe character) and the modifier name to the corresponding variable. Additional parameters are specified in parentheses. Example: Truncating a text

{{= $myProduct.name | take(30) }}

In this example, the take modifier is applied to the product name. It outputs only the first 30 characters. Example: Applying multiple modifiers to a variable You can also apply multiple modifiers to a variable in succession. They are processed in the order specified.

{{= $myProduct.description | stripHtml | take(120) }}

Here, stripHtml first removes the HTML formatting from the product description. Then take truncates the plain text to 120 characters. A complete list of all modifiers and their descriptions can be found in the modifiers overview.

Conditions

Conditions let you vary the output in the storefront depending on certain values. A condition is introduced with {{ if }} and closed with {{ /if }}. In between, any number of {{ elseif }} branches and one {{ else }} branch are allowed. The content of a branch is only output if the check in it is true (true). Example:

{{ if $myProduct.description }}
    {{= $myProduct.description }}
{{ else }}
    {{= $myProduct.custom.shortdescr }}
{{ /if }}

In this example, it is checked whether the variable $myProduct.description has content. If so, its content is output. Otherwise, the alternative content in the else branch is output, here a short description from a product data field. In addition to if and else, multiple checks can also be defined one after another by adding {{ elseif }}. Example: Greeting the visitor in the online shop

If a customer is logged in and has stored a billing address, they are greeted by their first name.
If a customer is logged in but has no billing address stored, a general greeting is displayed.
For all visitors who are not logged in, a note about registration is displayed.

{{ if $wsAccount.isLoggedIn and $wsAccount.defaultBillAddress.firstName }}
    <p>Welcome back, {{= $wsAccount.defaultBillAddress.firstName }}!</p>
{{ elseif $wsAccount.isLoggedIn }}
    <p>Welcome back!</p>
{{ else }}
    <p>Welcome! Please register.</p>
{{ /if }}

Example: Conditions with operators, for example for stock levels Operators can also be used to compare values, for example the available quantity of a product with > or <. The stock data is provided by the $wsInventory module:

{{ var $myInventory = $wsInventory.load($myProduct.id) }}
{{ if $myInventory.amount > 0 }}
    <p>This product is available.</p>
{{ else }}
    <p>This product is not available.</p>
{{ /if }}

A complete overview of the available operators and their use can be found in the operators reference.

Loops

Loops make it possible to iterate through a list containing multiple data records, for example products, and automatically generate content for each individual record. This allows you to efficiently create recurring structures such as product lists or image galleries. A loop is opened with {{ foreach <loop variable> in <list> }} and closed with {{ /foreach }}. The name of the loop variable can be chosen freely and may contain letters, numbers, and underscores. The foreach loop runs through all elements of a list and executes the enclosed code section for each element. With each iteration, the current element is assigned to the loop variable. Example: Product list of a category

{{ var $myProducts = $wsCategories.loadProducts('5678') }}
<div class="product-list">
    {{ foreach $myProduct in $myProducts }}
        <div class="product-item">
            <h2>{{= $myProduct.name }}</h2>
            <p>{{= $myProduct.description }}</p>
            <p>Price: {{= $myProduct.price }} €</p>
        </div>
    {{ /foreach }}
    {{ if not $myProducts }}
        <p>No products available in this category.</p>
    {{ /if }}
</div>

The loop runs through all products of the category with the ID 5678 and creates a new <div> element for each product. If the category contains no products, the list is empty and the subsequent condition outputs a corresponding message. Complete information on loops can be found under Loops.

Complete reference documentation

Of course, the WEBSALE template language offers many other functions and possibilities. However, the basics described above are among the most frequently used tools in daily work when editing the WEBSALE online shop. A complete overview of all functions, modules, actions, and possibilities can be found in our reference documentation.

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

WEBSALE template engine

Basics and syntax of the WEBSALE template engine

Text snippets

Placeholders (for dynamic content)

Standard escaping

Variables

Setting & using variables

Scope of variables

Modifiers

Conditions

Loops

Complete reference documentation

​WEBSALE template engine

​Basics and syntax of the WEBSALE template engine

​Text snippets

​Placeholders (for dynamic content)

​Standard escaping

​Variables

​Setting & using variables

​Scope of variables

​Modifiers

​Conditions

​Loops

​Complete reference documentation

WEBSALE template engine

Basics and syntax of the WEBSALE template engine

Text snippets

Placeholders (for dynamic content)

Standard escaping

Variables

Setting & using variables

Scope of variables

Modifiers

Conditions

Loops

Complete reference documentation