Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 30 ยท Administration

The Administration at a Glance

Understand the Shopware 6 Administration: a Vue single-page app with modules, components, Twig templates, snippets and ACL, plus a runnable override registry stand-in.

Everything a merchant does behind the scenes in Shopware 6, such as editing products, reading orders or switching a plugin on, happens in the Administration. It is not a set of server-rendered PHP pages. It is a single-page application written in Vue, and it talks to the shop through the Admin API you meet in The Admin API and Integrations. The PHP side only serves JSON.

This matters for plugin authors because extending the admin means writing JavaScript. You register modules (a menu entry plus pages), components (reusable Vue building blocks) and overrides (changes to components that already exist). In this lesson you learn how those pieces fit together, where plugin files live, and how to build and watch them. The next lesson, Building an Admin Module, turns this into a complete list and detail page.

The real admin code on this page is read-only, because the Administration cannot run on this site. The runnable examples are small PHP stand-ins that model one important idea: how a registry of components can be extended and overridden by many plugins at once.

How the admin is put together

The admin is built from a few layers. The core ships a bundle of modules (products, orders, customers, settings), a library of base components (sw-button, sw-card, sw-entity-listing, and many more) and services such as the repository factory. Your plugin adds its own JavaScript bundle on top. At build time everything is compiled into one set of assets that the browser loads.

flowchart TB
    B["Browser<br/>Vue single-page app"] --> M["Modules<br/>routes + navigation"]
    M --> C["Components<br/>Vue + Twig templates"]
    C --> S["Services<br/>repositoryFactory, acl, notification"]
    S --> API["Admin API<br/>JSON over HTTP"]
    P["Your plugin<br/>main.js"] -. "registers modules,<br/>components, overrides" .-> M
    P -.-> C

Plugins register code into the same module and component registries the core uses.

A plugin's admin code lives under src/Resources/app/administration/src. The entry point is main.js. Shopware looks for it by convention, so you do not declare it anywhere. A typical layout (read-only) looks like this:

TEXT
SwagBadge/
  src/Resources/app/administration/src/
    main.js
    module/
      swag-badge/
        index.js
        page/
          swag-badge-list/
            index.js
            swag-badge-list.html.twig
        snippet/
          en-GB.json
          de-DE.json
    extension/
      sw-product-list/
        index.js
        sw-product-list.html.twig

main.js simply imports the files that register things:

JavaScript
import './module/swag-badge';
import './extension/sw-product-list';

Nothing runs until something is imported. Beginners often create a file and forget the import, then wonder why nothing appears.

Components and Twig templates

A component is a JavaScript object plus a template. Shopware's admin templates are written in Twig syntax with blocks, not plain Vue templates. At build time the Twig blocks are resolved into a single Vue template string. That is what makes the next idea, overriding, possible.

You register a new component with Shopware.Component.register (read-only):

JavaScript
import template from './swag-badge-label.html.twig';

Shopware.Component.register('swag-badge-label', {
    template,

    props: {
        text: { type: String, required: true },
    },

    computed: {
        shortText() {
            return this.text.slice(0, 12);
        },
    },
});

The template is a Twig file with blocks, so others can extend it:

TWIG
{% block swag_badge_label %}
    <span class="swag-badge-label">
        {% block swag_badge_label_text %}
            {{ shortText }}
        {% endblock %}
    </span>
{% endblock %}

Block names should be unique and prefixed with your plugin name. That prefix is how other developers find and extend your blocks without collisions.

Three registration functions cover almost everything:

Function What it does
Component.register(name, config) Adds a brand-new component under a new name.
Component.extend(name, parent, config) Creates a new component that inherits from an existing one. The parent stays unchanged.
Component.override(name, config) Changes an existing component in place, for everyone who uses it.

Overriding an existing component

Overriding is how plugins add a column to the product list or a button to a page. You supply a template that replaces some of the parent's blocks, and optionally methods that wrap the parent's methods (read-only):

JavaScript
import template from './sw-product-list.html.twig';

Shopware.Component.override('sw-product-list', {
    template,

    computed: {
        productColumns() {
            const columns = this.$super('productColumns');
            columns.push({
                property: 'customFields.swag_badge_label',
                label: 'swag-badge.list.badgeColumn',
            });
            return columns;
        },
    },
});
TWIG
{% block sw_product_list_grid %}
    {% parent %}
    <p class="swag-badge-hint">{{ $tc('swag-badge.list.hint') }}</p>
{% endblock %}

