Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 30 ยท Storefront

Storefront Templates with Twig

Customize the Shopware 6 storefront with Twig: sw_extends, block overrides with parent(), sw_include and page-loaded subscribers that add your data to a page.

The Shopware storefront is a Symfony application that renders Twig templates, and almost every part of it is meant to be changed without copying files. Instead of editing the core templates, a plugin ships a small template that says "I extend that page, and I replace or extend this one block". When two plugins change the same page, Shopware stacks their templates so both changes apply.

In this lesson you will learn how sw_extends and blocks work, how to add a block to the product detail page, how sw_include reuses components, and how to get your own data into a page with a page-loaded subscriber. The real templates and PHP are read-only, because Shopware cannot run on this site. The runnable examples are PHP stand-ins: a tiny block-override renderer that behaves like Twig inheritance for blocks, and a page-loaded flow. They are not Twig, and each one says what is simplified. If you have not seen Twig inheritance before, read Twig Inheritance first; for the PHP events behind page data, see Subscribers and Core Events.

Where the templates live

The storefront's templates sit in the shopware/storefront package under Resources/views/storefront. Pages are in page/, reusable pieces in component/, and the base layout is base.html.twig. In a plugin, you mirror that path under your own Resources/views/storefront folder (the exact parent folder, src/Resources/views in most plugin layouts, follows your plugin structure; see Plugin Structure and Lifecycle). To change the product detail page, create:

TEXT
AcmeBadges/
  src/
    Resources/
      views/
        storefront/
          page/
            product-detail/
              index.html.twig

The path after views/ must match the path in the core, because Shopware looks up templates by that name and then finds all templates with the same name in all active plugins and themes.

sw_extends and blocks

Shopware replaces Twig's extends with sw_extends, which builds the stack of templates for you. A minimal override (read-only):

TWIG
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}

{% block page_product_detail_buy_container %}
    {{ parent() }}

    <p class="acme-badge">Made in Germany</p>
{% endblock %}

What happens here:

  • sw_extends '@Storefront/...' names the template you extend. @Storefront is the namespace of the storefront bundle. For a plugin, always extend the core path, not your own file.
  • {% block page_product_detail_buy_container %} overrides a block defined in the parent. The name must exist in the template you extend, or nothing happens. Find the block you need by reading the core template (or by turning on the Twig debug view in development, which shows block names in the HTML as comments).
  • {{ parent() }} renders the block's content from the template below yours. With it you add to the block; without it you replace it. Beginners often forget parent() and accidentally delete the buy button.
  • Everything outside a block in a child template is ignored.

Block names in the Storefront are long on purpose, built from the page path: page_product_detail_buy_container is the container for the price and the buy button on the product detail page. Choose the smallest block that fits your change. Overriding a huge block with parent() is safe; replacing it makes your plugin conflict with other plugins that changed the same block.

flowchart TD
    A["Core template<br/>page/product-detail/index.html.twig"] --> B["Plugin A override<br/>adds a badge"]
    B --> C["Plugin B override<br/>adds a delivery note"]
    C --> D["Rendered HTML<br/>block outputs stacked via parent()"]

Each active plugin adds a layer; parent() passes control down the stack until the core block is reached.

The order of the stack follows plugin and theme priority. If two plugins both replace a block without parent(), only the one on top shows. That is one more reason to call parent() whenever you can.

A block-override stand-in

The first stand-in is a small renderer for the template idea. It is real in the rules (blocks, nesting, parent(), layers stacked bottom to top) and simplified in everything else: it does not parse Twig, there are no filters or loops, and variables are plain dotted lookups that are HTML-escaped.

PHP Stacked block overrides with parent()

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The "free shipping" note appears after the button because plugin B called parent(), and the headline lost the plain name because it did not. Remove {{ parent() }} from plugin A and the "Add to cart" button disappears. Notice also that <Chair> was escaped: Twig escapes output by default, and so does the stand-in.

Reusing components with sw_include

Large pages are built from smaller component templates. To render a component you use sw_include, the stack-aware version of include:

TWIG
{% sw_include '@Storefront/storefront/component/product/card/box.html.twig' with {
    product: product,
    layout: 'standard'
} %}

