docs(administration): Vue single file component extension documentation

.wordlist.txt

@@ -231,6 +231,7 @@ Codestyle
 Cognito
 CommercialB
 CommercialBundle
+CommonJS
 ComponentFactory
 Composables
 ConfigJson
@@ -1353,12 +1354,14 @@ cmss
 codebase
 codeblock
 codeblocks
+codemod
 codemods
 codereview
 colorpicker
 compatability
 componentSectionRenderer
 composable
+composables
 config
 configComponent
 configs
@@ -1450,6 +1453,7 @@ dereference
 dereferenced
 describeFeatures
 destructure
+destructured
 destructuring
 dev
 devenv
@@ -1521,6 +1525,7 @@ externalReference
 failover
 fallback
 fallbacks
+fallthrough
 fastly
 favicon
 fetchable
@@ -1644,10 +1649,12 @@ init
 initialisms
 initializer
 initializers
+inlines
 installable
 instantiation
 integrations
 interceptable
+interop
 intl
 invalidations
 io
@@ -1821,6 +1828,7 @@ otel
 otlp
 overridable
 overrideComponentSetup
+overrideable
 oversales
 paas
 packagist
@@ -2042,6 +2050,7 @@ snackbar
 snackbars
 snakeCase
 sortings
+sourcemap
 sourcemaps
 sql
 src
@@ -2087,6 +2096,8 @@ substring
 supervisord
 svg
 sw
+swDefineOverride
+swDefinePublic
 swSelect
 sw_extends
 swoole
@@ -2159,8 +2170,11 @@ unhandled
 uninstallation
 uniqBy
 unminified
+unmount
+unmounting
 unprefixed
 unregister
+unregisters
 unrequested
 unsecure
 unserialize
@@ -2176,7 +2190,27 @@ uptime
 uri
 url
 urls
+useCmsElement
+useCmsState
+useInlineSnippet
+useListing
+useMediaGridListener
+useMediaSidebarModal
+useNotification
+useNotificationTranslation
+usePlaceholder
+usePosition
+useRuleBetweenOperator
+useRuleContainer
+useSalutation
+useSwContext
+useSwPreviousState
+useSwProps
+useTranslateWithFallback
+useUserSettings
+useValidation
 useValidityRange
+useVideoCover
 userAware
 userRecovery
 userland

guides/plugins/plugins/administration/index.md

@@ -23,6 +23,8 @@ This section follows a practical development workflow. Start with registering a
 
 For stable cross-version extension points, use the [Meteor Admin SDK](../../apps/administration/meteor-admin-sdk.md). The SDK can be used by both apps and plugins.
 
+Components can also be written as native Vue [Single File Components](single-file-components/index.md). This is the experimental alternative, available since Shopware 6.7.16.0, to the Options API and TwigJS templates described in this section, which stay the stable way today. The fastest way in is the [SFC tutorial](single-file-components/tutorial/index.md).
+
 ## Developer workflow
 
 When extending the Administration inside a plugin, follow this sequence:
@@ -35,6 +37,7 @@ When extending the Administration inside a plugin, follow this sequence:
 6. [Inject services](services-utilities/injecting-services.md) and [extend services](services-utilities/extending-services.md)
 7. [Customize templates](templates-styling/writing-templates.md) and [add custom styles](templates-styling/add-custom-styles.md)
 8. Manage state using [Vuex](data-handling-processing/using-vuex-state.md) or [Pinia](../../../upgrades-migrations/administration/pinia.md)
+9. Optional: try the experimental [Single File Component extension system](single-file-components/index.md) by following its [tutorial](single-file-components/tutorial/index.md)
 
 Advanced topics such as [mixins and directives](mixins-directives/using-mixins.md) or [extending webpack](advanced-configuration/extending-webpack.md) are covered separately.
 

guides/plugins/plugins/administration/mixins-directives/using-mixins.md

@@ -7,6 +7,10 @@ nav:
 
 # Using Mixins
 