Two details are worth remembering. {% parent %} outputs whatever the block contained before your override, including earlier plugins' changes. And this.$super('methodName') calls the previous version of a method or computed property. If you forget {% parent %}, you replace the block entirely and silently delete the core's content, and everyone else's overrides of that block as well.

Several plugins can override the same component. They are applied in a chain, and the result depends on the order. This is why careful plugins override a small block rather than a large one, and why they always call the parent.

The stand-in below models this chain. Templates are lists of named blocks; {{parent}} stands for the previous content. It is a simplified model of the idea, not Shopware's real template compiler.

PHP A component registry with extend and override

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.

Plugin B replaced the header without {{parent}}, so the original <h1>Products</h1> is gone. Real overrides behave the same way with {% parent %}.

A second stand-in shows the other half: a module registry that only shows a menu entry when the user's role holds the required privilege.

PHP Navigation entries filtered by privileges

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.

Hiding a menu entry is only a convenience. The Admin API must still enforce the privilege, which you will see in Security and Performance.

Snippets, ACL and the repository

Three more services appear in almost every admin extension.

Snippets are the translation files. You write JSON per language, hand them to the module and use $tc('key') in templates and this.$tc('key') in code. Never hard-code English text in templates, since the admin ships in many languages.

JSON
{
    "swag-badge": {
        "general": { "mainMenuItemGeneral": "Badges" },
        "list": { "badgeColumn": "Badge" }
    }
}

ACL (access control) decides what a role may see or do. A module declares the privilege it needs on routes and navigation entries, and templates can check acl.can('swag_badge.editor') to disable a button. Roles and privileges are managed in the admin under Users and permissions. The server checks them again for API calls.

The repository factory gives you a JavaScript counterpart of the PHP repositories from Reading and Writing with Repositories. You inject it and ask for the repository of an entity (read-only):

JavaScript
const { Criteria } = Shopware.Data;

Shopware.Component.override('sw-product-list', {
    inject: ['repositoryFactory'],

    methods: {
        loadBadgedProducts() {
            const repository = this.repositoryFactory.create('product');
            const criteria = new Criteria(1, 25);
            criteria.addFilter(Criteria.not('AND', [
                Criteria.equals('customFields.swag_badge_label', null),
            ]));
            return repository.search(criteria, Shopware.Context.api);
        },
    },
});

The Criteria object mirrors the PHP one and is sent to the search endpoint as JSON. Always pass a limit, so one call never loads the whole catalog.

Building and watching

Browsers cannot read your .twig and import files directly, so the admin has to be built. There are two modes. During development you run a watcher that rebuilds on every save and refreshes the browser, and for deployment you run a one-off production build. Your environment lesson, Setting Up a Development Environment, explains how to start the stack. The build commands live in the project's bin folder (read-only):

Terminal
bin/watch-administration.sh
bin/build-administration.sh
bin/console assets:install
bin/console cache:clear

The watcher serves the admin from a dev server with hot reload. The build script compiles production assets, assets:install copies them to public/, and the cache clear makes sure the new bundle is picked up. If your change does not appear, the usual causes are a missing import in main.js, a template block name that does not exist in the parent, or a stale cache.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What kind of application is the Shopware 6 Administration?

    The admin runs in the browser and fetches data as JSON from the Admin API. The PHP side does not render its pages.
  2. 2. What is the difference between Component.extend and Component.override?

    extend leaves the parent untouched and gives you a new name. override modifies the original, so every place that uses it sees the change.
  3. 3. You override a template block and leave out the parent tag. What happens?

    Without the parent tag you replace the block completely. Add it whenever you only want to add something.
  4. 4. Where does the plugin's admin entry point live by convention?

    Shopware picks up main.js from the plugin's administration folder. It must import every file that registers modules, components or overrides.

Summary

  • The Administration is a Vue single-page app. Plugins extend it with JavaScript, not PHP.
  • Modules add pages and navigation, components are reusable Vue pieces with Twig block templates, and overrides change existing components.
  • Use register for new components, extend for inheriting copies and override to change core components in place.
  • Always keep {% parent %} and this.$super() unless you really mean to replace the original.
  • Use snippets for text, ACL privileges for access, and the repository factory with Criteria for data.
  • Build or watch the admin, install assets and clear the cache to see changes.

Next: Building an Admin Module.