diff --git a/.gitignore b/.gitignore index ca02b484a..da4affb20 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ .idea /dictionary.dic +.DS_Store # VSCode-Project /.vscode/ -!/.vscode/settings.json \ No newline at end of file +!/.vscode/settings.json +.vscode diff --git a/.wordlist.txt b/.wordlist.txt index 15ce2c5fa..417ba51d5 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -435,6 +435,7 @@ dereferenced DESC describeFeatures destructuring +destructure Deutsch dev devenv @@ -694,6 +695,7 @@ herokuapp hideCookieBar hmac HMAC +HMR Homebrew hono Hono @@ -1065,6 +1067,7 @@ OTEL otlp OTLP oversales +overrideComponentSetup paas Paas PaaS @@ -1129,6 +1132,7 @@ PHPUnit phpunit's phpunitx PII +Pinia pluginlogger PluginManager png @@ -1159,6 +1163,7 @@ prem premapping Premapping PreparedPaymentHandlerInterface +prepend preprocessor preprocessors preselect @@ -1383,6 +1388,7 @@ setProductFixtureVisibility setSalesChannelDomain settingsItem setToInitialState +SFC SFTP sha SHA @@ -1583,6 +1589,7 @@ truthy tsx TTL TwigJS +twigjs typeAndCheck typeAndCheckSearchField TypeError @@ -1673,6 +1680,7 @@ viewportHeight viewports vimeo VirtualHosts +Vite Vitepress Vitest VM diff --git a/guides/plugins/plugins/administration/add-rule-assignment-configuration.md b/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md similarity index 99% rename from guides/plugins/plugins/administration/add-rule-assignment-configuration.md rename to guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md index 6d03f4c8c..7eb52c277 100644 --- a/guides/plugins/plugins/administration/add-rule-assignment-configuration.md +++ b/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md @@ -15,7 +15,7 @@ The rule assignment configuration is available from Shopware Version 6.4.8.0 You want to create a custom card in the rule assignment, where you can add or delete assignments? This guide gets you covered on this topic. Based on an example of the configuration of the `Dynamic Access` plugin, you will see how to write your configuration. -![Rule config](../../../../assets/add-rule-assignment-configuration-0.png) +![Rule config](../../../../../assets/add-rule-assignment-configuration-0.png) ## Prerequisites diff --git a/guides/plugins/plugins/administration/add-shortcuts.md b/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md similarity index 100% rename from guides/plugins/plugins/administration/add-shortcuts.md rename to guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md diff --git a/guides/plugins/plugins/administration/extending-webpack.md b/guides/plugins/plugins/administration/advanced-configuration/extending-webpack.md similarity index 100% rename from guides/plugins/plugins/administration/extending-webpack.md rename to guides/plugins/plugins/administration/advanced-configuration/extending-webpack.md diff --git a/guides/plugins/plugins/administration/modify-blacklist-for-dynamic-product-groups.md b/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md similarity index 100% rename from guides/plugins/plugins/administration/modify-blacklist-for-dynamic-product-groups.md rename to guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md diff --git a/guides/plugins/plugins/administration/customizing-components.md b/guides/plugins/plugins/administration/customizing-components.md deleted file mode 100644 index 514a0f309..000000000 --- a/guides/plugins/plugins/administration/customizing-components.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -nav: - title: Customizing components - position: 170 - ---- - -# Customizing components - -The Shopware 6 Administration allows you to override twig blocks to change its content. -This guide will teach you the basics of overriding parts of the Administration. - -## Prerequisites - -All you need for this guide is a running Shopware 6 instance, the files and preferably a registered module. -Of course, you'll have to understand JavaScript and have a basic familiarity with TwigJS, the templating engine, used in the Administration. -However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. - -## Finding the block to override - -In this guide we want to change the heading of the Shopware 6 dashboard to be `Welcome to a customized Administration` instead of `Welcome to Shopware 6`. -To do this we first need to find an appropriate twig block to override. -We don't want to replace too much but also to not override too little of the Administration. -In this case we only want to override the headline and not links or anything else on the page. -Looking at the twig markup for the dashboard [here](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.html.twig), -suggests that we only need to override the Twig block with the name `sw_dashboard_index_content_intro_content_headline` to achieve our goal. - -## Preparing the override - -Now that we know where to place our override, we need to decide what to override it with. -In this very simple example it suffices to create a twig file, declare a block with the name we previously found and to insert our new header into the block. - -```text - -{% block sw_dashboard_index_content_intro_content_headline %} -

- Welcome to a customized component -

