---
url: /api.md
---
# API

## Customer Addresses

```html
<form class="address">
    <input type="text" name="firstName">
    <input type="text" name="lastName">
    <input type="text" name="street">
    <input type="text" name="city">
    <input type="text" name="region">
    <input type="text" name="zip">
    <input type="text" name="country">
    <input type="email" name="email">
    <input type="tel" name="phone">
    <input type="text" name="companyName">
    <input type="text" name="companyId">
    <input type="text" name="vatId">
</form>
```

```javascript
document.querySelector('form.address').addEventListener('submit', function(event){
    event.preventDefault();

    var button = this.querySelector('[type="submit"]');
    button.disabled = true;
    button.classList.add('is-loading');

    api.user.address.add(new FormData(this))
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.address-error').textContent = error.message;
        })
        .finally(function(){
            button.disabled = false;
            button.classList.remove('is-loading');
        });
});

document.querySelector('form.address').addEventListener('submit', function(event){
    event.preventDefault();

    var button = this.querySelector('[type="submit"]');
    button.disabled = true;
    button.classList.add('is-loading');

    api.user.address.update(123456789, new FormData(this))
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.address-error').textContent = error.message;
        })
        .finally(function(){
            button.disabled = false;
            button.classList.remove('is-loading');
        });
});

document.querySelector('a.delete-address').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.user.address.delete(123456789)
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.address-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});

api.user.address.get(123456789)
    .then(function(response){
        document.querySelector('[name="firstName"]').value = response.firstName;
        document.querySelector('[name="lastName"]').value = response.lastName;
        // ... fill remaining fields
    })
    .catch(function(error){
        document.querySelector('.address-error').textContent = error.message;
    });
```

## Newsletter (logged-in customer)

### api.user.newsletter.unsubscribe

```javascript
document.querySelector('a.customer-unsubscribe').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.user.newsletter.unsubscribe()
        .then(function(){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.newsletter-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

## Order

### api.order.delete

```javascript
document.querySelector('a.delete-order').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.order.delete()
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.order-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.order.voucher.add

```javascript
document.querySelector('a.add-voucher').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.order.voucher.add('XYZ1234')
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.voucher-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.order.voucher.delete

```javascript
document.querySelector('a.delete-voucher').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.order.voucher.delete('XYZ1234')
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.voucher-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.order.item.changeAmount

```javascript
document.querySelector('a.remove-change-amount').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.order.item.changeAmount(/* item id*/ 123, 7 /* new amount (cannot be zero)  */)
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.cart-error').textContent = error.message;

            // Currently one of stock, unavailable, min_amount, max_amount, amount_multiple
            // More can be added later - always fallback to error message
            console.log(error.code);

            // translated error message
            console.log(error.message);

            // item name (useful if rule was triggered by bundle part)
            console.log(error.item.name);

            // correct amount for current validation (may not be valid for next validation)
            // zero for unavailable items
            console.log(error.recommendedAmount);
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.order.item.remove

```javascript
document.querySelector('a.remove-cart-item').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.order.item.delete(123)
        .then(function(response){
            window.location.reload();
        })
        .catch(function(error){
            document.querySelector('.cart-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.order.status.lookup

Look up order status using the order code and email. This method is protected by proof-of-work and rate limiting.

```javascript
document.querySelector('form.order-lookup').addEventListener('submit', function(event){
    event.preventDefault();

    var button = this.querySelector('[type="submit"]');
    button.disabled = true;
    button.classList.add('is-loading');

    var orderCode = this.querySelector('[name="orderCode"]').value;
    var email = this.querySelector('[name="email"]').value;

    api.order.status.lookup(orderCode, email)
        .then(function(response){
            // redirect to order status page
            window.location.href = response.url;
        })
        .catch(function(error){
            document.querySelector('.order-lookup-error').textContent = error.message;
        })
        .finally(function(){
            button.disabled = false;
            button.classList.remove('is-loading');
        });
});
```

## Products

### api.product.compare.add

```javascript
document.querySelector('a.compare-product').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.product.compare.add(123)
        .then(function(response){
            response.count // number of products in comparison
            response.url // URL to the product comparison page
        })
        .catch(function(error){
            document.querySelector('.compare-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.product.compare.remove

```javascript
document.querySelector('a.compare-product').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.product.compare.remove(123)
        .then(function(response){
            response.count // number of products in comparison
            response.url // URL to the product comparison page
        })
        .catch(function(error){
            document.querySelector('.compare-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.product.compare.clear

```javascript
document.querySelector('a.compare-product').addEventListener('click', function(event){
    event.preventDefault();

    var link = this;
    link.classList.add('is-loading');

    api.product.compare.remove()
        .then(function(response){
        })
        .catch(function(error){
            document.querySelector('.compare-error').textContent = error.message;
        })
        .finally(function(){
            link.classList.remove('is-loading');
        });
});
```

### api.log.feature.used

Feature usage logging is intended for tracking less frequently used features over a limited period -- for example, for A/B testing. The name can be arbitrary -- it is only used for debug reporting.

```javascript
document.querySelector('a.compare-product').addEventListener('click', function(event){
    event.preventDefault();

    api.log.feature.used('product-added-to-compare');
});
```

### api.geo.suggest.location

Returns a list of locations (addresses, cities, regions, ...) for the given phrase. Optionally, results can be filtered by country ("cz") or biased by coordinates. If the exact location is not known, it should always be used at least with GeoIP coordinates.

```javascript
api.geo.suggest.location('Drtinova 10', 'cz', 50.0843, 14.4075);
```

---

---
url: /cart.md
---
# Checkout Process

## Checkout Flow Architecture

The checkout is a multi-step process controlled by the `sekce` (section) variable. The main template `kosik.tpl` acts as a router, including the appropriate step partial based on the current section:

```twig
{# kosik.tpl — checkout router #}
{% if kos %}
    {# nesouhlas = terms and conditions not accepted #}
    {% if nesouhlas %}
        <div class="stav_err">{% trans 'checkout.terms-and-conditions.error.message' %}</div>
    {% endif %}

    {% if not sekce or sekce == 'kosik' %}
        {% include "kosik_obsah.tpl" %}       {# cart content step #}
    {% elseif sekce == 'udaje' %}
        {% include "kosik_udaje.tpl" %}        {# address entry step #}
    {% elseif sekce == 'dodani' %}
        {% include "kosik_dodani.tpl" %}       {# delivery selection step #}
    {% endif %}
{% else %}
    {% include 'kosik_prazdny.tpl' %}          {# empty cart #}
{% endif %}
```

### Step Templates

| Template | Purpose |
|---|---|
| `kosik.tpl` | Router — includes step partials based on `sekce` |
| `kosik_obsah.tpl` | Cart content — product list, quantities, discount codes |
| `kosik_dodani.tpl` | Delivery — transport and payment selection (see [Delivery](/delivery)) |
| `kosik_udaje.tpl` | Address — customer details entry |
| `kosik_souhrn.tpl` | Order summary sidebar — included in every step |
| `kosik_prazdny.tpl` | Empty cart fallback — shown when `kos` is falsy |
| `kosik_kroky.tpl` | Step indicator breadcrumb — included within each step |
| `kosik_darky.tpl` | Gift selection — included when `this.slaveConfig.enableGifts` is true |

The step flow is configured in `config.json` via the `cartSteps` setting (see [Configuration](/config)), which maps the progression: content -> delivery -> address. Each step form contains a hidden `toSekce` field that tells the server which step to advance to on submit.

### Cross-sell Products

After the checkout steps, `kosik.tpl` can display a cross-sell product carousel using a [content grid](/content-grid) slot:

```twig
{# Show cross-sell products below checkout when on the cart content step #}
{% if kos and not sekce and this.contentGrid('checkout-select-products').section.product is not empty %}
    {% set section = this.contentGrid('checkout-select-products').section %}
    <i:list-container type="product" hide-empty collection="{{ section.product }}">
        <h3>{{ section.headline }}</h3>
        <div data-role="list" class="listing"></div>
    </i:list-container>
{% endif %}
```

## Cart Items

The cart content step (`kosik_obsah.tpl`) displays products using the `cart.catalogItems` loop. The entire product list is wrapped in a form that posts to `this.urlSave`. The cart content area uses `i:dynamic="cart, objednavka"` so it reloads automatically when cart state changes (e.g., quantity updates). See [Syntax - Dynamic Content Reload](/syntax#dynamic-content-reload) for more on `i:dynamic`.

### Info Banner

An optional informational banner can be displayed above the cart items using a content grid slot:

```twig
{% if this.contentGrid('checkout-content-info') %}
    {% set block = this.contentGrid('checkout-content-info').checkouttext %}
    <div style="color: {{ block.color }}; background: {{ block.bgcolor }};
                border: {{ block.bordercolor ? '1px solid ' ~ block.bordercolor }}">
        {{ block.text }}
    </div>
{% endif %}
```

### Product List

```twig
<form action="{{ this.urlSave }}" method="post">
    <h1>{% trans 'checkout.headline' %} ({{ cart.catalogItemTotalAmount }} {% trans 'template.qty' %})</h1>

    {% for orderItem in cart.catalogItems %}
        <div class="cartie {{ orderItem.gift ? 'cartie--gift' }}">
            {# Product image — use variant image if available #}
            <a href="{{ orderItem.product.url }}">
                {% if orderItem.variant.image %}
                    <i:img src="orderItem.variant.image" format="130x92" fill />
                {% else %}
                    <i:img src="orderItem.image" format="130x92" fill />
                {% endif %}
            </a>

            {# Product name and child items (e.g., bundle contents) #}
            <a href="{{ orderItem.product.url }}">
                <strong>{{ orderItem.item.name }}</strong>
            </a>
            {% if orderItem.children is not empty %}
                {% for item in orderItem.children %}
                    {{ item.name }} {{ item.variantName }}
                    {% if item.priceTotal.current.value != 0 %}
                        ({{ item.priceTotal.current.formatted }})
                    {% endif %}
                {% endfor %}
            {% endif %}

            {# Variant name #}
            {% if orderItem.variantName %}
                {% trans 'template.variant' %}: <strong>{{ orderItem.variantName }}</strong>
            {% endif %}

            {# Unit price with optional discount display #}
            {% if orderItem.item.price.discount %}
                <span class="u-decoration-through">{{ orderItem.item.price.beforeDiscount.formatted }}</span>
            {% endif %}
            <strong>{{ orderItem.item.price.current.formatted }}</strong>

            {# Quantity input — name uses ks[orderItem.id] pattern #}
            {# For gift items, show "1 qty" text instead of input #}
            {% if orderItem.gift %}
                1 {% trans 'template.qty' %}
            {% else %}
                <input type="tel" name="ks[{{ orderItem.id }}]"
                       value="{{ orderItem.amount }}" size="1" min="0" />
            {% endif %}

            {# Total price per item #}
            {% if orderItem.gift %}
                <strong>{% trans 'global.free' %}</strong>
            {% else %}
                <strong>{{ orderItem.priceTotal.current.formatted }}</strong>
            {% endif %}

            {# Remove link — uses ?del= query parameter #}
            {% if not orderItem.gift %}
                <a href="?del={{ orderItem.id }}">{% trans 'cart-popup.item.delete' %}</a>
            {% endif %}
        </div>
    {% endfor %}

    {# Hidden field to advance to delivery step on submit #}
    <input type="hidden" name="toSekce" value="dodani">
</form>
```

### orderItem Properties

| Property | Description |
|---|---|
| `orderItem.product.url` | URL to the product detail page |
| `orderItem.image` | Product image |
| `orderItem.variant.image` | Variant-specific image (if available) |
| `orderItem.item.name` | Product name |
| `orderItem.variantName` | Selected variant name |
| `orderItem.item.price.current.formatted` | Formatted unit price |
| `orderItem.item.price.beforeDiscount.formatted` | Price before discount |
| `orderItem.item.price.discountPercent` | Discount percentage |
| `orderItem.priceTotal.current.formatted` | Total price for the line |
| `orderItem.amount` | Quantity in cart |
| `orderItem.id` | Order item ID (used for quantity input names and removal) |
| `orderItem.gift` | Whether the item is a gift (read-only quantity, free) |
| `orderItem.children` | Child items for bundles/sets |
| `orderItem.flagNew` | Whether the product is flagged as new |
| `orderItem.labels` | Custom product labels |
| `orderItem.freeDelivery` | Whether the item qualifies for free delivery |
| `orderItem.item.availability.text` | Availability text |
| `orderItem.item.availability.hours` | Availability in hours |
| `orderItem.availableUpsells` | Per-item upsell products |

### Per-Item Upsells

Each cart item can offer upsell products (e.g., extended warranty, gift wrapping). These are rendered as checkboxes within the item row:

```twig
{% if orderItem.availableUpsells is not empty and not orderItem.gift %}
    <strong>{% trans 'cart-dialog.upsells.headline' %}</strong>
    {% for upsell in orderItem.availableUpsells %}
        <input type="checkbox" name="upsell[{{ orderItem.id }}]"
               value="{{ orderItem.id }}-{{ upsell.id }}"
               if:checked="upsell.inCart">
        <label>
            {% if upsell.image %}
                <i:img src="upsell.image" format="40x40" fill />
            {% endif %}
            {{ upsell.name }}
            <span>{{ upsell.price.current.formatted }}</span>
        </label>
    {% endfor %}
{% endif %}
```

### Loyalty Program Integration

When the loyalty program is enabled, customers can apply loyalty points to their order:

```twig
{% if customer and this.slaveConfig.enableLoyaltyProgram and cart.useLoyaltyPointsManually %}
    <strong>{% trans 'checkout.points.text' %} {{ customer.userPointsAvailable }}
        {% trans %}user.credits-count{% plural customer.userPointsAvailable %}user.credits-count-plural{% endtrans %}:
    </strong>
    {# Hidden input ensures value submits even when checkbox is unchecked #}
    <input type="hidden" name="uplatnitbody" value="{{ cart.useLoyaltyPoints ? 1 : 0 }}" />
    <input type="checkbox" name="uplatnitBody"
           value="1"
           if:checked="cart.useLoyaltyPoints">
    <label>{% trans 'checkout.points.use' %}</label>
{% endif %}
```

The cart page also shows how many points the order will earn, and prompts unregistered users to sign up:

```twig
{% if this.slaveConfig.enableLoyaltyProgram %}
    {% trans 'checkout.loyalty.you-get' %} {{ cart.loyaltyPoints }}
    {% trans %}user.credits-count{% plural cart.loyaltyPoints %}user.credits-count-plural{% endtrans %}
    {% trans 'checkout.loyalty.discount-to-next-purchase' %}.
    {% if not user %}
        {% trans 'checkout.loyalty.dont-forget' %}
        <a href="{{ iUrl('User/Registrace') }}">{% trans 'checkout.loyalty.register' %}</a>.
    {% endif %}
{% endif %}
```

## Discount Codes

Discount items applied to the cart are displayed using the `cart.discountItems` loop. They appear after the product list in `kosik_obsah.tpl`:

```twig
{% for orderDiscountCart in cart.discountItems %}
    <div class="cartie">
        {# Discount icon from SVG sprite #}
        <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-Discount') }}"></use></svg>

        {# Discount name #}
        {{ orderDiscountCart.name }}

        {# Discount value — either percentage or fixed amount #}
        {% if orderDiscountCart.percent > 0 %}
            <strong>-{{ orderDiscountCart.percent }}%</strong>
        {% elseif orderDiscountCart.price.current.value > 0 %}
            <strong>{{ orderDiscountCart.price.current.formatted }}</strong>
        {% endif %}

        {# Remove discount link — uses ?delSleva= query parameter #}
        <a href="?delSleva={{ orderDiscountCart.id }}">
            {% trans 'cart-popup.item.delete' %}
        </a>
    </div>
{% endfor %}
```

The voucher code input is typically placed in the order summary sidebar (`kosik_souhrn.tpl`), sending the code via the `slev_kod` form field.

## Gift Selection

When gift selection is enabled in the shop configuration, the cart content step includes a gift picker partial:

```twig
{% if this.slaveConfig.enableGifts %}
    {% include 'kosik_darky.tpl' %}
{% endif %}
```

## Order Summary Sidebar

Each checkout step includes the order summary sidebar by passing a `checkout` context variable that controls what the sidebar displays (totals, buttons, voucher input):

```twig
{# In kosik_obsah.tpl (cart content step) #}
{% include 'kosik_souhrn.tpl' with {'checkout': 'products'} %}

{# In kosik_dodani.tpl (delivery step) #}
{% include 'kosik_souhrn.tpl' with {'checkout': 'delivery'} %}
```

The sidebar adapts its content based on the `checkout` variable — showing different submit buttons and information depending on the current step.

## Variant Selection

Enabling variant selection in the cart detail requires three steps:

1. In config.json, list the supported selection modes (dropdown, icons, ...)
2. In the shop admin panel, define the steps (which attribute set uses which selection mode, labels, ...)
3. In the template, implement `i:variant-choice`

### i:variant-choice

The i:variant-choice tag is used inside the add-to-cart form. It handles rendering the required number of steps, progressive loading of steps, pre-selection based on URL or customer preferences, URL updates on selection, etc.

**Important elements:**

* *else* branch - if multiple selection modes are supported, one (ideally the simplest, such as a dropdown) should be in the *else* branch. If the template only accounts for certain modes and the shop expects different ones, purchasing would be impossible -- the final *else* branch ensures the purchase can still proceed.
* `data-role="step"` - wrapper defining individual steps; when loading choices based on the current selection, only the subsequent steps are replaced
* `reload-targets` - classes (or CSS selector) of elements that should be updated on each selection change -- typically images, price, availability, etc. These elements must first be marked with *i:dynamic* in the template.
* `step.inputName`, `choice.inputValue` - name/value for the form input. Whether a select or radio is used is up to the template.
* `choice.image` - product or variant image (typically a product photo), not available everywhere
* `choice.icon` - image uploaded for the attribute set (typically an icon)
* `choice.color` - HEX color code set on the attribute value

```twig
<i:variant-choice product="product" reload-targets=".js_var_change_example">
    {%for step in product.variantChoiceSteps%}
    <div data-role="step">
        {%if step.mode == 'icons'%}
            <h5>{{step.headline}}</h5>
            <ul>
                {%for choice in step.choices%}
                    <li>
                        <label for="color-{{choice.inputValue}}" title="{{choice.name}}" class="custom-tooltip" i:href="{{choice}}">
                            <input name="{{step.inputName}}" type="radio" value="{{choice.inputValue}}" required data-msg-required="{{step.messageEmpty}}" if:checked="choice.selected">
                            {%if choice.image%}
                                <i:img src="choice.image" format="50x50" fill lazyload/>
                            {%elseif choice.icon%}
                                <i:img src="choice.icon" format="50x50" fill vector lazyload/>
                            {%elseif choice.color%}
                                <span style="background-color: {{choice.color}}"/>
                            {%endif%}
                            {{choice.name}}
                        </label>
                    </li>
                {%endfor%}
            </ul>
        {%else%}
            <h5>{%if step.headline%}{{step.headline}}{%else%}{%trans%}Vyberte variantu{%endtrans%}{%endif%}</h5>
            <select name="{{step.inputName}}" required>
                <option value="">{{step.placeholder}}</option>
                {%for choice in step.choices%}
                    <option value="{{choice.inputValue}}" if:selected="choice.selected">
                        {{choice.name}}
                    </option>
                {%endfor%}
            </select>
        {%endif%}
    </div>
    {%endfor%}
</i:variant-choice>
```

---

---
url: /components.md
---
# Components

::: info
Automatically generated from PHP attributes by the `shop:template:documentation` command. CSS must not rely on the generated HTML output of components - it may change in future versions.
:::

## i:gdpr-form

GDPR consent checkbox/text inserted into parent forms

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| codes | string | no |  | GDPR form codes to display (comma-separated) |
| context | cart-sign-up | footer | sidebar | no |  | Override auto-detected context |
| list | boolean | no |  | Render as \<li> elements without wrapper div |

::: info
Self-closing tag, must have no children. Context is auto-detected from the parent form component (newsletter-signup, user-signup, contact form). Use the codes attribute only when you need specific GDPR forms regardless of context.
:::

**Auto-detected context (inside newsletter-signup, user-signup, or contact form)**

```twig
<i:gdpr-form />
```

**Explicit GDPR form codes**

```twig
<i:gdpr-form codes="newsletter_consent,marketing" />
```

Generated output:

```html
<div>gdprForm({"codes":["newsletter_consent","marketing"]})</div>
```

## i:newsletter-signup

Newsletter subscription form

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| redirect | string | no |  | Redirect URL after successful signup |
| autohide | boolean | no |  | Hide form for already subscribed visitors |
| ignore-duplicated | boolean | no |  | Silently ignore duplicate subscriptions |
| confirm-template | string | no |  | Email template ID for confirmation (numeric, requires discount) |
| discount | string | no |  | Discount set ID(s) for coupon code (comma-separated, requires confirm-template) |

| Role | Tag | Required | Description |
|---|---|---|---|
| email | input | yes | Email address input |
| first\_name | input | no | First name |
| last\_name | input | no | Last name |
| street | input | no | Street address |
| city | input | no | City |
| zip | input | no | Postal code |
| country | input | no | Country code (cz, sk, ...) |
| source | input|select | no | Newsletter source (for external system integrations) |
| gender | input | no | Gender radio buttons (value: m or f) |
| submit | button | yes | Submit button |

::: info
When using discount attribute, the confirm-template attribute is also required. The email template can use {{discountCode}} for a single code or discountCodes array keyed by set ID for multiple codes.
:::

**Minimal newsletter form with GDPR consent**

```twig
<i:newsletter-signup>
<input data-role="email" data-label="Your email">
<i:gdpr-form />
<button data-role="submit">Subscribe</button>
</i:newsletter-signup>
```

Generated output:

```html
<form method="POST" action="/w/~Prijemce_Pridat/save/?uri=%2F" data-component="newsletter-signup">
<label for="email_uid">trans:Your email</label><input id="email_uid" name="email" type="email" required="required">
<div>gdprForm({"context":"newsletter-signup"})</div>
<div class="global-newsletter-url"><label for="newsletter_uid">trans:URL</label><input type="url" id="newsletter_uid" name="url"></div>
<button type="submit">trans:Subscribe</button>
</form>
```

**Newsletter form with extra fields and redirect**

```twig
<i:newsletter-signup redirect="/thank-you">
<input data-role="email" data-label="Your email">
<input data-role="first_name" data-label="First name">
<i:gdpr-form />
<button data-role="submit">Subscribe</button>
</i:newsletter-signup>
```

Generated output:

```html
<form method="POST" action="/w/~Prijemce_Pridat/save/?uri=%2F" data-component="newsletter-signup">
<label for="email_uid">trans:Your email</label><input id="email_uid" name="email" type="email" required="required">
<label for="first_name_uid">trans:First name</label><input id="first_name_uid" name="first_name" type="text">
<div>gdprForm({"context":"newsletter-signup"})</div>
<div class="global-newsletter-url"><label for="newsletter_uid">trans:URL</label><input type="url" id="newsletter_uid" name="url"></div>
<button type="submit">trans:Subscribe</button>
<input type="hidden" name="redirect" value="/thank-you"></form>
```

## i:search-form

Product search form with autocomplete support

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| autocomplete | boolean | no |  | Enable search autocomplete |
| min-length | string | no | 3 | Minimum characters before autocomplete triggers |
| template | string | no |  | Template name for search results (alphanumeric/underscore) |
| img-format | string | no |  | Image format for autocomplete results (e.g. "60x60") |

| Role | Tag | Required | Description |
|---|---|---|---|
| search | input | yes | Search text input |
| submit | button | yes | Submit button |

::: info
Autocomplete results template is in `ajax/search.tpl` (or custom file via template attribute). The template receives variable `q` with the search query. Each result link must have `tabindex` and `data-result-type` (product, category, brand, more) attributes. Style the `search-current-item` CSS class for keyboard navigation highlight.
:::

::: info
Fires `autocomplete:loaded` event on the form element after each autocomplete results load.
:::

**Search form with autocomplete**

```twig
<i:search-form autocomplete>
<input data-role="search" data-label="Search">
<button data-role="submit">Search</button>
</i:search-form>
```

Generated output:

```html
<form data-min-length="3" action="Vypis/Vyhledavani" method="GET" data-component="product-search" data-autocomplete>
<label for="search_uid">trans:Search</label><input id="search_uid" type="search" name="fraze" required="required" minlength="2" autocomplete="off">
<button type="submit">trans:Search</button>
</form>
```

## i:comment-form

Comment/review form for products, articles, and categories with proof-of-work spam protection

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| object | expression | yes |  | Variable with the commentable object (product, article, or category) |

| Role | Tag | Required | Description |
|---|---|---|---|
| text | textarea | no | Comment text |
| title | input | no | Comment headline |
| rating | select | no | Star rating 1-5 (products only, options auto-generated) |
| author | input | no | Author name |
| email | input | no | Author email |
| phone | input | no | Author phone |
| parent | input | no | Parent comment ID for threaded replies (auto-set as hidden) |
| submit | button | yes | Submit button |

::: info
Spam protection uses proof-of-work (no CAPTCHA needed). The form submits via AJAX automatically. Rating select options (stars) are auto-populated. For threaded replies, set parent slot value to the parent comment ID.
:::

**Basic product comment**

```twig
<i:comment-form object="product">
<input data-role="author" data-label="Name">
<textarea data-role="text" data-label="Comment"></textarea>
<button data-role="submit">Submit</button>
</i:comment-form>
```

Generated output:

```html
<form method="POST" action="/api/comments" data-component="comment-form">
<label for="author_uid">trans:Name</label><input id="author_uid" name="author" type="text" autocomplete="name">
<label for="text_uid">trans:Comment</label><textarea id="text_uid" name="text"></textarea>
<button type="submit">trans:Submit</button>
<input name="commentType" type="hidden" value="zbozi">
<input name="objectId" type="hidden" value="123">
</form>
```

**Product review with all fields**

```twig
<i:comment-form object="product">
<input data-role="author" data-label="Name">
<input data-role="email" data-label="Email">
<input data-role="title" data-label="Headline">
<textarea data-role="text" data-label="Review"></textarea>
<button data-role="submit">Submit review</button>
</i:comment-form>
```

Generated output:

```html
<form method="POST" action="/api/comments" data-component="comment-form">
<label for="author_uid">trans:Name</label><input id="author_uid" name="author" type="text" autocomplete="name">
<label for="email_uid">trans:Email</label><input id="email_uid" name="email" type="email" autocomplete="email">
<label for="title_uid">trans:Headline</label><input id="title_uid" name="title" type="text">
<label for="text_uid">trans:Review</label><textarea id="text_uid" name="text"></textarea>
<button type="submit">trans:Submit review</button>
<input name="commentType" type="hidden" value="zbozi">
<input name="objectId" type="hidden" value="456">
</form>
```

## i:list-empty

Defines the empty-state template macro shown when listing has no results

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| type | product | article | actuality | yes |  | Listing type |
| name | string | no | default | Empty template macro name |

**Empty state with separate messages for filtered and default states**

```twig
<i:list-item type="product">{{product.name}}</i:list-item><i:list-empty type="product"><p data-role="default">No products found.</p><p data-role="filter">No products match your filter.</p></i:list-empty><i:list-container type="product"><div data-role="empty"></div><div data-role="list"></div></i:list-container>
```

Generated output:

```html
<div data-type="product" data-list-config="eyJjb250ZW50R3JvdXBJZCI6bnVsbCwiY3VycmVudFBhZ2UiOm51bGwsInBlclBhZ2UiOm51bGwsInNvcnQiOm51bGx9" data-component="list-container"><div data-role="empty"><p>trans:No products found.</p></div><div data-role="list"></div></div><script>{inline-listing-loaded};</script>
```

## i:list-item

Defines the template macro for a single item in a listing

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| type | product | article | actuality | yes |  | Type of item |
| tag | string | no | div | HTML tag to wrap each item |
| name | string | no | default | Macro name (must match list-container name) |

**Basic product item template**

```twig
<i:list-item type="product"><h3>{{product.name}}</h3></i:list-item>{{_self.item_product_default(product)}}
```

Generated output:

```html
<div data-track="123|0||" data-oid="p123"><h3>name</h3></div>
```

## i:list-container

Main listing container that fetches items from a repository and renders them with pagination

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| type | product | article | actuality | yes |  | Type of items to display |
| source | expression | no |  | Custom repository query parameters as JSON object (e.g. {category: kategorie.id, limit: 8}) |
| collection | expression | no |  | Custom Twig collection to iterate over instead of repository |
| name | string | no | default | Template macro name for the item box |
| wrap | string | no |  | Wrap items in groups (e.g. "3:div.row" wraps every 3 items in a div.row) |
| append | string | no |  | Insert elements at positions (e.g. "3:div.spacer") |
| insert-before | string | no |  | Insert macro name to call before each item |
| insert-after | string | no |  | Insert macro name to call after each item |
| hide-empty | boolean | no |  | Hide the entire container when no items found (instead of showing empty slot) |
| scroll-offset | string | no |  | Offset for scroll-to behavior |
| analytics-name | string | no |  | Analytics identifier for tracking |

| Role | Tag | Required | Description |
|---|---|---|---|
| list | div | yes | Container for rendered items (must be empty) |
| empty |  | no | Shown when no items found (required unless hide-empty) |
| pagination | div | no | Pagination controls (can have multiple) |

**Default product listing**

```twig
<i:list-item type="product">{{product.name}}</i:list-item><i:list-empty type="product">No products found</i:list-empty><i:list-container type="product"><div data-role="list"></div><div data-role="empty"></div></i:list-container>
```

Generated output:

```html
<div data-type="product" data-list-config="eyJjb250ZW50R3JvdXBJZCI6bnVsbCwiY3VycmVudFBhZ2UiOm51bGwsInBlclBhZ2UiOm51bGwsInNvcnQiOm51bGx9" data-component="list-container"><div data-role="list"><div data-track="123|0|1|" data-oid="p123">abc</div></div><div data-role="empty"></div></div><script>{inline-listing-loaded};</script>
```

**Custom product listing with category filter**

```twig
<i:list-container type="product" source="{category: kategorie.id, limit: 4}">
<div data-role="list"></div>
<div data-role="empty">No products</div>
</i:list-container>
```

## i:list-pagination

Defines the pagination template macro for listings

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| type | product | article | actuality | yes |  | Listing type |
| name | string | no | default | Pagination macro name |

| Role | Tag | Required | Description |
|---|---|---|---|
| add-page | a | no | Load-more button, shown when next page exists |

**Simple load-more pagination**

```twig
<i:list-pagination type="product">
<a data-role="add-page">Load more</a>
</i:list-pagination>
```

## i:list-dynamic

Dynamic content area within a listing that renders content based on type (headline, text, subcategories)

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| type | headline | text | subcategories | other | yes |  | Type of dynamic content |
| variables | string | yes |  | Twig variables to pass to the dynamic content |

**Category headline in listing**

```twig
<div i:list-dynamic type="headline" variables="kategorie">{{ kategorie.name }}</div>
```

## i:banners

Banner/slider component with responsive images, CTA buttons, and carousel support

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| source | expression | yes |  | Twig expression returning banner collection |
| class | string | no |  | CSS class for the banner wrapper |
| plugin | string | no |  | Slider plugin name (e.g. "swiper") |
| click | cta | banner | off | auto | no | auto | Click behavior - CTA button, whole banner, disabled, or auto |
| visible-slides | string | no | 1 | Number of visible slides |
| priority | string | no | high | Loading priority (high = no lazy load for visible slides) |
| wrap | string | no |  | Wrapper element (e.g. "div.banner-inner") |
| arrows | boolean | no |  | Show navigation arrows |
| dots | boolean | no |  | Show pagination dots |
| thumbnails | boolean | no |  | Show thumbnail navigation |
| progress | boolean | no |  | Show progress bar |
| transparent | boolean | no |  | Preserve image transparency |
| fill | boolean | no |  | Use object-fit: cover on images |

**Responsive hero banner with Swiper plugin**

```twig
<i:banners source="banners" class="hero-banner" plugin="swiper" arrows dots><source format="1200x400" src="desktop"/><source format="400x300" src="mobile"/></i:banners>
```

Generated output:

```html
<div class="banner hero-banner swiper-container">
<div class="banner-wrap swiper-wrapper">
<div class="banner-item banner--item__1 banner--item__first banner--item__last swiper-slide">
<picture>
<source srcset="https://i00.eu/img/999999/400x300/b70ltmq7/17.webp 1x,https://i00.eu/img/999999/800x600c/14pro84s/17.webp 2x" media="(max-width: 400px)">
<img width="730" height="400" srcset="https://i00.eu/img/999999/1200x400/eb9g3pmd/17.webp 1x,https://i00.eu/img/999999/2400x800c/aergzgi6/17.webp 2x" src="https://i00.eu/img/999999/1200x400/eb9g3pmd/17.webp">
</picture>
</div>
</div>
<div class="pagination swiper-pagination"></div>
<div class="button-next swiper-button-next"></div>
<div class="button-prev swiper-button-prev"></div>
</div>
```

## i:menu

Defines a menu macro in \_menu.tpl, rendered by i:menu-container

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | yes |  | Menu macro name (must match i:menu-container name) |

::: info
Must be defined in \_menu.tpl file. The `lazy` variable is automatically passed by i:menu-container - use it to skip rendering deep submenus that will be loaded via AJAX. Menu output is cached, so use `active_menu_placeholder_class('className', category)` for active state instead of Twig conditionals. Also accepts a route hash like `active_menu_placeholder_class('active', 'Vypis/Slevy')` for page type matching.
:::

**Two-level category menu with active class and lazy support**

```twig
<i:menu name="main">
<ul>
{% for category in repository.category.findBy({'parent': 0}) %}
<li class="{{ active_menu_placeholder_class('active', category) }}">
<a href="{{ category.url }}">{{ category.name }}</a>
{% if not lazy and category.subcategories is not empty %}
<ul>
{% for sub in category.subcategories %}
<li class="{{ active_menu_placeholder_class('active', sub) }}">
<a href="{{ sub.url }}">{{ sub.name }}</a>
</li>
{% endfor %}
</ul>
{% endif %}
</li>
{% endfor %}
</ul>
</i:menu>
```

## i:menu-container

Category menu container that loads menu from \_menu.tpl template with optional lazy loading

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | yes |  | Menu macro name defined in \_menu.tpl |
| tag | string | no | div | HTML wrapper tag |
| lazy | boolean | no |  | Load menu asynchronously via AJAX |

::: info
Must be an empty element (no children). With `lazy`, the non-lazy part renders server-side and the full menu loads via AJAX, significantly improving page speed. Fires `menu:load` event on the container element after async load completes.
:::

**Lazy-loaded main navigation menu**

```twig
<div><i:menu-container name="main" tag="div" lazy /></div>
```

Generated output:

```html
<div><div id="js-menu-uid">trans:hello</div><script>(function(){var x=new XMLHttpRequest();x.open("GET","/ajax-menu-url");x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.send();x.onreadystatechange=function(){if(4===x.readyState){var t=x.responseText;var l=JSON.parse(document.body.dataset["activeCategories"]),r=document.body.dataset["routeHash"];for(var i=0;i<l.length;i++)t=t.replace(new RegExp("([a-zA-Z0-9\-_]+)\-menu\-class\-placeholder\-"+l[i]+"([^0-9])","g"),"$1$2");t=t.replace(new RegExp("([a-zA-Z0-9\-_]+)\-menu\-class\-placeholder\-"+r+"([^0-9a-z])","g"),"$1$2");document.getElementById("js-menu-uid").innerHTML=t.replace(new RegExp("[a-zA-Z0-9\-_]+\-menu\-class\-placeholder\-[0-9]+","g"),"");const event = document.createEvent("CustomEvent");event.initCustomEvent("menu:load", true, true, {});document.getElementById("js-menu-uid").dispatchEvent(event);}};})()</script></div>
```

**Sidebar menu rendered as list**

```twig
<div i:menu-container name="sidebar" tag="ul"></div>
```

## i:delivery-transports

Container for transport/shipping options in the checkout process

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| tag | string | no | div | HTML wrapper tag |
| reload-targets | string | no |  | CSS selectors of elements to reload when transport changes |

**Transport selection in checkout**

```twig
<i:delivery-transports>{% for transport in cart.availableTransportMethods %}<i:delivery-transport transport="transport" tag="div"><input name="transport" type="radio" />{{ transport.name }}<i:delivery-branch button-text="Choose branch" /></i:delivery-transport>{% endfor %}</i:delivery-transports>
```

Generated output:

```html
<div data-component="delivery-transports" data-dynamic-content="7eNRw6uOGJUoTV9lG4yoJ7tzbjZVbB5agwTz0Ph+6ks="><div data-component="delivery-transport"><input name="transport" type="radio" value="7">PPL<div data-component="delivery-branch"><input type="hidden" name="pobocka[zasilkovna_stat_1000]" value="5" data-config='{"type":"ppl"}' data-branch='{"code":5,"label":"Drtinova 10"}' data-excluded-places="[]"><span>Drtinova 10</span> <a href="#">trans:Choose branch</a></div></div></div>
```

## i:delivery-transport

Single transport option within delivery-transports

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| transport | expression | yes |  | Twig expression for the transport object from cart.transports loop |
| tag | string | yes |  | HTML wrapper tag |

**Transport option with branch selection**

```twig
<i:delivery-transport transport="transport" tag="label"><input name="transport" type="radio" />{{ transport.name }}<i:delivery-branch button-text="Choose pickup point" /></i:delivery-transport>
```

Generated output:

```html
<label data-component="delivery-transport"><input name="transport" type="radio" value="3">PPL<div data-component="delivery-branch"><input type="hidden" name="pobocka[ppl_cz]" data-config='{"type":"ppl"}' data-excluded-places="[]"><span></span> <a href="#">trans:Choose pickup point</a></div></label>
```

## i:delivery-payments

Container for payment method options in the checkout process

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| tag | string | no | div | HTML wrapper tag |
| reload-targets | string | no |  | CSS selectors of elements to reload when payment changes |

**Payment method selection in checkout**

```twig
<i:delivery-payments>{% for payment in cart.availablePaymentMethods %}<i:delivery-payment payment="payment" tag="label"><input name="payment" type="radio" />{{ payment.name }}</i:delivery-payment>{% endfor %}</i:delivery-payments>
```

Generated output:

```html
<div data-component="delivery-payments" data-dynamic-content="7eNRw6uOGJUoTV9lG4yoJ7tzbjZVbB5agwTz0Ph+6ks="><label data-component="delivery-payment"><input name="payment" type="radio" value="7">Credit card</label></div>
```

## i:delivery-payment

Single payment method option within delivery-payments

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| payment | expression | yes |  | Twig expression for the payment object from cart.payments loop |
| tag | string | yes |  | HTML wrapper tag |

**Payment option with radio button**

```twig
<i:delivery-payment payment="payment" tag="label"><input name="payment" type="radio" />{{ payment.name }}</i:delivery-payment>
```

Generated output:

```html
<label data-component="delivery-payment"><input name="payment" type="radio" value="5">Credit card</label>
```

## i:delivery-branch

Pickup point/branch selector within a delivery-transport (renders branch select widget)

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| transport | expression | yes |  | Transport object reference (auto-set by parent delivery-transport) |
| button-text | string | yes |  | Text for the branch selection button (translatable) |

**Branch selector (must be inside i:delivery-transport)**

```twig
<i:delivery-branch button-text="Choose pickup point" />
```

## i:filter-form

Defines a filter form template macro for product/article filtering

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | yes |  | Filter form macro name (referenced by filter-placeholder) |
| auto-scroll | string | no |  | Scroll to listing after filter change |

| Role | Tag | Required | Description |
|---|---|---|---|
| reset | a | no | Filter reset link/button (hidden when no filter is active) |

**Basic filter form with reset button**

```twig
<i:filter-form name="default">
<a data-role="reset">Reset filters</a>
{% for attr in attributes %}
<i:filter-attribute attribute="attr" />
{% endfor %}
</i:filter-form>
```

## i:filter-placeholder

Renders a filter-form macro at a specific location with given configuration

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | yes |  | Filter form macro name (must match a filter-form name) |
| config | string | yes |  | Filter configuration code |
| hide-empty | boolean | no |  | Hide the filter form when no filter attributes are available |
| always-collapsed | boolean | no |  | Render all filter groups initially collapsed |

**Render default filter form, hidden when empty**

```twig
<i:filter-placeholder name="default" config="default" hide-empty />
```

## i:variant-choice

Product variant selector with step-by-step attribute selection

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| data-product | expression | yes |  | Product ID expression |
| reload-targets | string | no |  | CSS selectors of elements to reload when variant changes |

| Role | Tag | Required | Description |
|---|---|---|---|
| step |  | yes | Container for each variant selection step |

**Variant selector with color/size steps**

```twig
<div i:variant-choice data-product="{{product.id}}" i:dynamic="product" reload-targets=".product-price,.product-availability">
{% for step in product.variantChoice.steps %}
<div data-role="step">
<strong>{{ step.name }}:</strong>
{% for value in step.values %}
<button>{{ value.name }}</button>
{% endfor %}
</div>
{% endfor %}
</div>
```

## i:dynamic

Wraps content for dynamic (AJAX) reloading when server-side state changes

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| variables | string | yes |  | Comma-separated Twig variables that trigger re-render |
| lazy | none | auto | manual | no | none | Lazy loading mode - none (server-rendered), auto (lazy on page load), manual |

**Cart summary that updates dynamically**

```twig
<i:dynamic variables="order">Order #{{ order.id }}</i:dynamic>
```

Generated output:

```html
<div data-dynamic-content="+U8r+mkvbR7EJVHWtAmbvIN9KvgnUinu7XHN9oUfE9Nb6OKzPQzr8vs6btDlfyPu1PqQ3yj1hmwFpfxEwO5Lxg==">Order #7</div>
```

## i:img

Responsive image with automatic srcset, DPR-aware rendering, and lazy loading

| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
| src | expression | yes |  | Twig expression returning an Image object (e.g. product.image) |
| format | string | yes |  | Dimensions WxH or comma-separated list (e.g. "359x479" or "800x600,400x300") |
| sizes | string | no |  | HTML sizes attribute (required when multiple formats) |
| fill | boolean | no |  | Use object-fit: cover |
| vector | boolean | no |  | SVG source - skip bitmap optimization |
| transparent | boolean | no |  | Preserve transparency (PNG/WebP instead of JPEG) |
| watermark | boolean | no |  | Apply watermark overlay |
| quality | low | normal | high | lossless | no |  | Compression quality |
| loading | string | no |  | Loading strategy (lazy/eager) |
| lazyload | boolean | no |  | Enable lazy loading |

**Basic product image**

```twig
<i:img src="product.img" format="100x100" fill />
```

Generated output:

```html
<img alt="description" width="100" height="100" srcset="http://100x100f.jpg 1x,http://200x200fc.jpg 2x" src="http://100x100f.jpg">
```

**Lazy-loaded lifestyle image variant**

```twig
<i:img src="product.image('lifestyle')" format="800x600" fill loading="lazy" />
```

**SVG brand logo**

```twig
<i:img src="brand.image" format="200x100" vector transparent fill />
```

---

---
url: /config.md
---
# Configuration

Every template can contain a **config.json** file describing template properties. Some properties are automatically generated (*plugins*, ...) and others can be modified manually.

## Configuration Reference

**config.json Attributes**

| Attribute | Type | Default | Description |
|---|---|---|---|
| **responsive** | *bool* | **false** | template is responsive -- activates viewport meta tag |
| **webfonts** | *array* | **\[]** | list of Google WebFonts |
| **webfontsPreload** | *array* | **\[]** | list of Google WebFonts to preload |
| **features** | *array* | **\[]** | list of supported special features (*last\_viewed\_products*) |
| **cartSteps** | *array* | **\[]** | checkout steps in the order they appear |
| **typekit** | *string* | --- | Typekit font ID |
| **skipOrderSummary** | *bool* | **false** | skip the *Checkout summary* step |
| **countryBeforeDelivery** | *bool* | **false** | delivery country is selected in the step before delivery method selection |
| **wysiwyg** | *object* | {} | list of CSS classes (and CSS rules) used in the WYSIWYG editor |
| **settings** | *object* | {} | admin-configurable template settings definition |
| **fulltext** | *bool* | **true** | allow search engine indexing |
| **mobile** | *bool* | **false** | template is mobile-only |
| **viewportDesktop** | *int* | --- | viewport width when forcing desktop version on a responsive layout |
| **skipOnFirstPage** | *object* | --- | how many listing items to **skip** on the first page of listings |
| **limitOnFirstPage** | *object* | --- | how many listing items to **display** on the first page of listings |
| **inputInLabel** | *bool* | **true** | wrap *checkbox*/*radio* inside *label* in generated forms |
| **manifest** | *object* | --- | definition for [manifest.json](https://developer.mozilla.org/en-US/docs/Web/Manifest) |
| **allowedPagination** | *array* | --- | list of allowed pagination size values |
| **criticalCss** | *object* | --- | per-page-type critical CSS generation hints (forceInclude, forceExclude, viewports) |
| **variantChoice** | *object* | --- | supported variant selection types |

### features

* *last\_viewed\_products*: visited products are stored so they can be listed in the template
* *multiline\_menu\_items*: category names for the menu can be saved with line breaks in the admin
* *upsell\_customer\_note*: upsell supports customer note input
* *upsell\_customer\_upload*: upsell supports customer file upload
* *google\_recaptcha\_enterprise\_cart*: Google reCaptcha Enterprise in the cart

### cartSteps

If the shop uses multiple checkout steps (visible in the URL as e.g. `/Kosik?sekce=adresa`), they must be listed in the configuration. The `/Kosik` (cart) and `/Pokladna` (checkout) paths themselves are not listed -- only the additional query parameters. Each step specifies a code identifying the content of that particular step (content, delivery, address, summary).

```json
{
  "cartSteps": [
    {
      "handles": [
        "content"
      ]
    },
    {
      "handles": [
        "delivery"
      ],
      "query": "dodani"
    },
    {
      "handles": [
        "address"
      ],
      "query": "adresa"
    }
  ]
}
```

### fields

Text types defined in the config are displayed as text fields in the admin panel. Once filled in, they are available in the template via `object.text('vlastni_kod_textu')` (custom text code). The config also specifies the field label shown in the admin and a description of where the text appears and any constraints it may have.

Supported objects: **transport**, **paymentMethod**, **textPage**, **store**, **admin**, **category**, **brand**, **product**, **author**, **upsellGroup**, **article**

Supported formats: **html**, **textarea**, **text**

```json
{
    "fields": {
        "transport": {
            "text": {
                "short" : {
                    "label": "Krátký popisek",
                    "format": "html",
                    "description": "Zobrazuje se košíku po najetí myší na způsob dopravy"
                },
                "long" : {
                    "label": "Dlouhý popis",
                    "format": "html",
                    "description": "Zobrazuje se na informační stránce a může mít 2-3 odstavce"
                }
            },
            "image": {
                "ico" : {
                    "label": "Ikonka výběru",
                    "description": "Zobrazuje se košíku po najetí myší na způsob dopravy"
                }
            }
        }
    }
}
```

### criticalCss

Per-page-type hints for the critical CSS generator. Each key is a page type matching the types returned by `/_random`:

| Page Type | Description |
|---|---|
| **index** | Homepage |
| **product** | Product detail (random products are sampled) |
| **category** | Top-level category listing |
| **subcategory** | Nested category listing |
| **page** | Static text pages |

Each type supports the following options:

| Option | Type | Description |
|---|---|---|
| **forceInclude** | *array* | CSS selectors always included in the output (substring match) |
| **forceExclude** | *array* | CSS selectors always excluded from the output (substring match) |
| **viewports** | *object* | Override default viewport sizes for this type |

Matching is substring-based — `".main-banner"` matches `.main-banner`, `.main-banner__slide`, `.page .main-banner`, etc.

The following selectors are always applied regardless of config:

* **Always included:** `.no-js`, `.global-announcement` (and BEM variants)
* **Always excluded:** `.wf-active` (web fonts loaded after critical render)

Default viewports are **mobile: 380×650** and **desktop: 1000×600**. Per-type viewports override these for that type only:

```json
{
    "criticalCss": {
        "index": {
            "forceInclude": [".main-banner", ".hero-slider"],
            "forceExclude": [".video-player"]
        },
        "product": {
            "forceInclude": [".product-gallery"],
            "viewports": {
                "mobile": { "width": 414, "height": 896 }
            }
        }
    }
}
```

## Configuration Example

```json
{
    "webfonts":[
        "Open Sans:400,600,700"
    ],
    "webfontsPreload":[
        "Open Sans:400,700"
    ],
    "responsive": true,
    "wysiwyg": [
        {
            "name": "important paragraph",
            "css": "p.wysiwyg_important {color: #F5007E;}"
        },
        {
            "name": "small paragraph",
            "css": "p.wysiwyg_small {font-size:0.9em}"
        }
    ],
    "skipOnFirstPage": {
        "categoryProducts": 1,
        "filteredCategoryProducts": 0,
        "topicArticles": 1,
        "allArticles": 2
    },
    "limitOnFirstPage": {
        "categoryProducts": 1,
        "filteredCategoryProducts": 0,
        "topicArticles": 1,
        "allArticles": 2
    },
    "manifest": {
        "display": "standalone",
        "background_color": "#ff00ff",
        "theme_color": "#ff00ff",
        "tile_color": "#ff00ff",
    },
    "settings": {
        "menu_mode": {
          "label": "Režim menu",
          "context": "global",
          "default": "small",
          "type": "select",
          "group": "Levý sloupec",
          "values": {
            "small": "malé menu",
            "big": "velké menu"
          }
        }
    },
    "criticalCss": {
        "index": {
            "forceInclude": [".main-banner"],
            "forceExclude": [".video-player"]
        },
        "product": {
            "forceInclude": [".product-gallery"]
        }
    },
    "variantChoice": {
        "code": "default",
        "modes": {
            "dropdown": "roletka s názvy",
            "icons": "obrázky s názvem"
        }
    }
}
```

## Settings

The *settings* section lets you define template values that can be configured directly from the admin panel. Use cases include toggling visual elements (e.g. winter theme), setting footer links, or selecting a display mode per category.

**context**

| Value | Description |
|---|---|
| **global** | available across the entire shop |
| **category** | category-specific, configured separately for each category |
| **product\_category** | configured separately for each category, applied on the product detail page |

**type**

| Value | Description |
|---|---|
| **select** | generic dropdown |
| **string** | text (single line, no HTML) |
| **color** | color (hex code) |
| **email** | e-mail |
| **text\_page** | text page |
| **article** | article |
| **article\_topic** | article topic |
| **banner\_section** | banner section |
| **upsell\_group** | upsell group |
| **attribute\_group** | attribute group |
| **attribute** | attribute |
| **attribute\_article** | article attribute |
| **attribute\_store** | store attribute |
| **attribute\_customer** | customer attribute |
| **category** | category |
| **product** | product |
| **product\_list** | product selection by properties |
| **product\_rules** | product group rules |
| **url** | any shop URL (including link text and title) |
| **admin** | shop administrator |
| **storage\_center** | storage center |
| **store** | store |
| **working\_hours** | opening hours |
| **image** | uploaded image (SVG/PNG/JPG/...) |

Configuration example:

```js
{
    "settings": {
        "sibebar_mode": {
          "label": "Režim postraního panelu",
          "description": "Přepínání způsobu zobrazení levého sloupce webu",
          "context": "global",
          "default": "small",
          "group": "Levý sloupec",
          "type": "select",
          "values": {
            "small": "malé menu",
            "big": "velké menu"
          }
        },
        "category_mode": {
          "label": "Režim zobrazení kategorie",
          "context": "category", // configured separately for each category
          "default": "default",
          "type": "select",
          "values": {
            "default": "standardní zobrazení",
            "big_banner": "zobrazit s velkým bannerem"
          }
        },
        "product_mode": {
          "label": "Režim zobrazení produkt",
          "context": "product_category", // configured separately for each category, applied on product detail
          "default": "default",
          "type": "select",
          "values": {
            "default": "standardní zobrazení",
            "big_banner": "zobrazit s velkým bannerem"
          }
        },
        "footer_menu": {
          "label": "Položky patičky",
          "context": "global", // site-wide
          "type": "text_page", // select a text page
          "lang": true, // configured separately for each language -- adding lang:true hides the originally set value
          "multiple": true // select multiple pages with ordering (the template receives an array of pages)
        }
    }
}
```

Usage in the template:

```twig
{% if this.templateAttributes.sibebar_mode == 'small' %}
    malý sidebar
{% endif%}
```

## Master Template

A master template serves as a base for other templates. It defines a list of variables that child (slave) templates can override.

Configuration example:

```json
{
    "master" : {
        "tpl": {
            "phone": {
                "name": "Telefon",
                "default": "+420 333 222 111"
            },
            "email": {
                "name": "E-mail",
                "type": "email",
                "language": true,
                "default": "info@example.org"
            },
            "facebook": {
                "name": "Facebook URL",
                "type": "url"
            },
            "showRelevantItems": {
                "name": "Zobrazit nabídku podobných produktů",
                "type": "bool"
            },
            "pageFooterId": {
                "name": "Text v patičce",
                "type": "page"
            },
            "listStyle": {
                "name": "Stype výpisu produktů",
                "type": "select",
                "values" : {
                    "simple": "jednoduchý",
                    "large_image": "velké obrázky",
                }

            }
        },
        "sass": {
            "primary-color": {
                "name": "Hlavní odstín",
                "type": "color",
                "default": "#fff",
                "group": "Barvy"
            }
        },
        "files": {
            "banner.png": "Obrázek v hlavičce"
        },
        "languageFiles": {
            "logo.png": "Logo eshopu"
        }
    }
}
```

To use variables in SASS, add the line `//<SLAVE-CONFIG>//` anywhere in *settings.scss*. During compilation this line is replaced with the configuration variables.

```scss
$pagination-mobile-items: true;
$pagination-arrows: false;
//<SLAVE-CONFIG>//
```

A slave template is activated by deleting all files and adding a **slave.json** file:

```json
{
    "master": "master-template-name"
}
```

## Complete Production Config Example

A realistic config.json extracted from the buran production template, showing all major sections working together. The `master` section defines variables that child (slave) templates can override -- `tpl` for feature toggles accessible via `this.slaveConfig`, and `sass` for SCSS variables organized into groups (Základní nastavení, Tlačítka, Štítky, Oznámení):

```json
{
    "webfonts": [
        "Manrope:500,600,700"
    ],
    "responsive": true,
    "plugins": {
        "jquery": "3.4",
        "foundation": "6.4",
        "swiper": "6.x",
        "jquery-fancybox": "3.5",
        "jquery-validation": "1.19",
        "jquery-ui-slider": "2.0",
        "jquery-ui-dialog": "2.0",
        "svgxuse-polyfill": "1.2"
    },
    "skipOrderSummary": true,
    "cartSteps": [
        { "handles": ["content"] },
        { "handles": ["delivery"], "query": "dodani" },
        { "handles": ["address"], "query": "adresa" }
    ],
    "inputInLabel": false,
    "features": [
        "last_viewed_products",
        "syntax2019",
        "upsell_customer_note",
        "upsell_customer_upload"
    ],
    "variantChoice": {
        "code": "default",
        "modes": {
            "selects": "roletka",
            "icons": "barevná okýnka",
            "text": "textově (default)"
        }
    },
    "manifest": {
        "theme_color": "#0F172A"
    },
    "master": {
        "name": "buran",
        "tpl": {
            "enableCompare": { "label": "Povolit porovnání", "type": "bool" },
            "enableWishlist": { "label": "Povolit Seznam přání", "type": "bool" },
            "enableLoyaltyProgram": { "label": "Povolit věrnostní program", "type": "bool" },
            "enableUpsells": { "label": "Povolit upselly", "type": "bool" },
            "enableGifts": { "label": "Povolit Dárky v košíku", "type": "bool" },
            "enableShops": { "label": "Povolit prodejny", "type": "bool" },
            "enableComments": { "label": "Povolit komentáře u produktů", "type": "bool" },
            "enableReviews": { "label": "Povolit recenze (Heureka, Zbozi, Biano)", "type": "bool" }
        },
        "sass": {
            "config-primary-color": {
                "label": "Barva textu - hlavní (primary) barva",
                "default": "#10b981",
                "group": "Základní nastavení"
            },
            "config-success-color": {
                "label": "Barva textu - hlavní (success) barva",
                "default": "#10b981",
                "group": "Základní nastavení"
            },
            "config-button-background": {
                "label": "Základní tlačítko - barva pozadí",
                "default": "#10b981",
                "group": "Tlačítka"
            },
            "config-button-background-hover": {
                "label": "Základní tlačítko - barva pozadí po najetí myši",
                "default": "#059669",
                "group": "Tlačítka"
            },
            "config-order-button-background": {
                "label": "Tlačítko nákupu - barva pozadí",
                "default": "#10b981",
                "group": "Tlačítka"
            },
            "config-product-label-discount-bg": {
                "label": "Štítek Sleva - barva pozadí",
                "default": "#dc2626",
                "group": "Štítky"
            },
            "config-product-label-new-bg": {
                "label": "Štítek Novinka - barva pozadí",
                "default": "#f5f5f5",
                "group": "Štítky"
            },
            "config-global-announcement-info-background-color": {
                "label": "Informace - barva pozadí",
                "default": "#f0f8ff",
                "group": "Oznámení"
            },
            "config-global-announcement-default-background-color": {
                "label": "Oznámení - barva pozadí",
                "default": "#cbe3c6",
                "group": "Oznámení"
            }
            // ... more color variables for labels, discount badges, etc.
        }
    }
}
```

The `tpl` feature toggles are accessed in templates via `this.slaveConfig`:

::: v-pre

```twig
{% if this.slaveConfig.enableWishlist %}
    {# Show wishlist button #}
{% endif %}
```

:::

## Plugins Reference

Plugins are declared in the `plugins` section of config.json. The platform automatically loads the corresponding JavaScript and CSS for each declared plugin. All plugins listed below are used in the buran production template:

| Plugin | Version | Description |
|---|---|---|
| **jquery** | 3.4 | jQuery library -- required by most other plugins |
| **foundation** | 6.4 | Zurb Foundation responsive framework (grid system with `grid-x`/`cell`, responsive visibility classes like `show-for-medium`, `hide-for-large`) |
| **swiper** | 6.x | Touch-enabled slider/carousel for banners, product carousels, and subcategory strips |
| **jquery-fancybox** | 3.5 | Lightbox for product image galleries and modal popups |
| **jquery-validation** | 1.19 | Client-side form validation (checkout forms, registration, contact) |
| **jquery-ui-slider** | 2.0 | Range slider widget used for price filters (see [filter](filter.md)) |
| **jquery-ui-dialog** | 2.0 | Modal dialog component (login, quick-view, confirmations) |
| **svgxuse-polyfill** | 1.2 | Polyfill for external SVG `<use>` references in older browsers |

## Custom Fields Usage in Templates

Fields defined in the `fields` section of config.json (see [fields](#fields) above) provide custom text and image slots for various objects. Once defined, they can be filled in through the admin panel and accessed in templates.

**Accessing custom text fields:**

::: v-pre

```twig
{# Display short description of a transport method #}
{{ transport.text('short') }}

{# Display custom HTML field on a product #}
{{ product.text('specification') }}

{# Use custom text in conditionals #}
{% if category.text('long') %}
    <div class="category-description">{{ category.text('long') }}</div>
{% endif %}
```

:::

**Accessing custom image fields:**

::: v-pre

```twig
{# Display transport icon as a 40x40 image #}
<i:img src="transport.image('ico')" format="40x40" />

{# Display category banner image #}
<i:img src="category.image('banner')" format="1200x400" />

{# Category icon used in subcategory listing #}
<i:img src="cat.image('ico')" format="80x80" fill loading="lazy" />
```

:::

**Defining fields in config.json:**

The `fields` config specifies text and image slots per object type. The `label` appears in the admin form, `format` controls the editor type, and `description` provides admin guidance:

```json
{
    "fields": {
        "transport": {
            "text": {
                "short": { "label": "Krátký popisek", "format": "html", "description": "Zobrazuje se v košíku" }
            },
            "image": {
                "ico": { "label": "Ikonka výběru", "description": "Zobrazuje se v košíku" }
            }
        },
        "category": {
            "text": {
                "long": { "label": "Úvodní text", "format": "html", "description": "Text nad výpisem" }
            },
            "image": {
                "ico": { "label": "Ikonka kategorie", "description": "Pro podkategorie" }
            }
        }
    }
}
```

Supported objects for custom fields: **transport**, **paymentMethod**, **textPage**, **store**, **admin**, **category**, **brand**, **product**, **author**, **upsellGroup**, **article**

## Critical CSS

Critical CSS is the minimal set of styles needed to render the visible part of a page (above the fold). These styles are inlined directly in the `<head>`, so the browser can paint the page without waiting for the full stylesheet to download. After the full CSS loads (typically under 1 second), the page appearance is corrected.

### How generation works

During deployment, the generator:

1. Fetches a list of random URLs per page type from `/_random` (index, product, category, subcategory, page)
2. Downloads the full `package.min.css`
3. For each URL × device (mobile 380×650, desktop 1000×600):
   * Opens the page in headless Chromium with JavaScript blocked
   * Parses the full CSS and checks which selectors have elements **above the viewport fold**
   * Removes `@media print`, media queries for smaller viewports, unused `@keyframes`
   * Keeps rules for `position: fixed`/`sticky` elements (always visible)
   * Applies `forceInclude`/`forceExclude` from config
4. Merges results across URLs, deduplicates, and runs cleanup (removes transitions, vendor prefixes, `@font-face`, `background-image`)

The output is a JSON object with `css` and `mobileCss` per page type, stored in the template config and served inline.

### Size budget

Critical CSS should stay **under ~14 KB gzipped** to fit within the first TCP roundtrip (congestion window). Larger critical CSS delays First Contentful Paint instead of helping it. If your critical CSS is too large, use `forceExclude` to remove heavy selectors that aren't needed for the initial render.

### When to configure `criticalCss`

**No configuration needed** for most templates. The generator samples random URLs and detects above-fold elements automatically. You only need `criticalCss` in config.json when:

* **Conditional elements** — A component only appears on some pages (e.g., `.main-banner` on the homepage with a banner, `.product-gallery` only on products with multiple images). If the sampled page happens not to have it, the styles will be missing. Use `forceInclude`.
* **Heavy below-fold components** — A large component (e.g., `.video-player`, `.reviews-section`) is technically above the fold on some pages but is not essential for the first paint. Use `forceExclude` to save bytes.
* **Custom viewport needs** — A page type has a non-standard layout that requires different viewport dimensions for accurate extraction.

### Recommended patterns

**Homepage with banners/sliders:**

```json
{
    "criticalCss": {
        "index": {
            "forceInclude": [".main-banner", ".hero-slider"],
            "forceExclude": [".video-player", ".chat-widget"]
        }
    }
}
```

**Product page with conditional gallery:**

```json
{
    "criticalCss": {
        "product": {
            "forceInclude": [".product-gallery", ".product-price"]
        }
    }
}
```

**Multiple types sharing the same pattern:**

```json
{
    "criticalCss": {
        "category": {
            "forceInclude": [".category-banner"]
        },
        "subcategory": {
            "forceInclude": [".category-banner"]
        }
    }
}
```

### Testing critical CSS

* **Quick flash test:** On production, press Ctrl+F5. Critical styles render first, then the full CSS loads. The flash should be brief and the layout should not jump.
* **Force critical mode:** Append `?_forceCritical` to any URL (requires admin login). The page renders using only the critical CSS — this shows exactly what visitors see before the full stylesheet loads.
* **Disable web fonts:** Append `?_disableWebFonts` to see the page without web fonts, matching how the generator sees it.
* **PageSpeed Insights:** [Google PageSpeed](https://developers.google.com/speed/pagespeed/insights/) gives the most realistic performance assessment.

## Favicon

The favicon is not part of the template. It is uploaded in the shop admin separately for each domain.

---

---
url: /content-grid.md
---
# Content grid

For structured content, you can define a schema that controls which UI elements are displayed in the admin panel. This allows creating an interface for entering content that the admin panel would not support by default.

This feature is intended for presentational elements -- for example, displaying text on a landing page at specific positions together with images. The content is not accessible outside the template, so the feature is not suitable for content that will be needed in feeds, label printing, and similar use cases.

## Schema definition

The schema is an XML file in the **content-grid** directory inside the template. The file name determines how the content is referenced in the template (e.g., content defined by the file **content-grid/product-cta.xml** is accessed in the template using {{ product.contentGrid('product-cta') }}).

In the editor, you can import the schema https://tpldoc.simplia.cz/xsd/content-grid.xsd to enable autocompletion of possible values and validation of correct syntax.

The defined structure does not directly affect functionality and is primarily for better orientation in the admin panel. The layout should ideally approximate the final display in the shop.

```xml
<?xml version="1.0" encoding="utf-8"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://tpldoc.simplia.cz/xsd/content-grid.xsd">
    <config>
        <name>Obsahová mřížka</name> <!-- name for orientation in the admin panel - displayed on the add button -->
        <priority>1</priority> <!-- priority for ordering in the admin panel -->
        <translations>false</translations> <!-- when translations are enabled, content is created separately for each language in the admin panel -->
        <mode>full_page</mode> <!-- "full_page" offers content-grid in the page type dropdown, "part" displays all content grids as buttons -->
        <supported-context type="article"/> <!-- which contexts the content is supported for -->
        <supported-context type="text_page"/>
    </config>
    <grid>
        <row label="Hlavička" code="header"> <!-- "label" sets the heading in the admin panel, "code" defines how the content is referenced in the template -->
            <content type="string" label="Nadpis" code="headline" width="20"/> <!-- optionally, width can be defined in percent -->
            <content type="image" label="Ikonka nadpisu" code="image"/>
        </row>
        <row label="Obsah" code="content">
            <content type="html" label="Text" code="text"/>
            <content type="image" label="Nadpis3" code="image2"/>
            <cell label="vyberte kategorii" code="image2">
                <row code="text">
                    <content type="html" label="Text" code="text"/>
                </row>
                <row code="image2">
                    <content type="image" label="Nadpis3" code="image2" multiple="true" /> <!-- content with multiple enabled can be reordered in the admin panel -->
                </row>
            </cell>
        </row>
        <row label="Obsah2" code="content2" multiple="true"> <!-- the "multiple" attribute allows adding multiple blocks (or none) - in the template "content2" is then available as an array -->
            <content type="html" label="Text" code="text"/>
            <content type="image" label="Nadpis3" code="image2"/>
            <content type="category" label="kategorie" code="category" multiple="true"/>
            <content type="select" label="Test selectu" code="selection" width="100">
                <choice code="first" label="První"/>
                <choice code="second" label="Druhý"/>
                <choice code="third" label="Třetí"/>
            </content>
        </row>
    </grid>
</schema>
```

## Display mode

The *mode* tag setting switches between two display modes:

* *full\_page*: The admin panel shows a "Layout" dropdown for selecting a page type. After selection, the dropdown disappears and no buttons for adding additional content grids are shown. Ideal for typed pages such as an "About Us" page, etc.
* *part*: Assumes that multiple different content grids may be used on a single page. Typically, a content grid represents one content element but does not take over the rest of the page.

## Usage in templates

For supported objects, content is always loaded using the *contentGrid* method with the definition file name. If no content has been defined for the given object, *null* is returned. The structure of the returned data corresponds to the XML definition structure. Not all values need to be filled in.

::: v-pre

```twig
{% if product.contentGrid('product-cta') %}
    <h3>{{ product.contentGrid('product-cta').header.headline }}</h3>
    {% for content in product.contentGrid('product-cta').content2 %}
        {{ content.text }}
    {% endfor %}
{% endif %}
```

```twig
{% if this.contentGrid('banner-cta') %}
    <h3>{{ this.contentGrid('banner-cta').header.headline }}</h3>
    {% for content in this.contentGrid('banner-cta').content2 %}
        {{ content.text }}
    {% endfor %}
{% endif %}
```

:::

## Content Type Reference

::: v-pre
| Type | Description | Template Access |
|---|---|---|
| **string** | Single-line plain text input | `{{ row.code }}` -- renders as plain string |
| **html** | Rich text editor (full WYSIWYG) | `{{ row.code }}` -- renders as raw HTML |
| **html\_simple** | Simplified rich text editor (basic formatting only -- bold, italic, links) | `{{ row.code }}` -- renders as raw HTML |
| **image** | Image upload (PNG, JPG, SVG, ...) | `<i:img src="row.code" format="300x300" />` |
| **color** | Color picker (hex code) | `{{ row.code }}` -- renders as `#rrggbb` string |
| **url** | URL with link text and title | `{{ row.code.url }}`, `{{ row.code.label }}`, `{{ row.code.title }}` |
| **category** | Category selector from catalog tree | Returns a category object with `.url`, `.name`, etc. |
| **product** | Single product selector | Returns a product object |
| **product\_list** | Product selection by rules (category, attributes, etc.) | Returns a collection for [i:list-container](list.md) `collection` attribute |
| **select** | Dropdown with predefined `<choice>` child elements | `{{ row.code }}` -- renders the selected choice `code` value |
| **article** | Article selector | Returns an article object with `.url`, `.name`, etc. |
| **text\_page** | Text page selector | Returns a text page object with `.url`, `.name`, `.text` |
:::

All types support the `multiple="true"` attribute, which turns the value into a reorderable array in the admin. Rows with `multiple="true"` are accessed as arrays in Twig (use `{% for item in ... %}`).

## Production Examples

These examples are extracted from the buran production template and simplified (feature toggles removed) to show core patterns.

### 1. Simple: Footer USP icons

A repeatable row with an image and short text. Used for "Unique Selling Proposition" icons displayed as a horizontal bar above the footer. The `html_simple` type provides basic formatting (bold, italic, links) without full WYSIWYG.

**Schema** (`content-grid/footer-usp.xml`):

```xml
<?xml version="1.0" encoding="utf-8"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://tpldoc.simplia.cz/xsd/content-grid.xsd">
    <config>
        <name>Patička - USP</name> <!-- Footer - USP icons -->
        <translations>true</translations>
        <mode>part</mode>
        <supported-context type="global"/>
    </config>

    <grid>
        <row code="item" label="USP" multiple="true">
            <content type="image" label="Obrázek" code="image" width="30" />
            <content type="html_simple" label="Text" code="text" width="70" />
        </row>
    </grid>
</schema>
```

**Template** (`_footer-usp.tpl`) -- the actual buran template renders USP items in a flex row with SVG icon support:

::: v-pre

```twig
{# _footer-usp.tpl -- loaded from _footer.tpl via {% include '_footer-usp.tpl' %} #}
{% set items = this.contentGrid('footer-usp').item %}
<div class="usp-bar">
    <div class="usp-bar__inner">
        {% for item in items %}
            <div class="usp-item">
                {# vector + transparent flags enable SVG rendering without background #}
                <i:img src="item.image" format="30x30" loading="lazy" vector transparent />
                <div>{{ item.text }}</div>
            </div>
        {% endfor %}
    </div>
</div>
```

:::

The parent `_footer.tpl` conditionally includes this partial:

::: v-pre

```twig
{% if this.contentGrid('footer-usp').item %}
    {% include '_footer-usp.tpl' %}
{% endif %}
```

:::

### 2. Medium: Footer column links with nested URL loops

Each column has a headline (string) and repeatable URL links. The `url` type provides both `.url` and `.label` properties. Note the nested `multiple="true"` -- the outer row repeats columns, and the inner `link` content repeats links within each column.

**Schema** (`content-grid/footer-column-links.xml`):

```xml
<?xml version="1.0" encoding="utf-8"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://tpldoc.simplia.cz/xsd/content-grid.xsd">
    <config>
        <name>Patička - Sloupečky s odkazy</name> <!-- Footer - Link columns -->
        <translations>true</translations>
        <mode>part</mode>
        <supported-context type="global"/>
    </config>

    <grid>
        <row code="item" label="Sloupeček" multiple="true"> <!-- Repeatable column -->
            <content type="string" label="Nadpis" code="headline" width="100" /> <!-- Column heading -->
            <content type="url" multiple="true" label="Odkaz" code="link" width="100" /> <!-- Repeatable link -->
        </row>
    </grid>
</schema>
```

**Template** (`_footer.tpl` excerpt) -- the buran footer limits to 3 columns and renders links as a `<ul>` list with collapsible headings on mobile:

::: v-pre

```twig
{# _footer.tpl -- iterate footer columns (limited to first 3) #}
{% for item in this.contentGrid('footer-column-links').item %}
    {% if loop.index <= 3 %}
        <div class="footer-box">
            <h4 class="footer-box__headline">
                {{ item.headline }}
                {# Chevron icon for mobile accordion toggle #}
                <svg class="footer-box__headline-angle icon">
                    <use xlink:href="{{ images('symbol-defs.svg#bi-chevron-down') }}"></use>
                </svg>
            </h4>
            <div class="footer-box__info">
                <ul>
                    {# Inner loop: each link has .url and .label from the url type #}
                    {% for link in item.link %}
                        <li><a href="{{ link.url }}">{{ link.label }}</a></li>
                    {% endfor %}
                </ul>
            </div>
        </div>
    {% endif %}
{% endfor %}
```

:::

### 3. Complex: Homepage banner with products

A complex schema using nested `<cell>` elements to group related fields into a two-column admin layout. Each banner has a left side (background color + image, 30% width) and a right side (text + headline + description + button + product list, 70% width). The `product_list` type returns a collection that can be passed to [i:list-container](list.md).

**Schema** (`content-grid/homepage-banner-products.xml`):

```xml
<?xml version="1.0" encoding="utf-8"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://tpldoc.simplia.cz/xsd/content-grid.xsd">
    <config>
        <name>Homepage - Banner s produkty</name> <!-- Homepage - Banner with products -->
        <translations>true</translations>
        <mode>part</mode>
        <supported-context type="global"/>
    </config>

    <grid>
        <row code="item" label="Banner" multiple="true">
            <cell code="left" width="30" label="Info vlevo"> <!-- Left panel in admin -->
                <content type="color" label="Barva pozadí" code="color" width="100" />
                <content type="image" label="Obrázek" code="image" width="100" />
            </cell>

            <cell code="right" width="70" label="Info vpravo"> <!-- Right panel in admin -->
                <content type="string" label="Nadpisek" code="text" width="100" />
                <content type="string" label="Nadpis" code="headline" width="100" />
                <content type="html_simple" label="Popisek" code="description" width="100" />
                <content type="url" label="Tlačítko" code="button" width="100" />
                <content type="product_list" label="Produkty" code="products" width="100" />
            </cell>
        </row>
    </grid>
</schema>
```

**Template** (`index.tpl` excerpt) -- the buran homepage iterates banner items, accesses nested cell data via `item.left.*` and `item.right.*`, and passes the `product_list` collection to a product slider:

::: v-pre

```twig
{# index.tpl -- homepage banner with product carousel #}
{% if this.contentGrid('homepage-banner-products') %}
    {% set section = this.contentGrid('homepage-banner-products').item %}
    {% for item in section %}
        <div class="banner-products" if:style="item.left.color ? '--banner-bg-color: ' ~ item.left.color">
            {# Left side: promotional image #}
            <div class="banner-products__image">
                <i:img src="item.left.image" format="600x600" loading="lazy" alt="{{ item.right.headline }}" />
            </div>

            {# Right side: text content with CTA button #}
            <div class="banner-products__text">
                <div>
                    <span>{{ item.right.text }}</span>
                    <strong>{{ item.right.headline }}</strong>
                    {% if item.right.description %}
                        <div>{{ item.right.description }}</div>
                    {% endif %}
                    <a href="{{ item.right.button.url }}" class="button">
                        {{ item.right.button.label }}
                    </a>
                </div>
            </div>

            {# Product carousel using the "simple" list-item variant from _listing.tpl #}
            <i:list-container type="product" name="simple" collection="{{ item.right.products }}" hide-empty
                              class="swiper-container" data-navigation="simple-slider-{{ loop.index }}">
                <div data-role="list" class="swiper-wrapper"></div>
            </i:list-container>
        </div>
    {% endfor %}
{% endif %}
```

:::

---

---
url: /glossary.md
---
# Czech-English Glossary

This glossary maps Czech identifiers used in Simplia template code to their English meanings. All terms listed here are **immutable code identifiers** — they appear in filenames, variable names, URL paths, filter names, and function names that cannot be renamed.

> **For AI agents:** When you encounter a Czech identifier in template code, look it up here. The "Code identifier" column shows the exact string found in source files. Do not translate or rename these identifiers.

## Template Files

Each e-shop page has a corresponding `.tpl` template file. The filenames use Czech naming.

| Code identifier | English meaning | Purpose |
|---|---|---|
| `_base.tpl` | base layout | Main layout wrapper (header, footer, page structure) |
| `index.tpl` | homepage | Homepage template |
| `zbozi.tpl` | product detail | Single product page |
| `kosik.tpl` | shopping cart | Cart page (may contain multiple checkout steps) |
| `kosik_obsah.tpl` | cart content | Cart content partial |
| `objednavka.tpl` | order detail | Order detail page (logged-in user viewing past order) |
| `objednavky.tpl` | order list | List of customer orders |
| `potvrzeni.tpl` | order confirmation | Order confirmation / thank-you page |
| `rychlokos.tpl` | quick cart | Zero-step (single page) checkout |
| `dodani.tpl` | delivery | Delivery/shipping selection template |
| `adresa.tpl` | address | Address entry template |
| `registrace.tpl` | registration | User registration page |
| `prihlaseni.tpl` | login | User login page |
| `profil.tpl` | user profile | Logged-in user profile page |
| `hledat.tpl` | search | Search page |
| `vyhledavani.tpl` | search results | Search results page |
| `vypis.tpl` | product listing | Category product listing page |
| `vypis_filtr.tpl` | filtered listing | Filtered product listing (AJAX) |
| `vypis_porovnani.tpl` | product comparison | Product comparison page |
| `vypis_prani.tpl` | wishlist | Wishlist page |
| `vypis_vyrobce.tpl` | brand listing | Brand/manufacturer product listing |
| `vyrobce.tpl` | brand detail | Single brand/manufacturer page |
| `znacky.tpl` | brands list | All brands page |
| `clanek.tpl` | article detail | Single article/blog post page |
| `clanek_zbozi.tpl` | article products | Article-related products page |
| `novinky.tpl` | news list | News/blog listing page |
| `novinka.tpl` | news detail | Single news item page |
| `tema.tpl` | topic detail | Article topic/magazine section page |
| `temata.tpl` | topics list | Article topics listing page |
| `autor.tpl` | author | Author page |
| `recenze/vypis.tpl` | reviews listing | Customer reviews page |
| `stranka.tpl` | text page | Static/CMS text page |
| `prodejna.tpl` | store detail | Physical store/branch detail page |
| `mapa.tpl` | sitemap | Site map page |
| `videa.tpl` | videos | Video listing page |
| `dialog/kosik_ok.tpl` | cart success dialog | "Added to cart" confirmation dialog |
| `dialog/hlidaci_pes.tpl` | watchdog dialog | Price/availability watchdog dialog |
| `_listing.tpl` | listing definitions | Listing item, pagination, and empty-state macros |
| `_listing_article.tpl` | article listing | Article listing macros |
| `_filter.tpl` | filter | Product filter template |
| `_menu.tpl` | menu | Navigation menu template |
| `ajax/search.tpl` | AJAX search | AJAX search results partial |

## URL Presenters (iUrl paths)

The `iUrl()` function generates internal URLs. The first argument is a presenter path in Czech.

### Order flow

| Code identifier | English meaning |
|---|---|
| `Objednavka/Kosik` | order/cart |
| `Objednavka/Pokladna` | order/checkout (summary/review) |
| `Objednavka/Platba` | order/payment |
| `Objednavka/Rychlokos` | order/quick-cart (single-page checkout) |
| `Objednavka/Vypis` | order/list (order history) |

### Product listings

| Code identifier | English meaning |
|---|---|
| `Vypis/Vybrane` | listing/selected (products by ID) |
| `Vypis/Porovnani` | listing/comparison |
| `Vypis/Akce` | listing/promo (products on promotion) |
| `Vypis/AkceSleva` | listing/promo-discount |
| `Vypis/Slevy` | listing/discounts |
| `Vypis/SlevyVyprodej` | listing/discounts-clearance |
| `Vypis/Vyprodej` | listing/clearance |
| `Vypis/Skladem` | listing/in-stock |
| `Vypis/Cena` | listing/price (price range) |
| `Vypis/Nejnovejsi` | listing/newest |
| `Vypis/Nejprodavanejsi` | listing/bestsellers |
| `Vypis/VyrobceKategorie` | listing/brand-category |
| `Vypis/Vyhledavani` | listing/search |

### User

| Code identifier | English meaning |
|---|---|
| `User/Login` | user/login |
| `User/Registrace` | user/registration |
| `User/HesloPozadavek` | user/password-request (forgotten password) |
| `Wish/Vypis` | wishlist |

### Other

| Code identifier | English meaning |
|---|---|
| `Vyrobce/Vypis` | brand/list |
| `Tema/Vypis` | topic/list (magazine) |
| `Recenze/Vypis` | review/list |
| `Novinka/Vypis` | news/list |
| `Video/Vypis` | video/list |
| `Page/Mapa` | page/sitemap |

## URL Parameters

Czech parameter names used in `iUrl()` calls.

| Code identifier | English meaning | Context |
|---|---|---|
| `sekce` | section | Cart step section (`address`, `delivery`, ...) |
| `kategorie` | category | Category link object |
| `vyrobce` | brand/manufacturer | Brand link object |
| `vyber` | selection | Product IDs (hyphen-separated) |
| `fraze` | phrase | Search query string |
| `datum` | date | Date filter |
| `od` | from | Price range start |
| `do` | to | Price range end |
| `objednavka` | order | Order reference for payment |

## Twig Filters (Czech-named)

Custom Simplia filters with Czech names. See [Twig reference](/twig) for full details.

| Code identifier | English meaning | Description |
|---|---|---|
| `cena` | price | Format number as price with currency |
| `mena` | currency | Format number with currency (alias of cena) |
| `mena_rounded` | currency rounded | Rounded price with currency |
| `orez` | trim/truncate | Truncate text to given length |
| `prvniVelke` | capitalize first | Uppercase first letter |
| `diakritika` | diacritics removal | Strip diacritical marks |

## Twig Functions (Czech-named)

| Code identifier | English meaning | Description |
|---|---|---|
| `isPracovniDen()` | isWorkingDay | Check if a date is a working day |
| `pristiPracovniDen()` | nextWorkingDay | Get the next working day |

## Global Context Variables

Variables available in all templates.

| Code identifier | Type | Description |
|---|---|---|
| `MENA` | string | Current currency code (e.g., `CZK`) |
| `MENADEF` | string | Default currency code |
| `HOST` | string | Current domain hostname |
| `LANG` | string | Current language code |
| `URI` | string | Current request URI |
| `cart` | Order | Current shopping cart object |
| `customer` | Customer | Current logged-in customer (or guest) |
| `shop` | Shop | Shop configuration object |
| `repository` | Repositories | Data access layer for querying entities |
| `this` | TemplateContext | Current template context (settings, URLs, content grid) |

## Template Context Variables (per-file)

Czech variable names used as Twig context in specific template files.

| Code identifier | English meaning | Available in | Type |
|---|---|---|---|
| `zbozi` | product | `i:product-box` tag, `zbozi.tpl` | Product |
| `kategorie` | category | list source expressions | Category |
| `article` | article | `clanek.tpl` | Article |
| `actuality` | news item | `novinka.tpl` | Actuality |
| `store` | physical store | `prodejna.tpl` | Store |
| `textPage` | text page | `stranka.tpl` | TextPage |
| `order` | order | `objednavka.tpl`, `potvrzeni.tpl` | Order |
| `brand` | brand | `vyrobce.tpl` | Brand |
| `searchQuery` | search query | `vyhledavani.tpl` | string |
| `deliveryCountries` | delivery countries | `kosik.tpl` | Country\[] |

## Pagination Properties

| Code identifier | English meaning | Description |
|---|---|---|
| `pagination.stran` | page count | Total number of pages |
| `pagination.nsum` | total count | Total number of items |
| `pagination.strany` | pages HTML | Rendered pagination links |

## Config Concepts

| Term | Description |
|---|---|
| master template | Parent template that defines overridable variables for child templates |
| slave template | Child template that inherits from a master, overriding specific variables via `slave.json` |
| `cartSteps` | Array in `config.json` defining multi-step checkout flow |
| `cartSteps[].handles` | What the step contains: `content`, `delivery`, `address`, `summary` |
| `cartSteps[].query` | Czech URL parameter for the step (e.g., `dodani`, `adresa`) |
| `variantChoice` | Configuration for product variant selection UI modes |
| `this.nastaveni` | Access to admin-configured template settings (nastaveni = settings) |
| `this.templateAttributes` | Access to template appearance settings |
| `sekce_kosik` | Flag/variable indicating current cart section |

---

---
url: /delivery.md
---
# Delivery Method

The delivery selection template is undergoing gradual unification, simplification, and migration to components. The goal is to introduce newer approaches incrementally without requiring a full rewrite of all templates from the start.

In the examples below, the `i:****` tags are the important parts; the rest of the template will differ historically for each shop.

## Delivery-transport and delivery-branch

Defines the element for selecting a carrier. Typically this is a radio input with a label such as *Ceska posta* (Czech Post).

Branch selection is displayed only if the given delivery method supports branches (this is not handled in the template). The branch selection button text is optional and is automatically added to translations.

The reload-targets attribute accepts selectors for elements that should be automatically updated when the transport or payment selection changes.

```twig
<i:delivery-transports tag="div" reload-targets=".order_totals">
    {% for transport in transports %}
        <i:delivery-transport tag="div" transport="transport">
            <label>
                <input type='radio' if:checked="transport.selected" name='transport'>
                {{ transport.name }}
            </label>
            <i:delivery-branch button-text="cart.select-branch.button"/>
        </i:delivery-transport>
    {% endfor %}
</i:delivery-transports>
```

```html
<!-- generated code - subject to change! -->

<div data-component="delivery-transports">
    <div data-component="delivery-transport">
        <label>
            <input type="radio" name="transport" value="14">
            Česká pošta
        </label>
        <div data-component="delivery-branch">
            <input type="hidden" name="pobocka[zasilkovna_stat_1000]" value="17">
            <span>Drtinova 10, Praha</span>
            <a href="#">vyberte pobočku</a>
        </div>
    </div>
</div>
```

## Delivery-payment

Defines the element for selecting a payment method. Typically this is a radio input with a label such as *platba kartou* (card payment). The tag identifies the related element for a single carrier -- currently only branch selection.

Available payment options are automatically updated when the transport selection changes.

```twig
<i:delivery-payments tag="div" reload-targets=".order_totals">
    {% for payment in payments %}
        <i:delivery-payment tag="div" payment="payment">
            <label>
                <input type='radio' if:checked="payment.selected" name='payment'>
                {{ payment.name }}
            </label>
        </i:delivery-payment>
    {% endfor %}
</i:delivery-payments>
```

```html
<!-- generated code - subject to change! -->

<div data-component="delivery-payments">
    <div data-component="delivery-payment">
        <label>
            <input type="radio" name="payment" value="14">
            platba kartou
        </label>
    </div>
</div>
```

## Delivery-map

Defines an element with an interactive carrier map.

```twig
<i:delivery-map />
<i:delivery-map country="cz" carrier="zasilkovna" query="Praha" />
```

**Attributes of delivery-map**

| Attribute | Required | Description |
|---|---|---|
| country | *no* | Country |
| carrier | *no* | Carrier type |
| query | *no* | Search phrase |

```html
<!-- generated code - subject to change! -->

<div data-type="zasilkovna" data-search="Praha" data-country="cz" class="branch-map"></div>
```

## Complete Delivery Step

The delivery step template (`kosik_dodani.tpl`) wraps the transport and payment selection in a form with step navigation. It is loaded by the checkout router (`kosik.tpl`) when `sekce == 'dodani'` (see [Cart - Checkout Flow Architecture](/cart#checkout-flow-architecture)).

```twig
{# kosik_dodani.tpl — delivery step #}
<form action="{{ this.urlSave }}" method="post" class="form_adresa">
    <div class="grid-x">
        <div class="checkout-left cell">
            {# Step indicator breadcrumb — kosik_kroky.tpl #}
            {% include 'kosik_kroky.tpl' %}

            {# Optional info banner from content grid #}
            {% if this.contentGrid('checkout-delivery-info') %}
                {% set block = this.contentGrid('checkout-delivery-info').checkouttext %}
                <div style="color: {{ block.color }}; background: {{ block.bgcolor }};
                            border: {{ block.bordercolor ? '1px solid ' ~ block.bordercolor }}">
                    {{ block.text }}
                </div>
            {% endif %}

            <h1>{% trans 'checkout.headline' %}
                (<span i:dynamic="cart">{{ cart.catalogItemTotalAmount }}</span>
                {% trans 'template.qty' %})
            </h1>

            {# Transport and payment selection (shared partial) #}
            {% include '_dodani.tpl' %}
        </div>

        {# Order summary sidebar — receives checkout context #}
        {% include 'kosik_souhrn.tpl' with {'checkout': 'delivery'} %}
    </div>

    {# Hidden field to advance to address step on submit #}
    <input type="hidden" name="toSekce" value="udaje">
</form>
```

### Key Structural Elements

| Element | Purpose |
|---|---|
| `kosik_kroky.tpl` | Step progress breadcrumb, included at the top of each step |
| `_dodani.tpl` | Shared partial containing the `i:delivery-transports` and `i:delivery-payments` components documented above |
| `kosik_souhrn.tpl` | Order summary sidebar, receives `{'checkout': 'delivery'}` context to show delivery costs and a "Continue to address" button |
| `toSekce` hidden field | Set to `udaje` (address) to advance to the next checkout step on form submit |
| `contentGrid('checkout-delivery-info')` | Optional admin-configurable info banner (see [Content Grid](/content-grid)) |
| `i:dynamic="cart"` | Marks the item count span for automatic reload when cart data changes (see [Syntax - Dynamic Content Reload](/syntax#dynamic-content-reload)) |

The `_dodani.tpl` partial contains the `i:delivery-transports` and `i:delivery-payments` components documented above. The summary sidebar (`kosik_souhrn.tpl`) adapts its content based on the `checkout` variable — showing delivery costs and a "Continue to address" button on the delivery step.

---

---
url: /editor.md
---
# Editor Configuration

## PhpStorm

### Syntax Highlighting

In *Settings*, under the *File Types* section, configure Twig syntax highlighting for *.tpl* file extensions.

![](img/phpstorm/syntax.png)

### Plugin

A PhpStorm plugin is available that provides autocompletion for available variables and validates template syntax. After installation, no further configuration is needed — it works automatically for Simplia templates.

![](img/phpstorm/plugin.png)

#### Plugin Installation

In Settings, under the Plugins section, click the gear icon and select *Manage Plugin Repositories*.

![](img/phpstorm/plugin-1.png)

Add the URL `https://phpstorm.simplia.cz`

![](img/phpstorm/plugin-2.png)

Search for and install the `Symfony Support` and `Simplia templates` plugins. After installing the plugins, restart PhpStorm.

![](img/phpstorm/plugin-3.png)

Autocompletion will be automatically available in templates of e-shops using the new syntax. If an update is released (for example, when a new object is added to templates), PhpStorm will offer it automatically.

![](img/phpstorm/plugin-4.png)

### Syntax Validation

#### Configuring Inspections

In the menu, select *Code* > *Inspect Code*:

![](img/phpstorm/inspection/code-inspect-1.png)

Create a new profile by clicking the three-dot button *...*:

![](img/phpstorm/inspection/code-inspect-2.png)

Download the Simplia.xml inspection definitions file and import it into PhpStorm — select the downloaded file and click *OK*.

![](img/phpstorm/inspection/code-inspect-3.png)

#### Running Inspections

In the menu, select *Code* > *Inspect Code*:

![](img/phpstorm/inspection/code-inspect-1.png)

![](img/phpstorm/inspection/code-inspect-4.png)

![](img/phpstorm/inspection/code-inspect-5.png)

## AI Agents and Machine Processing

For AI agents and automated tools, the documentation site provides machine-readable resources:

* **[llms.txt](/llms.txt)** / **[llms-full.txt](/llms-full.txt)** — the entire template documentation in a text format optimized for LLM processing. Suitable for loading the full documentation context at once.

---

---
url: /events.md
---
# Events

When using jQuery, you can bind custom actions to various events. For example, after adding an item to the cart you can update the order total on the page, etc.

## Add to cart (order:itemadded)

```javascript
$(document).on('order:itemadded', function(event, data) {
    // custom action
});
```

The event passes an object with the following content:

```javascript
{
    item: {
        id: 1, // internal product id
        name: 'abc' // product name
    }
}
```

## Successful newsletter subscription (newsletter:success)

```javascript
$(document).on('newsletter:success', function(event, data) {
    // custom action
});
```

The event passes an object with the following content:

```javascript
{
    email: 'info@example.org' // registered email
}
```

## Failed newsletter subscription (newsletter:error)

```javascript
$(document).on('newsletter:error', function(event, data) {
    // custom action
});
```

The event passes an object with the following content:

```javascript
{
    email: 'info@example.org'
}
```

## Page change (listing:changed)

Fires when the page changes during dynamic loading.

```javascript
$('div.list').on('listing:changed', function(event, data) {
    // custom action
});
```

## Dynamic content loaded (reload)

Fires after content is loaded via the reload() function.

```javascript
$(document).on('reload', 'div.list', function(event) {
    // custom action
});
```

## Lazy menu loaded

Fires after menu content is loaded in `<i:menu-container>`.

```javascript
$(document).on('menu:loaded', function(event) {
    // custom action
});
```

---

---
url: /functions.md
---
# Functions and filters

This page documents custom Simplia functions. For standard Twig functions and filters, see the [official Twig documentation](https://twig.symfony.com/doc/2.x/). For an overview of custom Simplia filters, see the [Simplia filters](/twig#simplia-filters) section.

## uniqueEntities

Processes an array of entities, removes duplicates, and optionally limits the result to a given count. A typical use case is displaying five products that are similar, in the same category, or on sale (depending on what is available).

If a maximum count is defined, items are iterated only until the count is met. If two product listings are defined as sources and the count is already satisfied by the first, the second is never loaded from the database.

```twig
{% for image in uniqueEntities([product.image, product.currentImages, product.imagesWithoutEnumValue], 5) %}
    {{ image.alt }}
{% endfor %}
```

---

---
url: /getting-started.md
---
# Getting Started

This guide covers the minimum file set needed for a working Simplia template, explains how pages are rendered, and walks through adding a content section. Based on the **buran** production template.

## Minimal template

A working template requires four files:

```
template/
├── _base.tpl        {# layout wrapper - wraps every page #}
├── config.json      {# template configuration #}
├── index.tpl        {# homepage content #}
└── css/
    └── base.scss    {# main stylesheet (required entry point for SCSS) #}
```

### Minimal \_base.tpl

The layout wrapper includes a header, renders the current page template, and includes a footer. This is simplified from the buran `_base.tpl` -- feature-toggle conditionals have been stripped to show the core structure:

```twig
{# _base.tpl - the outermost layout wrapper for every page #}

{# Detect checkout pages: sekce_kosik = "cart section" #}
{% set sekce_kosik = false %}
{% if iUrl('Objednavka/Kosik') in URI %}
    {% set sekce_kosik = true %}
{% endif %}

{# Choose header: checkout pages get a simplified header #}
{% if sekce_kosik and kos and sekce %}
    {% include '_header-checkout.tpl' %}
{% else %}
    {% include '_header.tpl' %}
{% endif %}

{# Main content area - this.template resolves to the current page's .tpl file #}
<main id="main" role="main" data-template="{{ this.templateName }}">
    {% include this.template %}
</main>

{# Footer: checkout pages get a simplified footer #}
{% if sekce_kosik and kos %}
    {% include '_footer-checkout.tpl' %}
{% else %}
    {% include '_footer.tpl' %}
{% endif %}
```

Key points:

* `{% include this.template %}` is the core mechanism -- the system sets `this.template` to the correct page file (e.g., `zbozi.tpl` for product detail)
* `this.templateName` returns the current template name without extension (e.g., `zbozi`, `vypis`)
* `sekce_kosik` (literally "cart section") detects checkout pages via `iUrl('Objednavka/Kosik')` -- the internal cart URL
* `kos` is the cart object, `sekce` is the current checkout step name
* `URI` is the current request URI

### Minimal config.json

```json
{
    "responsive": true,
    "webfonts": [
        "Manrope:500,600,700"
    ],
    "plugins": {
        "jquery": "3.4",
        "foundation": "6.4"
    },
    "cartSteps": [
        {
            "handles": ["content"]
        },
        {
            "handles": ["delivery"],
            "query": "dodani"
        },
        {
            "handles": ["address"],
            "query": "adresa"
        }
    ],
    "features": [
        "syntax2019"
    ]
}
```

* `responsive` -- enables viewport meta tag and responsive behavior
* `webfonts` -- Google Fonts loaded automatically
* `plugins` -- JS/CSS libraries injected before your code; `jquery` and `foundation` are the minimum for interactive templates
* `cartSteps` -- defines the checkout flow; `handles` are step identifiers, `query` is the URL query parameter for that step (`dodani` = delivery, `adresa` = address)
* `features` -- feature flags; `syntax2019` enables modern template syntax support

For the full config.json reference, see [Configuration](/config).

### Minimal css/base.scss

```scss
/* base.scss - required SCSS entry point */
/* All other .scss files should be @import-ed from here */

/* Optional: _settings.scss is injected before plugin styles,
   allowing you to override Foundation variables, colors, etc. */

body {
    font-family: 'Manrope', sans-serif;
}
```

The build system compiles SCSS in this order:

1. `_settings.scss` (if present) -- injected before plugin styles
2. Plugin styles (Foundation, etc.)
3. `base.scss` -- your main stylesheet

## Page-to-file mapping

Each shop page type maps to a specific template file. The system automatically selects the file based on the current URL and sets `this.template`.

| Shop page | Template file | Czech name | Key variables |
|---|---|---|---|
| Homepage | `index.tpl` | Uvodní stránka | `repository`, `this.contentGrid()` |
| Product detail | `zbozi.tpl` | Zboží | `product` |
| Category listing | `vypis.tpl` | Výpis | `kategorie`, `this.nazev` |
| Search results | `vyhledavani.tpl` | Vyhledávání | search query in URL |
| Cart | `kosik.tpl` | Košík | `kos`, `cart`, `sekce` |
| Order confirmation | `potvrzeni.tpl` | Potvrzení | `order` |
| Order management | `objednavka.tpl` | Objednávka | `order` |
| Registration | `registrace.tpl` | Registrace | form fields |
| Static page | `stranka.tpl` | Stránka | `textPage` |
| Article | `clanek.tpl` | Článek | `article` |
| Store detail | `prodejna.tpl` | Prodejna | `store` |
| Contact | `kontakty.tpl` | Kontakty | contact info |

Czech identifier glossary:

* `zbozi` = goods/product, `vypis` = listing, `kosik` = cart/basket
* `potvrzeni` = confirmation, `objednavka` = order, `registrace` = registration
* `stranka` = page, `clanek` = article, `prodejna` = store, `kontakty` = contacts
* `this.nazev` = current page title (nazev = name)

See [Object Types](/objects) for the full reference on `product`, `category`, `order`, and other objects.

## Page rendering flow

When a visitor opens a URL, the rendering proceeds through four stages:

```
1. URL resolution
   URL is resolved to a page type (e.g., /product/some-name -> product detail)
   The system binds variables: this.template = 'zbozi.tpl', product = <product object>

2. _base.tpl loads
   The layout wrapper begins rendering

3. Conditional header
   {% if sekce_kosik %} -> _header-checkout.tpl (simplified: logo + step indicators)
   {% else %}           -> _header.tpl (full: logo, navigation, search, cart icon)

4. {% include this.template %} renders the page-specific file
   e.g., zbozi.tpl renders inside <main> using the bound variables

5. Conditional footer
   {% if sekce_kosik %} -> _footer-checkout.tpl (simplified)
   {% else %}           -> _footer.tpl (full footer with links, contact, social)
```

### Concrete example: product detail

```
Visitor opens: /product/blue-sneakers

1. URL resolution -> page type: product detail
2. Variable binding:
   - this.template = 'zbozi.tpl'
   - this.templateName = 'zbozi'
   - product = {name: "Blue Sneakers", price: ..., image: ...}
3. _base.tpl renders:
   a. sekce_kosik = false (not a cart URL) -> includes _header.tpl
   b. {% include this.template %} -> renders zbozi.tpl
      zbozi.tpl can access {{ product.name }}, {{ product.price }}, etc.
   c. sekce_kosik = false -> includes _footer.tpl
```

### Header selection logic

`_base.tpl` chooses between two headers:

* **`_header.tpl`** -- full header with logo, navigation menu, search bar, cart icon, user account links
* **`_header-checkout.tpl`** -- simplified header for checkout pages (logo + checkout step indicators only)

The condition is `{% if sekce_kosik and kos and sekce %}` where:

* `sekce_kosik` = true when the URL contains the cart path
* `kos` = the cart object (truthy when a cart exists)
* `sekce` = current checkout step name (`'udaje'`, `'dodani'`); null/empty on the initial cart step (equivalent to `'kosik'`)

### Content area

The `<main>` tag wraps the page content. The `data-template` attribute is set to `this.templateName` for CSS/JS targeting:

```html
<main id="main" role="main" data-template="zbozi">
    <!-- zbozi.tpl content rendered here -->
</main>
```

This allows page-specific styling: `main[data-template="zbozi"] { ... }`

## Adding a content section

Content grid allows shop admins to configure content blocks through the admin panel without template code changes. Here is a step-by-step example adding a USP (Unique Selling Proposition) bar with repeatable image + text items.

### Step 1: Create the XML schema

Create `content-grid/header-usp.xml`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://tpldoc.simplia.cz/xsd/content-grid.xsd">
    <config>
        <name>Header - USP</name>
        <translations>true</translations>      <!-- separate content per language -->
        <mode>part</mode>                       <!-- "part" = one section, not a full page layout -->
        <supported-context type="global"/>      <!-- available on all pages, not tied to a product/article -->
    </config>

    <grid>
        <!-- multiple="true" means admins can add/remove/reorder items -->
        <row code="item" label="USP" multiple="true">
            <content type="image" label="Icon" code="image" width="30" />
            <content type="html_simple" label="Text" code="text" width="70" />
        </row>
    </grid>
</schema>
```

Key attributes:

* `multiple="true"` on `<row>` -- admins can add zero or more items, and reorder them
* `code="item"` -- how you access this row in Twig: `this.contentGrid('header-usp').item`
* `type="image"` -- image upload field; `type="html_simple"` -- basic rich text editor
* `width` -- percentage width in the admin panel layout (visual only, not output)

### Step 2: Reference in template

Use `this.contentGrid('section-name')` where the name matches the XML filename without extension:

```twig
{# In _header.tpl or wherever you want the USP bar #}
{% if this.contentGrid('header-usp') %}
    <div class="usp-bar grid-x">
        {% for item in this.contentGrid('header-usp').item %}
            <div class="usp-item cell auto">
                {# Render the uploaded icon image #}
                <i:img src="item.image" format="30x30" loading="lazy" vector transparent />
                {# Render the rich text content #}
                <span>{{ item.text }}</span>
            </div>
        {% endfor %}
    </div>
{% endif %}
```

Pattern notes:

* Always wrap in `{% if this.contentGrid('...') %}` -- returns null if no content has been configured
* `this.contentGrid('header-usp').item` returns an array because of `multiple="true"`
* `i:img` is the platform image tag with responsive format support (see [Syntax](/syntax))

### Step 3: Admin configuration

Once the XML file is deployed and the template references it, the content grid section automatically appears in the admin panel under template settings. Shop administrators fill in the content through a visual editor -- no further code is needed.

For the full content grid reference including all content types (string, html, image, color, url, category, product, product\_list, select, article, text\_page), see [Content Grid](/content-grid).

## Next steps

* [Template file structure](/files) -- directory layout and naming conventions
* [Configuration](/config) -- config.json options in detail
* [Syntax](/syntax) -- Twital custom tags (`i:img`, `i:list-container`, `if:class`, etc.)
* [Object Types](/objects) -- `product`, `category`, `cart`, and other object references
* [Examples](/examples) -- complete code recipes from production templates

---

---
url: /global.md
---
# Global elements

This page describes system elements that are automatically injected into templates. Their HTML structure and behavior are controlled by the system — in the template you can only affect their appearance via CSS.

Global variables available in all templates (`cart`, `customer`, `shop`, `repository`, etc.) can be found in the [object reference](/objects).

## Announcements

In the admin panel under Texts / Announcements, you can create informational announcements that are displayed above the website. Announcements have a defined validity period, display style, and an optional close button. The styles are predefined and announcements should work without any template modifications.

To test announcements while working on a template, you can trigger a placeholder announcement by adding a URL parameter:

* `?_previewAnnouncement=info`
* `?_previewAnnouncement=warning`
* `?_previewAnnouncement=important`

The HTML is fixed and generated automatically, but you can adjust the appearance via CSS in the template. When modifying the appearance, only cosmetic tweaks should be made — matching the announcement color shade, font size, and similar. Larger changes should always be made centrally in the system.

Likewise, it is not possible to attach custom JavaScript to announcements in the template.

In the admin panel, announcements currently support switching between these classes:

* `global-announcement--info`
* `global-announcement--warning`
* `global-announcement--important`

```html
<div class="global-announcement global-announcement--warning global-announcement--has-close">
  <div class="global-announcement__inner">
      Announcement text with a <a href="/">link</a> and <strong>highlighting</strong>
    <a class="global-announcement__close" href="#" onclick="..."></a>
  </div>
</div>
```

---

---
url: /html.md
---
# HTML Elements

## i:img (images)

Renders an image for a product, category, article, etc. Not used for static template images (icons, etc.).

Handles thumbnail URL generation, retina display support, and automatic image alt text.

When multiple dimensions are specified, a srcset is generated that can be used in combination with the HTML5 *sizes* attribute. If the *sizes* attribute is omitted, *width* and *height* attributes are set based on the actual resulting image dimensions.

If the **alt** attribute is not specified, it is automatically populated from the image description or the product/variant/... name.

The output differs depending on the device (retina/non-retina) and load order (first/subsequent). **Retina images may overflow -- you must handle this in CSS**, for example with *max-width:100%;max-height:100%*.

```twig
<i:img src="zbozi.img" format="800x600" />
<i:img src="zbozi.img" format="800x600,300x200" sizes="(min-width: 500px) 50vw, 100vw" />
```

**Attributes**

| Attribute | Required | Description |
|---|---|---|
| **src** | **yes** | Twig object |
| **format** | **yes** | image dimensions |
| sizes | *no* | same as HTML5 sizes -- required when multiple dimensions are specified |
| watermark | *no* | image will have a watermark |
| fill | *no* | pad the image with white borders |
| vector | *no* | use PNG/SVG |
| transparent | *no* | image has transparency |
| quality | *no* | low/normal/high/lossless (default: normal) |
| lazyload | *no* | *src* and *srcset* as data attributes |
| class | --- | CSS class |

### Image Zoom

Wrap an image in a link with **@** as the href -- it will be replaced with the appropriate URL. The link may contain **only one image**. If you need a conditional, use two separate links.

```twig
<a href="@"><i:img src="zbozi.img" format="800x600" /></a>
<a href="@"><i:img src="zbozi.img" format="800x600" sizes="(min-width: 500px) 50vw, 100vw" /></a>
```

## i:img360 -- 360 Product View

```twig
<i:img-360 product="product" />
<i:img-360 product="product" format="800x600,300x200" sizes="(min-width: 500px) 50vw, 100vw"/>
```

**Attributes**

| Attribute | Required | Description |
|---|---|---|
| **product** | **yes** | Product object |
| format | *no* | image dimensions (same as i:img). Default: \[500x500, 1000x1000, 1500x1500, 2000x2000] |
| sizes | *no* | responsiveness for images (same as i:img) -- required when multiple dimensions are specified |
| zoom | *no* | integer zoom value (default: 3) |
| no-steps | *no* | hide forward/backward step buttons |
| no-fullscreen | *no* | hide fullscreen button |
| no-play | *no* | hide play/stop button |
| hide-logo | *no* | hide 360 view logo |
| bottom-circle | *no* | show bottom 360 circle |
| lazyload | *no* | load library and images only when the element enters the viewport |
| lazyload="click" | *no* | load library and images only when the element is clicked |
| hidden | *no* | element is hidden (display:none) and activated via JS (used for fancybox) |
| autoplay | *no* | |

To display inside a FancyBox, add a thumbnail image and a hidden player. The specific class name does not matter -- what matters is pairing the thumbnail with the player.

```twig
<a data-src=".hidden-fancybox-360" data-type="inline" href="javascript:;" data-fancybox>
    <i:img src="product.firstImage360" format="350x350" />
</a>

<i:img-360 product="product" hidden class="hidden-fancybox-360" />
```

## i:video

```twig
{%for video in zbozi.videa%}
    <i:video src="video" width="400" height="300" />
{%endfor%}
{%for video in zbozi.videa%}
    <i:video src="video" width="400" height="300" class="embedded_video" />
{%endfor%}
```

**Attributes**

| Attribute | Required | Type | Description |
|---|---|---|---|
| **src** | **yes** | twig | Twig object |
| width | no | int | width in pixels (no units) |
| height | no | int | height in pixels (no units) |
| controls | no | string | `true` / `false` |
| loop | no | string | `true` / `false` |
| color | no | string | HEX color code for the icon |
| autoplay | no | | |
| class | --- | --- | CSS class |

## i:dynamic (attribute) -- dynamic section definition

Wrapping a section of code in an element with the *i:dynamic* attribute defines that this section needs to be dynamically updated from JavaScript. The attribute must list the variables used -- only these variables will be available inside the element (similar principle to a Twig [macro](https://twig.symfony.com/doc/1.x/tags/macro.html)).

Adding the *i:dynamic* attribute does not change the code's behavior -- the output remains the same. The only difference is a new attribute in the resulting HTML that enables reloading part of the page from JavaScript.

When reloading, you can also pass additional custom variables as "arguments". These are then available in the template via the "arguments" array. A typical use case is reloading a section that shows variant-specific information -- the newly selected variant can be passed as an argument.
Arguments are intended only for refining the selection and **cannot be used** to load entirely new content. The URL is public, so if an argument carried e.g. an order number, anyone could change the URL to see details of any order. For variant IDs and similar data, manual URL changes are harmless.

```twig
<div i:dynamic="cart,product" class="cart-items-table"> {# class is not required and can be anything #}
    {% if arguments['variant']|default(product.variant.id) %}
        abc
    {% endif %}
</div>
```

```javascript
$('.cart-items-table').reload(); // reload by class

$('.cart-items-table, .second-dynamic-div').reload(); // reload multiple sections at once

$('.cart-items-table').reload({
    callback: function() {
        alert('načteno!');
    }
});

$('.cart-items-table').reload({
    callback: function() {
        alert('načteno!');
    },
    arguments: {
        variant: 123
    }
});

$('.cart-items-table').reload({
    after:function(callback){
        // code that runs after the loading animation but before the actual reload
        // the reload is triggered by calling the callback
        // useful for async actions where you want the loading animation but delay the reload until completion
        callback();
    }
});
```

## i:dynamic (tag) -- dynamic section definition

Wrapping a section of code in an `<i:dynamic>` element defines that this section can be dynamically updated from JavaScript (automatically or manually).

The tag can be used for:

* reloading the element's content triggered by a JavaScript call
* deferring content generation until the element enters the viewport (lazy="auto")
* deferring content generation until explicitly requested from JavaScript (lazy="manual")

The *variables* attribute must list the variables used -- only these variables will be available inside the element (similar principle to a Twig [macro](https://twig.symfony.com/doc/1.x/tags/macro.html)).

```twig
{# content is rendered immediately with the page and can be refreshed from JavaScript #}
<i:dynamic variables="cart,product" class="cart-items-table"> {# class is not required and can be anything #}
    <h4>{{ product.name }}</h4>
</i:dynamic>

{# content is not rendered with the initial page load; it loads automatically when the element enters the viewport and can be refreshed from JavaScript #}
<i:dynamic variables="cart,product" lazy="auto" class="cart-items-table">
    <h4>{{ product.name }}</h4>
</i:dynamic>

{# content is not rendered with the initial page load; it loads only when reload() is called from JavaScript #}
<i:dynamic variables="cart,product" lazy="manual" class="cart-items-table">
    <h4>{{ product.name }}</h4>
</i:dynamic>
```

## i:map -- interactive map

The goal is to unify and simplify embedding maps in templates. The map automatically selects zoom and center based on the inserted points (**unless explicitly defined!**).

The map is rendered via mapy.cz, but support for additional map providers will likely be added in the future for language versions, etc. The template syntax is unified, and adding Google Maps support should not require any template changes.

```twig
<i:map grayscale class="map-class">
    <i:map-point address="Drtinova 10, Praha" icon="/images/logo.svg" size="40x50" header="Otevírací doba" tags="praha,kartou">
        Po: 08:00-18:00<br/>
        Út: 08:00-18:00<br/>
        St: 08:00-18:00<br/>
        Čt: 08:00-18:00<br/>
        Pá: 08:00-18:00<br/>
    </i:map-point>
    <i:map-point lat="50.65" lon="14.1456" icon="/images/logo.svg" size="40x50" label="Centrála" tags="usti,kartou"/>
    <i:map-point lat="51.00" lon="15.000" icon="/images/logo.svg" size="40x50" tags="andelka">
        <strong>{%trans%}Otevírací doba{%endtrans%}</strong> <br>
        08:00-18:00
    </i:map-point>

    {% for location in locations %}
        <i:map-point lat="{{location.lat}}" lon="{{location.lon}}" />
    {% endfor %}
</i:map>
```

```html
<!-- generated output -- subject to change! -->

<div class="map-class global-map grayscale">
    <span data-header="Otevírací doba" data-tags="praha,kartou" data-gps="50.0255597,14.5510733" data-icon="/1585575662/images/logo.svg" data-lat="50.0255597" data-lon="14.5510733">
        Po: 08:00-18:00<br>
        Út: 08:00-18:00<br>
        St: 08:00-18:00<br>
        Čt: 08:00-18:00<br>
        Pá: 08:00-18:00<br>
    </span>
    <span data-lat="50.65" data-lon="14.1456" data-label="Centrála" data-tags="usti,kartou" data-icon="/1585575662/images/logo.svg"></span>
    <span data-lat="51.00" data-lon="15.000" data-tags="andelka" data-icon="/1585575662/images/logo.svg">
        <strong>Otevírací doba</strong> <br>
        08:00-18:00
    </span>
    <div class="mapycz" style="height:400px"></div>
</div>
```

**i:map Attributes**

| Attribute | Required | Description |
|---|---|---|
| lat="" | *no* | latitude of the map center |
| lon="" | *no* | longitude of the map center |
| zoom="" | *no* | default map zoom |
| height="" | *no* | default map height (*400px*) |
| controls="off" | *no* | hide map controls |
| grayscale | *no* | |
| clusters="" | *no* | default distance for markers in a cluster (*40*) |
| cluster-class="" | *no* | custom class for the cluster |
| view="" | *no* | basic / hybrid / aviation / tourist / winter (default: *basic*) |
| view-layers="basic,aviation" | *no* | enable map layer switching -- basic / hybrid / aviation / tourist / winter (default: *"basic,aviation,hybrid,tourist,winter"*) |

**i:map-point Attributes**

| Attribute | Required | Description |
|---|---|---|
| lat="" and lon="" | **yes** | point coordinates. **Either lat/lon or address must be provided** |
| address="" | **yes** | point address. **Either lat/lon or address must be provided** |
| icon="/images/home.svg" | *no* | |
| size="20x20" | *no* | custom marker size. Default size: 23x32 |
| label="Centrala" | *no* | hover title |
| header="Opening hours" | *no* | card title |
| tags="praha" | *no* | tags separated by commas |
| code="xxx" | *no* | marker identifier |

### Custom Cluster Class

`<i:map cluster-class="embed-map-cluster"></i:map>`

cluster-class overrides the original class and creates new classes for the cluster.

**Attributes**

| Class | Description |
|---|---|
| **embed-map-cluster** | general class for all clusters |
| **embed-map-cluster-small** | < 10 points |
| **embed-map-cluster-medium** | < 40 points |
| **embed-map-cluster-large** | > 40 points |

### Opening a POI Externally

Call `window.mapComponent.openMarkerCard(code)` to open any POI detail.

```twig
<button type="button" class="show-marker-detail" data-code="simplia">Simplia</button>
<button type="button" class="show-marker-detail" data-code="test">Testovaci</button>

<i:map class="marker-map">
    <i:map-point address="Drtinova 10, Praha" code="simplia">
        Po: 08:00-18:00<br/>
        Út: 08:00-18:00<br/>
        St: 08:00-18:00<br/>
        Čt: 08:00-18:00<br/>
        Pá: 08:00-18:00<br/>
    </i:map-point>
    <i:map-point lat="51.00" lon="15.000" code="test">
        <strong>{%trans%}Otevírací doba{%endtrans%}</strong> <br>
        08:00-18:00
    </i:map-point>
</i:map>
```

```html
<script type="text/javascript">
    Array.prototype.forEach.call(document.querySelectorAll('.show-marker-detail'), function (el) {
        el.addEventListener('click', function (e) {
            e.preventDefault();

            var targetElement = e.target || e.srcElement;

            window.mapComponent.openMarkerCard('.marker-map', targetElement.dataset.code);
        });
    });
</script>
```

### Filtering Map Points

Filtering between tag arrays uses **AND** logic; within each tag array, **OR** logic is used. See the example: *Praha* **or** *Usti* **AND** *kartou* (card payment).

**window.mapComponent.filter Parameters**

| Attribute | Required | Description |
|---|---|---|
| selector | **yes** | map selector, e.g. **.global-map** |
| filter | **yes** | array of tag arrays |
| boolean | **no** | auto-center map on filtered POIs. **Default: false** |

```html
<script type="text/javascript">
    window.mapComponent.filter('.filter-map', [['praha', 'usti'], ['kartou']], true);
</script>
```

### Route Planning

Creates a URL via api.mapy.cz for route planning.

**i:map-route-link Attributes**

| Attribute | Required | Description |
|---|---|---|
| lat="" and lon="" | **yes** | point coordinates. **Either lat/lon or address must be provided** |
| address="" | **yes** | point address. **Either lat/lon or address must be provided** |

```twig
<i:map-route-link lat="50.7700158" lon="15.0595950">Popisek</i:map-route-link>
```

```html
<!-- generated output -- subject to change! -->

<a class="map-route-link" data-lat="50.7700158" data-lon="15.0595950" href="//mapy.cz/?planovani-trasy&amp;rc=95ra0x1qpF&amp;rs=&amp;rs=coor&amp;ri=&amp;ri=&amp;mrp=&amp;mrp={&quot;c&quot;:111}">
    Popisek
</a>
```

### Link to mapy.cz

Creates a URL to a POI on mapy.cz.

```twig
<i:map-link search="Helveti.cz">Helveti</i:map-link><br>
<i:map-link search="Jadi.cz, Praha">Jadi.cz Praha</i:map-link><br>
<i:map-link search="Jadi.cz, Liberec">JAdi.cz Liberec</i:map-link><br>
<i:map-link search="Jadi.cz">Jadi.cz</i:map-link><br>
<i:map-link search="Vítkova 244/8, Praha">Adresa</i:map-link>
```

```html
<!-- generated output -- subject to change! -->
<a class="map-link" href="//mapy.cz/zakladni?x=14.446071624756&amp;y=50.090213775635&amp;id=12903247&amp;source=firm">Helveti</a><br>
<a class="map-link" href="//mapy.cz/zakladni?x=14.429894447327&amp;y=50.081184387207&amp;id=12914136&amp;source=firm">Jadi.cz Praha</a><br>
<a class="map-link" href="//mapy.cz/zakladni?x=15.056777954102&amp;y=50.770107269287&amp;id=2099659&amp;source=firm">JAdi.cz Liberec</a><br>
<a class="map-link" href="//mapy.cz/zakladni?x=15.172479629517&amp;y=50.72388458252&amp;id=726263&amp;source=firm">Jadi.cz</a><br>
<a class="map-link" href="//mapy.cz/zakladni?q=V%C3%ADtkova+244%2F8%2C+Praha">Adresa</a>
```

## i:banners

Template for unified banner output.

In the examples below, the `i:****` tags are the important part -- the rest of the template markup will differ per shop due to legacy code.

```twig
<i:banners source="repository.banner.findBy({sectionCode: 'testovaci'})" plugin="swiper">
    <source format="1150x630" src="desktop"/>
</i:banners>
```

```html
<!-- generated output -- subject to change! -->

<div class="banner swiper-container">
    <div class="banner-wrap swiper-wrapper">
        <div class="banner-item banner--item__1 banner--item__first swiper-slide">
            <picture>
                <img width="1150" height="630"
                          srcset="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp 1x,//i00.eu/img/999997/2300x1260/25nkjd5z/2229.webp 2x"
                          src="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp">
            </picture>
        </div>
        <div class="banner-item banner--item__2 banner--item__last swiper-slide">
            <picture>
                <img class="auto-lazyload swiper-lazy" width="1150" height="599"
                          data-srcset="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp 1x,//i00.eu/img/999997/2300x1260/b9whiv1f/2237.webp 2x"
                          src="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp"
                          data-src="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp"
                          srcset="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp 1x,//i00.eu/img/999997/2300x1260/b9whiv1f/2237.webp 2x"
                          data-loaded="true">
            </picture>
        </div>
    </div>
</div>
```

Example using an inner wrapper div.

```twig
<i:banners source="repository.banner.findBy({sectionCode: 'testovaci'})" wrap="div.wrap.www-rap">
    <source format="1150x630" src="desktop"/>

    <h2 data-role="title"></h2>
    <div data-role="description"></div>
    <div data-role="cta"></div>
</i:banners>
```

```html
<div class="banner">
    <div class="banner-wrap">
        <div class="banner-item banner--item__1 banner--item__first">
            <div class="wrap www-rap">
                <picture>
                    <img width="1150" height="630"
                              srcset="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp 1x,//i00.eu/img/999997/2300x1260/25nkjd5z/2229.webp 2x"
                              src="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp">
                </picture>
                <div class="banner-info">
                    <h2 class="banner-info__headline">První Slide</h2>
                    <div class="banner-info__description">Popisek....</div>
                    <a class="button banner-info__button" href="https://www.simplia.cz">CTA</a>
                </div>
            </div>
        </div>
        <div class="banner-item banner--item__2">
            <div class="wrap www-rap">
                <picture>
                    <img class="auto-lazyload" width="1150" height="630"
                              data-srcset="//i00.eu/img/999997/1150x630a/79l5pfe2/2234.webp 1x,//i00.eu/img/999997/2300x1260/acf5nmee/2234.webp 2x"
                              src="//i00.eu/img/999997/1150x630a/79l5pfe2/2234.webp"
                              data-src="//i00.eu/img/999997/1150x630a/79l5pfe2/2234.webp"
                              srcset="//i00.eu/img/999997/1150x630a/79l5pfe2/2234.webp 1x,//i00.eu/img/999997/2300x1260/acf5nmee/2234.webp 2x"
                              data-loaded="true">
                </picture>
                <div class="banner-info">
                    <h2 class="banner-info__headline">Druhý slide</h2>
                    <div class="banner-info__description">popis :)</div>
                    <a class="button banner-info__button">CTA</a>
                </div>
            </div>
        </div>
        <div class="banner-item banner--item__3 banner--item__last">
            <div class="wrap www-rap">
                <picture>
                    <img class="auto-lazyload" width="1150" height="599"
                              data-srcset="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp 1x,//i00.eu/img/999997/2300x1260/b9whiv1f/2237.webp 2x"
                              src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1150 599'%3E%3C/svg%3E"
                              data-src="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp">
                </picture>
                <div class="banner-info">
                    <h2 class="banner-info__headline">Třetí slide</h2>
                </div>
            </div>
        </div>
    </div>
</div>
```

Nesting banner classes.

```twig
<i:banners source="repository.banner.findBy({sectionCode: 'testovaci'})" wrap="div.inner-wrap-class" banner-item-class="custom-item-class" banner-wrap-class="extra-banner-wrap">
    <source format="1150x630" src="desktop"/>
</i:banners>
```

```html
<div class="banner">
    <div class="banner-wrap extra-banner-wrap">
        <div class="banner-item banner--item__1 banner--item__first banner--item__last custom-item-class">
            <div class="inner-wrap-class">
                <picture>
                    <img width="1150" height="630"
                         srcset="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp 1x,//i00.eu/img/999997/2300x1260/25nkjd5z/2229.webp 2x"
                         src="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp">
                </picture>
            </div>
        </div>
    </div>
</div>
```

Banner title tooltip.

```twig
<i:banners source="repository.banner.findBy({sectionCode: 'testovaci'})">
    <source format="1150x630" src="desktop"/>

    <h2 data-role="title" tooltip></h2>
    <span data-role="cta"></span>
</i:banners>
```

```html
<div class="banner">
    <div class="banner-wrap">
        <div class="banner-item banner--item__1 banner--item__first banner--item__last">
            <picture>
                <img width="1150" height="630"
                          srcset="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp 1x,//i00.eu/img/999997/2300x1260/25nkjd5z/2229.webp 2x"
                          src="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp">
            </picture>
            <div class="banner-info">
                <h2 class="banner-info__headline">
                    První Slide
                    <span class="banner-info__headline-tooltip-text">Popisek....</span>
                </h2>
                <a class="button banner-info__button" href="https://www.simplia.cz">CTA</a>
            </div>
        </div>
    </div>
</div>
```

**Banner Parameters**

| Parameter | Required | Description |
|---|---|---|
| source | *yes* | `repository.banner.findBy()` |
| priority | *no* | allowed values: `high` / `low` (*default: high*). **low** -- lazyload on all images; **high** -- respects `visible-slides` |
| visible-slides | *no* | number of banners without lazyload (*default: 1*) |
| wrap | *no* | inner banner wrapper |
| class | *no* | add a custom class |
| banner-item-class | *no* | add a custom class to the banner items wrapper |
| banner-wrap-class | *no* | add a custom class to individual banner wrappers |
| picture-class | *no* | add a custom class to the picture wrapper |
| plugin | *no* | add helper classes for a specific plugin, e.g. `swiper` |
| click | *no* | configure banner click behavior. Allowed values: `banner` / `cta` / `off`. |

**Banner Attributes**

| Attribute | Required | Description |
|---|---|---|
| arrows | *no* | show arrows for slide navigation |
| dots | *no* | show slide navigation dots |
| progress | *no* | show progress bar |
| thumbnails | *no* | show thumbnails with banner titles |
| transparent | *no* | image has transparency |
| fill | *no* | pad image with white borders |

**Banner source elements**

| data-role | Required | Attributes |
|---|---|---|
| desktop | *yes* | **format** -- required banner dimensions, **sizes** -- same as HTML5 sizes, required when multiple dimensions are specified (*default: 80vw*), **class** -- add a custom class |
| tablet | *no* | **format** -- banner dimensions, **sizes** -- same as HTML5 sizes, required when multiple dimensions are specified, **media** -- same as HTML5 media, **class** -- add a custom class |
| mobile | *no* | **format** -- banner dimensions, **sizes** -- same as HTML5 sizes, required when multiple dimensions are specified, **media** -- same as HTML5 media, **class** -- add a custom class |

**Complete data-role list for banners**

| data-role | Required | Attributes |
|---|---|---|
| info-box | *no* | tag definition |
| title | *no* | tag definition |
| description | *no* | tag definition |
| cta | *no* | tag definition |

```twig
<i:banners source="repository.banner.findBy({sectionCode: 'testovaci'})" plugin="swiper" class="custom-class,super-class" click="banner" arrows dots progress>
    <source format="1150x630" src="desktop"/>
    <source media="(min-width: 440px) and (max-width: 768px)" format="748x486,249x162" sizes="100vw" src="tablet"/>
    <source media="max-width: 440px" format="640x790,320x340" sizes="100vw" src="mobile"/>

    <div data-role="info-box" class="infobox-extra-class" ></div>
    <h2 data-role="title"></h2>
    <div data-role="description"></div>
    <span data-role="cta"></span>
</i:banners>
```

```html
<!-- generated output -- subject to change! -->

<div class="banner custom-class super-class swiper-container">
    <div class="banner-wrap swiper-wrapper">
        <div class="banner-item banner--item__1 banner--item__first swiper-slide">
            <a href="https://www.simplia.cz">
                <picture>
                    <source srcset="//i00.eu/img/999997/640x790a/5e37hrnn/2227.webp 640w,//i00.eu/img/999997/320x340a/5072sf1e/2227.webp 320w"
                            media="max-width: 440px" sizes="100vw">
                    <source srcset="//i00.eu/img/999997/748x486a/cr5pv3u6/2228.webp 748w,//i00.eu/img/999997/249x162a/85hs2grx/2228.webp 249w"
                            media="(min-width: 440px) and (max-width: 768px)" sizes="100vw">
                    <img width="1150" height="630"
                         srcset="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp 1x,//i00.eu/img/999997/2300x1260/25nkjd5z/2229.webp 2x"
                         src="//i00.eu/img/999997/1150x630a/562ojxe8/2229.webp">
                </picture>
                <div class="banner-info infobox-extra-class">
                    <h2 class="banner-info__headline">První Slide</h2>
                    <div class="banner-info__description">Popisek....</div>
                    <span class="button banner-info__button">CTA</span>
                </div>
                <div class="banner-progress">
                    <div class="progress"></div>
                </div>
            </a>
        </div>
        <div class="banner-item banner--item__2 banner--item__last swiper-slide">
            <picture>
                <source srcset="//i00.eu/img/999997/640x790a/1ihskwis/2239.webp 640w,//i00.eu/img/999997/320x340a/4dkf8gy0/2239.webp 320w"
                        media="max-width: 440px" sizes="100vw">
                <source srcset="//i00.eu/img/999997/748x486a/697q3ssb/2238.webp 748w,//i00.eu/img/999997/249x162a/25bq8xs2/2238.webp 249w"
                        media="(min-width: 440px) and (max-width: 768px)" sizes="100vw">
                <img class="auto-lazyload swiper-lazy" width="1150" height="599"
                     data-srcset="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp 1x,//i00.eu/img/999997/2300x1260/b9whiv1f/2237.webp 2x"
                     src="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp"
                     data-src="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp"
                     srcset="//i00.eu/img/999997/1150x630a/a7mwzmns/2237.webp 1x,//i00.eu/img/999997/2300x1260/b9whiv1f/2237.webp 2x"
                     data-loaded="true">
            </picture>
            <div class="banner-info infobox-extra-class">
                <h2 class="banner-info__headline">Druhý slide</h2>
            </div>
            <div class="banner-progress">
                <div class="progress"></div>
            </div>
        </div>
    </div>
    <div class="pagination swiper-pagination"></div>
    <div class="button-next swiper-button-next"></div>
    <div class="button-prev swiper-button-prev"></div>
</div>
```

---

---
url: /url.md
---
# Internal Links

For linking within the shop, hard-coded URLs are never used. Instead, always use the dynamic URL generation function. It automatically ensures links remain functional after future URL changes or across language versions.

```twig
<a href="{{ iUrl('Objednavka/Kosik') }}">Košík</a>
<a href="{{ iUrl('Vypis/Cena', {od:0, do:500}) }}">Zboží od 0 Kč do 500 Kč</a>
```

## Orders

**Available iUrl parameters**

| Presenter | Parameters | Meaning | Description |
|---|---|---|---|
| Objednavka/Kosik | --- | Order/Cart | cart page |
| Objednavka/Kosik | sekce | Order/Cart section | cart section (e.g. address, delivery, ...) |
| Objednavka/Pokladna | --- | Order/Checkout | order summary / checkout |
| Objednavka/Platba | objednavka | Order/Payment | payment for a completed order |
| Objednavka/Rychlokos | --- | Order/QuickCart | zero-step order (instant checkout) |
| Objednavka/Vypis | --- | Order/List | orders of the logged-in user |

## Product Listings

**Available iUrl parameters**

| Presenter | Parameters | Meaning | Description |
|---|---|---|---|
| Vypis/Vybrane | vyber | Listing/Selected | product listing by ID (IDs separated by hyphens) |
| Vypis/Porovnani | --- | Listing/Comparison | product comparison listing |
| Vypis/Akce | --- | Listing/Sale | products on sale |
| Vypis/Akce | kategorie | Listing/Sale | sale products in a category (link) |
| Vypis/AkceSleva | --- | Listing/SaleDiscount | products on sale or discounted |
| Vypis/AkceSleva | kategorie | Listing/SaleDiscount | sale or discounted products in a category (link) |
| Vypis/Slevy | --- | Listing/Discounts | discounted products |
| Vypis/Slevy | kategorie | Listing/Discounts | discounted products in a category (link) |
| Vypis/Skladem | --- | Listing/InStock | products in stock |
| Vypis/Skladem | kategorie | Listing/InStock | products in stock in a category (link) |
| Vypis/SlevyVyprodej | --- | Listing/DiscountsClearance | discounted or clearance products |
| Vypis/SlevyVyprodej | kategorie | Listing/DiscountsClearance | discounted or clearance products in a category (link) |
| Vypis/Vyprodej | --- | Listing/Clearance | clearance products |
| Vypis/Vyprodej | kategorie | Listing/Clearance | clearance products in a category (link) |
| Vypis/Cena | od, do | Listing/Price | products by price (od = from, do = to) |
| Vypis/Cena | od, do, kategorie | Listing/Price | products by price in a category (link) |
| Vypis/Nejnovejsi | --- | Listing/Newest | newest products |
| Vypis/Nejnovejsi | kategorie | Listing/Newest | newest products in a category (link) |
| Vypis/Nejnovejsi | datum | Listing/Newest | newest products since a date |
| Vypis/Nejnovejsi | datum, kategorie | Listing/Newest | newest products since a date in a category (link) |
| Vypis/Nejprodavanejsi | --- | Listing/BestSelling | best-selling products |
| Vypis/Nejprodavanejsi | kategorie | Listing/BestSelling | best-selling products in a category (link) |
| Vypis/VyrobceKategorie | vyrobce, kategorie | Listing/ManufacturerCategory | products by manufacturer (link) in a category (link) |
| Vypis/Vyhledavani | --- | Listing/Search | search page |
| Vypis/Vyhledavani | fraze | Listing/Search | search by phrase |

## User

**Available iUrl parameters**

| Presenter | Parameters | Meaning | Description |
|---|---|---|---|
| User/Login | --- | User/Login | login form |
| User/Registrace | --- | User/Registration | registration |
| User/HesloPozadavek | --- | User/PasswordRequest | forgotten password |
| Wish/Vypis | --- | Wishlist/List | wishlist |
| Objednavka/Vypis | --- | Order/List | orders of the logged-in user |

## Other

**Available iUrl parameters**

| Presenter | Parameters | Meaning | Description |
|---|---|---|---|
| Vyrobce/Vypis | --- | Manufacturer/List | manufacturer listing |
| Tema/Vypis | --- | Topic/List | topic listing (magazine) |
| Recenze/Vypis | --- | Review/List | customer reviews |
| Novinka/Vypis | --- | News/List | news listing |
| Video/Vypis | --- | Video/List | video listing |
| Page/Mapa | --- | Page/Sitemap | sitemap |

## Language Links

The following syntax can be used to link to language-specific domains. The domain is filled in automatically based on configuration, and the subpage URL is generated from the current address.

```twig
<a href="{{this.langUrl('en')}}" lang="en" hreflang="en">english</a>
<a href="{{this.langUrl('cz')}}" lang="cs" hreflang="cs">česky</a>
```

Listing links to all language versions of the current page:

```twig
{%for data in this.languageUrls%}
    <a href="{{data.url}}" lang="{{data.locale}}" hreflang="{{data.locale}}">{{data.language|upper}}</a>
{%endfor%}
```

---

---
url: /list.md
---
# Listings

## List-container

Renders a product listing using the *list-item* template. If no products are found, the message defined in *list-empty* is displayed.

The **optional** *data-role="pagination"* element is populated with content defined via *pagination* in the `_listing.tpl` (listing definitions) file (`_listing_article.tpl` for articles, etc.). Different templates can be specified using the *data-name* attribute.

**WARNING!** You must not wrap the pagination in a conditional display check. Such code would break when filtering via AJAX. If you need to hide pagination for single-page listings, add the condition inside `<i:list-pagination>` instead.

```twig
{# uses the "default" (or unnamed) template from _listing.tpl #}
<i:list-container type="product">
    <div data-role="pagination"></div>
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

```twig
<i:list-container type="product">
    <div data-role="pagination"></div>
    <div data-role="empty"></div>
    <div data-role="list" data-name="short"></div>
    <div data-role="pagination" data-name="simple" ></div>
</i:list-container>
```

```twig
{# wrap boxes in groups of three into .wrap, insert <hr> between groups, and add class "third" #}
<i:list-container type="product" wrap="3:div.wrap" append="3:hr" box-class="3:third">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

```twig
{# wrap boxes in groups of three into .wrap and .www-rap, insert <hr> between groups, and add class "third" #}
<i:list-container type="product" wrap="3:div.wrap.www-rap" append="3:hr" box-class="3:third">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

```twig
{# uses the "news" template from _listing.tpl #}
<i:list-container type="product" name="news">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

**Attributes of list-container**

| Attribute | Required | Description |
|---|---|---|
| **type** | **yes** | listing type |
| source | *no* | Twig object with listing parameters (cannot be combined with *collection*) |
| collection | *no* | list of items to render (cannot be combined with *source* and does not support pagination) |
| name | *no* | item template name (as defined by *list-item*) |
| analytics-name | *no* | label for analytics tracking (e.g. "product.detail.bottom") |
| wrap | *no* | wrap groups of boxes |
| append | *no* | append a tag after a group of boxes |
| box-class | *no* | add a CSS class |
| hide-empty | *no* | hide the entire container when it has no items (no value needed) |
| scroll-offset | *no* | CSS selector for accounting for a fixed header |
| insert-before | *no* | name of a listing-insert template to insert before each item |
| insert-after | *no* | name of a listing-insert template to insert after each item |
| insert-arguments | *no* | arguments to pass to the insert template - Twig written as {{ {abc: product.id} }} is processed via json\_encode, so only simple values (numbers, arrays, simple objects) are supported |
| class | --- | CSS class |

### hide-empty - hide listing with no items

When the *hide-empty* attribute is present (specified without a value), the container is not rendered at all if it contains no items. With this attribute, the empty listing definition is not used.

```twig
<i:list-container type="product" source="{kategorie:123,limit:10}" hide-empty>
    <div data-role="list"></div>
</i:list-container>
```

### source - listing parameters

If the *source* attribute is not specified, the default listing for the current page is used. For example, a category page will list products from that category, etc. A listing without a specified *source* updates the URL on changes (page, filter, ...).

Global variables can be used in the parameters, but no local variables are allowed. The expression must work identically even if the rest of the template is deleted.

```twig
<i:list-container type="product" source="{kategorie:123,limit:10}">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

```twig
<i:list-container type="product" source="{kategorie:kategorie.id,limit:10}">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

### wrap - wrapping boxes into a single tag

The *wrap* attribute defines which tag with which class *(class is optional)* and under what conditions the boxes should be wrapped.

```twig
<i:list-container source="zdroj_zbozi" wrap="3:ul.sublist" class="list">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

```html
<div class="list">
    <ul class="sublist">
        <li>product</li>
        <li>product</li>
        <li>product</li>
    </ul>
    <ul class="sublist">
        <li>product</li>
        <li>product</li>
        <li>product</li>
    </ul>
    <ul class="sublist">
        <li>product</li>
    </ul>
</div>
```

### append - inserting a tag by position

The *append* attribute specifies a tag to insert after rendered boxes according to conditions. Multiple conditions can be specified, separated by commas -- the first matching tag is used.

```twig
<i:list-container append="3:hr.divider,last:hr.last" class="list">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

```html
<div class="list">
    <div class="item">product</div>
    <div class="item">product</div>
    <div class="item">product</div>
    <hr class="divider"/>
    <div class="item">product</div>
    <div class="item">product</div>
    <div class="item">product</div>
    <hr class="divider"/>
    <div class="item">product</div>
    <hr class="last"/>
</div>
```

## List pagination

Pagination definition -- always in the **\_listing.tpl** file. Defines a macro that is subsequently used for product listing in *list-container*.

Typically contains pagination, record count information, etc.

Global variables are not accessible; only the **pagination** and **filterActive** variables are available.

```twig
{# _listing.tpl #}
<i:list-pagination>
    {%if pagination.stran > 1%}
        {%trans%}celkem položek{%endtrans%}: <strong>{{pagination.nsum}}</strong>
        {%trans%}strana{%endtrans%}:  <strong>{{pagination.strany|raw}}</strong>
    {%endif%}
</i:list-pagination>
```

```twig
{# _listing.tpl #}
<i:list-pagination>
    {# appends the next page to the listing instead of changing the page #}
    <button data-role="add-page">{% trans 'listing.show-more-products' %}</button>
</i:list-pagination>
```

**Attributes of pagination**

| Attribute | Default | Description |
|---|---|---|
| **type** | --- | item type *(product, article, ...)* |
| name | *default* | box name for linking with *list-container* |

**Attributes of pagination.strany** (pages)

| Attribute | Values | Description |
|---|---|---|
| spaces | true/false | insert non-breaking spaces between pages |
| size | 1/2/3/4/5/... | number of displayed page links |
| label\_next | 'string' | text for the next page link |
| label\_previous | 'string' | text for the previous page link |
| hash | 'string' | appends a hash fragment after # in links |

```twig
{# _listing.tpl #}
<i:list-pagination>
    {{pagination.strany({spaces: true, label_next: 'next-page'|trans})}}
</i:list-pagination>
```

## List empty

Empty listing message definition -- always in the **\_listing.tpl** file. Defines a macro that is subsequently used for product listing in *list-container*.

Only the *url* variable is available.

```twig
<i:list-empty type="product" name="short">
    {% trans 'listing.no-products-found' %}
</i:list-empty>
```

```twig
<i:list-empty type="product">
    <div data-role="default">{% trans 'listing.no-products-found' %}</div>
    <div data-role="filter">
        {% trans 'listing.filter-no-results' %}
        <a href="{{url.reset}}">{% trans 'listing.reset-filter' %}</a>
        </div>
</i:list-empty>
```

**Attributes of list-empty**

| Attribute | Default | Description |
|---|---|---|
| **type** | --- | item type *(product, article, ...)* |
| name | *default* | name for linking with *list-container* |

**Available variables**

| Name | Value |
|---|---|
| url.reset | URL without filter and page |

## List insert

Template definition that is inserted before (or after) each rendered item -- always in the **\_listing.tpl** file. Defines a macro that is subsequently used for product listing in *list-container*.

```twig
<i:list-insert type="product" name="banner">
    {% if limit == 16 and pagePosition % 5 === 0 %}
        {% set article = repository.article.findOneBy({id:arguments.id}) %}
        {{ article.name }}
    {% endif %}
</i:list-insert>

<i:list-container insert-after="banner" insert-arguments="{{ {id:article.id} }}">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>
```

**Attributes of list-insert**

| Attribute | Description |
|---|---|
| **type** | item type *(product, article, ...)* |
| name | name for linking with *list-container* |

**Available variables**

| Name | Value |
|---|---|
| pagePosition | Position on the page (counted from 1) |
| page | Listing page number (counted from 1) |
| limit | Number of records per page (maximum) |
| recordsOnPage | Number of records on the current page (actual) |
| arguments | input data defined on the listing-container -- scalar only (passed through json\_encode) |

## List Item

Listing item definition -- always in the **\_listing.tpl** file. Defines a macro that is subsequently used for product listing in *list-container*.

Global variables are not accessible and the position within the listing cannot be determined.

```twig
{# _listing.tpl #}
<i:list-item>
    <h3>{{product.name}}</h3>
</i:list-item>
```

```twig
<i:list-item tag="li" name="news">
    <h3>{{product.name}}</h3>
</i:list-item>
```

**Attributes of list-item**

| Attribute | Default | Description |
|---|---|---|
| **type** | --- | item type *(product, article, ...)* |
| tag | *div* | which tag to wrap the resulting box in |
| name | *default* | box name for linking with *list-container* |
| class | --- | CSS class |

## Complete Listing Definition Example

A production `_listing.tpl` defines multiple list-items (default product card, compact card for sliders, search result card), empty states with context-specific messages, and several pagination variants. The examples below are simplified from the buran production template (feature toggles stripped, core patterns preserved).

**Default product card** -- the main listing item used for category pages. Includes product image, labels (discount/new/custom), name, price with optional discount, availability with estimated delivery date, and add-to-cart form:

::: v-pre

```twig
{# _listing.tpl -- default product card for category listing #}
<i:list-item type="product" class="swiper-slide cell cell--product">
    <div class="white-item">
        <div class="white-item__image">
            <a href="{{ product.url }}">
                <i:img src="product.image" format="359x479" fill />
            </a>

            {# Labels: discount percentage, new arrival, custom labels with dynamic color #}
            <div class="labels">
                {% if product.item.price.discountPercent %}
                    <strong class="label label__discount">-{{ product.item.price.discountPercent }}%</strong>
                {% endif %}
                {% if product.flagNew %}
                    <strong class="label label__new">{% trans 'template.label.new' %}</strong>
                {% endif %}
                {% for label in product.labels %}
                    <strong class="label" if:style="label.colorCode ? 'background: ' ~ label.colorCode">
                        {{ label.name }}
                    </strong>
                {% endfor %}
            </div>
        </div>

        <h2><a href="{{ product.url }}">{{ product.name }}</a></h2>

        {# Price with optional strikethrough for discounted items #}
        {% if product.item.price.discount %}
            <span class="u-decoration-through">{{ product.item.price.beforeDiscount.formatted }}</span>
        {% endif %}
        <strong class="{{ product.item.price.discount ? 'u-color-red' }}">
            {{ product.item.price.current.formatted }}
        </strong>

        {# Availability with estimated delivery date #}
        <strong class="availability availability--{{ product.item.availability.hours }}">
            {{ product.item.availability.text }}
        </strong>
        {% if product.item.availability.hours < 999 and product.item.availability.deliveryOption.dateDelivered %}
            <span>
                {% trans 'template.at-your-place' %}
                <strong>{{ product.item.availability.deliveryOption.dateDelivered|date('j. n.') }}</strong>
            </span>
        {% endif %}

        {# Add to cart #}
        <form action="/Koupit" method="post">
            <button type="submit" class="button--order">{% trans 'template.add-to-cart' %}</button>
            <input name="zbozi" value="{{ product.id }}" type="hidden" />
        </form>
    </div>
</i:list-item>
```

:::

**Compact card for sliders** (`name="simple"`) -- a simplified variant used in carousels (related products, homepage banners). Wrapped in a swiper-slide, image + name + price only:

::: v-pre

```twig
{# _listing.tpl -- compact card for product carousels #}
<i:list-item type="product" name="simple" class="swiper-slide cell simple-box">
    <span class="white-item">
        <a href="{{ product.url }}">
            <div class="white-item__image">
                <i:img src="product.image" format="300x376" fill />
                {# Labels (simplified) #}
                <div class="labels">
                    {% if product.item.price.discountPercent %}
                        <strong class="label label__discount">-{{ product.item.price.discountPercent }}%</strong>
                    {% endif %}
                    {% for label in product.labels %}
                        <strong class="label" if:style="label.colorCode ? 'background: ' ~ label.colorCode">{{ label.name }}</strong>
                    {% endfor %}
                </div>
            </div>
            <h3>{{ product.name }}</h3>
            <strong>{{ product.item.price.current.formatted }}</strong>
        </a>
    </span>
</i:list-item>
```

:::

**Empty listing states** -- separate messages for filter results vs. default, plus specialized variants for search and wishlist:

::: v-pre

```twig
{# _listing.tpl -- default empty states with filter/default variants #}
<i:list-empty type="product">
    <p data-role="filter" class="callout">{% trans 'listing.empty.filter' %}</p>
    <p data-role="default" class="callout">{% trans 'listing.empty.default' %}</p>
</i:list-empty>

{# Separate empty state for search results #}
<i:list-empty type="product" name="search">
    <div data-role="filter" class="callout">{% trans 'listing.empty.filter' %}</div>
    <div data-role="default" class="callout">{% trans 'listing.empty.search' %}</div>
</i:list-empty>

{# Empty state for wishlist #}
<i:list-empty type="product" name="wish">
    <div data-role="default" class="callout">{% trans 'listing.empty.wish' %}</div>
</i:list-empty>
```

:::

**Pagination variants** -- buran defines multiple named paginations that are placed independently inside `i:list-container` via `data-name`:

::: v-pre

```twig
{# Sort dropdown -- auto-generated by the system, just place the container #}
<div data-role="pagination" data-name="sort"></div>

{# Page number links #}
<i:list-pagination type="product" name="pages">
    {% if pagination.pageCount > 1 %}
        {{ pagination.html({'spaces': false, 'size': 2})|raw }}
    {% endif %}
</i:list-pagination>

{# Result count summary (e.g. "Showing 1 - 24 of 156 products") #}
<i:list-pagination type="product" name="numbers">
    {% if pagination.totalResults > 0 %}
        {% trans 'listing.show' %} <strong>{{ pagination.resultsFrom }} - {{ pagination.resultsTo }}</strong>
        {% trans 'listing.show-from' %} <strong>{{ pagination.totalResults }}</strong>
        {% trans 'listing.products' %}
    {% endif %}
</i:list-pagination>

{# Total result count (simple) #}
<i:list-pagination type="product" name="qty">
    {{ pagination.totalResults }} {% trans 'listing.results' %}
</i:list-pagination>

{# "Load more" button (appends next page via AJAX instead of navigating) #}
<i:list-pagination type="product" name="add">
    <a href="#" class="button" data-role="add-page">{% trans 'listing.show-more-products' %}</a>
</i:list-pagination>

{# Scroll-to-top anchor #}
<i:list-pagination type="product" name="scroll">
    <a href="#main" class="button js_scrollToAnchor">{% trans 'template.scroll-top' %}</a>
</i:list-pagination>
```

:::

## Common Source Patterns

The `source` attribute on `i:list-container` accepts a Twig object with query parameters. The `collection` attribute accepts a pre-loaded list of items (e.g. from [content grid](content-grid.md)). When neither is specified, the listing uses the default source for the current page (e.g. a category page lists its products automatically).

::: v-pre

```twig
{# Related/relevant products on product detail (uses "simple" card variant) #}
<i:list-container type="product" source="{relevant: product}" name="simple" hide-empty>
    <div data-role="list"></div>
</i:list-container>

{# Products from a specific category by ID #}
<i:list-container type="product" source="{kategorie: 123, limit: 8}" hide-empty>
    <div data-role="list"></div>
</i:list-container>

{# Products from a dynamic category variable #}
<i:list-container type="product" source="{kategorie: kategorie.id, limit: 10}">
    <div data-role="empty"></div>
    <div data-role="list"></div>
</i:list-container>

{# Products from the current category (automatic -- no source needed) #}
{# This is the typical pattern used in vypis.tpl (category listing page) #}
<i:list-container type="product">
    <div data-role="pagination" data-name="sort"></div>
    <div data-role="empty"></div>
    <div data-role="list"></div>
    <div data-role="pagination" data-name="pages"></div>
</i:list-container>

{# Products from a content grid product_list field (e.g. homepage banners) #}
<i:list-container type="product" collection="{{ item.right.products }}" name="simple" hide-empty
                  class="swiper-container" data-navigation="simple-slider-{{ loop.index }}">
    <div data-role="list" class="swiper-wrapper"></div>
</i:list-container>
```

:::

For how listings integrate with [filters](filter.md) (including `i:filter-placeholder` and `i:filter-placeholder-values` inside the container), see the [filter integration example](filter.md#integration-with-listing).

---

---
url: /objects.md
---
# Object Types

**in preparation** - not yet available in templates

## AccountingDocument

**Attributes of object AccountingDocument**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| name | string | Document name (e.g. Invoice 2330011) |
| date | datetime | Issue date |
| totalPrice | [Price](#price) | Total price |
| pdfUrl | [Url](#url) | PDF download URL |

Examples:

```twig
{{ accountingdocument.code }}
{{ accountingdocument.name }}
{{ accountingdocument.date|date('d. m. Y H:i') }}
{{ accountingdocument.totalPrice }} {# Price #}
{{ accountingdocument.pdfUrl }} {# Url #}
```

## Actuality

**Attributes of object Actuality**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| date | datetime | Date |
| url | [Url](#url) | Actuality URL or external URL (takes precedence) |
| annotation | string | null | Annotation |
| text | string | null | Text |
| image | [Image](#image) | null | Main image |

Examples:

```twig
{{ actuality.id }}
{{ actuality.name }}
{{ actuality.date|date('d. m. Y H:i') }}
{{ actuality.url }} {# Url #}
{% if actuality.annotation %} {{ actuality.annotation }} {% endif %}
{% if actuality.text %} {{ actuality.text }} {% endif %}
{% if actuality.image %} {{ actuality.image }} {# Image #} {% endif %}
```

## Address

**Attributes of object Address**

| Name | Type | Description |
|---|---|---|
| name | [Address/Name](#address-name) | Name |
| city | string | null | City |
| company | string | null | Company |
| companyId | string | null | Company ID |
| email | string | null | Email |
| phone | string | null | Phone |
| region | string | null | Region (state, district, ...) |
| street | string | null | Street and house number |
| vatId | string | null | VAT ID |
| web | string | null | Website URL |
| zip | string | null | ZIP code |
| purpose | [Address/AddressPurpose](#address-addresspurpose) | null | Contact purpose |
| country | [Address/Country](#address-country) | null | Country |

Examples:

```twig
{{ address.name }} {# Name #}
{% if address.city %} {{ address.city }} {% endif %}
{% if address.company %} {{ address.company }} {% endif %}
{% if address.companyId %} {{ address.companyId }} {% endif %}
{% if address.email %} {{ address.email }} {% endif %}
{% if address.phone %} {{ address.phone }} {% endif %}
{% if address.region %} {{ address.region }} {% endif %}
{% if address.street %} {{ address.street }} {% endif %}
{% if address.vatId %} {{ address.vatId }} {% endif %}
{% if address.web %} {{ address.web }} {% endif %}
{% if address.zip %} {{ address.zip }} {% endif %}
{% if address.purpose %} {{ address.purpose }} {# AddressPurpose #} {% endif %}
{% if address.country %} {{ address.country }} {# Country #} {% endif %}
```

## Address/AddressPurpose

**Attributes of object Address/AddressPurpose**

| Name | Type | Description |
|---|---|---|
| headline | string | Headline |

Examples:

```twig
{{ addresspurpose.headline }}
```

## Address/Country

**Attributes of object Address/Country**

| Name | Type | Description |
|---|---|---|
| code | string | Code (e.g. cz) |
| flagCircleUrl | string | Flag SVG URL (circular) |
| flagUrl | string | Flag SVG URL (rectangular 3:4) |
| name | string | Name |
| eU | bool | Is in EU? |

Examples:

```twig
{{ country.code }}
{{ country.flagCircleUrl }}
{{ country.flagUrl }}
{{ country.name }}
{% if country.eU %} ... {% endif %}
```

## Address/Name

**Attributes of object Address/Name**

| Name | Type | Description |
|---|---|---|
| first | string | null | First name |
| last | string | null | Last name |

Examples:

```twig
{{ name }}
{% if name.first %} {{ name.first }} {% endif %}
{% if name.last %} {{ name.last }} {% endif %}
```

## Addresses

**Attributes of object Addresses**

| Name | Type | Description |
|---|---|---|
| delivery | [Address](#address) | Delivery address |
| invoice | [Address](#address) | Billing address |

Examples:

```twig
{{ addresses.delivery }} {# Address #}
{{ addresses.invoice }} {# Address #}
```

## Admin

E-shop administrator

**Attributes of object Admin**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| email | string | Email |
| phone | string | Phone |
| position | string | Position |
| name | [Address/Name](#address-name) | First and last name |
| image | [Image](#image) | Image |
| text | html | null | Text |

Examples:

```twig
{{ admin.id }}
{{ admin.email }}
{{ admin.phone }}
{{ admin.position }}
{{ admin.name }} {# Name #}
{{ admin.image }} {# Image #}
{% if admin.text %} {{ admin.text }} {% endif %}
```

## AnalyticsReport

**Attributes of object AnalyticsReport**

| Name | Type | Description |
|---|---|---|
| name | string | Name |
| url | [Url](#url) | URL |

Examples:

```twig
{{ analyticsreport.name }}
{{ analyticsreport.url }} {# Url #}
```

## Article

**Attributes of object Article**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| commentType | string | Comment type for this entity |
| name | string | Name |
| datePublished | datetime | Publication date |
| attributes | [Attribute/AttributeInstance](#attribute-attributeinstance)\[] | Attributes and values |
| author | [Author](#author) | Author |
| files | [File](#file)\[] | Files (manuals, specifications, ...) |
| images | [Image](#image)\[] | Images |
| topic | [Topic](#topic) | Topic (classification) |
| topics | [Topic](#topic)\[] | Topics |
| url | [Url](#url) | Article URL |
| videos | [Video](#video)\[] | Videos |
| text | html | null | Text |
| attribute | [Attribute/AttributeInstance](#attribute-attributeinstance) | null | Attribute with values |
| image | [Image](#image) | null | Main image |
| seo | [Seo](#seo) | null | SEO attributes |
| contentGrid | array | null | Content grid |

Examples:

```twig
{{ article.id }}
{{ article.commentType }}
{{ article.name }}
{{ article.datePublished|date('d. m. Y H:i') }}
{% for attributeInstance in article.attributes %} ... {% endfor %}
{{ article.author }} {# Author #}
{% for file in article.files %} ... {% endfor %}
{% for image in article.images %} ... {% endfor %}
{{ article.topic }} {# Topic #}
{% for topic in article.topics %} ... {% endfor %}
{{ article.url }} {# Url #}
{% for video in article.videos %} ... {% endfor %}
{% if article.text %} {{ article.text }} {% endif %}
{% if article.attribute %} {{ article.attribute }} {# AttributeInstance #} {% endif %}
{% if article.image %} {{ article.image }} {# Image #} {% endif %}
{% if article.seo %} {{ article.seo }} {# Seo #} {% endif %}
{% if article.contentGrid %} {{ article.contentGrid }} {% endif %}
```

## Attribute/Attribute

**Attributes of object Attribute/Attribute**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Name |
| values | [Attribute/AttributeValue](#attribute-attributevalue)\[] | Values |
| text | string | null | Description |
| group | [Attribute/AttributeGroup](#attribute-attributegroup) | null | Attribute group |
| meaning | [AttributeMeaning](#attributemeaning) | null | Meaning |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ attribute.id }}
{{ attribute.name }}
{% for attributeValue in attribute.values %} ... {% endfor %}
{% if attribute.text %} {{ attribute.text }} {% endif %}
{% if attribute.group %} {{ attribute.group }} {# AttributeGroup #} {% endif %}
{% if attribute.meaning %} {{ attribute.meaning }} {# AttributeMeaning #} {% endif %}
{% if attribute.image %} {{ attribute.image }} {# Image #} {% endif %}
```

## Attribute/AttributeGroup

**Attributes of object Attribute/AttributeGroup**

| Name | Type | Description |
|---|---|---|
| id | int | ID |

Examples:

```twig
{{ attributegroup.id }}
```

## Attribute/AttributeInstance

**Attributes of object Attribute/AttributeInstance**

| Name | Type | Description |
|---|---|---|
| name | string | Name |
| valuesHtml | html | Value names including optional link and title, separated by comma |
| values | [Attribute/AttributeValueInstance](#attribute-attributevalueinstance)\[] | Values |
| description | string | null | Description |
| group | [Attribute/AttributeGroup](#attribute-attributegroup) | null | Attribute group |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ attributeinstance.name }}
{{ attributeinstance.valuesHtml }}
{% for attributeValueInstance in attributeinstance.values %} ... {% endfor %}
{% if attributeinstance.description %} {{ attributeinstance.description }} {% endif %}
{% if attributeinstance.group %} {{ attributeinstance.group }} {# AttributeGroup #} {% endif %}
{% if attributeinstance.image %} {{ attributeinstance.image }} {# Image #} {% endif %}
```

## Attribute/AttributeValue

Attribute value

**Attributes of object Attribute/AttributeValue**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| attribute | [Attribute/Attribute](#attribute-attribute) | Attribute |
| colorCode | string | null | Hex color code |
| text | html | null | Text |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ attributevalue.id }}
{{ attributevalue.name }}
{{ attributevalue.attribute }} {# Attribute #}
{% if attributevalue.colorCode %} {{ attributevalue.colorCode }} {% endif %}
{% if attributevalue.text %} {{ attributevalue.text }} {% endif %}
{% if attributevalue.image %} {{ attributevalue.image }} {# Image #} {% endif %}
```

## Attribute/AttributeValueInstance

**Attributes of object Attribute/AttributeValueInstance**

| Name | Type | Description |
|---|---|---|
| nameHtml | html | Name including title and optional link |
| colorCode | string | null | Hex color code |
| text | string | null | Description |
| unit | string | null | Unit |
| image | [Image](#image) | null | Image |
| name | string | int | float | null | Name |

Examples:

```twig
{{ attributevalueinstance }}
{{ attributevalueinstance.nameHtml }}
{% if attributevalueinstance.colorCode %} {{ attributevalueinstance.colorCode }} {% endif %}
{% if attributevalueinstance.text %} {{ attributevalueinstance.text }} {% endif %}
{% if attributevalueinstance.unit %} {{ attributevalueinstance.unit }} {% endif %}
{% if attributevalueinstance.image %} {{ attributevalueinstance.image }} {# Image #} {% endif %}
{% if attributevalueinstance.name %} {{ attributevalueinstance.name }} {% endif %}
```

## AttributeMeaning

**Attributes of object AttributeMeaning**

| Name | Type | Description |
|---|---|---|
| code | string | Code |

Examples:

```twig
{{ attributemeaning.code }}
```

## Author

Article author

**Attributes of object Author**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | [Address/Name](#address-name) | First and last name |
| image | [Image](#image) | Image |
| socialProfiles | [SocialProfile](#socialprofile)\[] | Social networks |
| url | [Url](#url) | URL |
| email | string | null | Email |
| nickname | string | null | Nickname |
| phone | string | null | Phone |
| text | html | null | Text |

Examples:

```twig
{{ author.id }}
{{ author.name }} {# Name #}
{{ author.image }} {# Image #}
{% for socialProfile in author.socialProfiles %} ... {% endfor %}
{{ author.url }} {# Url #}
{% if author.email %} {{ author.email }} {% endif %}
{% if author.nickname %} {{ author.nickname }} {% endif %}
{% if author.phone %} {{ author.phone }} {% endif %}
{% if author.text %} {{ author.text }} {% endif %}
```

## Availability

**Attributes of object Availability**

| Name | Type | Description |
|---|---|---|
| availableAmount | int | Available pieces |
| availableAmountExpectedToStorageRoom | int | Available pieces by source warehouse to be transferred to the selected warehouse (total) |
| availableAmountInShowroom | int | Available showroom pieces |
| availableAmountInStockroom | int | Available pieces in a specific stock room |
| availableAmountInStorageCenter | int | Available pieces in a specific storage center |
| availableAmountOnWayToStorageRoom | int | Available pieces by source warehouse currently in transit to the selected warehouse (total) |
| availableDemandsAmountFromSupplierToStorageRoom | int | Available pieces from supplier demand that will be available at the selected warehouse (total) |
| hours | int | Availability in hours |
| totalAmount | int | Total pieces (without deducting reservations) |
| inShowroom | bool | Is in showroom? |
| inStock | bool | Is in stock? |
| preorder | bool | Is preorder? |
| watchdogSupported | bool | Is watchdog supported? |
| deliveryOptions | [DeliveryOption](#deliveryoption)\[] | Available delivery options with dates |
| availableAmountsExpectedToStorageRoom | [ExpectedAmount](#expectedamount)\[] | Available pieces by source warehouse to be transferred to the selected warehouse (list) |
| availableAmountsOnWayToStorageRoom | [ExpectedAmount](#expectedamount)\[] | Available pieces by source warehouse currently in transit to the selected warehouse (list) |
| availableDemandsFromSupplierToStorageRoom | [ExpectedSupplierAmount](#expectedsupplieramount)\[] | Available pieces from supplier demand that will be available at the selected warehouse (list) |
| text | string | null | Availability description |
| dateExpected | datetime | null | Expected restocking date |
| deliveryOption | [DeliveryOption](#deliveryoption) | null | Fastest delivery option |

Examples:

```twig
{{ availability.availableAmount }}
{{ availability.availableAmountExpectedToStorageRoom }}
{{ availability.availableAmountInShowroom }}
{{ availability.availableAmountInStockroom }}
{{ availability.availableAmountInStorageCenter }}
{{ availability.availableAmountOnWayToStorageRoom }}
{{ availability.availableDemandsAmountFromSupplierToStorageRoom }}
{{ availability.hours }}
{{ availability.totalAmount }}
{% if availability.inShowroom %} ... {% endif %}
{% if availability.inStock %} ... {% endif %}
{% if availability.preorder %} ... {% endif %}
{% if availability.watchdogSupported %} ... {% endif %}
{% for deliveryOption in availability.deliveryOptions %} ... {% endfor %}
{% for expectedAmount in availability.availableAmountsExpectedToStorageRoom %} ... {% endfor %}
{% for expectedAmount in availability.availableAmountsOnWayToStorageRoom %} ... {% endfor %}
{% for expectedSupplierAmount in availability.availableDemandsFromSupplierToStorageRoom %} ... {% endfor %}
{% if availability.text %} {{ availability.text }} {% endif %}
{{ availability.dateExpected|date('d. m. Y H:i') }}
{% if availability.deliveryOption %} {{ availability.deliveryOption }} {# DeliveryOption #} {% endif %}
```

## AvailableUpsellGroup

**Attributes of object AvailableUpsellGroup**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Group name |
| singleSelection | bool | Selection mode |
| upsells | [Upsell](#upsell)\[] | Available upsells |
| code | string | null | Group name |

Examples:

```twig
{{ availableupsellgroup.id }}
{{ availableupsellgroup.name }}
{% if availableupsellgroup.singleSelection %} ... {% endif %}
{% for upsell in availableupsellgroup.upsells %} ... {% endfor %}
{% if availableupsellgroup.code %} {{ availableupsellgroup.code }} {% endif %}
```

## Banner

Banner

**Attributes of object Banner**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| validFrom | datetime | Valid from |
| validTo | datetime | Valid to |
| vector | bool | Vector image |
| section | [BannerSection](#bannersection) | Banner section |
| height | int | null | Height (px) |
| width | int | null | Width (px) |
| alt | string | null | Description |
| backgroundColorCode | string | null | Background color hex code |
| ctaClass | string | null | CTA class (button) |
| ctaText | string | null | CTA text (button) |
| name | string | null | Name |
| url | string | null | Url |
| urlTarget | string | null | Link open target |
| text | html | null | Text |
| image | [Image](#image) | null | Image |
| product | [Product](#product) | null | Product |

Examples:

```twig
{{ banner.id }}
{{ banner.validFrom|date('d. m. Y H:i') }}
{{ banner.validTo|date('d. m. Y H:i') }}
{% if banner.vector %} ... {% endif %}
{{ banner.section }} {# BannerSection #}
{% if banner.height %} {{ banner.height }} {% endif %}
{% if banner.width %} {{ banner.width }} {% endif %}
{% if banner.alt %} {{ banner.alt }} {% endif %}
{% if banner.backgroundColorCode %} {{ banner.backgroundColorCode }} {% endif %}
{% if banner.ctaClass %} {{ banner.ctaClass }} {% endif %}
{% if banner.ctaText %} {{ banner.ctaText }} {% endif %}
{% if banner.name %} {{ banner.name }} {% endif %}
{% if banner.url %} {{ banner.url }} {% endif %}
{% if banner.urlTarget %} {{ banner.urlTarget }} {% endif %}
{% if banner.text %} {{ banner.text }} {% endif %}
{% if banner.image %} {{ banner.image }} {# Image #} {% endif %}
{% if banner.product %} {{ banner.product }} {# Product #} {% endif %}
```

## BannerSection

Banner section

**Attributes of object BannerSection**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| height | int | null | Height (px) |
| width | int | null | Width (px) |
| code | string | null | Section code |
| name | string | null | Name |

Examples:

```twig
{{ bannersection.id }}
{% if bannersection.height %} {{ bannersection.height }} {% endif %}
{% if bannersection.width %} {{ bannersection.width }} {% endif %}
{% if bannersection.code %} {{ bannersection.code }} {% endif %}
{% if bannersection.name %} {{ bannersection.name }} {% endif %}
```

## Brand

**Attributes of object Brand**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| headline | string | Headline |
| name | string | Name |
| flagImportant | bool | Important |
| publicContacts | [Address](#address)\[] | Public contacts |
| categories | [Category](#category)\[] | Brand categories (pretty URL or classic filter) |
| url | [Url](#url) | Brand URL |
| categoryUrl | [Url](#url) | Brand category URL |
| code | string | null | Code |
| web | string | null | Brand website |
| text | html | null | Text |
| image | [Image](#image) | null | Image |
| seo | [Seo](#seo) | null | SEO attributes |
| contentGrid | array | null | Content grid |

Examples:

```twig
{{ brand.id }}
{{ brand.headline }}
{{ brand.name }}
{% if brand.flagImportant %} ... {% endif %}
{% for address in brand.publicContacts %} ... {% endfor %}
{% for category in brand.categories %} ... {% endfor %}
{{ brand.url }} {# Url #}
{{ brand.categoryUrl }} {# Url #}
{% if brand.code %} {{ brand.code }} {% endif %}
{% if brand.web %} {{ brand.web }} {% endif %}
{% if brand.text %} {{ brand.text }} {% endif %}
{% if brand.image %} {{ brand.image }} {# Image #} {% endif %}
{% if brand.seo %} {{ brand.seo }} {# Seo #} {% endif %}
{% if brand.contentGrid %} {{ brand.contentGrid }} {% endif %}
```

## BrandCategory

**Attributes of object BrandCategory**

| Name | Type | Description |
|---|---|---|
| brand | [Brand](#brand) | Brand |
| category | [Category](#category) | Category |
| url | [Url](#url) | URL |
| parent | [BrandCategory](#brandcategory) | null | Parent category |

Examples:

```twig
{{ brandcategory.brand }} {# Brand #}
{{ brandcategory.category }} {# Category #}
{{ brandcategory.url }} {# Url #}
{% if brandcategory.parent %} {{ brandcategory.parent }} {# BrandCategory #} {% endif %}
```

## Breadcrumb

**Attributes of object Breadcrumb**

| Name | Type | Description |
|---|---|---|
| label | string | Label |
| url | [Url](#url) | null | URL (the last breadcrumb has no URL) |

Examples:

```twig
{{ breadcrumb.label }}
{% if breadcrumb.url %} {{ breadcrumb.url }} {# Url #} {% endif %}
```

## Bundle

**Attributes of object Bundle**

| Name | Type | Description |
|---|---|---|
| multiPack | bool | Is a multi-pack? (multiple pieces of another item) |
| price | [Price](#price) | null | Bundle price (price before discount is sum of part prices) |

Examples:

```twig
{% if bundle.multiPack %} ... {% endif %}
{% if bundle.price %} {{ bundle.price }} {# Price #} {% endif %}
```

## Category

**Attributes of object Category**

| Name | Type | Description |
|---|---|---|
| id | int | Internal category ID |
| productCount | int | Number of products in category (approximate) |
| productInStockCount | int | Number of products in stock in category (approximate) |
| totalStockQuantity | int | Total stock quantity in category (approximate) |
| commentType | string | Comment type for this entity |
| headline | string | Headline |
| menuName | string | Category name in menu |
| name | string | Category name |
| flagErotic | bool | Erotic |
| flagImportant | bool | Important |
| noFollow | bool | Should search engines not follow the link? In templates typically: \<a href={{ category.url }} if:rel="category.noFollow ? 'nofollow'"> |
| subcategories | [Category](#category)\[] | Subcategories |
| url | [Url](#url) | URL |
| variantType | [VariantType](#varianttype) | Variant type |
| videos | [Video](#video)\[] | Videos |
| pathNames | array | Path to category (names) |
| pathIds | array | Path to category (IDs) |
| templateAttribute | mixed | Category layout settings |
| subHeadline | string | null | Subheadline |
| text | html | null | Text content |
| parent | [Category](#category) | null | Parent category |
| image | [Image](#image) | null | Image |
| contentGrid | array | null | Content grid |

Examples:

**Category breadcrumb and heading**

```twig
<h1>{{ kategorie.name }}</h1>
{% if kategorie.description %}
<div>{{ kategorie.description }}</div>
{% endif %}
```

**Category subcategories**

```twig
{% for child in kategorie.children %}
<a href="{{ child.url }}">
{% if child.image %}<i:img src="child.image" format="200x200" fill />{% endif %}
{{ child.name }}
</a>
{% endfor %}
```

## Comment

**Attributes of object Comment**

| Name | Type | Description |
|---|---|---|
| depth | int | Nesting depth |
| id | int | Id |
| date | datetime | Date |
| important | bool | Important? |
| replies | [Comment](#comment)\[] | Replies to the post |
| rating | int | null | Rating (1 to 5) |
| authorName | string | null | Author name |
| email | string | null | Author email |
| phone | string | null | Author phone |
| title | string | null | Title |
| text | html | null | Post text |
| admin | [Admin](#admin) | null | E-shop administrator |

Examples:

```twig
{{ comment.depth }}
{{ comment.id }}
{{ comment.date|date('d. m. Y H:i') }}
{% if comment.important %} ... {% endif %}
{% for comment in comment.replies %} ... {% endfor %}
{% if comment.rating %} {{ comment.rating }} {% endif %}
{% if comment.authorName %} {{ comment.authorName }} {% endif %}
{% if comment.email %} {{ comment.email }} {% endif %}
{% if comment.phone %} {{ comment.phone }} {% endif %}
{% if comment.title %} {{ comment.title }} {% endif %}
{% if comment.text %} {{ comment.text }} {% endif %}
{% if comment.admin %} {{ comment.admin }} {# Admin #} {% endif %}
```

## Compatibility/CompatibilityAttribute

**Attributes of object Compatibility/CompatibilityAttribute**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Name |
| values | [Compatibility/CompatibilityAttributeValue](#compatibility-compatibilityattributevalue)\[] | Values |

Examples:

```twig
{{ compatibilityattribute.id }}
{{ compatibilityattribute.name }}
{% for compatibilityAttributeValue in compatibilityattribute.values %} ... {% endfor %}
```

## Compatibility/CompatibilityAttributeValue

Compatibility attribute value

**Attributes of object Compatibility/CompatibilityAttributeValue**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| attribute | [Compatibility/CompatibilityAttribute](#compatibility-compatibilityattribute) | Attribute |

Examples:

```twig
{{ compatibilityattributevalue.id }}
{{ compatibilityattributevalue.name }}
{{ compatibilityattributevalue.attribute }} {# CompatibilityAttribute #}
```

## Customer

Registered customer

**Attributes of object Customer**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| userPointsAvailable | int | Current loyalty program points balance |
| userPointsExpiringOn | int | Number of points expiring on a given date |
| userPointsTotal | int | Total earned loyalty program points |
| name | string | Customer name |
| dateCreated | datetime | Registration date |
| productOnWishlist | bool | Is product on wishlist? |
| vatCharged | bool | Charge VAT |
| wholesale | bool | Wholesaler |
| receipts | [AccountingDocument](#accountingdocument)\[] | Receipts |
| address | [Addresses](#addresses) | Addresses |
| analyticReports | [AnalyticsReport](#analyticsreport)\[] | Analytics reports |
| orders | [Order](#order)\[] | Customer orders |
| childOrders | [Order](#order)\[] | Subordinate customer orders |
| userPointChanges | [UserPointChange](#userpointchange)\[] | Loyalty program points history |
| alternativeAddresses | array | Customer alternative addresses |
| loyaltyCard | string | null | Loyalty card code |
| socialLoginId | string | null | User ID in the service used for login |

Examples:

**Logged-in customer greeting**

```twig
{% if customer.logged %}
Welcome, {{ customer.name }}
<a href="{{ customer.logoutUrl }}">Logout</a>
{% else %}
<a href="{{ customer.loginUrl }}">Login</a>
{% endif %}
```

## DayBlock

**Attributes of object DayBlock**

| Name | Type | Description |
|---|---|---|
| dayName | string | Day of week name |
| dayNameShort | string | Abbreviated day of week name |
| date | datetime | Date |
| timeBlocks | [TimeBlock](#timeblock)\[] | null | Opening times |

Examples:

```twig
{{ dayblock.dayName }}
{{ dayblock.dayNameShort }}
{{ dayblock.date|date('d. m. Y H:i') }}
{% for timeBlock in dayblock.timeBlocks %} ... {% endfor %}
```

## Delivery

**Attributes of object Delivery**

| Name | Type | Description |
|---|---|---|
| name | string | Name |
| vatRate | float | VAT rate |
| deliveryAddressRequired | bool | Is delivery address required in cart? |
| payment | [Delivery/Payment](#delivery-payment) | Payment method |
| transport | [Delivery/Transport](#delivery-transport) | Delivery method |
| price | [Price](#price) | Price |
| id | int | null | ID |
| freeLimit | [Order/FreeLimit](#order-freelimit) | null | Free delivery threshold |

Examples:

```twig
{{ delivery.name }}
{{ delivery.vatRate }}
{% if delivery.deliveryAddressRequired %} ... {% endif %}
{{ delivery.payment }} {# Payment #}
{{ delivery.transport }} {# Transport #}
{{ delivery.price }} {# Price #}
{% if delivery.id %} {{ delivery.id }} {% endif %}
{% if delivery.freeLimit %} {{ delivery.freeLimit }} {# FreeLimit #} {% endif %}
```

## Delivery/BankAccount

**Attributes of object Delivery/BankAccount**

| Name | Type | Description | Example output |
|---|---|---|---|
| currency | string | Currency |  |
| bic | string | null | BIC |  |
| iban | string | null | IBAN |  |
| local | string | null | Local format | 123456789/2010 |

Examples:

```twig
{{ bankaccount }}
{{ bankaccount.currency }}
{% if bankaccount.bic %} {{ bankaccount.bic }} {% endif %}
{% if bankaccount.iban %} {{ bankaccount.iban }} {% endif %}
{% if bankaccount.local %} {{ bankaccount.local }} {% endif %}
```

## Delivery/Branch

**Attributes of object Delivery/Branch**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| name | string | Name |
| address | [Delivery/Branch/Address](#delivery-branch-address) | Address |

Examples:

```twig
{{ branch.code }}
{{ branch.name }}
{{ branch.address }} {# Address #}
```

## Delivery/Branch/Address

**Attributes of object Delivery/Branch/Address**

| Name | Type | Description |
|---|---|---|
| city | string | null | City |
| company | string | null | Company name |
| street | string | null | Street and house number |
| country | [Address/Country](#address-country) | null | Country |

Examples:

```twig
{{ address }}
{% if address.city %} {{ address.city }} {% endif %}
{% if address.company %} {{ address.company }} {% endif %}
{% if address.street %} {{ address.street }} {% endif %}
{% if address.country %} {{ address.country }} {# Country #} {% endif %}
```

## Delivery/Carrier

**Attributes of object Delivery/Carrier**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| name | string | Name |

Examples:

```twig
{{ carrier.code }}
{{ carrier.name }}
```

## Delivery/DeliveryDate

**Attributes of object Delivery/DeliveryDate**

| Name | Type | Description |
|---|---|---|
| dateDelivered | datetime | Delivery date to customer |
| dateSent | datetime | Shipment dispatch date |
| orderDeadline | datetime | Date and time by which the order must be placed to meet deadlines |
| timeDelivered | string | null | Delivery time to customer (e.g. "08:00-12:00") |

Examples:

```twig
{{ deliverydate.dateDelivered|date('d. m. Y H:i') }}
{{ deliverydate.dateSent|date('d. m. Y H:i') }}
{{ deliverydate.orderDeadline|date('d. m. Y H:i') }}
{% if deliverydate.timeDelivered %} {{ deliverydate.timeDelivered }} {% endif %}
```

## Delivery/PackageType

**Attributes of object Delivery/PackageType**

| Name | Type | Description |
|---|---|---|
| code | string | Code |

Examples:

```twig
{{ packagetype.code }}
```

## Delivery/Payment

**Attributes of object Delivery/Payment**

| Name | Type | Description | Example output |
|---|---|---|---|
| inputId | string | ID for binding input with label |  |
| name | string | Name | Bank transfer |
| url | string | Payment URL |  |
| vatRate | float | VAT rate | 21 |
| free | bool | Is free? |  |
| inAdvance | bool | Is advance payment required? |  |
| selected | bool | Is selected? |  |
| price | [Price](#price) | Price |  |
| code | null | string | Code | P123 |
| subcode | null | string | Sub-code | P123 |
| vs | string | null | Variable symbol | 2160001 |
| qRCodeHTML | html | null | HTML image code with QR code for bank transfer payment |  |
| text | html | null | Text |  |
| bankAccount | [Delivery/BankAccount](#delivery-bankaccount) | null | Bank account | 111111111/2010 |
| image | [Image](#image) | null | Image |  |

Examples:

```twig
{{ payment.inputId }}
{{ payment.name }}
{{ payment.url }}
{{ payment.vatRate }}
{% if payment.free %} ... {% endif %}
{% if payment.inAdvance %} ... {% endif %}
{% if payment.selected %} ... {% endif %}
{{ payment.price }} {# Price #}
{% if payment.code %} {{ payment.code }} {% endif %}
{% if payment.subcode %} {{ payment.subcode }} {% endif %}
{% if payment.vs %} {{ payment.vs }} {% endif %}
{% if payment.qRCodeHTML %} {{ payment.qRCodeHTML }} {% endif %}
{% if payment.text %} {{ payment.text }} {% endif %}
{% if payment.bankAccount %} {{ payment.bankAccount }} {# BankAccount #} {% endif %}
{% if payment.image %} {{ payment.image }} {# Image #} {% endif %}
```

## Delivery/StoreBranch

**Attributes of object Delivery/StoreBranch**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| name | string | Name |
| address | [Delivery/Branch/Address](#delivery-branch-address) | Address |

Examples:

```twig
{{ storebranch.code }}
{{ storebranch.name }}
{{ storebranch.address }} {# Address #}
```

## Delivery/Transport

**Attributes of object Delivery/Transport**

| Name | Type | Description |
|---|---|---|
| inputId | string | ID for binding input with label |
| name | string | Name |
| vatRate | float | VAT rate |
| branchRequired | bool | Is branch required? |
| currier | bool | Is personal courier? |
| dateGuaranteed | bool | Is delivery date guaranteed? |
| deliveryToAddress | bool | Is delivery to (home) address? |
| digital | bool | Is digital? |
| free | bool | Is free? |
| pickup | bool | Is pickup? |
| selected | bool | Is selected? |
| price | [Price](#price) | Price |
| text | html | null | Text |
| branch | [Delivery/Branch](#delivery-branch) | null | Branch |
| carrier | [Delivery/Carrier](#delivery-carrier) | null | Carrier |
| deliveryDate | [Delivery/DeliveryDate](#delivery-deliverydate) | null | Expected delivery date |
| packageType | [Delivery/PackageType](#delivery-packagetype) | null | Package type |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ transport.inputId }}
{{ transport.name }}
{{ transport.vatRate }}
{% if transport.branchRequired %} ... {% endif %}
{% if transport.currier %} ... {% endif %}
{% if transport.dateGuaranteed %} ... {% endif %}
{% if transport.deliveryToAddress %} ... {% endif %}
{% if transport.digital %} ... {% endif %}
{% if transport.free %} ... {% endif %}
{% if transport.pickup %} ... {% endif %}
{% if transport.selected %} ... {% endif %}
{{ transport.price }} {# Price #}
{% if transport.text %} {{ transport.text }} {% endif %}
{% if transport.branch %} {{ transport.branch }} {# Branch #} {% endif %}
{% if transport.carrier %} {{ transport.carrier }} {# Carrier #} {% endif %}
{% if transport.deliveryDate %} {{ transport.deliveryDate }} {# DeliveryDate #} {% endif %}
{% if transport.packageType %} {{ transport.packageType }} {# PackageType #} {% endif %}
{% if transport.image %} {{ transport.image }} {# Image #} {% endif %}
```

## DeliveryOption

**Attributes of object DeliveryOption**

| Name | Type | Description |
|---|---|---|
| dateDelivered | datetime | Delivery date to customer |
| dateSent | datetime | Shipment dispatch date |
| orderDeadline | datetime | Date and time by which the order must be placed to meet deadlines |
| transport | [Delivery/Transport](#delivery-transport) | Transport |
| timeDelivered | string | null | Delivery time to customer (e.g. "08:00-12:00") |

Examples:

```twig
{{ deliveryoption.dateDelivered|date('d. m. Y H:i') }}
{{ deliveryoption.dateSent|date('d. m. Y H:i') }}
{{ deliveryoption.orderDeadline|date('d. m. Y H:i') }}
{{ deliveryoption.transport }} {# Transport #}
{% if deliveryoption.timeDelivered %} {{ deliveryoption.timeDelivered }} {% endif %}
```

## Dimensions

**Attributes of object Dimensions**

| Name | Type | Description |
|---|---|---|
| unit | string | Unit |
| height | float | Height |
| length | float | Depth |
| width | float | Width |

Examples:

```twig
{{ dimensions }}
{{ dimensions.unit }}
{{ dimensions.height }}
{{ dimensions.length }}
{{ dimensions.width }}
```

## DynamicCategory

**Attributes of object DynamicCategory**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| dynamic | bool | Dynamic category? (always true) |
| url | [Url](#url) | Brand URL |
| text | html | null | Text |
| image | [Image](#image) | null | Image |
| seo | [Seo](#seo) | null | SEO attributes |

Examples:

```twig
{{ dynamiccategory.id }}
{{ dynamiccategory.name }}
{% if dynamiccategory.dynamic %} ... {% endif %}
{{ dynamiccategory.url }} {# Url #}
{% if dynamiccategory.text %} {{ dynamiccategory.text }} {% endif %}
{% if dynamiccategory.image %} {{ dynamiccategory.image }} {# Image #} {% endif %}
{% if dynamiccategory.seo %} {{ dynamiccategory.seo }} {# Seo #} {% endif %}
```

## EmptyOrder

**Attributes of object EmptyOrder**

| Name | Type | Description |
|---|---|---|
| catalogItemTotalAmount | int | Total item quantity in order |
| price | [Order/Price](#order-price) | Total prices |
| closestFreeDelivery | [Delivery](#delivery) | null | Closest available free delivery |

Examples:

```twig
{{ emptyorder.catalogItemTotalAmount }}
{{ emptyorder.price }} {# Price #}
{% if emptyorder.closestFreeDelivery %} {{ emptyorder.closestFreeDelivery }} {# Delivery #} {% endif %}
```

## EnumValue

Enum value

**Attributes of object EnumValue**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| enum | [ProductEnum](#productenum) | Enum |
| text | html | null | Text |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ enumvalue.id }}
{{ enumvalue.name }}
{{ enumvalue.enum }} {# ProductEnum #}
{% if enumvalue.text %} {{ enumvalue.text }} {% endif %}
{% if enumvalue.image %} {{ enumvalue.image }} {# Image #} {% endif %}
```

## Event/CartItemChange

**Attributes of object Event/CartItemChange**

| Name | Type | Description |
|---|---|---|
| amountChange | int | Number of added/removed pieces |
| rowId | int | Order row ID for tracking deduplication |
| catalogItem | [Item](#item) | Item (variant or product) |
| price | [Price](#price) | Unit price |

Examples:

```twig
{{ cartitemchange.amountChange }}
{{ cartitemchange.rowId }}
{{ cartitemchange.catalogItem }} {# Item #}
{{ cartitemchange.price }} {# Price #}
```

## ExpectedAmount

**Attributes of object ExpectedAmount**

| Name | Type | Description |
|---|---|---|
| amount | int | Number of available pieces |
| sourceStorageRoom | [StorageRoom](#storageroom) | Source warehouse from which items are replenished |

Examples:

```twig
{{ expectedamount.amount }}
{{ expectedamount.sourceStorageRoom }} {# StorageRoom #}
```

## ExpectedSupplierAmount

**Attributes of object ExpectedSupplierAmount**

| Name | Type | Description |
|---|---|---|
| amount | int | Number of available pieces |
| sourceStorageCenter | [StorageCenter](#storagecenter) | Destination center where the order will arrive (and items will be transferred) |
| expectedDate | datetime | null | When delivery is expected |
| orderDate | datetime | null | When the order was sent (if it was) |

Examples:

```twig
{{ expectedsupplieramount.amount }}
{{ expectedsupplieramount.sourceStorageCenter }} {# StorageCenter #}
{{ expectedsupplieramount.expectedDate|date('d. m. Y H:i') }}
{{ expectedsupplieramount.orderDate|date('d. m. Y H:i') }}
```

## File

File

**Attributes of object File**

| Name | Type | Description |
|---|---|---|
| bytes | int | Size in bytes |
| url | string | Url |
| usage | [FileUsage](#fileusage) | Usage type |
| mime | string | null | Mime type |
| name | string | null | Name |

Examples:

```twig
{{ file.bytes }}
{{ file.url }}
{{ file.usage }} {# FileUsage #}
{% if file.mime %} {{ file.mime }} {% endif %}
{% if file.name %} {{ file.name }} {% endif %}
```

## FileUsage

**Attributes of object FileUsage**

| Name | Type | Description |
|---|---|---|
| archive | bool | Archive |
| graphic | bool | Graphic |
| manual | bool | Manual |
| other | bool | Other |
| sound | bool | Sound |
| specification | bool | Specification |

Examples:

```twig
{% if fileusage.archive %} ... {% endif %}
{% if fileusage.graphic %} ... {% endif %}
{% if fileusage.manual %} ... {% endif %}
{% if fileusage.other %} ... {% endif %}
{% if fileusage.sound %} ... {% endif %}
{% if fileusage.specification %} ... {% endif %}
```

## Gift

**Attributes of object Gift**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| item | [Item](#item) | Item |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ gift.id }}
{{ gift.name }}
{{ gift.item }} {# Item #}
{% if gift.image %} {{ gift.image }} {# Image #} {% endif %}
```

## Image

Images should not be output via \<img src=, but always via the helper tag \<i:img, which handles retina displays and responsiveness.

If the image does not exist, a fallback image is shown based on admin settings - existence can be checked with the "exists" attribute to optionally hide it on the site.
If the object has multiple images (e.g. a gallery), they will always all exist and no check is needed.

**Attributes of object Image**

| Name | Type | Description |
|---|---|---|
| originalHeight | int | Height (px) of original photo |
| originalWidth | int | Width (px) of original photo |
| url | string | Image URL by parameters (for background-image only!) |
| alt | string | null | Image description or related item name |
| text | string | null | Image description |

Examples:

**Image with i:img component**

```twig
<i:img src="product.image" format="400x400" fill />
{{ product.image.alt }}
```

## Invoice

**Attributes of object Invoice**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| code | string | Code |

Examples:

```twig
{{ invoice.id }}
{{ invoice.code }}
```

## Item

**Attributes of object Item**

| Name | Type | Description |
|---|---|---|
| cartAmountRequiredMultiplier | int | Cart quantity must be a multiple of this value |
| id | int | Id |
| loyaltyPointsAmount | int | Number of loyalty points earned for purchasing the item |
| name | string | Name |
| trackingId | string | ID used in feeds and tracking scripts |
| digital | bool | Digital item? |
| sellable | bool | Is sellable? (show add to cart?) |
| service | bool | Is the item a service? (non-stock item) |
| availability | [Availability](#availability) | Availability |
| availableUpsellGroups | [AvailableUpsellGroup](#availableupsellgroup)\[] | Available upsell groups |
| product | [Product](#product) | Product |
| availableUpsells | [Upsell](#upsell)\[] | Available upsell items |
| trackingIds | array | ID used in feeds and tracking scripts (product and variant) |
| storageLocations | array | Storage locations |
| packageWeight | int | null | Package weight (g) |
| code | string | null | Code |
| packageHeight | float | null | Package height (cm) |
| packageLength | float | null | Package length (cm) |
| packageWidth | float | null | Package width (cm) |
| bundle | [Bundle](#bundle) | null | Bundle |
| cheapestDelivery | [Delivery/Transport](#delivery-transport) | null | Cheapest transport (does not consider cart or personal pickup) |
| freeDelivery | [Delivery](#delivery) | null | Is delivery free? (and which one) |
| closestFreeDelivery | [Delivery](#delivery) | null | Closest available free delivery |
| packageDimensions | [Dimensions](#dimensions) | null | Package dimensions |
| image | [Image](#image) | null | Image |
| price | [Price](#price) | null | Item price |
| url | [Url](#url) | null | Product/variant URL |
| variant | [Variant](#variant) | null | Variant |

Examples:

**Product item (purchasable unit) with price and availability**

```twig
{{ product.item.price.current.formatted }}
{% if product.item.price.discount %}
<del>{{ product.item.price.beforeDiscount.formatted }}</del>
-{{ product.item.price.discountPercent }}%
{% endif %}
{% if product.item.available %}
<a href="{{ product.item.cartUrl }}">Add to cart</a>
{% endif %}
```

## Label

**Attributes of object Label**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| code | string | null | Code for identification in template |
| colorCode | string | null | Hex color code |
| image | [Image](#image) | null | Image |

Examples:

```twig
{{ label.id }}
{{ label.name }}
{% if label.code %} {{ label.code }} {% endif %}
{% if label.colorCode %} {{ label.colorCode }} {% endif %}
{% if label.image %} {{ label.image }} {# Image #} {% endif %}
```

## LanguageUrl

**Attributes of object LanguageUrl**

| Name | Type | Description |
|---|---|---|
| url | string | Target URL |
| shop | [Shop](#shop) | Eshop |
| hreflang | string | null | Locale for the hreflang attribute, if available |
| shortDomain | string | null | Domain without WWW |

Examples:

```twig
{{ languageurl.url }}
{{ languageurl.shop }} {# Shop #}
{% if languageurl.hreflang %} {{ languageurl.hreflang }} {% endif %}
{% if languageurl.shortDomain %} {{ languageurl.shortDomain }} {% endif %}
```

## Link

**Attributes of object Link**

| Name | Type | Description |
|---|---|---|
| label | string | Link text |
| url | string | Link URL |
| title | string | null | Title |

Examples:

```twig
{{ link.label }}
{{ link.url }}
{% if link.title %} {{ link.title }} {% endif %}
```

## LoyaltyLevel

**Attributes of object LoyaltyLevel**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| pointsAmount | float | Points amount |
| minimumTotalPrice | [PriceValue](#pricevalue) | Minimum amount |
| maximumTotalPrice | [PriceValue](#pricevalue) | Maximum amount |

Examples:

```twig
{{ loyaltylevel.id }}
{{ loyaltylevel.pointsAmount }}
{{ loyaltylevel.minimumTotalPrice }} {# PriceValue #}
{{ loyaltylevel.maximumTotalPrice }} {# PriceValue #}
```

## Order

**Attributes of object Order**

| Name | Type | Description |
|---|---|---|
| amountOfItem | int | Total quantity of a specific item in the order |
| catalogItemCount | int | Number of items in the order |
| catalogItemTotalAmount | int | Total quantity of pieces in the order |
| id | int | Id |
| loyaltyPoints | int | Number of loyalty points earned for the order |
| usableLoyaltyPoints | int | Number of loyalty points applicable to the order |
| language | string | Order language |
| vs | string | Variable symbol (payment reference number) |
| containsAnyOfLabels | bool | Contains item with any of the labels? |
| containsItem | bool | Contains item? |
| containsLabel | bool | Contains item with label? |
| digitalPhysicalCombination | bool | Cart contains both digital and physical items |
| erotic | bool | Does the order contain an erotic item? |
| externalReviewAllowed | bool | Did the customer consent to a satisfaction survey? |
| paid | bool | Is the order paid? |
| preOrder | bool | Does the order contain a pre-order item? |
| useLoyaltyPoints | bool | Use loyalty points? |
| useLoyaltyPointsManually | bool | Are loyalty points applied only after manual selection? |
| accountingDocuments | [AccountingDocument](#accountingdocument)\[] | Accounting documents |
| address | [Addresses](#addresses) | Addresses |
| availablePaymentMethods | [Delivery/Payment](#delivery-payment)\[] | Available payment methods |
| payments | [Delivery/Payment](#delivery-payment)\[] | Order payments |
| availableTransportMethods | [Delivery/Transport](#delivery-transport)\[] | Available transport methods |
| delivery | [Delivery](#delivery) | Delivery |
| catalogItems | [Order/Item/CatalogItem](#order-item-catalogitem)\[] | Order items (products) |
| items | [Order/Item/CatalogItem](#order-item-catalogitem)\[] | [Order/Item/DiscountItem](#order-item-discountitem)\[] | Order items (products, discounts) |
| discountItems | [Order/Item/DiscountItem](#order-item-discountitem)\[] | Discounts |
| price | [Order/Price](#order-price) | Total prices |
| status | [Order/Status](#order-status) | Order status |
| shop | [Shop](#shop) | E-shop |
| url | [Url](#url) | URL for tracking order status (or cart for unsubmitted orders) |
| purchasedGiftVouchers | [Voucher/GiftVoucher](#voucher-giftvoucher)\[] | Purchased gift vouchers |
| vouchers | [Voucher/GiftVoucher](#voucher-giftvoucher)\[] | Applied discount codes or gift vouchers |
| code | string | null | Code |
| note | string | null | Customer note |
| date | datetime | null | Date created |
| dateInStatus | datetime | null | Date moved to current status |
| expectedShippingDate | datetime | null | Expected package shipping date (automatically calculated from availability or manually adjusted in admin) |
| customer | [Customer](#customer) | null | Registered customer |
| closestFreeDelivery | [Delivery](#delivery) | null | Closest available free delivery |
| parentOrder | [Order](#order) | null | Parent order |
| package | [Package](#package) | null | Package |
| store | [Store](#store) | null | Store for pickup |

Examples:

**Cart items and totals**

```twig
{% for item in cart.items %}
{{ item.name }} x {{ item.amount }} = {{ item.price.current.formatted }}
{% endfor %}
Total: {{ cart.price.current.formatted }}
```

**Discount and voucher display**

```twig
{% if cart.price.discount %}
Discount: -{{ cart.price.discountValue.formatted }}
{% endif %}
{% for voucher in cart.vouchers %}
Voucher: {{ voucher.code }} (-{{ voucher.discount.formatted }})
{% endfor %}
```

## Order/DiscountCode

**Attributes of object Order/DiscountCode**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| name | string | Discount code name |
| validFrom | datetime | Validity start date |
| validTo | datetime | Expiration date |

Examples:

```twig
{{ discountcode.code }}
{{ discountcode.name }}
{{ discountcode.validFrom|date('d. m. Y H:i') }}
{{ discountcode.validTo|date('d. m. Y H:i') }}
```

## Order/FreeLimit

**Attributes of object Order/FreeLimit**

| Name | Type | Description |
|---|---|---|
| percent | int | Percentage reached of total |
| total | [PriceValue](#pricevalue) | Order value to reach |
| remains | [PriceValue](#pricevalue) | Amount remaining to reach free delivery |

Examples:

```twig
{{ freelimit.percent }}
{{ freelimit.total }} {# PriceValue #}
{{ freelimit.remains }} {# PriceValue #}
```

## Order/Item/CatalogItem

**Attributes of object Order/Item/CatalogItem**

| Name | Type | Description |
|---|---|---|
| amount | int | Quantity |
| id | int | Id |
| name | string | Item name |
| productName | string | Product name |
| trackingId | string | ID used in feeds and tracking scripts |
| vatRate | float | VAT rate (%) |
| amountChangeAllowed | bool | Is quantity change allowed? |
| catalogItem | bool | Is a catalog item? |
| deleteAllowed | bool | Is removal from order allowed? |
| discountItem | bool | Is the item a discount? |
| gift | bool | Is the item a gift? |
| availableUpsellGroups | [AvailableUpsellGroup](#availableupsellgroup)\[] | Available upsell groups |
| availableConfiguratorUpsellGroups | [AvailableUpsellGroup](#availableupsellgroup)\[] | Available upsell groups for customization |
| children | [Order/Item/CatalogItem](#order-item-catalogitem)\[] | [Order/Item/DiscountItem](#order-item-discountitem)\[] | Child items (e.g. bundle parts) |
| relatedDiscounts | [Order/Item/DiscountItem](#order-item-discountitem)\[] | Related order discounts for the item (e.g. applied discount codes) |
| errors | [Order/Item/OrderItemError](#order-item-orderitemerror)\[] | Item errors (unavailable pieces, etc.) |
| price | [Price](#price) | Price per unit |
| priceTotal | [Price](#price) | Total price |
| availableConfigurators | [ProductDesigner/ProductDesigner](#productdesigner-productdesigner)\[] | Available configurators for customization |
| configuratorsWithResult | [ProductDesigner/ProductDesigner](#productdesigner-productdesigner)\[] | Returns available configurators that have customization results |
| availableUpsells | [Upsell](#upsell)\[] | Available upsell items |
| trackingIds | array | ID used in feeds and tracking scripts (variant and product) |
| code | string | null | Item code |
| note | string | null | Note |
| variantName | string | null | Variant name |
| image | [Image](#image) | null | Item image |
| item | [Item](#item) | null | Item (purchasable unit) |
| product | [Product](#product) | null | Product |
| unit | [Unit](#unit) | null | Unit of measure |
| upsell | [Upsell](#upsell) | null | Is the item an upsell? |
| variant | [Variant](#variant) | null | Variant |

Examples:

```twig
{{ catalogitem.amount }}
{{ catalogitem.id }}
{{ catalogitem.name }}
{{ catalogitem.productName }}
{{ catalogitem.trackingId }}
{{ catalogitem.vatRate }}
{% if catalogitem.amountChangeAllowed %} ... {% endif %}
{% if catalogitem.catalogItem %} ... {% endif %}
{% if catalogitem.deleteAllowed %} ... {% endif %}
{% if catalogitem.discountItem %} ... {% endif %}
{% if catalogitem.gift %} ... {% endif %}
{% for availableUpsellGroup in catalogitem.availableUpsellGroups %} ... {% endfor %}
{% for availableUpsellGroup in catalogitem.availableConfiguratorUpsellGroups %} ... {% endfor %}
{% for catalogItem in catalogitem.children %} ... {% endfor %}
{% for discountItem in catalogitem.relatedDiscounts %} ... {% endfor %}
{% for orderItemError in catalogitem.errors %} ... {% endfor %}
{{ catalogitem.price }} {# Price #}
{{ catalogitem.priceTotal }} {# Price #}
{% for productDesigner in catalogitem.availableConfigurators %} ... {% endfor %}
{% for productDesigner in catalogitem.configuratorsWithResult %} ... {% endfor %}
{% for upsell in catalogitem.availableUpsells %} ... {% endfor %}
{{ catalogitem.trackingIds }}
{% if catalogitem.code %} {{ catalogitem.code }} {% endif %}
{% if catalogitem.note %} {{ catalogitem.note }} {% endif %}
{% if catalogitem.variantName %} {{ catalogitem.variantName }} {% endif %}
{% if catalogitem.image %} {{ catalogitem.image }} {# Image #} {% endif %}
{% if catalogitem.item %} {{ catalogitem.item }} {# Item #} {% endif %}
{% if catalogitem.product %} {{ catalogitem.product }} {# Product #} {% endif %}
{% if catalogitem.unit %} {{ catalogitem.unit }} {# Unit #} {% endif %}
{% if catalogitem.upsell %} {{ catalogitem.upsell }} {# Upsell #} {% endif %}
{% if catalogitem.variant %} {{ catalogitem.variant }} {# Variant #} {% endif %}
```

## Order/Item/DiscountItem

**Attributes of object Order/Item/DiscountItem**

| Name | Type | Description |
|---|---|---|
| amount | int | Quantity |
| id | int | Discount ID |
| name | string | Discount name |
| vatRate | float | VAT rate (%) |
| amountChangeAllowed | bool | Is quantity change allowed? |
| catalogItem | bool | Is a catalog item? |
| deleteAllowed | bool | Is removal from order allowed? |
| discountItem | bool | Is a discount item? |
| children | [Order/Item/DiscountItem](#order-item-discountitem)\[] | Child items (e.g. bundle parts) |
| note | string | null | Note |
| trackingId | null | string | ID for tracking codes |
| percent | float | null | Value in percent (only if discount was created as percentage) |
| discountCode | [Order/DiscountCode](#order-discountcode) | null | Discount code |
| voucher | [Order/Voucher](#order-voucher) | null | Discount code / gift voucher |
| price | [Price](#price) | null | Discount value |
| priceTotal | [Price](#price) | null | Total price |
| unit | [Unit](#unit) | null | Quantity unit |

Examples:

```twig
{{ discountitem.amount }}
{{ discountitem.id }}
{{ discountitem.name }}
{{ discountitem.vatRate }}
{% if discountitem.amountChangeAllowed %} ... {% endif %}
{% if discountitem.catalogItem %} ... {% endif %}
{% if discountitem.deleteAllowed %} ... {% endif %}
{% if discountitem.discountItem %} ... {% endif %}
{% for discountItem in discountitem.children %} ... {% endfor %}
{% if discountitem.note %} {{ discountitem.note }} {% endif %}
{% if discountitem.trackingId %} {{ discountitem.trackingId }} {% endif %}
{% if discountitem.percent %} {{ discountitem.percent }} {% endif %}
{% if discountitem.discountCode %} {{ discountitem.discountCode }} {# DiscountCode #} {% endif %}
{% if discountitem.voucher %} {{ discountitem.voucher }} {# Voucher #} {% endif %}
{% if discountitem.price %} {{ discountitem.price }} {# Price #} {% endif %}
{% if discountitem.priceTotal %} {{ discountitem.priceTotal }} {# Price #} {% endif %}
{% if discountitem.unit %} {{ discountitem.unit }} {# Unit #} {% endif %}
```

## Order/Item/OrderItemError

**Attributes of object Order/Item/OrderItemError**

| Name | Type | Description |
|---|---|---|
| recommendedAmount | int | Recommended valid quantity |
| code | string | Error code |
| itemName | string | Problematic item name |
| message | string | Error message |

Examples:

```twig
{{ orderitemerror.recommendedAmount }}
{{ orderitemerror.code }}
{{ orderitemerror.itemName }}
{{ orderitemerror.message }}
```

## Order/Price

**Attributes of object Order/Price**

| Name | Type | Description |
|---|---|---|
| total | [PriceValue](#pricevalue) | Total value |
| unpaid | [PriceValue](#pricevalue) | Total amount due |
| paid | [PriceValue](#pricevalue) | Total paid |

Examples:

```twig
{{ price.total }} {# PriceValue #}
{{ price.unpaid }} {# PriceValue #}
{{ price.paid }} {# PriceValue #}
```

## Order/Status

**Attributes of object Order/Status**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Name |

Examples:

```twig
{{ status.id }}
{{ status.name }}
```

## Order/Voucher

**Attributes of object Order/Voucher**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| validTo | datetime | Expiration date |

Examples:

```twig
{{ voucher.code }}
{{ voucher.validTo|date('d. m. Y H:i') }}
```

## Order/ZeroPrice

**Attributes of object Order/ZeroPrice**

| Name | Type | Description |
|---|---|---|
| total | [PriceValue](#pricevalue) | Total value |
| unpaid | [PriceValue](#pricevalue) | Total amount due |
| paid | [PriceValue](#pricevalue) | Total paid |

Examples:

```twig
{{ zeroprice.total }} {# PriceValue #}
{{ zeroprice.unpaid }} {# PriceValue #}
{{ zeroprice.paid }} {# PriceValue #}
```

## Package

**Attributes of object Package**

| Name | Type | Description |
|---|---|---|
| parcelCount | int | Number of parcels |
| trackingUrl | string | Tracking URL |
| date | datetime | Dispatch date |
| history | [PackageHistory](#packagehistory)\[] | List of package delivery history records |
| status | [PackageStatus](#packagestatus) | Package status |
| code | string | null | Code |

Examples:

```twig
{{ package.parcelCount }}
{{ package.trackingUrl }}
{{ package.date|date('d. m. Y H:i') }}
{% for packageHistory in package.history %} ... {% endfor %}
{{ package.status }} {# PackageStatus #}
{% if package.code %} {{ package.code }} {% endif %}
```

## PackageHistory

**Attributes of object PackageHistory**

| Name | Type | Description |
|---|---|---|
| date | datetime | Change date |
| delivered | bool | Delivered |
| deposited | bool | Deposited at branch |
| inTransit | bool | In transit |
| notification | bool | General notification |
| returned | bool | Returned to e-shop |
| description | string | null | Description from carrier |

Examples:

```twig
{{ packagehistory.date|date('d. m. Y H:i') }}
{% if packagehistory.delivered %} ... {% endif %}
{% if packagehistory.deposited %} ... {% endif %}
{% if packagehistory.inTransit %} ... {% endif %}
{% if packagehistory.notification %} ... {% endif %}
{% if packagehistory.returned %} ... {% endif %}
{% if packagehistory.description %} {{ packagehistory.description }} {% endif %}
```

## PackageStatus

**Attributes of object PackageStatus**

| Name | Type | Description |
|---|---|---|
| delivered | bool | Has the package been delivered? |
| deposited | bool | Is the package deposited? |
| inTransit | bool | Is the package in transit? |
| returned | bool | Has the package been returned? (uncollected/refused) |

Examples:

```twig
{% if packagestatus.delivered %} ... {% endif %}
{% if packagestatus.deposited %} ... {% endif %}
{% if packagestatus.inTransit %} ... {% endif %}
{% if packagestatus.returned %} ... {% endif %}
```

## Pagination

**Attributes of object Pagination**

| Name | Type | Description |
|---|---|---|
| currentPage | int | Current page number |
| nextPageResultCount | int | Number of results on next page |
| pageCount | int | Number of available pages |
| perPage | int | Results per page (maximum) |
| resultsFrom | int | Starting result number |
| resultsTo | int | Ending result number |
| totalResults | int | Total number of results |
| html | html | HTML page links |
| nextPageUrl | string | null | Next page URL |

Examples:

```twig
{{ pagination.currentPage }}
{{ pagination.nextPageResultCount }}
{{ pagination.pageCount }}
{{ pagination.perPage }}
{{ pagination.resultsFrom }}
{{ pagination.resultsTo }}
{{ pagination.totalResults }}
{{ pagination.html }}
{% if pagination.nextPageUrl %} {{ pagination.nextPageUrl }} {% endif %}
```

## Payment

**Attributes of object Payment**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| amount | [PriceValue](#pricevalue) | Amount |
| text | string | null | Payment description |

Examples:

```twig
{{ payment.id }}
{{ payment.name }}
{{ payment.amount }} {# PriceValue #}
{% if payment.text %} {{ payment.text }} {% endif %}
```

## PaymentCalculator

**Attributes of object PaymentCalculator**

| Name | Type | Description |
|---|---|---|
| url | string | Calculator URL |
| windowJavascript | string | JavaScript to open calculator window |

Examples:

```twig
{{ paymentcalculator.url }}
{{ paymentcalculator.windowJavascript }}
```

## PaymentCalculators

**Attributes of object PaymentCalculators**

| Name | Type | Description |
|---|---|---|
| essox | [PaymentCalculator](#paymentcalculator) | null | Essox installment calculator |
| homecredit | [PaymentCalculator](#paymentcalculator) | null | Homecredit installment calculator |
| homecreditSK | [PaymentCalculator](#paymentcalculator) | null | Homecredit SK installment calculator |
| santander | [PaymentCalculator](#paymentcalculator) | null | Santander installment calculator |
| cofidis | [PaymentCalculator](#paymentcalculator) | null | Cofidis installment calculator |
| cofidisHU | [PaymentCalculator](#paymentcalculator) | null | Cofidis HU installment calculator |

Examples:

```twig
{% if paymentcalculators.essox %} {{ paymentcalculators.essox }} {# PaymentCalculator #} {% endif %}
{% if paymentcalculators.homecredit %} {{ paymentcalculators.homecredit }} {# PaymentCalculator #} {% endif %}
{% if paymentcalculators.homecreditSK %} {{ paymentcalculators.homecreditSK }} {# PaymentCalculator #} {% endif %}
{% if paymentcalculators.santander %} {{ paymentcalculators.santander }} {# PaymentCalculator #} {% endif %}
{% if paymentcalculators.cofidis %} {{ paymentcalculators.cofidis }} {# PaymentCalculator #} {% endif %}
{% if paymentcalculators.cofidisHU %} {{ paymentcalculators.cofidisHU }} {# PaymentCalculator #} {% endif %}
```

## Price

**Attributes of object Price**

| Name | Type | Description |
|---|---|---|
| vatRate | float | VAT rate |
| current | [PriceValue](#pricevalue) | Price |
| discountPercent | int | null | Discount (percentage) |
| discountValidTo | datetime | null | Discount expiry date (null if no discount or date is far away) |
| beforeDiscount | [PriceValue](#pricevalue) | null | Price before discount |
| discount | [PriceValue](#pricevalue) | null | Discount (amount) |

Examples:

```twig
{{ price.vatRate }}
{{ price.current }} {# PriceValue #}
{% if price.discountPercent %} {{ price.discountPercent }} {% endif %}
{{ price.discountValidTo|date('d. m. Y H:i') }}
{% if price.beforeDiscount %} {{ price.beforeDiscount }} {# PriceValue #} {% endif %}
{% if price.discount %} {{ price.discount }} {# PriceValue #} {% endif %}
```

## PriceValue

**Attributes of object PriceValue**

| Name | Type | Description |
|---|---|---|
| currency | string | Currency |
| formatted | string | Formatted output (e.g. 1 123 CZK) |
| value | float | Value |
| perUnit | [UnitPrice](#unitprice) | null | Price per base volume unit |

Examples:

```twig
{{ pricevalue.currency }}
{{ pricevalue.formatted }}
{{ pricevalue.value }}
{% if pricevalue.perUnit %} {{ pricevalue.perUnit }} {# UnitPrice #} {% endif %}
```

## PrintedLabel

**Attributes of object PrintedLabel**

| Name | Type | Description |
|---|---|---|
| quantity | int | Label count |
| barcodeContent | string | Barcode content |
| name | string | Item name (including variant name) |
| productName | string | Product name |
| qrDataUri | string | QR code with fixed item URL (redirects to current and allows additional tracking) |
| shortUrl | string | Short URL for QR code (redirects to current URL) |
| visibleCode | string | Visible code |
| item | [Item](#item) | Stock item |
| product | [Product](#product) | Product (with selected variant) |
| secondVisibleCode | string | null | Second visible code |
| variantName | string | null | Variant system name |
| price | [Price](#price) | null | Price (if to be displayed) |

Examples:

```twig
{{ printedlabel.quantity }}
{{ printedlabel.barcodeContent }}
{{ printedlabel.name }}
{{ printedlabel.productName }}
{{ printedlabel.qrDataUri }}
{{ printedlabel.shortUrl }}
{{ printedlabel.visibleCode }}
{{ printedlabel.item }} {# Item #}
{{ printedlabel.product }} {# Product #}
{% if printedlabel.secondVisibleCode %} {{ printedlabel.secondVisibleCode }} {% endif %}
{% if printedlabel.variantName %} {{ printedlabel.variantName }} {% endif %}
{% if printedlabel.price %} {{ printedlabel.price }} {# Price #} {% endif %}
```

## Product

**Attributes of object Product**

| Name | Type | Description |
|---|---|---|
| id | int | Internal product ID |
| commentType | string | Comment type for this entity |
| name | string | Product name |
| trackingId | string | ID used in feeds and tracking scripts |
| dateCreated | datetime | Date created |
| active | bool | Active |
| compared | bool | Is in comparison list? |
| differentVariantPrices | bool | Do variants have different prices? |
| flagNew | bool | New product |
| flagPromo | bool | Promo / on sale |
| flagSecondHand | bool | Second-hand goods |
| flagSellout | bool | Clearance sale |
| otherDiscountApplicable | bool | Can a coupon or user discount be applied? |
| soldSeparately | bool | Sold separately |
| publicContacts | [Address](#address)\[] | Public contacts |
| attributes | [Attribute/AttributeInstance](#attribute-attributeinstance)\[] | Attributes and values |
| availableUpsellGroups | [AvailableUpsellGroup](#availableupsellgroup)\[] | Available upsell groups |
| category | [Category](#category) | Main category |
| categories | [Category](#category)\[] | Categories |
| otherCategories | [Category](#category)\[] | Other categories |
| files | [File](#file)\[] | Files (manuals, specifications, ...) |
| images | [Image](#image)\[] | Images |
| imagesWithEnumValue | [Image](#image)\[] | Images with enum value |
| images360 | [Image](#image)\[] | Images for 360° view |
| currentImages | [Image](#image)\[] | Images with the currently displayed enum value |
| imagesWithoutEnumValue | [Image](#image)\[] | Images without enum value |
| otherImages | [Image](#image)\[] | Other images |
| item | [Item](#item) | Item (purchasable unit) |
| labels | [Label](#label)\[] | Labels (indexed by code) |
| configurators | [ProductDesigner/ProductDesigner](#productdesigner-productdesigner)\[] | Available configurators for customization |
| enumValues | [ProductEnumValue](#productenumvalue)\[] | Enum values |
| packTemplateProducts | [Product](#product)\[] | Products for set selection |
| rating | [Rating](#rating) | Rating |
| availableUpsells | [Upsell](#upsell)\[] | Available upsell items |
| url | [Url](#url) | Product URL |
| variantChoiceSteps | [VariantChoiceStep](#variantchoicestep)\[] | Variant selection steps |
| currentVariants | [Variant](#variant)\[] | Variants with the currently displayed enum value |
| variants | [Variant](#variant)\[] | Variants |
| variantsWithEnumValueIds | [Variant](#variant)\[] | Variants filtered by enum values (each variant will have all values) |
| variantType | [VariantType](#varianttype) | Variant type |
| videos | [Video](#video)\[] | Videos |
| trackingIds | array | ID used in feeds and tracking scripts - including all variants |
| currentSubName | string | null | Current selection name (color name, selected variant, ...) |
| nameSuffix | string | null | Name suffix |
| nameSupplier | string | null | Supplier name |
| text | html | null | Text |
| attribute | [Attribute/AttributeInstance](#attribute-attributeinstance) | null | Attribute with values |
| brand | [Brand](#brand) | null | Brand |
| image | [Image](#image) | null | Product image |
| imageForEnumValueId | [Image](#image) | null | Product image for enum value or fallback |
| successor | [Product](#product) | null | Successor product |
| seo | [Seo](#seo) | null | SEO attributes |
| supplier | [Supplier](#supplier) | null | Supplier |
| unit | [Unit](#unit) | null | Unit of measure |
| variant | [Variant](#variant) | null | Main variant |
| warranty | [Warranty](#warranty) | null | Warranty |
| contentGrid | array | null | Content grid |

Examples:

**Product card with price and image**

```twig
{{ product.name }}
<i:img src="product.image" format="359x479" fill />
{{ product.item.price.current.formatted }}
{% if product.item.price.discount %}
<del>{{ product.item.price.beforeDiscount.formatted }}</del>
{% endif %}
```

**Product labels and brand link**

```twig
{% for label in product.labels %}
<span style="background: {{ label.color }}">{{ label.name }}</span>
{% endfor %}
{% if product.brand %}
<a href="{{ product.brand.url }}">{{ product.brand.name }}</a>
{% endif %}
```

**Product availability and add-to-cart**

```twig
{% if product.item.available %}
<span>{{ product.item.availability.text }}</span>
<a href="{{ product.item.cartUrl }}">Add to cart</a>
{% else %}
<span>{{ product.item.availability.text }}</span>
{% endif %}
```

## ProductDesigner/ProductDesigner

**Attributes of object ProductDesigner/ProductDesigner**

| Name | Type | Description |
|---|---|---|
| name | string | Item name |
| upsell | [Upsell](#upsell) | Upsell |
| result | [ProductDesigner/ProductDesignerResult](#productdesigner-productdesignerresult) | null | Finished design from customer (images, prices, ...) |

Examples:

```twig
{{ productdesigner.name }}
{{ productdesigner.upsell }} {# Upsell #}
{% if productdesigner.result %} {{ productdesigner.result }} {# ProductDesignerResult #} {% endif %}
```

## ProductDesigner/ProductDesignerResult

**Attributes of object ProductDesigner/ProductDesignerResult**

| Name | Type | Description |
|---|---|---|
| imageUrl | string | Preview URL |
| uuid | string | Result identifier |
| price | [PriceValue](#pricevalue) | Design price |
| parts | [ProductDesigner/ProductDesignerResultPart](#productdesigner-productdesignerresultpart)\[] | Design parts |

Examples:

```twig
{{ productdesignerresult.imageUrl }}
{{ productdesignerresult.uuid }}
{{ productdesignerresult.price }} {# PriceValue #}
{% for productDesignerResultPart in productdesignerresult.parts %} ... {% endfor %}
```

## ProductDesigner/ProductDesignerResultPart

**Attributes of object ProductDesigner/ProductDesignerResultPart**

| Name | Type | Description |
|---|---|---|
| imageUrl | string | Image URL |
| label | string | Design part name |

Examples:

```twig
{{ productdesignerresultpart.imageUrl }}
{{ productdesignerresultpart.label }}
```

## ProductEnum

Enum

**Attributes of object ProductEnum**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| values | [EnumValue](#enumvalue)\[] | Values |
| text | html | null | Text |
| meaning | [AttributeMeaning](#attributemeaning) | null | Meaning |

Examples:

```twig
{{ productenum.id }}
{{ productenum.name }}
{% for enumValue in productenum.values %} ... {% endfor %}
{% if productenum.text %} {{ productenum.text }} {% endif %}
{% if productenum.meaning %} {{ productenum.meaning }} {# AttributeMeaning #} {% endif %}
```

## ProductEnumValue

Product enum value

**Attributes of object ProductEnumValue**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| selected | bool | Is value selected? (by filter, ...) |
| enum | [ProductEnum](#productenum) | Enum |
| url | [Url](#url) | Product URL with highlighted value |
| variants | [Variant](#variant)\[] | array | Product variants with enum value |
| text | html | null | Text |
| image | [Image](#image) | null | Image |
| variantImage | [Image](#image) | null | Variant image |

Examples:

```twig
{{ productenumvalue.id }}
{{ productenumvalue.name }}
{% if productenumvalue.selected %} ... {% endif %}
{{ productenumvalue.enum }} {# ProductEnum #}
{{ productenumvalue.url }} {# Url #}
{% for variant in productenumvalue.variants %} ... {% endfor %}
{% if productenumvalue.text %} {{ productenumvalue.text }} {% endif %}
{% if productenumvalue.image %} {{ productenumvalue.image }} {# Image #} {% endif %}
{% if productenumvalue.variantImage %} {{ productenumvalue.variantImage }} {# Image #} {% endif %}
```

## ProductMatcher

**Attributes of object ProductMatcher**

| Name | Type | Description |
|---|---|---|
| matches | bool | Does product match rules? Does order contain product matching rules? |

Examples:

```twig
{% if productmatcher.matches %} ... {% endif %}
```

## Rating

**Attributes of object Rating**

| Name | Type | Description |
|---|---|---|
| count | int | Number of votes |
| voted | bool | Can vote? |
| average | float | null | Average rating |

Examples:

```twig
{{ rating.count }}
{% if rating.voted %} ... {% endif %}
{% if rating.average %} {{ rating.average }} {% endif %}
```

## Reclaim

**Attributes of object Reclaim**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| code | string | Code |
| productCode | string | Product code |
| reportingType | string | Reporting method |
| incomingDate | datetime | Incoming date |
| purchaseDate | datetime | Purchase date |
| status | [RepairJob/Status](#repairjob-status) | Reclaim status |
| preferredSolutionCodes | array | Preferred resolutions |
| brand | [Brand](#brand) | null | Brand |
| invoice | [Invoice](#invoice) | null | Receipt |
| product | [Product](#product) | null | Product |
| store | [Store](#store) | null | Store |
| supplier | [Supplier](#supplier) | null | Supplier |

Examples:

```twig
{{ reclaim.id }}
{{ reclaim.code }}
{{ reclaim.productCode }}
{{ reclaim.reportingType }}
{{ reclaim.incomingDate|date('d. m. Y H:i') }}
{{ reclaim.purchaseDate|date('d. m. Y H:i') }}
{{ reclaim.status }} {# Status #}
{{ reclaim.preferredSolutionCodes }}
{% if reclaim.brand %} {{ reclaim.brand }} {# Brand #} {% endif %}
{% if reclaim.invoice %} {{ reclaim.invoice }} {# Invoice #} {% endif %}
{% if reclaim.product %} {{ reclaim.product }} {# Product #} {% endif %}
{% if reclaim.store %} {{ reclaim.store }} {# Store #} {% endif %}
{% if reclaim.supplier %} {{ reclaim.supplier }} {# Supplier #} {% endif %}
```

## RepairJob

**Attributes of object RepairJob**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| code | string | Code |
| status | [RepairJob/Status](#repairjob-status) | Repair job status |
| parts | use App/Entity/RepairJobItem\[] | Used parts |
| works | use App/Entity/RepairJobItem\[] | Labor |

Examples:

```twig
{{ repairjob.id }}
{{ repairjob.code }}
{{ repairjob.status }} {# Status #}
{% for item in repairjob.parts %} ... {% endfor %}
{% for item in repairjob.works %} ... {% endfor %}
```

## RepairJob/Status

**Attributes of object RepairJob/Status**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Name |

Examples:

```twig
{{ status.id }}
{{ status.name }}
```

## RepairJobItem

**Attributes of object RepairJobItem**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| amount | float | Quantity |
| vatRate | float | VAT rate (%) |
| price | [Price](#price) | Unit price |
| item | [Item](#item) | null | Item |

Examples:

```twig
{{ repairjobitem.id }}
{{ repairjobitem.amount }}
{{ repairjobitem.vatRate }}
{{ repairjobitem.price }} {# Price #}
{% if repairjobitem.item %} {{ repairjobitem.item }} {# Item #} {% endif %}
```

## ReturnCase

**Attributes of object ReturnCase**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| code | string | Code |
| createdDate | datetime | Creation date |
| invoice | [Invoice](#invoice) | Receipt |
| items | [ReturnCaseItem](#returncaseitem)\[] | Returned items |
| shipmentPIN | string | null | Shipment submission PIN |
| incomingDate | datetime | null | Incoming date |

Examples:

```twig
{{ returncase.id }}
{{ returncase.code }}
{{ returncase.createdDate|date('d. m. Y H:i') }}
{{ returncase.invoice }} {# Invoice #}
{% for returnCaseItem in returncase.items %} ... {% endfor %}
{% if returncase.shipmentPIN %} {{ returncase.shipmentPIN }} {% endif %}
{{ returncase.incomingDate|date('d. m. Y H:i') }}
```

## ReturnCaseItem

**Attributes of object ReturnCaseItem**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| quantity | int | Returned item quantity |
| code | string | Code |
| name | string | Returned item name |

Examples:

```twig
{{ returncaseitem.id }}
{{ returncaseitem.quantity }}
{{ returncaseitem.code }}
{{ returncaseitem.name }}
```

## Review

**Attributes of object Review**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| date | datetime | Date |
| rating | int | null | Rating |
| ratingCommunication | int | null | Store communication rating |
| ratingDeliveryTime | int | null | Delivery time rating |
| ratingTransportQuality | int | null | Delivery quality rating |
| ratingWebUsability | int | null | Website usability rating |
| cons | string | null | Cons |
| email | string | null | Email |
| name | string | null | Name |
| pros | string | null | Pros |
| ratingReaction | string | null | Store reaction |
| text | string | null | Review text |

Examples:

```twig
{{ review.id }}
{{ review.date|date('d. m. Y H:i') }}
{% if review.rating %} {{ review.rating }} {% endif %}
{% if review.ratingCommunication %} {{ review.ratingCommunication }} {% endif %}
{% if review.ratingDeliveryTime %} {{ review.ratingDeliveryTime }} {% endif %}
{% if review.ratingTransportQuality %} {{ review.ratingTransportQuality }} {% endif %}
{% if review.ratingWebUsability %} {{ review.ratingWebUsability }} {% endif %}
{% if review.cons %} {{ review.cons }} {% endif %}
{% if review.email %} {{ review.email }} {% endif %}
{% if review.name %} {{ review.name }} {% endif %}
{% if review.pros %} {{ review.pros }} {% endif %}
{% if review.ratingReaction %} {{ review.ratingReaction }} {% endif %}
{% if review.text %} {{ review.text }} {% endif %}
```

## Seo

**Attributes of object Seo**

| Name | Type | Description |
|---|---|---|
| description | string | null | SEO description |
| keywords | string | null | SEO keywords |
| title | string | null | SEO title |

Examples:

```twig
{% if seo.description %} {{ seo.description }} {% endif %}
{% if seo.keywords %} {{ seo.keywords }} {% endif %}
{% if seo.title %} {{ seo.title }} {% endif %}
```

## Shop

**Attributes of object Shop**

| Name | Type | Description | Example output |
|---|---|---|---|
| socialProfiles | [SocialProfile](#socialprofile)\[] | Social networks |  |
| email | string | null | Email | info@my-shop.cz |
| language | string | null | Shop language |  |
| locale | string | null | Locale |  |
| name | string | null | Name | MyShop.cz |
| phone | string | null | Phone | +420 777 123 456 |
| shortDomain | string | null | Domain without WWW |  |
| url | string | null | URL | https://my-shop.cz |
| country | [Address/Country](#address-country) | null | Country |  |
| image | [Image](#image) | null | Image |  |

Examples:

**Shop info in footer**

```twig
{{ shop.name }}
{{ shop.email }}
{{ shop.phone }}
{% for profile in shop.socialProfiles %}
<a href="{{ profile.url }}">{{ profile.type }}</a>
{% endfor %}
```

## SocialProfile

**Attributes of object SocialProfile**

| Name | Type | Description |
|---|---|---|
| type | string | Social network type |
| url | string | Profile URL |

Examples:

```twig
{{ socialprofile.type }}
{{ socialprofile.url }}
```

## StorageCenter

**Attributes of object StorageCenter**

| Name | Type | Description |
|---|---|---|
| name | string | Name |
| storageRooms | [StorageRoom](#storageroom)\[] | Storage rooms |
| shortName | string | null | Short name |
| address | [Address](#address) | null | Center address |

Examples:

```twig
{{ storagecenter.name }}
{% for storageRoom in storagecenter.storageRooms %} ... {% endfor %}
{% if storagecenter.shortName %} {{ storagecenter.shortName }} {% endif %}
{% if storagecenter.address %} {{ storagecenter.address }} {# Address #} {% endif %}
```

## StorageRoom

**Attributes of object StorageRoom**

| Name | Type | Description |
|---|---|---|
| name | string | Name |
| doesSupportLocations | bool | Uses storage locations? |

Examples:

```twig
{{ storageroom.name }}
{% if storageroom.doesSupportLocations %} ... {% endif %}
```

## Store

**Attributes of object Store**

| Name | Type | Description |
|---|---|---|
| distanceFromPoint | int | Distance of store from point in kilometers |
| id | int | Id |
| name | string | Name |
| cashiers | [Admin](#admin)\[] | Cashiers |
| attributes | [Attribute/AttributeInstance](#attribute-attributeinstance)\[] | Attributes and values |
| images | [Image](#image)\[] | Images |
| url | [Url](#url) | Store URL |
| videos | [Video](#video)\[] | Videos |
| city | string | null | City |
| companyId | string | null | Company ID |
| email | string | null | Email |
| latitude | string | null | GPS - latitude |
| longitude | string | null | GPS - longitude |
| phone | string | null | Phone |
| street | string | null | Street |
| vatId | string | null | VAT ID |
| zip | string | null | Zip code |
| text | html | null | Text |
| country | [Address/Country](#address-country) | null | Country |
| attribute | [Attribute/AttributeInstance](#attribute-attributeinstance) | null | Attribute with values |
| image | [Image](#image) | null | Image |
| workingHours | [WorkingHours](#workinghours) | null | Working hours |
| contentGrid | array | null | Content grid |

Examples:

```twig
{{ store.distanceFromPoint }}
{{ store.id }}
{{ store.name }}
{% for admin in store.cashiers %} ... {% endfor %}
{% for attributeInstance in store.attributes %} ... {% endfor %}
{% for image in store.images %} ... {% endfor %}
{{ store.url }} {# Url #}
{% for video in store.videos %} ... {% endfor %}
{% if store.city %} {{ store.city }} {% endif %}
{% if store.companyId %} {{ store.companyId }} {% endif %}
{% if store.email %} {{ store.email }} {% endif %}
{% if store.latitude %} {{ store.latitude }} {% endif %}
{% if store.longitude %} {{ store.longitude }} {% endif %}
{% if store.phone %} {{ store.phone }} {% endif %}
{% if store.street %} {{ store.street }} {% endif %}
{% if store.vatId %} {{ store.vatId }} {% endif %}
{% if store.zip %} {{ store.zip }} {% endif %}
{% if store.text %} {{ store.text }} {% endif %}
{% if store.country %} {{ store.country }} {# Country #} {% endif %}
{% if store.attribute %} {{ store.attribute }} {# AttributeInstance #} {% endif %}
{% if store.image %} {{ store.image }} {# Image #} {% endif %}
{% if store.workingHours %} {{ store.workingHours }} {# WorkingHours #} {% endif %}
{% if store.contentGrid %} {{ store.contentGrid }} {% endif %}
```

## Supplier

**Attributes of object Supplier**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| publicContacts | [Address](#address)\[] | Public contacts |

Examples:

```twig
{{ supplier.id }}
{{ supplier.name }}
{% for address in supplier.publicContacts %} ... {% endfor %}
```

## TextPage

Text page - used for terms and conditions, etc.

**Attributes of object TextPage**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Page name |
| files | [File](#file)\[] | Files (manuals, specifications, ...) |
| images | [Image](#image)\[] | Images |
| subPages | [TextPage](#textpage)\[] | Subpages |
| url | [Url](#url) | Page URL |
| videos | [Video](#video)\[] | Videos |
| code | string | null | Code identifier for template conditions |
| text | html | null | Page text |
| image | [Image](#image) | null | Main image |
| contentGrid | array | null | Content grid |

Examples:

```twig
{{ textpage.id }}
{{ textpage.name }}
{% for file in textpage.files %} ... {% endfor %}
{% for image in textpage.images %} ... {% endfor %}
{% for textPage in textpage.subPages %} ... {% endfor %}
{{ textpage.url }} {# Url #}
{% for video in textpage.videos %} ... {% endfor %}
{% if textpage.code %} {{ textpage.code }} {% endif %}
{% if textpage.text %} {{ textpage.text }} {% endif %}
{% if textpage.image %} {{ textpage.image }} {# Image #} {% endif %}
{% if textpage.contentGrid %} {{ textpage.contentGrid }} {% endif %}
```

## TextTemplate

Text page from template - order confirmation, etc.

**Attributes of object TextTemplate**

| Name | Type | Description |
|---|---|---|
| name | string | Name |
| text | html | null | Page text |

Examples:

```twig
{{ texttemplate.name }}
{% if texttemplate.text %} {{ texttemplate.text }} {% endif %}
```

## TimeBlock

**Attributes of object TimeBlock**

| Name | Type | Description |
|---|---|---|
| end | string | Opening end time |
| separator | string | Time separator |
| start | string | Opening start time |

Examples:

```twig
{{ timeblock }}
{{ timeblock.end }}
{{ timeblock.separator }}
{{ timeblock.start }}
```

## Topic

**Attributes of object Topic**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |
| image | [Image](#image) | Image |
| subtopics | [Topic](#topic)\[] | Subtopics |
| url | [Url](#url) | URL (without domain) |
| pathNames | array | Topic path (names) |
| text | html | null | Text |
| seo | [Seo](#seo) | null | SEO attributes |
| parent | [Topic](#topic) | null | Parent topic |
| contentGrid | array | null | Content grid |

Examples:

```twig
{{ topic.id }}
{{ topic.name }}
{{ topic.image }} {# Image #}
{% for topic in topic.subtopics %} ... {% endfor %}
{{ topic.url }} {# Url #}
{{ topic.pathNames }}
{% if topic.text %} {{ topic.text }} {% endif %}
{% if topic.seo %} {{ topic.seo }} {# Seo #} {% endif %}
{% if topic.parent %} {{ topic.parent }} {# Topic #} {% endif %}
{% if topic.contentGrid %} {{ topic.contentGrid }} {% endif %}
```

## Unit

**Attributes of object Unit**

| Name | Type | Description |
|---|---|---|
| name | string | Quantity unit name |

Examples:

```twig
{{ unit.name }}
```

## UnitPrice

**Attributes of object UnitPrice**

| Name | Type | Description |
|---|---|---|
| formatted | string | Formatted output (e.g. 1 123 CZK/kg) |
| unit | string | Base unit (e.g. kg) |
| price | [PriceValue](#pricevalue) | Price per unit |

Examples:

```twig
{{ unitprice }}
{{ unitprice.formatted }}
{{ unitprice.unit }}
{{ unitprice.price }} {# PriceValue #}
```

## Upsell

**Attributes of object Upsell**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| name | string | Item name |
| inCart | bool | Is in current order? |
| category | [Category](#category) | Main category |
| price | [Price](#price) | Unit price |
| product | [Product](#product) | Upsell item product (for URL, description, ...) |
| group | [UpsellGroup](#upsellgroup) | Group |
| code | string | null | Item code |
| vatRate | float | null | VAT rate (%) |
| image | [Image](#image) | null | Item image |
| unit | [Unit](#unit) | null | Quantity unit |

Examples:

```twig
{{ upsell.id }}
{{ upsell.name }}
{% if upsell.inCart %} ... {% endif %}
{{ upsell.category }} {# Category #}
{{ upsell.price }} {# Price #}
{{ upsell.product }} {# Product #}
{{ upsell.group }} {# UpsellGroup #}
{% if upsell.code %} {{ upsell.code }} {% endif %}
{% if upsell.vatRate %} {{ upsell.vatRate }} {% endif %}
{% if upsell.image %} {{ upsell.image }} {# Image #} {% endif %}
{% if upsell.unit %} {{ upsell.unit }} {# Unit #} {% endif %}
```

## UpsellGroup

**Attributes of object UpsellGroup**

| Name | Type | Description |
|---|---|---|
| id | int | ID |
| requiredNoteMaximumLength | int | Maximum customer note length |
| name | string | Group name |
| requiredNote | bool | Is customer note required? |
| requiredUpload | bool | Is customer file upload required? |
| singleSelection | bool | Selection mode |
| text | html | null | Text |
| uploadInput | html | null | HTML for file upload input |

Examples:

```twig
{{ upsellgroup.id }}
{{ upsellgroup.requiredNoteMaximumLength }}
{{ upsellgroup.name }}
{% if upsellgroup.requiredNote %} ... {% endif %}
{% if upsellgroup.requiredUpload %} ... {% endif %}
{% if upsellgroup.singleSelection %} ... {% endif %}
{% if upsellgroup.text %} {{ upsellgroup.text }} {% endif %}
{% if upsellgroup.uploadInput %} {{ upsellgroup.uploadInput }} {% endif %}
```

## Url

**Attributes of object Url**

| Name | Type | Description | Example output |
|---|---|---|---|
| absolute | string | URL including domain and protocol | https://www.example.org/product-1 |
| path | string | URL within domain | /product-1 |

Examples:

```twig
{{ url }}
{{ url.absolute }}
{{ url.path }}
```

## UserPointChange

Loyalty program points change

**Attributes of object UserPointChange**

| Name | Type | Description |
|---|---|---|
| amount | int | Points amount |
| text | string | Description |
| date | datetime | Date |
| dateExpire | datetime | null | Expiration date |

Examples:

```twig
{{ userpointchange.amount }}
{{ userpointchange.text }}
{{ userpointchange.date|date('d. m. Y H:i') }}
{{ userpointchange.dateExpire|date('d. m. Y H:i') }}
```

## Variant

**Attributes of object Variant**

| Name | Type | Description |
|---|---|---|
| id | int | Internal variant ID |
| name | string | Variant name |
| trackingId | string | ID used in feeds and tracking scripts |
| active | bool | Active |
| selected | bool | Is preselected? |
| availableUpsellGroups | [AvailableUpsellGroup](#availableupsellgroup)\[] | Available upsell groups |
| enumValues | [EnumValue](#enumvalue)\[] | Enum values |
| images | [Image](#image)\[] | Variant images |
| item | [Item](#item) | Item |
| product | [Product](#product) | Product |
| availableUpsells | [Upsell](#upsell)\[] | Available upsell items |
| url | [Url](#url) | Variant URL (variant is preselected in product detail) |
| legacyRel | string | null | Legacy property listing - awaiting migration |
| image | [Image](#image) | null | Item image |

Examples:

**Variant properties display**

```twig
{{ variant.name }}
{{ variant.code }}
{{ variant.item.price.current.formatted }}
{% if variant.item.available %}In stock{% endif %}
```

## VariantChoice

**Attributes of object VariantChoice**

| Name | Type | Description |
|---|---|---|
| inputValue | string | Value for selection input |
| name | string | Choice name |
| selected | bool | Is value selected? (for input checked) |
| color | string | null | Hex color code (including #) |
| description | string | null | Value description |
| availability | [Availability](#availability) | null | Availability |
| bundle | [Bundle](#bundle) | null | Bundle |
| icon | [Image](#image) | null | Choice icon image |
| image | [Image](#image) | null | Image |
| price | [Price](#price) | null | Item price |

Examples:

```twig
{{ variantchoice.inputValue }}
{{ variantchoice.name }}
{% if variantchoice.selected %} ... {% endif %}
{% if variantchoice.color %} {{ variantchoice.color }} {% endif %}
{% if variantchoice.description %} {{ variantchoice.description }} {% endif %}
{% if variantchoice.availability %} {{ variantchoice.availability }} {# Availability #} {% endif %}
{% if variantchoice.bundle %} {{ variantchoice.bundle }} {# Bundle #} {% endif %}
{% if variantchoice.icon %} {{ variantchoice.icon }} {# Image #} {% endif %}
{% if variantchoice.image %} {{ variantchoice.image }} {# Image #} {% endif %}
{% if variantchoice.price %} {{ variantchoice.price }} {# Price #} {% endif %}
```

## VariantChoiceStep

**Attributes of object VariantChoiceStep**

| Name | Type | Description |
|---|---|---|
| headline | string | Headline |
| inputName | string | Selection input name |
| mode | string | Selection display mode code |
| final | bool | Last selection step? (i.e. no more steps load after choosing a value) |
| choices | [VariantChoice](#variantchoice)\[] | array | Available choices |
| description | string | null | Selection description |
| infoDescription | string | null | Description for more information link |
| messageEmpty | string | null | Error message when value is not selected |
| placeholder | string | null | First "placeholder" item for dropdown |
| icon | [Image](#image) | null | Icon |
| infoIcon | [Image](#image) | null | Icon |
| info | [TextPage](#textpage) | null | Text page with additional information |
| selectedChoice | [VariantChoice](#variantchoice) | null | Selected choice |

Examples:

```twig
{{ variantchoicestep.headline }}
{{ variantchoicestep.inputName }}
{{ variantchoicestep.mode }}
{% if variantchoicestep.final %} ... {% endif %}
{% for variantChoice in variantchoicestep.choices %} ... {% endfor %}
{% if variantchoicestep.description %} {{ variantchoicestep.description }} {% endif %}
{% if variantchoicestep.infoDescription %} {{ variantchoicestep.infoDescription }} {% endif %}
{% if variantchoicestep.messageEmpty %} {{ variantchoicestep.messageEmpty }} {% endif %}
{% if variantchoicestep.placeholder %} {{ variantchoicestep.placeholder }} {% endif %}
{% if variantchoicestep.icon %} {{ variantchoicestep.icon }} {# Image #} {% endif %}
{% if variantchoicestep.infoIcon %} {{ variantchoicestep.infoIcon }} {# Image #} {% endif %}
{% if variantchoicestep.info %} {{ variantchoicestep.info }} {# TextPage #} {% endif %}
{% if variantchoicestep.selectedChoice %} {{ variantchoicestep.selectedChoice }} {# VariantChoice #} {% endif %}
```

## VariantType

**Attributes of object VariantType**

| Name | Type | Description |
|---|---|---|
| id | int | Id |
| name | string | Name |

Examples:

```twig
{{ varianttype.id }}
{{ varianttype.name }}
```

## Video

Videos should not be output via \<video src=, but always via the helper tag \<i:video, which handles retina displays and responsiveness.

**Attributes of object Video**

| Name | Type | Description |
|---|---|---|
| embeddedUrl | string | URL for displaying the player (for Fancybox only, otherwise use i:video) |
| name | string | null | Name |
| image | [Image](#image) | null | Main image |

Examples:

```twig
{{ video.embeddedUrl }}
{% if video.name %} {{ video.name }} {% endif %}
{% if video.image %} {{ video.image }} {# Image #} {% endif %}
```

## Visit

**Attributes of object Visit**

| Name | Type | Description | Example output |
|---|---|---|---|
| perPage | int | Records per page | 20 |
| country | string | Country code | cz |
| currency | string | Currency code | CZK |
| deliveryCountry | string | Delivery country code | cz |
| language | string | Language code | cz |
| android | bool | Is visitor using Android? |  |
| bot | bool | Is visitor a bot? | true |
| iOS | bool | Is visitor using iOS? |  |
| mobileDevice | bool | Is visitor on mobile device? | true |

Examples:

```twig
{{ visit.perPage }}
{{ visit.country }}
{{ visit.currency }}
{{ visit.deliveryCountry }}
{{ visit.language }}
{% if visit.android %} ... {% endif %}
{% if visit.bot %} ... {% endif %}
{% if visit.iOS %} ... {% endif %}
{% if visit.mobileDevice %} ... {% endif %}
```

## Voucher/GiftVoucher

**Attributes of object Voucher/GiftVoucher**

| Name | Type | Description |
|---|---|---|
| code | string | Code |
| name | string | Discount code name |
| validFrom | datetime | Validity start date |
| validTo | datetime | Expiration date |
| value | [PriceValue](#pricevalue) | Voucher value |

Examples:

```twig
{{ giftvoucher.code }}
{{ giftvoucher.name }}
{{ giftvoucher.validFrom|date('d. m. Y H:i') }}
{{ giftvoucher.validTo|date('d. m. Y H:i') }}
{{ giftvoucher.value }} {# PriceValue #}
```

## Warranty

**Attributes of object Warranty**

| Name | Type | Description |
|---|---|---|
| months | int | Number of months |

Examples:

```twig
{{ warranty.months }}
```

## WorkingHours

**Attributes of object WorkingHours**

| Name | Type | Description |
|---|---|---|
| open | bool | Is currently open? |
| forNextDays | [DayBlock](#dayblock)\[] | Opening hours for upcoming days |
| week | array | Opening hours for the week, consecutive days are merged into one record |
| weekFull | array | Opening hours for the full week, each day separately |
| specialCases | array | Opening hours exceptions |
| nextClose | datetime | null | Date and time of next closing |
| nextOpen | datetime | null | Date and time of next opening (if at all) |

Examples:

```twig
{% if workinghours.open %} ... {% endif %}
{% for dayBlock in workinghours.forNextDays %} ... {% endfor %}
{{ workinghours.week }}
{{ workinghours.weekFull }}
{{ workinghours.specialCases }}
{{ workinghours.nextClose|date('d. m. Y H:i') }}
{{ workinghours.nextOpen|date('d. m. Y H:i') }}
```

---

---
url: /performance.md
---
# Performance Optimization

## Images

All template images (PNG/JPG/GIF) are optimized. Unnecessary data (EXIF, etc.) is removed and lossless compression is applied.

This optimization happens **only after publishing**.

## Images in CSS

Images used in CSS (background, etc.) can be replaced with data-URIs. This eliminates waiting for them to load, as they are embedded directly in the CSS. For an image to be converted to a data-URI, it must meet these conditions:

* the image must not be larger than 1 KB (after optimization)
* the image appears only once in the CSS

## CSS Minification

All CSS files (including plugins) are merged into one file and then minified. Property declarations are simplified (for example, *margin-left*, *margin-right*, *margin-top* are merged into a single *margin*) and identical rules are combined.

```css
/* original CSS */
.product .price {
    display: none;
}
.hidden {
    display: none;
}

/* minified output */
.product .price,.hidden{display:none}
```

## JavaScript Minification

All JS files are merged into one (including plugins) and minified. Whitespace is removed, dead code is eliminated, and variables inside functions are replaced with shorter names.

You can help the minifier by wrapping logical units in an anonymous function. This results in smaller minified code and also isolates the code from the rest of the template. Wrapping only makes sense for larger units such as delivery JavaScript — there is no benefit in wrapping a single banner definition.

```javascript
(function(){
    // long code block
}());
```

## JavaScript

JavaScript is loaded at the end of the page. This way, page rendering does not wait for it to load. Visitors can use the page before JavaScript loads, so the page should work without it.

All plugins are initialized last, so this needs to be accounted for in CSS. For example, all tabs except the first one must be hidden via CSS — do not rely on JavaScript to hide them.

There is no need to use *$(document).ready* in JavaScript — because scripts load at the end of the page, this function is unnecessary and actually slows down execution.

## Lazy-load

When using banners, always use lazy-load. The first banner is rendered normally in the page, and the rest are loaded only when needed. This significantly speeds up page loading.

```twig
<div class="owl-carousel">
    {%for banner in zdroj_bannery_index%}
        <a href="{{banner.odkaz}}" title="{{banner.popis?banner.popis:banner.nazev}}" class="item">
            {%if loop.first%}
                <img src="banner.link" alt="{{banner.alt}}">
            {%else%}
                <img data-src="{{banner.link}}" class="owl-lazy" alt="{{banner.alt}}">
            {%endif%}
        </a>
    {%endfor%}
</div>
```

```javascript
var $owlCarousel = $('.owl-carousel');
if ($owlCarousel.size()) {
    $owlCarousel.owlCarousel({
        loop: true,
        items: 1,
        autoplay: true,
        autoplayTimeout: 8000,
        autoplayHoverPause: true,
        autoplaySpeed: 1000,
        lazyLoad: true
    });
}
```

## WebFonts

Google Fonts are loaded from CDN using preload so they are available as early as possible, with font-display:swap set. The site first renders with a fallback font and then flashes to the final font once it loads. To minimize the visual shift after font loading, you can use the **wf-active** class, which is applied to the HTML tag after all fonts have loaded.

In addition to the fallback font, you also need to match letter-spacing etc., so the text is as similar as possible. The quickest way to find the right settings is [FontStyleMatcher](https://meowni.ca/font-style-matcher/). You can test how the site looks without web fonts by appending *?\_disableWebFonts* to the URL.

Example:

```css
h1 {
    font-family: Verdana, sans-serif;
    letter-spacing: 0.4px;
}
.wf-active h1 {
    font-family: 'Open Sans', Verdana, sans-serif;
    letter-spacing: 0;
}
```

![](https://cloud.githubusercontent.com/assets/1369170/20506300/ed61ebac-b007-11e6-8324-df0a90604acd.gif)

## Critical CSS

When changes are deployed to production, critical CSS is generated. The result is the set of styles needed for an approximate rendering of the page. When these are used, the page does not wait for all stylesheets to load before displaying — it renders immediately.

The page likely will not look 100% correct, but it will appear faster. After the full stylesheets load, the appearance is corrected. The delay between critical and complete styles is typically **less than 1 second**, but it has a major impact on the perceived loading speed.

Critical CSS can be verified in the production version by pressing CTRL+F5 (the critical styles flash briefly and then the normal styles load) or by appending the **?\_forceCritical** parameter to the URL (only when logged in). When testing, keep in mind that in a real deployment the user does not have images cached, etc. The most realistic preview is obtained via [Google PageSpeed](https://developers.google.com/speed/pagespeed/insights/).

Automatic critical CSS generation runs on the main page types (index, product, category, subcategory, page), and for each type a random URL is selected (for example, a random product). However, some products may have a different layout. In config.json you can therefore define which CSS selectors should always be included, regardless of whether they were visible on the page. See the [criticalCss config reference](config.md#criticalcss) for all options including viewport overrides.

config.json:

```json
{
    "webfonts":[
        "Open Sans:400,600,700"
    ],
    "criticalCss": {
        "global": {
            "forceInclude": [".header-info-bar"],
            "forceExclude": [".promo-dialog"]
        },
        "index": {
            "forceInclude": [".main-banner"],
            "forceExclude": [".video-player"]
        },
        "product": {
            "forceInclude": [".image-gallery"]
        },
        "category": {
            "forceInclude": [".image-gallery"]
        },
        "subcategory": {
            "forceInclude": [".image-gallery"]
        },
        "page": {
            "forceInclude": [".image-gallery"]
        }
    }
}
```

---

---
url: /filter.md
---
# Product Filter

## Filter form

```twig
{# minimal usage #}
<i:filter-form name="default">
    {% for attribute in attributes %}
        <i:filter-attribute attribute="attribute">
            <a data-role="show-more">{% trans 'template.filter.more' %} (%n)</a>
        </i:filter-attribute>
    {% endfor %}
    <div data-role="reset">
        {% trans 'template.filter.active' %}
        <a data-role="reset">{% trans 'template.filter.reset' %}</a>
    </div>
    <button type="submit">{% trans 'template.filter.submit-button' %}</button>
</i:filter-form>
```

**Attributes of filter-form**

| Attribute | Required | Default | Description |
|---|---|---|---|
| **name** | **yes** | --- | name |
| auto-scroll | true | --- | automatically scroll to results (true/false) |

## Filter attribute

```twig
<i:filter-form name="default">
    {% for attribute in attributes %}
        <i:filter-attribute attribute="attribute" choice-wrap="div">
            <a data-role="show-more">{% trans 'template.filter.more' %} (%n)</a>
            <a data-role="show-less">{% trans 'template.filter.less' %}</a>
        </i:filter-attribute>
    {% endfor %}
    <button type="submit">{% trans 'template.filter.submit-button' %}</button>
</i:filter-form>
```

The "show-more"/"show-less" link is only displayed when needed. The optional `%n` placeholder is replaced with the number of hidden values. Expand/collapse functionality is handled globally and the expanded state is saved to LocalStorage.

**Attributes of filter-attribute**

| Attribute | Required | Default | Description |
|---|---|---|---|
| **attribute** | **yes** | --- | Twig object |
| choice-wrap | *no* | span | wrapper tag |
| checkbox-class | *no* | --- | CSS classes for the checkbox input |
| img-format | *no* | 30x30 | image size (same as in i:img) |
| img-sizes | *no* | --- | responsive sizes for the image (same as in i:img) |

## Filter values

Renders active filter values with the ability to remove individual values or reset the entire filter.

```twig
<i:filter-values name="default">
    {% for value in values %}
        <a href="{{value.url}}">{{value.name}}</a>
    {% endfor%}
    <a href="{{resetUrl}}">{% trans 'template.filter.reset' %}</a>
</i:filter-values>
```

**Attributes of filter-values**

| Attribute | Required | Description |
|---|---|---|
| **name** | **yes** | object name |

## Filter placeholder

```twig
<i:filter-placeholder name="default" config="default" />
```

**Attributes of filter-placeholder**

| Attribute | Required | Description |
|---|---|---|
| **name** | **yes** | object name |
| **config** | **yes** | filter group code |
| **hide-empty** | **no** | do not render the form if there are no filters to display |
| **always-collapsed** | **no** | collapse all filters regardless of the admin panel settings |

## Filter placeholder values

The i:filter-placeholder-values block must not be wrapped in a condition checking for an active filter! If the filter is not active, it will render as an empty div. If it were hidden by a parent condition, it could not appear dynamically during filtering.

```twig
<i:filter-placeholder-values name="default" config="default" />
```

**Attributes of filter-placeholder-values**

| Attribute | Required | Description |
|---|---|---|
| **name** | **yes** | object name |
| **config** | **yes** | filter group code |

## Price Slider (legacy filters)

Price slider for the filter. Uses jQuery UI Slider (must be enabled in plugins). No JavaScript initialization is needed -- inserting the tag into the template sets everything up automatically.
Elements marked with the *from* and *to* roles are used to display the current price.

```twig
{# minimal usage #}
<i:price-slider>
    <div data-role="slider"></div>
    <span data-role="from"></span> - <span data-role="to"></span>
</i:price-slider>

{# visible input #}
<i:price-slider>
    <div data-role="slider"></div>
    <input data-role="from"></input> - <input data-role="to"></input>
</i:price-slider>

{# custom classes (any) #}
<i:price-slider>
    <div data-role="slider"  class="slider-range" ></div>
    <div class="range">
        <em>{%trans%}od {%endtrans%} <span class="range-from" data-role="from"></span>  do <span class="range-to" data-role="to"></span></em>
    </div>
</i:price-slider>
```

To customize the slider behavior, use standard jQuery UI events ([documentation](https://api.jqueryui.com/slider/)). First add a custom class to the slider, then modify its behavior in external JavaScript:

```javascript
$(document).on('slide', '.slider-range', function(event, ui) {
    alert(ui.value);
});
```

Slider properties can be changed the same way:

```javascript
$('.slider-range').slider('option', 'animate', 'fast');
```

## Complete Filter Template

A production `_filter.tpl` combining the filter form with active filter values. This example is simplified from the buran template. The filter form includes a mobile-specific header (close button + title), a scrollable body with attribute sections, and submit/reset buttons at the bottom:

::: v-pre

```twig
{# _filter.tpl #}
<i:filter-form name="default" class="filter" auto-scroll="false">
    <div class="filter__in">
        {# Mobile-only header with close button #}
        <p class="filter__header hide-for-medium">
            <a class="toggle-filter" role="button" aria-label="{% trans 'template.close' %}">
                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-cross') }}"></use></svg>
            </a>
            <strong>{% trans 'template.filter.headline' %}</strong>
        </p>

        {# Scrollable filter body with attribute sections #}
        <div class="filter__body scrollbox">
            {% for attribute in attributes %}
                <div class="filter-section filter-section--{{ attribute.id }}">
                    <i:filter-attribute attribute="attribute" checkbox-class="spec-check">
                        {# "Show more" link -- only displayed when values are hidden #}
                        {# %n is replaced with the count of hidden values #}
                        <a data-role="show-more" class="filter-more">template.filter.more (%n)</a>
                    </i:filter-attribute>
                </div>
            {% endfor %}
        </div>

        {# Submit and reset buttons #}
        <div class="filter-buttons">
            <button type="submit" class="button">
                {% trans 'template.filter.submit-button' %}
            </button>
            {# data-role="reset" wrapper is only visible when a filter is active #}
            <div data-role="reset">
                <a data-role="reset">{% trans 'template.filter.reset-button' %}</a>
            </div>
        </div>
    </div>
</i:filter-form>

{# Active filter values -- displays selected filters with individual remove links #}
{# Each value.url removes that single filter value; resetUrl clears all filters #}
<i:filter-values name="default" class="filter-active">
    <div class="filter-active__in">
        <a href="{{ resetUrl }}" class="reset-filter">
            <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-cross') }}"></use></svg>
            {% trans 'template.filter.reset-button' %}
        </a>
        {% for value in values %}
            <a href="{{ value.url }}" class="filter-active__value">
                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-cross') }}"></use></svg>
                {{ value.name }}
            </a>
        {% endfor %}
    </div>
</i:filter-values>
```

:::

The `data-role="reset"` wrapper is only visible when a filter is active. The `data-role="show-more"` / `data-role="show-less"` links toggle automatically; their expanded/collapsed state persists in LocalStorage. On mobile, the filter typically opens as a slide-in panel triggered by a `toggle-filter` button in the listing page.

## Integration with Listing

The filter connects to a product listing through `i:filter-placeholder` and `i:filter-placeholder-values` placed inside `i:list-container`. Here is the buran `vypis.tpl` (category listing page) simplified to show how all components wire together -- the filter form, sort dropdown, active filter pills, product grid, and multiple pagination slots:

::: v-pre

```twig
{# vypis.tpl (category listing page) #}
<h1>{{ this.nazev }}</h1>

<i:list-container type="product" class="main-listing">

    {# Mobile filter toggle button (opens the filter as a slide-in panel) #}
    <div class="hide-for-medium">
        <a class="toggle-filter" role="button" aria-label="{% trans 'template.filter' %}">
            <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-filter') }}"></use></svg>
            <span>{% trans 'template.filter.all-filters' %}</span>
        </a>
    </div>

    {# Filter form placeholder -- renders _filter.tpl content here #}
    <i:filter-placeholder name="default" config="default" always-collapsed />

    {# Sort dropdown (defined in _listing.tpl as i:list-pagination name="sort") #}
    <div data-role="pagination" data-name="sort"></div>

    {# Result count (defined in _listing.tpl as i:list-pagination name="numbers") #}
    <div data-role="pagination" data-name="numbers"></div>

    {# Grid style toggle (defined in _listing.tpl as i:list-pagination name="grid") #}
    <div data-role="pagination" data-name="grid"></div>

    <hr />

    {# Active filter pills with remove links -- must NOT be wrapped in a conditional! #}
    <i:filter-placeholder-values name="default" config="default" />

    {# Empty state message #}
    <div data-role="empty"></div>

    {# Product grid #}
    <div data-role="list" class="listing"></div>

    {# Bottom pagination area with multiple named sections #}
    <div class="pagination">
        <div data-role="pagination" data-name="scroll"></div>
        <div data-role="pagination" data-name="pages"></div>
        <div data-role="pagination" data-name="add"></div>
        <div data-role="pagination" data-name="numbers"></div>
    </div>

</i:list-container>
```

:::

**Key points:**

* `i:filter-placeholder` renders the filter form (defined in `_filter.tpl`) inside the listing container. The `config` attribute refers to the filter group code configured in the admin panel.
* `i:filter-placeholder-values` renders the active filter selections with remove links (defined by `i:filter-values` in `_filter.tpl`). It must **not** be wrapped in a conditional -- it renders as an empty div when no filter is active and appears dynamically during AJAX filtering.
* The `name` attribute on both placeholders must match the `name` used in `i:filter-form` and `i:filter-values` in `_filter.tpl`.
* The `always-collapsed` attribute on `i:filter-placeholder` collapses all filter groups regardless of the admin panel settings.
* Multiple `data-role="pagination"` elements with different `data-name` values can coexist in the same container. Each renders the corresponding `i:list-pagination` definition from `_listing.tpl`. The same `data-name` can appear multiple times (e.g. `numbers` at the top and bottom).
* On mobile, the `.toggle-filter` button opens the filter panel (styled as a slide-in overlay). The close button inside the filter form (see [Complete Filter Template](#complete-filter-template)) dismisses it.

For more about the [listing components](/list) (list-item definitions, pagination variants, source patterns) used alongside filters.

## Available CSS classes

### Flags

* **filter-flag-in-stock** - in stock
* **filter-flag-new** - new arrival
* **filter-flag-promo** - promotion
* **filter-flag-discount** - discounted

---

---
url: /user.md
---
# Registered Customers

## Login

Form for entering email and password for login. The form has automatic HTML5 validation.

```twig
{# shorthand notation #}
<i:login>
    <input data-role="email" data-label="Váš email">
    <input data-role="password" data-label="Vaše heslo">
    <button data-role="submit">Přihlásit</button>
</i:login>

{# separate label notation #}
<i:login>
    <label for="role:email">Váš email</label>
    <input data-role="email">
    <label for="role:password">Vaše heslo</label>
    <input data-role="password">
    <button data-role="submit">Přihlásit</button>
</i:login>
```

```html
<!-- output - subject to change! -->
<form action="/_login" method="post">
    <label for="email_snj554hj">Váš email</label>
    <input type="email" id="email_snj554hj" required>

    <label for="password_snj554hj">Vaše heslo</label>
    <input type="email" id="password_snj554hj" required>

    <button type="submit">Přihlásit</button>
</form>
```

## External-login

Buttons for logging in via external services (Facebook, Seznam, ...). The available services change based on the shop's configuration, so the template must account for a variable number of buttons.

**Attributes of a\[data-role="button"]**

| Attribute | Value | Description |
|---|---|---|
| button-img | url | button image URL |
| button-text | string | button text |
| class | string | CSS class for the button |

```twig
{# universal rendering with default appearance #}
<i:external-login>
    {% for service in availableExternalLoginServices() %}
        <a href="{{ service }}" data-role="button" ></a>
    {% endfor %}
    <div data-role="terms" ></div>
</i:external-login>

{# custom appearance for a specific service, default for the rest #}
<i:external-login>
    {% for service in availableExternalLoginServices() %}
        {% if service == 'facebook' %}
            <a href="{{ service }}" data-role="button" button-img="/images/facebook-button.png" class="facebook_login" ></a>
        {% else %}
            <a href="{{ service }}" data-role="button" ></a>
        {% endif %}
    {% endfor %}
    <div data-role="terms" ></div>
</i:external-login>
```

## Password reset

Form for entering a new password. The link to this form comes from an email (see password reset request).
The form has automatic HTML5 validation. When the jquery-validation plugin is enabled, it automatically binds to the form.

```twig
{# shorthand notation #}
<i:password-reset>
    <input data-role="password" data-label="Nové heslo">
    <input data-role="password_again" data-label="Nové heslo (znovu)">
    <button data-role="submit">Nastavit heslo</button>
</i:password-reset>

{# separate label notation #}
<i:password-reset>
    <label for="role:password">Nové heslo</label>
    <input data-role="password">

    <label for="role:password_again">Nové heslo (znovu)</label>
    <input data-role="password_again">

    <button data-role="submit">Nastavit heslo</button>
</i:password-reset>
```

```html
<!-- output - subject to change! -->
<form action="/_password-reset" method="post">
    <label for="password_snj554hj">Nové heslo</label>
    <input name="password" type="password" id="password_snj554hj" required>

    <label for="password_snj554hj">Nové heslo (znovu)</label>
    <input name="password_again" type="password" id="password_again_snj554hj" required>

    <button type="submit">Nastavit heslo</button>
</form>
```

## Password reset request

Form for entering an email address to send a password reset link. The form has automatic HTML5 validation.
When the jquery-validation plugin is enabled, it automatically binds to the form.

```twig
{# shorthand notation #}
<i:password-reset-request>
    <input data-role="email" data-label="Váš email">
    <button data-role="submit">Resetovat heslo</button>
</i:password-reset-request>

{# separate label notation #}
<i:password-reset-request>
    <label for="role:email">Váš email</label>
    <input data-role="email">
    <button data-role="submit">Resetovat heslo</button>
</i:password-reset-request>
```

```html
<!-- output - subject to change! -->
<form action="/_password-reset" method="post">
    <label for="email_snj554hj">Váš email</label>
    <input type="email" id="email_snj554hj" required data-msg-required="Vyplňte váš email">
    <button type="submit">Resetovat heslo</button>
</form>
```

## Signup

Complete registration form.

**Form fields for user-signup**

| data-role | Required | Description |
|---|---|---|
| **email** | **yes** | login email address |
| **password** | **yes** | password |
| **password\_again** | **yes** | password confirmation |
| phone | *no* | phone number |
| first\_name | *no* | first name |
| last\_name | *no* | last name |
| company | *no* | company name |
| cin | *no* | company identification number (CIN) |
| vatid | *no* | VAT identification number |
| street | *no* | delivery street and house number |
| city | *no* | delivery city |
| zip | *no* | delivery postal code |
| region | *no* | delivery region (state, province) |
| country | *no* | delivery country |
| billing\_phone | *no* | billing phone number |
| billing\_first\_name | *no* | billing first name |
| billing\_last\_name | *no* | billing last name |
| billing\_company | *no* | billing company name |
| billing\_cin | *no* | billing CIN |
| billing\_vatid | *no* | billing VAT ID |
| billing\_street | *no* | billing street and house number |
| billing\_city | *no* | billing city |
| billing\_zip | *no* | billing postal code |
| billing\_region | *no* | billing region (state, province) |
| billing\_country | *no* | billing country |
| newsletter | *no* | subscribe to newsletter |

* When **use-billing** is used, fields wrapped in **billing-fields** are automatically hidden.
* When the *jQuery-validation* plugin is active, it automatically binds to the form.
* Values (previously filled in or from the user profile) are populated automatically.
* The country list is based on configuration and the default selection is determined by GeoIP.

```twig
<i:user-signup>
    <fieldset data-role="login">
        <legend>Přihlašovací údaje</legend>

        <input data-role="email" data-label="email">
        <input data-role="password" data-label="heslo">
        <input data-role="password_again" data-label="heslo (znovu)">
    </fieldset>

    <fieldset data-role="delivery">
        <legend>Dodací adresa</legend>

        <input data-role="phone" data-label="telefon">
        <input data-role="first_name" data-label="křestní jméno">
        <input data-role="last_name" data-label="příjmení">
        <input data-role="company" data-label="firma">
        <input data-role="cin" data-label="IČ">
        <input data-role="vatid" data-label="DIČ">
        <input data-role="street" data-label="ulice a č.p.">
        <input data-role="city" data-label="město">
        <input data-role="zip" data-label="PSČ">
        <select data-role="country" data-label="země" ></select>
    </fieldset>

    <fieldset data-role="billing">
        <legend>Fakturační adresa</legend>

        <input data-role="use-billing" data-label="fakturovat na jinou adresu">

        <div data-role="billing-fields"> {# "billing-fields" is only used together with "use-billing" #}
            <input data-role="billing-phone" data-label="telefon">
            <input data-role="billing-first_name" data-label="křestní jméno">
            <input data-role="billing-last_name" data-label="příjmení">
            <input data-role="billing-company" data-label="firma">
            <input data-role="billing-cin" data-label="IČ">
            <input data-role="billing-vatid" data-label="DIČ">
            <input data-role="billing-street" data-label="ulice a č.p.">
            <input data-role="billing-city" data-label="město">
            <input data-role="billing-zip" data-label="PSČ">
            <select data-role="billing-country" data-label="země" ></select>
        </div>
    </fieldset>

    <input data-role="newsletter" data-label="odebírat newsletter">

    <button data-role="submit">Registrovat</button>
</i:user-signup>
```

### Hiding company fields

By adding a checkbox, company fields can be automatically hidden -- no additional JavaScript is needed.

If *use-company* is placed inside the *delivery* or *billing* fieldset, it applies only to that address's fields. If placed outside, it applies to both at once.

*company-fields* can be used multiple times within a single fieldset -- for example, on table rows.

```twig
<i:user-signup>
    <input data-role="use-company" data-label="nakupuji na firmu">

    <fieldset data-role="delivery">
        ...
        <div data-role="company-fields">
            <input data-role="company" data-label="firma">
            <input data-role="cin" data-label="IČ">
            <input data-role="vatid" data-label="DIČ">
        </div>
    </fieldset>

    <fieldset data-role="billing">
        ...
        <table>
            ...
            <tr data-role="company-fields"><td>
                <input data-role="billing-company" data-label="firma">
            </td></tr>
            <tr data-role="company-fields"><td>
                <input data-role="billing-cin" data-label="IČ">
            </td></tr>
            <tr data-role="company-fields"><td>
                <input data-role="billing-vatid" data-label="DIČ">
            </td></tr>
        </table>
    </fieldset>
</i:user-signup>
```

---

---
url: /repositories.md
---
# Repositories (entity listings)

```twig
{% set newProducts = repository.product.findBy({ 'new': true, 'limit': 10 }) %}
Displayed: {{ newProducts|length }} {# outputs 0 to 10 #}
Total new: {{ newProducts.totalCount }} {# total count of new products - WARNING! Creates an extra database query, which can be more expensive than listing the first X items #}
```

## actuality

```twig
{% for actuality in repository.actuality.findBy({ ... }) %}
   {{actuality.id}}
{% endfor %}

{{ repository.actuality.findOneBy({  }) }}

{{ repository.actuality.count({  }) }}

{% if repository.actuality.count({  }) %}  {% endif %}
```

**Repository arguments for actuality**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| sort | newest, oldest | Sorting |
| limit | int | Maximum number of results |

## article

```twig
{% for article in repository.article.findBy({ ... }) %}
   {{article.id}}
{% endfor %}

{{ repository.article.findOneBy({  }) }}

{{ repository.article.count({  }) }}

{% if repository.article.count({  }) %}  {% endif %}
```

**Repository arguments for article**

| Argument | Type | Description |
|---|---|---|
| id | int, array | Article ID |
| skipId | int, array | Exclude article ID |
| topic | int | Article topic |
| author | int | Article author (id) |
| skipTopic | int, array | Exclude article topic |
| product | int | Product articles |
| category | int | Category articles |
| search | string | Contains phrase |
| sort | random, randomForVisitorDaily, randomVisitorHourly, name, newest, oldest | Sorting |
| limit | int | Maximum number of results |

## attribute

```twig
{% for attribute in repository.attribute.findBy({ ... }) %}
   {{attribute.id}}
{% endfor %}

{{ repository.attribute.findOneBy({  }) }}

{{ repository.attribute.count({  }) }}

{% if repository.attribute.count({  }) %}  {% endif %}
```

**Repository arguments for attribute**

| Argument | Type | Description |
|---|---|---|
| id | int, array | Attribute ID |
| skipId | int, array | Exclude attribute ID |
| type | int, array | Attribute type |
| section | int, array | Section |
| meaning | size, color, gender, material, pattern, age\_group, unknown | Meaning |
| namespace | product, store, article | Namespace |
| limit | int | Maximum number of results |

## attributeValue

```twig
{% for attributeValue in repository.attributeValue.findBy({ ... }) %}
   {{attributeValue.id}}
{% endfor %}

{{ repository.attributeValue.findOneBy({  }) }}

{{ repository.attributeValue.count({  }) }}

{% if repository.attributeValue.count({  }) %}  {% endif %}
```

**Repository arguments for attributeValue**

| Argument | Type | Description |
|---|---|---|
| id | int, array | Attribute value ID |
| skipId | int, array | Exclude attribute value ID |
| attribute | int, array | Attribute type |
| limit | int | Maximum number of results |

## author

```twig
{% for author in repository.author.findBy({ ... }) %}
   {{author.id}}
{% endfor %}

{{ repository.author.findOneBy({  }) }}

{{ repository.author.count({  }) }}

{% if repository.author.count({  }) %}  {% endif %}
```

**Repository arguments for author**

| Argument | Type | Description |
|---|---|---|
| id | int, array | Author ID |
| limit | int | Maximum number of results |

## banner

```twig
{% for banner in repository.banner.findBy({ ... }) %}
   {{banner.id}}
{% endfor %}

{{ repository.banner.findOneBy({  }) }}

{{ repository.banner.count({  }) }}

{% if repository.banner.count({  }) %}  {% endif %}
```

**Repository arguments for banner**

| Argument | Type | Description |
|---|---|---|
| id | int, array | Banner ID |
| sectionId | int | Section ID |
| sectionCode | string | Section code |
| category | int | Category ID (banners assigned to the category) |
| brand | int | Brand ID (banners assigned to the brand) |
| sort | random, priority | Sorting |
| limit | int | Maximum number of results |

## brand

```twig
{% for brand in repository.brand.findBy({ ... }) %}
   {{brand.id}}
{% endfor %}

{{ repository.brand.findOneBy({  }) }}

{{ repository.brand.count({  }) }}

{% if repository.brand.count({  }) %}  {% endif %}
```

**Repository arguments for brand**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| important | bool | Important |
| image | bool | Has image |
| search | string | Search by name |
| category | int | Category |
| sort | random, priority, name | Sorting |
| limit | int | Maximum number of results |

## category

```twig
{% for category in repository.category.findBy({ ... }) %}
   {{category.id}}
{% endfor %}

{{ repository.category.findOneBy({  }) }}

{{ repository.category.count({  }) }}

{% if repository.category.count({  }) %}  {% endif %}
```

**Repository arguments for category**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| parent | int | Parent category ID |
| important | bool | Important |
| active | bool | Active only (default true) |
| empty | bool | Empty? |
| alias | bool | Is alias of another category? |
| search | string | Search by name |
| brand | int | Only categories with products of the brand |
| level | int | Level (starts from 0) |
| path | string | All subcategories of the path |
| maximumLevel | int | Maximum level (inclusive; starts from 0) |
| sort | random, priority, name | Sorting |
| limit | int | Maximum number of results |

## comment

```twig
{% for comment in repository.comment.findBy({ ... }) %}
   {{comment.id}}
{% endfor %}

{{ repository.comment.findOneBy({  }) }}

{{ repository.comment.count({  }) }}

{% if repository.comment.count({  }) %}  {% endif %}
```

**Repository arguments for comment**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| for | Product, Category, Article | Comment subject (product, article, ...) |
| structured | bool | Output as structured tree |
| limit | int | Maximum number of results |

## compatibilityAttribute

```twig
{% for compatibilityAttribute in repository.compatibilityAttribute.findBy({ ... }) %}
   {{compatibilityAttribute.id}}
{% endfor %}

{{ repository.compatibilityAttribute.findOneBy({  }) }}

{{ repository.compatibilityAttribute.count({  }) }}

{% if repository.compatibilityAttribute.count({  }) %}  {% endif %}
```

**Repository arguments for compatibilityAttribute**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| sort | priority | Sorting |
| limit | int | Maximum number of results |

## compatibilityAttributeValue

```twig
{% for compatibilityAttributeValue in repository.compatibilityAttributeValue.findBy({ ... }) %}
   {{compatibilityAttributeValue.id}}
{% endfor %}

{{ repository.compatibilityAttributeValue.findOneBy({  }) }}

{{ repository.compatibilityAttributeValue.count({  }) }}

{% if repository.compatibilityAttributeValue.count({  }) %}  {% endif %}
```

**Repository arguments for compatibilityAttributeValue**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| attribute | int | Compatibility attribute ID |
| limit | int | Maximum number of results |

## dynamicCategory

```twig
{% for dynamicCategory in repository.dynamicCategory.findBy({ ... }) %}
   {{dynamicCategory.id}}
{% endfor %}

{{ repository.dynamicCategory.findOneBy({  }) }}

{{ repository.dynamicCategory.count({  }) }}

{% if repository.dynamicCategory.count({  }) %}  {% endif %}
```

**Repository arguments for dynamicCategory**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| category | int | Category ID |
| sort | name | Sorting |
| limit | int | Maximum number of results |

## label

```twig
{% for label in repository.label.findBy({ ... }) %}
   {{label.id}}
{% endfor %}

{{ repository.label.findOneBy({  }) }}

{{ repository.label.count({  }) }}

{% if repository.label.count({  }) %}  {% endif %}
```

**Repository arguments for label**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| sort | priority | Sorting |
| limit | int | Maximum number of results |

## loyaltyLevel

```twig
{% for loyaltyLevel in repository.loyaltyLevel.findBy({ ... }) %}
   {{loyaltyLevel.id}}
{% endfor %}

{{ repository.loyaltyLevel.findOneBy({  }) }}

{{ repository.loyaltyLevel.count({  }) }}

{% if repository.loyaltyLevel.count({  }) %}  {% endif %}
```

**Repository arguments for loyaltyLevel**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| type | invoice, receipt | Level type |
| limit | int | Maximum number of results |

## enum

```twig
{% for enum in repository.enum.findBy({ ... }) %}
   {{enum.id}}
{% endfor %}

{{ repository.enum.findOneBy({  }) }}

{{ repository.enum.count({  }) }}

{% if repository.enum.count({  }) %}  {% endif %}
```

**Repository arguments for enum**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| meaning | size, color, gender, material, pattern, age\_group, unknown | Meaning |
| sort | name | Sorting |
| limit | int | Maximum number of results |

## enumValue

```twig
{% for enumValue in repository.enumValue.findBy({ ... }) %}
   {{enumValue.id}}
{% endfor %}

{{ repository.enumValue.findOneBy({  }) }}

{{ repository.enumValue.count({  }) }}

{% if repository.enumValue.count({  }) %}  {% endif %}
```

**Repository arguments for enumValue**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| enum | int | Enum ID |
| sort | name, priority | Sorting |
| limit | int | Maximum number of results |

## product

```twig
{% for product in repository.product.findBy({ ... }) %}
   {{product.id}}
{% endfor %}

{{ repository.product.findOneBy({  }) }}

{{ repository.product.count({  }) }}

{% if repository.product.count({  }) %}  {% endif %}
```

**Repository arguments for product**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| skipId | int, array | Skip product ID |
| category | int, array | Category ID |
| subcategories | bool | Include products from subcategories |
| skipCategory | int | Skip main category ID |
| inStock | bool | Only products in stock |
| sellout | bool | Clearance sale |
| bestseller | bool | Bestseller |
| discount | bool | On sale |
| promo | bool | Promo |
| promoCategory | int | Promo for category |
| new | bool | New arrival |
| viewed | bool | Recently viewed products |
| wished | bool | Wishlist |
| image | bool | Products with image |
| recommendHomepage | bool | Recommend products for user homepage |
| recommendCart | bool | Recommend products for user cart |
| recommendSimilar | int | Recommend similar products for product ID |
| recommendCrossSell | int | Recommend cross-sell products for product ID |
| recommendDefault | int | Recommend products for product ID |
| file | bool, string | Products with file (can filter file type - manual, etc.) |
| video | bool | Products with video |
| search | string | Contains phrase |
| priceFrom | float | Minimum price |
| priceTo | float | Maximum price |
| brand | int, array | Brand ID |
| article | int | Article ID |
| label | int, array | Label ID |
| skipLabel | int, array | Excluded label ID |
| customersAlsoBought | int | Product ID to find frequently bought together items |
| relevant | int, Product | Related products for product ID |
| accessory | int, Product | Accessories for product ID |
| similar | int, Product | Similar products for product ID |
| bundleContainsProduct | Product | Bundles containing the product |
| enums | array | Array of enums with value IDs |
| attributes | array | Array of attributes with value IDs |
| boolAttributes | array | Array of attribute IDs |
| sort | priority, newest, random, randomForVisitorDaily, randomForVisitorHourly, lastStockIn, name, price, priceDesc, bestseller | Sorting |
| limit | int | Maximum number of results |

## review

```twig
{% for review in repository.review.findBy({ ... }) %}
   {{review.id}}
{% endfor %}

{{ repository.review.findOneBy({  }) }}

{{ repository.review.count({  }) }}

{% if repository.review.count({  }) %}  {% endif %}
```

**Repository arguments for review**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| type | order, product | Review type |
| rel | int | Reviewed object ID (product) |
| text | bool | Only reviews with text |
| anyText | bool | Only reviews with description, pros or cons |
| minimalRating | int | Only with higher rating |
| sort | oldest, newest | Sorting |
| limit | int | Maximum number of results |

## storageCenter

```twig
{% for storageCenter in repository.storageCenter.findBy({ ... }) %}
   {{storageCenter.id}}
{% endfor %}

{{ repository.storageCenter.findOneBy({  }) }}

{{ repository.storageCenter.count({  }) }}

{% if repository.storageCenter.count({  }) %}  {% endif %}
```

**Repository arguments for storageCenter**

| Argument | Type | Description |
|---|---|---|
| limit | int | Maximum number of results |

## storageRoom

```twig
{% for storageRoom in repository.storageRoom.findBy({ ... }) %}
   {{storageRoom.id}}
{% endfor %}

{{ repository.storageRoom.findOneBy({  }) }}

{{ repository.storageRoom.count({  }) }}

{% if repository.storageRoom.count({  }) %}  {% endif %}
```

**Repository arguments for storageRoom**

| Argument | Type | Description |
|---|---|---|
| limit | int | Maximum number of results |

## store

```twig
{% for store in repository.store.findBy({ ... }) %}
   {{store.id}}
{% endfor %}

{{ repository.store.findOneBy({  }) }}

{{ repository.store.count({  }) }}

{% if repository.store.count({  }) %}  {% endif %}
```

**Repository arguments for store**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| attributeValue | int, array | Attribute values |
| pickup | bool | Pickup available? |
| country | string, array | Country code |
| closestToPoint | array | Sort from closest to point \[latitude, longitude] |
| sort | priority, name | Sorting |
| limit | int | Maximum number of results |

## textPage

```twig
{% for textPage in repository.textPage.findBy({ ... }) %}
   {{textPage.id}}
{% endfor %}

{{ repository.textPage.findOneBy({  }) }}

{{ repository.textPage.count({  }) }}

{% if repository.textPage.count({  }) %}  {% endif %}
```

**Repository arguments for textPage**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| code | string, array | Code |
| limit | int | Maximum number of results |

## articleTopic

```twig
{% for articleTopic in repository.articleTopic.findBy({ ... }) %}
   {{articleTopic.id}}
{% endfor %}

{{ repository.articleTopic.findOneBy({  }) }}

{{ repository.articleTopic.count({  }) }}

{% if repository.articleTopic.count({  }) %}  {% endif %}
```

**Repository arguments for articleTopic**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| sort | name, priority | Sorting |
| limit | int | Maximum number of results |

## variant

```twig
{% for variant in repository.variant.findBy({ ... }) %}
   {{variant.id}}
{% endfor %}

{{ repository.variant.findOneBy({  }) }}

{{ repository.variant.count({  }) }}

{% if repository.variant.count({  }) %}  {% endif %}
```

**Repository arguments for variant**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| product | int | Product ID |
| enumValue | int, array | Enum value ID |
| sort | name, priority, price | Sorting |
| limit | int | Maximum number of results |

## video

```twig
{% for video in repository.video.findBy({ ... }) %}
   {{video.id}}
{% endfor %}

{{ repository.video.findOneBy({  }) }}

{{ repository.video.count({  }) }}

{% if repository.video.count({  }) %}  {% endif %}
```

**Repository arguments for video**

| Argument | Type | Description |
|---|---|---|
| id | int, array | ID |
| type | category, product, other | Video type |
| sort | newest, oldest, priority | Sorting |
| limit | int | Maximum number of results |

---

---
url: /sftp.md
---
# SFTP

SFTP access must be activated through support. An account will be created for you and tpltests will then be accessible via SFTP, allowing you to edit templates through your own editor that uploads changed files online.

## First-Time Setup

The following steps only need to be done once for your first template and for each computer where you want to use SFTP.

### Generating a Key

On all platforms (macOS, Linux, Windows 10+) use `ssh-keygen`:

```bash
ssh-keygen -f ~/cesta-klice -t rsa -b 4096
```

*If you already have a key generated for other purposes, you can reuse it — skip the following steps and just send us the public key.*

Send the generated public key (the file `~/cesta-klice.pub` — "cesta-klice" means "key-path") to support for activation. Store the private key (without the `.pub` extension) in a safe location where it will not be shared or backed up — it is far easier to generate a new key later than to deal with a compromised key.

**Do not send the private key anywhere** (e.g. by email) and do not share it with anyone.

::: details PuTTYgen (older Windows versions without ssh-keygen)
On older Windows versions (before Windows 10) you can use [PuTTYgen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html):

1. Set the key length to 4096 and click *Generate*
2. Move the mouse inside the window until key generation is complete
3. Optionally set a passphrase for added security
4. Save the key using the *Save private key* button
5. Copy the text from the upper box and send it to support
   :::

### PhpStorm Configuration

Configuration for other editors follows the same principle, only the menu location will differ.

Open the template folder and in the menu find *Tools / Deployment / Configuration*.

![](img/sftp/phpstorm-1.png)

Add a new **SFTP** server named **simplia-template** (the name matters so that project presets work correctly when using multiple templates). The server address is **sftp.simpliashop.cz**, port **2222**, and your login was provided by support.

For **Authentication** use **key pair** and locate where you stored the key (generated above).

Leave the **visible only for this project** checkbox unchecked, so you do not need to configure the connection separately for each template.

![](img/sftp/phpstorm-2.png)

---

---
url: /social.md
---
# Social Components

## Facebook Share button

Button for sharing on Facebook (see [documentation](https://developers.facebook.com/docs/plugins/share-button)). The **href** attribute contains the object to share on Facebook. You do not enter a URL directly -- instead you provide the object, and the URL is generated automatically.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of facebook-share**

| Attribute | Value | Description |
|---|---|---|
| **href** | *object* | object to share |
| **layout** | box\_count, button\_count, button, link, icon\_link, icon | appearance |

```twig
<i:facebook-share href="zbozi" layout="button_count" /> {# minimal notation #}
<i:facebook-share href="zbozi" layout="button_count" class="button_facebook" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<div class="fb-share-button" data-href="https://example.org/category/product-link" data-layout="button_count"></div>

<!-- with custom class -->
<div class="fb-share-button button_facebook" data-href="https://example.org/category/product-link" data-layout="button_count"></div>
```

## Facebook Like button

Button for like/recommend on Facebook (see [documentation](https://developers.facebook.com/docs/plugins/like-button)). The **href** attribute contains the object to share on Facebook. You do not enter a URL directly -- instead you provide the object, and the URL is generated automatically.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

The *href* attribute can optionally contain a direct Facebook page URL instead of an object (i.e., it must start with *https://www.facebook.com/...*). However, instead of this option we recommend using the Page Plugin (below).

**Attributes of facebook-like**

| Attribute | Value | Description |
|---|---|---|
| **href** | *object* | object to share |
| **layout** | standard, button\_count, button, box\_count | appearance |
| action | like/recommend | button label |
| colorscheme | light/dark | box appearance |
| share | true/false | add a "share" button |
| show-faces | true/false | display profile pictures |
| small-header | true/false | display a smaller header |
| width | *number* | width |
| lazy | true/false | browser's lazy-loading, **default = "true"** |

```twig
<i:facebook-like href="zbozi" layout="standard" /> {# minimal notation #}
<i:facebook-like href="zbozi" layout="standard" class="button_facebook" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<div class="fb-like" data-href="https://example.org/category/product-link" data-layout="standard"></div>

<!-- with custom class -->
<div class="fb-like button_facebook" data-href="https://example.org/category/product-link" data-layout="standard"></div>
```

## Facebook Follow button

Button for following on Facebook (see [documentation](https://developers.facebook.com/docs/plugins/follow-button)). The **href** attribute contains the page/profile URL.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of facebook-follow**

| Attribute | Value | Description |
|---|---|---|
| **href** | *object* | object to share |
| **layout** | standard, button\_count, box\_count | appearance |
| colorscheme | light/dark | box appearance |
| size | large/small | box appearance |
| show-faces | true/false | display profile pictures |
| width | *number* | width |

```twig
<i:facebook-follow href="https://www.facebook.com/simplia.cz" layout="standard" /> {# minimal notation #}
<i:facebook-follow href="https://www.facebook.com/simplia.cz" layout="standard" class="button_facebook" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<div class="fb-follow" data-href="https://www.facebook.com/simplia.cz" data-layout="standard"></div>

<!-- with custom class -->
<div class="fb-follow button_facebook" data-href="https://www.facebook.com/simplia.cz" data-layout="standard"></div>
```

## Facebook Page Plugin

A box displaying the shop's Facebook page (see [documentation](https://developers.facebook.com/docs/plugins/page-plugin)). The **href** attribute contains the Facebook page URL -- only the base URL without additional parameters.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of facebook-page**

| Attribute | Value | Description |
|---|---|---|
| **href** | *string* | Facebook page URL |
| href-config | *string* | slave config variable name for *href* |
| width | *number* | width (180-500) |
| height | *number* | height (130+) |
| hide-cover | true/false | hide cover |
| show-facepile | true/false | display profile pictures |
| show-posts | true/false | display page posts |
| lazy | true/false | browser's lazy-loading, **default = "true"** |

```twig
<i:facebook-page href="https://www.facebook.com/simplia" /> {# minimal notation #}
<i:facebook-page href="https://www.facebook.com/simplia" class="button_facebook" /> {# custom class (any) #}
<i:facebook-page href-config="facebookUrl" /> {# URL is populated from the config variable facebookUrl #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<div class="fb-page" data-href="https://www.facebook.com/simplia"></div>

<!-- with custom class -->
<div class="fb-page button_facebook" data-href="https://www.facebook.com/simplia"></div>
```

## Facebook Comments

Facebook comments (see [documentation](https://developers.facebook.com/docs/plugins/comments)). The **href** attribute contains the object to share on Facebook. You do not enter a URL directly -- instead you provide the object, and the URL is generated automatically.

**Attributes of facebook-comments**

| Attribute | Value | Description |
|---|---|---|
| **href** | *object* | object to share |
| width | *number*, 100% | width |
| colorscheme | light/dark | box appearance |
| order-by | social, reverse\_time, time | sort order |
| num-posts | *number* | number of posts |
| mobile | true/false | simplified display |

```twig
<i:facebook-comments href="zbozi" /> {# minimal notation #}
<i:facebook-comments href="zbozi" class="comments_facebook" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<div class="fb-comments" data-href="https://example.org/category/product-link" ></div>

<!-- with custom class -->
<div class="fb-comments comments_facebook" data-href="https://example.org/category/product-link" ></div>
```

## Facebook Message Us

"Message Us" button (see [documentation](https://developers.facebook.com/docs/messenger-platform/plugin-reference/message-us)). **The App Id and Page Id must be configured in the shop settings for the button to display.**

**Attributes of facebook-message-us**

| Attribute | Value | Description |
|---|---|---|
| color | blue/white | button appearance |
| size | standard/large/xlarge | button size |

```twig
<i:facebook-message-us /> {# minimal notation #}
<i:facebook-message-us class="message_facebook" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<div class="fb-messengermessageus" messenger_app_id="APP_ID" page_id="PAGE_ID"> </div>
```

## Facebook Login button

Button for logging in via Facebook. The configured GDPR text is automatically appended below the button.

**Attributes of facebook-login**

| Attribute | Value | Description |
|---|---|---|
| button-img | url | button image URL |
| button-text | string | button text |
| button-class | string | login form CSS class |

```twig
<i:facebook-login /> {# minimal notation #}
<i:facebook-login button-img="/images/facebook-button.png" class="facebook_login" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->
<div>
    <a href="https://facebook.com/xxx" class="global-facebook-login-button"><img src="/images/facebook-button.png"/></a>
    <div>
        <p class="global-gdpr-form-description">Informace o zpracování najdete <a href="">tady</a></p>
    </div>
</div>
```

::: info Note on the Twitter to X rebrand
The `i:twitter-share` and `i:twitter-follow` components retain their original names from before the rebrand to X. Use the existing `i:twitter-*` names in templates.
:::

## Twitter Share

Button for sending a tweet (see [documentation](https://dev.twitter.com/web/tweet-button)). The **href** attribute contains the object to share on Twitter. You do not enter a URL directly -- instead you provide the object, and the URL is generated automatically.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of twitter-share**

| Attribute | Value | Description |
|---|---|---|
| **href** | *object* | object to share |
| size | medium, large | button size |
| count | none, horizontal, vertical | display share count |
| via | *string* | account |
| text | *string* | tweet text |
| related | *string* | related accounts |

```twig
<i:twitter-share href="zbozi" /> {# minimal notation #}
<i:twitter-share href="zbozi" class="button_twitter" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<a class="twitter-share-button" data-url="https://example.org/link" href="https://twitter.com/share?url=https%3A%2F%2Fexample.org%2Flink" data-text="example name" data-lang="cs">Tweet</a>

<!-- with custom class -->
<a class="twitter-share-button button_twitter" data-url="https://example.org/link" href="https://twitter.com/share?url=https%3A%2F%2Fexample.org%2Flink" data-text="example name" data-lang="cs">Tweet</a>
```

## Twitter Follow

Button for following a Twitter account (see [documentation](https://dev.twitter.com/web/follow-button)). The **href** attribute contains the account name.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of twitter-follow**

| Attribute | Value | Description |
|---|---|---|
| **href** | *string* | account name |
| size | medium, large | button size |
| show-count | true, false | display share count |
| show-screen-name | true, false | display account name |
| align | left, right | alignment |
| width | *number* | width in percent or px |

```twig
<i:twitter-follow href="simplia" /> {# minimal notation #}
<i:twitter-follow href="simplia" class="button_twitter" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<a class="twitter-follow-button" href="https://twitter.com/simplia" data-lang="cs">Follow @simplia</a>

<!-- with custom class -->
<a class="twitter-follow-button button_twitter" href="https://twitter.com/simplia" data-lang="cs">Follow @simplia</a>
```

## Pinterest Share button

Button for sharing on Pinterest.com (see [documentation](https://business.pinterest.com/en/widget-builder#do_pin_it_button)). The **href** attribute contains the object to share on Pinterest. You do not enter a URL directly -- instead you provide the object, and the URL is generated automatically.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of pinterest-share**

| Attribute | Value | Description |
|---|---|---|
| **href** | *object* | object to share |
| type | **rect**, round | button type |
| size | **large**, small | button size |
| color | **red**, gray, white | button color |
| count | **none**, above, beside | share count |
| icon | **true**/false | display icon |

When using the *circular* button type, the share count cannot be displayed and the color cannot be changed.

```twig
<i:pinterest-share href="zbozi" type="rectangular" /> {# minimal notation #}
<i:pinterest-share href="zbozi" type="rectangular" class="button_pinterest" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<a href="//www.pinterest.com/pin/create/button/?url=http%3A%2F%2Fwww.flickr.com%2Fphotos%2Fkentbrew%2F6851755809%2F&media=http%3A%2F%2Ffarm8.staticflickr.com%2F7027%2F6851755809_df5b2051c9_z.jpg&description=Next%20stop%3A%20Pinterest" data-pin-do="buttonPin" data-pin-config="above" data-pin-color="red" data-pin-height="28"><img src="//assets.pinterest.com/images/pidgets/pinit_fg_en_rect_red_28.png" /></a>

<!-- with custom class -->
<a class="button_pinterest" href="//www.pinterest.com/pin/create/button/?url=http%3A%2F%2Fwww.flickr.com%2Fphotos%2Fkentbrew%2F6851755809%2F&media=http%3A%2F%2Ffarm8.staticflickr.com%2F7027%2F6851755809_df5b2051c9_z.jpg&description=Next%20stop%3A%20Pinterest" data-pin-do="buttonPin" data-pin-config="above" data-pin-color="red" data-pin-height="28"><img src="//assets.pinterest.com/images/pidgets/pinit_fg_en_rect_red_28.png" /></a>
```

## Pinterest Follow

Button for following a Pinterest account (see [documentation](https://business.pinterest.com/en/widget-builder#do_follow_me_button)). The **href** attribute contains the account name.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of pinterest-follow**

| Attribute | Value | Description |
|---|---|---|
| **href** | *string* | account name |

```twig
<i:pinterest-follow href="simplia" /> {# minimal notation #}
<i:pinterest-follow href="simplia" class="button_pinterest" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<a  href="https://www.pinterest.com/simplia/" data-pin-do="buttonFollow" >Simplia</a>

<!-- with custom class -->
<a class="button_pinterest" href="https://www.pinterest.com/simplia/" data-pin-do="buttonFollow" >Simplia</a>
```

## Pinterest Profile

Widget for embedding a Pinterest profile (see [documentation](https://business.pinterest.com/en/widget-builder#do_embed_user)). The **href** attribute contains the account name.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of pinterest-profile**

| Attribute | Value | Description |
|---|---|---|
| **href** | *string* | account name |
| image-width | *int* | image width |
| board-width | *int* | widget width |
| board-height | *int* | widget height |

```twig
<i:pinterest-profile href="simplia" /> {# minimal notation #}
<i:pinterest-profile href="simplia" class="button_pinterest" /> {# custom class (any) #}
<i:pinterest-profile href="simplia">Sledujte nás na Pinterest.com!</i:pinterest-profile> {# custom fallback message #}
```

```html
<!-- generated output - subject to change! -->

<a href="https://www.pinterest.com/simplia/" data-pin-do="embedUser" data-pin-scale-width="130" data-pin-scale-height="120" data-pin-board-width="100">Visit Pinterest's profile on Pinterest.</a>
```

## Instagram Follow

Button for following an Instagram account. The **href** attribute contains the account name.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the button is displayed.

**Attributes of instagram-follow**

| Attribute | Value | Description |
|---|---|---|
| **href** | *string* | account name |

```twig
<i:instagram-follow href="simplia" /> {# minimal notation #}
<i:instagram-follow href="simplia" class="button_instagram" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<!-- minimal notation -->
<a  href="https://instagram.com/simplia?ref=badge" data-pin-do="buttonFollow"><img src="//badges.instagram.com/static/images/ig-badge-16.png" alt="Instagram"></a>

<!-- with custom class -->
<a class="button_instagram" href="https://instagram.com/simplia?ref=badge"><img src="//badges.instagram.com/static/images/ig-badge-16.png" alt="Instagram"></a>
```

## Trustpilot

Display the Trustpilot score.

No additional code needs to be added to the template -- the JavaScript is injected automatically on all pages where the widget is displayed.

**Attributes of trustpilot**

| Attribute | Value | Description |
|---|---|---|
| **theme** | *string* | widget appearance |
| **width** | *string* | width (including units or percent) |
| **height** | *string* | height (including units or percent) |

```twig
<i:trustpilot /> {# minimal notation #}
<i:trustpilot height="25px" width="100%" theme="light" class="button_instagram" /> {# custom class (any) #}
```

```html
<!-- generated output - subject to change! -->

<div class="trustpilot-widget" data-locale="en-US" data-template-id="5419b6a8b0d04a076446a9ad" data-businessunit-id="5c4719c7745e98000197e08b" data-style-height="24px" data-style-width="100%" data-theme="light"> <a href="https://www.trustpilot.com/review/gentlemanstore.hu" target="_blank" rel="noopener">Trustpilot</a> </div>
```

---

---
url: /syntax.md
---
# Syntax

Templates use Twig syntax (https://twig.symfony.com/), extended with platform-specific functions. This documentation covers only these extensions. We recommend familiarizing yourself with the base Twig syntax first: https://twig.symfony.com/doc/2.x/templates.html

## Template validity

All templates are processed by a DOM parser, so they must be valid HTML. Crossing tags is not allowed, and all tags opened in one file should be closed in the same file.
Template processing follows the HTML5 specification, so self-closing tags like IMG, INPUT, BR, HR, etc. do not need to be explicitly closed.

A consequence of template parsing can be unexpected behavior — for example, when using DIV inside P:

```twig
{# as written in the template #}
<p> Hello!
    <div>Hi!</div>
</p>
```

Actual output:

```xml
<p> Hello!</p>
<div>Hi!</div>
```

According to the HTML5 specification, a DIV cannot be inside a paragraph, so the paragraph is closed as soon as the parser encounters the DIV.

The following constructs cannot be used in templates:

```twig
<input {%if x%}checked{%endif%}> {# invalid tag #}
<img src="{{iUrl("Objednavka/Kosik")}}"> {# incorrect quotes — use apostrophes in Twig instead #}
```

## Template structure

Some constructs may pass validation but are not recommended. For example, the following is technically valid but can cause problems:

```twig
{# incorrect pattern #}
{%if user %}
    <div class="user">
{%endif%}
{%include this.template %}
{%if user %}
    </div>
{%endif%}
```

Recommended approach:

```twig
{# correct pattern #}
{%if user %}
    <div class="user">
        {%include this.template %}
    </div>
{%else%}
    {%include this.template %}
{%endif%}
```

When you need different structures based on conditions, it is most practical to define the entire structure in one place. For example, keep only conditions in one file and split the template code into macros/files.
The resulting code is significantly more readable and avoids problems during template processing.

## Conditional attributes

Using the *if:* prefix, you can conditionally render an attribute. The attribute value is Twig code (without {{}}) that can contain either just a condition (for use with checked, selected, etc.) or a condition and a value.

```twig
<input if:checked="1==1"> {# output: <input checked> #}
<input if:checked="1==2"> {# output: <input> #}

<div if:class="1==1 ? 'main'"> {# output: <div class="main"> #}
<div if:class="1==2 ? 'main'"> {# output: <div> #}
```

## Twital and the `i:` prefix

Simplia templates use [Twital](https://github.com/goetas/twital) — a Twig extension that allows writing Twig logic directly as XML attributes and custom elements. This keeps templates as valid HTML/XML and makes them easily parseable.

The key concept is the **`i:` prefix** — custom XML elements that are replaced with the resulting HTML at compile time. `i:*` elements are Simplia system components (images, lists, forms, social buttons, etc.).

```twig
{# Twital component — product image #}
<i:img src="product.image" width="300" height="300" />

{# Twital component — product listing #}
<i:list-container repository="product.recommended" limit="4">
    <div>{{ product.name }}</div>
</i:list-container>

{# Twital conditional attribute (if: prefix) #}
<button if:disabled="not product.available">Buy</button>
```

The complete list of available `i:*` components can be found in the [component reference](/components).

## Common Patterns

### Setting and Reusing Variables

Use `{% set %}` to define variables at the top of a template and reference them later:

```twig
{% set headerMode = '' %}
{% if page.type == 'checkout' %}
    {% set headerMode = 'header--minimal' %}
{% endif %}

<header class="header{{ headerMode ? ' ' ~ headerMode }}">
```

### Dynamic Content Reload

Mark elements with `i:dynamic` so they refresh automatically when related data changes. The attribute accepts a comma-separated list of data scopes:

```twig
{# Reload this element when product data changes #}
<div i:dynamic="product">
    {{ product.price.current.formatted }}
</div>

{# Reload when cart or order data changes #}
<div i:dynamic="cart, objednavka">
    {{ cart.catalogItemTotalAmount }} items
</div>
```

### Translation Patterns

Three ways to output translated strings:

```twig
{# Block trans tag #}
{% trans 'checkout.headline' %}

{# Inline trans filter #}
{{ 'checkout.headline'|trans }}

{# Trans filter with parameters #}
{{ 'cart.items.count'|trans({count: cart.catalogItemTotalAmount}) }}
```

### SVG Sprite Access

Icons are stored in an SVG sprite file and referenced with `<use>`:

```twig
<svg class="icon">
    <use xlink:href="{{ images('symbol-defs.svg#bi-Arrow-right') }}"></use>
</svg>
```

The `images()` function resolves the path to the template's images directory. Icon names use the `bi-` prefix (e.g., `bi-Close`, `bi-Chevron-down`, `bi-Voucher`).

### Conditional CSS Classes

Combine static and dynamic classes using Twig's ternary operator and string concatenation (`~`):

```twig
{# Append class conditionally #}
<header class="header{{ headerMode ? ' ' ~ headerMode }}">

{# Choose between two classes #}
<strong class="{{ orderItem.price.discount ? 'u-color-red' : 'u-color-black' }}">

{# Use if: prefix for fully conditional attributes #}
<div if:class="product.available ? 'in-stock' : 'out-of-stock'">
```

### Conditional Inline Styles

The `if:style` prefix works the same way as `if:class` for inline styles:

```twig
{# Dynamic background color from data #}
<span class="label" if:style="label.colorCode ? 'background: ' ~ label.colorCode">
    {{ label.name }}
</span>

{# Conditionally hide an element #}
<div if:style="hidden ? 'display: none'">
```

### Content Grid Blocks

Use `this.contentGrid()` to fetch configurable content blocks from the admin panel (see [Content Grid](/content-grid)):

```twig
{% if this.contentGrid('checkout-content-info') %}
    {% set block = this.contentGrid('checkout-content-info').checkouttext %}
    <div style="color: {{ block.color }}; background: {{ block.bgcolor }}">
        {{ block.text }}
    </div>
{% endif %}
```

### Template Attributes

Access shop-level configuration flags and values via `this.templateAttributes`:

```twig
{# Check a feature toggle #}
{% if this.templateAttributes.global_enable_free_delivery == 'enabled' %}
    {% include 'partials/_free-delivery.tpl' %}
{% endif %}

{# Use a custom label text with fallback #}
{% if this.templateAttributes.label_new %}
    {{ this.templateAttributes.label_new }}
{% else %}
    {% trans 'template.label.new' %}
{% endif %}
```

### Slave Config Flags

Feature toggles from the shop configuration are available via `this.slaveConfig`:

```twig
{% if this.slaveConfig.enableGifts %}
    {% include 'kosik_darky.tpl' %}
{% endif %}

{% if this.slaveConfig.enableLoyaltyProgram %}
    {# Loyalty program UI #}
{% endif %}
```

### Plural Translations

For strings that need pluralization, use the `{% trans %}...{% plural %}...{% endtrans %}` block syntax:

```twig
{{ customer.userPointsAvailable }}
{% trans %}user.credits-count{% plural customer.userPointsAvailable %}user.credits-count-plural{% endtrans %}
```

---

---
url: /examples.md
---
# Template Examples

Simplified code recipes extracted from the **buran** production template. Feature-toggle conditionals have been stripped to show core structural patterns. For the complete file listing, see [Template file structure](/files).

## Product listing item

The `_listing.tpl` file defines how each product card looks in category pages, search results, and product sliders. The `i:list-item` tag wraps each item and is rendered automatically by `i:list-container` (see [Product listing](/list)).

```twig
{# _listing.tpl - default product card #}
<i:list-item type="product" class="swiper-slide cell cell--product">
    <div class="white-item white-item--column">
        {# Product image with link #}
        <div class="white-item__image">
            <a href="{{ product.url }}">
                <i:img src="product.image" format="359x479" fill />
            </a>

            {# Labels: discount, new, custom labels #}
            <div class="listing__labels labels">
                {% if product.item.price.discountPercent %}
                    <strong class="label label__discount">
                        -{{ product.item.price.discountPercent }}%
                    </strong>
                {% endif %}
                {% if product.flagNew %}
                    <strong class="label label__new">{% trans 'template.label.new' %}</strong>
                {% endif %}
                {% for label in product.labels %}
                    <strong class="label" if:style="label.colorCode ? 'background: ' ~ label.colorCode">
                        {{ label.name }}
                    </strong>
                {% endfor %}
            </div>
        </div>

        {# Product name #}
        <h2 class="listing-item__header">
            <a href="{{ product.url }}">{{ product.name }}</a>
        </h2>

        {# Price: before-discount + current price #}
        <div class="white-item__bottom-left">
            {% if product.item.price.discount %}
                <span class="u-decoration-through">{{ product.item.price.beforeDiscount.formatted }}</span>
            {% endif %}
            <strong class="{{ product.item.price.discount ? 'u-color-red' }}">
                {{ product.item.price.current.formatted }}
            </strong>
        </div>

        {# Availability text and estimated delivery date #}
        <div class="white-item__bottom-right">
            <strong class="availability availability--{{ product.item.availability.hours }}">
                {# prvniVelke = capitalize first letter #}
                {{ product.item.availability.text|prvniVelke }}
            </strong>
            {% if product.item.availability.hours < 999 and product.item.availability.deliveryOption.dateDelivered %}
                <span>
                    {% trans 'template.at-your-place' %}
                    <strong>{{ product.item.availability.deliveryOption.dateDelivered|date('j. n.') }}</strong>
                </span>
            {% endif %}
        </div>

        {# Add-to-cart button #}
        <div class="listing__submit-form">
            <form action="/Koupit" class="js_koupit" method="post">
                <button type="submit" class="button--order">
                    + {% trans 'template.add-to-cart' %}
                </button>
                <input name="zbozi" value="{{ product.id }}" type="hidden" />
            </form>
        </div>

        {# Wishlist heart icon (prani = wishes) #}
        <a href="#" class="listing__fav fav-link {{ customer ? (customer.productOnWishlist(product) ? 'js_wish_del is-active' : 'js_wish_add') : 'js_prihlaseni' }}"
           data-zbozi="{{ product.id }}" role="button">
            <svg class="icon fav-empty"><use xlink:href="{{ images('symbol-defs.svg#bi-Heart') }}"></use></svg>
            <svg class="icon fav-full u-color-red"><use xlink:href="{{ images('symbol-defs.svg#bi-Heart') }}"></use></svg>
        </a>
    </div>
</i:list-item>
```

Key objects: `product.url`, `product.image`, `product.name`, `product.item.price`, `product.item.availability`, `product.labels`. See [Object Types](/objects#product).

## Category page

The `vypis.tpl` (category listing) uses `i:list-container` to render a filterable, sortable product grid. The container automatically loads `_listing.tpl` for each product. The `i:list-dynamic` wrapper marks sections that the system re-renders via AJAX when the user applies filters or navigates pages.

```twig
{# vypis.tpl - category listing (vypis = listing/display) #}
<div class="grid-container">
    {# Category title (this.nazev = page heading set by the system) #}
    <h1>{{ this.nazev }}</h1>

    {# Category description - i:list-dynamic re-renders this block when filters change #}
    {% if category.text('long') %}
        <i:list-dynamic variables="category" type="text">
            {{ category.text('long') }}
            {# Link to bottom description if both long and short text exist #}
            {% if category.text %}
                <p><a href="#long-description" class="to-anchor">
                    {% trans 'template.category.description.more' %}
                </a></p>
            {% endif %}
        </i:list-dynamic>
    {% endif %}

    {# Subcategory navigation with swiper - also dynamic (updates on filter) #}
    <i:list-dynamic variables="category" type="subcategories" class="swiper-container subcategories">
        {% if category.subcategories %}
            <div class="swiper-wrapper">
                {% for cat in category.subcategories %}
                    <a href="{{ cat.url }}" class="swiper-slide subcategory">
                        {# cat.image('ico') = icon-sized category image #}
                        <i:img src="cat.image('ico')" format="80x80" fill loading="lazy" />
                        <span>{{ cat.name }}</span>
                    </a>
                {% endfor %}
            </div>
        {% endif %}
    </i:list-dynamic>
</div>

<div class="grid-container">
    {# Product list container - automatically renders _listing.tpl for each product #}
    <i:list-container type="product" class="main-listing">
        {# Filter placeholder - renders the filter form from _filter.tpl #}
        <i:filter-placeholder name="default" config="default" always-collapsed />

        {# Sort dropdown (razeni = sorting) #}
        <div data-role="pagination" data-name="sort"></div>

        {# Product count display #}
        <div data-role="pagination" data-name="numbers"></div>

        {# Grid/list view toggle #}
        <div data-role="pagination" data-name="grid"></div>

        {# Active filter values with remove buttons #}
        <i:filter-placeholder-values name="default" config="default" />

        {# Empty state message (shown when no products match filters) #}
        <div data-role="empty"></div>

        {# Product grid - items from _listing.tpl are injected here #}
        <div data-role="list" class="listing"></div>

        {# Pagination controls - multiple strategies: scroll, pages, load-more #}
        <div class="pagination">
            <div data-role="pagination" data-name="scroll"></div>
            <div data-role="pagination" data-name="pages"></div>
            <div data-role="pagination" data-name="add"></div>
            <div data-role="pagination" data-name="numbers"></div>
        </div>
    </i:list-container>

    {# Bottom category description (SEO text) #}
    {% if category.text %}
        <div id="long-description">
            <i:list-dynamic variables="category" type="text">
                {{ category.text }}
            </i:list-dynamic>
        </div>
    {% endif %}
</div>
```

See [Product listing](/list) for `i:list-container` reference and [Filters](/filter) for `i:filter-placeholder`. The `i:list-dynamic` component is documented in [Syntax](/syntax).

## Homepage

The `index.tpl` renders the homepage with banner sliders, product sections, brands, and content-grid-driven content blocks. The homepage is heavily data-driven: most sections are controlled through content grids and banner repositories configured in the admin panel.

```twig
{# index.tpl - homepage (uvodni stranka) #}

{# Main banner slider (configured via admin banner sections) #}
{% if this.templateAttributes.banners_homepage %}
{% set banner_section_id = this.templateAttributes.banners_homepage.id %}
<div class="main-banner" role="banner">
    <i:banners source="repository.banner.findBy({'sectionId': banner_section_id, 'limit': 6})"
               class="main-banner__swiper" click="banner" plugin="swiper">
        {# Responsive image sources - system picks best size per device #}
        <source format="1920x800" src="desktop" alt="" />
        <source format="767x900" src="tablet" alt="" />
        <source format="375x440" src="mobile" alt="" />

        {# Banner content slots - filled from banner.name, banner.text, banner.ctaText #}
        <span data-role="title"></span>
        <strong data-role="description"></strong>
        <button data-role="cta" class="button--white"></button>
    </i:banners>
</div>
{% endif %}

{# Content-grid section: rich text/image block (positioned above or below banner) #}
{% if this.contentGrid('homepage-about-top') %}
    {% set item = this.contentGrid('homepage-about-top').item %}
    <div if:style="item.color ? 'background-color: ' ~ item.color">
        {% if item.image %}
            {# Multiple format sizes for responsive srcset generation #}
            <i:img src="item.image" format="2000x2000,1600x1600,800x800" sizes="100vw" loading="lazy" />
        {% endif %}
        {{ item.text }}
    </div>
{% endif %}

{# Content-grid section: banner with product slider combo #}
{% if this.contentGrid('homepage-banner-products') %}
    {% for item in this.contentGrid('homepage-banner-products').item %}
        <div class="banner-products" if:style="item.left.color ? '--banner-bg-color: ' ~ item.left.color">
            {# Left side: promotional image #}
            <div class="banner-products__image">
                <i:img src="item.left.image" format="600x600" loading="lazy" />
            </div>
            {# Right side: text + CTA button #}
            <div class="banner-products__text">
                <span>{{ item.right.text }}</span>
                <strong>{{ item.right.headline }}</strong>
                <a href="{{ item.right.button.url }}" class="button">
                    {{ item.right.button.label }}
                </a>
            </div>
            {# Product slider using a content-grid-defined product collection #}
            {# hide-empty = don't render this block if collection is empty #}
            <i:list-container type="product" name="simple"
                              collection="{{ item.right.products }}" hide-empty>
                <div data-role="list" class="swiper-wrapper"></div>
            </i:list-container>
        </div>
    {% endfor %}
{% endif %}

{# Text block above brands (optional content grid section) #}
{% if this.contentGrid('homepage-text-above-brands') %}
    {% set item = this.contentGrid('homepage-text-above-brands').item %}
    <div if:style="item.color ? 'background-color: ' ~ item.color">
        {{ item.text }}
    </div>
{% endif %}

{# Important brands slider from repository #}
{% set important_brands = repository.brand.findBy({'important': true, 'limit': 10}) %}
{% if important_brands|length > 0 %}
    <h2>{% trans 'template.favourite-brands.headline' %}</h2>
    <p><a href="{{ iUrl('Vyrobce/Vypis') }}">{% trans 'template.favourite-brands.text' %}</a></p>
    <div class="swiper-container swiper-per-10">
        <div class="swiper-wrapper">
            {% for brand in important_brands %}
                <div class="swiper-slide">
                    <a href="{{ brand.url }}">
                        {# vector + transparent = render SVG logos without background #}
                        <i:img src="brand.image" format="69x60" loading="lazy" vector transparent="" fill />
                    </a>
                </div>
            {% endfor %}
        </div>
    </div>
{% endif %}

{# Blog articles section #}
{% if repository.article.findBy({'limit': 4}) is not empty %}
    <div class="swiper-container swiper-per-4">
        <div class="swiper-wrapper">
            {% for article in repository.article.findBy({'limit': 4}) %}
                <div class="swiper-slide">
                    <a href="{{ article.url }}">
                        {# article.image('preview') = preview-sized article image #}
                        <i:img src="article.image('preview')" format="359x251" fill loading="lazy" />
                    </a>
                    <span>{{ article.topic.name|upper }}</span>
                    <h3><a href="{{ article.url }}">{{ article.name }}</a></h3>
                    {# orez = truncate text to N characters #}
                    <p>{{ article.text('annotation')|orez(100) }}</p>
                </div>
            {% endfor %}
        </div>
    </div>
{% endif %}

{# Footer about section driven by content grid #}
{% if this.contentGrid('homepage-about') %}
    {% include 'partials/_footer-about.tpl' %}
{% endif %}
```

Key patterns:

* `repository.banner.findBy()`, `repository.brand.findBy()`, `repository.article.findBy()` -- query data from [Repositories](/repositories)
* `this.contentGrid('name')` -- load admin-configured content (see [Content Grid](/content-grid))
* `this.templateAttributes.banners_homepage.id` -- banner section ID from [Configuration](/config)
* `i:banners` -- banner slider component with responsive `<source>` tags (see [Syntax](/syntax))
* `i:list-container` with `collection` attribute -- render a specific product set as a slider
* `iUrl('Vyrobce/Vypis')` -- generate internal URL for a route (see [Global variables](/global))

## Product detail buy form

From `zbozi.tpl` and `zbozi_vars.tpl` -- the variant selection and add-to-cart area on product detail pages. The buy form is only rendered when `product.active` is true; inactive products show alternative recommendations instead.

```twig
{# zbozi.tpl - product detail buy form (Koupit = Buy) #}
{% if product.active %}
    <form class="product__rest js_koupit" action="/Koupit" method="post">
        {# Variant choice component - renders color/size selectors #}
        {# See variant-selection docs for full reference #}
        {% include 'zbozi_vars.tpl' %}

        {# Availability info block - reloads when variant changes #}
        {# js_reload_var + i:dynamic="product" = AJAX-reloaded on variant select #}
        <div class="js_reload_var" i:dynamic="product">
            <strong class="availability availability--{{ product.item.availability.hours }}">
                {# prvniVelke = capitalize first letter #}
                {{ product.item.availability.text|prvniVelke }}
            </strong>
            {% if product.item.availability.deliveryOption.dateDelivered %}
                <div>
                    {% trans 'template.estimated-delivery-date' %}
                    <strong>{{ product.item.availability.deliveryOption.dateDelivered|date('j. n.') }}</strong>
                </div>
            {% endif %}
        </div>

        {# Hidden product ID (zbozi = goods/product) #}
        <input type="hidden" value="{{ product.id }}" name="zbozi">

        {# Quantity input (ks = kusy = pieces) #}
        <div class="product__amount">
            <span class="plus-minus">
                <a href="" class="plus-minus__plus">+</a>
                <a href="" class="plus-minus__minus">-</a>
                <label>
                    {% trans 'checkout.catalog-table.item.quantity' %}
                    <input type="tel" name="ks" class="ks" value="1" size="1" min="0" />
                </label>
            </span>
        </div>

        {# Buy button with inline price display #}
        <div class="product__buy">
            <button type="submit" class="button button--order button--expanded">
                {% trans 'product.button.buy' %}
                <span class="product__buy-price">
                    {{ product.item.price.current.formatted }}
                </span>
            </button>
        </div>
    </form>
{% endif %}
```

The `zbozi_vars.tpl` uses the `i:variant-choice` component. It supports three step modes: `icons` (color swatches), `selects` (dropdown), and a default radio-button list. The buran template also adds size table links when available:

```twig
{# zbozi_vars.tpl - variant choice steps #}
<i:variant-choice product="product" reload-targets=".js_reload_var">
    {% for step in product.variantChoiceSteps %}
        <div data-role="step">
            {% if step.mode == 'icons' %}
                {# Color swatches (barva = color) #}
                <label>{{ step.headline }}: <span>{{ step.selectedChoice.name }}</span></label>
                <ul class="variant-choice__list variant-choice__list--color">
                    {% for choice in step.choices %}
                        <li>
                            <input name="{{ step.inputName }}" type="radio"
                                   value="{{ choice.inputValue }}" if:checked="choice.selected"
                                   required data-msg-required="{{ step.messageEmpty }}" />
                            <label title="{{ choice.name }}">
                                {% if choice.icon %}
                                    <i:img src="choice.icon" fill format="40x40" vector loading="lazy" />
                                {% elseif choice.description %}
                                    {# description contains hex color code #}
                                    <span style="background-color: {{ choice.description }}"></span>
                                {% endif %}
                            </label>
                        </li>
                    {% endfor %}
                </ul>
            {% elseif step.mode == 'selects' %}
                {# Dropdown select (roletka = dropdown) #}
                {# Size table link if available on product or brand #}
                {% if step.infoDescription %}
                    <a class="variant-choice__link open-dialog"
                       data-dialogtitle="{{ step.infoDescription }}">
                        {{ step.infoDescription }}
                    </a>
                {% endif %}
                <label>{{ step.headline }}</label>
                <select name="{{ step.inputName }}" required
                        data-msg-required="{{ step.messageEmpty }}">
                    <option value="">{{ step.placeholder }}</option>
                    {% for choice in step.choices %}
                        <option value="{{ choice.inputValue }}" if:selected="choice.selected">
                            {{ choice.name }}
                        </option>
                    {% endfor %}
                </select>
            {% else %}
                {# Default: radio button list with availability per choice #}
                <label>{{ step.headline }}: <span>{{ step.selectedChoice.name }}</span></label>
                <ul class="variant-choice__list">
                    {% for choice in step.choices %}
                        <li>
                            <input type="radio" name="{{ step.inputName }}"
                                   value="{{ choice.inputValue }}" if:checked="choice.selected"
                                   required data-msg-required="{{ step.messageEmpty }}" />
                            <label>
                                <strong>{{ choice.name }}</strong>
                                {% if choice.availability %}
                                    <br><small class="availability availability--{{ choice.availability.hours }}">
                                        {{ choice.availability.text }}
                                    </small>
                                {% endif %}
                            </label>
                        </li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>
    {% endfor %}
</i:variant-choice>
```

Key attributes:

* `i:variant-choice` with `reload-targets` -- automatically reloads price/availability when a variant is selected
* `i:dynamic="product"` -- marks elements for AJAX reload when variant changes
* `product.variantChoiceSteps` -- array of selection steps (color, size, etc.)
* `step.mode` -- determines rendering style: `icons`, `selects`, or default radio list
* `step.infoDescription` / `step.infoIcon` -- optional help link (e.g., size table)
* `choice.availability` -- per-choice stock info (only in default radio mode)
* See [Variant Selection](/cart#variant-selection) for the full reference

## Cart items

From `kosik_obsah.tpl` -- iterating over products in the cart. The cart page uses `cart.catalogItems` to loop through items. The entire cart form is wrapped in `i:dynamic="cart, objednavka"` so the system can reload it via AJAX when quantities change.

```twig
{# kosik_obsah.tpl - cart product list (kosik = cart, obsah = content) #}
<form action="{{ this.urlSave }}" method="post">
    <div class="checkout-left js_reload_order" i:dynamic="cart, objednavka">

        {# Optional checkout info banner from content grid #}
        {% if this.contentGrid('checkout-content-info') %}
            {% set block = this.contentGrid('checkout-content-info').checkouttext %}
            <div class="callout callout--info"
                 style="color: {{ block.color }}; background: {{ block.bgcolor }}">
                {{ block.text }}
            </div>
        {% endif %}

        <h1>
            {% trans 'checkout.headline' %}
            <span>({{ cart.catalogItemTotalAmount }} {% trans 'template.qty' %})</span>
        </h1>

        {# Loop through cart items (orderItem = polozka objednavky) #}
        {% for orderItem in cart.catalogItems %}
            <div class="cartie cartie--item {{ orderItem.gift ? 'cartie--gift' }}">
                {# Product image - use variant image if available #}
                <a href="{{ orderItem.product.url }}" class="cartie__image">
                    {% if orderItem.variant.image %}
                        <i:img src="orderItem.variant.image" format="130x92" fill />
                    {% else %}
                        <i:img src="orderItem.image" format="130x92" fill />
                    {% endif %}
                </a>

                <div class="cartie__rest">
                    {# Product name and child items (e.g., bundle components) #}
                    <div class="cartie__name">
                        <a href="{{ orderItem.product.url }}">
                            <strong>{{ orderItem.item.name }}</strong>
                        </a>
                        {% for item in orderItem.children %}
                            {% if orderItem.name not in item.name %}
                                {{ item.name }} {{ item.variantName }}
                                {% if item.priceTotal.current.value != 0 %}
                                    ({{ item.priceTotal.current.formatted }})
                                {% endif %}<br>
                            {% endif %}
                        {% endfor %}
                    </div>

                    {# Availability and variant info (not shown for gift items) #}
                    {% if not orderItem.gift %}
                        <div class="cartie__info">
                            {% trans 'template.availability' %}:
                            <strong class="availability availability--{{ orderItem.item.availability.hours }}">
                                {{ orderItem.item.availability.text }}
                            </strong><br>
                            {% if orderItem.variantName %}
                                {% trans 'template.variant' %}: <strong>{{ orderItem.variantName }}</strong><br>
                            {% endif %}
                            {% trans 'template.price' %}:
                            {% if orderItem.item.price.discount %}
                                <span class="u-decoration-through">{{ orderItem.item.price.beforeDiscount.formatted }}</span>
                            {% endif %}
                            <strong>{{ orderItem.item.price.current.formatted }}</strong>
                        </div>
                    {% endif %}

                    {# Line total (darek zdarma = free gift) #}
                    <div class="cartie__price">
                        {% if orderItem.gift %}
                            <strong class="u-color-red">{% trans 'global.free' %}</strong>
                        {% else %}
                            <strong>{{ orderItem.priceTotal.current.formatted }}</strong>
                        {% endif %}
                    </div>

                    {# Quantity input with plus/minus buttons (ks = kusy = pieces) #}
                    <div class="cartie__quantity">
                        {% if orderItem.gift %}
                            1 {% trans 'template.qty' %}
                        {% else %}
                            <span class="plus-minus plus-minus--to-null">
                                <a href="" class="plus-minus__plus">+</a>
                                <a href="" class="plus-minus__minus">-</a>
                                <label>
                                    {% trans 'checkout.catalog-table.item.quantity' %}
                                    <input type="tel" name="ks[{{ orderItem.id }}]"
                                           value="{{ orderItem.amount }}" size="1" min="0" />
                                </label>
                            </span>
                        {% endif %}
                    </div>

                    {# Remove item link (del = smazat/delete) #}
                    {% if not orderItem.gift %}
                        <a href="?del={{ orderItem.id }}" class="cartie__del">
                            {% trans 'cart-popup.item.delete' %}
                        </a>
                    {% endif %}

                    {# Upsell add-ons (e.g., extended warranty, gift wrapping) #}
                    {% if orderItem.availableUpsells is not empty and not orderItem.gift %}
                        <div class="cartie__extra">
                            <strong>{% trans 'cart-dialog.upsells.headline' %}</strong>
                            {% for upsell in orderItem.availableUpsells %}
                                <p>
                                    <input type="checkbox" name="upsell[{{ orderItem.id }}]"
                                           value="{{ orderItem.id }}-{{ upsell.id }}"
                                           if:checked="upsell.inCart" />
                                    <label>
                                        {{ upsell.name }}
                                        <span>{{ upsell.price.current.formatted }}</span>
                                    </label>
                                </p>
                            {% endfor %}
                        </div>
                    {% endif %}
                </div>
            </div>
        {% endfor %}

        {# Discount items (e.g., coupon codes; sleva = discount) #}
        {% for orderDiscountCart in cart.discountItems %}
            <div class="cartie">
                <div class="cartie__name">{{ orderDiscountCart.name }}</div>
                <div class="cartie__price">
                    {% if orderDiscountCart.percent > 0 %}
                        <strong>-{{ orderDiscountCart.percent }}%</strong>
                    {% elseif orderDiscountCart.price.current.value > 0 %}
                        <strong>{{ orderDiscountCart.price.current.formatted }}</strong>
                    {% endif %}
                </div>
                {# delSleva = delete discount #}
                <a href="?delSleva={{ orderDiscountCart.id }}" class="cartie__del">
                    {% trans 'cart-popup.item.delete' %}
                </a>
            </div>
        {% endfor %}
    </div>

    {# Order summary sidebar (souhrn = summary) #}
    {% include 'kosik_souhrn.tpl' with {'checkout': 'products'} %}

    {# toSekce = target section for next checkout step (dodani = delivery) #}
    <input type="hidden" name="toSekce" value="dodani">
    <input type="submit" name="submit" class="hide" value="{% trans 'checkout.button.recount' %}" />
</form>
```

Key objects:

* `cart.catalogItems` -- ordered products (see [Cart](/cart))
* `cart.discountItems` -- applied discount coupons (sleva = discount)
* `cart.catalogItemTotalAmount` -- total number of items
* `orderItem.item.price`, `orderItem.priceTotal` -- unit price vs line total
* `orderItem.availableUpsells` -- add-on products (warranty, services) for this item
* `orderItem.children` -- child items for bundles/packs
* `orderItem.gift` -- boolean, true if item is a free gift
* `this.urlSave` -- form action URL for cart updates
* `this.contentGrid('checkout-content-info')` -- optional info banner (see [Content Grid](/content-grid))
* `i:dynamic="cart, objednavka"` -- marks the section for AJAX reload when cart changes

## Footer with content grid

From `_footer.tpl` -- rendering configurable footer columns using the `footer-column-links` content grid. The footer is composed of multiple included sub-templates and content-grid-driven sections.

```twig
{# _footer.tpl - footer link columns from content grid #}
<div class="footer">
    {# Newsletter subscription form (optional, toggled via templateAttributes) #}
    {% include 'partials/_newsletter.tpl' %}

    {# USP bar: free shipping, returns, etc. (from content-grid/footer-usp.xml) #}
    {% if this.contentGrid('footer-usp').item %}
        {% include '_footer-usp.tpl' %}
    {% endif %}

    <div class="u-bg-light-gray">
        <div class="grid-container">
            <div class="grid-x xlarge-up-5">
                {# Link columns from content-grid/footer-column-links.xml #}
                {# Each item has .headline and .link[] array #}
                {# Production template limits to first 3 columns: loop.index <= 3 #}
                {% for item in this.contentGrid('footer-column-links').item %}
                    <div class="cell footer-box">
                        <h4 class="footer-box__headline">
                            {{ item.headline }}
                            {# Chevron icon for mobile accordion toggle #}
                            <svg class="footer-box__headline-angle icon">
                                <use xlink:href="{{ images('symbol-defs.svg#bi-chevron-down') }}"></use>
                            </svg>
                        </h4>
                        <div class="footer-box__info">
                            <ul>
                                {% for link in item.link %}
                                    <li><a href="{{ link.url }}">{{ link.label }}</a></li>
                                {% endfor %}
                            </ul>
                        </div>
                    </div>
                {% endfor %}

                {# Contact column with phone and email #}
                <div class="cell footer-box">
                    <h4>{% trans 'footer.contact.headline' %}</h4>
                    <div class="footer-box__info">
                        {% if shop.phone %}
                            <a href="tel:{{ shop.phone }}" class="button button--white-bg-gray-border">
                                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-Phone') }}"></use></svg>
                                <span>
                                    {% trans 'footer.contact.phone-contact' %}<br>
                                    <strong>{{ shop.phone }}</strong>
                                </span>
                            </a>
                        {% endif %}
                        {% if shop.email %}
                            <a href="mailto:{{ shop.email }}" class="button button--white-bg-gray-border">
                                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-Envelope') }}"></use></svg>
                                <span>
                                    {% trans 'footer.contact.email-contact' %}<br>
                                    <strong>{{ shop.email }}</strong>
                                </span>
                            </a>
                        {% endif %}
                    </div>
                </div>

                {# Social media links (sledujte nas = follow us) #}
                <div class="cell footer-box">
                    <h4>{% trans 'footer.social.headline' %}</h4>
                    <div class="footer-box__info">
                        <span>{% trans 'footer.social.find-us' %}</span><br>
                        {% if shop.socialProfiles['facebook'] %}
                            <a href="{{ shop.socialProfiles['facebook'].url }}" rel="nofollow" target="_blank" aria-label="Facebook">
                                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-Facebook') }}"></use></svg>
                            </a>
                        {% endif %}
                        {% if shop.socialProfiles['instagram'] %}
                            <a href="{{ shop.socialProfiles['instagram'].url }}" rel="nofollow" target="_blank" aria-label="Instagram">
                                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-Instagram') }}"></use></svg>
                            </a>
                        {% endif %}
                        {% if shop.socialProfiles['pinterest'] %}
                            <a href="{{ shop.socialProfiles['pinterest'].url }}" rel="nofollow" target="_blank" aria-label="Pinterest">
                                <svg class="icon"><use xlink:href="{{ images('symbol-defs.svg#bi-Pinterest') }}"></use></svg>
                            </a>
                        {% endif %}
                    </div>
                </div>
            </div>
        </div>
    </div>

    {# Copyright bar (podpis = signature) #}
    {% include '_footer-sign.tpl' %}
</div>
```

Key patterns:

* `this.contentGrid('footer-column-links').item` -- returns an array of column objects, each with `.headline` and `.link[]` (see [Content Grid](/content-grid))
* `this.contentGrid('footer-usp').item` -- USP items (free delivery, returns guarantee, etc.)
* `shop.phone`, `shop.email` -- global shop contact info (see [Global variables](/global))
* `shop.socialProfiles['facebook'].url` -- social media URLs configured in admin; supports `facebook`, `instagram`, `pinterest`, `twitter`
* `images('symbol-defs.svg#bi-*')` -- SVG sprite icon references; the `symbol-defs.svg` file in `images/` contains all icons
* Footer boxes collapse into accordions on mobile (toggled by the chevron icon)

## Working Hours

`workingHours` is an object of type `WorkingHours`, either the global `this.templateAttributes.globalWorkingHours` or on an object of type `Store`.

### Current Status

```twig
{% if workingHours.open %}
    Otevřeno
{% else %}
    Zavřeno
{% endif %}
```

Display of the current open/closed status with the next transition time.

```twig
{% if workingHours.open %}
    Máme otevřeno, zavíráme {{ workingHours.nextClose|date('d. m. Y H:i') }}
{% else %}
    Máme zavřeno, otevíráme {{ workingHours.nextOpen|date('d. m. Y H:i') }}
{% endif %}
```

### Compact Display

Days with the same opening hours are merged, e.g. Po-St (Mon-Wed), Ct (Thu), Pa-Ne (Fri-Sun).
`timeFormat: 'compact'` hides minutes when they are 0 (e.g. 9-10:30, 9:30-11).

**Note: This display does not include exceptions (or holidays) — they must be listed separately**: [Listing Exceptions and Holidays](#listing-exceptions-and-holidays)

```twig
{% for day, time in workingHours.week({longDays: false, timeDelimiter: '-', timeFormat: 'compact'}) %}
    {{ day }}: {% if time %}
        {{ time|join(', ') }}
    {% else %}
        Zavřeno
    {% endif %}
{% endfor %}
```

### Full Week Day-by-Day Display

Lists the entire week day by day (Monday, Tuesday, ...).

**Note: This display does not include exceptions (or holidays) — they must be listed separately**: [Listing Exceptions and Holidays](#listing-exceptions-and-holidays)

```twig
{% for day, time in workingHours.weekFull({longDays: true, timeDelimiter: '-', timeFormat: 'compact'}) %}
    {{ day }}: {% if time %}
        {{ time|join(', ') }}
    {% else %}
        Zavřeno
    {% endif %}
{% endfor %}
```

### Upcoming Days Display

Day-by-day listing including dates (reflects exceptions and holidays).

```twig
{% for dayBlock in workingHours.forNextDays %}
    {# Or dayNameShort for abbreviated day names: #}
    {{ dayBlock.dayName }} {{ dayBlock.date|date('d. m. Y') }}:
    {% if dayBlock.timeBlocks %}
        {{ dayBlock.timeBlocks|join(', ') }}
    {% else %}
        Zavřeno
    {% endif %}
{% endfor %}
```

### Listing Exceptions and Holidays

Lists exceptions to regular opening hours, including holidays.

```twig
{% for date, timeBlocks in workingHours.specialCases({dateFormat: 'd. m. Y'}) %}
    {{ date }}:
    {% if timeBlocks %}
        {{ timeBlocks|join(', ') }}
    {% else %}
        Zavřeno
    {% endif %}
{% endfor %}
```

> **Locale note:** The day abbreviations in code output (Po, Ut, St, Ct, Pa, So, Ne) and Czech strings like "Otevřeno" (open), "Zavřeno" (closed), "Máme otevřeno, zavíráme" (we are open, closing at), and "Máme zavřeno, otevíráme" (we are closed, opening at) come from the system locale / template layer and are intentionally left in Czech in the code examples.

---

---
url: /files.md
---
# Template file structure

## Directory structure

A template contains the following directories and files. This is the complete file listing of the **buran** production template:

```
template/
│
│  ── LAYOUT ─────────────────────────────────────────────────
├── _base.tpl              # Main layout wrapper (includes header, content, footer)
├── _header.tpl            # Full site header (logo, nav, search, cart)
├── _header-checkout.tpl   # Simplified checkout header (only logo + steps)
├── _footer.tpl            # Full site footer (links, contact, social)
├── _footer-checkout.tpl   # Simplified checkout footer
├── _footer-usp.tpl        # USP bar above footer (unique selling points)
├── _footer-sign.tpl       # Copyright / footer bottom bar
├── _breadcrumbs.tpl       # Breadcrumb navigation (drobecky)
├── _menu.tpl              # Main navigation mega-menu
├── _bar-compare.tpl       # Product comparison floating bar
│
│  ── PRODUCT LISTING ────────────────────────────────────────
├── _listing.tpl           # Product card for all product grids
├── _listing_article.tpl   # Article card for blog listings
├── _filter.tpl            # Product filter sidebar/form definition
│
│  ── PAGE TEMPLATES ─────────────────────────────────────────
├── index.tpl              # Homepage (uvodni stranka)
├── zbozi.tpl              # Product detail (zbozi = goods/product)
├── zbozi_imgs.tpl         #   ├── product image gallery
├── zbozi_vars.tpl         #   ├── variant choice (size, color selectors)
├── zbozi_bar.tpl          #   ├── sticky buy bar (scrolls with page)
├── zbozi_komplet.tpl      #   ├── bundle/pack products (komplet = set)
├── zbozi_upsells.tpl      #   ├── upsell product recommendations
├── zbozi_dostupnost.tpl   #   ├── availability info (dostupnost = availability)
├── zbozi_comments.tpl     #   ├── product Q&A (dotazy)
├── zbozi_rating.tpl       #   └── product reviews/ratings (hodnoceni)
├── zbozi_admin-dostupnost.tpl  # admin-facing availability overlay
├── vypis.tpl              # Category listing (vypis = listing)
├── vypis_filtr.tpl        # Category with sidebar filter layout
├── vypis_vyrobce.tpl      # Brand product listing (vyrobce = manufacturer)
├── vypis_prani.tpl        # Wishlist (prani = wishes)
├── vypis_porovnani.tpl    # Product comparison page (porovnani = comparison)
├── vyhledavani.tpl        # Search results (vyhledavani = search)
├── kosik.tpl              # Cart router (kosik = cart/basket)
├── kosik_obsah.tpl        #   ├── cart contents (obsah = content)
├── kosik_udaje.tpl        #   ├── customer details (udaje = details)
├── kosik_dodani.tpl       #   ├── delivery selection (dodani = delivery)
├── kosik_souhrn.tpl       #   ├── order summary sidebar
├── kosik_kroky.tpl        #   ├── checkout step indicators
├── kosik_prazdny.tpl      #   ├── empty cart (prazdny = empty)
├── kosik_darky.tpl        #   └── gift selection (darky = gifts)
├── potvrzeni.tpl          # Order confirmation (potvrzeni = confirmation)
├── objednavka.tpl         # Order detail (objednavka = order)
├── objednavky.tpl         # Order list
├── registrace.tpl         # Registration
├── stranka.tpl            # Static page (stranka = page)
├── clanek.tpl             # Article/blog post (clanek = article)
├── temata.tpl             # Blog topic list (temata = topics)
├── tema.tpl               # Single blog topic
├── vyrobce.tpl            # Brand detail page (vyrobce = manufacturer)
├── znacky.tpl             # All brands grid (znacky = brands)
├── prodejna.tpl           # Physical store page (prodejna = store)
├── heslo_pozadavek.tpl    # Password reset request (pozadavek = request)
├── heslo_zmena.tpl        # Password change (zmena = change)
├── _udaje.tpl             # Shared customer details form (udaje = details)
├── _dodani.tpl            # Shared delivery/shipping form (dodani = delivery)
├── _macro-accordion.tpl   # Accordion expand/collapse macro
├── _macro-rating.tpl      # Star rating display macro
├── 404.tpl                # 404 error page
│
│  ── CONFIGURATION ──────────────────────────────────────────
├── config.json            # Central template configuration (see /config)
│
│  ── CONTENT GRID XML ───────────────────────────────────────
├── content-grid/
│   ├── homepage-about-top.xml            # Homepage about block (above fold)
│   ├── homepage-about.xml                # Homepage about section (bottom)
│   ├── homepage-banner-products.xml      # Banner + product slider combos
│   ├── homepage-blog.xml                 # Blog section heading/text
│   ├── homepage-text-above-brands.xml    # Text block above brands slider
│   ├── footer-column-links.xml           # Footer link columns
│   ├── footer-usp.xml                    # Footer USP bar items
│   ├── footer-usp-checkout.xml           # USP bar for checkout pages
│   ├── footer-delivery-payment.xml       # Footer delivery/payment logos
│   ├── header-usp.xml                    # Header USP bar items
│   ├── detail-usp.xml                    # Product detail USP items
│   ├── product-detail-callout.xml        # Product detail callout boxes
│   ├── product-detail-specialtext.xml    # Product detail special text
│   ├── checkout-content-info.xml         # Checkout info banner
│   ├── checkout-delivery-info.xml        # Delivery step info banner
│   ├── checkout-select-products.xml      # Checkout cross-sell products
│   ├── checkout-select-upsells.xml       # Checkout upsell products
│   ├── article-grid-text-products.xml    # Article text + product grid
│   ├── page-accordion.xml                # Static page FAQ accordion
│   └── search.xml                        # Search page content blocks
│
│  ── TRANSLATIONS ───────────────────────────────────────────
├── locale/                # Translation directories by locale
│   ├── cs_CZ/             # Czech (default)
│   ├── sk_SK/             # Slovak
│   ├── en_GB/             # English
│   ├── de_DE/             # German
│   ├── pl_PL/             # Polish
│   ├── hu_HU/             # Hungarian
│   ├── ro_RO/             # Romanian
│   ├── bg_BG/             # Bulgarian
│   ├── hr_HR/             # Croatian
│   ├── sl_SI/             # Slovenian
│   ├── es_ES/             # Spanish
│   ├── fr_FR/             # French
│   └── it_IT/             # Italian
│
│  ── SUBDIRECTORIES ─────────────────────────────────────────
├── partials/              # Reusable template fragments
│   ├── _newsletter.tpl        # Newsletter subscription form
│   ├── _footer-about.tpl      # Footer about/content-grid block
│   ├── _free-delivery.tpl     # Free delivery progress bar
│   ├── _popup-cart.tpl        # Mini cart popup (kosik popup)
│   ├── _user-menu.tpl         # Logged-in user dropdown menu
│   ├── _user-register.tpl     # Registration/login form partial
│   ├── _user-wish.tpl         # Wishlist icon + dropdown
│   ├── _user-credits.tpl      # Customer credits display
│   ├── _flags.tpl             # Country/language flag icons
│   ├── _blog-menu.tpl         # Blog sidebar menu
│   └── _usp.tpl               # USP (unique selling points) bar
├── dialog/                # Modal dialog templates
│   ├── kosik_ok.tpl           # "Added to cart" confirmation dialog
│   ├── prihlaseni.tpl         # Login dialog (prihlaseni = login)
│   ├── product-comment.tpl    # Product Q&A dialog
│   ├── product-compare.tpl    # Compare products dialog
│   ├── product-wish.tpl       # Add to wishlist dialog
│   └── _recommended-shop.tpl  # Recommended regional shop dialog
├── macros/                # Twig macro files
│   └── pocet_kusu.tpl        # Quantity selector macro (pocet kusu = quantity)
├── ajax/                  # Templates for AJAX/dynamic responses
│   └── search.tpl             # Live search results overlay
├── recenze/               # Review-related templates (recenze = reviews)
│   └── vypis.tpl              # Review listing page
│
│  ── ASSETS ─────────────────────────────────────────────────
├── css/
│   ├── base.scss          # Main SCSS entry point (required)
│   ├── _settings.scss     # SCSS variables (optional, injected before plugins)
│   ├── settings/          # Breakpoints, colors, typography variables
│   ├── generic/           # CSS reset, box-sizing rules
│   ├── elements/          # Base HTML element styles
│   ├── objects/           # Layout objects (grid, media)
│   ├── components/        # BEM component styles (button, cartie, dialog, ...)
│   ├── tools/             # SCSS mixins and functions
│   └── utilities/         # Utility classes (spacing, visibility, colors)
├── js/                    # JavaScript files (auto-concatenated alphabetically)
│   ├── _header-sticky.js      # Sticky header scroll behavior
│   ├── _listing.js            # Product listing interactions
│   ├── _menu.js               # Navigation menu behavior
│   ├── countdowns.js          # Discount countdown timers
│   ├── ga-events.js           # Google Analytics 4 event tracking
│   ├── image-select.js        # Image selector for variants
│   ├── kosik.js               # Cart page interactions (kosik = cart)
│   ├── kosik_validace.js      # Cart validation (validace = validation)
│   ├── layout.js              # Global layout JS (sticky, scroll, resize)
│   ├── product.js             # Product detail page JS
│   ├── product_vars.js        # Variant selection JS
│   ├── swiper.js              # Swiper carousel initialization
│   ├── togglers.js            # Accordion/toggle UI components
│   ├── voucher.js             # Voucher/coupon code handling
│   └── wish-compare.js        # Wishlist and compare functionality
├── images/                # Static images and SVG sprites
│   ├── symbol-defs.svg        # SVG sprite with all icons (bi-Heart, bi-Phone, ...)
│   ├── logo.svg               # Shop logo
│   ├── no-gift.svg            # "No gift" placeholder
│   ├── sad-face.svg           # Empty state illustration
│   ├── flags/                 # Country flag images
│   └── temp/                  # Temporary/placeholder images
└── tests/                 # Playwright E2E tests
    ├── init.js                # Test initialization
    ├── browsers.json          # Browser configuration
    ├── global/                # Global test suites
    ├── checkout/              # Checkout flow tests
    ├── newsletter/            # Newsletter tests
    └── sign/                  # Login/registration tests
```

## Include relationship diagram

The `_base.tpl` file is the root of every page. It conditionally includes the header, the page-specific template via `{% include this.template %}`, and the footer. The checkout branch (`kosik` pages) uses simplified header/footer variants:

```
_base.tpl
├── [announcement bar]              # top info banner (from banner repository)
├── _header-checkout.tpl            # ← if on checkout (kosik) pages
│   └── kosik_kroky.tpl                  # checkout step indicators
├── _header.tpl                     # ← if on regular pages
│   ├── _menu.tpl                        # mega-menu navigation
│   ├── partials/_user-menu.tpl          # account dropdown
│   ├── partials/_user-wish.tpl          # wishlist icon
│   └── partials/_popup-cart.tpl         # mini cart popup
│
├── _breadcrumbs.tpl                # shown on most pages (not homepage/checkout)
├── {% include this.template %}     # ← system inserts the current page file
│
│   Examples of page templates:
│   ├── zbozi.tpl (product detail)
│   │   ├── _breadcrumbs.tpl             # inline breadcrumbs
│   │   ├── zbozi_imgs.tpl              # image gallery
│   │   ├── zbozi_vars.tpl             # variant selectors
│   │   ├── zbozi_komplet.tpl          # bundle products
│   │   ├── zbozi_upsells.tpl         # upsell recommendations
│   │   ├── zbozi_dostupnost.tpl      # availability details
│   │   ├── zbozi_comments.tpl        # Q&A section
│   │   └── zbozi_rating.tpl          # reviews/ratings
│   │
│   ├── vypis.tpl (category listing)
│   │   └── uses _listing.tpl (via i:list-container)
│   │
│   ├── kosik.tpl (cart router → delegates to step sub-template)
│   │   ├── kosik_obsah.tpl  ──┐
│   │   ├── kosik_udaje.tpl  ──┤ each includes:
│   │   ├── kosik_dodani.tpl ──┘ └── kosik_souhrn.tpl (order summary)
│   │   ├── kosik_prazdny.tpl    # empty cart
│   │   └── kosik_darky.tpl     # gift selection
│   │
│   └── index.tpl (homepage)
│       ├── uses _listing.tpl (via i:list-container)
│       └── partials/_footer-about.tpl
│
├── _footer.tpl                     # ← if on regular pages
│   ├── partials/_newsletter.tpl         # newsletter subscription
│   ├── _footer-usp.tpl                 # USP bar
│   └── _footer-sign.tpl                # copyright bar
├── _footer-checkout.tpl            # ← if on checkout pages
│
├── dialog/product-wish.tpl         # wishlist dialog (if enabled)
├── dialog/product-compare.tpl      # compare dialog (if enabled)
├── _bar-compare.tpl                # compare floating bar (if enabled)
└── dialog/_recommended-shop.tpl    # regional shop redirect dialog
```

The `_listing.tpl` file is special: it is never included directly via `{% include %}`. Instead, `i:list-container` components automatically use it to render each product card. Every page that shows a product grid (category, search, homepage sliders, upsells) uses the same `_listing.tpl` for consistent product card rendering. See [Product listing](/list).

## Naming conventions

* **Page templates** (`*.tpl`): each shop page has its own root file (e.g., `zbozi.tpl`, `vypis.tpl`, `kosik.tpl`)
* **Underscore prefix** (`_base.tpl`, `_header.tpl`): files starting with `_` are included by other templates and never used as standalone pages
* **Sub-templates** (`zbozi_imgs.tpl`, `kosik_obsah.tpl`): related files share a prefix with their parent page
* **Macro files** (`_macro-*.tpl`): reusable Twig macros in the root directory; the `macros/` directory holds additional macro files
* **config.json**: central template configuration file (see [Configuration](/config))

## Javascript (js/\*.js)

**All** \*.js files in the *js/* directory are sorted alphabetically, concatenated into one file, and minified. Files with an underscore prefix (e.g., `_header-sticky.js`, `_listing.js`, `_menu.js`) sort first due to alphabetical ordering, which is useful for initialization code that must run early.

## CSS (css/\*.css)

**All** \*.css files in the *css/* directory are sorted alphabetically, concatenated into one file, and minified. CSS is not processed further if a *base.scss* file exists.

## SCSS (css/\*.scss)

To use SASS, you must always have a *base.scss* file, which should import your other files.

Optionally, you can also use a *\_settings.scss* file, which should contain variables that affect the template (primary color, font sizes, breakpoints, etc.).

During compilation, *\_settings.scss* is injected before external plugins, so it can influence plugin behavior as well. This allows you to override properties of Foundation, Select2, and others.

```sass
/* automatically generated SCSS compilation template */
@import "_settings"; /* optional */
@import "/global/plugins/..."; /* automatically added plugins */
@import "base"; /* required main file */
```

The buran template organizes its SCSS files using an ITCSS-inspired layer structure inside `css/`:

| Directory       | Purpose                                              |
|-----------------|------------------------------------------------------|
| `settings/`     | Variables: breakpoints, colors, typography, spacing   |
| `tools/`        | SCSS mixins and functions                            |
| `generic/`      | CSS reset and box-sizing rules                       |
| `elements/`     | Base HTML element styles (body, headings, links)     |
| `objects/`      | Layout patterns (grid, media objects)                |
| `components/`   | BEM component styles (button, cartie, dialog, filter, listing, ...) |
| `utilities/`    | Single-purpose utility classes (spacing, visibility, colors) |

## Content grid directory

The `content-grid/` directory contains XML files that define configurable content sections. Each XML file defines fields (text, image, color, links) that shop admins can fill in through the admin panel. Templates access these values via `this.contentGrid('name')` where `name` matches the XML filename without extension (e.g., `footer-column-links.xml` is accessed as `this.contentGrid('footer-column-links')`). The buran template ships with 20 content grid definitions covering homepage, footer, checkout, product detail, and article sections. See [Content Grid](/content-grid).

## Locale directory

The `locale/` directory contains translation files organized by locale code (e.g., `cs_CZ/`, `en_GB/`, `de_DE/`). Each locale subdirectory contains an `LC_MESSAGES` directory with translation catalogs. The buran template supports 13 locales. These provide template-specific translations used with `{% trans %}` tags. System-level translations are separate.

---

---
url: /tests.md
---
# Template Testing

Documentation and articles:

* [Playwright](https://playwright.dev/docs/intro).
* [test example](https://playwright.dev/docs/writing-tests#first-test)

## Setting Up Tests

To add tests to a template downloaded from tpltest, follow these steps:

1. Install `node` and `npm`: <https://nodejs.org/en/download/> (the installer will ask about native module support — this is not needed).
2. In the template directory, create a file with the following content (if you are using the provided PhpStorm ZIP, this is already prepared):

`package.json` — after creating the file, PhpStorm will offer to install dependencies (click `Run 'npm install'`).

```json
{
  "scripts": {
    "install": "npx playwright install",
    "start-test-ui": "npx playwright test --ui",
  },
  "devDependencies": {
    "@playwright/test": "^1.54",
    "@simplia/frontend-test-data": "*"
  }
}
```

![](img/phpstorm/npm-install.png)

3. In the `tests` folder, create a file named browsers.json

This file contains the list of browsers/devices on which tests will run. Individual tests can restrict the device set.

```json
[
  "Desktop Chrome",
  "Desktop Firefox",
  "Desktop Safari",
  "Pixel 5",
  "iPhone 12"
]
```

Available devices:

```text
Blackberry PlayBook
Blackberry PlayBook landscape
BlackBerry Z30
BlackBerry Z30 landscape
Galaxy Note 3
Galaxy Note 3 landscape
Galaxy Note II
Galaxy Note II landscape
Galaxy S III
Galaxy S III landscape
Galaxy S5
Galaxy S5 landscape
Galaxy S8
Galaxy S8 landscape
Galaxy S9+
Galaxy S9+ landscape
Galaxy Tab S4
Galaxy Tab S4 landscape
iPad (gen 5)
iPad (gen 5) landscape
iPad (gen 6)
iPad (gen 6) landscape
iPad (gen 7)
iPad (gen 7) landscape
iPad Mini
iPad Mini landscape
iPad Pro 11
iPad Pro 11 landscape
iPhone 6
iPhone 6 landscape
iPhone 6 Plus
iPhone 6 Plus landscape
iPhone 7
iPhone 7 landscape
iPhone 7 Plus
iPhone 7 Plus landscape
iPhone 8
iPhone 8 landscape
iPhone 8 Plus
iPhone 8 Plus landscape
iPhone SE
iPhone SE landscape
iPhone X
iPhone X landscape
iPhone XR
iPhone XR landscape
iPhone 11
iPhone 11 landscape
iPhone 11 Pro
iPhone 11 Pro landscape
iPhone 11 Pro Max
iPhone 11 Pro Max landscape
iPhone 12
iPhone 12 landscape
iPhone 12 Pro
iPhone 12 Pro landscape
iPhone 12 Pro Max
iPhone 12 Pro Max landscape
iPhone 12 Mini
iPhone 12 Mini landscape
iPhone 13
iPhone 13 landscape
iPhone 13 Pro
iPhone 13 Pro landscape
iPhone 13 Pro Max
iPhone 13 Pro Max landscape
iPhone 13 Mini
iPhone 13 Mini landscape
iPhone 14
iPhone 14 landscape
iPhone 14 Plus
iPhone 14 Plus landscape
iPhone 14 Pro
iPhone 14 Pro landscape
iPhone 14 Pro Max
iPhone 14 Pro Max landscape
Kindle Fire HDX
Kindle Fire HDX landscape
LG Optimus L70
LG Optimus L70 landscape
Microsoft Lumia 550
Microsoft Lumia 550 landscape
Microsoft Lumia 950
Microsoft Lumia 950 landscape
Nexus 10
Nexus 10 landscape
Nexus 4
Nexus 4 landscape
Nexus 5
Nexus 5 landscape
Nexus 5X
Nexus 5X landscape
Nexus 6
Nexus 6 landscape
Nexus 6P
Nexus 6P landscape
Nexus 7
Nexus 7 landscape
Nokia Lumia 520
Nokia Lumia 520 landscape
Nokia N9
Nokia N9 landscape
Pixel 2
Pixel 2 landscape
Pixel 2 XL
Pixel 2 XL landscape
Pixel 3
Pixel 3 landscape
Pixel 4
Pixel 4 landscape
Pixel 4a (5G)
Pixel 4a (5G) landscape
Pixel 5
Pixel 5 landscape
Moto G4
Moto G4 landscape
Desktop Chrome HiDPI
Desktop Edge HiDPI
Desktop Firefox HiDPI
Desktop Safari
Desktop Chrome
Desktop Edge
Desktop Firefox
```

4. In the `tests` folder, create test files (subfolders are allowed) — the file name must always end with `.spec.js` or `.spec.ts`:

`test.spec.js`

```javascript
import {test, expect} from '@playwright/test';
import {Url} from '@simplia/frontend-test-data';

test('buy single variant on mobile', async ({page, isMobile}) => {
    const url = await Url.productWithSingleSelectedVariant();

    await page.goto(url);
    await page.waitForLoadState();

    if (await page.locator('.gdpr-cookie-bar').isVisible()) {
        await page.locator('.gdpr-cookie-bar .gdpr-cookie-confirm').click();
    }

    await page.locator('.js_koupit').getByRole('button').click();

    await expect(page.locator('.dialog-koupit .ui-dialog-title')).toBeVisible();
    await expect(page.locator('#dialog-tlacitka .button-shadow--green')).toBeVisible();
});
```

5. Running tests locally:

To open the test UI, run the following command in the terminal:

```bash
npx playwright test --ui
```

## Test URLs

Tests must not contain hardcoded URLs:

* they would not work on other tpltests
* if a product sells out, the test would stop working

A *Url* helper class is provided for use in tests, returning typed pages:

* Url.index() — home page
* Url.index({preselectGDPR: true}) — home page, but all required GDPR checkboxes or terms-of-service consents are pre-checked
* Url.productWithoutVariants() — random product without variants
* Url.productWithSingleVariant() — random product with a single variant
* Url.productWithSingleSelectedVariant() — random product with a single pre-selected variant
* Url.productWithVariants() — random product with multiple variants
* Url.productWithVariantsSelected() — random product with multiple variants and one pre-selected

All URLs can also be augmented with parameters that affect the behavior of the loaded page. For example, you can disable JavaScript and test the page as a customer on a slow connection would see it: Url.index({javascript: false})

In addition to the provided URLs, you can also navigate within a test by loading a page and clicking through menus. If you need a typed page with specific parameters, contact support to have it added.

## Input Data

For form input data, use the *Input* helper class. Unlike static data hardcoded in tests (such as a delivery address), this ensures that input data is relevant to the specific domain.

```javascript
import {Input} from '@simplia/frontend-test-data';

export default async function (page) {
    const testAddress = await Input.validAddress();

    await page.locator('.form_adresa input[name="email"]').fill(testAddress.email)
}
```

## Recommendations

Playwright is designed to navigate via button texts and verify displayed texts. For e-shops, however, this approach is not practical because products change and templates are used across e-shops in different languages.

Therefore, you should use either CSS selectors or, ideally, the `data-testid` attribute. If an element is marked in the code with `data-testid="directions"`, you can use `page.getByTestId('directions').click()` in Playwright.

Using testid has the advantage that for standard elements (such as the add-to-cart button) the same identifier can be used across templates without affecting CSS/JS. This way, a test definition can survive a redesign.

## Special Values

The email address *debug@simplia.cz* used in an order, registration, or newsletter signup will land on the confirmation page as if the action succeeded, but it can be used repeatedly without actually creating an order.

The search phrase *%debugSearchAnyResult%* always returns some result, and the phrase *%debugSearchNoResult%* never finds a product.

---

---
url: /twig.md
---
# Twig syntax

## Filters

Standard Twig filters — https://twig.symfony.com/doc/2.x/filters/index.html

## Functions

Standard Twig functions — https://twig.symfony.com/doc/2.x/functions/index.html

### newsletter\_subscribed

**Parameters of newsletter\_subscribed**

| Attribute | Description |
|---|---|
| **email** | recipient email address |

```twig
{% if not newsletter_subscribed(user.email) %}
    Subscribe to the newsletter!
{% endif %}
```

## Simplia filters

In addition to standard Twig filters, Simplia templates provide custom filters.

### Price formatting

| Filter | Description | Example |
|---|---|---|
| `cena` (price) | format price with currency | `{{ product.price\|cena }}` |
| `mena` (currency) | format price with currency (alias) | `{{ value\|mena }}` |
| `mena_rounded` (currency rounded) | rounded price with currency | `{{ value\|mena_rounded }}` |

### Text

| Filter | Description | Example |
|---|---|---|
| `orez` (trim) | truncate text to length | `{{ text\|orez(100) }}` |
| `highlight` | highlight search term | `{{ text\|highlight(query) }}` |
| `prvniVelke` (capitalize first) | capitalize first letter | `{{ text\|prvniVelke }}` |
| `diakritika` (diacritics) | remove diacritics | `{{ text\|diakritika }}` |
| `strip` | remove HTML tags | `{{ text\|strip }}` |
| `preg_replace` | regex replacement | `{{ text\|preg_replace('/pattern/', 'replacement') }}` |

### Date

| Filter | Description | Example |
|---|---|---|
| `date_locale` | localized date | `{{ date\|date_locale }}` |
| `relative_date` | relative date (2 days ago) | `{{ date\|relative_date }}` |
| `addWorkingDays` | add working days | `{{ date\|addWorkingDays(3) }}` |

### Images

| Filter | Description | Example |
|---|---|---|
| `imgSrc` | image URL at specified size | `{{ image\|imgSrc(300, 300) }}` |
| `imgSrcSet` | srcset for responsive images | `{{ image\|imgSrcSet }}` |
| `image_proxy` | URL through image proxy | `{{ url\|image_proxy }}` |
| `gravatar` | Gravatar URL for email | `{{ email\|gravatar }}` |