From fea9932a9c80061c47080d53dbe865b5a450c9bc Mon Sep 17 00:00:00 2001 From: shopwareBot Date: Fri, 4 Sep 2026 07:04:47 +0200 Subject: [PATCH 1/5] Update guides/upgrades-migrations/administration/vue-native.md for PR #20006: feat(administration): shim for sfc override templates to twig templates --- .../administration/vue-native.md | 192 +++++++++++++++++- 1 file changed, 189 insertions(+), 3 deletions(-) diff --git a/guides/upgrades-migrations/administration/vue-native.md b/guides/upgrades-migrations/administration/vue-native.md index 4c5cd09d5c..545894d061 100644 --- a/guides/upgrades-migrations/administration/vue-native.md +++ b/guides/upgrades-migrations/administration/vue-native.md @@ -108,6 +108,126 @@ The following table shows the current status of both systems and the direction t | Twig.js blocks | Standard | Will be deprecated and removed once the migration to native blocks is complete | | Native blocks (`sw-block`) | Experimental | Will become the standard for core components and extensions | +#### Overriding Twig-based core components from native `.vue` files + +During the migration period, you can write Administration overrides as native `.vue` files even when the core component you target still uses Twig.js. + +Use this approach when: + +- your plugin already uses native Vue SFC overrides +- the core component has not yet been migrated to native blocks +- you want to keep your extension on the native override path where possible + +A native override still follows the same `*.override.vue` convention: + +```vue + + + +``` + +If the targeted Twig component contains a matching block, the override is mounted into that block during template resolution. + +#### How to choose the correct target block + +For Twig-based core components, the `extends` value must match the original Twig block name you want to replace or extend. + +Example Twig core template: + +```twig +{% block sw-text-field %} + +{% endblock %} +``` + +Matching native override: + +```vue + +``` + +If your override does not render, verify the following first: + +1. The file name matches `*.override.vue` +2. The block name in `extends` matches the Twig block name exactly +3. Your override file is part of the Administration build +4. The target block structure is supported by the compatibility bridge described below + +#### Supported migration scenario + +This hybrid setup is intended for the migration period: + +- **Core component:** Twig.js template +- **Plugin override:** native `*.override.vue` + +You can use this to migrate plugin overrides incrementally instead of waiting until every core component has been converted to native Vue blocks. + +#### Limitations of native overrides against Twig templates + +This bridge does not provide full parity with native-to-native overrides. + +Use a legacy Twig override instead if the target Twig block uses a structure that cannot host a single `sw-block` insertion point. + +In particular, blocks that contain multiple named slot templates are not supported. + +Example of an unsupported Twig block structure: + +```twig +{% block sw_order_list_content %} + + + +{% endblock %} +``` + +For blocks like this, keep using the legacy Twig-based extension technique until the core component is migrated. + +#### Troubleshooting native overrides for Twig components + +If your native override renders nothing, work through this checklist: + +1. **Check the file name** + - Use the `*.override.vue` suffix + +2. **Check the block name** + - `extends="..."` must match the Twig block exactly + +3. **Check whether the target is Twig or native** + - For native core components, use the native override path as usual + - For Twig core components, only supported block structures can be bridged + +4. **Inspect the original Twig template** + - Look for a single block content area + - If the block contains several sibling `