Hello World
{{ sw_block('component_product_box') }} {% endblock %} ``` ### The `sw_embed` Tag The `sw_embed` tag is a Shopware-specific wrapper for the native Twig `embed` tag. This is a powerful tag that allows you to include a template file in another template and override included blocks. It also supports multi inheritance. This is useful when: - A template is reused in multiple places (e.g., alerts or product cards). - You need to override specific blocks only in a certain context. - You want to keep the original structure but adjust parts of it. **Example: Customize an alert locally** ```twig {% sw_embed '@Storefront/storefront/utilities/alert.html.twig' with { type: 'info', heading: 'Heads up', content: 'This is the default alert content.' } %} {# Override a block to customize the content #} {% block utilities_alert_content %} {{ parent() }}Extra tip: You can add additional markup here.
{% endblock %} {% end_sw_embed %} ``` In this example: - The alert template is reused. - Only the `utilities_alert_content` block is extended. - **Other alerts in the storefront are not affected, although they use the same base template.** The key idea of `sw_embed` is to create a local variation of a template. It does not replace the original template but only modifies the embedded version inside a specific block. **Example: Adjust the product card only in the category listing** Product cards are used in many places: Category listings, cross-selling on the product detail page, CMS elements, search results, and more. Sometimes, you want to slightly change it only in one context, for example, in the category listing. ```twig {# Place this embed inside your category listing template. #} {# This example assumes `product`, `element`, and `page` are available in this context. #} {% if product is defined and element is defined and page is defined %} {% set sizes = { xs: '500px', sm: '315px', md: '390px', lg: '350px', xl: '280px' } %} {% sw_embed '@Storefront/storefront/component/product/card/box-standard.html.twig' with { product: product, element: element, page: page, layout: 'standard', sizes: sizes } %} {% block component_product_box_name %} {{ parent() }} Special Listing Label {% endblock %} {% end_sw_embed %} {% endif %} ``` In this example: - The product card template is reused as usual. - Only the product name block is extended. - The change only applies where this `sw_embed` code is placed (the category listing template). - Other usages of the product card (e.g., cross-selling on the product detail page) are not affected. In most projects, you first extend the **category listing template** with `sw_extends`. This is the place where you control how product cards are rendered in the listing. At this point, you usually have two ways to add a small change (like a badge next to the product name): **Option A: Global override (affects many places)** If you override the product card template itself (for example `box-standard.html.twig`) using `sw_extends`, the change can affect **every place** where this card is used (category listing, cross-selling, CMS elements, search results, etc.). Use this approach only if you want the same change everywhere. **Option B: Local change (only this place)** If you want the change only in the category listing, use `sw_embed` inside your listing template. The `sw_embed` keeps the original product card as the base template but lets you extend only the necessary block for this single usage. This means the change applies only to the category listing and other usages of the product card remain unchanged. **In short:** - Use `sw_extends` on the product card when you want a **global** change. - Use `sw_embed` when you want a **local** change in one specific context. #### `sw_extends` vs. `sw_embed` Both allow block overrides, but they serve different purposes: - **`sw_extends`**: - Create a new file - Override behavior globally - Used for theme/plugin customization - **`sw_embed`**: - Used directly inside a template - Override behavior locally - Used for small, contextual changes **When to use what?** - Use `sw_extends` for permanent overrides (theme/plugin level). - Use `sw_embed` for small adjustments inside a template. - Use `sw_include` if you just want to include a template without changes. This powerful tag saves a lot of time and keeps template structures clean, especially when working with reusable components. --- If you want a full overview of what Shopware provides, see: [Shopware's Twig functions](https://developer.shopware.com/docs/resources/references/storefront-reference/twig-function-reference.html). ## Further Twig Features This section focuses on writing robust and defensive templates. In real storefront projects, not every variable exists on every page type. These features help you avoid runtime errors and keep your templates stable. ### The `default` Filter You already heard the `default` filter from the previous learning path. Here, we use it defensively to provide safe fallback values when optional data is missing or empty. **Typical use cases:** - Provide a safe fallback for optional page data (e.g., meta title, teaser, custom fields). - Avoid empty headings or labels in the UI. - Ensure safe rendering when values may be missing (not defined) or `null`. ```twig {{ page.metaInformation.metaTitle|default('Shopware Storefront') }} ``` ### The `defined` Test Use `is defined` before accessing properties that may not exist on every page type. Accessing a non-existing property without guarding it may cause a runtime error. **Typical use cases:** - Guard page-specific data (e.g., `page.product` only exists on product detail pages). - Check if an extension/association was loaded. - Avoid "variable/attribute does not exist" errors in Twig. ```twig {% if page.product is defined %}{{ page.product.translated.name }}
{% endif %} ``` ### The `apply` Tag The `apply` tag lets you apply a filter to an entire block of content instead of wrapping every single expression. **Typical use cases:** - Apply filters to a snippet of markup. - Keep templates readable when you need the same transformation multiple times. ```twig {% apply upper %} This text becomes uppercase {% endapply %} ``` You can use any filter that exists in Twig/Shopware to filter entire blocks of markup. For example, you can also chain filters and pass arguments: ```twig {% apply lower|escape('html') %} SOME TEXT {% endapply %} {# outputs "<strong>some text</strong>" #} ``` ### Built-In Whitespace Control Older Twig code sometimes used the `spaceless` filter (often with `apply`) to remove whitespace between HTML tags. This approach is deprecated in modern Twig. Instead, use Twig's built-in whitespace control with `-`. The `-` trims whitespace directly around the Twig tag where it is used, including: - Line breaks - Indentation - Spaces before or after a Twig expression or control tag This is mainly useful when: - Trimming unwanted line breaks around Twig output. - Avoiding unwanted whitespace in inline elements. - Keeping loops and small fragments from adding extra empty lines. #### Whitespace Around Expressions Without whitespace control: ```twig {% set label = 'Sale' %} {{ label }} ``` Rendered HTML: ```html Sale ``` When inspected in the browser, the text is still displayed as `Sale`. The important difference is in the generated HTML: The element contains extra line breaks and indentation around the text. With whitespace control: ```twig {% set label = 'Sale' %} {{- label -}} ``` Rendered HTML: ```html Sale ``` The `-` after the opening expression delimiter removes whitespace before the expression. The `-` before the closing expression delimiter removes whitespace after the expression. #### Whitespace Around Control Tags Whitespace control also works with Twig control tags such as `if`, `for`, or `set`. Without whitespace control: ```twig-
{% for category in categories %}
- {{ category.name }} {% endfor %}
- Clothing
- Shoes
-
{%- for category in categories -%}
- {{ category.name }} {%- endfor -%}
- Clothing
- Shoes
{{ customer.firstName }} {{ customer.lastName }}
{% endif %} ``` ### The `customer` Object The `customer` object represents the currently logged-in customer (if any). It typically contains data such as: - The `firstName`, `lastName`, `email`. - Billing/shipping addresses (depending on what was loaded). - Custom fields and customer-specific metadata. **Where you usually access it:** - In most storefront pages via `context.customer` (recommended and widely available). - On account/checkout related pages it may also be available as `customer`, depending on the template. ```twig {% set customer = context.customer|default(null) %} {% if customer %}Welcome back, {{ customer.firstName }}!
{% else %} Login {% endif %} ``` ### The `product` Object The `product` object represents a product entity. Typical properties you work with in Twig are: - The `translated.name` and `translated.description`. - The `id` and `productNumber`. - The `price`, `calculatedPrice` (depending on context). - Media and cover information (depending on what was loaded). **Where you usually access it:** - On the product detail page via `page.product`. - In listings via `page.listing` (products are usually in a result/collection, not a single `product`). - In partials/components, `product` is often passed explicitly (e.g., product card). ```twig {% if page.product is defined %}{{ page.product.translated.name }}
{% endif %} ``` **Example (listing, simplified)**: ```twig {% if page.listing is defined and page.listing is iterable %} {# page.listing is a search result / collection that you can iterate over #} {% for product in page.listing %} {{ product.translated.name }} {% endfor %} {% endif %} ``` ### The `order` Object The `order` object represents an order entity. It can contain data such as: - Order number and order date/time. - Order customer data. - Addresses and deliveries. - Transactions and payment/shipping state. - Line items (products, promotions, shipping). **Where you usually access it:** - In checkout/order confirmation-related templates usually via `page.order` (depending on the route and what the page provides). - In emails, where an order is commonly passed directly as `order`. ```twig {% if page.order is defined %}Order number: {{ page.order.orderNumber }}
{% endif %} ```
{# Some Content #}
```
### When (And When Not) to Use `app`
Shopware already exposes route-related variables like `activeRoute` / `activeRouteParameters` in many core templates. Prefer those when available, and use `app.request` mainly when you explicitly need request-level data.
Twig is meant for presentation logic. Business logic should be implemented in PHP.
**Do NOT use `app` for the following:**
- Implementing business logic (price rules, permission decisions, etc.)
- Accessing customer/authentication data as your primary source of truth. Preferring `context.customer` is recommended.
- Building complex conditionals logic based on request internals.
If you need complex decisions, compute the final state in PHP (page loader, subscriber, controller) and pass the prepared data into the template.
## Summary
In this learning unit, you deepened your understanding of Twig usage in the storefront. You learned how to:
- Use Shopware-specific Twig helpers such as `seoUrl`, `rawUrl`, `theme_config`, `searchMedia`, `sw_block` and `sw_embed`.
- Apply defensive Twig patterns such as `default`, `defined`, `is iterable`, `apply`, and `json_encode` to build robust templates.
- Safely transfer data from Twig to JavaScript via `json_encode`.
- Understand how data is exposed common storefront variables such as `page`, `context`, `customer`, `product`, `order`, and `app`.
- Recognize the proper role of Twig as a presentation layer and avoid implementing business logic inside templates.
With this knowledge, you can build robust, maintainable, and update-safe storefront templates in Shopware.