diff --git a/guides/plugins/apps/lifecycle/configuration.md b/guides/plugins/apps/lifecycle/configuration.md index 878fc63149..7704012745 100644 --- a/guides/plugins/apps/lifecycle/configuration.md +++ b/guides/plugins/apps/lifecycle/configuration.md @@ -13,29 +13,39 @@ Configurations for apps adhere to the same schema as [Plugin Configurations](../ ## Overview -To offer configuration possibilities to your users you can provide a `config.xml` file that describes your configuration options. You can find detailed information about the possibilities and the structure of the `config.xml` in the according documentation page. To include a `config.xml` file in your app put it into the `Resources/config` folder: +To offer configuration possibilities to your users you can provide a `config.xml` file that describes your configuration options. +You can find detailed information about the possibilities and the structure of the `config.xml` in the according documentation page. +To include a `config.xml` file in your app put it into the `Resources/config` folder: ```text ... └── DemoApp └── Resources - └── config + └── config └── config.xml └── manifest.xml ``` The configuration page will be displayed in the Administration under `Extensions > My extensions`. +See [plugin documentation](../../plugins/plugin-fundamentals/add-plugin-configuration.md) for more details and examples. For development purposes you can use the Administration component to configure plugins to provide configuration for your app, therefore use the URL `{APP_URL}/admin#/sw/extension/config/{appName}`. -If an app configuration value changes cached Storefront output, mark the corresponding `` or `` with `cache-relevant="true"` in the `config.xml`. See [Cache relevant fields](../../plugins/plugin-fundamentals/add-plugin-configuration.md#cache-relevant-fields) for details. +If an app configuration value changes cached Storefront output, mark the corresponding `` or `` with `cache-relevant="true"` in the `config.xml`. +See [Cache relevant fields](../../plugins/plugin-fundamentals/add-plugin-configuration.md#cache-relevant-fields) for details. ## Reading the configuration values -The configuration values are saved as part of the `SystemConfig` and you can use the key `{appName}.config.{fieldName}` to identify the values. There are two possibilities to access the configuration values from your app. If you need those values on your app-backend server, you can read them over the API. If you need the configuration values in your Storefront twig templates you can use the `systemConfig()`-twig function. +The configuration values are saved as part of the `SystemConfig` and you can use the key `{appName}.config.{fieldName}` to identify the values. +There are two possibilities to access the configuration values from your app. +If you need those values on your app-backend server, you can read them over the API. +If you need the configuration values in your Storefront twig templates you can use the `systemConfig()`-twig function. ### Reading the config over the API -To access your apps configuration over the API make a GET request against the `/api/_action/system-config` route. You have to add the prefix for your configuration as the `domain` query parameter. Optionally you can provide a `SalesChannelId`, if you want to read the values for a specific SalesChannel, as the `salesChannelId` query param. The API call will return a JSON-Object containing all of your configuration values. A sample Request and Response may look like this. +To access your apps configuration over the API make a GET request against the `/api/_action/system-config` route. +You have to add the prefix for your configuration as the `domain` query parameter. +Optionally you can provide a `SalesChannelId`, if you want to read the values for a specific SalesChannel, as the `salesChannelId` query param. +The API call will return a JSON-Object containing all of your configuration values. A sample Request and Response may look like this. ```txt GET /api/_action/system-config?domain=DemoApp.config&salesChannelId=98432def39fc4624b33213a56b8c944d @@ -84,7 +94,8 @@ App scripts provide access to the [`config` service](../../../../resources/refer Note that app scripts were introduced in Shopware 6.4.8.0, and are not supported in previous versions. ::: -The `config` service provides an `app()` method, that can be used to access your app's configuration. When using this method you don't need to provide the `{appName}.config` prefix and your app does not need any additional permissions. +The `config` service provides an `app()` method, that can be used to access your app's configuration. +When using this method you don't need to provide the `{appName}.config` prefix and your app does not need any additional permissions. ```twig {% set configValue = services.config.app('field1') %} diff --git a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md index 008bbb27d3..3269867933 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md @@ -46,7 +46,9 @@ As you now know how to create configurations, you can start to fill it with life The `config.xml` follows a simple syntax. You can organize the content in `` elements. -Every `config.xml` must contain at least one `` element with a `` and at least one `<input-field>`. See the minimum `config.xml` below: +Place cards directly inside `<config>` or, starting with Shopware 6.7.16.0, group them inside `<tab>` elements. + +The following minimum example contains one card with a title and an input field: ::: code-group @@ -68,6 +70,59 @@ Every `config.xml` must contain at least one `<card>` element with a `<title>` a Please make sure to specify the `xsi:noNamespaceSchemaLocation` as shown above and fetch the external resource into your IDE if possible. This enables auto-completion and suggestions for this XML file and will therefore help you to prevent issues and bugs. +### Tabs in your configuration + +::: info +Configuration tabs are available starting with Shopware 6.7.16.0. +::: + +Use `<tab>` to group related cards, with `<name>` as the technical tab name and `<title>` as its displayed label. + +Translate tab titles with the `lang` attribute, just like card titles. + +The following example combines a card outside any tab with a named tab: + +```xml +<?xml version="1.0" encoding="UTF-8"?> +<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd"> + <card> + <title>Basic settings + + enabled + + false + + + + + shipping + Shipping + Versand + + Delivery settings + + deliveryDays + + 3 + + + + +``` + +Cards outside explicit tabs are grouped into a first tab labeled **General**, followed by the explicit tabs in XML order. + +Add more `` elements inside a tab or more `` elements inside `` to organize larger forms. + +Tabs are optional, and existing configurations containing only root-level cards still work. + +The Administration displays the tab navigation only when the schema contains more than one tab. + +Tab and card names do not become part of stored configuration keys, so the fields above remain `SwagBasicExample.config.enabled` and `SwagBasicExample.config.deliveryDays`. + +For custom form consumers, see [Reading the configuration form schema](use-plugin-configuration.md#reading-the-configuration-form-schema). + ### Card Titles A `` `` is translatable, this is managed via the `lang` attribute. diff --git a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md index e46b5da98d..4b315dc98f 100644 --- a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md @@ -7,13 +7,14 @@ nav: # Use Plugin Configuration -The [Add a Plugin Configuration Guide](add-plugin-configuration.md) shows how to define configuration options in your plugins. This guide helps you to use them in your plugin, showing you how to read plugin configuration values in PHP, Administration JavaScript, and Storefront code. +The [Add a Plugin Configuration Guide](add-plugin-configuration.md) shows how to define configuration options in your plugins. +This guide helps you to use them in your plugin, showing you how to read plugin configuration values in PHP, Administration JavaScript, and Storefront code. ## Prerequisites - First, review the [Plugin Base Guide](../plugin-base-guide.md) - Then define a plugin configuration field in [Add plugin configuration](add-plugin-configuration.md) -- Get familiar with the [Listening to events](../framework/event/listening-to-events.md) guide, as in this example the configuration is read inside of a subscriber +- Get familiar with the [Listening to events](../framework/event/listening-to-events.md) guide, as in this example the configuration is read inside a subscriber The example plugin includes a subscriber that listens to the `product.loaded` event and is called every time a product is loaded. @@ -122,9 +123,12 @@ class MySubscriber implements EventSubscriberInterface The `SystemConfigService` is now available in your subscriber. -Use the `get` method to read configuration values. Calling `$this->systemConfigService->get('example')` would be ambiguous — multiple plugins could define a field with the same technical name. +Use the `get` method to read configuration values. +Calling `$this->systemConfigService->get('example')` would be ambiguous — multiple plugins could define a field with the same technical name. -To avoid conflicts, plugin configurations are always prefixed. By default, the pattern is the following: `<BundleName>.config.<configName>`. Thus, it would be `SwagBasicExample.config.example` here. +To avoid conflicts, plugin configurations are always prefixed. +By default, the pattern is the following: `<BundleName>.config.<configName>`. +Thus, it would be `SwagBasicExample.config.example` here. ```php // <plugin root>/src/Subscriber/MySubscriber.php @@ -153,6 +157,8 @@ Set `salesChannelId` to `null` to apply the configuration to all Sales Channels, In the Administration, use `systemConfigApiService` (wraps system-config endpoints). +Use `getValues()` to read saved values and `getSchema()` to read the tabs, cards, and fields that define the configuration form. + ### Using injection in Vue components ```javascript @@ -202,6 +208,91 @@ async function getPluginConfig() { Your plugin needs the `system_config:read` permission to access this API endpoint. ::: +### Reading the configuration form schema + +Starting with Shopware 6.7.16.0, use `systemConfigApiService.getSchema(domain)` to load the form definition: + +```javascript +const systemConfigApiService = Shopware.Service('systemConfigApiService'); +const domain = 'SwagBasicExample.config'; +const schema = await systemConfigApiService.getSchema(domain); +const values = await systemConfigApiService.getValues(domain); + +for (const tab of schema) { + for (const card of tab.cards) { + for (const element of card.elements) { + const value = values[element.name] ?? element.config.defaultValue; + console.log(tab.name, card.title, element.name, value); + } + } +} +``` + +The schema is an array of tabs, each containing `cards`, whose `elements` contain the field definitions. + +Field names are fully qualified configuration keys, while labels, defaults, and component options are inside `element.config`. + +The schema endpoint supplies definitions; read saved values separately with `getValues()` as above. + +API clients can retrieve the same schema with this request: + +```http +GET /api/_action/system-config/get-schema?domain=SwagBasicExample.config +``` + +Both the schema endpoint and the values endpoint require the `system_config:read` privilege. + +A response excerpt for the [tab example](add-plugin-configuration.md#tabs-in-your-configuration) looks like this: + +```json +[ + { + "name": null, + "title": null, + "cards": [ + { + "title": { "en-GB": "Basic settings" }, + "elements": [ + { + "name": "SwagBasicExample.config.enabled", + "type": "bool", + "config": { + "label": { "en-GB": "Enable integration" }, + "defaultValue": false + }, + "value": null + } + ] + } + ] + }, + { + "name": "shipping", + "title": { "en-GB": "Shipping", "de-DE": "Versand" }, + "cards": [ + { + "title": { "en-GB": "Delivery settings" }, + "elements": [ + { + "name": "SwagBasicExample.config.deliveryDays", + "type": "int", + "config": { + "label": { "en-GB": "Delivery time in days" }, + "defaultValue": 3 + }, + "value": null + } + ] + } + ] + } +] +``` + +The tab with `name: null` and `title: null` represents root-level cards and is displayed as **General** when tab navigation is visible. + +Even configurations without explicit `<tab>` elements return a tab array containing their cards. + </Tab> <Tab title="Storefront">