diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md index 2d01354dc4..14f5abb7ae 100644 --- a/guides/upgrades-migrations/administration/index.md +++ b/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. diff --git a/guides/upgrades-migrations/administration/vite.md b/guides/upgrades-migrations/administration/vite.md index 61df8be77e..5b0446650b 100644 --- a/guides/upgrades-migrations/administration/vite.md +++ b/guides/upgrades-migrations/administration/vite.md @@ -61,6 +61,92 @@ export default defineConfig({ 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 + +``` + +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 %} + + + +{% 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 @@ The script will do the following: 1. Get all bundles/plugins from the `/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 @@ const { ref } = window['Shopware']['Vue']; ### 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 + +``` + +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 diff --git a/guides/upgrades-migrations/administration/vue-migration-build.md b/guides/upgrades-migrations/administration/vue-migration-build.md index 94a887bd3f..b629df756e 100644 --- a/guides/upgrades-migrations/administration/vue-migration-build.md +++ b/guides/upgrades-migrations/administration/vue-migration-build.md @@ -142,6 +142,174 @@ this.myObject.key = 'value'; 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 + +``` + +### 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 %} + +{% endblock %} +``` + +Then reference that same block in your `.vue` override: + +```vue + +``` + +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 %} + + + +{% 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 + +``` + +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 + +``` + +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. diff --git a/guides/upgrades-migrations/administration/vue-native.md b/guides/upgrades-migrations/administration/vue-native.md index 4c5cd09d5c..ebcbd2b4a0 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 `