Theme development basics

Shoper is using Twig as a template engine. It is a PHP framework used to create dynamic web pages. It is available as an open source project on GitHub and used by many different software projects and companies.

What is a template engine?

Website designers and developers can use a template language to build webpages that combine both static and dynamic content. Static content is, in other words, just HTML. Dynamic content however consists of output and logic provided by Twig. A template language makes it possible to re-use the static elements that define the layout of a webpage, while dynamically populating the page with data from a Shoper store.

Syntax

Twig has its own syntax like traditional programming languages. Interacts with variables and includes constructs such as output and logic. Due to its syntax, Twig constructs are easy to recognize and can be distinguished from HTML by the following sets of delimiters:

• {{ }} Double curly brace delimiters, which denote output.
• {% %} Curly brace percentage delimiters, which denote logic and control flow.

Variables

In a theme template, variables are wrapped in double curly brace delimiters {{ }} to render their values and look like this:

{{ product_id }}

In the above example, product_id is the variable. When the code in the file is compiled and rendered on a product page, the output of the variable will be the ID of the current product:

1

Remember that all of the variables may have different contexts in which they can be used. For example the product_id is only available within a product card page because it makes sense for this variable to exist only within this context.

Objects and Object Api

Object Api is a facade for the Shops data providing various objects that can be accessed in Twig. Take a look at an example of using Object Api with the product_id variable. To load dynamic data about the current product, the code needs to access the specific product object. To obtain the product object for the current product, the code needs to use the getProduct() method from the Object Api like this:

{% set product = ObjectApi.getProduct(product_id) %}
{{ product.name }}

In the above example, product is the object, and name is a property of that object. Each object has a list of associated properties. To learn more about the product object's properties, see the Product object page.

When the code in the file is compiled and rendered on a product page, the output will be the name of the product. For example, in a clothing store, the result might be:

Awesome T-Shirt

Even though the same template is used for every product in a store, the objects in the template will output different data depending on the specific product page being viewed. In other words, while the template remains constant, the data it generates is dynamic and depends on the specific product displayed on the page.

To learn more about the different objects that can be used in theme templates, see the Object Api page.

Tags

Twig tags allow to include logic into templates. They are used within a logic tag {% %} and are separated from the variable by a space character. There are many different tags available in Twig. To learn more about the different tags that can be used in theme templates, see the Twig tags documentation.

Control flow tags

Control flow tags allow to determine when and under which circumstances to process our statements. These are tags like if statements or ternary operators. For example, the following code uses the if tag to check if the value of the product.name variable is equal to Awesome T-Shirt. If it is, the <p> HTML tag will be outputted:

{% if product.name == 'Awesome T-Shirt' %}
    <p>This is an awesome t-shirt!</p>
{% endif %}

Iteration tags

Iteration tags allow to iterate through data. These are tags like for loops. For example, the following code uses the for tag to iterate through the products variable and output the name of each product:

{% for product in products %}
    <p>{{ product.name }}</p>
{% endfor %}

Variable tags

Variable tags are used to assign values to variables. These are tags like set. For example, the following code uses the set tag to assign the value Awesome T-Shirt to the product.name variable:

{% set product.name = 'Awesome T-Shirt' %}

Filters

Twig filters allow to manipulate and format data. They are used within an output tag {{ }} as well as a login tag {% %} depending on the context which will be shown in the examples. Filters are separated from the variable by a pipe character |.

Take a look at the the following code, which uses the upper filter to convert the value of the product.name variable to uppercase:

{{ product.name|upper }}

There is also a filter that can be used to format a date. For example, the following code uses the date filter to format the value of the product.createdAt variable to a date:

{{ product.createdAt|date('Y-m-d') }}

We can also make it more specific by adding the time and timezone:

{{ product.createdAt|date('Y-m-d\\Tg:i:sP') }}

Another example of a formatting filter that requires an argument is a join filter that can be used to join elements of an array into a string. For example, the following code uses the join filter to join the array of numbers into a string representing those numbers separated by the space character:

{% set arrayOfNumbers = [12, 45, 365, 86] %}
{{ arrayOfNumbers|join(' ') }}

There are more complex filters which require an arrow function inside to manipulate the data. An example of such filter is a filter that can be used to filter out unnecessary elements from a sequence or a list. Take a look at the following code, which uses the filter to retrieve products related to the currently displayed product that are undergoing a promotion and set them to a variable:

{% set relatedProductsUndergoingPromotion = product.relatedProducts|filter(relatedProduct => relatedProduct.hasSpecialOffer) %}

We could then use a for loop mentioned above to iterate through the relatedProductsUndergoingPromotion variable and output the name of each related product that is undergoing a promotion:

{% for relatedProduct in relatedProductsUndergoingPromotion %}
    {{ relatedProduct.name }}
{% endfor %}

There are many different filters available in Twig. To learn more about the different filters that can be used in theme templates, see the Twig filters documentation.