Documentation Update: feat(administration): shim for sfc override templates to twig templates (PR #20006)

guides/upgrades-migrations/administration/index.md

@@ -7,7 +7,9 @@ nav:
 
 # Administration
 
-These guides cover architectural changes and migration paths affecting Administration extensions, helping you prepare plugins for major system transitions. Depending on the version, some changes—for example, Vue 3, Pinia, and Vite—may have already been completed:
+These guides cover architectural changes and migration paths affecting Administration extensions, helping you prepare plugins for major system transitions. Depending on the migration stage of the component you work with, you may use native Vue extensions against fully migrated components and, for many cases, against legacy Twig-based core components through the compatibility guidance in the native Vue migration guide.
+
+Use these guides for the corresponding extension strategy:
 
 * [Vue 3 migration](./vue3)
 * [Meteor components](./meteor-components)
@@ -16,4 +18,6 @@ These guides cover architectural changes and migration paths affecting Administr
 * [Vue migration build removal](./vue-migration-build)
 * [Native Vue implementation](./vue-native)
 
+If you want to override Administration components with `.vue` files, start with [Native Vue implementation](./vue-native). That guide explains when a native override can target a legacy Twig-based core component, how Twig blocks are matched, and which Twig structures still require legacy Twig overrides.
+
 For automated detection and fixing of supported Administration migration patterns, see the [Shopware CLI automatic refactoring](../../../products/tools/cli/automatic-refactoring.md) guide.

guides/upgrades-migrations/administration/vite.md

@@ -61,6 +61,92 @@
 
 This is a very basic example. The Vite config can be much more complex and powerful. You can find more information about the Vite config in the [Vite documentation](https://vite.dev/config/). Depending on your webpack config, the migration can vary greatly.
 
+### Use native Vue overrides with legacy Twig components
+
+During the Administration migration, a plugin can use native Vue `*.override.vue` files even when the targeted core component still uses a Twig template.
+
+Use this approach when:
+
+- your extension is written as native Vue SFCs
+- the core Administration component you want to override is still Twig-based
+- a plain `*.override.vue` file would otherwise render nothing
+
+#### How to create the override
+
+1. Create an override component that targets the existing component name.
+2. Implement the desired block override in the SFC template.
+3. Build or watch the Administration as usual.
+
+Example structure:
+
+```text
+src/Resources/app/administration/src/
+├── component/
+│   └── sw-product-list/
+│       └── sw-product-list.override.vue
+└── main.ts
+```
+
+Example override:
+
+```vue
+<template>
+    <sw-block name="sw_product_list_smart_bar_actions">
+        <template #default="{ blockProps }">
+            <mt-button variant="primary">
+                My custom action
+            </mt-button>
+        </template>
+    </sw-block>
+</template>
+```
+
+Build the Administration:
+
+```bash
+composer build:js:admin
+```
+
+Or run the watcher:
+
+```bash
+composer watch:admin
+```
+
+If the targeted Twig block is supported, the override is injected into the legacy Twig component automatically.
+
+#### When to use Twig overrides instead
+
+Keep using legacy Twig-based overrides if your target block structure cannot be mapped safely into a native `sw-block` host.
+
+A known unsupported pattern is a Twig block that contains multiple named slot templates:
+
+```twig
+{% block sw_order_list_content %}
+    <template #content>
+        ...
+    </template>
+
+    <template #sidebar>
+        <sw-sidebar>
+            ...
+        </sw-sidebar>
+    </template>
+{% endblock %}
+```
+
+For structures like this, continue using the legacy Twig extension technique for that component.
+
+#### Troubleshooting native overrides against Twig components
+
+If your `*.override.vue` file is loaded but nothing is rendered:
+
+1. Confirm that the core target component is still Twig-based.
+2. Confirm that your override uses the correct Twig block name.
+3. Rebuild the Administration to ensure block detection runs again.
+4. Check whether the target block contains multiple named slot templates. If so, use a Twig-based override instead.
+5. Test with `composer watch:admin` and reload the Administration to verify the override is registered in development mode.
+
 ## Implementation details
 
 In this section, we'll document the implementation details of the new Vite setup.
@@ -90,6 +176,7 @@
 1. Get all bundles/plugins from the `<shopwareRoot>/var/plugins.json`
 2. Call `build` from Vite for each plugin
 3. The `build` function of Vite will automatically load `vite.config` files from the path of the entry file.
+4. During override processing, `*.override.vue` files are scanned for target block usage so mixed native-Vue-to-Twig override scenarios can be prepared before runtime template resolution.
 
 ### Dev mode/HMR server
 
@@ -143,7 +230,30 @@
 
 ### override-component
 
-Registering `*.override.vue` files automatically. It will search for all files matching the override pattern and automatically import them into the bundle/plugin entry file. Additionally, these imports will be registered as override components by calling `Shopware.Component.registerOverrideComponent`. This ensures that all overrides are loaded immediately when the bundle/plugin script is injected. To learn more about the new overrides, take a look at the Vue native docs right next to this file.
+Registering `*.override.vue` files automatically. It will search for all files matching the override pattern and automatically import them into the bundle/plugin entry file. Additionally, these imports will be registered as override components by calling `Shopware.Component.registerOverrideComponent`. This ensures that all overrides are loaded immediately when the bundle/plugin script is injected.
+
+When an override targets a legacy Twig-based component, the build step also analyzes the override template for referenced block names. Those targets are registered before runtime so the Twig template system can attach `sw-block` hosts where supported.
+
+Use this behavior as follows:
+
+1. Create a `*.override.vue` file for the component you want to extend.
+2. Reference the intended block explicitly in the template.
+3. Run `composer build:js:admin` or `composer watch:admin`.
+4. Verify the block is rendered in Administration.
+
+Example:
+
+```vue
+<template>
+    <sw-block name="sw_dashboard_index_content_intro_content_headline">
+        <template #default>
+            <h1>Custom headline</h1>
+        </template>
+    </sw-block>
+</template>
+```
+
+If the target is unsupported by the Twig compatibility layer, use the legacy Twig override approach for that specific component. To learn more about the new overrides, take a look at the Vue native docs right next to this file.
 
 ### twigjs
 

guides/upgrades-migrations/administration/vue-migration-build.md

@@ -142,6 +142,174 @@
 delete this.myObject.key;
 ```
 
+## Using native `.vue` overrides with legacy Twig-based administration components
+
+During the administration migration, you can write native Vue single-file component overrides even when the targeted core administration component still renders its template through Twig.
+
+Use this approach when you want to keep your extension in native `.vue` format instead of maintaining a Twig override.
+
+### When to use this approach
+
+Use a native `.vue` override if all of the following are true:
+
+- your extension is already migrated to Vue 3
+- the core administration component is still Twig-based
+- you only need to replace or extend supported Twig blocks
+- the override template renders a normal component structure without unsupported multi-slot Twig block layouts
+
+If the target Twig block is not supported by the compatibility layer, keep using the legacy Twig override technique for that component.
+
+### Basic override structure
+
+Create your administration override component in `.vue` format and target the same component name you would use for other administration overrides.
+
+Example registration:
+
+```js
+import template from './sw-product-list-override.vue';
+
+Shopware.Component.override('sw-product-list', {
+    template,
+});
+```
+
+Example override template:
+
+```vue
+<template>
+    {% block sw_product_list_grid %}
+    <div class="my-product-list-grid">
+        <sw-data-grid
+            v-bind="$attrs"
+            v-on="$attrs"
+        />
+    </div>
+    {% endblock %}
+</template>
+```
+
+### How block targeting works
+
+When you use a native `.vue` override against a Twig-based core component, the override must still target Twig block names that exist in the original core template.
+
+Use the original Twig component template to identify the correct block name:
+
+```twig
+{% block sw_product_list_grid %}
+    <sw-data-grid
+        :data-source="products"
+    />
+{% endblock %}
+```
+
+Then reference that same block in your `.vue` override:
+
+```vue
+<template>
+    {% block sw_product_list_grid %}
+    <div class="my-product-list-grid">
+        <sw-data-grid
+            :data-source="products"
+        />
+    </div>
+    {% endblock %}
+</template>
+```
+
+If the block name does not match a block in the target Twig template, your override is not rendered.
+
+### Recommended migration workflow
+
+1. Check whether the target administration component is still Twig-based.
+2. Inspect the core template and identify the block you want to override.
+3. Create a native `.vue` override and wrap your replacement content in the matching Twig block.
+4. Rebuild the administration.
+5. Verify the rendered output in the browser.
+6. If the override is not rendered, confirm that:
+   - the component name in `Shopware.Component.override(...)` is correct
+   - the Twig block name matches the core template exactly
+   - the target block does not use an unsupported slot structure
+
+### Unsupported Twig block structures
+
+Some Twig blocks cannot be targeted reliably through a native `.vue` override.
+
+In particular, avoid this approach for blocks that contain multiple named slot templates, for example:
+
+```twig
+{% block sw_order_list_content %}
+    <template #content>
+        ...
+    </template>
+
+    <template #sidebar>
+        <sw-sidebar>
+            ...
+        </sw-sidebar>
+    </template>
+{% endblock %}
+```
+
+For blocks like this, continue using a Twig-based override.
+
+### Troubleshooting native-to-Twig overrides
+
+If your native override is not rendered:
+
+- verify the override is registered with the correct component name
+- verify the targeted Twig block exists in the core component
+- verify the block is not one of the unsupported multi-slot structures
+- rebuild the administration so the override template is processed again
+- test with a minimal override first to confirm the block is reachable
+
+Minimal test override:
+
+```vue
+<template>
+    {% block sw_product_list_grid %}
+    <div style="padding: 16px; background: #ffe9a8;">
+        Override reached
+    </div>
+    {% endblock %}
+</template>
+```
+
+If the test override renders, the block is supported and your original implementation should be reviewed for template or runtime errors.
+
+## Build-time handling of override templates
+
+Administration override templates are processed during the build.
+
+For native `.vue` overrides that target Twig-based core components, the build step analyzes the override template for Twig block usage. To make this work reliably:
+
+- keep the targeted Twig block names directly inside the override template
+- avoid generating block names dynamically
+- rebuild the administration after changing block names or moving override templates
+
+A typical extension setup looks like this:
+
+```js
+import overrideTemplate from './sw-order-list-override.vue';
+
+Shopware.Component.override('sw-order-list', {
+    template: overrideTemplate,
+});
+```
+
+```vue
+<template>
+    {% block sw_order_list_actions %}
+    <div class="my-order-list-actions">
+        <sw-button size="small" variant="primary">
+            Custom action
+        </sw-button>
+    </div>
+    {% endblock %}
+</template>
+```
+
+Because block detection happens from the override template source, use explicit Twig block declarations in the file that you pass as `template`.
+
 ## Conclusion
 
 In Shopware 6.7, the Vue migration build was removed entirely. To ensure compatibility, all plugins must be updated to Vue 3 following the official migration guide. If you encounter challenges during migration, refer to the official Vue 3 documentation or seek assistance from the Shopware developer community.