+::: info
+Mixins are the stable way to share component logic today. A Single File Component cannot use them, so the experimental Single File Component system is adding composables for the commonly used mixins. See [Composables replacing mixins](../single-file-components/roadmap.md#composables-replacing-mixins) for the current state of that list.
+:::
+
 ## Overview
 
 This guide covers how to use an existing Administration mixin in a plugin. Generally, mixins behave the same as they do in Vue normally, differing only in the registration and the way mixins are included in a component.

guides/plugins/plugins/administration/module-component-management/add-custom-component.md

@@ -7,6 +7,10 @@ nav:
 
 # Add Custom Components
 
+::: info
+The Options API registration shown on this page is the stable way to build a component today. Since Shopware 6.7.16.0, a component can also be written as a native Vue [Single File Component](../single-file-components/index.md), the experimental alternative. See the [SFC tutorial](../single-file-components/tutorial/index.md) if you want to try it.
+:::
+
 ## Overview
 
 Since the Shopware 6 Administration is using [VueJS](https://vuejs.org/) as its framework, it also supports creating custom components. This guide will teach you how to register your own custom component with your plugin.
@@ -156,5 +160,6 @@ You've now added a custom component, including a little template. However, there
 * [More about templates](../templates-styling/writing-templates.md)
 * [Add some styling to your component](../templates-styling/add-custom-styles.md)
 * [Use shortcuts for your component](../advanced-configuration/add-shortcuts.md)
+* [Build the same component as an experimental Single File Component](../single-file-components/tutorial/build-your-own-component.md)
 
 Furthermore, what about [customizing other components](customizing-components.md), instead of creating new ones?

guides/plugins/plugins/administration/module-component-management/customizing-components.md

@@ -6,6 +6,10 @@ nav:
 
 # Customizing Components
 
+::: info
+`Component.override()` with TwigJS blocks, as shown on this page, is the stable way to customize a component today. Its counterpart in the experimental Single File Component system, available since Shopware 6.7.16.0, is an `.override.vue` file using `<sw-block extends>`. See [Chapter 2: Your first override](../single-file-components/tutorial/your-first-override.md).
+:::
+
 ## Overview
 
 The Shopware 6 Administration allows you to override and extend components to change its content and its behavior.

guides/plugins/plugins/administration/single-file-components/api-reference/block-components/index.md

@@ -0,0 +1,51 @@
+---
+nav:
+  title: Block components
+  position: 30
+
+---
+
+# Block components
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+Two globally registered components carry the native block system. You write the tags without importing anything.
+
+<PageRef page="sw-block" title="sw-block" sub="Declare an extension point, or contribute to one" />
+<PageRef page="sw-block-parent" title="sw-block-parent" sub="Render what the extension point held before you" />
+
+## The model
+
+A component **declares** an extension point by wrapping markup in `<sw-block name="…">`. Its children are the default content, and with nothing registered against the name it renders as though the wrapper were not there.
+
+An override **contributes** to that point with `<sw-block extends="…">`. That tag renders nothing where it stands: it registers its content, and the matching `<sw-block name>` renders it wherever that happens to be.
+
+```html
+<!-- swag-greeting-card.vue -->
+<sw-block name="swag_greeting_card_body">
+    <p>Default content</p>
+</sw-block>
+
+<!-- swag-greeting-card.override.vue -->
+<sw-block extends="swag_greeting_card_body">
+    <sw-block-parent />
+    <p>Mine, underneath</p>
+</sw-block>
+```
+
+## Names
+
+A block name is a plain string and nothing validates it, so a typo matches nothing and fails silently. Names must be unique per component.
+
+The convention is an owner prefix, then the path through the component, in `snake_case`:
+
+```text
+sw_product_detail_base_price_form
+swag_greeting_card_body
+```
+
+Core uses `sw_`; a plugin uses its own prefix. A block name you find in core is covered by the backwards-compatibility promise: it stays until the next major version, and if one is removed in a major, the changelog names it. When core converts a component to a Single File Component, its block names stay the same.
+
+## Chains
+
+Several overrides may target one block. They stack in registration order, and each one's `<sw-block-parent />` renders the previous one's output rather than the original default. Leaving `<sw-block-parent />` out replaces everything below it, which is how one plugin removes another plugin's contribution.

guides/plugins/plugins/administration/single-file-components/api-reference/block-components/sw-block-parent.md

@@ -0,0 +1,47 @@
+---
+nav:
+  title: sw-block-parent
+  position: 70
+
+---
+
+# `sw-block-parent`
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+```html
+<sw-block-parent />
+```
+
+Takes no props. Renders whatever the extension point held before this override: the default content, or the previous override in the chain. Globally registered, so you write the tag without importing anything.
+
+Leave it out and the original markup is replaced.
+
+## Position decides yours
+
+```html
+<!-- append -->
+<sw-block extends="swag_greeting_card_body">
+    <sw-block-parent />
+    <p>I go after</p>
+</sw-block>
+
+<!-- prepend -->
+<sw-block extends="swag_greeting_card_body">
+    <p>I go before</p>
+    <sw-block-parent />
+</sw-block>
+
+<!-- replace -->
+<sw-block extends="swag_greeting_card_body">
+    <p>The original content is gone</p>
+</sw-block>
+```
+
+## Render it once, unconditionally
+
+It claims its position in the chain when it is created, so a `v-if` on it, or a `v-for` around it, corrupts that chain. One `<sw-block-parent />` per extending block, always rendered.
+
+## Chains
+
+When several overrides target one block they stack, and each one's `<sw-block-parent />` renders the previous one's output rather than the original default. That is what keeps other plugins on the page when your own change is additive.

guides/plugins/plugins/administration/single-file-components/api-reference/block-components/sw-block.md

@@ -0,0 +1,61 @@
+---
+nav:
+  title: sw-block
+  position: 60
+
+---
+
+# `sw-block`
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+The extension point. Globally registered, so you write the tag without importing anything. Which prop you pass decides what it does.
+
+| Prop      | Type     | Meaning                                                                              |
+| --------- | -------- | ------------------------------------------------------------------------------------ |
+| `name`    | `string` | **Declares** an extension point. Its children are the default content                |
+| `extends` | `string` | **Contributes** to the extension point of that name. Renders nothing where it stands |
+
+Write `name` (base components only) or `extends` (overrides only) as a static attribute and nothing else. The component has other props - your editor may offer them - and they are internal. The build rejects any other attribute or directive on the tag, including `class`, `v-if`, a bound `:extends`, `data`, `v-bind` and an authored `#default`.
+
+## Declaring an extension point
+
+```html
+<sw-block name="swag_greeting_card_body">
+    <p>Default content</p>
+</sw-block>
+```
+
+With nothing registered against the name, this renders as though the wrapper were not there.
+
+## Contributing to one
+
+```html
+<sw-block extends="swag_greeting_card_body">
+    <sw-block-parent />
+    <p>Mine, underneath</p>
+</sw-block>
+```
+
+The target block is replaced by what goes inside. To keep what was there, render [`sw-block-parent`](sw-block-parent).
+
+An `<sw-block extends>` belongs at the root of an override's template and cannot be nested inside another element. Where it sits does not affect where its content renders: it registers the content, and the matching `<sw-block name>` renders it.
+
+## Names
+
+Block names are strings and nothing validates them, so a typo silently matches nothing. They must be unique per component. The convention is an owner prefix and then the path through the component, in `snake_case`: core uses `sw_`, a plugin uses its own.
+
+```text
+sw_product_detail_base_price_form
+swag_greeting_card_body
+```
+
+## Bindings in block content
+
+Your override's bindings are available inside its `<sw-block extends>` content and read like any other Vue template binding. Mutating one from the template - `@click="counter++"` - is not supported; wrap the mutation in a function and call that instead.
+
+## Order, when several extensions meet
+
+Native `<sw-block extends>` contributions render in registration order, and all of them render after a TwigJS override of the same block. A legacy override is therefore always the parent of a native one, whichever order the plugins load in.
+
+<PageRef page="../../internals" title="Internals" sub="How the chain is assembled, and why the order is what it is" />