Because sw_include resolves the template through the same stack, a plugin that overrides component/product/card/box.html.twig changes every place that includes it. Use sw_include for your own partials as well, and pass data explicitly with with {...} instead of relying on variables that happen to be in scope.

Adding your own data to a page

A template can only show what the controller put into the page object. The product detail page contains the product, reviews, cross selling and more, but not your badge or ERP delivery time. You add it in PHP with a subscriber on the page-loaded event (read-only):

PHP
namespace Acme\Badges\Subscriber;

use Shopware\Core\Framework\Struct\ArrayStruct;
use Shopware\Storefront\Page\Product\ProductPageLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ProductPageSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [ProductPageLoadedEvent::class => 'onProductPageLoaded'];
    }

    public function onProductPageLoaded(ProductPageLoadedEvent $event): void
    {
        $product = $event->getPage()->getProduct();

        $event->getPage()->addExtension('acme_badge', new ArrayStruct([
            'label' => $this->labelFor($product->getId()),
        ]));
    }
}

An extension is a named bag of data attached to a Struct such as the page. It keeps your data separate from the core fields, so you cannot overwrite them by accident, and the name is global, so prefix it with your vendor. The subscriber is registered like any other (see Services and the Dependency Injection Container). In the template you read it like this:

TWIG
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}

{% block page_product_detail_buy_container %}
    {{ parent() }}

    {% set badge = page.extensions.acme_badge %}
    {% if badge and badge.label %}
        <span class="acme-badge">{{ badge.label }}</span>
    {% endif %}
{% endblock %}

Guard with {% if badge %}: a page loaded by a different path, or a failure in your subscriber, should not break the template. Keep the work in the subscriber light, because it runs on every product page view, which is among the busiest pages of a shop. Load by ids in one query, never one query per product. See Security and Performance.

For debugging, {{ dump(page.extensions) }} works when the shop runs in debug mode and shows everything you can reach from the template. If a template change does not show up, run bin/console cache:clear and check that the plugin is installed and active.

A page-loaded flow stand-in

The second stand-in models the flow: a page struct with extensions, a subscriber registered for an event, and a template that guards against a missing extension. Only the idea is real; the dispatcher and the page are minimal inventions.

PHP Page-loaded event adds an extension

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Practical tips

  • Smallest block, always parent() unless you mean to replace. This is the single most important habit.
  • Do not copy whole core templates. A copied file keeps old markup after a Shopware update and hides new core changes. Override blocks instead.
  • Use snippets for text: {{ "acme.badge.new"|trans }} with translation files, so the shop can be translated.
  • Escape by default. Output from {{ }} is escaped. Use |raw only for HTML you fully control, and sanitize merchant-entered HTML with the sanitize filter the storefront provides.
  • Think about caching. Product pages can be cached for all visitors. Data that depends on the logged-in customer must not be baked into a shared cached page; load it with JavaScript or use the cache-aware mechanisms of your version.
  • Style and behavior go into SCSS and JavaScript plugins, covered next in Styling and JavaScript in the Storefront.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does {{ parent() }} do inside an overridden block?

    parent() outputs the previous layer's version of the same block. Leaving it out replaces the block instead of extending it.
  2. 2. Where must a plugin place its override of storefront/page/product-detail/index.html.twig?

    Shopware finds templates by name, so the path under the views folder must mirror the core path.
  3. 3. How do you make your own data available in the product detail template?

    A subscriber on the page-loaded event can attach a named extension to the page, which the template reads as page.extensions.<name>.
  4. 4. Why is it risky to replace a large block without parent()?

    A replacement discards everything below it in the stack, including other plugins' additions and future core changes in that block.

Summary

  • Plugins override storefront templates by mirroring the core path and using sw_extends with the core template name.
  • Override the smallest block possible and call {{ parent() }} to add to it instead of replacing it.
  • sw_include renders components through the same stack, so overrides reach every place that uses them.
  • Add data to a page with a page-loaded subscriber and addExtension, then read page.extensions.<name> in Twig and guard against it being missing.
  • Keep subscribers cheap, escape output and never copy whole core templates.

Next, make the new markup look and behave right in Styling and JavaScript in the Storefront.