-{% endblock %} -``` - -This overrides the entire Twig block with our new markup. -However, if we want to retain the original content of the Twig block and just add our markup to the existing one, we can do that by including a {% parent %} somewhere in the Twig block. -Learn more about the capabilities of twig.js [here](https://github.com/twigjs/twig.js/wiki). - -As you might have noticed the heading we just replaced had a `{ $tc() }` [string interpolation](https://vuejs.org/v2/guide/syntax.html#Text) which is used to make it multilingual. -Learn more about internationalization in the Shopware 6 Administration and about adding your own snippets to the Administration [here](adding-snippets). - -## Applying the override - -Registering the override of the Vue component is done by using the override method of our ComponentFactory. -This could be done in any `.js` file, which then has to be later imported, but we'll place it in `/src/Resources/app/administration/src/sw-dashboard-index-override/index.js`. - -```javascript -import template from './sw-dashboard-index.html.twig'; - -Shopware.Component.override('sw-dashboard-index', { - template -}); -``` - -The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties , e.g. the new twig template extension for this component. - -## Loading the JavaScript File - -The main entry point to customize the Administration via a plugin is the `main.js` file. -It has to be placed into the `/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6. - -The only thing now left to just add an import for our of previously created `./sw-dashboard-index-override/index.js` in the `main.js`: - -```javascript -import './sw-dashboard-index-override/'; -``` - -## More interesting topics - -* [Customizing templates](writing-templates) -* [Customizing via custom styles](add-custom-styles) -* [Using base components](using-base-components) diff --git a/guides/plugins/plugins/administration/handling-media.md b/guides/plugins/plugins/administration/data-handling-processing/handling-media.md similarity index 100% rename from guides/plugins/plugins/administration/handling-media.md rename to guides/plugins/plugins/administration/data-handling-processing/handling-media.md diff --git a/guides/plugins/plugins/administration/search-custom-data.md b/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md similarity index 100% rename from guides/plugins/plugins/administration/search-custom-data.md rename to guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md diff --git a/guides/plugins/plugins/administration/the-shopware-object.md b/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md similarity index 97% rename from guides/plugins/plugins/administration/the-shopware-object.md rename to guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md index 8a95d5913..0d224f6d3 100644 --- a/guides/plugins/plugins/administration/the-shopware-object.md +++ b/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md @@ -80,7 +80,7 @@ TypeScript declarations are available from Shopware Version 6.4.4.0 The Shopware Administration is written in pure JavaScript. To provide you with the benefits of TypeScript and the best possible developer experience while working in JavaScript files we're providing TypeScript declaration files within the Administration. These files are helping you to understand how the Shopware object works and what arguments you have to provide for example when you're creating a new module or registering a new component. -![TypeScript declarations example](../../../../assets/typescript-declaration-shopware-module.gif) +![TypeScript declarations example](../../../../../assets/typescript-declaration-shopware-module.gif) In the example above you can see how the TypeScript declarations are helping you to register a module. It automatically marks your code and points out what is missing. diff --git a/guides/plugins/plugins/administration/using-custom-fields.md b/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md similarity index 100% rename from guides/plugins/plugins/administration/using-custom-fields.md rename to guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md diff --git a/guides/plugins/plugins/administration/using-data-handling.md b/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md similarity index 100% rename from guides/plugins/plugins/administration/using-data-handling.md rename to guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md diff --git a/guides/plugins/plugins/administration/using-the-data-grid-component.md b/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md similarity index 100% rename from guides/plugins/plugins/administration/using-the-data-grid-component.md rename to guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md diff --git a/guides/plugins/plugins/administration/using-vuex-state.md b/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md similarity index 100% rename from guides/plugins/plugins/administration/using-vuex-state.md rename to guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md diff --git a/guides/plugins/plugins/administration/add-mixins.md b/guides/plugins/plugins/administration/mixins-directives/add-mixins.md similarity index 100% rename from guides/plugins/plugins/administration/add-mixins.md rename to guides/plugins/plugins/administration/mixins-directives/add-mixins.md diff --git a/guides/plugins/plugins/administration/adding-directives.md b/guides/plugins/plugins/administration/mixins-directives/adding-directives.md similarity index 100% rename from guides/plugins/plugins/administration/adding-directives.md rename to guides/plugins/plugins/administration/mixins-directives/adding-directives.md diff --git a/guides/plugins/plugins/administration/using-mixins.md b/guides/plugins/plugins/administration/mixins-directives/using-mixins.md similarity index 100% rename from guides/plugins/plugins/administration/using-mixins.md rename to guides/plugins/plugins/administration/mixins-directives/using-mixins.md diff --git a/guides/plugins/plugins/administration/add-custom-component.md b/guides/plugins/plugins/administration/module-component-management/add-custom-component.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-component.md rename to guides/plugins/plugins/administration/module-component-management/add-custom-component.md diff --git a/guides/plugins/plugins/administration/add-custom-field.md b/guides/plugins/plugins/administration/module-component-management/add-custom-field.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-field.md rename to guides/plugins/plugins/administration/module-component-management/add-custom-field.md diff --git a/guides/plugins/plugins/administration/add-custom-module.md b/guides/plugins/plugins/administration/module-component-management/add-custom-module.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-module.md rename to guides/plugins/plugins/administration/module-component-management/add-custom-module.md diff --git a/guides/plugins/plugins/administration/module-component-management/customizing-components.md b/guides/plugins/plugins/administration/module-component-management/customizing-components.md new file mode 100644 index 000000000..cecc40baa --- /dev/null +++ b/guides/plugins/plugins/administration/module-component-management/customizing-components.md @@ -0,0 +1,485 @@ +--- +nav: + title: Customizing components + position: 170 +--- + +# Customizing components + +The Shopware 6 Administration allows you to override and extend components to change its content and its behavior. + +## Prerequisites + +All you need for this guide is a running Shopware 6 instance, the files and preferably a registered module. +Of course, you will have to understand JavaScript, Vue and have a basic familiarity with TwigJS block system, and the templating engine used in the Administration. It is just used for the block extending and overriding. Every other feature of TwigJS is not used in the Administration. +However, that is a prerequisite for Shopware as a whole and will not be taught as part of this documentation. + +## General + +To add new functionality or change the behavior of an existing component, you can either override or extend the component. + +The difference between the two methods is that with `Component.extend()` a new component is created. With `Component.override()`, on the other hand, the previous behavior of the component is simply overwritten. + +## Override a component + +The following example shows how you can override the template of the `sw-text-field` component. + +```JS +// import the new twig-template file +import template from './sw-text-field-new.html.twig'; + +// override the existing component `sw-text-field` by passing the new configuration +Shopware.Component.override('sw-text-field', { + template +}); +``` + +## Extending a component + +To create your custom text-field `sw-custom-field` based on the existing `sw-text-field` you can implement it like the following: + +```JS +// import the custom twig-template file +import template from './sw-custom-field.html.twig'; + +// extend the existing component `sw-text-field` by passing +// a new component name and the new configuration +Shopware.Component.extend('sw-custom-field', 'sw-text-field', { + template +}); +``` + +Now you can render your new component `sw-custom-field` in any template like this: + +```twig + +``` + +## Customize a component template + +To extend a given template you can use the Twig `block` feature. + +Imagine, the component you want to extend/override has the following template: + +```twig +{% block card %} +
+ {% block card_header %} +
+ {{ header }} +
+ {% endblock %} + + {% block card_content %} +
+ {{ content }} +
+ {% endblock %} +
+{% endblock %} +``` + +Maybe you want to replace the markup of the header section and add an extra block to the content. +With the Twig `block` feature you can implement a solution like this: + +```twig +{# override/replace an existing block #} +{% block card_header %} +

+ {{ header }} +

+{% endblock %} + +{% block card_content %} + + {# render the original block #} + {% parent %} + +
+ ... +
+{% endblock %} +``` + +Summarized with the `block` feature you will be able to replace blocks inside a template. +Additionally, you can render the original markup of a block by using `{% parent %}` + +## Extending methods and computed properties + +Sometimes you need to change the logic of a method or a computed property while you are extending/overriding a component. +In the following example we extend the `sw-text-field` component and change the `onInput()` method, which gets called after the value of the input field changes. + +```JS +// extend the existing component `sw-text-field` by passing +// a new component name and the new configuration +Shopware.Component.extend('sw-custom-field', 'sw-text-field', { + + // override the logic of the onInput() method + methods: { + onInput() { + // add your custom logic in here + // ... + } + } +}); +``` + +In the previous example, the inherited logic of `onInput()` will be replaced completely. +But sometimes, you will only be able to add additional logic to the method. You can achieve this by using `this.$super()` call. + +```JS +// extend the existing component `sw-text-field` by passing +// a new component name and the new configuration +Shopware.Component.extend('sw-custom-field', 'sw-text-field', { + + // extend the logic of the onInput() method + methods: { + onInput() { + // call the original implementation of `onInput()` + const superCallResult = this.$super('onInput'); + + // add your custom logic in here + // ... + } + } +}); +``` + +This technique also works for `computed` properties, for example: + +```JS +// extend the existing component `sw-text-field` by passing +// a new component name and the new configuration +Shopware.Component.extend('sw-custom-field', 'sw-text-field', { + + // extend the logic of the computed property `stringRepresentation` + computed: { + stringRepresentation() { + // call the original implementation of `onInput()` + const superCallResult = this.$super('stringRepresentation'); + + // add your custom logic in here + // ... + } + } +}); +``` + +## Real world example for block overriding + +### Finding the block to override + +In this guide we want to change the heading of the Shopware 6 dashboard to be `Welcome to a customized Administration` instead of `Welcome to Shopware 6`. +To do this, we first need to find an appropriate twig block to override. +We don't want to replace too much but also to not override too little of the Administration. +In this case, we only want to override the headline and not links or anything else on the page. +Looking at the twig markup for the dashboard [here](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.html.twig), +suggests that we only need to override the twig block with the name `sw_dashboard_index_content_intro_content_headline` to achieve our goal. + +### Preparing the override + +Now that we know where to place our override, we need to decide what to override it with. +In this very simple example it suffices to create a twig file, declare a block with the name we previously found and to insert our new header into the block. + +```text + +{% block sw_dashboard_index_content_intro_content_headline %} +

+ Welcome to a customized component +

+{% endblock %} +``` + +This overrides the entire twig block with our new markup. +However, if we want to retain the original content of the twig block and just add our markup to the existing one, we can do that by including a {% parent %} somewhere in the twig block. +Learn more about the capabilities of twig.js [here](https://github.com/twigjs/twig.js/wiki). + +As you might have noticed the heading we just replaced had a `{ $tc() }` [string interpolation](https://vuejs.org/v2/guide/syntax.html#Text) which is used to make it multilingual. +Learn more about internationalization in the Shopware 6 Administration and about adding your own snippets to the Administration [here](adding-snippets). + +### Applying the override + +Registering the override of the Vue component is done by using the override method of our ComponentFactory. +This could be done in any `.js` file, which then has to be later imported, but we'll place it in `/src/Resources/app/administration/src/sw-dashboard-index-override/index.js`. + +```javascript +import template from './sw-dashboard-index.html.twig'; + +Shopware.Component.override('sw-dashboard-index', { + template +}); +``` + +The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties for example, the new twig template extension for this component. + +### Loading the JavaScript File + +The main entry point to customize the Administration via a plugin is the `main.js` file. +It has to be placed into the `/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6. + +The only thing now left to just add an import for our previously created `./sw-dashboard-index-override/index.js` in the `main.js`: + +```javascript +import './sw-dashboard-index-override/'; +``` + +## Experimental: Composition API extension system + +Shopware 6 is introducing a new way to extend components using the Composition API. This system is currently in an experimental state and is needed for the future migration of components from the Options API to the Composition API. + +### Current status and future plans + +- The existing Options API extension system remains fully supported and functional. +- The new Composition API extension system is introduced as an experimental feature. +- In future versions, components will gradually migrate from Options API to Composition API. +- Plugin developers are encouraged to familiarize themselves with the new system, but should continue using the current Component factory extension system for components written with the Options API. +- For components written with the Composition API, the new extension system should be used. +- In the long term, the Composition API extension system will become the standard way to override components. The Options API extension system will be deprecated and eventually removed when all components are migrated to the Composition API. + +### How it works + +The new extension system introduces two main functions: + +1. `Shopware.Component.createExtendableSetup`: Used within components to make them extendable. This will mainly be used by the core team to make components extendable. +2. `Shopware.Component.overrideComponentSetup`: Used by plugins to override components. + +### Using overrideComponentSetup + +The `overrideComponentSetup` function is a key part of the new Composition API extension system. It allows plugin developers to override or extend the behavior of existing components without directly altering their source code. + +### Basic usage + +```javascript +Shopware.Component.overrideComponentSetup()('componentName', (previousState, props, context) => { + // Your extension logic here + return { + // Return the new or modified properties and methods + }; +}); +``` + +#### Parameters + +1. `componentName`: A string identifying the component you want to override. +2. Callback function: This function receives three arguments: + 1. `previousState`: The current state of the component, including all its reactive properties and methods. + 2. `props`: The props passed to the component. + 3. `context`: The setup context, similar to what you would receive in a standard Vue 3 setup function. + +#### Return value + +The callback function should return an object containing any new or modified properties or methods you want to add or change in the component. + +#### Example: Replacing a Single Property + +```javascript +Shopware.Component.overrideComponentSetup()('sw-product-list', (previousState) => { + const newPageSize = ref(50); + + return { + pageSize: newPageSize // Override the default page size with the new ref + }; +}); +``` + +#### Example: Adding a New Method + +```javascript +Shopware.Component.overrideComponentSetup()('sw-order-list', (previousState) => { + return { + newCustomMethod() { + console.log('This is a new method added to sw-order-list'); + } + }; +}); +``` + +#### Example: Modifying existing data + +```javascript +Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState) => { + // Add a new column to the list + previousState.columns.push({ property: 'customField', label: 'Custom Field' }); + + return {}; +}); +``` + +#### Example: Overwriting a method + +```javascript +Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState) => { + // Overwrite the existing method + const newIncrement = () => { + // Able to access the previous method + previousState.increment(); + // Add custom logic + console.log('Incremented by 1'); + }; + + return { + increment: newIncrement, + }; +}); +``` + +#### Example: Accessing props and context + +```javascript +Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, props, context) => { + // Access the props + console.log(props); + + // Access the context + console.log(context); + + return {}; +}); +``` + +### Important notes + +1. Type Safety: The system aims to provide type safety. Make sure your IDE is set up to recognize the types from Shopware's type definitions. +2. Reactive Properties: When modifying reactive properties, ensure you maintain their reactivity. Use Vue's reactive utilities when necessary. +3. Multiple Overrides: Multiple plugins can override the same component. Overrides are applied in the order they are registered. +4. Performance: Be mindful of performance implications when adding complex logic to frequently used components. +5. Compatibility: This method is part of the experimental Composition API system. Ensure your plugin clearly states its dependency on this feature. +6. Testing: Thoroughly test your overrides, especially when modifying core component behavior. + +### Example real world usage + +Here is an example of how to create an extendable component and how to override it: + +```javascript +import { defineComponent, reactive } from 'vue'; + +// Original component +const originalComponent = defineComponent({ + template: ` +
+

{{ message }}

+
+ Increment + +

+ {{ countMessage }} +

+ +

+ Notifications are currently: {{ showNotification ? 'enabled' : 'disabled' }} +

+
+
+ `, + props: { + showNotification: { + type: Boolean, + default: false, + }, + }, + setup: (props, context) => Shopware.Component.createExtendableSetup({ + props, + context, + name: 'originalComponent', + }, () => { + const count = ref(0); + const message = 'Hello from Shopware!'; + const countMessage = computed(() => `The current count is: ${count.value}`); + + const increment = () => { + count.value++; + }; + + const privateExample = ref('This is a private property'); + + return { + public: { + count, + message, + countMessage, + increment, + }, + private: { + privateExample, + } + }; + }), +}); + +// Overriding the component with a plugin +Shopware.Component.overrideComponentSetup()('originalComponent', (previousState, props) => { + const newMessage = 'Hello from the plugin!'; + const newCountMessage = computed(() => `The new, amazing count is: ${previousState.count.value}`); + const newIncrement = () => { + previousState.increment(); + + if (props.showNotification) { + Shopware.ServiceContainer.get('notification').dispatch({ + title: 'Incremented!', + message: `The count has been incremented by the user to ${previousState.count.value}!`, + variant: 'success', + }); + } + }; + + return { + message: newMessage, + countMessage: newCountMessage, + increment: newIncrement, + }; +}); +``` + +In this example, `createExtendableSetup` is used to make the `originalComponent` extendable. The `overrideComponentSetup` function is then used to modify the properties of the component. In this case, the message is changed, a new computed property is added, and the increment method is modified to show a notification if the `showNotification` prop is set to `true`. + +### Key differences from Options API extension system + +- Uses Composition API syntax and reactive primitives of Vue 3 instead of Vue 2 options API. +- Extensions are applied using function composition rather than option merging. +- Provides more granular control over what parts of a component can be overridden. +- Only overrides are possible. Extending a component is not supported anymore. This can be done natively with the Composition API. + +### Using TypeScript + +To take full advantage of the Composition API extension system, it is recommended to use TypeScript. This will provide better type safety and autocompletion in your IDE and prevent common errors. + +For adding type safety to props you need to import the type of the component you want to override and use it in the `overrideComponentSetup` function as a generic type: ``. The types for the `previousState` are automatically inferred from the component you are overriding by using the correct component name. + +```typescript +import _InternalTestComponent from 'src/the/path/to/the/exported/component'; + +Shopware.Component.overrideComponentSetup()('_internal_test_compponent', (previousState, props) => { + const newBaseValue = ref(5); + const newMultipliedValue = computed(() => { + // Props are now correctly typed + return newBaseValue.value * props.multiplier!; + }); + + // Previous state is now correctly typed + previousState.baseValue.value = 2; + + return { + baseValue: newBaseValue, + multipliedValue: newMultipliedValue, + }; +}); +``` + +### Accessing private properties + +In some cases, you may need to access private properties of a component. This is not recommended, as it can lead to unexpected behavior and breakages when the component is updated. However, if you need to access private properties for debugging or testing purposes, you can do so using the `_private` property of the `previousState` object where all private properties are stored. + +Note: overriding and accessing private properties has no TS support and is not recommended for production use. + +```javascript +Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, props, context) => { + // Access the private properties + console.log(previousState._private.thePrivateProperty); +}); +``` + +## More interesting topics + +- [Customizing templates](writing-templates) +- [Customizing via custom styles](add-custom-styles) +- [Using base components](using-base-components) diff --git a/guides/plugins/plugins/administration/customizing-modules.md b/guides/plugins/plugins/administration/module-component-management/customizing-modules.md similarity index 100% rename from guides/plugins/plugins/administration/customizing-modules.md rename to guides/plugins/plugins/administration/module-component-management/customizing-modules.md diff --git a/guides/plugins/plugins/administration/using-base-components.md b/guides/plugins/plugins/administration/module-component-management/using-base-components.md similarity index 100% rename from guides/plugins/plugins/administration/using-base-components.md rename to guides/plugins/plugins/administration/module-component-management/using-base-components.md diff --git a/guides/plugins/plugins/administration/add-acl-rules.md b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md similarity index 99% rename from guides/plugins/plugins/administration/add-acl-rules.md rename to guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md index f32a579b2..bace31375 100644 --- a/guides/plugins/plugins/administration/add-acl-rules.md +++ b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md @@ -36,7 +36,7 @@ A distinction is made here between normal `permissions` and `additional_permissi ### Normal permissions -![Permissions GUI](../../../../assets/permissions-gui.png) +![Permissions GUI](../../../../../assets/permissions-gui.png) `permissions`: @@ -61,7 +61,7 @@ For each admin privilege, the needed entity privileges need to be assigned. Depe In addition to the normal `permissions`, which represent CRUD functionality, there are also `additional_permissions`. These are intended for all functions that cannot be represented by CRUD. -![Additional permissions GUI](../../../../assets/additionalPermissions-gui.png) +![Additional permissions GUI](../../../../../assets/additionalPermissions-gui.png) The `additional_permissions` have their own card below the normal permissions grid. An example for `additional_permissions` would be: "clearing the cache". This is an individual action without CRUD functionalities. The key is still used for grouping. Therefore the role can be individual and does not have to follow the scheme. diff --git a/guides/plugins/plugins/administration/add-error-handling.md b/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md similarity index 100% rename from guides/plugins/plugins/administration/add-error-handling.md rename to guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md diff --git a/guides/plugins/plugins/administration/add-custom-route.md b/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-route.md rename to guides/plugins/plugins/administration/routing-navigation/add-custom-route.md diff --git a/guides/plugins/plugins/administration/add-menu-entry.md b/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md similarity index 100% rename from guides/plugins/plugins/administration/add-menu-entry.md rename to guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md diff --git a/guides/plugins/plugins/administration/add-new-tab.md b/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md similarity index 100% rename from guides/plugins/plugins/administration/add-new-tab.md rename to guides/plugins/plugins/administration/routing-navigation/add-new-tab.md diff --git a/guides/plugins/plugins/administration/overriding-routes.md b/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md similarity index 100% rename from guides/plugins/plugins/administration/overriding-routes.md rename to guides/plugins/plugins/administration/routing-navigation/overriding-routes.md diff --git a/guides/plugins/plugins/administration/add-custom-service.md b/guides/plugins/plugins/administration/services-utilities/add-custom-service.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-service.md rename to guides/plugins/plugins/administration/services-utilities/add-custom-service.md diff --git a/guides/plugins/plugins/administration/add-filter.md b/guides/plugins/plugins/administration/services-utilities/add-filter.md similarity index 100% rename from guides/plugins/plugins/administration/add-filter.md rename to guides/plugins/plugins/administration/services-utilities/add-filter.md diff --git a/guides/plugins/plugins/administration/extending-services.md b/guides/plugins/plugins/administration/services-utilities/extending-services.md similarity index 100% rename from guides/plugins/plugins/administration/extending-services.md rename to guides/plugins/plugins/administration/services-utilities/extending-services.md diff --git a/guides/plugins/plugins/administration/injecting-services.md b/guides/plugins/plugins/administration/services-utilities/injecting-services.md similarity index 100% rename from guides/plugins/plugins/administration/injecting-services.md rename to guides/plugins/plugins/administration/services-utilities/injecting-services.md diff --git a/guides/plugins/plugins/administration/the-sanitizer-helper.md b/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md similarity index 100% rename from guides/plugins/plugins/administration/the-sanitizer-helper.md rename to guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md diff --git a/guides/plugins/plugins/administration/using-filter.md b/guides/plugins/plugins/administration/services-utilities/using-filter.md similarity index 100% rename from guides/plugins/plugins/administration/using-filter.md rename to guides/plugins/plugins/administration/services-utilities/using-filter.md diff --git a/guides/plugins/plugins/administration/using-utils.md b/guides/plugins/plugins/administration/services-utilities/using-utils.md similarity index 100% rename from guides/plugins/plugins/administration/using-utils.md rename to guides/plugins/plugins/administration/services-utilities/using-utils.md diff --git a/guides/plugins/plugins/administration/system-updates/vite.md b/guides/plugins/plugins/administration/system-updates/vite.md new file mode 100644 index 000000000..a4dc20c7e --- /dev/null +++ b/guides/plugins/plugins/administration/system-updates/vite.md @@ -0,0 +1,119 @@ +--- +nav: + title: Changing from Webpack to Vite + position: 260 +--- + +# Future Development Roadmap: Changing from Webpack to Vite + +> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change. +> This document serves as a general guideline for our development direction. + +## Introduction + +We are planning substantial changes to the way we build our Vue.js application. +The current Webpack build system has been in place for quite some time now, but like everything in tech, it becomes outdated sooner than later. Additionally to Webpack being slow and outdated, we identified a security risk for the future of our application. Many Webpack maintainers have moved on to other projects. Therefore, the Webpack project no longer receives significant updates. The same applies to the Webpack loaders we currently use. + +## Introducing Vite + +The Vue.js ecosystem has built its own bundler: Vite. Vite is fast, easier to configure and the new standard for Vue.js applications. That's why we decided to switch to Vite with Shopware 6.7. + +## Consequences for extensions + +For apps there are no consequences as your build process is already decoupled from Shopware. For plugins you only need to get active if you currently extend the webpack config by providing your own `webpack.config.js` file. + +## Implementation details + +In this section we'll document the implementation details of the new Vite setup. + +### Feature flag + +The system is already in place and can be tested by activating the feature flag: `ADMIN_VITE`. + +### Bundle information + +The information about all active bundles/plugins is written to `/var/plugins.json` by the `Shopware\Core\Framework\Plugin\Command\BundleDumpCommand`. This command can be triggered standalone by running `php bin/console bundle:dump`. It is also part of the composer commands `build:js:admin`, `build:js:storefront`, `watch:admin` and `watch:storefront`. This file is used to load all the Shopware Bundles and custom plugins. + +### Building the Shopware Administration + +The command responsible for building the Shopware Administration with all extensions remains `composer build:js:admin`. + +### Building the core + +The Vite config located under `/src/Administration/Resources/app/administration/vite.config.mts` is only responsible for the core without extensions. Currently there are a few file duplications because Vite requires different module loading order. You can recognize these files, they look like this: `*.vite.ts`. So for example the entry file `/src/Administration/Resources/app/administration/src/index.vite.ts`. + +### Building extensions + +The script responsible for building all extensions is located at `/src/Administration/Resources/app/administration/build/plugins.vite.ts`. This script uses the JS API of Vite to build all extensions. As mentioned above, it's still part of the `composer build:js:admin` command and needs no manual execution. + +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. + +### Dev mode/HMR server + +The command responsible for serving the application in dev mode (HMR server) is still `composer watch:admin`. For the core it's just going to take the `vite.config.mts` again and this time the `plugins.vite.ts` script will call `createServer` for each plugin. + +### Loading Vite assets + +Once built the right assets need to be loaded somehow into the administration. For the core we use the `pentatrion_vite` Symfony bundle. Loading the correct file(s) based on the `entrypoints.json` file generated by its counterpart `vite-plugin-symfony`. For bundles and plugins the boot process inside the `application.ts` will load and inject the entry files based on the environment. + +Production build: + +- Information is taken from the `/api/_info/config` call + +Dev mode/HMR server: + +- Information is served by our own Vite plugin `shopware-vite-plugin-serve-multiple-static` in form of the `sw-plugin-dev.json` file requested by the `application.ts` + +## Vite plugins + +To accomplish all this, we created a few Vite plugins and in this section we'll take the time to explain what they do. All our Vite plugin names are prefixed with `shopware-vite-plugin-`. I'll leave this out of the headlines for better readability. + +### asset-path + +This plugin manipulates the chunk loading function of Vite, to prepend the `window.__sw__.assetPath` to the chunk path. This is needed for cluster setups, serving the assets from a S3 bucket. + +### static-assets + +Copies static admin assets from `static` to the output directory so they can get served. + +### serve-multiple-static + +Serves static assets in dev mode (HMR server). + +### vue-globals + +Replacing all Vue imports in bundles/plugins to destructure from `Shopware.Vue`. This solves the problem of having multiple Vue instances. It does this by creating a temporary file exporting the Shopware.Vue and adding an alias to point every Vue import to that temporary file. This way it will result in bundled code like this: + +From this: + +```vue +// From this + + +// To this + +``` + +### 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 will make sure that all overrides are loaded at any time as soon as 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. + +### twigjs + +Transforming all `*.html.twig` files in a way that they can be loaded by Vite. + +## HMR reloading + +A quick note on HMR (Hot Module Replacement). Vite is only capable of reloading `*.vue` files. This means that we can only leverage the HMR by the time we transitioned everything to SFC (Single File Components) but once we do the Vite setup will be able to distinguish between changes in a plugin or the core. + +## Performance + +Vite is able to build the core Administration in ~18s on my system. This is a saving of over 50% compared to Webpack. In dev mode it's similar but not directly comparable. The Vite dev server starts instantly and moves the loading time to the first request. Webpack on the other hand compiles a long time upfront until the server is ready. diff --git a/guides/plugins/plugins/administration/system-updates/vue-native.md b/guides/plugins/plugins/administration/system-updates/vue-native.md new file mode 100644 index 000000000..99f2594b4 --- /dev/null +++ b/guides/plugins/plugins/administration/system-updates/vue-native.md @@ -0,0 +1,340 @@ +--- +nav: + title: Native Vue + position: 260 +--- + +# Future Development Roadmap: Moving Towards Vue Native + +> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change. +> This document serves as a general guideline for our development direction. + +## Introduction + +We are planning a significant shift in our development approach, moving towards a more native Vue.js implementation. +This document outlines the reasons for this change and provides an overview of our upgrade path. + +## Current status + +To better understand the changes described in this article, let's recap the current status. +The Shopware 6 Administration is built around Vue.js with several custom systems on top to allow for extensions. + +### Custom component registration + +```javascript +Shopware.Component.register('sw-component', { + template, + + //... +}); +``` + +### Custom templates with Twig.Js + +```html +{% block sw-component %} + +{% endblock %} +``` + +## Why Go Native? + +Our transition to a more native Vue.js approach is driven by several key factors: + +1. **Improved Developer Experience** + - Devtool enhancements + - Easier maintenance + +2. **Future-Proofing** + - Aligning with Vue 3 and potential future versions + - Preparing for upcoming industry standards + +3. **Performance Optimization** + - Leveraging native Vue.js capabilities for better performance + +## Major Changes + +### 1. Moving from Options API to Composition API + +#### Why Make This Change? + +We aim to better align with Vue's ecosystem, to minimize the amount of specifications new Developers need to learn. +The Composition API has become the new standard for Vue's documentation and projects all over Github. +Renowned libraries like `vue-i18n` are dropping support of the Options API, as seen in their [migration guide](https://vue-i18n.intlify.dev/guide/migration/vue3#summary), and we expect similar transitions from other tools in the ecosystem. +This also aligns with Vue's best practices, as highlighted in the official [Composition API FAQ](https://vuejs.org/guide/extras/composition-api-faq.html#why-composition-api). + +#### What Will Change? + +We will gradually transform our components from Options API to Composition API. Together with native blocks, this builds the foundation to use Single File Components (SFC). +The transformation will be stretched over multiple major versions to offer enough time for all of us to adapt. Take a look at the estimated timeline below. + +#### Upgrade Path + +| Shopware Version | Options API | Composition API | +|:----------------:|---------------------------------|------------------------------| +| 6.7 | Standard | Experimental | +| 6.8 | Still supported for extensions* | Standard for Core components | +| 6.9 | Removed completely | Standard | + +*Extensions still can register components using the Options API; overwriting Core components needs the Composition API. + +### 2. TwigJS to Native Blocks + +#### Why Make This Change? + +Vue has no native support for blocks like in Twig.js. Vue has slots, but slots don't work like blocks. +Recently, we accomplished the unthinkable and found a way to implement blocks with native Vue components. +This will allow us to finally use SFC and keep the extendability of Twig.js. +Lowering the learning curve, as the Twig.js syntax is especially unfamiliar to Vue developers. +Standard tooling like VSCode, ESLint, and Prettier will work out of the box. + +#### What Will Change? + +We will gradually transform all component templates from external `*.html.twig` files with Twig.Js into `.vue` files using the native block implementation. + +#### Upgrade Path + +| Shopware Version | Twig.Js | Native blocks | +|:----------------:|---------------------------------|------------------------------| +| 6.7 | Standard | Experimental | +| 6.8 | Still supported for extensions* | Standard for Core components | +| 6.9 | Removed completely | Standard | + +*Extensions still can register components using Twig.Js templates; overwriting Core blocks needs the native block implementation. + +### 3. Vuex to Pinia + +#### Why Make This Change? + +Vuex has been the default State management for Vue 2. For Vue 3 Pinia took it's place. + +#### What Will Change? + +We will move all core Vuex states to Pinia stores. The public API will change from `Shopware.State` to `Shopware.Store`. + +#### Upgrade Path + +| Shopware Version | Vuex | Pinia | +|:----------------:|---------------------------------|------------------------------| +| 6.7 | Still supported for extensions* | Standard for Core components | +| 6.8 | Removed completely | Standard | + +*Extensions still can register Vuex states; Accessing core stores is done via Pinia + +## Example: Component Evolution + +Now let's take a look how core and extension components will evolve. + +### Shopware 6.7 + +First we start with the current status which is still compatible with Shopware 6.7. + +#### Core component + +In the core we register a component via `Shopware.Component.register`. + +```javascript +Shopware.Component.register('sw-text-field', { + template: ` + {% block sw-text-field %} + + {% endblock %} + `, + + data() { + return { + value: null, + } + }, + + methods: { + onChange() { + this.$emit('update:value', this.value); + } + }, +}); +``` + +#### Extension override + +The extension overrides the component via `Shopware.Component.override`. + +```javascript +Shopware.Component.override('sw-text-field', { + template: ` + {% block sw-text-field %} + {% parent %} + + {{ helpText }} + {% endblock %} + `, + + props: { + helpText: { + type: String, + required: false, + } + } +}) +``` + +#### Extension new component + +The extension adds additional component via `Shopware.Component.register`. + +```javascript +Shopware.Component.register('your-crazy-ai-field', { + template: ` + {% block your-crazy-ai-field %} + {# ... #} + {% endblock %} + `, + + // Options API implementation +}) +``` + +### Shopware 6.8 + +With Shopware 6.8 the core uses single file components with the composition API. + +#### Core component + +The core component is added via a single file component `*.vue` file. + +```vue + + + +``` + +#### Extension override + +For overrides we created a new convention. They must match the `*.override.vue` pattern. +`*.override.vue` files will be loaded automatically in your main entry file. + +```vue + + + +``` + +#### Extension new component + +```javascript + +// For this you would also have the option to use a `*.vue` file but you don't have to +Shopware.Component.register('your-crazy-ai-field', { + template: ` + {% block your-crazy-ai-field %} + {# ... #} + {% endblock %} + `, + + // Options API implementation +}) +``` + +### Shopware 6.9 + +The only difference for 6.9 is that you can no longer register new components via `Shopware.Component.register`. + +## FAQ + +**Will existing extensions built with Options API continue to work in Shopware 6.8?** + +When you only use `Shopware.Component.register` yes. If you also use `Shopware.Component.extend/ override` you need to use the composition API extension approach for that. + +**How can I prepare my development team for the transition to Composition API?** + +I would recommend building a simple Vue application using the Composition API. You can do so by following [official guides](https://vuejs.org/guide/extras/composition-api-faq.html). + +**What advantages does the native block implementation offer over the current Twig.js system?** + +It works with native Vue.Js components, therefore is compatible with default tooling. + +**Can I mix Composition API and Options API components during the transition period?** + +Yes as long as you stick to the limitations from the upgrade paths. + +**How will the migration from Twig.js templates to .vue files affect my existing component overrides?** + +You need to migrate all your overrides with Shopware 6.8. + +**What tools or resources will be available to help migrate existing components?** + +We'll try to provide a code mod to transition your components into SFC. This will not work for all edge cases, so you need to manually check and transition them. + +**Will there be any performance impact during the transition period when both systems are supported?** + +During our tests we didn't experience any performance issues. + +**How does the new `Shopware.Component.createExtendableSetup` function work with TypeScript?** + +It has built in TypeScript support. + +**What happens to existing extensions using Twig.js templates after version 6.9?** + +They will stop working with Shopware version 6.9. + +**Can I start using the native blocks and Composition API in my extensions before version 6.8?** + +Yes! You can add new components using SFC and native blocks. But you can't extend core components using the old systems or vise versa. + +**Which extensions are affected by these changes?** + +- Apps aren't affected at all +- Plugins need to respect the discussed changes diff --git a/guides/plugins/plugins/administration/add-custom-styles.md b/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md similarity index 100% rename from guides/plugins/plugins/administration/add-custom-styles.md rename to guides/plugins/plugins/administration/templates-styling/add-custom-styles.md diff --git a/guides/plugins/plugins/administration/adding-snippets.md b/guides/plugins/plugins/administration/templates-styling/adding-snippets.md similarity index 100% rename from guides/plugins/plugins/administration/adding-snippets.md rename to guides/plugins/plugins/administration/templates-styling/adding-snippets.md diff --git a/guides/plugins/plugins/administration/using-assets.md b/guides/plugins/plugins/administration/templates-styling/using-assets.md similarity index 100% rename from guides/plugins/plugins/administration/using-assets.md rename to guides/plugins/plugins/administration/templates-styling/using-assets.md diff --git a/guides/plugins/plugins/administration/writing-templates.md b/guides/plugins/plugins/administration/templates-styling/writing-templates.md similarity index 100% rename from guides/plugins/plugins/administration/writing-templates.md rename to guides/plugins/plugins/administration/templates-styling/writing-templates.md diff --git a/guides/plugins/plugins/administration/adding-responsive-behavior.md b/guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md similarity index 100% rename from guides/plugins/plugins/administration/adding-responsive-behavior.md rename to guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md