From b3c0e8803aca5d1aa5c9c549b35aec73bf60bb5e Mon Sep 17 00:00:00 2001 From: LApple Date: Mon, 16 Mar 2026 18:39:21 +0100 Subject: [PATCH 01/59] chore: revises docs --- docs/admin-sdk/README.md | 2 +- docs/admin-sdk/api-reference/base-options.md | 6 +- docs/admin-sdk/api-reference/cms/index.md | 5 - .../composables/getRepository.md | 0 .../api-reference/composables/index.md | 5 - docs/admin-sdk/api-reference/data/get.md | 21 +- .../api-reference/data/in-app-purchases.md | 31 +++ docs/admin-sdk/api-reference/data/index.md | 24 +- .../api-reference/data/repository.md | 7 + .../admin-sdk/api-reference/data/subscribe.md | 19 +- docs/admin-sdk/api-reference/data/update.md | 16 +- .../in-app-purchases/in-app-purchases.md | 19 -- .../api-reference/in-app-purchases/index.md | 5 - docs/admin-sdk/api-reference/index.md | 84 ++++++- .../api-reference/ui/actionButton.md | 30 ++- .../{ => ui}/assets/sidebar-example.png | Bin ...onent-section.md => component-sections.md} | 31 ++- docs/admin-sdk/api-reference/ui/index.md | 47 +++- docs/admin-sdk/api-reference/ui/mainModule.md | 47 +++- docs/admin-sdk/api-reference/ui/mediaModal.md | 29 ++- docs/admin-sdk/api-reference/ui/menu.md | 28 ++- docs/admin-sdk/api-reference/ui/modals.md | 49 ++-- .../api-reference/ui/module/index.md | 3 - .../ui/{module => }/paymentOverviewCard.md | 24 +- .../api-reference/ui/settingsItem.md | 30 ++- docs/admin-sdk/api-reference/ui/sidebars.md | 31 ++- docs/admin-sdk/api-reference/ui/tabs.md | 23 +- docs/admin-sdk/api-reference/window.md | 115 --------- .../architecture.md} | 17 +- .../assets/devtool-example.png | Bin .../assets/post-message-communication.png | Bin docs/admin-sdk/concepts/component-sections.md | 23 +- .../{internals => concepts}/datahandling.md | 15 +- docs/admin-sdk/concepts/index.md | 17 +- docs/admin-sdk/concepts/locations.md | 37 ++- docs/admin-sdk/concepts/positions.md | 29 ++- docs/admin-sdk/concepts/selectors.md | 98 ++++++-- ...tools-plugin-extension-point-selection.png | Bin .../assets/devtools-plugin-settings-list.png | Bin .../assets/devtools-plugin-settings.png | Bin ...devtools-plugin-tab-shopware-extension.png | Bin .../assets/devtools-plugin.png | Bin .../assets/devtools-usage.png | Bin .../assets/notification-example.jpg | Bin .../assets/register-cms-block-example.png | Bin .../assets/register-cms-element-example.png | Bin .../assets/toast-example.png | Bin .../assets/useSharedState-demo.gif | Bin docs/admin-sdk/develop/cms/index.md | 10 + .../cms/registerCmsBlock.md | 12 +- .../cms/registerCmsElement.md | 12 +- docs/admin-sdk/develop/composables/index.md | 17 ++ .../composables/useRepository.md | 22 +- .../composables/useSharedState.md | 14 +- .../{api-reference => develop}/context.md | 6 + docs/admin-sdk/develop/devtools.md | 80 ++++++ docs/admin-sdk/develop/entity-types.md | 94 +++++++ docs/admin-sdk/develop/index.md | 53 ++++ .../{api-reference => develop}/location.md | 98 ++++---- .../develop/migrating-admin-plugins.md | 98 ++++++++ .../notification.md | 21 +- .../{api-reference => develop}/toast.md | 26 +- docs/admin-sdk/develop/translations.md | 50 ++++ docs/admin-sdk/develop/window.md | 148 +++++++++++ docs/admin-sdk/faq/index.md | 49 ---- docs/admin-sdk/getting-started/devTools.md | 30 --- docs/admin-sdk/getting-started/index.md | 118 ++++++++- .../getting-started/installation-apps.md | 152 ++++++++++++ .../getting-started/installation-plugins.md | 114 +++++++++ .../admin-sdk/getting-started/installation.md | 229 ------------------ docs/admin-sdk/getting-started/usage.md | 110 ++------- docs/admin-sdk/index.md | 94 ++----- docs/admin-sdk/internals/index.md | 5 - docs/admin-sdk/tooling/index.md | 5 - docs/admin-sdk/tooling/vue-devtools.md | 34 --- examples/admin-sdk-plugin/README.md | 3 +- 76 files changed, 1777 insertions(+), 894 deletions(-) delete mode 100644 docs/admin-sdk/api-reference/cms/index.md delete mode 100644 docs/admin-sdk/api-reference/composables/getRepository.md delete mode 100644 docs/admin-sdk/api-reference/composables/index.md create mode 100644 docs/admin-sdk/api-reference/data/in-app-purchases.md delete mode 100644 docs/admin-sdk/api-reference/in-app-purchases/in-app-purchases.md delete mode 100644 docs/admin-sdk/api-reference/in-app-purchases/index.md rename docs/admin-sdk/api-reference/{ => ui}/assets/sidebar-example.png (100%) rename docs/admin-sdk/api-reference/ui/{component-section.md => component-sections.md} (84%) delete mode 100644 docs/admin-sdk/api-reference/ui/module/index.md rename docs/admin-sdk/api-reference/ui/{module => }/paymentOverviewCard.md (80%) delete mode 100644 docs/admin-sdk/api-reference/window.md rename docs/admin-sdk/{internals/how-it-works.md => concepts/architecture.md} (96%) rename docs/admin-sdk/{internals => concepts}/assets/devtool-example.png (100%) rename docs/admin-sdk/{internals => concepts}/assets/post-message-communication.png (100%) rename docs/admin-sdk/{internals => concepts}/datahandling.md (86%) rename docs/admin-sdk/{tooling => develop}/assets/devtools-plugin-extension-point-selection.png (100%) rename docs/admin-sdk/{tooling => develop}/assets/devtools-plugin-settings-list.png (100%) rename docs/admin-sdk/{tooling => develop}/assets/devtools-plugin-settings.png (100%) rename docs/admin-sdk/{tooling => develop}/assets/devtools-plugin-tab-shopware-extension.png (100%) rename docs/admin-sdk/{getting-started => develop}/assets/devtools-plugin.png (100%) rename docs/admin-sdk/{getting-started => develop}/assets/devtools-usage.png (100%) rename docs/admin-sdk/{api-reference => develop}/assets/notification-example.jpg (100%) rename docs/admin-sdk/{api-reference => develop}/assets/register-cms-block-example.png (100%) rename docs/admin-sdk/{api-reference => develop}/assets/register-cms-element-example.png (100%) rename docs/admin-sdk/{api-reference => develop}/assets/toast-example.png (100%) rename docs/admin-sdk/{api-reference => develop}/assets/useSharedState-demo.gif (100%) create mode 100644 docs/admin-sdk/develop/cms/index.md rename docs/admin-sdk/{api-reference => develop}/cms/registerCmsBlock.md (98%) rename docs/admin-sdk/{api-reference => develop}/cms/registerCmsElement.md (93%) create mode 100644 docs/admin-sdk/develop/composables/index.md rename docs/admin-sdk/{api-reference => develop}/composables/useRepository.md (91%) rename docs/admin-sdk/{api-reference => develop}/composables/useSharedState.md (92%) rename docs/admin-sdk/{api-reference => develop}/context.md (99%) create mode 100644 docs/admin-sdk/develop/devtools.md create mode 100644 docs/admin-sdk/develop/entity-types.md create mode 100644 docs/admin-sdk/develop/index.md rename docs/admin-sdk/{api-reference => develop}/location.md (66%) create mode 100644 docs/admin-sdk/develop/migrating-admin-plugins.md rename docs/admin-sdk/{api-reference => develop}/notification.md (87%) rename docs/admin-sdk/{api-reference => develop}/toast.md (65%) create mode 100644 docs/admin-sdk/develop/translations.md create mode 100644 docs/admin-sdk/develop/window.md delete mode 100644 docs/admin-sdk/faq/index.md delete mode 100644 docs/admin-sdk/getting-started/devTools.md create mode 100644 docs/admin-sdk/getting-started/installation-apps.md create mode 100644 docs/admin-sdk/getting-started/installation-plugins.md delete mode 100644 docs/admin-sdk/getting-started/installation.md delete mode 100644 docs/admin-sdk/internals/index.md delete mode 100644 docs/admin-sdk/tooling/index.md delete mode 100644 docs/admin-sdk/tooling/vue-devtools.md diff --git a/docs/admin-sdk/README.md b/docs/admin-sdk/README.md index 3afcca565..bb8f7d16e 100644 --- a/docs/admin-sdk/README.md +++ b/docs/admin-sdk/README.md @@ -28,4 +28,4 @@ pnpm docs:link ``` pnpm docs:preview -``` \ No newline at end of file +``` diff --git a/docs/admin-sdk/api-reference/base-options.md b/docs/admin-sdk/api-reference/base-options.md index 2bf5f5f9a..f92acd8e7 100644 --- a/docs/admin-sdk/api-reference/base-options.md +++ b/docs/admin-sdk/api-reference/base-options.md @@ -1,11 +1,13 @@ -# Base options -There are options that exist for every message type in the SDK. You'll find a list with all of them below. +# Base Options + +These options are supported by multiple SDK APIs and modify how messages are executed in the Shopware Administration. | Name | Required | Default | Availability | Description | | :----------- | :------- | :------------- | :------------------ | :---------------------------------------------------------------------------------------------- | | `privileges` | false | | >= Shopware 6.6.3.0 | The privileges that will be checked before executing the message in the Shopware Administration | ## Example privileges + ```typescript import * as sw from '@shopware-ag/meteor-admin-sdk'; diff --git a/docs/admin-sdk/api-reference/cms/index.md b/docs/admin-sdk/api-reference/cms/index.md deleted file mode 100644 index bd17294ed..000000000 --- a/docs/admin-sdk/api-reference/cms/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CMS" -nav: - position: 300 ---- diff --git a/docs/admin-sdk/api-reference/composables/getRepository.md b/docs/admin-sdk/api-reference/composables/getRepository.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/admin-sdk/api-reference/composables/index.md b/docs/admin-sdk/api-reference/composables/index.md deleted file mode 100644 index c3d9fb086..000000000 --- a/docs/admin-sdk/api-reference/composables/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Vue Composables" -nav: - position: 400 ---- diff --git a/docs/admin-sdk/api-reference/data/get.md b/docs/admin-sdk/api-reference/data/get.md index e77c2cb3b..09a659e83 100644 --- a/docs/admin-sdk/api-reference/data/get.md +++ b/docs/admin-sdk/api-reference/data/get.md @@ -1,12 +1,17 @@ +--- +title: "Get" +nav: + position: 30 +--- + # Get -With `data.get` you can receive datasets from the Shopware administration. -More information on how to find the unique identifiers can be found in [this guide](../../internals/datahandling.md). +With `data.get` you can receive datasets from the Shopware Administration. More information on how to find the unique identifiers can be found in [the data-handling guide](../../concepts/datahandling.md). + +Compared to `data.subscribe`, `data.get` only gives you the current state of the data. If the data is not available yet, such as when opening a page, you won't receive any data. In these cases, it's better to subscribe to data changes instead. -Compared to data.subscribe, data.get only gives you the current state of the data. If the data is not available yet, -such as when opening a page, you won't receive any data. In these cases, it's better to subscribe to data changes instead. +## Usage -#### Usage: ```ts data.get({ id: 'sw-product-detail__product', @@ -16,7 +21,8 @@ data.get({ }); ``` -#### Output: +## Output + ```json { "name": "Ergonomic Copper Mr. Frenzy", @@ -26,7 +32,8 @@ data.get({ } ``` -#### Parameters +## Parameters + | Name | Required | Description | | :-------- | :------- |:---------------------------------------------------------------------------------------------------------------------| | `options` | true | Containing the unique `id` and optional `selectors`. Read more about selectors [here](../../concepts/selectors.md) | diff --git a/docs/admin-sdk/api-reference/data/in-app-purchases.md b/docs/admin-sdk/api-reference/data/in-app-purchases.md new file mode 100644 index 000000000..5e6682517 --- /dev/null +++ b/docs/admin-sdk/api-reference/data/in-app-purchases.md @@ -0,0 +1,31 @@ +--- +title: "In-App Purchases" +nav: + position: 60 +--- + + +# In-App Purchases + +> Available since Shopware v6.6.9.0 +> +In-App purchases allow apps to unlock different functionality based on purchases made by the user. This guide covers how to start the in-app purchase flow directly from the Administration. + +## Start the purchase flow + +To open a modal with details about the feature that can be purchased: + +```ts +sw.iap.purchase({ + identifier: 'your-in-app-purchase-id', +}); +``` + +## Behavior + +When called, Shopware opens a purchase modal inside the Administration. The modal guides the merchant through the checkout flow for purchasing or subscribing to the feature. + +After a successful purchase: + +- The charge is added to the merchant's Shopware bill +- The purchased feature becomes available in the app. diff --git a/docs/admin-sdk/api-reference/data/index.md b/docs/admin-sdk/api-reference/data/index.md index 3cdc8aff9..c9c30ab68 100644 --- a/docs/admin-sdk/api-reference/data/index.md +++ b/docs/admin-sdk/api-reference/data/index.md @@ -1,5 +1,25 @@ --- -title: "Data" +title: "Working with Data" nav: - position: 200 + position: 10 --- + + +# Working with Data + +The Meteor Admin SDK provides APIs for accessing and manipulating Shopware data from within the Administration. These APIs allow extensions to interact with Shopware entities, react to changes in data, and update records using the same repository-based data layer used by the Administration itself. + +Typical data workflows follow this pattern: + +1. Access an entity repository +2. Retrieve entities or collections +3. Subscribe to updates or changes +4. Modify or persist data + +## Available APIs + +- [Repository](./repository.md): Access Shopware entity repositories. +- [Get](./get.md): Retrieve entity data from the Administration data layer. +- [Subscribe](./subscribe.md): React to changes in entity data. +- [Update](./update.md): Modify and persist entity data. +- [In-App Purchases](./in-app-purchases.md): APIs for working with Shopware in-app purchase functionality. diff --git a/docs/admin-sdk/api-reference/data/repository.md b/docs/admin-sdk/api-reference/data/repository.md index f65c745ff..b7b92780f 100644 --- a/docs/admin-sdk/api-reference/data/repository.md +++ b/docs/admin-sdk/api-reference/data/repository.md @@ -1,3 +1,10 @@ +--- +title: "Repository" +nav: + position: 20 +--- + + # Repository The data handling of the SDK allows you to fetch and write nearly everything in the database. The behavior matches the data handling in the main administration. The only difference is the implementation details because the data handling don't request the server directly. It communicates with the admin which handles the requests, changesets, saving and more. diff --git a/docs/admin-sdk/api-reference/data/subscribe.md b/docs/admin-sdk/api-reference/data/subscribe.md index 716d55a93..0d88bb036 100644 --- a/docs/admin-sdk/api-reference/data/subscribe.md +++ b/docs/admin-sdk/api-reference/data/subscribe.md @@ -1,9 +1,16 @@ +--- +title: "Subscribe" +nav: + position: 40 +--- + + # Subscribe -With `data.subscribe` you can subscribe to dataset changes. The callback will be called every time, the dataset with the matching id is changed. -More information on how to find the unique identifiers can be found in [this guide](../../internals/datahandling.md). +With `data.subscribe` you can subscribe to dataset changes. The callback will be called every time, the dataset with the matching id is changed. More information on how to find the unique identifiers can be found in [the data handling guide](../../concepts/datahandling.md). + +## Usage -#### Usage: ```ts data.subscribe( 'sw-product-detail__product', @@ -16,7 +23,8 @@ data.subscribe( ); ``` -#### Output: +## Output + ```json { "name": "Ergonomic Copper Mr. Frenzy", @@ -26,7 +34,8 @@ data.subscribe( } ``` -#### Parameters +## Parameters + | Name | Required | Description | | :---------- | :------- |:------------------------------------------------------------------------------------------------------| | `id` | true | The unique id of the dataset you want to receive | diff --git a/docs/admin-sdk/api-reference/data/update.md b/docs/admin-sdk/api-reference/data/update.md index 56181c035..0f1456147 100644 --- a/docs/admin-sdk/api-reference/data/update.md +++ b/docs/admin-sdk/api-reference/data/update.md @@ -1,9 +1,16 @@ +--- +title: "Update" +nav: + position: 50 +--- + + # Update -With `data.update` you can update datasets from the Shopware administration. -More information on how to find the unique identifiers can be found in [this guide](../../internals/datahandling.md). +With `data.update` you can update datasets from the Shopware Administration. More information on how to find the unique identifiers can be found in [the data-handling guide](../../concepts/datahandling.md). + +## Usage -#### Usage: ```ts data.update({ id: 'sw-product-detail__product', @@ -15,7 +22,8 @@ data.update({ }); ``` -#### Parameters +## Parameters + | Name | Required | Description | | :-------- | :------- | :------------------------------------------------- | | `options` | true | An object containing the id and the data to update | diff --git a/docs/admin-sdk/api-reference/in-app-purchases/in-app-purchases.md b/docs/admin-sdk/api-reference/in-app-purchases/in-app-purchases.md deleted file mode 100644 index c54329029..000000000 --- a/docs/admin-sdk/api-reference/in-app-purchases/in-app-purchases.md +++ /dev/null @@ -1,19 +0,0 @@ -# In-App Purchase Flow - -> Available since Shopware v6.6.9.0 -> -In-App purchases allow you to create different functionality based on purchases the user has made in your app. This guide will show you how to start the in-app purchase flow. - -### Opening modal with details of feature - -To open a modal with the details of the feature you want to purchase, you can use the following code: - -```ts -sw.iap.purchase({ - identifier: 'your-in-app-purchase-id', -}); -``` - -This will create a modal in admin which takes the user through the checkout flow in which the app will be purchased or subscribed to. - -Once the purchase has been completed, the amount will be added to the bill of the merchant, and the feature will be unlocked. diff --git a/docs/admin-sdk/api-reference/in-app-purchases/index.md b/docs/admin-sdk/api-reference/in-app-purchases/index.md deleted file mode 100644 index 0763ccc69..000000000 --- a/docs/admin-sdk/api-reference/in-app-purchases/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "In App Purchases" -nav: - position: 350 ---- diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index 9e859ad9b..c3a826e81 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -1,5 +1,87 @@ --- title: "API Reference" nav: - position: 50 + position: 40 --- + +# API Reference + +The Meteor Admin SDK provides APIs for extending the Shopware Administration UI and interacting with Administration data. + +These APIs allow extensions to add user interface elements, access and modify entity data, register CMS blocks and elements, and share state between components. + +Use the sections below to navigate the available APIs. + +## Extending the Administration UI + +These APIs allow extensions to add UI elements to the Shopware Administration. +They can be used to register modules, add navigation entries, extend existing pages, and display dialogs or side panels. + +Typical use cases include: + +- Creating custom modules in the Administration +- Extending entity detail pages +- Adding navigation or settings entries +- Displaying modals or contextual UI elements + +APIs in this section include: + +- [Main Module](./ui/mainModule.md) +- [Menu](./ui/menu.md) +- [Settings Item](./ui/settingsItem.md) +- [Action Button](./ui/actionButton.md) +- [Tabs](./ui/tabs.md) +- [Component Sections](./ui/component-sections.md) +- [Sidebars](./ui/sidebars.md) +- [Modals](./ui/modals.md) +- [Media Modal](./ui/mediaModal.md) +- [Payment Overview Card](./ui/paymentOverviewCard.md) + +## Working with Data + +These APIs allow extensions to access and manipulate Shopware entity data from within the Administration. + +They follow the same repository-based data access pattern used internally by the Administration. + +Typical workflows include: + +- Accessing entity repositories +- Retrieving entity data +- Subscribing to changes +- Updating or persisting entities + +APIs in this section include: + +- [Repository](./data/repository.md) +- [Get](./data/get.md) +- [Subscribe](./data/subscribe.md) +- [Update](./data/update.md) +- [In-App Purchases](./data/in-app-purchases.md) + +## Composable APIs + +Composable APIs provide reusable helpers for working with the Administration state and data layer inside extensions. + +They simplify common patterns such as accessing repositories or sharing state between components. + +APIs in this section include: + +- [useRepository](../develop/composables/useRepository.md) +- [useSharedState](../develop/composables/useSharedState.md) + +## Extending the CMS + +These APIs allow extensions to add new CMS blocks and elements to the Shopware Shopping Experiences editor. + +They can be used to introduce custom content components that merchants can use when building storefront pages. + +APIs in this section include: + +- [Register CMS Block](../develop/cms/registerCmsBlock.md) +- [Register CMS Element](../develop/cms/registerCmsElement.md) + +## Shared Options + +Some SDK APIs support shared configuration options that control how actions are executed in the Administration. + +- [Base Options](./base-options.md) diff --git a/docs/admin-sdk/api-reference/ui/actionButton.md b/docs/admin-sdk/api-reference/ui/actionButton.md index 37bec482e..1d8eb94da 100644 --- a/docs/admin-sdk/api-reference/ui/actionButton.md +++ b/docs/admin-sdk/api-reference/ui/actionButton.md @@ -1,6 +1,18 @@ -# Action button +--- +title: "Action Button" +nav: + position: 50 +--- + + +# Action Button + +An action button adds a clickable button to an existing area of the Shopware Administration. + +Action buttons are typically used to trigger extension-specific actions such as opening a modal, executing a workflow, or navigating to an extension module. + +## Usage -#### Usage: ```ts import { location, ui } from '@shopware-ag/meteor-admin-sdk'; @@ -17,7 +29,8 @@ if (location.is(sw.location.MAIN_HIDDEN)) { } ``` -#### Parameters +## Parameters + | Name | Required | Description | | :------------------- | :------- | :--------------------------------------------------------------------------------------------------------- | | `action` | true | A unique name of your action | @@ -28,10 +41,12 @@ if (location.is(sw.location.MAIN_HIDDEN)) { | `fileTypes` | false | Media file types you want the action button to be displayed for. Will be available in Shopware version 6.7.6. | | `callback` | true | The callback function where you receive the entity and the entityIds for further processing | -### Calling app actions +## Calling app actions + As an app developer you may want to receive the information of the callback function server side. The following example will render the same action button as the above example but once it gets clicked you will receive a POST request to your app server. -**This will only work for apps. Plugin developers need to use a api client directly in there callback.**. + +**This will only work for apps. Plugin developers must use an API client directly in their callback.**. ```ts import { location, ui } from '@shopware-ag/meteor-admin-sdk'; @@ -53,7 +68,8 @@ if (location.is(sw.location.MAIN_HIDDEN)) { } ``` -#### Example +## Example + - Add action button in customer detail page ![Action button example](./assets/add-action-button-example.png) @@ -90,4 +106,4 @@ ui.actionButton.add({ // TODO: Navigate to image editor app }, }); -``` \ No newline at end of file +``` diff --git a/docs/admin-sdk/api-reference/assets/sidebar-example.png b/docs/admin-sdk/api-reference/ui/assets/sidebar-example.png similarity index 100% rename from docs/admin-sdk/api-reference/assets/sidebar-example.png rename to docs/admin-sdk/api-reference/ui/assets/sidebar-example.png diff --git a/docs/admin-sdk/api-reference/ui/component-section.md b/docs/admin-sdk/api-reference/ui/component-sections.md similarity index 84% rename from docs/admin-sdk/api-reference/ui/component-section.md rename to docs/admin-sdk/api-reference/ui/component-sections.md index 380d1d2c8..20142709a 100644 --- a/docs/admin-sdk/api-reference/ui/component-section.md +++ b/docs/admin-sdk/api-reference/ui/component-sections.md @@ -1,11 +1,21 @@ -# Component Section +--- +title: "Component Sections" +nav: + position: 70 +--- + +# Component Sections + +Component sections allow extensions to render UI components inside existing Administration views. They are typically used together with tabs or other extension points that expose a `positionId`. + +See the [Component Sections concept](../../concepts/component-sections.md) for an overview. ## Add + Add a new component to a component section. ### General usage -#### Usage: ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -18,19 +28,22 @@ ui.componentSection.add({ }) ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | | :---------- | :------- | :------ | :--------------------------------------------- | | `component` | true | | Choose the component which you want to render. | -#### Return value: +### Return value + This method does not have a return value. ## Available components ### Card -#### Properties: +#### Properties + | Name | Required | Default | Description | |:-------------|:---------|:--------|:-----------------------------------| | `title` | false | | The main title of the card | @@ -38,7 +51,8 @@ This method does not have a return value. | `locationId` | true | | The locationId for the custom view | | `tabs` | false | | Render different content with tabs | -#### Usage: +#### Usage + ```js import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -54,9 +68,11 @@ ui.componentSection.add({ ``` #### Example + ![Card component example](./assets/example-card.png) -#### With tabs: +#### With tabs + ```js import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -85,4 +101,5 @@ ui.componentSection.add({ ``` #### Example + ![Card component with tabs example](./assets/example-card-with-tabs.png) diff --git a/docs/admin-sdk/api-reference/ui/index.md b/docs/admin-sdk/api-reference/ui/index.md index aa43b9db2..72e3ae3f4 100644 --- a/docs/admin-sdk/api-reference/ui/index.md +++ b/docs/admin-sdk/api-reference/ui/index.md @@ -1,5 +1,46 @@ --- -title: "UI" +title: "Extending the Administration UI" nav: - position: 100 ---- \ No newline at end of file + position: 10 +--- + + +# Extending the Administration UI + +The Meteor Admin SDK allows extensions to add UI elements to the Shopware Administration. + +These APIs let you integrate custom functionality into existing areas of the Administration, such as navigation menus, action buttons, settings pages, or custom modules. + +The following guides cover common UI extension patterns. + +## Using UI components + +Shopware Administration components cannot be used directly inside apps or plugins. Instead, extensions should use the Meteor Component Library to achieve a native look and feel. + +Shopware Administration components are not native Vue components. They rely on internal extension capabilities, Twig templates, and framework integrations that are not available externally. + +The [Meteor Component Library](https://github.com/shopware/meteor-component-library) provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. + +## Typical development flow + +A typical extension often follows this progression. + +1. Create a new module: Use a [Main Module](./mainModule.md) when your extension needs a dedicated application area in the Administration. + +2. Expose the module in navigation: Add a [Menu](./menu.md) entry so users can access your extension. + +3. Add configuration options: Use a [Settings Item](./settingsItem.md) to place configuration inside the Administration settings. + +4. Add interactive actions: Use an [Action Button](./actionButton.md) to trigger extension functionality from existing pages. + +5. Extend existing views: Add [Tabs](./tabs.md) to entity detail pages such as products, customers, or orders. + +6. Render custom UI inside existing views: Use [Component Sections](./component-sections.md) to add components to extension points. + +7. Provide contextual UI: Use [Sidebars](./sidebars.md) to display additional contextual information. + +8. Open dialogs and workflows: Use [Modals](./modals.md) for confirmations, forms, or multi-step workflows. + +9. Work with media: Use the [Media Modal](./mediaModal.md) to allow users to select or manage media assets. + +10. Extend specialized interfaces: Use a [Payment Overview Card](./paymentOverviewCard.md) to customize how payment methods appear in the Administration. diff --git a/docs/admin-sdk/api-reference/ui/mainModule.md b/docs/admin-sdk/api-reference/ui/mainModule.md index a0e84e91d..cff6292cd 100644 --- a/docs/admin-sdk/api-reference/ui/mainModule.md +++ b/docs/admin-sdk/api-reference/ui/mainModule.md @@ -1,10 +1,22 @@ -# Main module +--- +title: "Main Module" +nav: + position: 20 +--- -### Add main module -Add a main module to your extension. The content of the main module is determined by your `locationId`. -A specific view or a set of actions can be triggered based on the `locationId`. -#### Usage: +# Main Module + +A main module registers a new top-level section in the Shopware Administration navigation. + +Use a main module when your extension provides a dedicated application area with its own pages and functionality. + +## Add main module + +Add a main module to your extension. The content of the main module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. + +### Usage + ```ts ui.mainModule.addMainModule({ heading: 'My App', @@ -12,7 +24,8 @@ ui.mainModule.addMainModule({ }); ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | | :---------------------- | :------- | :------ | :------------------------------------- | | `heading` | true | | The heading displayed in your module | @@ -20,8 +33,10 @@ ui.mainModule.addMainModule({ | `displaySearchBar` | false | true | Toggles the sw-page search bar on/off | | `displayLanguageSwitch` | false | false | Toggles sw-page language switch on/off | -#### Example +### Example + ![Main module example](./assets/add-main-module-example.png) + ```ts import { location, ui } from '@shopware-ag/meteor-admin-sdk'; @@ -53,10 +68,12 @@ if (location.is('main-location-id')) { } ``` -### Add smart bar button to main module +## Add smart bar button to main module + Add a button to the smart bar of your main module. The button can be used to trigger actions, e.g. saving, cancel, etc. The location ID needs to be defined and have the same value as the `locationId` of the main module. -#### Usage: +### Usage + ```ts ui.mainModule.addSmartbarButton({ locationId: 'main-location-id', // locationId of your main module @@ -67,7 +84,8 @@ ui.mainModule.addSmartbarButton({ }); ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | | :---------------- | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------ | | `locationId` | true | | The locationId of the module you want to display the smart bar button | @@ -77,17 +95,20 @@ ui.mainModule.addSmartbarButton({ | `onClickCallback` | true | | Callback function which will be called once the button is clicked | | `disabled` | false | false | Toggle disabled state of the button | -### Hide smart bar +## Hide smart bar + Turn the smart bar off as needed. -#### Usage: +### Usage + ```ts ui.mainModule.hideSmartBar({ locationId: 'main-location-id', }); ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | Available at Shopware | | :----------- | :------- | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| | `locationId` | true | | The locationId of the module you want to hide the smart bar | v6.6.7.0 | diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index 2b3ae72dc..afe1d4138 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -1,19 +1,22 @@ -# Media modal +--- +title: "Media Modals" +nav: + position: 100 +--- -This method allows an app to interact with the Administration's media modal, which includes the Media modal and the Save media modal. -Functionality of each modal: -- The Media modal is used for selecting existing media from the media library or uploading new media. This functionality has been available since version 6.7.1. +# Media Modals -- The Save media modal is used to choose a specific location to save the media, and this feature will be implemented in version 6.7.5. +This method allows apps to interact with the Administration's media modal. Two modal types are supported: -## Media modal +- **Media modal**: Select existing media from the media library or upload new files. Available since Shopware 6.7.1. +- **Save media modal**: Choose a specific folder and filename when saving media. Available since Shopware 6.7.5. -### Open modal +## Open modal Open media modal in the current view. -#### Usage: +### Usage ```ts ui.mediaModal.open({ @@ -25,7 +28,7 @@ ui.mediaModal.open({ }); ``` -#### Parameters +### Parameters All parameters are similar to `sw-media-modal-v2` component's props @@ -39,7 +42,7 @@ All parameters are similar to `sw-media-modal-v2` component's props | `selectors` | false | ['fileName', 'id', 'url'] | Selected properties which should be returned in callback function | | `callback` | true | | Callback function which will be called once the media item is selected. | -#### Example +### Example ![Menu item example](./assets/media-modal.png) @@ -58,7 +61,7 @@ ui.mediaModal.open({ Open save media modal in the current view. -#### Usage: +### Usage ```ts ui.mediaModal.openSaveMedia({ @@ -69,7 +72,7 @@ ui.mediaModal.openSaveMedia({ }); ``` -#### Parameters +### Parameters All parameters are similar to `sw-media-save-modal` component's props @@ -80,7 +83,7 @@ All parameters are similar to `sw-media-save-modal` component's props | `fileType` | false | null | File extension of media to display on file name input's suffix | | `callback` | true | | This callback function is triggered when the "Save media" button is clicked. It returns the updated file name and the folderId where the media is stored. | -#### Example +### Example ![Menu item example](./assets/save-media-modal.png) diff --git a/docs/admin-sdk/api-reference/ui/menu.md b/docs/admin-sdk/api-reference/ui/menu.md index a28a6df7f..0cd12d21b 100644 --- a/docs/admin-sdk/api-reference/ui/menu.md +++ b/docs/admin-sdk/api-reference/ui/menu.md @@ -1,23 +1,36 @@ +--- +title: "Menu" +nav: + position: 30 +--- + # Menu -### Toggle menu +Menu items allow extensions to add navigation entries to existing areas of the Shopware Administration menu. + +They are typically used to expose extension functionality inside existing admin modules. + +## Toggle menu > Available since Shopware v6.6.2.0 The Admin SDK allows you to manipulate the Admin menu of your application. One of the features it provides is the ability to toggle the Admin menu. This is done using the `collapseMenu` and `expandMenu` methods. -#### Usage: +### Usage + ```ts ui.menu.collapseMenu(); // To collapse the Admin menu; ui.menu.expandMenu(); // To expand the Admin menu; ``` -### Add menu item +## Add menu item + Add a new menu item to the Shopware admin menu. The content of the menu item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. -#### Usage: +### Usage + ```ts ui.menu.addMenuItem({ label: 'Test item', @@ -28,7 +41,8 @@ ui.menu.addMenuItem({ }) ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | | :------------------- | :------- | :------------- | :------------------------------------------------------------ | | `label` | true | | The label of the tab bar item | @@ -38,8 +52,10 @@ ui.menu.addMenuItem({ | `parent` | false | 'sw-extension' | Determines under which main menu entry your item is displayed | | `position` | false | 110 | Determines the position of your menu item | -#### Example +### Example + ![Menu item example](./assets/add-menu-item-example.png) + ```ts import { location, ui } from '@shopware-ag/meteor-admin-sdk'; diff --git a/docs/admin-sdk/api-reference/ui/modals.md b/docs/admin-sdk/api-reference/ui/modals.md index c57bc6ae3..ac640de8c 100644 --- a/docs/admin-sdk/api-reference/ui/modals.md +++ b/docs/admin-sdk/api-reference/ui/modals.md @@ -1,14 +1,26 @@ +--- +title: "Modals" +nav: + position: 90 +--- + + # Modals -A modal can be displayed in front of all other elements. To return to the main content the user must engage -with the modal by completing an action or by closing it. It should be mainly opened when the user interacts with something. -We recommend that no modal gets opened without context. As an example, it would be bad practice if the user gets logged -in and directly see some modals (e.g. changelogs of extensions) which all need to be closed manually. +Modals display dialog windows in front of the Shopware Administration interface. + +They should be triggered by user interaction and used for confirmations, forms, or multi-step workflows. To return to the main content the user must engage with the modal by completing an action or by closing it. + +Avoid opening modals automatically without context, as this interrupts the user’s workflow. For example, it is poor practice to show modals immediately after login (such as changelogs) that users must manually dismiss. + +See also: [Base Options](../base-options.md) for shared configuration options supported by SDK message APIs. + +## Open modal -### Open modal Open a new modal in the current view. The content of the modal is determined by your `locationId` or by using plain text with `textContent`. -#### Usage: +### Usage + ```ts ui.modal.open({ title: 'Your modal title', @@ -43,7 +55,8 @@ ui.modal.open({ }) ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | Available at Shopware | |:--------------|:---------|:----------|:-----------------------------------------------------------------------------------------------|:----------------------| | `title` | true | | The title of the modal | | @@ -55,8 +68,10 @@ ui.modal.open({ | `closable` | false | true | If this is set to `false` then the modal can only be closed programmatically | | | `buttons` | false | [] | This array contains button configurations which will render buttons in the footer of the modal | | -#### Example +### Example + ![Menu item example](./assets/modal-example.png) + ```ts ui.modal.open({ title: 'Hello from the plugin', @@ -84,12 +99,14 @@ ui.modal.open({ }) ``` -### Update modal +## Update modal + > Available since Shopware 6.7.1.0 Updates an existing modal with the given `locationId`. This can be used to modify the modal's properties after it has been opened, such as changing the title, buttons, or visibility of header/footer from inside the modal. -#### Usage: +### Usage + ```ts ui.modal.update({ locationId: 'your-location-id', @@ -108,7 +125,8 @@ ui.modal.update({ }) ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | |:-------------|:---------|:--------|:-----------------------------------------------------------------------------------------------| | `locationId` | true | | The id of the modal which should be updated | @@ -118,15 +136,18 @@ ui.modal.update({ | `closable` | false | | If set to `false` then the modal can only be closed programmatically | | `buttons` | false | | Array of button configurations which will render buttons in the footer of the modal | -### Close modal +## Close modal + Closes an opened modal. You need use the correct `locationId` of the modal which should get closed. If you don't provide a `locationId` the last modal without a `locationId` gets closed. -#### Usage: +### Usage + ```ts ui.modal.close({ locationId: 'your-location-id' }) ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | |:-------------|:---------|:--------|:--------------------------------------------------------------------------------------------------------------------------| | `locationId` | false | | The locationId of the modal which should get closed. If not provided, the last modal without a locationId will be closed. | diff --git a/docs/admin-sdk/api-reference/ui/module/index.md b/docs/admin-sdk/api-reference/ui/module/index.md deleted file mode 100644 index e0d98846a..000000000 --- a/docs/admin-sdk/api-reference/ui/module/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: "Extending modules" ---- diff --git a/docs/admin-sdk/api-reference/ui/module/paymentOverviewCard.md b/docs/admin-sdk/api-reference/ui/paymentOverviewCard.md similarity index 80% rename from docs/admin-sdk/api-reference/ui/module/paymentOverviewCard.md rename to docs/admin-sdk/api-reference/ui/paymentOverviewCard.md index 252f22451..89fa0db2b 100644 --- a/docs/admin-sdk/api-reference/ui/module/paymentOverviewCard.md +++ b/docs/admin-sdk/api-reference/ui/paymentOverviewCard.md @@ -1,19 +1,28 @@ +--- +title: "Payment Overview Cards" +nav: + position: 110 +--- + + # Payment Overview Cards -### Add a custom payment method overview card in settings +A payment overview card allows extensions to customize how a payment method appears in the payment methods overview in the Shopware Administration. + +Starting with Shopware **6.4.14.0**, extensions can replace the default payment method card with a custom component. This makes it possible to add additional logic before a payment method can be activated. -Starting with Shopware 6.4.14.0, you can render a custom card in the new payment method overview. -With that, you can replace the default card, where you can toggle the active state of a payment method, with your own component. -This allows you, for example, to require an onboarding to your payment provider before activating the payment method. +For example, you might require merchants to complete an onboarding process with your payment provider before enabling the payment method. + +## Parameters -### Parameters | Name | Required | Default | Description | |:------------------------|:---------| :------------- |:------------------------------------------------------------------------------------------------------------------------------------| | `positionId` | true | | The position id that is created in the payment overview, where you can add a component section to | | `paymentMethodHandlers` | true | | A list of formatted payment method handlers, which are handled by your component and where the default card should not be rendered. | | `component` | false | | The component name of you custom payment overview card. Only useful, if you have a plugin with a registered component | -### Extension example +## Extension example + ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -46,7 +55,8 @@ if (sw.location.is('my-custom-payment-overview-position-before')) { } ``` -### Custom plugin component example +## Custom plugin component example + ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; diff --git a/docs/admin-sdk/api-reference/ui/settingsItem.md b/docs/admin-sdk/api-reference/ui/settingsItem.md index 9ba00a746..7835a321a 100644 --- a/docs/admin-sdk/api-reference/ui/settingsItem.md +++ b/docs/admin-sdk/api-reference/ui/settingsItem.md @@ -1,10 +1,22 @@ +--- +title: "Settings Item" +nav: + position: 40 +--- + + # Settings Item -### Add settings item -Add a new settings item to the Shopware settings. The content of the settings item module is determined by your `locationId`. -A specific view or a set of actions can be triggered based on the `locationId`. +A settings item adds an entry to the Shopware Administration settings area. + +Use this when your extension provides configurable options that should appear in the central settings section. + +## Add settings item + +Add a new settings item to the Shopware settings. The content of the settings item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. + +### Usage -#### Usage: ```ts ui.settings.addSettingsItem({ label: 'App Settings', @@ -16,7 +28,8 @@ ui.settings.addSettingsItem({ }); ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | | :------------------- | :------- | :------------- | :------------------------------------------------------------ | | `label` | true | | The label of the tab bar item | @@ -26,12 +39,15 @@ ui.settings.addSettingsItem({ | `displaySmartBar` | false | true | Toggles the sw-page smart bar on/off | | `tab` | false | 'plugins' | Determines in which tab your settings item will be displayed | -### Getting the right icon +## Getting the right icon + Assuming that your editor supports TypeScript, you should get auto-completion for valid `icon` values. In case that doesn't work take a look at the list [here](https://github.com/shopware/meteor-admin-sdk/blob/trunk/src/icons.ts). -#### Example +### Example + ![Settings item example](./assets/add-settings-item-example.png) + ```ts import { location, ui } from '@shopware-ag/meteor-admin-sdk'; diff --git a/docs/admin-sdk/api-reference/ui/sidebars.md b/docs/admin-sdk/api-reference/ui/sidebars.md index 7cb781531..34aa2eac3 100644 --- a/docs/admin-sdk/api-reference/ui/sidebars.md +++ b/docs/admin-sdk/api-reference/ui/sidebars.md @@ -1,12 +1,19 @@ +--- +title: "Sidebars" +nav: + position: 80 +--- + + # Sidebars A sidebar provides a contextual panel that displays at the right edge of the Administration window. Unlike modals, sidebars allow users to view and interact with additional content or functionality without losing context of the main interface. Sidebars should be opened in response to user interaction rather than appearing automatically. As a best practice, avoid opening sidebars without clear user context - for example, automatically displaying extension changelog sidebars immediately after login creates a poor user experience by requiring manual dismissal of each one. -### Add a sidebar +## Add a sidebar Add a new sidebar. The content of the sidebar is determined by your `locationId`. -#### Usage: +### Usage ```ts sw.ui.sidebar.add({ @@ -16,7 +23,8 @@ sw.ui.sidebar.add({ }); ``` -#### Parameters +### Parameters + | Name | Required | Description | Available at Shopware | | :----------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| | `title` | true | The title of the sidebar | 6.7 | @@ -24,14 +32,15 @@ sw.ui.sidebar.add({ | `icon` | true | The icon to display in the sidebar. You can use any icon from the Shopware icon library | 6.7 | | `resizable` | false | Enables horizontal resizing of the sidebar | 6.7.2.0 | -#### Example +### Example + ![Menu item example](../assets/sidebar-example.png) -### Close a sidebar +## Close a sidebar Close an existing sidebar programmatically. -#### Usage: +### Usage ```ts sw.ui.sidebar.close({ @@ -39,16 +48,17 @@ sw.ui.sidebar.close({ }); ``` -#### Parameters +### Parameters + | Name | Required | Description | Available at Shopware | | :----------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| | `locationId` | true | The id of the sidebar to close | 6.7 | -### Remove a sidebar +## Remove a sidebar Remove a sidebar completely from the DOM. -#### Usage: +### Usage ```ts sw.ui.sidebar.remove({ @@ -56,7 +66,8 @@ sw.ui.sidebar.remove({ }); ``` -#### Parameters +### Parameters + | Name | Required | Description | Available at Shopware | | :----------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| | `locationId` | true | The id of the sidebar to remove | 6.7 | diff --git a/docs/admin-sdk/api-reference/ui/tabs.md b/docs/admin-sdk/api-reference/ui/tabs.md index df99219e0..64e3c0bd6 100644 --- a/docs/admin-sdk/api-reference/ui/tabs.md +++ b/docs/admin-sdk/api-reference/ui/tabs.md @@ -1,12 +1,25 @@ +--- +title: "Tabs" +nav: + position: 60 +--- + + # Tabs -### Add tab item +Tabs allow extensions to add additional tabs to existing Administration pages. + +They are commonly used to extend entity detail pages such as products, customers, or orders. + +## Add tab item + Add a new tab item to an existing tab bar. The content of the the new tab item contains a component section. This works with tab bar's which have routing and also static tab bars. If the tab bar has routing then the route for the tab item will be generated automatically. -#### Usage: +### Usage + ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -16,13 +29,15 @@ ui.tabs('sw-product-detail' /* The positionId of the tab bar*/).addTabItem({ }) ``` -#### Parameters +### Parameters + | Name | Required | Default | Description | | :------------------- | :------- | :------ | :------------------------------------------------------ | | `label` | true | | The label of the tab bar item | | `componentSectionId` | true | | The Id for for the component section in the tab content | -#### Example +### Example + ![Tab item example](./assets/add-tab-item-example.png) ```ts import { ui, location } from '@shopware-ag/meteor-admin-sdk'; diff --git a/docs/admin-sdk/api-reference/window.md b/docs/admin-sdk/api-reference/window.md deleted file mode 100644 index 0dc5b7f29..000000000 --- a/docs/admin-sdk/api-reference/window.md +++ /dev/null @@ -1,115 +0,0 @@ -# Window - -### Redirect to another URL - -#### Usage: -```ts -sw.window.redirect({ - url: 'https://www.shopware.com, - newTab: true -}) -``` - -#### Parameters: -| Name | Required | Default | Description | -| :------ | :------ | :------ | :------ | -| `url` | true | | The title of the notification | -| `newTab` | false | false | The message of the notification | - -#### Return value: -Returns a promise without data. - -### Push to another page -For redirecting to other pages in the admin. - -#### Usage: -The usage matches the Vue Router push capabilities. Here are two examples how to use it for redirecting to your own modules: - -```ts -sw.window.routerPush({ - name: 'sw.extension.sdk.index', - params: { - id: 'the_id_of_the_module' // can be get with context.getModuleInformation - } -}) -``` - -```ts -sw.window.routerPush({ - path: `/extension/${the_id_of_the_module}` // id can be get with context.getModuleInformation -}) -``` - -#### Parameters: -| Name | Required | Default | Description | -| :------ | :------ | :------ | :------ | -| `name` | false | undefined | The name of the route | -| `path` | false | undefined | The path of the route | -| `params` | false | undefined | Additional params for the new route | -| `replace` | false | false | Should not change the browser history | - -#### Return value: -Returns a promise without data. - -### Reload page - -Useful for development. You can trigger a page reload on file changes. - -#### Usage: -```ts -sw.window.reload() -``` - -#### Parameters: -No parameters required. - -#### Return value: -Returns a promise without data. - -### Get an unique identifier for the window - -> Available since Shopware v6.7.1.0 - -When it comes to session handling it can be useful to have a unique identifier for your window. - -### Usage: -```ts -sw.window.getId() -``` - -### Parameters -No parameters required - -### Return value: -A `string` representing an unique identifier for the current window - -### Example -In this example we check if the `sessionStorage` contains data from a former window. This can happen if a user uses the *Duplicate Tab* feature of some browsers. - -```ts -const windowId = sw.window.getId(); -const storedWindowId = globalThis.sessionStorage.getItem('window-id'); - -if (windowId !== storedWindowId) { - globalThis.sessionStorage.clear(); - globalThis.sessionStorage.setItem('window-id', windowId); -} - -``` - -### Get the view router path - -> Available since Shopware v6.7.3.0 - -You can get the view router full path. - -#### Usage: -```ts -sw.window.getPath() -``` - -#### Parameters: -No parameters required. - -#### Return value: -A `string` with the full path, or empty if router not found. diff --git a/docs/admin-sdk/internals/how-it-works.md b/docs/admin-sdk/concepts/architecture.md similarity index 96% rename from docs/admin-sdk/internals/how-it-works.md rename to docs/admin-sdk/concepts/architecture.md index bcdcea3e6..1df9b6de8 100644 --- a/docs/admin-sdk/internals/how-it-works.md +++ b/docs/admin-sdk/concepts/architecture.md @@ -1,4 +1,11 @@ -# How it works +--- +title: "Architecture" +nav: + position: 20 +--- + + +# Architecture The Meteor Admin SDK provides wrapper methods for a better development experience. It abstracts and hides the more complex logic behind a simple API. This makes it easier for app and plugin developers to create their solutions and focus @@ -71,6 +78,7 @@ handle('contextLanguage', () => { It uses the `handle` method, which is also a helper method of the `channel`. You see now, that the type matches the sender type. And in the second argument it provides a method that returns the data. This method reacts to every `contextLanguage` request and sends the data values back to the source of the request. It also creates an object that includes meta information which in turn are needed for the original `send` window: + ```js { _type: 'contextLanguage', @@ -93,9 +101,11 @@ const language = await sw.context.getLanguage(); And this is basically it! The app or plugin has now got the data from the Administration. It all just looks like a simple call, but there is a lot going on in the background. ## Sending methods + In normal cases you can't add methods to JSON objects which will get stringified. But in our case we are convinced it would make the many developers' lives much easier if they can also use their own methods in the calls. -To handle these edge-cases we are converting the methods to information objects like this: +To handle these edge cases we are converting the methods to information objects like this: + ```js { __type__: '__function__', @@ -116,5 +126,4 @@ send('__function__', { The sender gets the message back and executes the method with the matching ID and the given arguments. The return value will then be sent back to the converted method in the receiver. -This complex logic is also abstracted. To use it, just add methods to -the data. They will then be converted and handled automatically. \ No newline at end of file +This complex logic is also abstracted. To use it, just add methods to the data. They will then be converted and handled automatically. diff --git a/docs/admin-sdk/internals/assets/devtool-example.png b/docs/admin-sdk/concepts/assets/devtool-example.png similarity index 100% rename from docs/admin-sdk/internals/assets/devtool-example.png rename to docs/admin-sdk/concepts/assets/devtool-example.png diff --git a/docs/admin-sdk/internals/assets/post-message-communication.png b/docs/admin-sdk/concepts/assets/post-message-communication.png similarity index 100% rename from docs/admin-sdk/internals/assets/post-message-communication.png rename to docs/admin-sdk/concepts/assets/post-message-communication.png diff --git a/docs/admin-sdk/concepts/component-sections.md b/docs/admin-sdk/concepts/component-sections.md index a825dfa43..b58c71b79 100644 --- a/docs/admin-sdk/concepts/component-sections.md +++ b/docs/admin-sdk/concepts/component-sections.md @@ -1,10 +1,22 @@ -# Component sections +--- +title: "Component Sections" +nav: + position: 50 +--- -In most cases extension developers will directly use the extension capabilities of the UI components (e.g. adding tab items, adding button to grid, ...). This will cover most needs of many extensions. But in cases where a extension need special solutions which aren't feasible with the given extension they can use a feature named `Component Sections`. These are sections where any extension developer can inject components. -These components are prebuilt (like cards) and contain in most cases custom [location](./locations.md) where the extension has the full freedom to render anything. +# Component Sections -### Example: +Component sections allow extensions to render UI components inside predefined extension points in the Shopware Administration. + +Unlike other extension APIs that modify existing UI elements (such as tabs or buttons), component sections allow extensions to inject full components into specific UI positions. + +Component sections are prebuilt (like cards) and usually work together with: + +- [Positions](./positions.md): identify where UI can be injected +- [Locations](./locations.md): determine where extension content should render + +## Example ```js if (location.is(location.MAIN_HIDDEN)) { @@ -32,7 +44,8 @@ if (sw.location.is('my-app-card-before-properties')) { ![Component Sections screenshot example](./assets/component-sections-example.png) -If you want to render tabs inside the `card` component section, we provide a way to do so: +To render tabs inside the `card` component section, we provide a way to do so: + ```js if (sw.location.is(sw.location.MAIN_HIDDEN)) { // Choose a position id where you want to render a custom component diff --git a/docs/admin-sdk/internals/datahandling.md b/docs/admin-sdk/concepts/datahandling.md similarity index 86% rename from docs/admin-sdk/internals/datahandling.md rename to docs/admin-sdk/concepts/datahandling.md index 147667423..582da6b5e 100644 --- a/docs/admin-sdk/internals/datahandling.md +++ b/docs/admin-sdk/concepts/datahandling.md @@ -1,12 +1,21 @@ -# Datahandling +--- +title: "Data Handling" +nav: + position: 70 +--- -This guide elaborates how the data handling works between extensions and the Shopware administration. + +# Data Handling + +This guide elaborates how the data handling works between extensions and the Shopware Sdministration. ## What are datasets? + Datasets consist of a unique identifier, an `id` and some `data` which could be anything from a single value to a whole entity. The id gives some insight on what to expect as the value. For example `sw-product-detail__product` contains the product of the product detail page. ## How to find available datasets + You can explore all available datasets with the Vue Devtool extension we provide with the Shopware administration. - Open the Vue DevTools in the Shopware Administration @@ -14,6 +23,6 @@ You can explore all available datasets with the Vue Devtool extension we provide In this inspector you will see all published datasets if there are any in the current view. +## Example -#### Example ![Action button example](./assets/devtool-example.png) diff --git a/docs/admin-sdk/concepts/index.md b/docs/admin-sdk/concepts/index.md index 4aff59e17..543881413 100644 --- a/docs/admin-sdk/concepts/index.md +++ b/docs/admin-sdk/concepts/index.md @@ -1,5 +1,20 @@ --- title: "Concepts" nav: - position: 500 + position: 10 --- + +# Concepts + +Before building Administration extensions, it helps to understand a few core concepts used by the Meteor Admin SDK. + +These concepts explain how extensions are rendered, where UI can be injected, and how data is accessed. + +## Concepts overview + +- [Architecture](./architecture.md): explains how the SDK communicates with the Shopware Administration and how requests are handled internally. +- [Locations](./locations.md): determine where extension code runs. +- [Positions](./positions.md): identify extendable areas of the Administration UI. +- [Component Sections](./component-sections.md): render custom components inside extension points. +- [Selectors](./selectors.md): retrieve specific fields from Administration data. +- [Data Handling](./datahandling.md): represent the data published by the Administration that extensions can read, subscribe to, or update. diff --git a/docs/admin-sdk/concepts/locations.md b/docs/admin-sdk/concepts/locations.md index 7fc602803..3e97b0dec 100644 --- a/docs/admin-sdk/concepts/locations.md +++ b/docs/admin-sdk/concepts/locations.md @@ -1,12 +1,35 @@ +--- +title: "Locations" +nav: + position: 30 +--- + # Locations +Locations define where an extension is rendered inside the Shopware Administration. + +Because an extension can appear in multiple places (such as tabs, modals, sidebars, or custom modules), extensions typically check the current location before executing UI logic. + +This concept allows a single extension bundle to support multiple entry points inside the Administration. + Extensions can render custom views via iFrames. To support multiple views in different places every `location` of the iFrame gets a unique ID. These can be defined by the extension developer itself. -*Example:* +## How extensions use locations + +An extension can appear in multiple places inside the Administration. Each of these places is identified by a **location ID**. + +Typical flow: + +1. Register UI extensions when the extension loads +2. Define a `locationId` where the custom UI will render +3. Render different views depending on the current location + +### Example A extension wants to render a custom iFrame in a card in the dashboard. The `location` of the iFrame has then a specific `locationId` like `sw-dashboard-example-app-dashboard-card`. The app can also render another iFrames which also get `locationId`s. In our example it is a iFrame in a custom modal: `example-app-example-modal-content`. The extension want to render different views depending on the `location` of the iFrame. So the extension developer can render the correct view depending on the `locationId`: + ```js // Add the ui extensions when your extension is loaded in the hidden iFrame if (sw.location.is(sw.location.MAIN_HIDDEN)) { @@ -31,6 +54,7 @@ if (sw.location.is('my-app-card-before-properties')) { ``` ## Base location + Every extension gets rendered in a hidden iFrame. In this iFrame the extension can execute different commands to extend the administration and add custom locations to different extension points. To check if the script will be executed in this location you can use the predefined constant: @@ -44,7 +68,9 @@ if (location.is(location.MAIN_HIDDEN)) { ``` ## Change height of location iFrame + The iFrame height is by default fixed. You can update the height with the location helper: + ```js location.updateHeight(750); // change iFrame height to 750px ``` @@ -52,17 +78,21 @@ location.updateHeight(750); // change iFrame height to 750px If you use a parameter then the height will automatically be calculated so that your whole view gets rendered. In most cases you don't want to update the height manually. To watch for height changes you can use the auto resizer. It updates the iFrame height everytime the height of the view changes: + ```js // watch for height changes and update the iFrame location.startAutoResizer(); ``` + ![Auto Resizer example](./assets/auto-resizer.gif) ## Avoiding scrollbars + If you render custom locations it is useful to disable the scroll behavior in your view. Otherwise scrollbars are visible which aren't needed in most cases. To avoid this you can add the css property `overflow: hidden;` to the `body` element. -## For existing plugin migrations: render Vue components instead of iFrames +## For existing plugin migrations, render Vue components instead of iFrames + In some cases you just want to use specific features from the SDK and some features from the existing plugin system which works with Twig and Component overriding. In this case you can do some things with the SDK but render components from the Shopware Component Factory instead of iFrames. To do this you need to register the component in the existing plugin system: @@ -74,6 +104,7 @@ Shopware.Component.register('your-component-name', { ``` Now if you want to render the component in a location you need to add the name of the component to the current location. This can be done with the `sdkLocation` store: + ```js Shopware.State.commit('sdkLocation/addLocation', { locationId: 'your-location-id', @@ -117,4 +148,4 @@ if (!location.isIframe()) { componentName: 'your-component-name' }) } -``` \ No newline at end of file +``` diff --git a/docs/admin-sdk/concepts/positions.md b/docs/admin-sdk/concepts/positions.md index 427539bbf..99e0ffd92 100644 --- a/docs/admin-sdk/concepts/positions.md +++ b/docs/admin-sdk/concepts/positions.md @@ -1,19 +1,32 @@ +--- +title: "Positions" +nav: + position: 40 +--- + + # Positions -Extension developer can extend existing areas or create new areas in the administration. It is so flexible that there are way to many Id's to remember. To identify the positions which the developer want to extend we need a unique ID for every position. These Id's are the `positionId`s. +Positions define where UI components can be injected into the Shopware Administration. + +Each extendable area exposes a unique `positionId`. Extensions use this identifier to tell the Administration where a UI component or extension should be rendered. -### Example: +Extension developers can extend existing areas or create new areas in the Administration. Memorizing all available `positionId`s is impractical. Instead, the SDK provides tooling to help discover them dynamically. + +## Example + +Suppose an extension wants to add a new tab to the product detail page. The extension must target the correct `positionId` for the tab bar. -A extension wants to add a new tab item to a tab-bar. In the administration are -many tab-bars available. So the developer needs to choose the correct `positionId` to tell the admin which tab-bar should be extended. In this example the developer adds a new tab item to the tab-bar in the product detail page. ```js sw.ui.tabs('sw-product-detail').addTabItem({ ... }) ``` +In this example, `sw-product-detail` is the `positionId` that identifies the tab bar in the product detail page. + +## Finding position IDs with Vue DevTools -### Vue Devtools Plugin for finding the PositionId's -It is impossible to create a list of all potential position Id's. And they would be hard to manage. To solve this problem the SDK provides a custom plugin for the Vue Devtools. It makes identifying the position Id's very easy. +Because the number of available positions is large and varies across views, the Meteor Admin SDK provides a plugin for [Vue DevTools](../develop/devtools.md) to help discover them. -Just open the plugin in the Devtools (It is available directly when you open the Administration). Then you can see all positions at the current administration view which are available for extending. If you click at one position Id you get more information about it. Like the property in the meteor-admin-sdk so that you directly know what functionality this position has. +Open the plugin in the Administration. When the DevTools plugin is open, it shows all extendable positions for the current Administration view. Selecting a position displays additional information, including the corresponding SDK API that can be used to extend it. -In summary: the Devtool plugin provides a visual way to see which parts can be extended and what are the positionIDs for the extension position. You can find a detailed guide in the tooling section of this documentation: [Vue Devtools](../tooling/vue-devtools.md) \ No newline at end of file +This provides a visual way to identify which parts of the Administration can be extended and which positionId should be used. diff --git a/docs/admin-sdk/concepts/selectors.md b/docs/admin-sdk/concepts/selectors.md index 7781f5605..3e967ceb1 100644 --- a/docs/admin-sdk/concepts/selectors.md +++ b/docs/admin-sdk/concepts/selectors.md @@ -1,12 +1,23 @@ +--- +title: "Selectors" +nav: + position: 60 +--- + + # Selectors -Selectors are a powerful tool to reduce the payload and minimize the needed privileges. -They are used in `data.subscribe` and `data.get`. Selectors are an array of strings. Each string represents a path to a property in the dataset. +Selectors allow extensions to request only specific fields from Administration data. + +By selecting only the required properties, selectors reduce payload size and limit the privileges required to access data. + +They are used in `data.subscribe` and `data.get`. Selectors are an array of strings, where each string represents the path to a property in the dataset. -### Example: +## Example -Imagine this payload: -```json +Consider the following example payload: + +```js { "name": "My Product", "manufacturer": { @@ -24,46 +35,95 @@ Imagine this payload: } ``` -If you are only interested in the names of the product and manufacturer, you can use the following selectors: -```javascript +If only the product name and manufacturer name are needed, request them using selectors: + +```js data.get({ id: 'sw-product-detail__product', selectors: ['name', 'manufacturer.name'], }).then((product) => { - console.log(product); // prints { name: "My Product", manufacturer: { name: "My Manufacturer" } } + console.log(product); }); ``` -### Combining selectors +Result: -Again for the above payload, if you are interested in multiple properties of the manufacturer, you can use the following selectors: -```javascript +```js +{ + "name": "My Product", + "manufacturer": { + "name": "My Manufacturer" + } +} +``` + +## Combining selectors + +It is possible to request multiple properties from the same object: + +```js data.get({ id: 'sw-product-detail__product', selectors: ['manufacturer.id', 'manufacturer.name'], }).then((product) => { - console.log(product); // prints { manufacturer: { id: '065e71ab94d778a980008e8c3e890270', name: "My Manufacturer" } + console.log(product); }); ``` -### Arrays +Result: + +```js +{ + "manufacturer": { + "id": "065e71ab94d778a980008e8c3e890270", + "name": "My Manufacturer" + } +} +``` + +## Arrays -If you are interested in a specific variant, you can use the following selectors: -```javascript +Selectors can also access array values: + +```js data.get({ id: 'sw-product-detail__product', selectors: ['variants.[0].name'], }).then((product) => { - console.log(product); // prints { variants: [ { name: "First Variant" } ] } + console.log(product); }); ``` -If you are interested in all variants, you can use wildcards. A wildcard is the asterix symbol (`*`) -```javascript +Result: + +```js +{ + "variants": [ + { "name": "First Variant" } + ] +} +``` + +## Wildcards + +To retrieve values from all items in an array, use the `*` wildcard: + +```js data.get({ id: 'sw-product-detail__product', selectors: ['variants.*.name'], }).then((product) => { - console.log(product); // prints { variants: [ { name: "First Variant" }, // same structure for all entries ] } + console.log(product); }); ``` + +Result: + +```js +{ + "variants": [ + { "name": "First Variant" }, + { "name": "Second Variant" } + ] +} +``` diff --git a/docs/admin-sdk/tooling/assets/devtools-plugin-extension-point-selection.png b/docs/admin-sdk/develop/assets/devtools-plugin-extension-point-selection.png similarity index 100% rename from docs/admin-sdk/tooling/assets/devtools-plugin-extension-point-selection.png rename to docs/admin-sdk/develop/assets/devtools-plugin-extension-point-selection.png diff --git a/docs/admin-sdk/tooling/assets/devtools-plugin-settings-list.png b/docs/admin-sdk/develop/assets/devtools-plugin-settings-list.png similarity index 100% rename from docs/admin-sdk/tooling/assets/devtools-plugin-settings-list.png rename to docs/admin-sdk/develop/assets/devtools-plugin-settings-list.png diff --git a/docs/admin-sdk/tooling/assets/devtools-plugin-settings.png b/docs/admin-sdk/develop/assets/devtools-plugin-settings.png similarity index 100% rename from docs/admin-sdk/tooling/assets/devtools-plugin-settings.png rename to docs/admin-sdk/develop/assets/devtools-plugin-settings.png diff --git a/docs/admin-sdk/tooling/assets/devtools-plugin-tab-shopware-extension.png b/docs/admin-sdk/develop/assets/devtools-plugin-tab-shopware-extension.png similarity index 100% rename from docs/admin-sdk/tooling/assets/devtools-plugin-tab-shopware-extension.png rename to docs/admin-sdk/develop/assets/devtools-plugin-tab-shopware-extension.png diff --git a/docs/admin-sdk/getting-started/assets/devtools-plugin.png b/docs/admin-sdk/develop/assets/devtools-plugin.png similarity index 100% rename from docs/admin-sdk/getting-started/assets/devtools-plugin.png rename to docs/admin-sdk/develop/assets/devtools-plugin.png diff --git a/docs/admin-sdk/getting-started/assets/devtools-usage.png b/docs/admin-sdk/develop/assets/devtools-usage.png similarity index 100% rename from docs/admin-sdk/getting-started/assets/devtools-usage.png rename to docs/admin-sdk/develop/assets/devtools-usage.png diff --git a/docs/admin-sdk/api-reference/assets/notification-example.jpg b/docs/admin-sdk/develop/assets/notification-example.jpg similarity index 100% rename from docs/admin-sdk/api-reference/assets/notification-example.jpg rename to docs/admin-sdk/develop/assets/notification-example.jpg diff --git a/docs/admin-sdk/api-reference/assets/register-cms-block-example.png b/docs/admin-sdk/develop/assets/register-cms-block-example.png similarity index 100% rename from docs/admin-sdk/api-reference/assets/register-cms-block-example.png rename to docs/admin-sdk/develop/assets/register-cms-block-example.png diff --git a/docs/admin-sdk/api-reference/assets/register-cms-element-example.png b/docs/admin-sdk/develop/assets/register-cms-element-example.png similarity index 100% rename from docs/admin-sdk/api-reference/assets/register-cms-element-example.png rename to docs/admin-sdk/develop/assets/register-cms-element-example.png diff --git a/docs/admin-sdk/api-reference/assets/toast-example.png b/docs/admin-sdk/develop/assets/toast-example.png similarity index 100% rename from docs/admin-sdk/api-reference/assets/toast-example.png rename to docs/admin-sdk/develop/assets/toast-example.png diff --git a/docs/admin-sdk/api-reference/assets/useSharedState-demo.gif b/docs/admin-sdk/develop/assets/useSharedState-demo.gif similarity index 100% rename from docs/admin-sdk/api-reference/assets/useSharedState-demo.gif rename to docs/admin-sdk/develop/assets/useSharedState-demo.gif diff --git a/docs/admin-sdk/develop/cms/index.md b/docs/admin-sdk/develop/cms/index.md new file mode 100644 index 000000000..29406b7dd --- /dev/null +++ b/docs/admin-sdk/develop/cms/index.md @@ -0,0 +1,10 @@ +--- +title: "Extending the CMS" +nav: + position: 300 +--- + + +# Extending the CMS + +These APIs allow extensions to register new CMS blocks and CMS elements for use in the Shopware Shopping Experiences editor. diff --git a/docs/admin-sdk/api-reference/cms/registerCmsBlock.md b/docs/admin-sdk/develop/cms/registerCmsBlock.md similarity index 98% rename from docs/admin-sdk/api-reference/cms/registerCmsBlock.md rename to docs/admin-sdk/develop/cms/registerCmsBlock.md index 3f574e9bd..99249dd2b 100644 --- a/docs/admin-sdk/api-reference/cms/registerCmsBlock.md +++ b/docs/admin-sdk/develop/cms/registerCmsBlock.md @@ -1,3 +1,9 @@ +--- +title: "Register CMS block" +sidebar_position: 2 +--- + + # Register CMS block > Available since Shopware v6.6.1.0 @@ -6,7 +12,8 @@ With `cms.registerCmsBlock` you can register CMS blocks to use in the Shopping E ![Register a CMS block in your Shopping Experiences Module via App](../assets/register-cms-block-example.png) -#### Usage: +#### Usage + ```ts cms.registerCmsBlock({ name: 'dailymotion-dual-block', @@ -25,6 +32,7 @@ cms.registerCmsBlock({ ``` #### Parameters + | Name | Required | Description | | :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | true | The name of the cms block - Should have vendor prefix. It can be used in the Storefront for overriding the default layout. | @@ -65,4 +73,4 @@ Example: {% endfor %} {% endblock %} -``` \ No newline at end of file +``` diff --git a/docs/admin-sdk/api-reference/cms/registerCmsElement.md b/docs/admin-sdk/develop/cms/registerCmsElement.md similarity index 93% rename from docs/admin-sdk/api-reference/cms/registerCmsElement.md rename to docs/admin-sdk/develop/cms/registerCmsElement.md index b63f735b9..88d4119dc 100644 --- a/docs/admin-sdk/api-reference/cms/registerCmsElement.md +++ b/docs/admin-sdk/develop/cms/registerCmsElement.md @@ -1,4 +1,10 @@ -# Register CMS element +--- +title: "Register CMS Element" +sidebar_position: 3 +--- + + +# Register CMS Element > Available since Shopware v6.4.17.0 @@ -7,7 +13,8 @@ More information on how to develop CMS elements can be found in these guides for ![Register a CMS element in your Shopping Experiences Module via App](../assets/register-cms-element-example.png) -#### Usage: +#### Usage + ```ts void cms.registerCmsElement({ name: 'dailymotionElement', @@ -22,6 +29,7 @@ void cms.registerCmsElement({ ``` #### Parameters + | Name | Required | Description | |:----------------|:---------|:---------------------------------------------------------------------------------------------------------| | `name` | true | The name of the cms element, which will also be used to generate locationIds - Should have vendor prefix | diff --git a/docs/admin-sdk/develop/composables/index.md b/docs/admin-sdk/develop/composables/index.md new file mode 100644 index 000000000..84c9a8339 --- /dev/null +++ b/docs/admin-sdk/develop/composables/index.md @@ -0,0 +1,17 @@ +--- +title: "Composable APIs" +nav: + position: 10 +--- + + +# Composable APIs + +Composable APIs provide reusable helpers for working with the Shopware Administration data layer and shared state inside extensions. + +They simplify common tasks such as accessing repositories or sharing reactive state between different parts of an extension. + +Currently, the SDK exposes two composables: + +- [useRepository](./useRepository.md): Access Shopware entity repositories to load and manipulate data. +- [useSharedState](./useSharedState.md): Share reactive state between different extension components. diff --git a/docs/admin-sdk/api-reference/composables/useRepository.md b/docs/admin-sdk/develop/composables/useRepository.md similarity index 91% rename from docs/admin-sdk/api-reference/composables/useRepository.md rename to docs/admin-sdk/develop/composables/useRepository.md index d858b9252..81bb5bfb6 100644 --- a/docs/admin-sdk/api-reference/composables/useRepository.md +++ b/docs/admin-sdk/develop/composables/useRepository.md @@ -1,10 +1,22 @@ +--- +title: "useRepository" +nav: + position: 20 +--- + + # useRepository +:::info +Some older examples reference `getRepository`. This helper is not part of the public API. Use [`useRepository`](./useRepository.md) instead. +::: + The `composables.useRepository` function is a reactive wrapper around the `getRepository` function. It creates a repository instance that automatically updates when its dependencies change. This is particularly useful when you need a repository that responds to reactive data changes in your Vue components. Unlike `getRepository`, which returns a static repository instance, `useRepository` accepts reactive references (refs) or values as parameters and returns a computed repository that updates when those parameters change. -#### Usage: +## Usage + ```ts // Inside a Vue component setup import { ref } from 'vue'; @@ -27,7 +39,7 @@ const repository = useRepository('product', myFactory); const products = await repository.value.search(criteria); ``` -## Dynamic Repository Creation +## Dynamic repository creation The main advantage of `useRepository` is that it automatically recreates the repository when its inputs change: @@ -36,13 +48,15 @@ The main advantage of `useRepository` is that it automatically recreates the rep This reactivity is implemented using Vue's computed properties, ensuring that the repository is only recreated when necessary. -#### Parameters +## Parameters + | Name | Required | Description | |:--------------------|:---------|:----------------------------------------------------------------| | `entityNameRef` | true | The name of the entity type as a ref or static value | | `repositoryFactory` | false | Optional repository factory as a ref or static value | -#### Return Value +## Return value + A computed ref containing a repository that updates when its dependencies change. The repository provides the same methods as described in the `getRepository` documentation, but you need to access them through the `.value` property of the computed ref. ## Relationship with getRepository diff --git a/docs/admin-sdk/api-reference/composables/useSharedState.md b/docs/admin-sdk/develop/composables/useSharedState.md similarity index 92% rename from docs/admin-sdk/api-reference/composables/useSharedState.md rename to docs/admin-sdk/develop/composables/useSharedState.md index cdaa9ce1d..01ac63600 100644 --- a/docs/admin-sdk/api-reference/composables/useSharedState.md +++ b/docs/admin-sdk/develop/composables/useSharedState.md @@ -1,3 +1,9 @@ +--- +title: "useSharedState" +nav: + position: 30 +--- + # useSharedState The `composables.useSharedState` function allows you to create globally accessible state in your app. The state defined within this composable has a unique key, and any other part of the app that uses the same composable with the same key will access the same data. @@ -6,9 +12,10 @@ The shared state is reactive, meaning that when you update the data in one place The value stored within the shared state can be any data type that can be serialized to JSON. Additionally, we have added support for Entities and EntityCollections. -![useShardState demo](../assets/useSharedState-demo.gif) +![useSharedState demo](../assets/useSharedState-demo.gif) + +## Usage -#### Usage: ```ts // Inside a Vue component setup import { composables } from '@shopware-ag/meteor-admin-sdk'; @@ -17,7 +24,8 @@ const { useSharedState } = composables; const mySharedStateValue = useSharedState('myUniqueKeyForTheSharedState', 'myInitialDataValue'); ``` -#### Parameters +### Parameters + | Name | Required | Description | | :------------- | :------- | :------------------------------------------------------------------------ | | `key` | true | The unique key used to share the state across different places | diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/develop/context.md similarity index 99% rename from docs/admin-sdk/api-reference/context.md rename to docs/admin-sdk/develop/context.md index 31887b6bc..4de52de40 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/develop/context.md @@ -1,3 +1,9 @@ +--- +title: "Context" +sidebar_position: 40 +--- + + # Context ## Language diff --git a/docs/admin-sdk/develop/devtools.md b/docs/admin-sdk/develop/devtools.md new file mode 100644 index 000000000..d2967a0a2 --- /dev/null +++ b/docs/admin-sdk/develop/devtools.md @@ -0,0 +1,80 @@ +--- +title: "Finding Extension Points with Vue DevTools" +sidebar_position: 20 +--- + + +# Finding Extension Points with Vue DevTools + +This guide describes the recommended tooling for developing and debugging Administration extensions built with the Meteor Admin SDK. + +The Shopware Administration provides many extension points, often implemented as components identified by a unique `positionId`. Identifying the correct `positionId` manually can require searching through the core source code, and can become time-consuming. + +A more efficient approach is to use the [Vue DevTools](https://devtools.vuejs.org/) plugin. The Shopware Administration integrates a Shopware Extension API plugin that works with Vue DevTools, enabling interactive discovery of extension points. + +Vue DevTools is **optional** but strongly recommended. + +## Prerequisites + +- A running Shopware instance +- A working app or plugin +- Vue DevTools installed in the browser. This tool is available for Chrome, Firefox, Edge, or as a standalone application, and can be used for inspecting Vue components and extension points inside the Shopware Administration. + +The Shopware Extension API plugin for Vue DevTools is available starting with Vue DevTools version 6+ (currently distributed via the [beta channel](https://chrome.google.com/webstore/detail/vuejs-devtools/ljjemllljcmogpfapbkkighbhhppjdbg)). It can be installed alongside older versions. If using a version prior to 6, the plugin will not work. + +## 1. Start the Administration watcher + +Before inspecting extension points, start the Administration build watcher: + +```bash +composer run watch:admin +``` + +Wait until the compilation finishes successfully. This rebuilds the Administration and enables development mode features. + +After installing the browser extension, open the Shopware Administration in development/watch mode. + +To verify that the plugin is active, open the DevTools settings and ensure the Shopware Admin plugin is installed and enabled. + +## 2. Open the Shopware Extension API plugin + +Open the Shopware Administration, then open the browser’s developer tools and navigate to the Vue tab. Select the Shopware Extension API plugin. + +![Devtools plugin](./assets/devtools-plugin.png) + +![Vue Devtools plugin settings](./assets/devtools-plugin-settings.png) + +![Vue Devtools plugin settings list](./assets/devtools-plugin-settings-list.png) + +## 3. Find extension points + +The plugin displays all available extension points for the current page. It is possible to: + +- Select an extension point to highlight the corresponding area in the Administration. +- Inspect available properties and metadata. +- Identify where and how to extend the UI using the Meteor Admin SDK. + +This helps you to understand: + +- Which extension points are available +- What data is exposed +- How the extension interacts with the Administration. + +![Devtools usage](./assets/devtools-usage.png) + +Navigate to the page you want to extend. For example, open the product detail page and switch to the **Specifications** tab. + +Open the Shopware Extension API plugin from the Vue DevTools dropdown: + +![Vue Devtools plugin tab Shopware extension](./assets/devtools-plugin-tab-shopware-extension.png) + +On the left side is a list of available extension points. Selecting one highlights the corresponding area in the Administration. + +![Vue Devtools plugin extension point selection](./assets/devtools-plugin-extension-point-selection.png) + +The DevTools inspector displays additional details about the selected extension point, including: + +- The `property` value (referenced in the API documentation) +- The `positionId`, which uniquely identifies the extension location (required in most cases) + +Use the `positionId` to target a specific extension point instead of extending all instances globally. diff --git a/docs/admin-sdk/develop/entity-types.md b/docs/admin-sdk/develop/entity-types.md new file mode 100644 index 000000000..f549fc53b --- /dev/null +++ b/docs/admin-sdk/develop/entity-types.md @@ -0,0 +1,94 @@ +--- +title: "Adding Entity Types" +sidebar_position: 100 +--- + + +# Adding Entity Types (TypeScript) + +The Meteor Admin SDK supports TypeScript typings for Shopware entities. Adding entity types enables type-safe access, editing, and saving of entities when working with repositories. + +To enable typings, create a global declaration file such as `global.d.ts` and extend the `EntitySchema` namespace. + +## Option 1: Use Shopware’s generated entity types (recommended) + +Shopware provides generated TypeScript definitions for all core entities. + +Install the package that matches your Shopware version: + +```bash +npm install @shopware-ag/entity-schema-types@5.0.0 +``` + +The package version corresponds to the Shopware version without the leading `6.`. Examples: + +`Shopware 6.5.0.0` → `@shopware-ag/entity-schema-types@5.0.0` +`Shopware 6.5.1.2` → `@shopware-ag/entity-schema-types@5.1.2` +`Shopware 6.6.3.1` → `@shopware-ag/entity-schema-types@6.3.1` + +Then import the types in your global declaration file: + +```ts +// global.d.ts +import '@shopware-ag/entity-schema-types'; +``` + +## Option 2: Use a fallback `any` type + +This is the simplest solution, but it removes type safety. If strict typing isn't required, it's possible to define a fallback type for all entities by setting the type to `any`: + +```ts +// global.d.ts +declare namespace EntitySchema { + interface Entities { + [entityName: string]: any; + } +} +``` + +This avoids type errors but disables type safety. + +## Option 3: Define custom entity types + +This option provides full control by defining entity types manually for each property and association. The drawback is the additional effort required to maintain the definitions. + +```ts +// global.d.ts +declare namespace EntitySchema { + interface Entities { + // using product_manufacturer as an example + product_manufacturer: product_manufacturer; + // in this case 'media', 'product' and 'product_manufacturer_translation' is also needed + ... + } + + interface product_manufacturer { + id: string; + versionId: string; + mediaId?: string; + link?: string; + name: string; + description?: string; + customFields?: unknown; + /* + * Entity and EntityCollection is defined in the namespace and can directly be used. + * The value in the generic (here 'media', 'product' and 'product_manufacturer_translation') must + * also be defined in this file. + */ + media?: Entity<'media'>; + products?: EntityCollection<'product'>; + translations: EntityCollection<'product_manufacturer_translation'>; + createdAt: string; + updatedAt?: string; + translated?: {name?: string, description?: string, customFields?: unknown}; + } + + ... +} +``` + +It is necessary to define types for any referenced entities, such as: + +- `media` +- `product` +- `product_manufacturer_translation` diff --git a/docs/admin-sdk/develop/index.md b/docs/admin-sdk/develop/index.md new file mode 100644 index 000000000..49921158e --- /dev/null +++ b/docs/admin-sdk/develop/index.md @@ -0,0 +1,53 @@ +--- +title: "Start Developing" +sidebar_position: 30 +--- + + +# Start Developing + +This section explains how to build Administration extensions with the Meteor Admin SDK, using core extension capabilities such as UI extension points, composables, and tooling. + +A typical Administration extension follows this workflow: + +1. Identify an extension point in the Administration UI. +2. Add a [main module](../api-reference/ui/mainModule) or [action button](../api-reference/ui/actionButton) at that [location](./api/location). + - **Location**: Defines where extension code runs inside the Administration UI. + - **Main module**: The entry point of your extension inside the Administration navigation. + - **Action button**: Adds functionality to an existing Administration view, such as the product detail page. +3. Load or modify Shopware data using [repositories](./composables/use-repository). +4. Provide feedback to users with [notifications](./notification) or [toasts](./toast). + +## Development Tools + +Use the [DevTools](./devtools.md) guide to discover extension points and inspect the Administration UI with Vue DevTools. + +## Extension APIs + +The following APIs allow extensions to interact with and extend the Shopware Administration UI: + +- **[Location](./location)**: Determine where your extension is rendered inside the Administration. +- **[Context](./context)**: Access information about the current Administration context. +- **[Notification](./notification)**: Display notification messages to users. +- **[Toast](./toast)**: Show temporary toast messages. +- **[Window](./window)**: Interact with browser windows or external links. +- **[Translations](./translations)**: Localize extension UI using snippet files and synchronize language changes with the Administration. + +## Composables + +Composables provide reusable helpers for working with Administration data and shared state. + +- **[useRepository](./composables/use-repository)**: Access Shopware repositories to load and manipulate entities. +- **[useSharedState](./composables/use-shared-state)**: Share state between extensions or components. + +## CMS extensions + +The CMS API allows extensions to add new CMS blocks and elements to the Shopware content system. + +- **[Register CMS Block](./cms/register-cms-block)**: Add custom CMS blocks that structure and group content elements in the Shopping Experiences editor. +- **[Register CMS Element](./cms/register-cms-element)**: Create custom CMS elements that render specific content or functionality inside CMS blocks. + +## Advanced topics + +- **[Entity Types](./entity-types)**: Configure and extend TypeScript typings for entity access and SDK usage. +- **[Migrating Existing Admin Plugins](./migrating-existing-admin-plugins)**: Learn how to gradually migrate existing Twig-based Admin plugins to the Meteor Admin SDK. diff --git a/docs/admin-sdk/api-reference/location.md b/docs/admin-sdk/develop/location.md similarity index 66% rename from docs/admin-sdk/api-reference/location.md rename to docs/admin-sdk/develop/location.md index 70cc5bb91..a2c40a4a5 100644 --- a/docs/admin-sdk/api-reference/location.md +++ b/docs/admin-sdk/develop/location.md @@ -1,14 +1,26 @@ +--- +title: "Location" +sidebar_position: 30 +--- + + # Location +Locations define where extension code is executed inside the Shopware Administration. + +Each location represents a specific UI context (for example a tab, modal, sidebar, or hidden entry point). Extensions typically check the current location before deciding which UI elements to register or which view to render. + +See [Locations](../concepts/locations.md) for a full explanation of the concept. + ## Prerequisites + We recommend you read the [concept](../concepts/locations.md) of locations first. -## Location checks -### Check the current location id +## Location checks -Check if the current location matches the given location Id. +### Check the current location ID -#### Usage: +Check if the current location matches the given location ID: ```ts if (sw.location.is('my-location-id')) { @@ -16,25 +28,26 @@ if (sw.location.is('my-location-id')) { } ``` -#### Parameters: +### Parameters + | Name | Required | Default | Description | | :----------- | :------- | :------ | :----------------------- | -| `locationId` | true | | The location Id to check | +| `locationId` | true | | The location ID to check | -#### Return value: -Returns a boolean. It is `true` if the location Id matches the current location. +### Return value -### Get the current location id +Returns a boolean. It is `true` if the location ID matches the current location. -Get the name of the current location ID +### Get the current location ID -#### Usage: +Get the name of the current location ID: ```ts const currentLocation = sw.location.get() ``` -#### Return value: +### Return value + Returns a string with the name of the current location. ### Check if current location is inside iFrame @@ -42,8 +55,6 @@ Returns a string with the name of the current location. Useful for hybrid extensions which are using plugin and Extension SDK functionalities together (Shopware 6.6 and lower). You can use this check to separate code which should be executed inside the Extension SDK context and the plugin context. -#### Usage: - ```ts if (location.isIframe()) { // Execute the code which uses the meteor-admin-sdk context @@ -54,64 +65,66 @@ if (location.isIframe()) { } ``` -## iFrame Heights +## iFrame heights + +### Parameters -#### Parameters: No parameters needed. -#### Return value: -Returns a boolean. If it is executed inside a iFrame it returns `true`. +### Return value -### Update the height of the location iFrame +Returns a boolean. Returns `true` if executed inside an iFrame. -You can update the height of the iFrame with this method. +### Update the height of the location iFrame -#### Usage: +Update the height of the iFrame with this method: ```ts sw.location.updateHeight(750); ``` -#### Parameters: +### Parameters + | Name | Required | Default | Description | | :-------------- | :------- | :------------- | :------------------------------------------------------------------------------------------------------------- | | `iFrame height` | false | Auto generated | The height of the iFrame. If no value is provided it will be automatically calculated from the current height. | -#### Return value: +### Return value + This method does not have a return value. ### Start auto resizing of the iFrame height -This methods starts the auto resizer of the iFrame height. +This method starts the auto resizer of the iFrame height. ![Auto resizing example](../concepts/assets/auto-resizer.gif) -#### Usage: - ```ts sw.location.startAutoResizer(); ``` -#### Parameters: +### Parameters + No parameters needed. -#### Return value: +### Return value + This method does not have a return value. ### Stop auto resizing of the iFrame height -This methods stops the auto resizer of the iFrame height. - -#### Usage: +This method stops the auto resizer of the iFrame height: ```ts sw.location.stopAutoResizer(); ``` -#### Parameters: +### Parameters + No parameters needed. -#### Return value: +### Return value + This method does not have a return value. ## URL changes inside your app @@ -125,9 +138,7 @@ Important: You can track and emit your URL changes only inside your own main mod ### Update URL Send the current URL of your iFrame to the administration. When the user reloads the whole page your iFrame will get the -last page you sent to the administration. - -#### Usage: +last page you sent to the administration: ```ts const currentUrl = window.location.href; @@ -135,17 +146,16 @@ const currentUrl = window.location.href; sw.location.updateUrl(new URL(currentUrl)) ``` -#### Parameters: +### Parameters + | Name | Required | Default | Description | | :-------------- | :------- | :------ | :------------------------------------ | | First parameter | true | | An URL object which contains your URL | ### Start automatic URL updates -To avoid manually sending URL changes you can use this helper methods. It sends automatically changes in your URL to the -administration. - -#### Usage: +To avoid manually sending URL changes, use this helper method that automatically sends changes in the URL to the +Administration: ```ts sw.location.startAutoUrlUpdater(); @@ -153,10 +163,8 @@ sw.location.startAutoUrlUpdater(); ### Stop automatic URL updates -If you had started an automatic URL updater before then you can stop it by calling this method. - -#### Usage: +Stop automatic URL updaters by calling this method: ```ts sw.location.stopAutoUrlUpdater(); -``` \ No newline at end of file +``` diff --git a/docs/admin-sdk/develop/migrating-admin-plugins.md b/docs/admin-sdk/develop/migrating-admin-plugins.md new file mode 100644 index 000000000..291f39a79 --- /dev/null +++ b/docs/admin-sdk/develop/migrating-admin-plugins.md @@ -0,0 +1,98 @@ +--- +title: "Migrating Existing Admin Plugins" +sidebar_position: 110 +--- + + +# Migrating Existing Admin Plugins + +The Meteor Admin SDK can be adopted gradually in existing Shopware Admin plugins. This guide shows how to combine the traditional Twig-based extension system with the SDK so you can migrate functionality step by step. + +## Combining the Meteor Admin SDK with existing plugins + +Shopware 6 has a rich Admin plugin extension system based on Twig and the concepts of component overriding and component extending. These concepts are very powerful, but they can also come with a steep learning curve. For this reason, you can migrate gradually to the Meteor Admin SDK. + +Both approaches can work together. This allows you to start by converting only parts of your plugins and then gradually migrate more functionality as new SDK features become available. + +This approach can also help simplify your plugins and prepare them for long-term maintenance. + +### Example + +```js +// Use existing extension capabilties +Shopware.Component.override('sw-dashboard-index', { + methods: { + async createdComponent() { + // Can also use Meteor Admin SDK features + await sw.notification.dispatch({ + title: 'Hello from the plugin', + message: 'I am combining the existing approach with the new SDK approach', + }) + + this.$super('createdComponent'); + } + } +}); +``` + +## Using locations with normal Vue components without iFrame rendering + +**This feature is not yet released in Shopware. It's only available with the development environment or `dev-trunk` version of Shopware.** + +This feature is useful when you want to partially migrate from the Twig plugin system to the SDK extension system and use both systems together. Instead of rendering an iFrame view for a location, you can render a normal Vue component directly inside the Shopware Administration. + +To do this, register the component in the existing plugin system: + + +```js +Shopware.Component.register('your-component-name', { + // your component +}) +``` + +To render the component in a location, add the component name to the location using the `sdkLocation` store: + +```js +Shopware.State.commit('sdkLocation/addLocation', { + locationId: 'your-location-id', + componentName: 'your-component-name' +}) +``` + +With this feature you can mix the usage of the Meteor Admin SDK and the existing plugin system. A complete example could look like this: It creates a new tab in the product detail page, renders a card using the `componentSection` renderer, and displays a location inside the card. Instead of rendering the traditional location iFrame, it renders a Vue component registered in the Shopware Component Factory. + +```js +// in a normal plugin js file without a HTML file +import { ui, location } from '@shopware-ag/meteor-admin-sdk'; + +if (!location.isIframe()) { + const myLocationId = 'my-example-location-id'; + + // Create a new tab entry + ui.tabs('sw-product-detail').addTabItem({ + label: 'Example tab', + componentSectionId: 'example-product-detail-tab-content' + }) + + // Add a new card to the tab content which renders a location + ui.componentSection.add({ + component: 'card', + positionId: 'example-product-detail-tab-content', + props: { + title: 'Component section example', + locationId: myLocationId + } + }) + + // Register your component which should be rendered inside the location + Shopware.Component.register('your-component-name', { + // your component + }) + + // Add the component name to the specific location + Shopware.State.commit('sdkLocation/addLocation', { + locationId: myLocationId, + componentName: 'your-component-name' + }) +} +``` diff --git a/docs/admin-sdk/api-reference/notification.md b/docs/admin-sdk/develop/notification.md similarity index 87% rename from docs/admin-sdk/api-reference/notification.md rename to docs/admin-sdk/develop/notification.md index 1bd4fbb59..a7bdf6b73 100644 --- a/docs/admin-sdk/api-reference/notification.md +++ b/docs/admin-sdk/develop/notification.md @@ -1,10 +1,21 @@ +--- +title: "Notification" +sidebar_position: 50 +--- + + # Notification -### Dispatch a notification +Notifications display persistent messages in the Shopware Administration to inform users about events, errors, or completed actions. + +See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. + +## Dispatch a notification ![notification example](./assets/notification-example.jpg) -#### Usage: +### Usage + ```ts function alertYes() { alert('Yes'); @@ -36,7 +47,8 @@ sw.notification.dispatch({ }) ``` -#### Parameters: +### Parameters + | Name | Required | Default | Description | |:-------------|:---------|:---------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `title` | true | | Defines a notification's **title**. | @@ -46,5 +58,6 @@ sw.notification.dispatch({ | `growl` | false | `true` | Displays a notification that is overlaying any module. Use `false` to display the notification in the notification center (bell symbol) only. | | `actions` | false | `[]` | Adds clickable buttons to the notification. Each button with a `label` can trigger a `method` or open a `route` (internal route or external link). Buttons can also be disabled using the attribute `disabled`. | -#### Return value: +## Return value + Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/toast.md b/docs/admin-sdk/develop/toast.md similarity index 65% rename from docs/admin-sdk/api-reference/toast.md rename to docs/admin-sdk/develop/toast.md index 8778a393e..4113d344f 100644 --- a/docs/admin-sdk/api-reference/toast.md +++ b/docs/admin-sdk/develop/toast.md @@ -1,13 +1,25 @@ +--- +title: "Toast" +sidebar_position: 60 +--- + + # Toast +Toasts display short, temporary messages to provide feedback about user actions or system events. + +See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. + ## Availability + This feature will be available with Shopware 6.6.2.0. ### Dispatch a toast ![toast example](./assets/toast-example.png) -#### Usage: +#### Usage + ```ts function alertYes() { alert('Yes'); @@ -24,14 +36,16 @@ sw.toast.dispatch({ }) ``` -#### Parameters: +#### Parameters + | Name | Required | Default | Description | |:--------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------| | `msg` | true | | Defines a toast's main expression or message to the user. | | `type` | true | | Defines the toast type. Available `types` are `positive`, `informal` and `critical`. | -| `icon ` | false | None | A icon that should be displayed in front of your message. | -| `dismissible` | false | `false` | Specifies if the toast can be manually dismmissed. | -| `action` | false | None | Adds a clickable button to the toast. The button receives a label and a callback wichs is called once clicked. | +| `icon ` | false | None | An icon that should be displayed in front of your message. | +| `dismissible` | false | `false` | Specifies if the toast can be manually dismissed. | +| `action` | false | None | Adds a clickable button to the toast. The button receives a label and a callback which is called once clicked. | + +#### Return value -#### Return value: Returns a promise without data. diff --git a/docs/admin-sdk/develop/translations.md b/docs/admin-sdk/develop/translations.md new file mode 100644 index 000000000..5f3ef2cdd --- /dev/null +++ b/docs/admin-sdk/develop/translations.md @@ -0,0 +1,50 @@ +--- +title: "Translations" +sidebar_position: 80 +--- + + +# Translations + +Extensions can localize text displayed in the Shopware Administration using snippet files and a frontend translation library. + +For content rendered inside your extension UI, you can use any translation solution supported by your frontend framework (for example, the Vue i18n plugin). To keep translations synchronized with the Administration language, listen for language changes using the [Context API](./context.md#subscribe-on-language-changes). + +For text rendered [inside](../concepts/locations.md) native Administration UI components (such as titles inside [component sections](../concepts/component-sections.md)), Shopware supports snippet files inside the app. + +## Creating snippet files + +Create one snippet file per supported language in the app. These files should reside in the `Resources/app/administration/snippet` directory. + +Use the language code as the filename—for example: `en-GB.json` for English language support. The file structure mirrors that of administration snippets. Example snippet file: + +```json +// /Resources/app/administration/snippet/en-GB.json +{ + "my-app-name": { + "example-card": { + "title": "My app", + "subtitle": "This is my app" + } + } +} +``` + +Snippet files follow the same structure used by the Shopware Administration. Overriding existing Administration snippets is possible, if needed. + +## Using snippets in an extension + +Reference snippet keys directly in the UI configuration. Example: + +```js +sw.ui.componentSection('sw-manufacturer-card-custom-fields__before').add({ + component: 'card', + props: { + title: 'my-app-name.example-card.title', + subtitle: 'my-app-name.example-card.subtitle', + locationId: 'my-app-card-before-properties' + } +}) +``` + +When the Administration language changes, the corresponding snippet file is automatically used. diff --git a/docs/admin-sdk/develop/window.md b/docs/admin-sdk/develop/window.md new file mode 100644 index 000000000..ecbbbf811 --- /dev/null +++ b/docs/admin-sdk/develop/window.md @@ -0,0 +1,148 @@ +--- +title: "Window" +sidebar_position: 70 +--- + + +# Window + +The Window API provides methods for navigation and window-related utilities inside the Shopware Administration. + +## redirect() + +Redirect to an external URL. + +### Usage + +Use this method to open an external URL either in the current tab or a new tab. + +```ts +sw.window.redirect({ + url: 'https://www.shopware.com', + newTab: true +}) +``` + +### Parameters + +| Name | Required | Default | Description | +| :------ | :------ | :------ | :------ | +| `url` | true | | The URL to open | +| `newTab` | false | false | Open the URL in a new browser tab | + +### Return value + +Returns a promise without data. + +## routerPush() + +Navigate to another page inside the Shopware Administration. + +### Usage + +This method mirrors the behavior of Vue Router’s `push()`. + +Navigate using a named route: + +```ts +sw.window.routerPush({ + name: 'sw.extension.sdk.index', + params: { + id: 'the_id_of_the_module' // can be retrieved with context.getModuleInformation + } +}) +``` + +Alternatively, navigate using a path: + +```ts +sw.window.routerPush({ + path: `/extension/${the_id_of_the_module}` // id can be retrieved with context.getModuleInformation +}) +``` + +### Parameters + +| Name | Required | Default | Description | +| :------ | :------ | :------ | :------ | +| `name` | false | undefined | Name of the route | +| `path` | false | undefined | Path of the route | +| `params` | false | undefined | Additional params for the new route | +| `replace` | false | false | Replace current browser history entry | + +### Return value + +Returns a promise without data. + +## reload() + +Reload the current Administration page. This can be useful during development or when UI state must be reset. + +### Usage + +```ts +sw.window.reload() +``` + +### Parameters + +No parameters required. + +### Return value + +Returns a promise without data. + +## getId() + +> Available since Shopware v6.7.1.0 + +Returns a unique identifier for the current browser window. This is useful when working with session storage or detecting duplicated tabs. + +### Usage + +```ts +sw.window.getId() +``` + +### Parameters + +No parameters required + +### Return value + +A `string` representing a unique identifier for the current window. + +### Example + +This example clears `sessionStorage` when a duplicated browser tab is detected. This can happen if a user uses the *Duplicate Tab* feature of some browsers. + +```ts +const windowId = sw.window.getId(); +const storedWindowId = globalThis.sessionStorage.getItem('window-id'); + +if (windowId !== storedWindowId) { + globalThis.sessionStorage.clear(); + globalThis.sessionStorage.setItem('window-id', windowId); +} + +``` + +## getPath() + +> Available since Shopware v6.7.3.0 + +Retrieve the current Administration router path. + +### Usage + +```ts +sw.window.getPath() +``` + +### Parameters + +No parameters required. + +### Return value + +Returns a `string` containing the full path, or an empty string if the router is not available. diff --git a/docs/admin-sdk/faq/index.md b/docs/admin-sdk/faq/index.md deleted file mode 100644 index ce7b1372b..000000000 --- a/docs/admin-sdk/faq/index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "FAQ" -nav: - position: 1100 ---- - -# FAQ - -## Can I use the same domain with subfolders for multiple apps? -No, for technical reasons, it is not possible to use the same domain with subfolders to host multiple apps. Each app must have its own separate domain. -The preferred solution is to use subdomains for each app. For example, you can use subdomains like "app-one.your-company.com", "app-two.your-company.com", and so on. Using subdomains allows you to have separate domains for each app, which avoids the technical limitations associated with using subfolders. - -## How can I use components that resemble the original components in the administration? -While it is not possible to use the exact same components in the Shopware administration, there is a component library called Meteor Component Library that offers similar components. The Shopware administration components are not native Vue components because they have extension capabilities, Twig templates, and other features that cannot be directly used. However, by utilizing the Meteor Component Library, you can achieve a native look and feel for your app that seamlessly integrates with the original Shopware administration. - -To access the Meteor Component Library, visit the following link: https://github.com/shopware/meteor-component-library - -## How can I use snippets to translate my app? - -You can manage all texts rendered within your [locations](../concepts/locations.md) with a translation plugin of your choice. If you're utilizing Vue.js as your frontend framework, you can use the i18n plugin. Additionally, to ensure consistency between your app and the Shopware Administration, you can synchronize language changes by [subscribing to them through the context API](../api-reference/context.md#subscribe-on-language-changes). - -For text elements in native Shopware Administration components, such as titles within [component sections](../concepts/component-sections.md), you can employ snippet files within your app. This is supported since the Shopware Version 6.6. Here's a how to accomplish this: - -1. **Create Snippet Files:** Begin by generating a snippet file for each supported language within your app. These files should reside in the `Resources/app/administration/snippet` directory. Naming conventions follow the language code format, for instance, `en-GB.json` for English language support. The file structure mirrors that of administration snippets. However it is not impossible to overwrite Shopware Administration snippets. - -```json -// /Resources/app/administration/snippet/en-GB.json -{ - "my-app-name": { - "example-card": { - "title": "My app", - "subtitle": "This is my app" - } - } -} -``` - -2. **Integrate Snippets:** Utilize these snippets within your app by referencing their paths directly in your code. For example: - -```js -sw.ui.componentSection('sw-manufacturer-card-custom-fields__before').add({ - component: 'card', - props: { - title: 'my-app-name.example-card.title', - subtitle: 'my-app-name.example-card.subtitle', - locationId: 'my-app-card-before-properties' - } -}) -``` diff --git a/docs/admin-sdk/getting-started/devTools.md b/docs/admin-sdk/getting-started/devTools.md deleted file mode 100644 index 5eec0f712..000000000 --- a/docs/admin-sdk/getting-started/devTools.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Vue dev tools" -sidebar_position: 2 ---- - -# Vue dev tools - -## Prerequisites -We assume that you got the [Vue dev tools](https://devtools.vuejs.org/) installed for your browser. -The extension is available for Chrome, Firefox, Edge and as a standalone app. - -## Development setup -Furthermore you should have [Shopware](https://github.com/shopware/platform) setup. -To make use of the Extension API plugin for the Vue dev tools start the watcher of the administration: - -```bash -$ composer run watch:admin -``` - -## Vue dev tool plugin -Once you logged into your administration, open up the development tools of your browser and choose the Vue tab. -Inside the Vue tab choose the Shopware Extension API plugin. - -![Devtools plugin](./assets/devtools-plugin.png) - -## Usage -The plugin will show you all extension points for the current page you visit. -Once you select an extension point it will highlight the corresponding area in the viewport and give detailed information how to extend the highlighted property. - -![Devtools usage](./assets/devtools-usage.png) \ No newline at end of file diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index 3deb6836a..388c7c749 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -1,5 +1,121 @@ --- -title: "Getting started" +title: "Getting Started" nav: position: 10 --- + + +# Getting Started + +Learn how to install and set up the Meteor Admin SDK to start building extensions for the Shopware Administration. + +## Install the SDK + +There are two ways to install the Meteor Admin SDK: + +- **npm + Vite (recommended)**: for production extensions with a build pipeline +- **CDN**: for quick prototypes without a build step + +### Using npm and Vite (recommended) + +Using npm is recommended for production environments. It enables proper bundling and tree-shaking, ensuring that only the required functionality is included in your final bundle. + +[Vite](https://vitejs.dev/guide/) is a JavaScript build tool that bundles your frontend code and dependencies for use in the Shopware Administration. + +Install the SDK and Vite: + +```bash +npm install @shopware-ag/meteor-admin-sdk +npm install vite +``` + +#### Import variants + +The SDK can be imported in several ways depending on the bundling setup. Import the SDK in your frontend entry file (for example, `main.js`). + +Import the full SDK (for quick prototyping or when using many SDK features): + +```js +import * as sw from '@shopware-ag/meteor-admin-sdk'; +``` + +Import only the required module (recommended for better tree-shaking and reduced bundle size): + +```js +import { notification } from '@shopware-ag/meteor-admin-sdk'; +``` + +Direct method import (for maximum bundle optimization; imports a specific internal module): + +```js +import { dispatch as dispatchNotification } from '@shopware-ag/meteor-admin-sdk/es/notification'; +``` + +The path depends on your build configuration. + +### Configure Vite + +Configure Vite according to your extension’s frontend setup. See the [official Vite documentation](https://vitejs.dev/guide/) for configuration details. + +The extension frontend might have a structure similar to this: + +```plaintext +custom/plugins/yourPlugin/src/Resources/app/meteor-app +├── index.html +├── vite.config.js (optional) +├── package.json +├── package-lock.json +├── src +│ ├── main.js +``` + +### Run the development server + +Start the Vite development server: + +```bash +npx vite +``` + +Vite will bundle the SDK and serve the frontend during development. + +### Verify the installation + +If the extension loads in the Administration and the notification example runs successfully, the SDK is installed correctly. + +## Minimal "Hello World" example with the CDN build + +If you do not want to use a build tool, the SDK can also be loaded directly from a CDN. The following example demonstrates the smallest possible working integration. + +Import the source from the CDN, using the latest version: + +```html + +``` +It is also possible to use a fixed version (example: 1.2.3): + +```html + +``` + +When using the CDN build, the SDK is available globally as `sw`: + +```html + +``` + +If the notification appears in the top-right corner of the Administration, the SDK is working correctly. + +Using the CDN is quick and convenient, making it suitable for prototyping, experimentation, or simple setups without a build pipeline. It is not recommended for production use. + +## Next steps + +Choose your extension type: + +- [App Installation Flow](./getting-started/installation-apps.md) +- [Plugin Installation Flow](./getting-started/installation-plugins.md) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md new file mode 100644 index 000000000..d4d300175 --- /dev/null +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -0,0 +1,152 @@ +--- +title: "App Installation Flow" +sidebar_position: 20 +--- + + +# App Installation Flow + +Using the Meteor Admin SDK in an app requires exposing an Administration page from the app server and registering it in the app manifest. + +This guide discusses two SDKs: + +- Meteor Admin SDK: UI layer **only** +- Optional App Server SDK = **backend** layer + +## App hosting requirement + +Each Shopware app must be hosted on its own domain. + +It is NOT possible to host multiple apps under the same domain using different subfolders. Instead, use subdomains for each app. + +Example: + +- `app-one.your-company.com` +- `app-two.your-company.com` + +Each app must expose its own publicly reachable URL for registration and webhook handling. + +## Backend requirement + +Apps require a backend that handles the registration handshake and request validation. + +Optional, but highly recommended for app development, is the [App Server SDK](https://github.com/shopware/app-sdk-js): a small TypeScript helper library that simplifies the registration handshake, signature verification, webhook handling, and communication with the Shopware API. + +The App Server SDK is suitable for both development and production environments [across runtimes](https://www.shopware.com/en/news/shopware-app-server-sdk-in-javascript/) such as Node.js, Deno, Bun, or Cloudflare Workers. + +To run a local dev server for an app, follow the SDK repo README for exact commands: + +```bash +# clone the App Server SDK (example) +git clone https://github.com/shopware/app-sdk-js +cd app-sdk-js + +# install dependencies and start the dev server +npm install +npm run dev # or `npm start` per the repo README + +# the dev server will expose a public URL (or you can tunnel it with ngrok) for registering the App's admin page +``` + +Visit [the App Server SDK guide](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/javascript/01-getting_started.html) for detailed instructions. + +### 1. Ensure the app server is running + +If the app provides an Administration UI, it must: + +- Handle the registration handshake +- Expose a publicly reachable URL +- Serve an HTML page for the Administration + +Using the [App Server SDK](https://github.com/shopware/app-sdk-js) is recommended, as it handles the registration handshake, signature verification, webhook handling, and request validation. But it is also possible to implement the registration and request validation manually, for advanced setups. + +### 2. Create the Administration HTML page + +Create an HTML file. This file must be accessible via URL, so ensure that it is served by the app server. + +CDN example: + +```html + + + + + + + + + + + +``` + +npm example: + +```html + + + + + + + + + +``` + +The SDK must be bundled using the build tool. See the [App development guide](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide). + +### 3. Register the Administration page in `manifest.xml` + +After the registration handshake is working, add the `` field inside the `` section of the [manifest file](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide#manifest-file). The `` field should contain the app's public URL. + +As required by Shopware's app system, the `` section must already contain the `registrationUrl` and `secret`. + +For an example, the `manifest.xml` of an app whose HTML page is served under `http://localhost/my-example-app.html` would look like this: + +```xml + + + + MyExampleApp + + + + + http://link-to-your-local-app-server/register + S3cr3tf0re$t + + + + + http://localhost/my-example-app.html + + +``` + +### 4. Install and activate the app + +- Upload or register the app +- Activate it in the Administration + +### 5. Verify installation + +Log in to the Shopware Administration. + +Open the module defined in the app's `` section. + +The notification should appear in the top-right corner. + +Installation complete. ✅ diff --git a/docs/admin-sdk/getting-started/installation-plugins.md b/docs/admin-sdk/getting-started/installation-plugins.md new file mode 100644 index 000000000..498ea013c --- /dev/null +++ b/docs/admin-sdk/getting-started/installation-plugins.md @@ -0,0 +1,114 @@ +--- +title: "Plugin Installation Flow" +sidebar_position: 30 +--- + + +# Plugin Installation Flow + +Plugins are supported on self-hosted Shopware instances only. + +## For Shopware 6.7+ + +Shopware 6.7 introduced a new Administration extension architecture (`meteor-app`) with modern frontend build tooling (Vite-based). Earlier versions use the legacy `administration` directory. Admin extensions are loaded as a hidden iframe, and there's clear separation between plugin backends and frontend apps. + +### 1. Create the administration entry + +Create the folder `custom/plugins/yourPlugin/src/Resources/app/meteor-app`. This is the base path for all new files for your extension. + +### 2. Initialize npm + +Initialize a new Node project with `npm init --yes`. + +### 3. Install the SDK + +Then install the SDK with `npm install @shopware-ag/meteor-admin-sdk`. + +### 4. Implement your entry file + +Create a new base `index.html` file, which will be automatically injected as a hidden iFrame to the Administration when the plugin is activated. + +Then create a JavaScript file in the subfolder `src/main.js` and reference it in the `index.html`: + +```html + + + + + + + Your extension + + +
+ + + +``` + +The SDK must be bundled as part of your plugin’s build process. See the [Plugin development guide](https://developer.shopware.com/docs/guides/plugins/plugins/plugin-base-guide.html). + +### 5. Rebuild the Administration + +This command starts the Administration watcher and rebuilds the frontend bundle: + +```bash +bin/watch-administration.sh +``` + +Wait until the compilation finishes successfully. + +### 6. Verify installation + +Log in to the Administration. The SDK should function correctly. + +Installation complete ✅ + +## For Shopware 6.6 and below + +These versions use the legacy `administration` directory, with an older Admin build process. Files are injected directly into the Administration bundle. + +### 1. Create the Administration entry + +Open the path `custom/plugins/yourPlugin/src/Resources/app/administration`. This is the base path for all new admin files. + +Create a new base `index.html` file. This file will be automatically injected to the Administration when the plugin is activated. + +Then create a JavaScript file in the subfolder `src/main.js`. This file will be automatically injected into the created HTML file. + +### 2. Initialize npm + +For plugins, the best way is to install the SDK via npm. First, initialize a new npm project in the plugin folder: + +```bash +npm init --yes +``` + +This should result in the following folder structure: + +```plaintext +custom/plugins/yourPlugin/src/Resources/app/administration +├── index.html +├── package.json +├── package-lock.json +├── src +│ ├── main.js +``` + +### 3. Install the SDK + +```bash +npm install @shopware-ag/meteor-admin-sdk +``` + +### 4. Rebuild the Administration + +```bash +bin/watch-administration.sh +``` + +### 5. Verify installation + +Log in to the Administration and confirm that your SDK code executes. + +Installation complete. ✅ diff --git a/docs/admin-sdk/getting-started/installation.md b/docs/admin-sdk/getting-started/installation.md deleted file mode 100644 index 5bee2811a..000000000 --- a/docs/admin-sdk/getting-started/installation.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: "Installation" -sidebar_position: 1 ---- - -# Installation - -## Prerequisites: - -You need to have an working [app](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide) or [plugin](https://developer.shopware.com/docs/guides/plugins/plugins/plugin-base-guide) installed on your Shopware 6 instance. - -## Prepare your app or plugin - -### App: - -You need to create a HTML page with an JS file for your app. This page needs to be served by your app-server as it needs to be accesible via URL. -For development purposes you can use [App server sdk](https://github.com/shopware/app-sdk-js). - -Once you got the registration/ handshake working you need to add the `` field to the `` section of the [manifest](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide#manifest-file) file. This field should contain the public URL of your app. Let's assume your app HTML page is served under `http://localhost/my-example-app.html`: - -```xml - - - - MyExampleApp - - - - - http://link-to-your-local-app-server/register - S3cr3tf0re$t - - - - - http://localhost/my-example-app.html - - -``` - -In your new HTML file you need inject a JS file. This file can use the Meteor Admin SDK via CDN or if you want to use a build tools then you -can use the NPM package. - -### Plugin: -**Notice:** Plugins will work on self-hosted instances only. You won't be able to use a Shopware 6 cloud instance with plugins. - -#### For Shopware 6.7 and higher: -Create the folder `custom/plugins/yourPlugin/src/Resources/app/meteor-app`. This is the base path for all new files -for your extension. - -Create a new base `index.html` file. This file will be automatically injected as a hidden iFrame to the administration -when the plugin is activated. Then you need to create a JavaScript file in the subfolder `src/main.js` and -add it to your `index.html`: - -```html - - - - - - - Your extension - - -
- - - -``` - -Then you initialize a new Node project with `npm init --yes` and install the SDK via NPM -with `npm i --save @shopware-ag/meteor-admin-sdk`. - -If you want to have a custom Vite configuration you can install Vite with `npm i --save vite` and -create a `vite.config.js` file in the `meteor-app` folder with your custom configuration. - -This should result in a folder structure like this: -```plaintext -custom/plugins/yourPlugin/src/Resources/app/meteor-app -├── index.html -├── vite.config.js (optional) -├── package.json -├── package-lock.json -├── src -│ ├── main.js -``` - -#### For Shopware 6.6 and lower: -Open the path `custom/plugins/yourPlugin/src/Resources/app/administration`. This is the base path for all new admin files. - -Create a new base `index.html` file. This file will be automatically injected to the administration when the plugin is -activated. Then you need to create a JavaScript file in the subfolder `src/main.js`. This file will be automatically -injected into the created HTML file. - -For plugins the best way is to install the SDK via NPM. But first you need to initialize a new NPM project in your plugin folder with -`npm init --yes`. - -This should result in a folder structure like this: -```plaintext -custom/plugins/yourPlugin/src/Resources/app/administration -├── index.html -├── package.json -├── package-lock.json -├── src -│ ├── main.js -``` - -## Installing the SDK: - -The preferred way of using the library is with a NPM package. This guarantees the smallest bundle size for your apps and plugins, since this way only necessary functions are bundled together. - -The CDN method is easy to use and fast to implement. It is best used for quick prototyping or if you don't want to work with building tools. - -### Using NPM (require bundling): -Install it to your `package.json` -``` -npm i --save @shopware-ag/meteor-admin-sdk -``` - -and import it into your app or plugin: -```js -// import everything as one big object -import * as sw from '@shopware-ag/meteor-admin-sdk'; - -// or import only needed functionality scope -import { notification } from '@shopware-ag/meteor-admin-sdk'; - -// or the direct method (here with an alias) -import { dispatch as dispatchNotification } from '@shopware-ag/meteor-admin-sdk/es/notification' - -``` - -### Using CDN: -Import the source from the CDN - -```js -// use the latest version available - - -// use a fix version (example here: 1.2.3) - -``` - -and access it with the global variable `sw`. - -```js -sw.notification.dispatch({ - title: 'My first notification', - message: 'This was really easy to do' -}) -``` - -## Adding types for Entities (TS only) - -The data management inside the SDK supports complete TypeScript support. This allows complete type safety when getting -entities, editing or saving them. - -For adding the types you need to create a global type definition file like `global.d.ts`. Inside this file you can -add the types for the entities by extending the global namespace. - -### Using auto-generated types from Shopware -This is the easiest solution. Just install the correct type definition for the matching shopware version: - -`npm install @shopware-ag/entity-schema-types@5.0.0` - -The version number should match the Shopware version number without the `6.` in the beginning. Examples: - -`Shopware 6.5.0.0` → `@shopware-ag/entity-schema-types@5.0.0` -`Shopware 6.5.1.2` → `@shopware-ag/entity-schema-types@5.1.2` -`Shopware 6.6.3.1` → `@shopware-ag/entity-schema-types@6.3.1` - -```ts -// global.d.ts -import '@shopware-ag/entity-schema-types'; -``` - -### Using "any" fallback - -This is the easiest solution. You set the type to `any` for every entity. The downside of this is the missing type safety. - -```ts -// global.d.ts -declare namespace EntitySchema { - interface Entities { - [entityName: string]: any; - } -} -``` - -### Using custom types - -This is the safest solution. You define for every needed entity every property and association. The downside of this is -that it takes time to write the definitions. - -```ts -// global.d.ts -declare namespace EntitySchema { - interface Entities { - // using product_manufacturer as an example - product_manufacturer: product_manufacturer; - // in this case 'media', 'product' and 'product_manufacturer_translation' is also needed - ... - } - - interface product_manufacturer { - id: string; - versionId: string; - mediaId?: string; - link?: string; - name: string; - description?: string; - customFields?: unknown; - /* - * Entity and EntityCollection is defined in the namespace and can directly be used. - * The value in the generic (here 'media', 'product' and 'product_manufacturer_translation') need - * also to be defined in this file. - */ - media?: Entity<'media'>; - products?: EntityCollection<'product'>; - translations: EntityCollection<'product_manufacturer_translation'>; - createdAt: string; - updatedAt?: string; - translated?: {name?: string, description?: string, customFields?: unknown}; - } - - // 'media', 'product' and 'product_manufacturer_translation' also needs to be added - ... -} -``` \ No newline at end of file diff --git a/docs/admin-sdk/getting-started/usage.md b/docs/admin-sdk/getting-started/usage.md index 09db0849c..588e606ac 100644 --- a/docs/admin-sdk/getting-started/usage.md +++ b/docs/admin-sdk/getting-started/usage.md @@ -1,119 +1,37 @@ --- -sidebar_position: 3 +title: "Usage" +sidebar_position: 40 --- # Usage -After [installing](./installation) the Meteor Admin SDK successfully you can use it in your apps and plugins. +After installing the Meteor Admin SDK, you can use it in your extensions. Most extensions should use the NPM package with a bundler such as Vite. This provides proper dependency management, type support, and better integration with modern development workflows. -## Adding functionality to new apps or plugins -You can use the SDK features directly in your JS file. Just import the specific feature (NPM method) or use the method in the -`sw` object (CDN method). You can find all features in the API reference documentation. +Alternatively, you can load the SDK via a CDN, which exposes the SDK through the global `sw` object. This approach is mainly useful for simple setups or quick experiments. + +## Using the SDK with NPM (recommended) + +Import the SDK features you need directly into your JavaScript file. -### NPM example: ```js // import notification toolkit from the SDK -import { notification } from '@shopware-ag/meteor-admin-sdk'; +import { notification } from '@shopware-ag/meteor-admin-sdk'; // dispatch a new notification notification.dispatch({ title: 'My first notification', message: 'This was really easy to do' -}) +}); ``` -### CDN example: +## Using the SDK via CDN + +If you load the SDK from a CDN, its APIs are available on the global `sw` object. + ```js // access the "notification" toolkit in the global "sw" object and dispatch a new notification sw.notification.dispatch({ title: 'My first notification', message: 'This was really easy to do' -}) -``` - - -## Adding functionality to existing plugins -Shopware 6 has a rich plugin extension system for the Admin based on Twig and the concepts of component overriding and component extending. These -concepts are very powerful, but may also come with a steep learning curve. That's why you can migrate gradually to the new Meteor Admin SDK, if you want. -Both approaches can work together. This way you can start by converting only parts of your plugins at first and then gradually converting more and more of your plugins as new features are added to the SDK. -This approach is also going to help with simplifying your plugins and preparing them for long term usage. - -#### Example: - -```js -// Use existing extension capabilties -Shopware.Component.override('sw-dashboard-index', { - methods: { - async createdComponent() { - // Can also use Meteor Admin SDK features - await sw.notification.dispatch({ - title: 'Hello from the plugin', - message: 'I am combining the existing approach with the new SDK approach', - }) - - this.$super('createdComponent'); - } - } }); ``` - -### Using locations with normal Vue components without iFrame rendering - -**This feature is not yet released in Shopware. -It's only available with the development enviroment or `dev-trunk` version of Shopware.** - -It is useful when you want to migrate partially from the twig plugin system to the SDK extension system that you use both systems together. To make this happen you can render normal Vue components in the Shopware administration for the locations instead of your iFrame view. - -To do this you need to register the component in the existing plugin system: - -```js -Shopware.Component.register('your-component-name', { - // your component -}) -``` - -Now if you want to render the component in a location you need to add the name of the component to the current location. This can be done with the `sdkLocation` store: -```js -Shopware.State.commit('sdkLocation/addLocation', { - locationId: 'your-location-id', - componentName: 'your-component-name' -}) -``` - -With this feature you can create mix the usage of the SDK and the existing plugin system. A complete example could be looking like this. It creates a new tab item in the product detail page, renders a card with the componentSection renderer and inside the card it renders the location. But instead of the traditional location it renders a Vue component which was registered in the Shopware Component Factory. - -```js -// in a normal plugin js file without a HTML file -import { ui, location } from '@shopware-ag/meteor-admin-sdk'; - -if (!location.isIframe()) { - const myLocationId = 'my-example-location-id'; - - // Create a new tab entry - ui.tabs('sw-product-detail').addTabItem({ - label: 'Example tab', - componentSectionId: 'example-product-detail-tab-content' - }) - - // Add a new card to the tab content which renders a location - ui.componentSection.add({ - component: 'card', - positionId: 'example-product-detail-tab-content', - props: { - title: 'Component section example', - locationId: myLocationId - } - }) - - // Register your component which should be rendered inside the location - Shopware.Component.register('your-component-name', { - // your component - }) - - // Add the component name to the specific location - Shopware.State.commit('sdkLocation/addLocation', { - locationId: myLocationId, - componentName: 'your-component-name' - }) -} -``` diff --git a/docs/admin-sdk/index.md b/docs/admin-sdk/index.md index e2b4b06f1..18696264f 100644 --- a/docs/admin-sdk/index.md +++ b/docs/admin-sdk/index.md @@ -9,83 +9,39 @@ custom_edit_url: null # Introduction -The Meteor Admin SDK is an NPM library for Shopware 6 apps and plugins that need an easy way of extending or customizing the Administration. +The Meteor Admin SDK is an npm library for building Shopware Administration UI extensions. It enables [apps](https://developer.shopware.com/docs/guides/plugins/apps/) and [plugins](https://developer.shopware.com/docs/guides/plugins/plugins/) to extend the Shopware Administration through a stable, typed API that runs in the browser context. -It contains helper functions to communicate with the Administration, execute actions, subscribe to data or extend the user interface. +What you can build: -- 🏗 **Works with Shopware 6 Apps and Plugins:** you can use the SDK for your plugins or apps. API usage is identical. -- 🎢 **Shallow learning curve:** you don't need to have extensive knowledge about the internals of the Shopware 6 Administration. Our SDK hides the complicated stuff behind a beautiful API. -- 🧰 **Many extension capabilities:** from throwing notifications, accessing context information or extending the current UI. The feature set of the SDK will gradually be extended, providing more possibilities and flexibility for your ideas and solutions. -- 🪨 **A stable API with great backwards compatibility:** don't fear Shopware updates anymore. Breaking changes in this SDK are an exception. If you use the SDK, your apps and plugins will stay stable for a longer time, without any need for code maintenance. -- 🧭 **Type safety:** the whole SDK is written in TypeScript which provides great autocompletion support and more safety for your apps and plugins. -- 💙 **Developer experience:** have a great development experience right from the start. And it will become better and better in the future. -- 🪶 **Lightweight:** the whole library is completely tree-shakable and dependency-free. Every functionality can be imported granularly to keep your bundle as small and fast as possible. +- Custom Administration modules +- Context-aware UI extensions +- Entity-driven workflows inside the Administration +- Notification and interaction systems +- Admin-driven integrations with external services +- Dynamic UI behavior based on Shopware state -Go to [Installation](./getting-started/installation.md) to get started. Or check out the quick start guide: +What you can do: -## Quick start +- Dispatch notifications +- Access context information +- Extend the Administration UI +- Interact with entities -Understand the Shopware Extension SDK by learning how to throw a notification. +## Why use the SDK -Requirements for this quick start guide are: -- [Shopware 6 self-hosted instance](https://developer.shopware.com/docs/guides/installation) or a [Shopware 6 cloud instance](https://www.shopware.com/en/shopware-cloud/) -- [clean Shopware 6 Plugin or App](https://developer.shopware.com/docs/guides/plugins/overview) which is activated +- Provides a stable, backwards-compatible API for extending the Administration and reducing complexity during Shopware updates +- Abstracts internal complexity, so deep knowledge of the Admin internals is not required +- Written in [TypeScript](https://www.typescriptlang.org/) with full type safety and auto-completion support +- Lightweight and tree-shakable with no external dependencies, allowing granular imports and small bundle sizes -### App -1. Create an HTML file with following content: -```html - - - - - - - +## Prerequisites - - - -``` +Using the Meteor Admin SDK requires: -2. Add the link to the webpage and to the [manifest.xml](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide#manifest-file) of your app. For local files you can use [ngrok](https://ngrok.com/) to create a public URL for your HTML file. +- A Shopware instance +- A working [app](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide) or [plugin](https://developer.shopware.com/docs/guides/plugins/plugins/plugin-base-guide) installed in Shopware 6 +- The SDK installed via npm (recommended) or CDN -3. Visit the Administration. After you have logged in you should see the notification from your app. +## Next steps -Congratulation 🎉 You just created your first interaction with the Administration via the Meteor Admin SDK. - -### Plugin -**Notice:** Plugins will only be working on self-hosted instances. You can't use a Shopware 6 cloud instance for plugins. - -1. Create a new `index.html` file to your new plugin in the following path: `custom/plugins/yourPlugin/src/Resources/app/administration/index.html`. The HTML file should have the following content: -```html - - - - - - - - - - - -``` - -2. Start the Shopware 6 Administration watcher using the following command: -```bash -$ bin/watch-administration.sh -``` - -After all files have been compiled, a new browser window should open, in which you should see the Administration. After logging in, you should see the notification from your plugin. - -Congratulations 🎉 You just created your first interaction with the Administration via the Meteor Admin SDK. +Go here to install the SDK and choose your installation path: npm and Vite (recommended for production) or CDN (for quick prototyping). diff --git a/docs/admin-sdk/internals/index.md b/docs/admin-sdk/internals/index.md deleted file mode 100644 index 6e5beed3e..000000000 --- a/docs/admin-sdk/internals/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Internals" -nav: - position: 1000 ---- \ No newline at end of file diff --git a/docs/admin-sdk/tooling/index.md b/docs/admin-sdk/tooling/index.md deleted file mode 100644 index 3a4905d48..000000000 --- a/docs/admin-sdk/tooling/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Tooling" -nav: - position: 75 ---- \ No newline at end of file diff --git a/docs/admin-sdk/tooling/vue-devtools.md b/docs/admin-sdk/tooling/vue-devtools.md deleted file mode 100644 index d73127c2a..000000000 --- a/docs/admin-sdk/tooling/vue-devtools.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Vue Devtools" -sidebar_position: 1 ---- - -# Vue Devtools -The administration has many extension capabilties. Many of them are components with an unique positionId. It can be -difficult to find out their id to extend them. You need to manually look in the core source code to find out the id. - -The better way is using the Vue devtools plugin. It is preinstalled in every Shopware administration so that you can -find out the ids in an interactive and visual way. - -## Prerequisites: -You need to have the Vue Devtools installed. The plugin API for the Vue Devtools is only available in the versions 6+ (Currently only in the [beta channel](https://chrome.google.com/webstore/detail/vuejs-devtools/ljjemllljcmogpfapbkkighbhhppjdbg). You can install both parallel.). If you are using an older version then this plugin will not work. - -After installing the browser extensions you should be able to open the devtools in the development/watch mode of the administration. To check if the admin plugin works you can go to the settings and check if the Shopware Admin plugin is installed and enabled: - -![Vue Devtools plugin settings](./assets/devtools-plugin-settings.png) - -![Vue Devtools plugin settings list](./assets/devtools-plugin-settings-list.png) - -## Finding extension capabilites -Navigate to the page which you want to extend. In our example we go to the product detail page in the tab specifications. - -Now you can open the plugin in the top dropdown menu: - -![Vue Devtools plugin tab Shopware extension](./assets/devtools-plugin-tab-shopware-extension.png) - -You should see a list on the left side where all extension capabilities are listed. If you click on any of them you will directly see them highlighted in the administration. - -![Vue Devtools plugin extension point selection](./assets/devtools-plugin-extension-point-selection.png) - -In the inspector of the devtools you will see more information about the extension point. You can see the `Property` value which you can look in the API Reference documentation. Then you know how to use your selected extension point and which capabilities are available. And in most cases you need the `positionId` which is also shown in the inspector. The positionId is a unique identifer so that you extend not every area but only your selected one. - diff --git a/examples/admin-sdk-plugin/README.md b/examples/admin-sdk-plugin/README.md index 8c01956ad..79f241275 100644 --- a/examples/admin-sdk-plugin/README.md +++ b/examples/admin-sdk-plugin/README.md @@ -3,6 +3,7 @@ This package contains an example plugin. It uses the [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/admin-sdk) to extend the administration. ## Prerequisites + We assume that you have a functioning Shopware 6 setup on your local machine. ## Plugin setup @@ -21,5 +22,3 @@ Now you should see the plugin installed when opening the Shopware Admin and look 1. Create a `.env` file in `/examples/admin-sdk-plugin/tests/acceptance` 2. Specify your Shopware instance app url: `APP_URL=https://dev.local/` 3. Run the tests: `cd && pnpm --filter @shopware-ag/meteor-admin-sdk-example-plugin run test:ats` - - From 30b83ef2f279da5d08263edb91437e23158e3172 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 18:45:53 +0100 Subject: [PATCH 02/59] Update get.md --- docs/admin-sdk/api-reference/data/get.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/admin-sdk/api-reference/data/get.md b/docs/admin-sdk/api-reference/data/get.md index 09a659e83..de7ede809 100644 --- a/docs/admin-sdk/api-reference/data/get.md +++ b/docs/admin-sdk/api-reference/data/get.md @@ -6,10 +6,12 @@ nav: # Get -With `data.get` you can receive datasets from the Shopware Administration. More information on how to find the unique identifiers can be found in [the data-handling guide](../../concepts/datahandling.md). +With `data.get` you can receive datasets from the Shopware Administration. Compared to `data.subscribe`, `data.get` only gives you the current state of the data. If the data is not available yet, such as when opening a page, you won't receive any data. In these cases, it's better to subscribe to data changes instead. +More information on how to find the unique identifiers can be found in the [data-handling guide](../../concepts/datahandling.md). + ## Usage ```ts @@ -36,4 +38,4 @@ data.get({ | Name | Required | Description | | :-------- | :------- |:---------------------------------------------------------------------------------------------------------------------| -| `options` | true | Containing the unique `id` and optional `selectors`. Read more about selectors [here](../../concepts/selectors.md) | +| `options` | true | Containing the unique `id` and optional `selectors`. Read more about selectors [here](../../concepts/selectors.md). | From 0488e2ff460ade185c01a146e8fdfbd1fc1640a2 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 18:48:44 +0100 Subject: [PATCH 03/59] Update index.md --- docs/admin-sdk/api-reference/data/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-sdk/api-reference/data/index.md b/docs/admin-sdk/api-reference/data/index.md index c9c30ab68..fffc09846 100644 --- a/docs/admin-sdk/api-reference/data/index.md +++ b/docs/admin-sdk/api-reference/data/index.md @@ -7,7 +7,7 @@ nav: # Working with Data -The Meteor Admin SDK provides APIs for accessing and manipulating Shopware data from within the Administration. These APIs allow extensions to interact with Shopware entities, react to changes in data, and update records using the same repository-based data layer used by the Administration itself. +The Meteor Admin SDK provides tools for accessing and manipulating Shopware data from within the Administration. These APIs allow extensions to interact with Shopware entities, react to changes in data, and update records using the same repository-based data layer used by the Administration itself. Typical data workflows follow this pattern: @@ -16,7 +16,7 @@ Typical data workflows follow this pattern: 3. Subscribe to updates or changes 4. Modify or persist data -## Available APIs +## Data access and operations - [Repository](./repository.md): Access Shopware entity repositories. - [Get](./get.md): Retrieve entity data from the Administration data layer. From 0fa41007570527be53f9362debe0ed8a1fc5cb30 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 18:49:17 +0100 Subject: [PATCH 04/59] Update index.md --- docs/admin-sdk/api-reference/data/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/api-reference/data/index.md b/docs/admin-sdk/api-reference/data/index.md index fffc09846..edea9d418 100644 --- a/docs/admin-sdk/api-reference/data/index.md +++ b/docs/admin-sdk/api-reference/data/index.md @@ -22,4 +22,4 @@ Typical data workflows follow this pattern: - [Get](./get.md): Retrieve entity data from the Administration data layer. - [Subscribe](./subscribe.md): React to changes in entity data. - [Update](./update.md): Modify and persist entity data. -- [In-App Purchases](./in-app-purchases.md): APIs for working with Shopware in-app purchase functionality. +- [In-App Purchases](./in-app-purchases.md): Work with Shopware in-app purchase functionality. From dfe4defb3b187f9432ac17b445605f8b9f46c60c Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:19:32 +0100 Subject: [PATCH 05/59] Update index.md --- docs/admin-sdk/api-reference/ui/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-sdk/api-reference/ui/index.md b/docs/admin-sdk/api-reference/ui/index.md index 72e3ae3f4..b6d06b6be 100644 --- a/docs/admin-sdk/api-reference/ui/index.md +++ b/docs/admin-sdk/api-reference/ui/index.md @@ -21,9 +21,9 @@ Shopware Administration components are not native Vue components. They rely on i The [Meteor Component Library](https://github.com/shopware/meteor-component-library) provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. -## Typical development flow +## Typical UI extension workflow -A typical extension often follows this progression. +A typical UI extension workflow often follows this progression. 1. Create a new module: Use a [Main Module](./mainModule.md) when your extension needs a dedicated application area in the Administration. From 9a2abdca0a4155ddecc50f3f5a366b11a948cfc4 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:21:12 +0100 Subject: [PATCH 06/59] Update index.md --- docs/admin-sdk/api-reference/ui/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/api-reference/ui/index.md b/docs/admin-sdk/api-reference/ui/index.md index b6d06b6be..9de48e87d 100644 --- a/docs/admin-sdk/api-reference/ui/index.md +++ b/docs/admin-sdk/api-reference/ui/index.md @@ -19,7 +19,7 @@ Shopware Administration components cannot be used directly inside apps or plugin Shopware Administration components are not native Vue components. They rely on internal extension capabilities, Twig templates, and framework integrations that are not available externally. -The [Meteor Component Library](https://github.com/shopware/meteor-component-library) provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. +The [Meteor Component Library](https://github.com/shopware/meteor/tree/main/packages/component-library) provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. ## Typical UI extension workflow From f7b5704628dc9ba48abe51e4011390bb687bdd9a Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:43:08 +0100 Subject: [PATCH 07/59] Update settingsItem.md --- docs/admin-sdk/api-reference/ui/settingsItem.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/admin-sdk/api-reference/ui/settingsItem.md b/docs/admin-sdk/api-reference/ui/settingsItem.md index 7835a321a..91849bd3f 100644 --- a/docs/admin-sdk/api-reference/ui/settingsItem.md +++ b/docs/admin-sdk/api-reference/ui/settingsItem.md @@ -41,8 +41,7 @@ ui.settings.addSettingsItem({ ## Getting the right icon -Assuming that your editor supports TypeScript, you should get auto-completion for valid `icon` values. -In case that doesn't work take a look at the list [here](https://github.com/shopware/meteor-admin-sdk/blob/trunk/src/icons.ts). +If your editor supports TypeScript, you should get auto-completion when importing icons from the Meteor icon package. To browse available icons, see the [Meteor icon kit repository](https://github.com/shopware/meteor/tree/main/packages/icon-kit). ### Example From f0e9e2f543a9446975cdeefde854952486044e67 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:45:12 +0100 Subject: [PATCH 08/59] Update sidebars.md --- docs/admin-sdk/api-reference/ui/sidebars.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/api-reference/ui/sidebars.md b/docs/admin-sdk/api-reference/ui/sidebars.md index 34aa2eac3..32c171bbd 100644 --- a/docs/admin-sdk/api-reference/ui/sidebars.md +++ b/docs/admin-sdk/api-reference/ui/sidebars.md @@ -34,7 +34,7 @@ sw.ui.sidebar.add({ ### Example -![Menu item example](../assets/sidebar-example.png) +![Menu item example](./assets/sidebar-example.png) ## Close a sidebar From 82e1611ec055e4781d520d30fe8792b1a5d9d690 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:48:48 +0100 Subject: [PATCH 09/59] Update index.md --- docs/admin-sdk/api-reference/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index c3a826e81..accbee56a 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -39,7 +39,7 @@ APIs in this section include: ## Working with Data -These APIs allow extensions to access and manipulate Shopware entity data from within the Administration. +These tools allow extensions to access and manipulate Shopware entity data from within the Administration. They follow the same repository-based data access pattern used internally by the Administration. @@ -50,7 +50,7 @@ Typical workflows include: - Subscribing to changes - Updating or persisting entities -APIs in this section include: +Tools this section include: - [Repository](./data/repository.md) - [Get](./data/get.md) From 44dd652402b4d629bcb37e3551292dce36c5fd3a Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:50:14 +0100 Subject: [PATCH 10/59] Update index.md --- docs/admin-sdk/api-reference/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index accbee56a..8b91c754d 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -14,8 +14,7 @@ Use the sections below to navigate the available APIs. ## Extending the Administration UI -These APIs allow extensions to add UI elements to the Shopware Administration. -They can be used to register modules, add navigation entries, extend existing pages, and display dialogs or side panels. +These UI extension components allow extensions to add UI elements to the Shopware Administration. They can be used to register modules, add navigation entries, extend existing pages, and display dialogs or side panels. Typical use cases include: @@ -24,7 +23,7 @@ Typical use cases include: - Adding navigation or settings entries - Displaying modals or contextual UI elements -APIs in this section include: +UI extension components in this section include: - [Main Module](./ui/mainModule.md) - [Menu](./ui/menu.md) From ded179b9cd5d3d56cfb4acb91ec453d94e28b7ae Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:54:49 +0100 Subject: [PATCH 11/59] Update index.md --- docs/admin-sdk/develop/cms/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/cms/index.md b/docs/admin-sdk/develop/cms/index.md index 29406b7dd..67e9cf69a 100644 --- a/docs/admin-sdk/develop/cms/index.md +++ b/docs/admin-sdk/develop/cms/index.md @@ -7,4 +7,9 @@ nav: # Extending the CMS -These APIs allow extensions to register new CMS blocks and CMS elements for use in the Shopware Shopping Experiences editor. +These CMS extension features allow extensions to register new CMS blocks and CMS elements for use in the Shopware Shopping Experiences editor. + +Features in this section include: + +- [Register CMS Block](./registerCmsBlock.md): Add custom CMS blocks that define layout structures in the Shopping Experiences editor. +- [Register CMS Element](./registerCmsElement.md): Create custom CMS elements that render content or functionality inside CMS blocks. From 2b6c948aaa75d48fc54e2874d11afd3360a3f6f3 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:55:21 +0100 Subject: [PATCH 12/59] Update registerCmsBlock.md --- docs/admin-sdk/develop/cms/registerCmsBlock.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/cms/registerCmsBlock.md b/docs/admin-sdk/develop/cms/registerCmsBlock.md index 99249dd2b..98beaf426 100644 --- a/docs/admin-sdk/develop/cms/registerCmsBlock.md +++ b/docs/admin-sdk/develop/cms/registerCmsBlock.md @@ -1,6 +1,6 @@ --- title: "Register CMS block" -sidebar_position: 2 +sidebar_position: 10 --- From 3bd481e90ca881b4d80e630d2f2af60045ce9e46 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:55:34 +0100 Subject: [PATCH 13/59] Update index.md --- docs/admin-sdk/develop/cms/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/cms/index.md b/docs/admin-sdk/develop/cms/index.md index 67e9cf69a..f5e8d1dbc 100644 --- a/docs/admin-sdk/develop/cms/index.md +++ b/docs/admin-sdk/develop/cms/index.md @@ -1,7 +1,7 @@ --- title: "Extending the CMS" nav: - position: 300 + position: 10 --- From ab2cc5f637c18e0f1a01925bf5b1df1f4e631ad8 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:55:43 +0100 Subject: [PATCH 14/59] Update registerCmsBlock.md --- docs/admin-sdk/develop/cms/registerCmsBlock.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/cms/registerCmsBlock.md b/docs/admin-sdk/develop/cms/registerCmsBlock.md index 98beaf426..48449029d 100644 --- a/docs/admin-sdk/develop/cms/registerCmsBlock.md +++ b/docs/admin-sdk/develop/cms/registerCmsBlock.md @@ -1,6 +1,6 @@ --- title: "Register CMS block" -sidebar_position: 10 +sidebar_position: 20 --- From bf68f2aebff35838438046b518745f3606167882 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:55:52 +0100 Subject: [PATCH 15/59] Update registerCmsElement.md --- docs/admin-sdk/develop/cms/registerCmsElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/cms/registerCmsElement.md b/docs/admin-sdk/develop/cms/registerCmsElement.md index 88d4119dc..90060b85e 100644 --- a/docs/admin-sdk/develop/cms/registerCmsElement.md +++ b/docs/admin-sdk/develop/cms/registerCmsElement.md @@ -1,6 +1,6 @@ --- title: "Register CMS Element" -sidebar_position: 3 +sidebar_position: 30 --- From 650cc4da7a902e4b9d7c23236fe5e0cade5073ee Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 19:56:50 +0100 Subject: [PATCH 16/59] Update registerCmsBlock.md --- docs/admin-sdk/develop/cms/registerCmsBlock.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/cms/registerCmsBlock.md b/docs/admin-sdk/develop/cms/registerCmsBlock.md index 48449029d..870680a31 100644 --- a/docs/admin-sdk/develop/cms/registerCmsBlock.md +++ b/docs/admin-sdk/develop/cms/registerCmsBlock.md @@ -47,7 +47,7 @@ cms.registerCmsBlock({ The CMS block will render automatically in the Storefront without any additional work. It renders the block as a CSS grid with the slots as grid items and the grid shorthand syntax you provided in the `slotLayout` property. -If you want you can override the default layout by creating a new template file in your app. The file should be named `cms-block-app-renderer.html.twig` and should be placed in the `/Resources/views/storefront/block` directory of your app folder. More details on how to customize the Storefront in your App can be found in this documentation: https://developer.shopware.com/docs/guides/plugins/apps/storefront/customize-templates.html +If you want you can override the default layout by creating a new template file in your app. The file should be named `cms-block-app-renderer.html.twig` and should be placed in the `/Resources/views/storefront/block` directory of your app folder. More details on how to customize the Storefront in your App can be found in the [Customize Templates](https://developer.shopware.com/docs/guides/plugins/apps/storefront/customize-templates.html) guide. Inside this file you need to define the block layout and the slots. The block which needs to be created follows this naming pattern: `block_app_renderer_${yourBlockName}`. The `${yourBlockName}` is the name of the block you registered with `cms.registerCmsBlock` except that you need to replace the hyphens with underscores. From 61b679ad5e8972c09709b2a00daf9a9acd721160 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 20:00:19 +0100 Subject: [PATCH 17/59] Update context.md --- docs/admin-sdk/develop/context.md | 117 +++++++++++++++++++++--------- 1 file changed, 81 insertions(+), 36 deletions(-) diff --git a/docs/admin-sdk/develop/context.md b/docs/admin-sdk/develop/context.md index 4de52de40..f6b7d36ed 100644 --- a/docs/admin-sdk/develop/context.md +++ b/docs/admin-sdk/develop/context.md @@ -10,15 +10,18 @@ sidebar_position: 40 ### Get current language -#### Usage: +#### Usage + ```ts const language = await sw.context.getLanguage(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<{ languageId: string, @@ -26,7 +29,8 @@ Promise<{ }> ``` -#### Example value: +#### Example value + ```ts { languageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b', @@ -36,7 +40,8 @@ Promise<{ ### Subscribe on language changes -#### Usage: +#### Usage + ```ts sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { // do something with the callback data @@ -44,11 +49,13 @@ sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { ``` #### Parameters + | Name | Description | | :------ | :------ | | `callbackMethod` | Called every-time the language changes | -#### Callback value: +#### Callback value + ```ts { languageId: string, @@ -56,7 +63,8 @@ sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { } ``` -#### Example callback value: +#### Example callback value + ```ts { languageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b', @@ -74,14 +82,17 @@ const environment = await sw.context.getEnvironment(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<'development' | 'production' | 'testing'> ``` -#### Example value: +#### Example value + ```ts 'development' ``` @@ -90,15 +101,18 @@ Promise<'development' | 'production' | 'testing'> ### Get current locale -#### Usage: +#### Usage + ```ts const locale = await sw.context.getLocale(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<{ locale: string, @@ -106,7 +120,8 @@ Promise<{ }> ``` -#### Example value: +#### Example value + ```ts { locale: 'de-DE', @@ -116,7 +131,8 @@ Promise<{ ### Subscribe on locale changes -#### Usage: +#### Usage + ```ts sw.context.subscribeLocale(({ locale, fallbackLocale }) => { // do something with the callback data @@ -124,11 +140,13 @@ sw.context.subscribeLocale(({ locale, fallbackLocale }) => { ``` #### Parameters + | Name | Description | | :------ | :------ | | `callbackMethod` | Called every-time the locale changes | -#### Callback value: +#### Callback value + ```ts { locale: string, @@ -136,7 +154,8 @@ sw.context.subscribeLocale(({ locale, fallbackLocale }) => { } ``` -#### Example callback value: +#### Example callback value + ```ts { locale: 'de-DE', @@ -148,15 +167,18 @@ sw.context.subscribeLocale(({ locale, fallbackLocale }) => { ### Get current currency -#### Usage: +#### Usage + ```ts const currency = await sw.context.getCurrency(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<{ systemCurrencyId: string, @@ -164,7 +186,8 @@ Promise<{ }> ``` -#### Example value: +#### Example value + ```ts { systemCurrencyId: 'b7d2554b0ce847cd82f3ac9bd1c0dfca', @@ -176,20 +199,24 @@ Promise<{ ### Get current Shopware version -#### Usage: +#### Usage + ```ts const shopwareVersion = await sw.context.getShopwareVersion(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts string ``` -#### Example value: +#### Example value + ```ts '6.4.0.0' ``` @@ -200,12 +227,14 @@ In many cases you have to make sure that the shop you are communicating with has The function always treats the current Shopware version of a shop as the left hand operator of the comparison. That means a call like `context.compareIsShopwareVersion('>=', '7.0.0')` can be read as "*Compare: is Shopware version equal or greater than 7.0.0*" -#### Usage: +#### Usage + ```ts const isRightVersion = await sw.context.compareShopwareVersion('>=', '7.0.0') ``` #### Parameters + | Name | Description | |:-------------|:------------------------------------------------------------------------------------------------------------------| | `comparator` | The operator to compare. Possible values: `'='` `'!='` `'>'` `'<'` `'<='` `'>='`| @@ -220,13 +249,13 @@ await sw.context.compareShopwareVersion('>=', '6.6.4.0'); await sw.context.compareShopwareVersion('>=', '6.4.0'); ``` -#### Return value: +#### Return value ```ts boolean ``` -#### Example value: +#### Example value ```ts true ``` @@ -237,20 +266,24 @@ true > The privileges property will be available with Shopware v6.7.1.0 and higher -#### Usage: +#### Usage + ```ts const { name, version, type, privileges } = await sw.context.getAppInformation(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<{ name: string ; version: string ; type: 'app' | 'plugin', privileges: privileges }> ``` -#### Example value: +#### Example value + ```ts { name: 'my-extension', @@ -272,15 +305,18 @@ Promise<{ name: string ; version: string ; type: 'app' | 'plugin', privileges: p Do not use this feature yet. It is not implemented in a Shopware release yet. ::: -#### Usage: +#### Usage + ```ts const userInformation = await sw.context.getUserInformation(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<{ aclRoles: Array<{ @@ -303,7 +339,8 @@ Promise<{ }> ``` -#### Example value: +#### Example value + ```ts { "aclRoles": [], @@ -331,15 +368,18 @@ This feature will be available with Shopware ^6.6.2.0 This feature allows you to get the timezone of the user. -#### Usage: +#### Usage + ```ts const userTimezone = await sw.context.getUserTimezone(); ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise ``` @@ -349,11 +389,13 @@ This function returns a Promise that resolves to a string representing the user' ## Module information ### Get module information + Get information about all registered modules. These modules are created by adding new menu items, setting items, etc. The ID can be used to change the current route to the module. -#### Usage: +#### Usage + ```ts const { modules } = await sw.context.getModuleInformation(); @@ -366,9 +408,11 @@ sw.window.routerPush({ ``` #### Parameters + No parameters needed. -#### Return value: +#### Return value + ```ts Promise<{ modules: Array<{ @@ -380,7 +424,8 @@ Promise<{ }> ``` -#### Example value: +#### Example value + ```ts { modules: [ @@ -412,7 +457,7 @@ const shopId = await sw.context.getShopId(); no parameters needed -#### Return value: +#### Return value ```ts Promise @@ -437,4 +482,4 @@ No parameters needed. ```ts boolean -``` \ No newline at end of file +``` From 54282bba5a19f0c10301bc43eb1f5ae38615f0f4 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 20:10:22 +0100 Subject: [PATCH 18/59] Update index.md --- docs/admin-sdk/develop/index.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/admin-sdk/develop/index.md b/docs/admin-sdk/develop/index.md index 49921158e..b012cb00a 100644 --- a/docs/admin-sdk/develop/index.md +++ b/docs/admin-sdk/develop/index.md @@ -11,12 +11,12 @@ This section explains how to build Administration extensions with the Meteor Adm A typical Administration extension follows this workflow: 1. Identify an extension point in the Administration UI. -2. Add a [main module](../api-reference/ui/mainModule) or [action button](../api-reference/ui/actionButton) at that [location](./api/location). +2. Add a [main module](../api-reference/ui/mainModule.md) or [action button](../api-reference/ui/actionButton.md) at that [location](./api/location.md). - **Location**: Defines where extension code runs inside the Administration UI. - **Main module**: The entry point of your extension inside the Administration navigation. - **Action button**: Adds functionality to an existing Administration view, such as the product detail page. -3. Load or modify Shopware data using [repositories](./composables/use-repository). -4. Provide feedback to users with [notifications](./notification) or [toasts](./toast). +3. Load or modify Shopware data using [repositories](./composables/use-repository.md). +4. Provide feedback to users with [notifications](./notification.md) or [toasts](./toast.md). ## Development Tools @@ -26,28 +26,28 @@ Use the [DevTools](./devtools.md) guide to discover extension points and inspect The following APIs allow extensions to interact with and extend the Shopware Administration UI: -- **[Location](./location)**: Determine where your extension is rendered inside the Administration. -- **[Context](./context)**: Access information about the current Administration context. -- **[Notification](./notification)**: Display notification messages to users. -- **[Toast](./toast)**: Show temporary toast messages. -- **[Window](./window)**: Interact with browser windows or external links. -- **[Translations](./translations)**: Localize extension UI using snippet files and synchronize language changes with the Administration. +- **[Location](./location.md)**: Determine where your extension is rendered inside the Administration. +- **[Context](./context.md)**: Access information about the current Administration context. +- **[Notification](./notification.md)**: Display notification messages to users. +- **[Toast](./toast.md)**: Show temporary toast messages. +- **[Window](./window.md)**: Interact with browser windows or external links. +- **[Translations](./translations.md)**: Localize extension UI using snippet files and synchronize language changes with the Administration. ## Composables Composables provide reusable helpers for working with Administration data and shared state. -- **[useRepository](./composables/use-repository)**: Access Shopware repositories to load and manipulate entities. -- **[useSharedState](./composables/use-shared-state)**: Share state between extensions or components. +- **[useRepository](./composables/use-repository.md)**: Access Shopware repositories to load and manipulate entities. +- **[useSharedState](./composables/use-shared-state.md)**: Share state between extensions or components. ## CMS extensions The CMS API allows extensions to add new CMS blocks and elements to the Shopware content system. -- **[Register CMS Block](./cms/register-cms-block)**: Add custom CMS blocks that structure and group content elements in the Shopping Experiences editor. -- **[Register CMS Element](./cms/register-cms-element)**: Create custom CMS elements that render specific content or functionality inside CMS blocks. +- **[Register CMS Block](./cms/register-cms-block.md)**: Add custom CMS blocks that structure and group content elements in the Shopping Experiences editor. +- **[Register CMS Element](./cms/register-cms-element.md)**: Create custom CMS elements that render specific content or functionality inside CMS blocks. ## Advanced topics -- **[Entity Types](./entity-types)**: Configure and extend TypeScript typings for entity access and SDK usage. -- **[Migrating Existing Admin Plugins](./migrating-existing-admin-plugins)**: Learn how to gradually migrate existing Twig-based Admin plugins to the Meteor Admin SDK. +- **[Entity Types](./entity-types.md)**: Configure and extend TypeScript typings for entity access and SDK usage. +- **[Migrating Existing Admin Plugins](./migrating-existing-admin-plugins.md)**: Learn how to gradually migrate existing Twig-based Admin plugins to the Meteor Admin SDK. From 13243c3e20f566c53bbc4c26092aa4ab7d9fb8cc Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 20:10:44 +0100 Subject: [PATCH 19/59] Update index.md --- docs/admin-sdk/develop/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/index.md b/docs/admin-sdk/develop/index.md index b012cb00a..e4020fe47 100644 --- a/docs/admin-sdk/develop/index.md +++ b/docs/admin-sdk/develop/index.md @@ -11,7 +11,7 @@ This section explains how to build Administration extensions with the Meteor Adm A typical Administration extension follows this workflow: 1. Identify an extension point in the Administration UI. -2. Add a [main module](../api-reference/ui/mainModule.md) or [action button](../api-reference/ui/actionButton.md) at that [location](./api/location.md). +2. Add a [main module](../api-reference/ui/mainModule.md) or [action button](../api-reference/ui/actionButton.md) at that [location](./location.md). - **Location**: Defines where extension code runs inside the Administration UI. - **Main module**: The entry point of your extension inside the Administration navigation. - **Action button**: Adds functionality to an existing Administration view, such as the product detail page. From a3538a31554bbc7c7767112e0b933aadd40437db Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 20:16:37 +0100 Subject: [PATCH 20/59] Update index.md --- docs/admin-sdk/develop/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/admin-sdk/develop/index.md b/docs/admin-sdk/develop/index.md index e4020fe47..57dd4efbd 100644 --- a/docs/admin-sdk/develop/index.md +++ b/docs/admin-sdk/develop/index.md @@ -15,7 +15,7 @@ A typical Administration extension follows this workflow: - **Location**: Defines where extension code runs inside the Administration UI. - **Main module**: The entry point of your extension inside the Administration navigation. - **Action button**: Adds functionality to an existing Administration view, such as the product detail page. -3. Load or modify Shopware data using [repositories](./composables/use-repository.md). +3. Load or modify Shopware data using [repositories](./composables/useRepository.md). 4. Provide feedback to users with [notifications](./notification.md) or [toasts](./toast.md). ## Development Tools @@ -37,17 +37,17 @@ The following APIs allow extensions to interact with and extend the Shopware Adm Composables provide reusable helpers for working with Administration data and shared state. -- **[useRepository](./composables/use-repository.md)**: Access Shopware repositories to load and manipulate entities. -- **[useSharedState](./composables/use-shared-state.md)**: Share state between extensions or components. +- **[useRepository](./composables/useRepository.md)**: Access Shopware repositories to load and manipulate entities. +- **[useSharedState](./composables/useSharedState.md)**: Share state between extensions or components. ## CMS extensions The CMS API allows extensions to add new CMS blocks and elements to the Shopware content system. -- **[Register CMS Block](./cms/register-cms-block.md)**: Add custom CMS blocks that structure and group content elements in the Shopping Experiences editor. -- **[Register CMS Element](./cms/register-cms-element.md)**: Create custom CMS elements that render specific content or functionality inside CMS blocks. +- **[Register CMS Block](./cms/registerCmsBlock.md)**: Add custom CMS blocks that structure and group content elements in the Shopping Experiences editor. +- **[Register CMS Element](./cms/registerCmsElement.md)**: Create custom CMS elements that render specific content or functionality inside CMS blocks. ## Advanced topics - **[Entity Types](./entity-types.md)**: Configure and extend TypeScript typings for entity access and SDK usage. -- **[Migrating Existing Admin Plugins](./migrating-existing-admin-plugins.md)**: Learn how to gradually migrate existing Twig-based Admin plugins to the Meteor Admin SDK. +- **[Migrating Existing Admin Plugins](./migrating-admin-plugins.md)**: Learn how to gradually migrate existing Twig-based Admin plugins to the Meteor Admin SDK. From 14dd9b26a21f5f1859c1e7669a0d88173eb66f05 Mon Sep 17 00:00:00 2001 From: somethings Date: Mon, 16 Mar 2026 20:18:21 +0100 Subject: [PATCH 21/59] Update location.md --- docs/admin-sdk/develop/location.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/admin-sdk/develop/location.md b/docs/admin-sdk/develop/location.md index a2c40a4a5..6f0a795ce 100644 --- a/docs/admin-sdk/develop/location.md +++ b/docs/admin-sdk/develop/location.md @@ -10,11 +10,9 @@ Locations define where extension code is executed inside the Shopware Administra Each location represents a specific UI context (for example a tab, modal, sidebar, or hidden entry point). Extensions typically check the current location before deciding which UI elements to register or which view to render. -See [Locations](../concepts/locations.md) for a full explanation of the concept. - ## Prerequisites -We recommend you read the [concept](../concepts/locations.md) of locations first. +See [Locations](../concepts/locations.md) for a full explanation of the concept. ## Location checks From 5b4885bf783b523210053e2a4a91ed2e3e6c5ed5 Mon Sep 17 00:00:00 2001 From: somethings Date: Tue, 17 Mar 2026 19:57:08 +0100 Subject: [PATCH 22/59] Update migrating-admin-plugins.md --- docs/admin-sdk/develop/migrating-admin-plugins.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/admin-sdk/develop/migrating-admin-plugins.md b/docs/admin-sdk/develop/migrating-admin-plugins.md index 291f39a79..5c4a20645 100644 --- a/docs/admin-sdk/develop/migrating-admin-plugins.md +++ b/docs/admin-sdk/develop/migrating-admin-plugins.md @@ -37,8 +37,6 @@ Shopware.Component.override('sw-dashboard-index', { ## Using locations with normal Vue components without iFrame rendering -**This feature is not yet released in Shopware. It's only available with the development environment or `dev-trunk` version of Shopware.** - This feature is useful when you want to partially migrate from the Twig plugin system to the SDK extension system and use both systems together. Instead of rendering an iFrame view for a location, you can render a normal Vue component directly inside the Shopware Administration. To do this, register the component in the existing plugin system: From 16557d04d93b280ddc12efda52861b21717a64bc Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 19 Mar 2026 07:57:28 +0100 Subject: [PATCH 23/59] Update migrating-admin-plugins.md --- docs/admin-sdk/develop/migrating-admin-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/migrating-admin-plugins.md b/docs/admin-sdk/develop/migrating-admin-plugins.md index 5c4a20645..89714e3cc 100644 --- a/docs/admin-sdk/develop/migrating-admin-plugins.md +++ b/docs/admin-sdk/develop/migrating-admin-plugins.md @@ -19,7 +19,7 @@ This approach can also help simplify your plugins and prepare them for long-term ### Example ```js -// Use existing extension capabilties +// Use existing extension capabilities Shopware.Component.override('sw-dashboard-index', { methods: { async createdComponent() { From 33b87cf1882c0c7f6ce18c58339de28b84db9870 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 19 Mar 2026 08:22:05 +0100 Subject: [PATCH 24/59] Update index.md --- docs/admin-sdk/getting-started/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index 388c7c749..394d79583 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -117,5 +117,5 @@ Using the CDN is quick and convenient, making it suitable for prototyping, exper Choose your extension type: -- [App Installation Flow](./getting-started/installation-apps.md) -- [Plugin Installation Flow](./getting-started/installation-plugins.md) +- [App Installation Flow](./installation-apps.md) +- [Plugin Installation Flow](./installation-plugins.md) From bb771a83cfa9ba7313c11445f51f9a738c25f743 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 19 Mar 2026 11:20:48 +0100 Subject: [PATCH 25/59] Update index.md --- docs/admin-sdk/getting-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index 394d79583..b92209b33 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -31,7 +31,7 @@ npm install vite #### Import variants -The SDK can be imported in several ways depending on the bundling setup. Import the SDK in your frontend entry file (for example, `main.js`). +The SDK can be imported in several ways depending on the bundling setup. You can import the SDK wherever you need it in your frontend code, for example in a module that uses it or in an entry file such as `main.js`. Import the full SDK (for quick prototyping or when using many SDK features): From be116ede4016062c7a1640d5e11b70723641a842 Mon Sep 17 00:00:00 2001 From: somethings Date: Thu, 19 Mar 2026 19:32:11 +0100 Subject: [PATCH 26/59] Update index.md --- docs/admin-sdk/api-reference/ui/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-sdk/api-reference/ui/index.md b/docs/admin-sdk/api-reference/ui/index.md index 9de48e87d..d8ff1af5e 100644 --- a/docs/admin-sdk/api-reference/ui/index.md +++ b/docs/admin-sdk/api-reference/ui/index.md @@ -15,11 +15,11 @@ The following guides cover common UI extension patterns. ## Using UI components -Shopware Administration components cannot be used directly inside apps or plugins. Instead, extensions should use the Meteor Component Library to achieve a native look and feel. +Shopware Administration components cannot be used directly inside apps or plugins. Instead, extensions should use the [Meteor Component Library](https://github.com/shopware/meteor/tree/main/packages/component-library) to achieve a native look and feel. Shopware Administration components are not native Vue components. They rely on internal extension capabilities, Twig templates, and framework integrations that are not available externally. -The [Meteor Component Library](https://github.com/shopware/meteor/tree/main/packages/component-library) provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. +The Meteor Component Library provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. ## Typical UI extension workflow From 2e21e152802a50b380ea9dbd8e1ef0e75d526b43 Mon Sep 17 00:00:00 2001 From: LApple Date: Thu, 19 Mar 2026 22:39:43 +0100 Subject: [PATCH 27/59] fixes api ref --- .../assets/notification-example.jpg | Bin .../assets/register-cms-block-example.png | Bin .../assets/register-cms-element-example.png | Bin .../assets/toast-example.png | Bin .../assets/useSharedState-demo.gif | Bin .../{develop => api-reference}/cms/index.md | 0 .../cms/registerCmsBlock.md | 0 .../cms/registerCmsElement.md | 0 .../{develop => api-reference}/composables/index.md | 0 .../composables/useRepository.md | 0 .../composables/useSharedState.md | 0 .../admin-sdk/{develop => api-reference}/context.md | 3 ++- .../api-reference/data/in-app-purchases.md | 4 ++-- docs/admin-sdk/api-reference/index.md | 8 ++++---- .../{develop => api-reference}/location.md | 0 .../{develop => api-reference}/notification.md | 0 docs/admin-sdk/{develop => api-reference}/toast.md | 0 docs/admin-sdk/{develop => api-reference}/window.md | 0 18 files changed, 8 insertions(+), 7 deletions(-) rename docs/admin-sdk/{develop => api-reference}/assets/notification-example.jpg (100%) rename docs/admin-sdk/{develop => api-reference}/assets/register-cms-block-example.png (100%) rename docs/admin-sdk/{develop => api-reference}/assets/register-cms-element-example.png (100%) rename docs/admin-sdk/{develop => api-reference}/assets/toast-example.png (100%) rename docs/admin-sdk/{develop => api-reference}/assets/useSharedState-demo.gif (100%) rename docs/admin-sdk/{develop => api-reference}/cms/index.md (100%) rename docs/admin-sdk/{develop => api-reference}/cms/registerCmsBlock.md (100%) rename docs/admin-sdk/{develop => api-reference}/cms/registerCmsElement.md (100%) rename docs/admin-sdk/{develop => api-reference}/composables/index.md (100%) rename docs/admin-sdk/{develop => api-reference}/composables/useRepository.md (100%) rename docs/admin-sdk/{develop => api-reference}/composables/useSharedState.md (100%) rename docs/admin-sdk/{develop => api-reference}/context.md (99%) rename docs/admin-sdk/{develop => api-reference}/location.md (100%) rename docs/admin-sdk/{develop => api-reference}/notification.md (100%) rename docs/admin-sdk/{develop => api-reference}/toast.md (100%) rename docs/admin-sdk/{develop => api-reference}/window.md (100%) diff --git a/docs/admin-sdk/develop/assets/notification-example.jpg b/docs/admin-sdk/api-reference/assets/notification-example.jpg similarity index 100% rename from docs/admin-sdk/develop/assets/notification-example.jpg rename to docs/admin-sdk/api-reference/assets/notification-example.jpg diff --git a/docs/admin-sdk/develop/assets/register-cms-block-example.png b/docs/admin-sdk/api-reference/assets/register-cms-block-example.png similarity index 100% rename from docs/admin-sdk/develop/assets/register-cms-block-example.png rename to docs/admin-sdk/api-reference/assets/register-cms-block-example.png diff --git a/docs/admin-sdk/develop/assets/register-cms-element-example.png b/docs/admin-sdk/api-reference/assets/register-cms-element-example.png similarity index 100% rename from docs/admin-sdk/develop/assets/register-cms-element-example.png rename to docs/admin-sdk/api-reference/assets/register-cms-element-example.png diff --git a/docs/admin-sdk/develop/assets/toast-example.png b/docs/admin-sdk/api-reference/assets/toast-example.png similarity index 100% rename from docs/admin-sdk/develop/assets/toast-example.png rename to docs/admin-sdk/api-reference/assets/toast-example.png diff --git a/docs/admin-sdk/develop/assets/useSharedState-demo.gif b/docs/admin-sdk/api-reference/assets/useSharedState-demo.gif similarity index 100% rename from docs/admin-sdk/develop/assets/useSharedState-demo.gif rename to docs/admin-sdk/api-reference/assets/useSharedState-demo.gif diff --git a/docs/admin-sdk/develop/cms/index.md b/docs/admin-sdk/api-reference/cms/index.md similarity index 100% rename from docs/admin-sdk/develop/cms/index.md rename to docs/admin-sdk/api-reference/cms/index.md diff --git a/docs/admin-sdk/develop/cms/registerCmsBlock.md b/docs/admin-sdk/api-reference/cms/registerCmsBlock.md similarity index 100% rename from docs/admin-sdk/develop/cms/registerCmsBlock.md rename to docs/admin-sdk/api-reference/cms/registerCmsBlock.md diff --git a/docs/admin-sdk/develop/cms/registerCmsElement.md b/docs/admin-sdk/api-reference/cms/registerCmsElement.md similarity index 100% rename from docs/admin-sdk/develop/cms/registerCmsElement.md rename to docs/admin-sdk/api-reference/cms/registerCmsElement.md diff --git a/docs/admin-sdk/develop/composables/index.md b/docs/admin-sdk/api-reference/composables/index.md similarity index 100% rename from docs/admin-sdk/develop/composables/index.md rename to docs/admin-sdk/api-reference/composables/index.md diff --git a/docs/admin-sdk/develop/composables/useRepository.md b/docs/admin-sdk/api-reference/composables/useRepository.md similarity index 100% rename from docs/admin-sdk/develop/composables/useRepository.md rename to docs/admin-sdk/api-reference/composables/useRepository.md diff --git a/docs/admin-sdk/develop/composables/useSharedState.md b/docs/admin-sdk/api-reference/composables/useSharedState.md similarity index 100% rename from docs/admin-sdk/develop/composables/useSharedState.md rename to docs/admin-sdk/api-reference/composables/useSharedState.md diff --git a/docs/admin-sdk/develop/context.md b/docs/admin-sdk/api-reference/context.md similarity index 99% rename from docs/admin-sdk/develop/context.md rename to docs/admin-sdk/api-reference/context.md index f6b7d36ed..b3407d1a3 100644 --- a/docs/admin-sdk/develop/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -76,7 +76,8 @@ sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { ### Get current environment -#### Usage: +#### Usage + ```ts const environment = await sw.context.getEnvironment(); ``` diff --git a/docs/admin-sdk/api-reference/data/in-app-purchases.md b/docs/admin-sdk/api-reference/data/in-app-purchases.md index 5e6682517..e27a438a8 100644 --- a/docs/admin-sdk/api-reference/data/in-app-purchases.md +++ b/docs/admin-sdk/api-reference/data/in-app-purchases.md @@ -7,8 +7,8 @@ nav: # In-App Purchases -> Available since Shopware v6.6.9.0 -> +Available since Shopware v6.6.9.0. + In-App purchases allow apps to unlock different functionality based on purchases made by the user. This guide covers how to start the in-app purchase flow directly from the Administration. ## Start the purchase flow diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index 8b91c754d..11ad48aaa 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -65,8 +65,8 @@ They simplify common patterns such as accessing repositories or sharing state be APIs in this section include: -- [useRepository](../develop/composables/useRepository.md) -- [useSharedState](../develop/composables/useSharedState.md) +- [useRepository](./composables/useRepository.md) +- [useSharedState](./composables/useSharedState.md) ## Extending the CMS @@ -76,8 +76,8 @@ They can be used to introduce custom content components that merchants can use w APIs in this section include: -- [Register CMS Block](../develop/cms/registerCmsBlock.md) -- [Register CMS Element](../develop/cms/registerCmsElement.md) +- [Register CMS Block](./cms/registerCmsBlock.md) +- [Register CMS Element](./cms/registerCmsElement.md) ## Shared Options diff --git a/docs/admin-sdk/develop/location.md b/docs/admin-sdk/api-reference/location.md similarity index 100% rename from docs/admin-sdk/develop/location.md rename to docs/admin-sdk/api-reference/location.md diff --git a/docs/admin-sdk/develop/notification.md b/docs/admin-sdk/api-reference/notification.md similarity index 100% rename from docs/admin-sdk/develop/notification.md rename to docs/admin-sdk/api-reference/notification.md diff --git a/docs/admin-sdk/develop/toast.md b/docs/admin-sdk/api-reference/toast.md similarity index 100% rename from docs/admin-sdk/develop/toast.md rename to docs/admin-sdk/api-reference/toast.md diff --git a/docs/admin-sdk/develop/window.md b/docs/admin-sdk/api-reference/window.md similarity index 100% rename from docs/admin-sdk/develop/window.md rename to docs/admin-sdk/api-reference/window.md From 78a819eb6656748d473334327ad7c0666f6659c7 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 15:15:34 +0100 Subject: [PATCH 28/59] docs: apply code suggestions for api-reference and concepts - Set navigation positions: ui=100, data=200, cms=300, composables=400, concepts=20 - Rename composables title to "Vue Composables" - Rename ui title to "Extending the UI" - Rename api-reference heading to "Extending the UI" - Use method-style headings in repository.md (repository.search(), etc.) - Use method-style headings in mainModule.md and mediaModal.md - Improve data file descriptions (subscribe, update, get) - Fix component-sections example headings - Fix toast availability formatting and icon column - Fix datahandling.md typo - Improve component-sections concept description - Remove internal getRepository references from useRepository.md Made-with: Cursor --- docs/admin-sdk/api-reference/cms/index.md | 2 +- .../api-reference/composables/index.md | 8 ++-- .../composables/useRepository.md | 37 ++++--------------- docs/admin-sdk/api-reference/data/get.md | 2 +- docs/admin-sdk/api-reference/data/index.md | 2 +- .../api-reference/data/repository.md | 16 ++++---- .../admin-sdk/api-reference/data/subscribe.md | 4 +- docs/admin-sdk/api-reference/data/update.md | 2 +- docs/admin-sdk/api-reference/index.md | 8 ++-- docs/admin-sdk/api-reference/toast.md | 10 ++--- .../api-reference/ui/component-sections.md | 8 +--- docs/admin-sdk/api-reference/ui/index.md | 4 +- docs/admin-sdk/api-reference/ui/mainModule.md | 6 +-- docs/admin-sdk/api-reference/ui/mediaModal.md | 4 +- docs/admin-sdk/concepts/component-sections.md | 2 +- docs/admin-sdk/concepts/datahandling.md | 2 +- docs/admin-sdk/concepts/index.md | 2 +- 17 files changed, 47 insertions(+), 72 deletions(-) diff --git a/docs/admin-sdk/api-reference/cms/index.md b/docs/admin-sdk/api-reference/cms/index.md index f5e8d1dbc..67e9cf69a 100644 --- a/docs/admin-sdk/api-reference/cms/index.md +++ b/docs/admin-sdk/api-reference/cms/index.md @@ -1,7 +1,7 @@ --- title: "Extending the CMS" nav: - position: 10 + position: 300 --- diff --git a/docs/admin-sdk/api-reference/composables/index.md b/docs/admin-sdk/api-reference/composables/index.md index 84c9a8339..436b7a0bf 100644 --- a/docs/admin-sdk/api-reference/composables/index.md +++ b/docs/admin-sdk/api-reference/composables/index.md @@ -1,13 +1,13 @@ --- -title: "Composable APIs" +title: "Vue Composables" nav: - position: 10 + position: 400 --- -# Composable APIs +# Vue Composables -Composable APIs provide reusable helpers for working with the Shopware Administration data layer and shared state inside extensions. +Composable APIs provide reusable Vue Composables for working with the Shopware Administration data layer and shared state inside extensions. They simplify common tasks such as accessing repositories or sharing reactive state between different parts of an extension. diff --git a/docs/admin-sdk/api-reference/composables/useRepository.md b/docs/admin-sdk/api-reference/composables/useRepository.md index 81bb5bfb6..9588ad2c6 100644 --- a/docs/admin-sdk/api-reference/composables/useRepository.md +++ b/docs/admin-sdk/api-reference/composables/useRepository.md @@ -7,13 +7,9 @@ nav: # useRepository -:::info -Some older examples reference `getRepository`. This helper is not part of the public API. Use [`useRepository`](./useRepository.md) instead. -::: +The `composables.useRepository` function creates a reactive repository instance that automatically updates when its dependencies change. This is particularly useful when you need a repository that responds to reactive data changes in your Vue components. -The `composables.useRepository` function is a reactive wrapper around the `getRepository` function. It creates a repository instance that automatically updates when its dependencies change. This is particularly useful when you need a repository that responds to reactive data changes in your Vue components. - -Unlike `getRepository`, which returns a static repository instance, `useRepository` accepts reactive references (refs) or values as parameters and returns a computed repository that updates when those parameters change. +`useRepository` accepts reactive references (refs) or values as parameters and returns a computed repository that updates when those parameters change. ## Usage @@ -31,9 +27,8 @@ const productRepository = useRepository(entityName); entityName.value = 'category'; // Now productRepository.value references a category repository -// With a reactive repository factory -const myFactory = ref(customRepositoryFactory); -const repository = useRepository('product', myFactory); +// With a custom repository factory +const repository = useRepository('product', myRepositoryFactory); // Search for products const products = await repository.value.search(criteria); @@ -59,27 +54,9 @@ This reactivity is implemented using Vue's computed properties, ensuring that th A computed ref containing a repository that updates when its dependencies change. The repository provides the same methods as described in the `getRepository` documentation, but you need to access them through the `.value` property of the computed ref. -## Relationship with getRepository +## How it works -Under the hood, `useRepository` calls `getRepository` whenever its dependencies change. This means: +`useRepository` uses Vue's `computed` to automatically recreate the repository when its inputs change. This follows Vue's composition API conventions, where composables prefixed with "use" provide reactive wrappers. -- It uses the same repository factory resolution logic as `getRepository` -- It provides the same repository interface and functionality +- It provides the full repository interface (search, get, save, delete, etc.) - It adds reactivity, automatically updating when inputs change - -```ts -// Example implementation (simplified) -import { computed } from 'vue'; -import { getRepository } from './getRepository'; - -export function useRepository(entityNameRef, factoryRef) { - return computed(() => { - const entityName = unref(entityNameRef); - const factory = unref(factoryRef); - - return getRepository(entityName, factory); - }); -} -``` - -This pattern follows Vue's composition API conventions, where composables prefixed with "use" typically provide reactive wrappers around non-reactive functionality. diff --git a/docs/admin-sdk/api-reference/data/get.md b/docs/admin-sdk/api-reference/data/get.md index de7ede809..062a7d3f5 100644 --- a/docs/admin-sdk/api-reference/data/get.md +++ b/docs/admin-sdk/api-reference/data/get.md @@ -10,7 +10,7 @@ With `data.get` you can receive datasets from the Shopware Administration. Compared to `data.subscribe`, `data.get` only gives you the current state of the data. If the data is not available yet, such as when opening a page, you won't receive any data. In these cases, it's better to subscribe to data changes instead. -More information on how to find the unique identifiers can be found in the [data-handling guide](../../concepts/datahandling.md). +[The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. ## Usage diff --git a/docs/admin-sdk/api-reference/data/index.md b/docs/admin-sdk/api-reference/data/index.md index edea9d418..3d8ae83df 100644 --- a/docs/admin-sdk/api-reference/data/index.md +++ b/docs/admin-sdk/api-reference/data/index.md @@ -1,7 +1,7 @@ --- title: "Working with Data" nav: - position: 10 + position: 200 --- diff --git a/docs/admin-sdk/api-reference/data/repository.md b/docs/admin-sdk/api-reference/data/repository.md index b7b92780f..df7d5fa5a 100644 --- a/docs/admin-sdk/api-reference/data/repository.md +++ b/docs/admin-sdk/api-reference/data/repository.md @@ -79,7 +79,7 @@ criteria.getAssociation('categories') ``` -### Search +### repository.search() Sends a search request for the repository entity. #### Usage: @@ -98,7 +98,7 @@ const yourEntities = await exampleRepository.search(yourCriteria); #### Return value: The return value is a EntityCollection which contains all entities matching the criteria. -### Get +### repository.get() Short hand to fetch a single entity from the server #### Usage: @@ -118,7 +118,7 @@ const yourEntity = await exampleRepository.get('theEntityId'); #### Return value: The return value is the entity result when a matching entity was found. -### Save +### repository.save() Detects all entity changes and send the changes to the server. If the entity is marked as new, the repository will send a POST create. Updates will be send as PATCH request. Deleted associations will be send as additional request @@ -139,7 +139,7 @@ await exampleRepository.save(yourEntityObject); #### Return value: This method does not have a return value. It just returns a Promise which is resolved when it was saved successfully. -### Clone +### repository.clone() Clones an existing entity #### Usage: @@ -158,7 +158,7 @@ const clonedEntityId = await exampleRepository.clone('theEntityIdToClone'); #### Return value: This method returns the id of the cloned entity. -### Has changes +### repository.hasChanges() Detects if the entity or the relations has remaining changes which are not synchronized with the server #### Usage: @@ -176,7 +176,7 @@ const hasChanges = await exampleRepository.hasChanges(yourEntityObject); #### Return value: This method returns a boolean value. If the entity has changes then it returns `true`. Otherwise it returns `false`. -### Save all +### repository.saveAll() Detects changes of all provided entities and send the changes to the server #### Usage: @@ -195,7 +195,7 @@ await exampleRepository.saveAll(yourEntityCollection); #### Return value: This method does not have a return value. It just returns a Promise which is resolved when it was saved successfully. -### Delete +### repository.delete() Sends a delete request for the provided id. #### Usage: @@ -214,7 +214,7 @@ await exampleRepository.delete('yourEntityId'); #### Return value: This method does not have a return value. It just returns a Promise which is resolved when it was deleted successfully. -### Create +### repository.create() Creates a new entity for the local schema. To Many association are initialed with a collection with the corresponding remote api route. This entity is not saved to the database yet. #### Usage: diff --git a/docs/admin-sdk/api-reference/data/subscribe.md b/docs/admin-sdk/api-reference/data/subscribe.md index 0d88bb036..710a92332 100644 --- a/docs/admin-sdk/api-reference/data/subscribe.md +++ b/docs/admin-sdk/api-reference/data/subscribe.md @@ -7,7 +7,9 @@ nav: # Subscribe -With `data.subscribe` you can subscribe to dataset changes. The callback will be called every time, the dataset with the matching id is changed. More information on how to find the unique identifiers can be found in [the data handling guide](../../concepts/datahandling.md). +With `data.subscribe`, you can subscribe to changes in the dataset. +Every time the dataset you subscribed to changes, the callback will be called with the new data. +An individual dataset is referenced by an ID. [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. ## Usage diff --git a/docs/admin-sdk/api-reference/data/update.md b/docs/admin-sdk/api-reference/data/update.md index 0f1456147..7e7ec896f 100644 --- a/docs/admin-sdk/api-reference/data/update.md +++ b/docs/admin-sdk/api-reference/data/update.md @@ -7,7 +7,7 @@ nav: # Update -With `data.update` you can update datasets from the Shopware Administration. More information on how to find the unique identifiers can be found in [the data-handling guide](../../concepts/datahandling.md). +With `data.update` you can update datasets from the Shopware Administration. [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. ## Usage diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index 11ad48aaa..3d46b3830 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -12,9 +12,9 @@ These APIs allow extensions to add user interface elements, access and modify en Use the sections below to navigate the available APIs. -## Extending the Administration UI +## Extending the UI -These UI extension components allow extensions to add UI elements to the Shopware Administration. They can be used to register modules, add navigation entries, extend existing pages, and display dialogs or side panels. +These components allow extensions to add UI elements to the Shopware Administration. They can be used to register modules, add navigation entries, extend existing pages, and display dialogs or side panels. Typical use cases include: @@ -51,11 +51,11 @@ Typical workflows include: Tools this section include: -- [Repository](./data/repository.md) +- [Repository](./data/repository.md): Access Shopware entity repositories - [Get](./data/get.md) - [Subscribe](./data/subscribe.md) - [Update](./data/update.md) -- [In-App Purchases](./data/in-app-purchases.md) +- [Trigger an In-App Purchase](./data/in-app-purchases.md) ## Composable APIs diff --git a/docs/admin-sdk/api-reference/toast.md b/docs/admin-sdk/api-reference/toast.md index 4113d344f..6da53e9ec 100644 --- a/docs/admin-sdk/api-reference/toast.md +++ b/docs/admin-sdk/api-reference/toast.md @@ -10,11 +10,11 @@ Toasts display short, temporary messages to provide feedback about user actions See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. -## Availability +:::info Availability +This feature is available since Shopware 6.6.2.0. +::: -This feature will be available with Shopware 6.6.2.0. - -### Dispatch a toast +## Dispatch a toast ![toast example](./assets/toast-example.png) @@ -42,7 +42,7 @@ sw.toast.dispatch({ |:--------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------| | `msg` | true | | Defines a toast's main expression or message to the user. | | `type` | true | | Defines the toast type. Available `types` are `positive`, `informal` and `critical`. | -| `icon ` | false | None | An icon that should be displayed in front of your message. | +| `icon` | false | None | An icon that should be displayed in front of your message. | | `dismissible` | false | `false` | Specifies if the toast can be manually dismissed. | | `action` | false | None | Adds a clickable button to the toast. The button receives a label and a callback which is called once clicked. | diff --git a/docs/admin-sdk/api-reference/ui/component-sections.md b/docs/admin-sdk/api-reference/ui/component-sections.md index 20142709a..f2c9b20ea 100644 --- a/docs/admin-sdk/api-reference/ui/component-sections.md +++ b/docs/admin-sdk/api-reference/ui/component-sections.md @@ -51,7 +51,7 @@ This method does not have a return value. | `locationId` | true | | The locationId for the custom view | | `tabs` | false | | Render different content with tabs | -#### Usage +#### Example: Add a component to the product page ```js import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -67,11 +67,9 @@ ui.componentSection.add({ }) ``` -#### Example - ![Card component example](./assets/example-card.png) -#### With tabs +#### Example: Add tabs to the card ```js import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -100,6 +98,4 @@ ui.componentSection.add({ }) ``` -#### Example - ![Card component with tabs example](./assets/example-card-with-tabs.png) diff --git a/docs/admin-sdk/api-reference/ui/index.md b/docs/admin-sdk/api-reference/ui/index.md index d8ff1af5e..d60bdce71 100644 --- a/docs/admin-sdk/api-reference/ui/index.md +++ b/docs/admin-sdk/api-reference/ui/index.md @@ -1,7 +1,7 @@ --- -title: "Extending the Administration UI" +title: "Extending the UI" nav: - position: 10 + position: 100 --- diff --git a/docs/admin-sdk/api-reference/ui/mainModule.md b/docs/admin-sdk/api-reference/ui/mainModule.md index cff6292cd..0b3115e0f 100644 --- a/docs/admin-sdk/api-reference/ui/mainModule.md +++ b/docs/admin-sdk/api-reference/ui/mainModule.md @@ -11,7 +11,7 @@ A main module registers a new top-level section in the Shopware Administration n Use a main module when your extension provides a dedicated application area with its own pages and functionality. -## Add main module +## addMainModule() Add a main module to your extension. The content of the main module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. @@ -68,7 +68,7 @@ if (location.is('main-location-id')) { } ``` -## Add smart bar button to main module +## addSmartbarButton() Add a button to the smart bar of your main module. The button can be used to trigger actions, e.g. saving, cancel, etc. The location ID needs to be defined and have the same value as the `locationId` of the main module. @@ -95,7 +95,7 @@ ui.mainModule.addSmartbarButton({ | `onClickCallback` | true | | Callback function which will be called once the button is clicked | | `disabled` | false | false | Toggle disabled state of the button | -## Hide smart bar +## hideSmartBar() Turn the smart bar off as needed. diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index afe1d4138..07dbbd82e 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -12,9 +12,9 @@ This method allows apps to interact with the Administration's media modal. Two m - **Media modal**: Select existing media from the media library or upload new files. Available since Shopware 6.7.1. - **Save media modal**: Choose a specific folder and filename when saving media. Available since Shopware 6.7.5. -## Open modal +## ui.mediaModal.open() -Open media modal in the current view. +Open the media modal in the current view. ### Usage diff --git a/docs/admin-sdk/concepts/component-sections.md b/docs/admin-sdk/concepts/component-sections.md index b58c71b79..2ddbea928 100644 --- a/docs/admin-sdk/concepts/component-sections.md +++ b/docs/admin-sdk/concepts/component-sections.md @@ -7,7 +7,7 @@ nav: # Component Sections -Component sections allow extensions to render UI components inside predefined extension points in the Shopware Administration. +Component sections allow extensions to render custom UI components inside predefined extension points in the Shopware Administration. Unlike other extension APIs that modify existing UI elements (such as tabs or buttons), component sections allow extensions to inject full components into specific UI positions. diff --git a/docs/admin-sdk/concepts/datahandling.md b/docs/admin-sdk/concepts/datahandling.md index 582da6b5e..1cbdb594b 100644 --- a/docs/admin-sdk/concepts/datahandling.md +++ b/docs/admin-sdk/concepts/datahandling.md @@ -7,7 +7,7 @@ nav: # Data Handling -This guide elaborates how the data handling works between extensions and the Shopware Sdministration. +This guide elaborates on how the data handling works between extensions and the Shopware Administration. ## What are datasets? diff --git a/docs/admin-sdk/concepts/index.md b/docs/admin-sdk/concepts/index.md index 543881413..11a809cc4 100644 --- a/docs/admin-sdk/concepts/index.md +++ b/docs/admin-sdk/concepts/index.md @@ -1,7 +1,7 @@ --- title: "Concepts" nav: - position: 10 + position: 20 --- # Concepts From 103e6d591192c83a557fb20b5a84943ce714b5b0 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 15:18:03 +0100 Subject: [PATCH 29/59] docs: revise installation guides and index page installation-apps.md: - Clarify backend is required, not optional - Add Cross-Origin Security explanation and dev tip - Add Docker host.docker.internal note - Replace git clone with npx tiged scaffold command - Add php-sdk reference and official SDK list link - Add manifest path and install commands - Clarify notification appears on every page - Add next steps section installation-plugins.md: - Restructure to assume 6.7+ as default - Add collapsible <6.7 details throughout - Add info box about version differences - Fix SDK install command with correct path - Add plugin install and cache clear commands - Add bundling explanation (Shopware handles Vite) - Add next steps section index.md: - Combine "What you can build" and "What you can do" into single section - Fix ambiguous "Go here" link Made-with: Cursor --- .../getting-started/installation-apps.md | 53 +++++----- .../getting-started/installation-plugins.md | 98 ++++++++----------- docs/admin-sdk/index.md | 21 ++-- 3 files changed, 75 insertions(+), 97 deletions(-) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index d4d300175..9e2ba8270 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -10,8 +10,8 @@ Using the Meteor Admin SDK in an app requires exposing an Administration page fr This guide discusses two SDKs: -- Meteor Admin SDK: UI layer **only** -- Optional App Server SDK = **backend** layer +- Meteor Admin SDK: **frontend** layer for the administration +- App Server SDK: **backend** layer (the backend is required; only the framework you use to provide it is up to you) ## App hosting requirement @@ -24,41 +24,41 @@ Example: - `app-one.your-company.com` - `app-two.your-company.com` -Each app must expose its own publicly reachable URL for registration and webhook handling. +Each app must expose its own publicly reachable URL for registration and webhook handling. This is required due to Cross-Origin security policies enforced by the browser. + +:::tip +For local development, you don't need a public URL yet. You can use `localhost` or a tunneling service like ngrok. +If your Shopware instance runs inside Docker, use `host.docker.internal:PORT` instead of `localhost:PORT` to reach the app server from inside the container. +::: ## Backend requirement Apps require a backend that handles the registration handshake and request validation. -Optional, but highly recommended for app development, is the [App Server SDK](https://github.com/shopware/app-sdk-js): a small TypeScript helper library that simplifies the registration handshake, signature verification, webhook handling, and communication with the Shopware API. - -The App Server SDK is suitable for both development and production environments [across runtimes](https://www.shopware.com/en/news/shopware-app-server-sdk-in-javascript/) such as Node.js, Deno, Bun, or Cloudflare Workers. +Optional, but highly recommended for app development, is the [App Server SDK](https://github.com/shopware/app-sdk-js): a library written in TypeScript that provides a server setup to simplify the registration handshake, signature verification, webhook handling, and communication with the Shopware API. -To run a local dev server for an app, follow the SDK repo README for exact commands: +The App Server SDK supports Node.js, Deno, Bun, and Cloudflare Workers. -```bash -# clone the App Server SDK (example) -git clone https://github.com/shopware/app-sdk-js -cd app-sdk-js +Shopware also provides SDKs for other languages. See the [full list of official App SDKs](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/). -# install dependencies and start the dev server -npm install -npm run dev # or `npm start` per the repo README +To scaffold a new app using the App Server SDK: -# the dev server will expose a public URL (or you can tunnel it with ngrok) for registering the App's admin page +```bash +npx tiged shopware/app-sdk-js/examples/node-hono demo-app +cd demo-app ``` Visit [the App Server SDK guide](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/javascript/01-getting_started.html) for detailed instructions. ### 1. Ensure the app server is running -If the app provides an Administration UI, it must: +Every app must: - Handle the registration handshake - Expose a publicly reachable URL - Serve an HTML page for the Administration -Using the [App Server SDK](https://github.com/shopware/app-sdk-js) is recommended, as it handles the registration handshake, signature verification, webhook handling, and request validation. But it is also possible to implement the registration and request validation manually, for advanced setups. +Using the [App Server SDK](https://github.com/shopware/app-sdk-js) is recommended, as it handles the registration handshake, signature verification, webhook handling, and request validation. It is also possible to implement the registration and request validation manually for advanced setups. ### 2. Create the Administration HTML page @@ -138,15 +138,20 @@ For an example, the `manifest.xml` of an app whose HTML page is served under `ht ### 4. Install and activate the app -- Upload or register the app -- Activate it in the Administration +The manifest needs to be stored under `/custom/apps//manifest.xml`. Then install using the command line: -### 5. Verify installation +```bash +# if you are using Docker, run the following commands inside the container: docker compose exec -it web /bin/bash +bin/console app:install --activate +bin/console cache:clear +``` -Log in to the Shopware Administration. +### 5. Verify installation -Open the module defined in the app's `` section. +Log in to the Shopware Administration. The notification should appear in the top-right corner on any page (the notification is not bound to a specific module — it appears on every page load). -The notification should appear in the top-right corner. +## Next steps -Installation complete. ✅ +- Explore the [API Reference](../api-reference/index.md) for all available SDK features +- Learn about [Concepts](../concepts/index.md) like locations, positions, and data handling +- See the [Usage Guide](./usage.md) for more detailed examples diff --git a/docs/admin-sdk/getting-started/installation-plugins.md b/docs/admin-sdk/getting-started/installation-plugins.md index 498ea013c..91c95b0ca 100644 --- a/docs/admin-sdk/getting-started/installation-plugins.md +++ b/docs/admin-sdk/getting-started/installation-plugins.md @@ -8,23 +8,29 @@ sidebar_position: 30 Plugins are supported on self-hosted Shopware instances only. -## For Shopware 6.7+ - -Shopware 6.7 introduced a new Administration extension architecture (`meteor-app`) with modern frontend build tooling (Vite-based). Earlier versions use the legacy `administration` directory. Admin extensions are loaded as a hidden iframe, and there's clear separation between plugin backends and frontend apps. +:::info +The setup process is slightly different for **Shopware instances below version 6.7**. Look out for spoilers that explain what's different. +::: ### 1. Create the administration entry -Create the folder `custom/plugins/yourPlugin/src/Resources/app/meteor-app`. This is the base path for all new files for your extension. +Create the folder `custom/plugins/yourPluginName/src/Resources/app/meteor-app`. This is the base path for all new files for your extension. -### 2. Initialize npm +
+ If your shopware instance runs a version below 6.7 + Use the path `custom/plugins/yourPluginName/src/Resources/app/administration` instead +
-Initialize a new Node project with `npm init --yes`. +### 2. Install the SDK -### 3. Install the SDK +Then install the SDK -Then install the SDK with `npm install @shopware-ag/meteor-admin-sdk`. +```bash +cd custom/plugins/yourPluginName/src/Resources/app/meteor-app +npm install @shopware-ag/meteor-admin-sdk +``` -### 4. Implement your entry file +### 3. Implement your entry file Create a new base `index.html` file, which will be automatically injected as a hidden iFrame to the Administration when the plugin is activated. @@ -35,7 +41,6 @@ Then create a JavaScript file in the subfolder `src/main.js` and reference it in - Your extension @@ -46,69 +51,46 @@ Then create a JavaScript file in the subfolder `src/main.js` and reference it in ``` -The SDK must be bundled as part of your plugin’s build process. See the [Plugin development guide](https://developer.shopware.com/docs/guides/plugins/plugins/plugin-base-guide.html). +
+ If your shopware instance runs a version below 6.7 + Leave out <script type="module" src="/src/main.js"></script> since it's injected automatically. +
-### 5. Rebuild the Administration +In `src/main.js`, add a quick test to verify the SDK works: -This command starts the Administration watcher and rebuilds the frontend bundle: +```js +import { notification } from '@shopware-ag/meteor-admin-sdk'; -```bash -bin/watch-administration.sh +notification.dispatch({ + title: 'Hello from your plugin', + message: 'Meteor Admin SDK is working' +}); ``` -Wait until the compilation finishes successfully. - -### 6. Verify installation - -Log in to the Administration. The SDK should function correctly. - -Installation complete ✅ - -## For Shopware 6.6 and below - -These versions use the legacy `administration` directory, with an older Admin build process. Files are injected directly into the Administration bundle. - -### 1. Create the Administration entry - -Open the path `custom/plugins/yourPlugin/src/Resources/app/administration`. This is the base path for all new admin files. - -Create a new base `index.html` file. This file will be automatically injected to the Administration when the plugin is activated. - -Then create a JavaScript file in the subfolder `src/main.js`. This file will be automatically injected into the created HTML file. - -### 2. Initialize npm - -For plugins, the best way is to install the SDK via npm. First, initialize a new npm project in the plugin folder: +### 4. Installing the plugin ```bash -npm init --yes +# if you are using Docker, run the following commands inside the container: docker compose exec -it web /bin/bash +bin/console plugin:install --activate yourPluginName +bin/console cache:clear ``` -This should result in the following folder structure: - -```plaintext -custom/plugins/yourPlugin/src/Resources/app/administration -├── index.html -├── package.json -├── package-lock.json -├── src -│ ├── main.js -``` +### 5. Bundling the plugin -### 3. Install the SDK +You don't need to set up Vite (the bundler) on your own — Shopware already takes care of that. Run the Administration watcher to rebuild the frontend bundle: ```bash -npm install @shopware-ag/meteor-admin-sdk +bin/watch-administration.sh ``` -### 4. Rebuild the Administration +Wait until the compilation finishes successfully. -```bash -bin/watch-administration.sh -``` +### 6. Verify installation -### 5. Verify installation +Log in to the Administration. A notification should appear in the top-right corner. -Log in to the Administration and confirm that your SDK code executes. +## Next steps -Installation complete. ✅ +- Explore the [API Reference](../api-reference/index.md) for all available SDK features +- Learn about [Concepts](../concepts/index.md) like locations, positions, and data handling +- See the [Usage Guide](./usage.md) for more detailed examples diff --git a/docs/admin-sdk/index.md b/docs/admin-sdk/index.md index 18696264f..d09b8af15 100644 --- a/docs/admin-sdk/index.md +++ b/docs/admin-sdk/index.md @@ -11,21 +11,12 @@ custom_edit_url: null The Meteor Admin SDK is an npm library for building Shopware Administration UI extensions. It enables [apps](https://developer.shopware.com/docs/guides/plugins/apps/) and [plugins](https://developer.shopware.com/docs/guides/plugins/plugins/) to extend the Shopware Administration through a stable, typed API that runs in the browser context. -What you can build: +What you can do with the SDK: -- Custom Administration modules -- Context-aware UI extensions -- Entity-driven workflows inside the Administration -- Notification and interaction systems -- Admin-driven integrations with external services -- Dynamic UI behavior based on Shopware state - -What you can do: - -- Dispatch notifications -- Access context information -- Extend the Administration UI -- Interact with entities +- Build custom Administration modules and context-aware UI extensions +- Extend the Administration UI with notifications, modals, tabs, and more +- Access and modify entity data through the Administration data layer +- Create entity-driven workflows and admin-driven integrations with external services ## Why use the SDK @@ -44,4 +35,4 @@ Using the Meteor Admin SDK requires: ## Next steps -Go here to install the SDK and choose your installation path: npm and Vite (recommended for production) or CDN (for quick prototyping). +See the [Getting Started guide](./getting-started/index.md) to install the SDK and choose your installation path. From 6e4fe12e43c7142483e39e1624d4655c75cc6510 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 15:20:21 +0100 Subject: [PATCH 30/59] docs: demote Usage/Parameters/Return/Example headings to h4 Sub-headings like Usage, Parameters, Return value, and Example should not appear in the table of contents. Changed from h3 (###) to h4 (####) across all API reference pages. Also removed trailing colons from heading text for consistency. 14 files changed, 70+ heading-level adjustments. Made-with: Cursor --- .../composables/useSharedState.md | 2 +- .../api-reference/data/repository.md | 48 +++++++++---------- docs/admin-sdk/api-reference/location.md | 24 +++++----- docs/admin-sdk/api-reference/notification.md | 6 +-- docs/admin-sdk/api-reference/toast.md | 2 +- .../api-reference/ui/component-sections.md | 4 +- docs/admin-sdk/api-reference/ui/mainModule.md | 14 +++--- docs/admin-sdk/api-reference/ui/mediaModal.md | 12 ++--- docs/admin-sdk/api-reference/ui/menu.md | 8 ++-- docs/admin-sdk/api-reference/ui/modals.md | 14 +++--- .../api-reference/ui/settingsItem.md | 6 +-- docs/admin-sdk/api-reference/ui/sidebars.md | 14 +++--- docs/admin-sdk/api-reference/ui/tabs.md | 6 +-- docs/admin-sdk/api-reference/window.md | 32 ++++++------- 14 files changed, 96 insertions(+), 96 deletions(-) diff --git a/docs/admin-sdk/api-reference/composables/useSharedState.md b/docs/admin-sdk/api-reference/composables/useSharedState.md index 01ac63600..e5e2f4107 100644 --- a/docs/admin-sdk/api-reference/composables/useSharedState.md +++ b/docs/admin-sdk/api-reference/composables/useSharedState.md @@ -24,7 +24,7 @@ const { useSharedState } = composables; const mySharedStateValue = useSharedState('myUniqueKeyForTheSharedState', 'myInitialDataValue'); ``` -### Parameters +#### Parameters | Name | Required | Description | | :------------- | :------- | :------------------------------------------------------------------------ | diff --git a/docs/admin-sdk/api-reference/data/repository.md b/docs/admin-sdk/api-reference/data/repository.md index df7d5fa5a..a677e087a 100644 --- a/docs/admin-sdk/api-reference/data/repository.md +++ b/docs/admin-sdk/api-reference/data/repository.md @@ -82,40 +82,40 @@ criteria.getAssociation('categories') ### repository.search() Sends a search request for the repository entity. -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); const yourEntities = await exampleRepository.search(yourCriteria); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `criteria` | true | | Your criteria object | | `context` | false | {} | Change the [request context](#request-context) | -#### Return value: +#### Return value The return value is a EntityCollection which contains all entities matching the criteria. ### repository.get() Short hand to fetch a single entity from the server -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); const yourEntity = await exampleRepository.get('theEntityId'); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `id` | true | | The id of the entity | | `context` | false | {} | Change the [request context](#request-context) | | `criteria` | true | | Your criteria object | -#### Return value: +#### Return value The return value is the entity result when a matching entity was found. ### repository.save() @@ -123,114 +123,114 @@ Detects all entity changes and send the changes to the server. If the entity is marked as new, the repository will send a POST create. Updates will be send as PATCH request. Deleted associations will be send as additional request -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); await exampleRepository.save(yourEntityObject); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :-------- | :------- | :------ | :--------------------------------------------- | | `entity` | true | | The entity object | | `context` | false | {} | Change the [request context](#request-context) | -#### Return value: +#### Return value This method does not have a return value. It just returns a Promise which is resolved when it was saved successfully. ### repository.clone() Clones an existing entity -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); const clonedEntityId = await exampleRepository.clone('theEntityIdToClone'); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `entityId` | true | | The entity id which should be cloned | | `context` | false | {} | Change the [request context](#request-context) | -#### Return value: +#### Return value This method returns the id of the cloned entity. ### repository.hasChanges() Detects if the entity or the relations has remaining changes which are not synchronized with the server -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); const hasChanges = await exampleRepository.hasChanges(yourEntityObject); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :------- | :------- | :------ | :---------------- | | `entity` | true | | The entity object | -#### Return value: +#### Return value This method returns a boolean value. If the entity has changes then it returns `true`. Otherwise it returns `false`. ### repository.saveAll() Detects changes of all provided entities and send the changes to the server -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); await exampleRepository.saveAll(yourEntityCollection); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `entities` | true | | Your entity collection which should be saved | | `context` | false | {} | Change the [request context](#request-context) | -#### Return value: +#### Return value This method does not have a return value. It just returns a Promise which is resolved when it was saved successfully. ### repository.delete() Sends a delete request for the provided id. -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); await exampleRepository.delete('yourEntityId'); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `entityId` | true | | The id of the entity which should be deleted | | `context` | false | {} | Change the [request context](#request-context) | -#### Return value: +#### Return value This method does not have a return value. It just returns a Promise which is resolved when it was deleted successfully. ### repository.create() Creates a new entity for the local schema. To Many association are initialed with a collection with the corresponding remote api route. This entity is not saved to the database yet. -#### Usage: +#### Usage ```ts const exampleRepository = sw.data.repository('your_entity'); const yourNewEntity = await exampleRepository.create(); ``` -#### Parameters: +#### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `context` | false | {} | Change the [request context](#request-context) | | `id` | false | | You can provide a id of the new entity if wanted | -#### Return value: +#### Return value This method returns the newly created entity. ### Request Context diff --git a/docs/admin-sdk/api-reference/location.md b/docs/admin-sdk/api-reference/location.md index 6f0a795ce..e79482b7d 100644 --- a/docs/admin-sdk/api-reference/location.md +++ b/docs/admin-sdk/api-reference/location.md @@ -26,13 +26,13 @@ if (sw.location.is('my-location-id')) { } ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :----------- | :------- | :------ | :----------------------- | | `locationId` | true | | The location ID to check | -### Return value +#### Return value Returns a boolean. It is `true` if the location ID matches the current location. @@ -44,7 +44,7 @@ Get the name of the current location ID: const currentLocation = sw.location.get() ``` -### Return value +#### Return value Returns a string with the name of the current location. @@ -65,11 +65,11 @@ if (location.isIframe()) { ## iFrame heights -### Parameters +#### Parameters No parameters needed. -### Return value +#### Return value Returns a boolean. Returns `true` if executed inside an iFrame. @@ -81,13 +81,13 @@ Update the height of the iFrame with this method: sw.location.updateHeight(750); ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :-------------- | :------- | :------------- | :------------------------------------------------------------------------------------------------------------- | | `iFrame height` | false | Auto generated | The height of the iFrame. If no value is provided it will be automatically calculated from the current height. | -### Return value +#### Return value This method does not have a return value. @@ -101,11 +101,11 @@ This method starts the auto resizer of the iFrame height. sw.location.startAutoResizer(); ``` -### Parameters +#### Parameters No parameters needed. -### Return value +#### Return value This method does not have a return value. @@ -117,11 +117,11 @@ This method stops the auto resizer of the iFrame height: sw.location.stopAutoResizer(); ``` -### Parameters +#### Parameters No parameters needed. -### Return value +#### Return value This method does not have a return value. @@ -144,7 +144,7 @@ const currentUrl = window.location.href; sw.location.updateUrl(new URL(currentUrl)) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :-------------- | :------- | :------ | :------------------------------------ | diff --git a/docs/admin-sdk/api-reference/notification.md b/docs/admin-sdk/api-reference/notification.md index a7bdf6b73..f2496325b 100644 --- a/docs/admin-sdk/api-reference/notification.md +++ b/docs/admin-sdk/api-reference/notification.md @@ -6,7 +6,7 @@ sidebar_position: 50 # Notification -Notifications display persistent messages in the Shopware Administration to inform users about events, errors, or completed actions. +Notifications display messages in the Shopware Administration to inform users about events, errors, or completed actions. They remain visible in the notification center (bell icon) until dismissed by the user. See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. @@ -14,7 +14,7 @@ See also: [Base Options](../api-reference/base-options.md) for shared configurat ![notification example](./assets/notification-example.jpg) -### Usage +#### Usage ```ts function alertYes() { @@ -47,7 +47,7 @@ sw.notification.dispatch({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | |:-------------|:---------|:---------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/admin-sdk/api-reference/toast.md b/docs/admin-sdk/api-reference/toast.md index 6da53e9ec..04db6cbf7 100644 --- a/docs/admin-sdk/api-reference/toast.md +++ b/docs/admin-sdk/api-reference/toast.md @@ -6,7 +6,7 @@ sidebar_position: 60 # Toast -Toasts display short, temporary messages to provide feedback about user actions or system events. +Toasts display short, temporary messages to provide feedback about user actions or system events. Unlike [notifications](./notification.md), which persist in the notification center until dismissed, toasts disappear automatically after a short time. See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. diff --git a/docs/admin-sdk/api-reference/ui/component-sections.md b/docs/admin-sdk/api-reference/ui/component-sections.md index f2c9b20ea..8a89f5012 100644 --- a/docs/admin-sdk/api-reference/ui/component-sections.md +++ b/docs/admin-sdk/api-reference/ui/component-sections.md @@ -28,13 +28,13 @@ ui.componentSection.add({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :---------- | :------- | :------ | :--------------------------------------------- | | `component` | true | | Choose the component which you want to render. | -### Return value +#### Return value This method does not have a return value. diff --git a/docs/admin-sdk/api-reference/ui/mainModule.md b/docs/admin-sdk/api-reference/ui/mainModule.md index 0b3115e0f..865edac8d 100644 --- a/docs/admin-sdk/api-reference/ui/mainModule.md +++ b/docs/admin-sdk/api-reference/ui/mainModule.md @@ -15,7 +15,7 @@ Use a main module when your extension provides a dedicated application area with Add a main module to your extension. The content of the main module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. -### Usage +#### Usage ```ts ui.mainModule.addMainModule({ @@ -24,7 +24,7 @@ ui.mainModule.addMainModule({ }); ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :---------------------- | :------- | :------ | :------------------------------------- | @@ -33,7 +33,7 @@ ui.mainModule.addMainModule({ | `displaySearchBar` | false | true | Toggles the sw-page search bar on/off | | `displayLanguageSwitch` | false | false | Toggles sw-page language switch on/off | -### Example +#### Example ![Main module example](./assets/add-main-module-example.png) @@ -72,7 +72,7 @@ if (location.is('main-location-id')) { Add a button to the smart bar of your main module. The button can be used to trigger actions, e.g. saving, cancel, etc. The location ID needs to be defined and have the same value as the `locationId` of the main module. -### Usage +#### Usage ```ts ui.mainModule.addSmartbarButton({ @@ -84,7 +84,7 @@ ui.mainModule.addSmartbarButton({ }); ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :---------------- | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------ | @@ -99,7 +99,7 @@ ui.mainModule.addSmartbarButton({ Turn the smart bar off as needed. -### Usage +#### Usage ```ts ui.mainModule.hideSmartBar({ @@ -107,7 +107,7 @@ ui.mainModule.hideSmartBar({ }); ``` -### Parameters +#### Parameters | Name | Required | Default | Description | Available at Shopware | | :----------- | :------- | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index 07dbbd82e..32a0dd999 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -16,7 +16,7 @@ This method allows apps to interact with the Administration's media modal. Two m Open the media modal in the current view. -### Usage +#### Usage ```ts ui.mediaModal.open({ @@ -28,7 +28,7 @@ ui.mediaModal.open({ }); ``` -### Parameters +#### Parameters All parameters are similar to `sw-media-modal-v2` component's props @@ -42,7 +42,7 @@ All parameters are similar to `sw-media-modal-v2` component's props | `selectors` | false | ['fileName', 'id', 'url'] | Selected properties which should be returned in callback function | | `callback` | true | | Callback function which will be called once the media item is selected. | -### Example +#### Example ![Menu item example](./assets/media-modal.png) @@ -61,7 +61,7 @@ ui.mediaModal.open({ Open save media modal in the current view. -### Usage +#### Usage ```ts ui.mediaModal.openSaveMedia({ @@ -72,7 +72,7 @@ ui.mediaModal.openSaveMedia({ }); ``` -### Parameters +#### Parameters All parameters are similar to `sw-media-save-modal` component's props @@ -83,7 +83,7 @@ All parameters are similar to `sw-media-save-modal` component's props | `fileType` | false | null | File extension of media to display on file name input's suffix | | `callback` | true | | This callback function is triggered when the "Save media" button is clicked. It returns the updated file name and the folderId where the media is stored. | -### Example +#### Example ![Menu item example](./assets/save-media-modal.png) diff --git a/docs/admin-sdk/api-reference/ui/menu.md b/docs/admin-sdk/api-reference/ui/menu.md index 0cd12d21b..af4d36c24 100644 --- a/docs/admin-sdk/api-reference/ui/menu.md +++ b/docs/admin-sdk/api-reference/ui/menu.md @@ -16,7 +16,7 @@ They are typically used to expose extension functionality inside existing admin The Admin SDK allows you to manipulate the Admin menu of your application. One of the features it provides is the ability to toggle the Admin menu. This is done using the `collapseMenu` and `expandMenu` methods. -### Usage +#### Usage ```ts ui.menu.collapseMenu(); // To collapse the Admin menu; @@ -29,7 +29,7 @@ ui.menu.expandMenu(); // To expand the Admin menu; Add a new menu item to the Shopware admin menu. The content of the menu item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. -### Usage +#### Usage ```ts ui.menu.addMenuItem({ @@ -41,7 +41,7 @@ ui.menu.addMenuItem({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :------------------- | :------- | :------------- | :------------------------------------------------------------ | @@ -52,7 +52,7 @@ ui.menu.addMenuItem({ | `parent` | false | 'sw-extension' | Determines under which main menu entry your item is displayed | | `position` | false | 110 | Determines the position of your menu item | -### Example +#### Example ![Menu item example](./assets/add-menu-item-example.png) diff --git a/docs/admin-sdk/api-reference/ui/modals.md b/docs/admin-sdk/api-reference/ui/modals.md index ac640de8c..8ce286299 100644 --- a/docs/admin-sdk/api-reference/ui/modals.md +++ b/docs/admin-sdk/api-reference/ui/modals.md @@ -19,7 +19,7 @@ See also: [Base Options](../base-options.md) for shared configuration options su Open a new modal in the current view. The content of the modal is determined by your `locationId` or by using plain text with `textContent`. -### Usage +#### Usage ```ts ui.modal.open({ @@ -55,7 +55,7 @@ ui.modal.open({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | Available at Shopware | |:--------------|:---------|:----------|:-----------------------------------------------------------------------------------------------|:----------------------| @@ -68,7 +68,7 @@ ui.modal.open({ | `closable` | false | true | If this is set to `false` then the modal can only be closed programmatically | | | `buttons` | false | [] | This array contains button configurations which will render buttons in the footer of the modal | | -### Example +#### Example ![Menu item example](./assets/modal-example.png) @@ -105,7 +105,7 @@ ui.modal.open({ Updates an existing modal with the given `locationId`. This can be used to modify the modal's properties after it has been opened, such as changing the title, buttons, or visibility of header/footer from inside the modal. -### Usage +#### Usage ```ts ui.modal.update({ @@ -125,7 +125,7 @@ ui.modal.update({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | |:-------------|:---------|:--------|:-----------------------------------------------------------------------------------------------| @@ -140,13 +140,13 @@ ui.modal.update({ Closes an opened modal. You need use the correct `locationId` of the modal which should get closed. If you don't provide a `locationId` the last modal without a `locationId` gets closed. -### Usage +#### Usage ```ts ui.modal.close({ locationId: 'your-location-id' }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | |:-------------|:---------|:--------|:--------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/admin-sdk/api-reference/ui/settingsItem.md b/docs/admin-sdk/api-reference/ui/settingsItem.md index 91849bd3f..af3fb03e2 100644 --- a/docs/admin-sdk/api-reference/ui/settingsItem.md +++ b/docs/admin-sdk/api-reference/ui/settingsItem.md @@ -15,7 +15,7 @@ Use this when your extension provides configurable options that should appear in Add a new settings item to the Shopware settings. The content of the settings item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. -### Usage +#### Usage ```ts ui.settings.addSettingsItem({ @@ -28,7 +28,7 @@ ui.settings.addSettingsItem({ }); ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :------------------- | :------- | :------------- | :------------------------------------------------------------ | @@ -43,7 +43,7 @@ ui.settings.addSettingsItem({ If your editor supports TypeScript, you should get auto-completion when importing icons from the Meteor icon package. To browse available icons, see the [Meteor icon kit repository](https://github.com/shopware/meteor/tree/main/packages/icon-kit). -### Example +#### Example ![Settings item example](./assets/add-settings-item-example.png) diff --git a/docs/admin-sdk/api-reference/ui/sidebars.md b/docs/admin-sdk/api-reference/ui/sidebars.md index 32c171bbd..fc409c94d 100644 --- a/docs/admin-sdk/api-reference/ui/sidebars.md +++ b/docs/admin-sdk/api-reference/ui/sidebars.md @@ -13,7 +13,7 @@ A sidebar provides a contextual panel that displays at the right edge of the Adm Add a new sidebar. The content of the sidebar is determined by your `locationId`. -### Usage +#### Usage ```ts sw.ui.sidebar.add({ @@ -23,7 +23,7 @@ sw.ui.sidebar.add({ }); ``` -### Parameters +#### Parameters | Name | Required | Description | Available at Shopware | | :----------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| @@ -32,7 +32,7 @@ sw.ui.sidebar.add({ | `icon` | true | The icon to display in the sidebar. You can use any icon from the Shopware icon library | 6.7 | | `resizable` | false | Enables horizontal resizing of the sidebar | 6.7.2.0 | -### Example +#### Example ![Menu item example](./assets/sidebar-example.png) @@ -40,7 +40,7 @@ sw.ui.sidebar.add({ Close an existing sidebar programmatically. -### Usage +#### Usage ```ts sw.ui.sidebar.close({ @@ -48,7 +48,7 @@ sw.ui.sidebar.close({ }); ``` -### Parameters +#### Parameters | Name | Required | Description | Available at Shopware | | :----------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| @@ -58,7 +58,7 @@ sw.ui.sidebar.close({ Remove a sidebar completely from the DOM. -### Usage +#### Usage ```ts sw.ui.sidebar.remove({ @@ -66,7 +66,7 @@ sw.ui.sidebar.remove({ }); ``` -### Parameters +#### Parameters | Name | Required | Description | Available at Shopware | | :----------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------| diff --git a/docs/admin-sdk/api-reference/ui/tabs.md b/docs/admin-sdk/api-reference/ui/tabs.md index 64e3c0bd6..91516b921 100644 --- a/docs/admin-sdk/api-reference/ui/tabs.md +++ b/docs/admin-sdk/api-reference/ui/tabs.md @@ -18,7 +18,7 @@ contains a component section. This works with tab bar's which have routing and also static tab bars. If the tab bar has routing then the route for the tab item will be generated automatically. -### Usage +#### Usage ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -29,14 +29,14 @@ ui.tabs('sw-product-detail' /* The positionId of the tab bar*/).addTabItem({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :------------------- | :------- | :------ | :------------------------------------------------------ | | `label` | true | | The label of the tab bar item | | `componentSectionId` | true | | The Id for for the component section in the tab content | -### Example +#### Example ![Tab item example](./assets/add-tab-item-example.png) ```ts diff --git a/docs/admin-sdk/api-reference/window.md b/docs/admin-sdk/api-reference/window.md index ecbbbf811..4db0e93e5 100644 --- a/docs/admin-sdk/api-reference/window.md +++ b/docs/admin-sdk/api-reference/window.md @@ -12,7 +12,7 @@ The Window API provides methods for navigation and window-related utilities insi Redirect to an external URL. -### Usage +#### Usage Use this method to open an external URL either in the current tab or a new tab. @@ -23,14 +23,14 @@ sw.window.redirect({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :------ | :------ | :------ | :------ | | `url` | true | | The URL to open | | `newTab` | false | false | Open the URL in a new browser tab | -### Return value +#### Return value Returns a promise without data. @@ -38,7 +38,7 @@ Returns a promise without data. Navigate to another page inside the Shopware Administration. -### Usage +#### Usage This method mirrors the behavior of Vue Router’s `push()`. @@ -61,7 +61,7 @@ sw.window.routerPush({ }) ``` -### Parameters +#### Parameters | Name | Required | Default | Description | | :------ | :------ | :------ | :------ | @@ -70,7 +70,7 @@ sw.window.routerPush({ | `params` | false | undefined | Additional params for the new route | | `replace` | false | false | Replace current browser history entry | -### Return value +#### Return value Returns a promise without data. @@ -78,17 +78,17 @@ Returns a promise without data. Reload the current Administration page. This can be useful during development or when UI state must be reset. -### Usage +#### Usage ```ts sw.window.reload() ``` -### Parameters +#### Parameters No parameters required. -### Return value +#### Return value Returns a promise without data. @@ -98,21 +98,21 @@ Returns a promise without data. Returns a unique identifier for the current browser window. This is useful when working with session storage or detecting duplicated tabs. -### Usage +#### Usage ```ts sw.window.getId() ``` -### Parameters +#### Parameters No parameters required -### Return value +#### Return value A `string` representing a unique identifier for the current window. -### Example +#### Example This example clears `sessionStorage` when a duplicated browser tab is detected. This can happen if a user uses the *Duplicate Tab* feature of some browsers. @@ -133,16 +133,16 @@ if (windowId !== storedWindowId) { Retrieve the current Administration router path. -### Usage +#### Usage ```ts sw.window.getPath() ``` -### Parameters +#### Parameters No parameters required. -### Return value +#### Return value Returns a `string` containing the full path, or an empty string if the router is not available. From 43ac5c39303fbb0b6ed561ec933136cfe1b608a4 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 15:21:54 +0100 Subject: [PATCH 31/59] docs: add context descriptions, fix develop index, improve toast/notification context.md: - Add overall introduction explaining the Context API - Add brief description to each section (Language, Environment, Locale, etc.) develop/index.md: - Remove broken links to files that live in api-reference/ - Simplify to only reference files that exist in develop/ toast.md: - Explain difference between toasts and notifications notification.md: - Clarify that notifications persist in notification center Made-with: Cursor --- docs/admin-sdk/api-reference/context.md | 28 ++++++++++++++-- docs/admin-sdk/develop/index.md | 43 +++---------------------- 2 files changed, 30 insertions(+), 41 deletions(-) diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index b3407d1a3..6f1034e38 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -6,8 +6,14 @@ sidebar_position: 40 # Context +The Context API provides read access to the current state of the Shopware Administration. Extensions can use these methods to retrieve information about the active language, locale, currency, environment, Shopware version, and more. + +This is useful for adapting extension behavior based on the current Administration context — for example, loading translations for the active language or checking the Shopware version before using a newer API. + ## Language +Retrieve or subscribe to the currently active Administration language. + ### Get current language #### Usage @@ -74,6 +80,8 @@ sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { ## Environment +Check whether the Administration is running in development, production, or testing mode. + ### Get current environment #### Usage @@ -100,6 +108,8 @@ Promise<'development' | 'production' | 'testing'> ## Locale +Retrieve or subscribe to the browser locale used by the Administration UI. + ### Get current locale #### Usage @@ -166,6 +176,8 @@ sw.context.subscribeLocale(({ locale, fallbackLocale }) => { ## Currency +Retrieve the system currency configured for the Shopware instance. + ### Get current currency #### Usage @@ -198,6 +210,8 @@ Promise<{ ## Shopware version +Query the Shopware version to conditionally enable features or check compatibility. + ### Get current Shopware version #### Usage @@ -263,6 +277,8 @@ true ## App information +Retrieve metadata about the current app or plugin, including its name, version, type, and granted privileges. + ### Get app information > The privileges property will be available with Shopware v6.7.1.0 and higher @@ -300,6 +316,8 @@ Promise<{ name: string ; version: string ; type: 'app' | 'plugin', privileges: p ## User information +Access details about the currently logged-in Administration user. + ### Get user information :::caution @@ -361,6 +379,8 @@ Promise<{ ## User Timezone +Retrieve the timezone setting of the currently logged-in user. + ### Get user timezone :::caution @@ -389,6 +409,8 @@ This function returns a Promise that resolves to a string representing the user' ## Module information +Query the list of registered extension modules to navigate between them. + ### Get module information Get information about all registered modules. These modules are created by adding new menu items, setting items, etc. @@ -442,6 +464,8 @@ Promise<{ ## ShopId +Retrieve the unique shop ID used by Shopware's app system. + ### Get the shopId > Available since Shopware v6.7.1.0 @@ -466,9 +490,9 @@ Promise ## Check app's privileges -> Available since Shopware 6.7.1.0 +Check whether a specific privilege is granted for the current app. Useful for conditionally showing features. -This lets you check if a specific privilege is granted for your app +> Available since Shopware 6.7.1.0 #### Usage diff --git a/docs/admin-sdk/develop/index.md b/docs/admin-sdk/develop/index.md index 57dd4efbd..d802152c5 100644 --- a/docs/admin-sdk/develop/index.md +++ b/docs/admin-sdk/develop/index.md @@ -6,48 +6,13 @@ sidebar_position: 30 # Start Developing -This section explains how to build Administration extensions with the Meteor Admin SDK, using core extension capabilities such as UI extension points, composables, and tooling. +This section covers advanced development topics for building Administration extensions with the Meteor Admin SDK. -A typical Administration extension follows this workflow: +For a full overview of available APIs, see the [API Reference](../api-reference/index.md). -1. Identify an extension point in the Administration UI. -2. Add a [main module](../api-reference/ui/mainModule.md) or [action button](../api-reference/ui/actionButton.md) at that [location](./location.md). - - **Location**: Defines where extension code runs inside the Administration UI. - - **Main module**: The entry point of your extension inside the Administration navigation. - - **Action button**: Adds functionality to an existing Administration view, such as the product detail page. -3. Load or modify Shopware data using [repositories](./composables/useRepository.md). -4. Provide feedback to users with [notifications](./notification.md) or [toasts](./toast.md). +## Guides -## Development Tools - -Use the [DevTools](./devtools.md) guide to discover extension points and inspect the Administration UI with Vue DevTools. - -## Extension APIs - -The following APIs allow extensions to interact with and extend the Shopware Administration UI: - -- **[Location](./location.md)**: Determine where your extension is rendered inside the Administration. -- **[Context](./context.md)**: Access information about the current Administration context. -- **[Notification](./notification.md)**: Display notification messages to users. -- **[Toast](./toast.md)**: Show temporary toast messages. -- **[Window](./window.md)**: Interact with browser windows or external links. +- **[DevTools](./devtools.md)**: Discover extension points and inspect the Administration UI with Vue DevTools. - **[Translations](./translations.md)**: Localize extension UI using snippet files and synchronize language changes with the Administration. - -## Composables - -Composables provide reusable helpers for working with Administration data and shared state. - -- **[useRepository](./composables/useRepository.md)**: Access Shopware repositories to load and manipulate entities. -- **[useSharedState](./composables/useSharedState.md)**: Share state between extensions or components. - -## CMS extensions - -The CMS API allows extensions to add new CMS blocks and elements to the Shopware content system. - -- **[Register CMS Block](./cms/registerCmsBlock.md)**: Add custom CMS blocks that structure and group content elements in the Shopping Experiences editor. -- **[Register CMS Element](./cms/registerCmsElement.md)**: Create custom CMS elements that render specific content or functionality inside CMS blocks. - -## Advanced topics - - **[Entity Types](./entity-types.md)**: Configure and extend TypeScript typings for entity access and SDK usage. - **[Migrating Existing Admin Plugins](./migrating-admin-plugins.md)**: Learn how to gradually migrate existing Twig-based Admin plugins to the Meteor Admin SDK. From 321a294f9ad157121d74e71d6874101704f293bf Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 15:23:16 +0100 Subject: [PATCH 32/59] docs: fix broken link in translations.md The context.md file is in api-reference/, not develop/. Fixed relative path to ../api-reference/context.md Made-with: Cursor --- docs/admin-sdk/develop/translations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/develop/translations.md b/docs/admin-sdk/develop/translations.md index 5f3ef2cdd..dc45b4260 100644 --- a/docs/admin-sdk/develop/translations.md +++ b/docs/admin-sdk/develop/translations.md @@ -8,7 +8,7 @@ sidebar_position: 80 Extensions can localize text displayed in the Shopware Administration using snippet files and a frontend translation library. -For content rendered inside your extension UI, you can use any translation solution supported by your frontend framework (for example, the Vue i18n plugin). To keep translations synchronized with the Administration language, listen for language changes using the [Context API](./context.md#subscribe-on-language-changes). +For content rendered inside your extension UI, you can use any translation solution supported by your frontend framework (for example, the Vue i18n plugin). To keep translations synchronized with the Administration language, listen for language changes using the [Context API](../api-reference/context.md#subscribe-on-language-changes). For text rendered [inside](../concepts/locations.md) native Administration UI components (such as titles inside [component sections](../concepts/component-sections.md)), Shopware supports snippet files inside the app. From b1ee1865564dbc4f15f4da27a6c2f4589dfd3d09 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 18:09:26 +0100 Subject: [PATCH 33/59] docs: address review feedback on previous changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit useRepository.md: - Re-add getRepository in "How it works" with code example context.md: - Use method-style headings (context.getLanguage(), etc.) - Remove sw. prefix from all code examples - Remove outdated caution on getUserInformation (available since v6.4.9.0) - Change getUserTimezone caution to "Available since Shopware v6.6.2.0" - Change getAppInformation privileges note to "available since" - Add parameters table to context.can() location.md: - Remove outdated caution about URL change feature not being implemented actionButton.md: - Change future-tense "will be available" to "Available since" for meteorIcon and fileTypes Normalize "Available since" formatting: - toast.md: info block → blockquote format - in-app-purchases.md: plain text → blockquote format - All standalone availability notes now use `> Available since Shopware vX.Y.Z` - Table-embedded and inline availability notes left as-is installation-apps.md: - Add npm install + npm run dev to scaffold command - Clarify Docker tip: host.docker.internal for registrationUrl/webhooks only - Add Docker reminder in manifest section - Use port 3000 as default, host.docker.internal for registrationUrl installation-plugins.md: - Replace
spoilers with :::caution blocks for better visibility - Change bin/watch-administration.sh to composer watch:admin - Improve info box wording Made-with: Cursor --- .../composables/useRepository.md | 19 +++- docs/admin-sdk/api-reference/context.md | 94 +++++++++---------- .../api-reference/data/in-app-purchases.md | 2 +- docs/admin-sdk/api-reference/location.md | 6 +- docs/admin-sdk/api-reference/toast.md | 4 +- .../api-reference/ui/actionButton.md | 4 +- .../getting-started/installation-apps.md | 20 +++- .../getting-started/installation-plugins.md | 26 +++-- 8 files changed, 92 insertions(+), 83 deletions(-) diff --git a/docs/admin-sdk/api-reference/composables/useRepository.md b/docs/admin-sdk/api-reference/composables/useRepository.md index 9588ad2c6..7a56a5468 100644 --- a/docs/admin-sdk/api-reference/composables/useRepository.md +++ b/docs/admin-sdk/api-reference/composables/useRepository.md @@ -56,7 +56,20 @@ A computed ref containing a repository that updates when its dependencies change ## How it works -`useRepository` uses Vue's `computed` to automatically recreate the repository when its inputs change. This follows Vue's composition API conventions, where composables prefixed with "use" provide reactive wrappers. +Under the hood, `useRepository` wraps `getRepository` inside a Vue `computed`, so the repository is recreated whenever the inputs change: -- It provides the full repository interface (search, get, save, delete, etc.) -- It adds reactivity, automatically updating when inputs change +```ts +import { computed, unref } from 'vue'; +import { composables } from '@shopware-ag/meteor-admin-sdk'; +const { getRepository } = composables; + +function useRepository(entityNameRef, factoryRef) { + return computed(() => { + return getRepository(unref(entityNameRef), unref(factoryRef)); + }); +} +``` + +- `getRepository(entityName, factory?)` returns a static repository instance for the given entity +- `useRepository` adds reactivity on top, automatically updating when inputs change +- Both provide the full repository interface (search, get, save, delete, etc.) diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index 6f1034e38..e8183cc21 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -14,12 +14,12 @@ This is useful for adapting extension behavior based on the current Administrati Retrieve or subscribe to the currently active Administration language. -### Get current language +### context.getLanguage() #### Usage ```ts -const language = await sw.context.getLanguage(); +const language = await context.getLanguage(); ``` #### Parameters @@ -44,12 +44,12 @@ Promise<{ } ``` -### Subscribe on language changes +### context.subscribeLanguage() #### Usage ```ts -sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { +context.subscribeLanguage(({ languageId, systemLanguageId }) => { // do something with the callback data }); ``` @@ -82,12 +82,12 @@ sw.context.subscribeLanguage(({ languageId, systemLanguageId }) => { Check whether the Administration is running in development, production, or testing mode. -### Get current environment +### context.getEnvironment() #### Usage ```ts -const environment = await sw.context.getEnvironment(); +const environment = await context.getEnvironment(); ``` #### Parameters @@ -110,12 +110,12 @@ Promise<'development' | 'production' | 'testing'> Retrieve or subscribe to the browser locale used by the Administration UI. -### Get current locale +### context.getLocale() #### Usage ```ts -const locale = await sw.context.getLocale(); +const locale = await context.getLocale(); ``` #### Parameters @@ -140,12 +140,12 @@ Promise<{ } ``` -### Subscribe on locale changes +### context.subscribeLocale() #### Usage ```ts -sw.context.subscribeLocale(({ locale, fallbackLocale }) => { +context.subscribeLocale(({ locale, fallbackLocale }) => { // do something with the callback data }); ``` @@ -178,12 +178,12 @@ sw.context.subscribeLocale(({ locale, fallbackLocale }) => { Retrieve the system currency configured for the Shopware instance. -### Get current currency +### context.getCurrency() #### Usage ```ts -const currency = await sw.context.getCurrency(); +const currency = await context.getCurrency(); ``` #### Parameters @@ -212,12 +212,12 @@ Promise<{ Query the Shopware version to conditionally enable features or check compatibility. -### Get current Shopware version +### context.getShopwareVersion() #### Usage ```ts -const shopwareVersion = await sw.context.getShopwareVersion(); +const shopwareVersion = await context.getShopwareVersion(); ``` #### Parameters @@ -236,16 +236,16 @@ string '6.4.0.0' ``` -### Compare current Shopware version with a given version +### context.compareShopwareVersion() -In many cases you have to make sure that the shop you are communicating with has a certain Shopware version. For this purpose the Meteor Admin SDK provides the `context.compareIsShopwareVersion` function. +In many cases you have to make sure that the shop you are communicating with has a certain Shopware version. For this purpose the Meteor Admin SDK provides the `context.compareShopwareVersion` function. -The function always treats the current Shopware version of a shop as the left hand operator of the comparison. That means a call like `context.compareIsShopwareVersion('>=', '7.0.0')` can be read as "*Compare: is Shopware version equal or greater than 7.0.0*" +The function always treats the current Shopware version of a shop as the left hand operator of the comparison. That means a call like `context.compareShopwareVersion('>=', '7.0.0')` can be read as "*Compare: is Shopware version equal or greater than 7.0.0*" #### Usage ```ts -const isRightVersion = await sw.context.compareShopwareVersion('>=', '7.0.0') +const isRightVersion = await context.compareShopwareVersion('>=', '7.0.0') ``` #### Parameters @@ -255,13 +255,12 @@ const isRightVersion = await sw.context.compareShopwareVersion('>=', '7.0.0') | `comparator` | The operator to compare. Possible values: `'='` `'!='` `'>'` `'<'` `'<='` `'>='`| | `version` | The string with the version to compare - -The function supports both, Shopware's four-digit version number and semver versions. The following calls are equivalent: +The function supports both Shopware's four-digit version number and semver versions. The following calls are equivalent: ```ts -await sw.context.compareShopwareVersion('>=', '6.6.4.0'); +await context.compareShopwareVersion('>=', '6.6.4.0'); -await sw.context.compareShopwareVersion('>=', '6.4.0'); +await context.compareShopwareVersion('>=', '6.4.0'); ``` #### Return value @@ -279,14 +278,14 @@ true Retrieve metadata about the current app or plugin, including its name, version, type, and granted privileges. -### Get app information +### context.getAppInformation() -> The privileges property will be available with Shopware v6.7.1.0 and higher +> The `privileges` property is available since Shopware v6.7.1.0. #### Usage ```ts -const { name, version, type, privileges } = await sw.context.getAppInformation(); +const { name, version, type, privileges } = await context.getAppInformation(); ``` #### Parameters @@ -318,16 +317,14 @@ Promise<{ name: string ; version: string ; type: 'app' | 'plugin', privileges: p Access details about the currently logged-in Administration user. -### Get user information +### context.getUserInformation() -:::caution -Do not use this feature yet. It is not implemented in a Shopware release yet. -::: +> Available since Shopware v6.4.9.0 #### Usage ```ts -const userInformation = await sw.context.getUserInformation(); +const userInformation = await context.getUserInformation(); ``` #### Parameters @@ -381,18 +378,14 @@ Promise<{ Retrieve the timezone setting of the currently logged-in user. -### Get user timezone - -:::caution -This feature will be available with Shopware ^6.6.2.0 -::: +### context.getUserTimezone() -This feature allows you to get the timezone of the user. +> Available since Shopware v6.6.2.0 #### Usage ```ts -const userTimezone = await sw.context.getUserTimezone(); +const userTimezone = await context.getUserTimezone(); ``` #### Parameters @@ -411,7 +404,7 @@ This function returns a Promise that resolves to a string representing the user' Query the list of registered extension modules to navigate between them. -### Get module information +### context.getModuleInformation() Get information about all registered modules. These modules are created by adding new menu items, setting items, etc. @@ -420,12 +413,12 @@ The ID can be used to change the current route to the module. #### Usage ```ts -const { modules } = await sw.context.getModuleInformation(); +const { modules } = await context.getModuleInformation(); -sw.window.routerPush({ +window.routerPush({ name: 'sw.extension.sdk.index', params: { - id: modules[0].id // get the ID of the wanted module + id: modules[0].id } }) ``` @@ -466,21 +459,19 @@ Promise<{ Retrieve the unique shop ID used by Shopware's app system. -### Get the shopId +### context.getShopId() > Available since Shopware v6.7.1.0 -Get the shop's shop-id used by Shopware's app system - #### Usage ```ts -const shopId = await sw.context.getShopId(); +const shopId = await context.getShopId(); ``` #### Parameters -no parameters needed +No parameters needed. #### Return value @@ -492,16 +483,21 @@ Promise Check whether a specific privilege is granted for the current app. Useful for conditionally showing features. -> Available since Shopware 6.7.1.0 +### context.can() + +> Available since Shopware v6.7.1.0 #### Usage ```ts -const isAllowed: boolean = await sw.context.can('product:read'); +const isAllowed: boolean = await context.can('product:read'); ``` #### Parameters -No parameters needed. + +| Name | Description | +|:------------|:-------------------------------------------------| +| `privilege` | The privilege string to check, e.g. `'product:read'` | #### Return value diff --git a/docs/admin-sdk/api-reference/data/in-app-purchases.md b/docs/admin-sdk/api-reference/data/in-app-purchases.md index e27a438a8..b12765297 100644 --- a/docs/admin-sdk/api-reference/data/in-app-purchases.md +++ b/docs/admin-sdk/api-reference/data/in-app-purchases.md @@ -7,7 +7,7 @@ nav: # In-App Purchases -Available since Shopware v6.6.9.0. +> Available since Shopware v6.6.9.0 In-App purchases allow apps to unlock different functionality based on purchases made by the user. This guide covers how to start the in-app purchase flow directly from the Administration. diff --git a/docs/admin-sdk/api-reference/location.md b/docs/admin-sdk/api-reference/location.md index e79482b7d..e630d67e4 100644 --- a/docs/admin-sdk/api-reference/location.md +++ b/docs/admin-sdk/api-reference/location.md @@ -127,11 +127,7 @@ This method does not have a return value. ## URL changes inside your app -:::caution -Do not use this feature yet. It is not implemented in a Shopware release yet. -::: - -Important: You can track and emit your URL changes only inside your own main module or settings page. +You can track and emit your URL changes only inside your own main module or settings page. ### Update URL diff --git a/docs/admin-sdk/api-reference/toast.md b/docs/admin-sdk/api-reference/toast.md index 04db6cbf7..874079eef 100644 --- a/docs/admin-sdk/api-reference/toast.md +++ b/docs/admin-sdk/api-reference/toast.md @@ -10,9 +10,7 @@ Toasts display short, temporary messages to provide feedback about user actions See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. -:::info Availability -This feature is available since Shopware 6.6.2.0. -::: +> Available since Shopware v6.6.2.0 ## Dispatch a toast diff --git a/docs/admin-sdk/api-reference/ui/actionButton.md b/docs/admin-sdk/api-reference/ui/actionButton.md index 1d8eb94da..55d5096be 100644 --- a/docs/admin-sdk/api-reference/ui/actionButton.md +++ b/docs/admin-sdk/api-reference/ui/actionButton.md @@ -37,8 +37,8 @@ if (location.is(sw.location.MAIN_HIDDEN)) { | `entity` | true | The entity this action is for possible values: `product`, `order`, `category`, `promotion`, `customer` or `media`. Value `media` is available in Shopware version 6.7.1 | | `view` | true | Determines if the action button appears on the listing or detail page, possible values: `detail`,`list` or item. View `item` is only used for entity `media` and in version 6.7.1 | | `label` | true | The label of your action button | -| `meteorIcon` | false | Meteor icon before label, will be available in Shopware version 6.7.4.0 . Check icon name on https://developer.shopware.com/resources/meteor-icon-kit/ | -| `fileTypes` | false | Media file types you want the action button to be displayed for. Will be available in Shopware version 6.7.6. | +| `meteorIcon` | false | Meteor icon before label. Available since Shopware v6.7.4.0. Check icon name on https://developer.shopware.com/resources/meteor-icon-kit/ | +| `fileTypes` | false | Media file types you want the action button to be displayed for. Available since Shopware v6.7.6.0. | | `callback` | true | The callback function where you receive the entity and the entityIds for further processing | ## Calling app actions diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index 9e2ba8270..4892167a6 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -28,7 +28,7 @@ Each app must expose its own publicly reachable URL for registration and webhook :::tip For local development, you don't need a public URL yet. You can use `localhost` or a tunneling service like ngrok. -If your Shopware instance runs inside Docker, use `host.docker.internal:PORT` instead of `localhost:PORT` to reach the app server from inside the container. +If your Shopware instance runs inside Docker, use `host.docker.internal:PORT` instead of `localhost:PORT` for the `registrationUrl` and webhook URLs so Shopware can reach your app server from inside the container. The `base-app-url` does **not** need this — it is loaded by the browser, not by the Shopware server. ::: ## Backend requirement @@ -44,8 +44,13 @@ Shopware also provides SDKs for other languages. See the [full list of official To scaffold a new app using the App Server SDK: ```bash +# scaffold the example app npx tiged shopware/app-sdk-js/examples/node-hono demo-app cd demo-app + +# install dependencies and start the dev server +npm install +npm run dev ``` Visit [the App Server SDK guide](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/javascript/01-getting_started.html) for detailed instructions. @@ -114,7 +119,11 @@ After the registration handshake is working, add the `` field insi As required by Shopware's app system, the `` section must already contain the `registrationUrl` and `secret`. -For an example, the `manifest.xml` of an app whose HTML page is served under `http://localhost/my-example-app.html` would look like this: +:::tip Docker reminder +Remember: the `registrationUrl` must be reachable by the Shopware server. If Shopware runs in Docker, use `host.docker.internal` for that URL. The `base-app-url` is loaded by the browser, so `localhost` works fine there. +::: + +Example `manifest.xml` for a local dev setup (app server running on port 3000): ```xml @@ -125,13 +134,14 @@ For an example, the `manifest.xml` of an app whose HTML page is served under `ht - http://link-to-your-local-app-server/register + + http://host.docker.internal:3000/register S3cr3tf0re$t - - http://localhost/my-example-app.html + + http://localhost:3000/my-example-app.html ``` diff --git a/docs/admin-sdk/getting-started/installation-plugins.md b/docs/admin-sdk/getting-started/installation-plugins.md index 91c95b0ca..879f13fa0 100644 --- a/docs/admin-sdk/getting-started/installation-plugins.md +++ b/docs/admin-sdk/getting-started/installation-plugins.md @@ -9,22 +9,19 @@ sidebar_position: 30 Plugins are supported on self-hosted Shopware instances only. :::info -The setup process is slightly different for **Shopware instances below version 6.7**. Look out for spoilers that explain what's different. +This guide assumes **Shopware 6.7 or later**. Shopware 6.7 introduced a new extension architecture (`meteor-app`) with modern frontend build tooling. If you are running an older version, differences are noted inline. ::: ### 1. Create the administration entry Create the folder `custom/plugins/yourPluginName/src/Resources/app/meteor-app`. This is the base path for all new files for your extension. -
- If your shopware instance runs a version below 6.7 - Use the path `custom/plugins/yourPluginName/src/Resources/app/administration` instead -
+:::caution Shopware below 6.7 +Use the path `custom/plugins/yourPluginName/src/Resources/app/administration` instead. +::: ### 2. Install the SDK -Then install the SDK - ```bash cd custom/plugins/yourPluginName/src/Resources/app/meteor-app npm install @shopware-ag/meteor-admin-sdk @@ -51,10 +48,9 @@ Then create a JavaScript file in the subfolder `src/main.js` and reference it in ``` -
- If your shopware instance runs a version below 6.7 - Leave out <script type="module" src="/src/main.js"></script> since it's injected automatically. -
+:::caution Shopware below 6.7 +Leave out `` — it is injected automatically in older versions. +::: In `src/main.js`, add a quick test to verify the SDK works: @@ -67,7 +63,7 @@ notification.dispatch({ }); ``` -### 4. Installing the plugin +### 4. Install the plugin ```bash # if you are using Docker, run the following commands inside the container: docker compose exec -it web /bin/bash @@ -75,12 +71,12 @@ bin/console plugin:install --activate yourPluginName bin/console cache:clear ``` -### 5. Bundling the plugin +### 5. Build and watch -You don't need to set up Vite (the bundler) on your own — Shopware already takes care of that. Run the Administration watcher to rebuild the frontend bundle: +You don't need to set up Vite on your own — Shopware already takes care of bundling. Run the Administration watcher to rebuild the frontend: ```bash -bin/watch-administration.sh +composer watch:admin ``` Wait until the compilation finishes successfully. From 259a93264d8bfc35562c0973d20f2cd329a5e4ff Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 18:43:56 +0100 Subject: [PATCH 34/59] docs: add getRepository docs, fix window import, add location availability composables/getRepository.md: - New page documenting the getRepository composable - Includes usage, custom factory, parameters, return value composables/index.md, api-reference/index.md: - Add getRepository to composables listing context.md: - Fix window shadowing: import window as swWindow from SDK location.md: - Add "Available since Shopware v6.6.8.0" to URL changes section Made-with: Cursor --- .../composables/getRepository.md | 53 +++++++++++++++++++ .../api-reference/composables/index.md | 5 +- docs/admin-sdk/api-reference/context.md | 4 +- docs/admin-sdk/api-reference/index.md | 1 + docs/admin-sdk/api-reference/location.md | 2 + 5 files changed, 62 insertions(+), 3 deletions(-) create mode 100644 docs/admin-sdk/api-reference/composables/getRepository.md diff --git a/docs/admin-sdk/api-reference/composables/getRepository.md b/docs/admin-sdk/api-reference/composables/getRepository.md new file mode 100644 index 000000000..cc2dfaae8 --- /dev/null +++ b/docs/admin-sdk/api-reference/composables/getRepository.md @@ -0,0 +1,53 @@ +--- +title: "getRepository" +nav: + position: 10 +--- + + +# getRepository + +The `composables.getRepository` function returns a static repository instance for a given entity. It provides the same repository interface as the [data.repository](../data/repository.md) API, but as a composable that can be called directly inside Vue component setup functions. + +When called inside a Vue component, `getRepository` first checks for an injected `repositoryFactory` (provided by the Administration host). If none is found, it falls back to a lazy-loaded SDK repository that communicates with the Administration via postMessage. + +For a reactive variant that automatically updates when its inputs change, see [useRepository](./useRepository.md). + +## Usage + +```ts +import { composables } from '@shopware-ag/meteor-admin-sdk'; +const { getRepository } = composables; + +const productRepository = getRepository('product'); + +// Search for products +const products = await productRepository.search(criteria); + +// Get a single product +const product = await productRepository.get('some-product-id'); + +// Save changes +await productRepository.save(product); +``` + +## With a custom repository factory + +If you need to provide your own repository factory (for example in tests or custom setups), pass it as the second argument: + +```ts +const productRepository = getRepository('product', (entityName) => { + return myCustomFactory.create(entityName); +}); +``` + +## Parameters + +| Name | Required | Description | +|:--------------------|:---------|:-----------------------------------------------------------------------------------------| +| `entityName` | true | The name of the entity type (e.g. `'product'`, `'category'`, `'order'`) | +| `repositoryFactory` | false | Optional factory function that creates the underlying repository for the given entity | + +## Return value + +A repository instance with the same methods as described in the [Repository API reference](../data/repository.md): `search`, `get`, `save`, `clone`, `hasChanges`, `saveAll`, `delete`, `create`. diff --git a/docs/admin-sdk/api-reference/composables/index.md b/docs/admin-sdk/api-reference/composables/index.md index 436b7a0bf..cd1af5778 100644 --- a/docs/admin-sdk/api-reference/composables/index.md +++ b/docs/admin-sdk/api-reference/composables/index.md @@ -11,7 +11,8 @@ Composable APIs provide reusable Vue Composables for working with the Shopware A They simplify common tasks such as accessing repositories or sharing reactive state between different parts of an extension. -Currently, the SDK exposes two composables: +Currently, the SDK exposes: -- [useRepository](./useRepository.md): Access Shopware entity repositories to load and manipulate data. +- [getRepository](./getRepository.md): Create a static repository instance for a given entity. +- [useRepository](./useRepository.md): Reactive wrapper around `getRepository` that updates when its inputs change. - [useSharedState](./useSharedState.md): Share reactive state between different extension components. diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index e8183cc21..a3bc94aad 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -413,9 +413,11 @@ The ID can be used to change the current route to the module. #### Usage ```ts +import { window as swWindow } from '@shopware-ag/meteor-admin-sdk'; + const { modules } = await context.getModuleInformation(); -window.routerPush({ +swWindow.routerPush({ name: 'sw.extension.sdk.index', params: { id: modules[0].id diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index 3d46b3830..ce2c0880a 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -65,6 +65,7 @@ They simplify common patterns such as accessing repositories or sharing state be APIs in this section include: +- [getRepository](./composables/getRepository.md) - [useRepository](./composables/useRepository.md) - [useSharedState](./composables/useSharedState.md) diff --git a/docs/admin-sdk/api-reference/location.md b/docs/admin-sdk/api-reference/location.md index e630d67e4..dc1d67e46 100644 --- a/docs/admin-sdk/api-reference/location.md +++ b/docs/admin-sdk/api-reference/location.md @@ -127,6 +127,8 @@ This method does not have a return value. ## URL changes inside your app +> Available since Shopware v6.6.8.0 + You can track and emit your URL changes only inside your own main module or settings page. ### Update URL From 01928f3cda408385a89143544783284943b0f054 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 19:18:27 +0100 Subject: [PATCH 35/59] docs: resolve discussions and open questions from PR review - Add docs.yml redirect map for all moved/renamed files and AGENTS.md - Restructure ui/index.md to unordered scenario sections, remove MCL line - Rewrite base-options.md with full privileges section and examples - Move in-app-purchases and paymentOverviewCard to ui/purchases-and-payments - Simplify concepts/locations.md intro per reviewer suggestion - Add selector syntax reference to concepts/selectors.md - Cross-reference concepts/component-sections.md with API reference - Update api-reference/index.md and data/index.md after file moves Made-with: Cursor --- docs/AGENTS.md | 3 + docs/admin-sdk/api-reference/base-options.md | 80 ++++++++++++++++--- docs/admin-sdk/api-reference/data/index.md | 1 - docs/admin-sdk/api-reference/index.md | 7 +- docs/admin-sdk/api-reference/ui/index.md | 36 +++------ .../in-app-purchases.md | 6 +- .../ui/purchases-and-payments/index.md | 13 +++ .../paymentOverviewCard.md | 12 +-- docs/admin-sdk/concepts/component-sections.md | 57 ++----------- docs/admin-sdk/concepts/locations.md | 66 +++++---------- docs/admin-sdk/concepts/selectors.md | 23 ++++++ docs/admin-sdk/docs.yml | 17 ++++ 12 files changed, 179 insertions(+), 142 deletions(-) create mode 100644 docs/AGENTS.md rename docs/admin-sdk/api-reference/{data => ui/purchases-and-payments}/in-app-purchases.md (90%) create mode 100644 docs/admin-sdk/api-reference/ui/purchases-and-payments/index.md rename docs/admin-sdk/api-reference/ui/{ => purchases-and-payments}/paymentOverviewCard.md (90%) create mode 100644 docs/admin-sdk/docs.yml diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 000000000..219697b51 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,3 @@ +# Agent Guidelines + +When renaming or moving documentation files under `docs/admin-sdk/`, add redirect entries to `docs/admin-sdk/docs.yml` mapping old `.html` paths to new ones so the developer portal preserves external links. diff --git a/docs/admin-sdk/api-reference/base-options.md b/docs/admin-sdk/api-reference/base-options.md index f92acd8e7..ee5a9e740 100644 --- a/docs/admin-sdk/api-reference/base-options.md +++ b/docs/admin-sdk/api-reference/base-options.md @@ -1,21 +1,83 @@ # Base Options -These options are supported by multiple SDK APIs and modify how messages are executed in the Shopware Administration. +Base options are shared configuration options that can be passed to most SDK methods. They are provided as additional properties alongside the method's own parameters. -| Name | Required | Default | Availability | Description | -| :----------- | :------- | :------------- | :------------------ | :---------------------------------------------------------------------------------------------- | -| `privileges` | false | | >= Shopware 6.6.3.0 | The privileges that will be checked before executing the message in the Shopware Administration | +More options may be added in the future. Currently, the following option is available: -## Example privileges +| Name | Required | Default | Availability | Description | +| :----------- | :------- | :------ | :------------------ | :----------------------------------------------------------------------------------------- | +| `privileges` | false | | >= Shopware 6.6.3.0 | Check the current user's privileges before executing the action. See [Privileges](#privileges). | -```typescript -import * as sw from '@shopware-ag/meteor-admin-sdk'; +```ts +import { notification } from '@shopware-ag/meteor-admin-sdk'; -// This notification will only be displayed if the user has `product:read` permissions. -sw.notification.dispatch({ +notification.dispatch({ message: 'Your product report is ready', privileges: [ 'product:read', ], }); ``` + +In this example, the notification is only dispatched if the current Administration user has `product:read` permission. + +## Privileges + +The `privileges` option accepts an array of privilege strings. When provided, the SDK checks whether the current Administration user holds all listed privileges before executing the action. If any privilege is missing, the action is silently skipped. + +:::caution Not a security feature +Privilege checks happen client-side in the browser. They prevent UI elements from appearing for users who lack the required permissions, but they do not enforce access control on the server. Server-side authorization is still required for any sensitive operation. +::: + +#### Privilege string format + +Each privilege string follows the pattern `action:entity`: + +``` +'product:read' +'order:update' +'category:create' +'customer:delete' +``` + +Available actions: + +| Action | Description | +| :----------- | :----------------------------------- | +| `read` | Read access to the entity | +| `create` | Permission to create new entities | +| `update` | Permission to modify existing entities | +| `delete` | Permission to remove entities | +| `additional` | Custom additional privileges | + +#### Usage + +Pass the `privileges` array to any SDK method that supports base options: + +```ts +import { notification, ui } from '@shopware-ag/meteor-admin-sdk'; + +notification.dispatch({ + message: 'Your product report is ready', + privileges: [ + 'product:read', + ], +}); + +ui.actionButton.add({ + action: 'generate-report', + entity: 'product', + view: 'detail', + label: 'Generate Report', + privileges: [ + 'product:read', + 'order:read', + ], +}); +``` + +#### Parameters + +| Name | Type | Required | Description | +| :----------- | :--------- | :------- | :-------------------------------------------------------------------------- | +| `privileges` | `string[]` | false | Array of `action:entity` strings. All must match for the action to execute. | diff --git a/docs/admin-sdk/api-reference/data/index.md b/docs/admin-sdk/api-reference/data/index.md index 3d8ae83df..5008fb911 100644 --- a/docs/admin-sdk/api-reference/data/index.md +++ b/docs/admin-sdk/api-reference/data/index.md @@ -22,4 +22,3 @@ Typical data workflows follow this pattern: - [Get](./get.md): Retrieve entity data from the Administration data layer. - [Subscribe](./subscribe.md): React to changes in entity data. - [Update](./update.md): Modify and persist entity data. -- [In-App Purchases](./in-app-purchases.md): Work with Shopware in-app purchase functionality. diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index ce2c0880a..04bf7593d 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -34,7 +34,11 @@ UI extension components in this section include: - [Sidebars](./ui/sidebars.md) - [Modals](./ui/modals.md) - [Media Modal](./ui/mediaModal.md) -- [Payment Overview Card](./ui/paymentOverviewCard.md) + +**Purchases and payments** + +- [In-App Purchases](./ui/purchases-and-payments/in-app-purchases.md): Start an in-app purchase flow +- [Payment Overview Card](./ui/purchases-and-payments/paymentOverviewCard.md): Customize payment method cards ## Working with Data @@ -55,7 +59,6 @@ Tools this section include: - [Get](./data/get.md) - [Subscribe](./data/subscribe.md) - [Update](./data/update.md) -- [Trigger an In-App Purchase](./data/in-app-purchases.md) ## Composable APIs diff --git a/docs/admin-sdk/api-reference/ui/index.md b/docs/admin-sdk/api-reference/ui/index.md index d60bdce71..b5a7e96f5 100644 --- a/docs/admin-sdk/api-reference/ui/index.md +++ b/docs/admin-sdk/api-reference/ui/index.md @@ -15,32 +15,22 @@ The following guides cover common UI extension patterns. ## Using UI components -Shopware Administration components cannot be used directly inside apps or plugins. Instead, extensions should use the [Meteor Component Library](https://github.com/shopware/meteor/tree/main/packages/component-library) to achieve a native look and feel. +Extensions should use the [Meteor Component Library](https://github.com/shopware/meteor/tree/main/packages/component-library) to build their UI. It provides Vue components designed to match the Administration look and feel and integrate seamlessly with the Meteor Admin SDK. -Shopware Administration components are not native Vue components. They rely on internal extension capabilities, Twig templates, and framework integrations that are not available externally. +## Adding new pages and navigation -The Meteor Component Library provides Vue components designed to resemble the original Administration UI and integrate seamlessly with extensions built using the Meteor Admin SDK. +- [Main Module](./mainModule.md): Add a dedicated app area in the Administration +- [Menu](./menu.md): Add navigation entries to the sidebar +- [Settings Item](./settingsItem.md): Place configuration inside the Administration settings -## Typical UI extension workflow +## Extending existing views -A typical UI extension workflow often follows this progression. +- [Tabs](./tabs.md): Add tabs to entity detail pages such as products, customers, or orders +- [Component Sections](./component-sections.md): Inject custom components into extension points +- [Sidebars](./sidebars.md): Display additional contextual information -1. Create a new module: Use a [Main Module](./mainModule.md) when your extension needs a dedicated application area in the Administration. +## Actions and dialogs -2. Expose the module in navigation: Add a [Menu](./menu.md) entry so users can access your extension. - -3. Add configuration options: Use a [Settings Item](./settingsItem.md) to place configuration inside the Administration settings. - -4. Add interactive actions: Use an [Action Button](./actionButton.md) to trigger extension functionality from existing pages. - -5. Extend existing views: Add [Tabs](./tabs.md) to entity detail pages such as products, customers, or orders. - -6. Render custom UI inside existing views: Use [Component Sections](./component-sections.md) to add components to extension points. - -7. Provide contextual UI: Use [Sidebars](./sidebars.md) to display additional contextual information. - -8. Open dialogs and workflows: Use [Modals](./modals.md) for confirmations, forms, or multi-step workflows. - -9. Work with media: Use the [Media Modal](./mediaModal.md) to allow users to select or manage media assets. - -10. Extend specialized interfaces: Use a [Payment Overview Card](./paymentOverviewCard.md) to customize how payment methods appear in the Administration. +- [Action Button](./actionButton.md): Trigger extension functionality from existing pages +- [Modals](./modals.md): Confirmations, forms, or multi-step workflows +- [Media Modal](./mediaModal.md): Select or manage media assets diff --git a/docs/admin-sdk/api-reference/data/in-app-purchases.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md similarity index 90% rename from docs/admin-sdk/api-reference/data/in-app-purchases.md rename to docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md index b12765297..1bcd06751 100644 --- a/docs/admin-sdk/api-reference/data/in-app-purchases.md +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md @@ -1,7 +1,7 @@ --- title: "In-App Purchases" nav: - position: 60 + position: 10 --- @@ -16,7 +16,9 @@ In-App purchases allow apps to unlock different functionality based on purchases To open a modal with details about the feature that can be purchased: ```ts -sw.iap.purchase({ +import { iap } from '@shopware-ag/meteor-admin-sdk'; + +iap.purchase({ identifier: 'your-in-app-purchase-id', }); ``` diff --git a/docs/admin-sdk/api-reference/ui/purchases-and-payments/index.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/index.md new file mode 100644 index 000000000..025f1cfc8 --- /dev/null +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/index.md @@ -0,0 +1,13 @@ +--- +title: "Purchases and Payments" +nav: + position: 120 +--- + + +# Purchases and Payments + +These APIs allow extensions to integrate purchasing flows and customize how payment methods appear in the Shopware Administration. + +- [In-App Purchases](./in-app-purchases.md): Start an in-app purchase flow from the Administration +- [Payment Overview Cards](./paymentOverviewCard.md): Customize how payment methods appear in the payment overview diff --git a/docs/admin-sdk/api-reference/ui/paymentOverviewCard.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md similarity index 90% rename from docs/admin-sdk/api-reference/ui/paymentOverviewCard.md rename to docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md index 89fa0db2b..4d1a9fc40 100644 --- a/docs/admin-sdk/api-reference/ui/paymentOverviewCard.md +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md @@ -1,7 +1,7 @@ --- title: "Payment Overview Cards" nav: - position: 110 + position: 20 --- @@ -24,20 +24,17 @@ For example, you might require merchants to complete an onboarding process with ## Extension example ```ts -import { ui } from '@shopware-ag/meteor-admin-sdk'; +import { ui, location } from '@shopware-ag/meteor-admin-sdk'; -if (sw.location.is(sw.location.MAIN_HIDDEN)) { - // create the position +if (location.is(location.MAIN_HIDDEN)) { ui.module.payment.overviewCard.add({ positionId: 'my-custom-payment-overview-position', paymentMethodHandlers: [ 'handler_my_custom_payment_method_one', 'handler_my_custom_payment_method_two', - // ... ], }); - // add your component to that position ui.componentSection.add({ component: 'card', positionId: 'my-custom-payment-overview-position', @@ -49,8 +46,7 @@ if (sw.location.is(sw.location.MAIN_HIDDEN)) { }) } -// render your view to that location -if (sw.location.is('my-custom-payment-overview-position-before')) { +if (location.is('my-custom-payment-overview-position-before')) { // your content here } ``` diff --git a/docs/admin-sdk/concepts/component-sections.md b/docs/admin-sdk/concepts/component-sections.md index 2ddbea928..e52306a91 100644 --- a/docs/admin-sdk/concepts/component-sections.md +++ b/docs/admin-sdk/concepts/component-sections.md @@ -18,71 +18,28 @@ Component sections are prebuilt (like cards) and usually work together with: ## Example +This example adds a card with custom content before the properties card on the manufacturer detail page: + ```js +import { ui, location } from '@shopware-ag/meteor-admin-sdk'; + if (location.is(location.MAIN_HIDDEN)) { - sw.ui.componentSection.add({ - // Choose a position id where you want to render a custom component + ui.componentSection.add({ positionId: 'sw-manufacturer-card-custom-fields__before', - // The Component Sections provides different components out of the box component: 'card', - // Props are depending on the type of component props: { title: 'Hello from plugin', subtitle: 'I am before the properties card', - // Some components can render a custom view. In this case the extension can render custom content in the card. locationId: 'my-app-card-before-properties' } }) } -// Render the custom UI when the iFrame location matches your defined location -if (sw.location.is('my-app-card-before-properties')) { +if (location.is('my-app-card-before-properties')) { document.body.innerHTML = '

Hello World before

'; - document.body.style.background = 'blue'; } ``` ![Component Sections screenshot example](./assets/component-sections-example.png) -To render tabs inside the `card` component section, we provide a way to do so: - -```js -if (sw.location.is(sw.location.MAIN_HIDDEN)) { - // Choose a position id where you want to render a custom component - sw.ui.componentSection.add({ - // The Component Sections provides different components out of the box - component: 'card', - // Props are depending on the type of component - props: { - title: 'Hello from plugin', - subtitle: 'I am before the properties card', - // Render tabs and custom tab content with the provided location id - tabs: [ - { - name: 'example-tab-1', - label: 'First tab', - locationId: 'example-tab-1' - }, - { - name: 'example-tab', - label: 'Second tab', - locationId: 'example-tab-2' - } - ], - } - }) -} - -// Render the custom UI for different tab with the location id -if (sw.location.is('example-tab-1')) { - document.body.innerHTML = '

My first tab

'; - document.body.style.background = 'blue'; -} - -if (sw.location.is('example-tab-2')) { - document.body.innerHTML = '

My second tab

'; - document.body.style.background = 'yellow'; -} -``` - -![Component Sections screenshot example](./assets/component-sections-with-tabs-example.png) +For the full API reference including available components, card properties, and tab support, see the [Component Sections API reference](../api-reference/ui/component-sections.md). diff --git a/docs/admin-sdk/concepts/locations.md b/docs/admin-sdk/concepts/locations.md index 3e97b0dec..8584ed8a3 100644 --- a/docs/admin-sdk/concepts/locations.md +++ b/docs/admin-sdk/concepts/locations.md @@ -6,58 +6,33 @@ nav: # Locations -Locations define where an extension is rendered inside the Shopware Administration. +Locations define where an extension renders inside the Shopware Administration. Your SDK code gets injected into every location — and one hidden location — as an iframe. Since the same code runs in every iframe, you need a condition to check which location you are in and render the appropriate view. -Because an extension can appear in multiple places (such as tabs, modals, sidebars, or custom modules), extensions typically check the current location before executing UI logic. - -This concept allows a single extension bundle to support multiple entry points inside the Administration. - -Extensions can render custom views via iFrames. To support multiple views in different places every `location` of the iFrame gets a unique ID. These can be defined by the extension developer itself. - -## How extensions use locations - -An extension can appear in multiple places inside the Administration. Each of these places is identified by a **location ID**. - -Typical flow: - -1. Register UI extensions when the extension loads -2. Define a `locationId` where the custom UI will render -3. Render different views depending on the current location - -### Example - -A extension wants to render a custom iFrame in a card in the dashboard. The `location` of the iFrame has then a specific `locationId` like `sw-dashboard-example-app-dashboard-card`. The app can also render another iFrames which also get `locationId`s. In our example it is a iFrame in a custom modal: `example-app-example-modal-content`. - -The extension want to render different views depending on the `location` of the iFrame. So the extension developer can render the correct view depending on the `locationId`: +Each location is identified by a **location ID**. When you register a UI extension (such as a component section or tab), you assign it a `locationId`. Then in your code, you use `location.is()` to branch: ```js -// Add the ui extensions when your extension is loaded in the hidden iFrame -if (sw.location.is(sw.location.MAIN_HIDDEN)) { +import { ui, location } from '@shopware-ag/meteor-admin-sdk'; + +if (location.is(location.MAIN_HIDDEN)) { ui.componentSection.add({ component: 'card', positionId: 'sw-product-properties__before', props: { title: 'Hello from plugin', subtitle: 'I am before the properties card', - /** - * The locationId: - **/ locationId: 'my-app-card-before-properties' } }) } -// Render the custom UI when the iFrame location matches your defined location -if (sw.location.is('my-app-card-before-properties')) { - document.body.innerHTML = '

I am the in the location "my-app-card-before-properties"

'; +if (location.is('my-app-card-before-properties')) { + document.body.innerHTML = '

Custom content here

'; } ``` -## Base location +## Base location (hidden iframe) -Every extension gets rendered in a hidden iFrame. In this iFrame the extension can execute different commands to extend -the administration and add custom locations to different extension points. To check if the script will be executed in this -location you can use the predefined constant: +Every extension is initially loaded in a hidden iframe. This is where you register all your UI extensions — adding tabs, component sections, menu entries, and so on. To check whether the current code is running in the hidden iframe, use the `MAIN_HIDDEN` constant: ```js import { location } from '@shopware-ag/meteor-admin-sdk'; @@ -67,17 +42,15 @@ if (location.is(location.MAIN_HIDDEN)) { } ``` -## Change height of location iFrame +## Change iframe height -The iFrame height is by default fixed. You can update the height with the location helper: +The iframe height is fixed by default. You can set it explicitly: ```js -location.updateHeight(750); // change iFrame height to 750px +location.updateHeight(750); // set iframe height to 750px ``` -If you use a parameter then the height will automatically be calculated so that your whole view gets rendered. In most cases -you don't want to update the height manually. To watch for height changes you can use the auto resizer. It updates the iFrame -height everytime the height of the view changes: +In most cases you want the height to adjust automatically. The auto resizer watches for height changes and updates the iframe whenever the content size changes: ```js // watch for height changes and update the iFrame @@ -88,14 +61,13 @@ location.startAutoResizer(); ## Avoiding scrollbars -If you render custom locations it is useful to disable the scroll behavior in your view. Otherwise scrollbars are visible -which aren't needed in most cases. To avoid this you can add the css property `overflow: hidden;` to the `body` element. +When rendering custom locations, add `overflow: hidden;` to the `body` element to prevent unnecessary scrollbars inside the iframe. -## For existing plugin migrations, render Vue components instead of iFrames +## Render Vue components instead of iframes (plugin migration) -In some cases you just want to use specific features from the SDK and some features from the existing plugin system which works with Twig and Component overriding. In this case you can do some things with the SDK but render components from the Shopware Component Factory instead of iFrames. +When migrating existing plugins, you can mix the SDK with the existing plugin system. Instead of rendering an iframe, you can render a Vue component registered via `Shopware.Component.register` at a location. -To do this you need to register the component in the existing plugin system: +Register the component: ```js Shopware.Component.register('your-component-name', { @@ -103,7 +75,7 @@ Shopware.Component.register('your-component-name', { }) ``` -Now if you want to render the component in a location you need to add the name of the component to the current location. This can be done with the `sdkLocation` store: +Then map it to a location ID using the `sdkLocation` store: ```js Shopware.State.commit('sdkLocation/addLocation', { @@ -112,7 +84,7 @@ Shopware.State.commit('sdkLocation/addLocation', { }) ``` -With this feature you can create mix the usage of the SDK and the existing plugin system. A complete example could be looking like this. It creates a new tab item in the product detail page, renders a card with the componentSection renderer and inside the card it renders the location. But instead of the traditional location it renders a Vue component which was registered in the Shopware Component Factory. +A complete example that adds a tab to the product detail page and renders a Vue component inside a card: ```js // in a normal plugin js file without a HTML file diff --git a/docs/admin-sdk/concepts/selectors.md b/docs/admin-sdk/concepts/selectors.md index 3e967ceb1..1c8311a4f 100644 --- a/docs/admin-sdk/concepts/selectors.md +++ b/docs/admin-sdk/concepts/selectors.md @@ -13,6 +13,29 @@ By selecting only the required properties, selectors reduce payload size and lim They are used in `data.subscribe` and `data.get`. Selectors are an array of strings, where each string represents the path to a property in the dataset. +## Selector syntax + +A selector is a dot-separated string. Each segment between dots is one of the following: + +| Segment | Syntax | Description | +| :--------- | :--------- | :------------------------------------------------------------------- | +| Property | `name` | Access a named property on the current object | +| Nested | `a.b` | Traverse into a nested object — each dot moves one level deeper | +| Array index| `[N]` | Access a specific element in an array by its zero-based index | +| Wildcard | `*` | Iterate over all elements in an array | + +These segments combine to form a path from the root of the dataset to the value you want. For example: + +| Selector | Meaning | +| :----------------------- | :--------------------------------------------------------- | +| `name` | The `name` property at the root level | +| `manufacturer.name` | The `name` property of the `manufacturer` object | +| `variants.[0].name` | The `name` of the first element in the `variants` array | +| `variants.*.name` | The `name` of every element in the `variants` array | +| `manufacturer.id` | The `id` property of the `manufacturer` object | + +When multiple selectors are passed, their results are merged into a single object. Properties from the same parent are combined — for example `['manufacturer.id', 'manufacturer.name']` returns one `manufacturer` object containing both `id` and `name`. + ## Example Consider the following example payload: diff --git a/docs/admin-sdk/docs.yml b/docs/admin-sdk/docs.yml new file mode 100644 index 000000000..32d333629 --- /dev/null +++ b/docs/admin-sdk/docs.yml @@ -0,0 +1,17 @@ +redirects: + api-reference/ui/component-section.html: api-reference/ui/component-sections.html + api-reference/ui/module/paymentOverviewCard.html: api-reference/ui/paymentOverviewCard.html + internals/how-it-works.html: concepts/architecture.html + internals/datahandling.html: concepts/datahandling.html + api-reference/in-app-purchases/in-app-purchases.html: api-reference/data/in-app-purchases.html + api-reference/in-app-purchases/index.html: api-reference/data/index.html + api-reference/ui/module/index.html: api-reference/ui/index.html + faq/index.html: develop/translations.html + getting-started/devTools.html: develop/devtools.html + getting-started/installation.html: getting-started/installation-apps.html + internals/index.html: concepts/index.html + tooling/index.html: develop/index.html + tooling/vue-devtools.html: develop/devtools.html + assets/sidebar-example.png: ui/assets/sidebar-example.png + api-reference/data/in-app-purchases.html: api-reference/ui/purchases-and-payments/in-app-purchases.html + api-reference/ui/paymentOverviewCard.html: api-reference/ui/purchases-and-payments/paymentOverviewCard.html From 5ca87a136d66238cef4585ae96dddbf32df783b0 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 19:18:43 +0100 Subject: [PATCH 36/59] docs: use info blocks for Shopware below 6.7 notes in plugin guide Made-with: Cursor --- docs/admin-sdk/getting-started/installation-plugins.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin-sdk/getting-started/installation-plugins.md b/docs/admin-sdk/getting-started/installation-plugins.md index 879f13fa0..b2018653d 100644 --- a/docs/admin-sdk/getting-started/installation-plugins.md +++ b/docs/admin-sdk/getting-started/installation-plugins.md @@ -16,7 +16,7 @@ This guide assumes **Shopware 6.7 or later**. Shopware 6.7 introduced a new exte Create the folder `custom/plugins/yourPluginName/src/Resources/app/meteor-app`. This is the base path for all new files for your extension. -:::caution Shopware below 6.7 +:::info Shopware below 6.7 Use the path `custom/plugins/yourPluginName/src/Resources/app/administration` instead. ::: @@ -48,7 +48,7 @@ Then create a JavaScript file in the subfolder `src/main.js` and reference it in ``` -:::caution Shopware below 6.7 +:::info Shopware below 6.7 Leave out `` — it is injected automatically in older versions. ::: @@ -73,7 +73,7 @@ bin/console cache:clear ### 5. Build and watch -You don't need to set up Vite on your own — Shopware already takes care of bundling. Run the Administration watcher to rebuild the frontend: +You don't need to set up Vite on your own — Shopware already takes care of bundling. Rerun the Administration watcher to rebuild the frontend: ```bash composer watch:admin From 1ee53bd022c9ff6fa959de77e71b7f36c3759c3c Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 19:39:19 +0100 Subject: [PATCH 37/59] docs: flatten context.md hierarchy, fix develop nav, update resolved.md - Remove group headings (Language, Environment, etc.) from context.md and add per-method explanations instead - Normalize develop/index.md to use nav.position instead of sidebar_position - Update resolved.md to reflect getRepository was recreated Made-with: Cursor --- docs/admin-sdk/api-reference/context.md | 84 ++++------ docs/admin-sdk/develop/index.md | 3 +- review/resolved.md | 196 ++++++++++++++++++++++++ 3 files changed, 228 insertions(+), 55 deletions(-) create mode 100644 review/resolved.md diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index a3bc94aad..f044cbf7a 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -10,11 +10,9 @@ The Context API provides read access to the current state of the Shopware Admini This is useful for adapting extension behavior based on the current Administration context — for example, loading translations for the active language or checking the Shopware version before using a newer API. -## Language +## context.getLanguage() -Retrieve or subscribe to the currently active Administration language. - -### context.getLanguage() +Returns the current Administration language ID and the system default language ID. Use this to load the correct translations or filter data by language. #### Usage @@ -44,7 +42,9 @@ Promise<{ } ``` -### context.subscribeLanguage() +## context.subscribeLanguage() + +Subscribes to language changes in the Administration. The callback fires whenever the user switches languages, allowing extensions to react immediately (e.g. reloading translated content). #### Usage @@ -78,11 +78,9 @@ context.subscribeLanguage(({ languageId, systemLanguageId }) => { } ``` -## Environment +## context.getEnvironment() -Check whether the Administration is running in development, production, or testing mode. - -### context.getEnvironment() +Returns the current Administration environment mode. Use this to enable debug features or disable analytics in non-production environments. #### Usage @@ -106,11 +104,9 @@ Promise<'development' | 'production' | 'testing'> 'development' ``` -## Locale - -Retrieve or subscribe to the browser locale used by the Administration UI. +## context.getLocale() -### context.getLocale() +Returns the browser locale used by the Administration UI, including a fallback locale. Use this to format dates, numbers, or currencies according to the user's regional settings. #### Usage @@ -140,7 +136,9 @@ Promise<{ } ``` -### context.subscribeLocale() +## context.subscribeLocale() + +Subscribes to locale changes in the Administration. The callback fires whenever the locale changes, allowing extensions to re-render locale-dependent content like formatted dates or currencies. #### Usage @@ -174,11 +172,9 @@ context.subscribeLocale(({ locale, fallbackLocale }) => { } ``` -## Currency - -Retrieve the system currency configured for the Shopware instance. +## context.getCurrency() -### context.getCurrency() +Returns the system currency configured for the Shopware instance. Use this when displaying prices or working with monetary values. #### Usage @@ -208,11 +204,9 @@ Promise<{ } ``` -## Shopware version +## context.getShopwareVersion() -Query the Shopware version to conditionally enable features or check compatibility. - -### context.getShopwareVersion() +Returns the Shopware version as a string. Use this to conditionally enable features or check compatibility before using newer APIs. #### Usage @@ -236,11 +230,9 @@ string '6.4.0.0' ``` -### context.compareShopwareVersion() - -In many cases you have to make sure that the shop you are communicating with has a certain Shopware version. For this purpose the Meteor Admin SDK provides the `context.compareShopwareVersion` function. +## context.compareShopwareVersion() -The function always treats the current Shopware version of a shop as the left hand operator of the comparison. That means a call like `context.compareShopwareVersion('>=', '7.0.0')` can be read as "*Compare: is Shopware version equal or greater than 7.0.0*" +Compares the current Shopware version against a target version. The current Shopware version is always the left-hand side of the comparison — so `context.compareShopwareVersion('>=', '7.0.0')` reads as "is the current Shopware version equal to or greater than 7.0.0?" #### Usage @@ -274,11 +266,9 @@ boolean true ``` -## App information +## context.getAppInformation() -Retrieve metadata about the current app or plugin, including its name, version, type, and granted privileges. - -### context.getAppInformation() +Returns metadata about the current app or plugin, including its name, version, type, and granted privileges. Use this to adapt behavior based on the extension type or check which permissions were granted. > The `privileges` property is available since Shopware v6.7.1.0. @@ -313,11 +303,9 @@ Promise<{ name: string ; version: string ; type: 'app' | 'plugin', privileges: p } ``` -## User information - -Access details about the currently logged-in Administration user. +## context.getUserInformation() -### context.getUserInformation() +Returns details about the currently logged-in Administration user, including their roles, email, and admin status. Use this to personalize the extension UI or check user permissions. > Available since Shopware v6.4.9.0 @@ -374,11 +362,9 @@ Promise<{ } ``` -## User Timezone +## context.getUserTimezone() -Retrieve the timezone setting of the currently logged-in user. - -### context.getUserTimezone() +Returns the timezone setting of the currently logged-in user. Use this to display dates and times in the user's local timezone. > Available since Shopware v6.6.2.0 @@ -400,15 +386,9 @@ Promise This function returns a Promise that resolves to a string representing the user's timezone. -## Module information - -Query the list of registered extension modules to navigate between them. +## context.getModuleInformation() -### context.getModuleInformation() - -Get information about all registered modules. These modules are created by adding new menu items, setting items, etc. - -The ID can be used to change the current route to the module. +Returns the list of all registered extension modules (created by adding menu items, settings items, etc.). Use the module ID to navigate between extensions. #### Usage @@ -457,11 +437,9 @@ Promise<{ } ``` -## ShopId +## context.getShopId() -Retrieve the unique shop ID used by Shopware's app system. - -### context.getShopId() +Returns the unique shop ID used by Shopware's app system. Use this to identify the shop instance when communicating with external services. > Available since Shopware v6.7.1.0 @@ -481,11 +459,9 @@ No parameters needed. Promise ``` -## Check app's privileges - -Check whether a specific privilege is granted for the current app. Useful for conditionally showing features. +## context.can() -### context.can() +Checks whether a specific privilege is granted for the current app. Use this to conditionally show features that require specific permissions. > Available since Shopware v6.7.1.0 diff --git a/docs/admin-sdk/develop/index.md b/docs/admin-sdk/develop/index.md index d802152c5..2d04f4557 100644 --- a/docs/admin-sdk/develop/index.md +++ b/docs/admin-sdk/develop/index.md @@ -1,6 +1,7 @@ --- title: "Start Developing" -sidebar_position: 30 +nav: + position: 30 --- diff --git a/review/resolved.md b/review/resolved.md new file mode 100644 index 000000000..dd27525fa --- /dev/null +++ b/review/resolved.md @@ -0,0 +1,196 @@ +# Resolved Review Comments + +PR: [shopware/meteor#1075](https://github.com/shopware/meteor/pull/1075) + +Items are moved here after todos from a comment are completed. + +- [ ] = pending human verification +- [x] = verified by human, ready for GH thread resolution + +## Already Resolved on GitHub + +### #2953581776 + +**File:** `docs/admin-sdk/getting-started/index.md` | [View on GitHub](https://github.com/shopware/meteor/pull/1075#discussion_r2953581776) + +> These two links are relative paths and therefore are referencing to a non existing file. Remove the redundant `getting-started/` prefix + +**Status:** Resolved on GitHub prior to this process. + + +### #2953586858 + +**File:** `docs/admin-sdk/develop/migrating-admin-plugins.md` | [View on GitHub](https://github.com/shopware/meteor/pull/1075#discussion_r2953586858) + +> Typo `capabilities` + +**Status:** Resolved on GitHub prior to this process. + + +### #2953601227 + +**File:** `docs/admin-sdk/develop/index.md` | [View on GitHub](https://github.com/shopware/meteor/pull/1075#discussion_r2953601227) + +> Several files that contain pure API reference material (parameters, return values, usage signatures) were moved from `api-reference/` into `develop/`: + +- `develop/context.md` +- [...] + +**Status:** Resolved on GitHub prior to this process. + + +### #2953609821 + +**File:** `docs/admin-sdk/faq/index.md` | [View on GitHub](https://github.com/shopware/meteor/pull/1075#discussion_r2953609821) + +> Where was this content moved to? These are very important information we should not lose or delete + +**Status:** Resolved on GitHub prior to this process. + + +### #2953656853 + +**File:** `docs/admin-sdk/getting-started/index.md` | [View on GitHub](https://github.com/shopware/meteor/pull/1075#discussion_r2953656853) + +> It doesn't need to be in the entry file. You need to import it where you need it. + +**Status:** Resolved on GitHub prior to this process. + + +## Resolved During This Process + +### `docs/admin-sdk/api-reference/cms/index.md` + +- [x] **#2966698897** — Set CMS position to 300. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966698897) + +### `docs/admin-sdk/api-reference/composables/index.md` + +- [x] **#2966697591** — Set composables position to 400. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966697591) +- [x] **#2966712098** — Updated composable description to mention Vue Composables. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966712098) +- [x] **#2966741402** — Renamed title to 'Vue Composables'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966741402) + +### `docs/admin-sdk/api-reference/composables/useRepository.md` + +- [ ] **#2966728289** — Recreated getRepository documentation page and re-added getRepository references in useRepository "How it works" section with code example. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966728289) + +### `docs/admin-sdk/api-reference/context.md` + +- [ ] **#2974427282** — Added overall introduction and brief descriptions for each context section. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974427282) + +### `docs/admin-sdk/api-reference/data/get.md` + +- [ ] **#2966845584** — Replaced with data handling guide link. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966845584) + +### `docs/admin-sdk/api-reference/data/index.md` + +- [ ] **#2966696276** — Set data position to 200. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966696276) + +### `docs/admin-sdk/api-reference/data/repository.md` + +- [ ] **#2966818177** — Renamed to repository.search(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966818177) +- [ ] **#2966819560** — Renamed to repository.get(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966819560) +- [ ] **#2966824040** — Renamed to repository.save(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966824040) +- [ ] **#2966825119** — Renamed to repository.clone(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966825119) +- [ ] **#2966826682** — Renamed to repository.hasChanges(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966826682) +- [ ] **#2966828136** — Renamed to repository.saveAll(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966828136) +- [ ] **#2966829119** — Renamed to repository.delete(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966829119) +- [ ] **#2966830321** — Renamed to repository.create(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966830321) + +### `docs/admin-sdk/api-reference/data/subscribe.md` + +- [ ] **#2965086703** — Rewrote subscribe description with data handling guide link. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965086703) + +### `docs/admin-sdk/api-reference/data/update.md` + +- [ ] **#2965091293** — Rewrote update description with data handling guide link. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965091293) + +### `docs/admin-sdk/api-reference/index.md` + +- [ ] **#2966197662** — Applied suggestion. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966197662) +- [ ] **#2966371533** — Changed to 'Trigger an In-App Purchase'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966371533) +- [ ] **#2974303496** — Applied h3→h4 for Usage/Parameters/Return across all API reference files (70+ changes). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974303496) +- [ ] **#2974341610** — Changed heading to '## Extending the UI'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974341610) + +### `docs/admin-sdk/api-reference/notification.md` + +- [ ] **#2974454354** — Rewrote to clarify notifications persist in notification center but can be dismissed. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974454354) + +### `docs/admin-sdk/api-reference/toast.md` + +- [ ] **#2974466629** — Added explanation of toast vs notification difference. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974466629) +- [ ] **#2974470481** — Fixed icon column formatting. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974470481) +- [ ] **#2974757040** — Converted availability heading to info box. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974757040) + +### `docs/admin-sdk/api-reference/ui/component-sections.md` + +- [ ] **#2966156633** — Removed redundant 'Example' heading. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966156633) +- [ ] **#2966162956** — Changed to 'Example: Add a component to the product page'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966162956) +- [ ] **#2966175089** — Changed to 'Example: Add tabs to the card'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966175089) +- [ ] **#2966178429** — Removed redundant 'Example' heading. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966178429) + +### `docs/admin-sdk/api-reference/ui/index.md` + +- [ ] **#2966693593** — Set UI position to 100. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966693593) +- [ ] **#2974343217** — Renamed title to 'Extending the UI'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974343217) + +### `docs/admin-sdk/api-reference/ui/mainModule.md` + +- [ ] **#2966914130** — Changed to addMainModule(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966914130) +- [ ] **#2966916677** — Changed to addSmartbarButton(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966916677) +- [ ] **#2966919080** — Changed to hideSmartBar(). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966919080) + +### `docs/admin-sdk/api-reference/ui/mediaModal.md` + +- [ ] **#2973864833** — Changed to ui.mediaModal.open() with updated description. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2973864833) +- [ ] **#2974288657** — Same as above — both suggestions targeted same line. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974288657) + +### `docs/admin-sdk/concepts/component-sections.md` + +- [ ] **#2974917759** — Updated to 'render custom UI components inside predefined extension points'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974917759) + +### `docs/admin-sdk/concepts/datahandling.md` + +- [ ] **#2974938338** — Fixed typo ('Sdministration' → 'Administration') and improved wording. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2974938338) + +### `docs/admin-sdk/concepts/index.md` + +- [ ] **#2966184142** — Set concepts position to 20. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966184142) + +### `docs/admin-sdk/develop/index.md` + +- [ ] **#2975080837** — Removed broken links to api-reference files; simplified to list only develop/ files. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2975080837) + +### `docs/admin-sdk/getting-started/index.md` + +- [ ] **#2965625728** — Getting Started position (10) is already above Concepts (20). [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965625728) + +### `docs/admin-sdk/getting-started/installation-apps.md` + +- [ ] **#2965277799** — Clarified backend is required, not optional. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965277799) +- [ ] **#2965286416** — Changed to 'frontend layer for the administration'. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965286416) +- [ ] **#2965295630** — Added Cross-Origin Security explanation and dev tip with Docker note. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965295630) +- [ ] **#2965308179** — Rewrote App Server SDK description. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965308179) +- [ ] **#2965321387** — Removed 'across runtimes' link. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965321387) +- [ ] **#2965329814** — Replaced with npx tiged scaffold command. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965329814) +- [ ] **#2965338350** — Clarified first two steps are mandatory, third is optional. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965338350) +- [ ] **#2965344679** — Added php-sdk recommendation and official SDK list link. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965344679) +- [ ] **#2965460313** — Added manifest path and install commands. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965460313) +- [ ] **#2965462871** — Clarified notification appears on every page load. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965462871) +- [ ] **#2965766407** — Added Docker host.docker.internal note in dev tip. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965766407) +- [ ] **#2966119941** — Added Next Steps section with links to API Reference, Concepts, and Usage. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966119941) + +### `docs/admin-sdk/getting-started/installation-plugins.md` + +- [ ] **#2965470006** — Restructured to assume 6.7+ with collapsible <6.7 details. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965470006) +- [ ] **#2965629922** — Updated folder path with <6.7 details block. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965629922) +- [ ] **#2965670128** — Added install command with correct cd path. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965670128) +- [ ] **#2965693461** — Added plugin install commands, bundling explanation, and <6.7 details. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965693461) +- [ ] **#2965699891** — Changed to 'Log in to the Administration. A notification should appear...' [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965699891) +- [ ] **#2965773310** — Removed legacy 6.6 section; consolidated into single flow with spoilers. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965773310) +- [ ] **#2966121229** — Added Next Steps section. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966121229) +- [ ] **#2966688213** — Added info box about 6.7 version differences. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966688213) + +### `docs/admin-sdk/index.md` + +- [ ] **#2965812015** — Combined 'What you can build' and 'What you can do' into single section. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2965812015) +- [ ] **#2966139483** — Replaced 'Go here' with explicit link to Getting Started guide. [View](https://github.com/shopware/meteor/pull/1075#discussion_r2966139483) From aca809850110a062f1a8ca75be56e46e01dc5171 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 19:39:39 +0100 Subject: [PATCH 38/59] docs: refine base-options intro example and use warning block Made-with: Cursor --- docs/admin-sdk/api-reference/base-options.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/admin-sdk/api-reference/base-options.md b/docs/admin-sdk/api-reference/base-options.md index ee5a9e740..9977eec82 100644 --- a/docs/admin-sdk/api-reference/base-options.md +++ b/docs/admin-sdk/api-reference/base-options.md @@ -8,24 +8,24 @@ More options may be added in the future. Currently, the following option is avai | :----------- | :------- | :------ | :------------------ | :----------------------------------------------------------------------------------------- | | `privileges` | false | | >= Shopware 6.6.3.0 | Check the current user's privileges before executing the action. See [Privileges](#privileges). | +#### Usage + +In this example you can see that in `notification`, you can insert base options alongside the message property. + ```ts import { notification } from '@shopware-ag/meteor-admin-sdk'; notification.dispatch({ message: 'Your product report is ready', - privileges: [ - 'product:read', - ], + /* ... base options ... */ }); ``` -In this example, the notification is only dispatched if the current Administration user has `product:read` permission. - ## Privileges The `privileges` option accepts an array of privilege strings. When provided, the SDK checks whether the current Administration user holds all listed privileges before executing the action. If any privilege is missing, the action is silently skipped. -:::caution Not a security feature +:::warning Not a security feature Privilege checks happen client-side in the browser. They prevent UI elements from appearing for users who lack the required permissions, but they do not enforce access control on the server. Server-side authorization is still required for any sensitive operation. ::: From 4e9d1a3f331d21bef1b8bbf0a16396d8b68b6074 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 19:50:32 +0100 Subject: [PATCH 39/59] docs: add npm/cdn import tabs to all API reference pages, improve app install guide - Add ::: code-group import sections (npm vs cdn) to all 25 API reference pages showing how to import each module - Convert installation-apps.md step 2 HTML examples to tabbed code-group - Add explanation for serving HTML from Hono app server with code snippets - Fix sw. prefix in repository.md intro example Made-with: Cursor --- .../api-reference/cms/registerCmsBlock.md | 13 +++++++ .../api-reference/cms/registerCmsElement.md | 13 +++++++ .../composables/getRepository.md | 13 +++++++ .../composables/useRepository.md | 13 +++++++ .../composables/useSharedState.md | 13 +++++++ docs/admin-sdk/api-reference/context.md | 13 +++++++ docs/admin-sdk/api-reference/data/get.md | 13 +++++++ .../api-reference/data/repository.md | 14 ++++++- .../admin-sdk/api-reference/data/subscribe.md | 13 +++++++ docs/admin-sdk/api-reference/data/update.md | 13 +++++++ docs/admin-sdk/api-reference/location.md | 13 +++++++ docs/admin-sdk/api-reference/notification.md | 13 +++++++ docs/admin-sdk/api-reference/toast.md | 13 +++++++ .../api-reference/ui/actionButton.md | 13 +++++++ .../api-reference/ui/component-sections.md | 13 +++++++ docs/admin-sdk/api-reference/ui/mainModule.md | 13 +++++++ docs/admin-sdk/api-reference/ui/mediaModal.md | 13 +++++++ docs/admin-sdk/api-reference/ui/menu.md | 13 +++++++ docs/admin-sdk/api-reference/ui/modals.md | 13 +++++++ .../in-app-purchases.md | 13 +++++++ .../paymentOverviewCard.md | 13 +++++++ .../api-reference/ui/settingsItem.md | 13 +++++++ docs/admin-sdk/api-reference/ui/sidebars.md | 13 +++++++ docs/admin-sdk/api-reference/ui/tabs.md | 13 +++++++ docs/admin-sdk/api-reference/window.md | 13 +++++++ .../getting-started/installation-apps.md | 39 +++++++++++++++---- 26 files changed, 357 insertions(+), 8 deletions(-) diff --git a/docs/admin-sdk/api-reference/cms/registerCmsBlock.md b/docs/admin-sdk/api-reference/cms/registerCmsBlock.md index 870680a31..5bf55bea8 100644 --- a/docs/admin-sdk/api-reference/cms/registerCmsBlock.md +++ b/docs/admin-sdk/api-reference/cms/registerCmsBlock.md @@ -12,6 +12,19 @@ With `cms.registerCmsBlock` you can register CMS blocks to use in the Shopping E ![Register a CMS block in your Shopping Experiences Module via App](../assets/register-cms-block-example.png) +::: code-group + +```ts [npm] +import { cms } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.cms instead of cms +sw.cms.registerCmsBlock({ /* ... */ }); +``` + +::: + #### Usage ```ts diff --git a/docs/admin-sdk/api-reference/cms/registerCmsElement.md b/docs/admin-sdk/api-reference/cms/registerCmsElement.md index 90060b85e..287c592c9 100644 --- a/docs/admin-sdk/api-reference/cms/registerCmsElement.md +++ b/docs/admin-sdk/api-reference/cms/registerCmsElement.md @@ -13,6 +13,19 @@ More information on how to develop CMS elements can be found in these guides for ![Register a CMS element in your Shopping Experiences Module via App](../assets/register-cms-element-example.png) +::: code-group + +```ts [npm] +import { cms } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.cms instead of cms +sw.cms.registerCmsElement({ /* ... */ }); +``` + +::: + #### Usage ```ts diff --git a/docs/admin-sdk/api-reference/composables/getRepository.md b/docs/admin-sdk/api-reference/composables/getRepository.md index cc2dfaae8..872c0947c 100644 --- a/docs/admin-sdk/api-reference/composables/getRepository.md +++ b/docs/admin-sdk/api-reference/composables/getRepository.md @@ -13,6 +13,19 @@ When called inside a Vue component, `getRepository` first checks for an injected For a reactive variant that automatically updates when its inputs change, see [useRepository](./useRepository.md). +::: code-group + +```ts [npm] +import { composables } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.composables instead of composables +sw.composables.getRepository('product'); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/composables/useRepository.md b/docs/admin-sdk/api-reference/composables/useRepository.md index 7a56a5468..ec075b8aa 100644 --- a/docs/admin-sdk/api-reference/composables/useRepository.md +++ b/docs/admin-sdk/api-reference/composables/useRepository.md @@ -11,6 +11,19 @@ The `composables.useRepository` function creates a reactive repository instance `useRepository` accepts reactive references (refs) or values as parameters and returns a computed repository that updates when those parameters change. +::: code-group + +```ts [npm] +import { composables } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.composables instead of composables +sw.composables.useRepository('product'); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/composables/useSharedState.md b/docs/admin-sdk/api-reference/composables/useSharedState.md index e5e2f4107..7646bfd36 100644 --- a/docs/admin-sdk/api-reference/composables/useSharedState.md +++ b/docs/admin-sdk/api-reference/composables/useSharedState.md @@ -14,6 +14,19 @@ The value stored within the shared state can be any data type that can be serial ![useSharedState demo](../assets/useSharedState-demo.gif) +::: code-group + +```ts [npm] +import { composables } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.composables instead of composables +sw.composables.useSharedState('my-key', defaultValue); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index f044cbf7a..b0999bd2e 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -10,6 +10,19 @@ The Context API provides read access to the current state of the Shopware Admini This is useful for adapting extension behavior based on the current Administration context — for example, loading translations for the active language or checking the Shopware version before using a newer API. +::: code-group + +```ts [npm] +import { context } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.context instead of context +sw.context.getLanguage(); +``` + +::: + ## context.getLanguage() Returns the current Administration language ID and the system default language ID. Use this to load the correct translations or filter data by language. diff --git a/docs/admin-sdk/api-reference/data/get.md b/docs/admin-sdk/api-reference/data/get.md index 062a7d3f5..9245ef303 100644 --- a/docs/admin-sdk/api-reference/data/get.md +++ b/docs/admin-sdk/api-reference/data/get.md @@ -12,6 +12,19 @@ Compared to `data.subscribe`, `data.get` only gives you the current state of the [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. +::: code-group + +```ts [npm] +import { data } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.data instead of data +sw.data.get({ id: 'sw-product-detail__product' }); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/data/repository.md b/docs/admin-sdk/api-reference/data/repository.md index a677e087a..ee7b58391 100644 --- a/docs/admin-sdk/api-reference/data/repository.md +++ b/docs/admin-sdk/api-reference/data/repository.md @@ -12,11 +12,23 @@ The data handling of the SDK allows you to fetch and write nearly everything in The data handling implements the repository pattern. You can create a repository for an entity simply like this: ```ts -sw.data.repository('your_entity_name') +data.repository('your_entity_name') ``` With this repository you can search for data, save it, delete it, create it or check for changes. +::: code-group + +```ts [npm] +import { data } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.data instead of data +sw.data.repository('product'); +``` + +::: ### Permissions For every action on the repository, your app will need the matching permissions. diff --git a/docs/admin-sdk/api-reference/data/subscribe.md b/docs/admin-sdk/api-reference/data/subscribe.md index 710a92332..989148fe8 100644 --- a/docs/admin-sdk/api-reference/data/subscribe.md +++ b/docs/admin-sdk/api-reference/data/subscribe.md @@ -11,6 +11,19 @@ With `data.subscribe`, you can subscribe to changes in the dataset. Every time the dataset you subscribed to changes, the callback will be called with the new data. An individual dataset is referenced by an ID. [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. +::: code-group + +```ts [npm] +import { data } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.data instead of data +sw.data.subscribe('sw-product-detail__product', callback); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/data/update.md b/docs/admin-sdk/api-reference/data/update.md index 7e7ec896f..1f9a4b4e0 100644 --- a/docs/admin-sdk/api-reference/data/update.md +++ b/docs/admin-sdk/api-reference/data/update.md @@ -9,6 +9,19 @@ nav: With `data.update` you can update datasets from the Shopware Administration. [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. +::: code-group + +```ts [npm] +import { data } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.data instead of data +sw.data.update({ id: '...', data: { /* ... */ } }); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/location.md b/docs/admin-sdk/api-reference/location.md index dc1d67e46..ef36650ef 100644 --- a/docs/admin-sdk/api-reference/location.md +++ b/docs/admin-sdk/api-reference/location.md @@ -10,6 +10,19 @@ Locations define where extension code is executed inside the Shopware Administra Each location represents a specific UI context (for example a tab, modal, sidebar, or hidden entry point). Extensions typically check the current location before deciding which UI elements to register or which view to render. +::: code-group + +```ts [npm] +import { location } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.location instead of location +sw.location.is(sw.location.MAIN_HIDDEN); +``` + +::: + ## Prerequisites See [Locations](../concepts/locations.md) for a full explanation of the concept. diff --git a/docs/admin-sdk/api-reference/notification.md b/docs/admin-sdk/api-reference/notification.md index f2496325b..f234b921a 100644 --- a/docs/admin-sdk/api-reference/notification.md +++ b/docs/admin-sdk/api-reference/notification.md @@ -10,6 +10,19 @@ Notifications display messages in the Shopware Administration to inform users ab See also: [Base Options](../api-reference/base-options.md) for shared configuration options supported by SDK message APIs. +::: code-group + +```ts [npm] +import { notification } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.notification instead of notification +sw.notification.dispatch({ title: '...', message: '...' }); +``` + +::: + ## Dispatch a notification ![notification example](./assets/notification-example.jpg) diff --git a/docs/admin-sdk/api-reference/toast.md b/docs/admin-sdk/api-reference/toast.md index 874079eef..37a8f50eb 100644 --- a/docs/admin-sdk/api-reference/toast.md +++ b/docs/admin-sdk/api-reference/toast.md @@ -12,6 +12,19 @@ See also: [Base Options](../api-reference/base-options.md) for shared configurat > Available since Shopware v6.6.2.0 +::: code-group + +```ts [npm] +import { toast } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.toast instead of toast +sw.toast.dispatch({ msg: '...' }); +``` + +::: + ## Dispatch a toast ![toast example](./assets/toast-example.png) diff --git a/docs/admin-sdk/api-reference/ui/actionButton.md b/docs/admin-sdk/api-reference/ui/actionButton.md index 55d5096be..a4643f6a3 100644 --- a/docs/admin-sdk/api-reference/ui/actionButton.md +++ b/docs/admin-sdk/api-reference/ui/actionButton.md @@ -11,6 +11,19 @@ An action button adds a clickable button to an existing area of the Shopware Adm Action buttons are typically used to trigger extension-specific actions such as opening a modal, executing a workflow, or navigating to an extension module. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.actionButton.add({ /* ... */ }); +``` + +::: + ## Usage ```ts diff --git a/docs/admin-sdk/api-reference/ui/component-sections.md b/docs/admin-sdk/api-reference/ui/component-sections.md index 8a89f5012..bdc44a10c 100644 --- a/docs/admin-sdk/api-reference/ui/component-sections.md +++ b/docs/admin-sdk/api-reference/ui/component-sections.md @@ -10,6 +10,19 @@ Component sections allow extensions to render UI components inside existing Admi See the [Component Sections concept](../../concepts/component-sections.md) for an overview. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.componentSection.add({ /* ... */ }); +``` + +::: + ## Add Add a new component to a component section. diff --git a/docs/admin-sdk/api-reference/ui/mainModule.md b/docs/admin-sdk/api-reference/ui/mainModule.md index 865edac8d..142a1794b 100644 --- a/docs/admin-sdk/api-reference/ui/mainModule.md +++ b/docs/admin-sdk/api-reference/ui/mainModule.md @@ -11,6 +11,19 @@ A main module registers a new top-level section in the Shopware Administration n Use a main module when your extension provides a dedicated application area with its own pages and functionality. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.mainModule.add({ /* ... */ }); +``` + +::: + ## addMainModule() Add a main module to your extension. The content of the main module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index 32a0dd999..b05044dd0 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -12,6 +12,19 @@ This method allows apps to interact with the Administration's media modal. Two m - **Media modal**: Select existing media from the media library or upload new files. Available since Shopware 6.7.1. - **Save media modal**: Choose a specific folder and filename when saving media. Available since Shopware 6.7.5. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.mediaModal.open({ /* ... */ }); +``` + +::: + ## ui.mediaModal.open() Open the media modal in the current view. diff --git a/docs/admin-sdk/api-reference/ui/menu.md b/docs/admin-sdk/api-reference/ui/menu.md index af4d36c24..a229be1c0 100644 --- a/docs/admin-sdk/api-reference/ui/menu.md +++ b/docs/admin-sdk/api-reference/ui/menu.md @@ -10,6 +10,19 @@ Menu items allow extensions to add navigation entries to existing areas of the S They are typically used to expose extension functionality inside existing admin modules. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.menu.addMenuItem({ /* ... */ }); +``` + +::: + ## Toggle menu > Available since Shopware v6.6.2.0 diff --git a/docs/admin-sdk/api-reference/ui/modals.md b/docs/admin-sdk/api-reference/ui/modals.md index 8ce286299..89210849d 100644 --- a/docs/admin-sdk/api-reference/ui/modals.md +++ b/docs/admin-sdk/api-reference/ui/modals.md @@ -15,6 +15,19 @@ Avoid opening modals automatically without context, as this interrupts the user See also: [Base Options](../base-options.md) for shared configuration options supported by SDK message APIs. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.modal.open({ /* ... */ }); +``` + +::: + ## Open modal Open a new modal in the current view. The content of the modal is determined by your `locationId` or by using plain text with `textContent`. diff --git a/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md index 1bcd06751..fe7a4ea87 100644 --- a/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md @@ -11,6 +11,19 @@ nav: In-App purchases allow apps to unlock different functionality based on purchases made by the user. This guide covers how to start the in-app purchase flow directly from the Administration. +::: code-group + +```ts [npm] +import { iap } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.iap instead of iap +sw.iap.purchase({ identifier: '...' }); +``` + +::: + ## Start the purchase flow To open a modal with details about the feature that can be purchased: diff --git a/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md index 4d1a9fc40..794823cf2 100644 --- a/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md @@ -13,6 +13,19 @@ Starting with Shopware **6.4.14.0**, extensions can replace the default payment For example, you might require merchants to complete an onboarding process with your payment provider before enabling the payment method. +::: code-group + +```ts [npm] +import { ui, location } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui and sw.location instead of ui and location +sw.ui.module.payment.overviewCard.add({ /* ... */ }); +``` + +::: + ## Parameters | Name | Required | Default | Description | diff --git a/docs/admin-sdk/api-reference/ui/settingsItem.md b/docs/admin-sdk/api-reference/ui/settingsItem.md index af3fb03e2..e9b5492dc 100644 --- a/docs/admin-sdk/api-reference/ui/settingsItem.md +++ b/docs/admin-sdk/api-reference/ui/settingsItem.md @@ -11,6 +11,19 @@ A settings item adds an entry to the Shopware Administration settings area. Use this when your extension provides configurable options that should appear in the central settings section. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.settings.addSettingsItem({ /* ... */ }); +``` + +::: + ## Add settings item Add a new settings item to the Shopware settings. The content of the settings item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. diff --git a/docs/admin-sdk/api-reference/ui/sidebars.md b/docs/admin-sdk/api-reference/ui/sidebars.md index fc409c94d..0b5e1f2aa 100644 --- a/docs/admin-sdk/api-reference/ui/sidebars.md +++ b/docs/admin-sdk/api-reference/ui/sidebars.md @@ -9,6 +9,19 @@ nav: A sidebar provides a contextual panel that displays at the right edge of the Administration window. Unlike modals, sidebars allow users to view and interact with additional content or functionality without losing context of the main interface. Sidebars should be opened in response to user interaction rather than appearing automatically. As a best practice, avoid opening sidebars without clear user context - for example, automatically displaying extension changelog sidebars immediately after login creates a poor user experience by requiring manual dismissal of each one. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.sidebar({ /* ... */ }); +``` + +::: + ## Add a sidebar Add a new sidebar. The content of the sidebar is determined by your `locationId`. diff --git a/docs/admin-sdk/api-reference/ui/tabs.md b/docs/admin-sdk/api-reference/ui/tabs.md index 91516b921..6e4b94a0b 100644 --- a/docs/admin-sdk/api-reference/ui/tabs.md +++ b/docs/admin-sdk/api-reference/ui/tabs.md @@ -11,6 +11,19 @@ Tabs allow extensions to add additional tabs to existing Administration pages. They are commonly used to extend entity detail pages such as products, customers, or orders. +::: code-group + +```ts [npm] +import { ui } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.ui instead of ui +sw.ui.tabs('sw-product-detail').addTabItem({ /* ... */ }); +``` + +::: + ## Add tab item Add a new tab item to an existing tab bar. The content of the the new tab item diff --git a/docs/admin-sdk/api-reference/window.md b/docs/admin-sdk/api-reference/window.md index 4db0e93e5..384f9a809 100644 --- a/docs/admin-sdk/api-reference/window.md +++ b/docs/admin-sdk/api-reference/window.md @@ -8,6 +8,19 @@ sidebar_position: 70 The Window API provides methods for navigation and window-related utilities inside the Shopware Administration. +::: code-group + +```ts [npm] +import { window as swWindow } from '@shopware-ag/meteor-admin-sdk'; +``` + +```ts [cdn] +// use sw.window instead of window +sw.window.routerPush({ name: '...' }); +``` + +::: + ## redirect() Redirect to an external URL. diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index 4892167a6..79486deb1 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -67,11 +67,11 @@ Using the [App Server SDK](https://github.com/shopware/app-sdk-js) is recommende ### 2. Create the Administration HTML page -Create an HTML file. This file must be accessible via URL, so ensure that it is served by the app server. +Create an HTML file called `my-example-app.html`. This is the page that Shopware loads inside the Administration when the app is active. -CDN example: +::: code-group -```html +```html [cdn] @@ -90,9 +90,7 @@ CDN example: ``` -npm example: - -```html +```html [npm] @@ -111,7 +109,34 @@ npm example: ``` -The SDK must be bundled using the build tool. See the [App development guide](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide). +::: + +When using npm, the SDK must be bundled with a build tool like Vite. See the [App development guide](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide). + +#### Serving the HTML file + +The scaffolded Hono app server does not serve static files by default. You need to add a route that serves `my-example-app.html`. + +Place the file next to your `index.ts` (e.g. `demo-app/my-example-app.html`), then add a route to serve it: + +```ts +import { readFileSync } from 'node:fs'; + +app.get('/my-example-app.html', (c) => { + const html = readFileSync('./my-example-app.html', 'utf-8'); + return c.html(html); +}); +``` + +Alternatively, serve all files from a `public/` folder using Hono's static file middleware: + +```ts +import { serveStatic } from '@hono/node-server/serve-static'; + +app.use('/*', serveStatic({ root: './public' })); +``` + +With this approach, place the HTML file at `demo-app/public/my-example-app.html`. ### 3. Register the Administration page in `manifest.xml` From 72af6f87a4834283885d663246372d90a7d0256d Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Mon, 23 Mar 2026 20:06:06 +0100 Subject: [PATCH 40/59] docs: restructure landing pages, improve app installation guide - Move index.md content to introduction.md, rewrite index.md as hub page - Delete README.md, add redirect to introduction in docs.yml - Overhaul getting-started/index.md: app vs plugin guidance, recommend apps for cloud compatibility, reference migration guide - installation-apps.md: npm tab first, explicit file path at demo-app/my-example-app.html, use 'Test' as secret with sync warning, improve HTML serving explanation - Fix CHANGELOG title Made-with: Cursor --- docs/admin-sdk/CHANGELOG.md | 2 +- docs/admin-sdk/README.md | 31 ----- docs/admin-sdk/docs.yml | 1 + docs/admin-sdk/getting-started/index.md | 114 +++++------------- .../getting-started/installation-apps.md | 26 ++-- docs/admin-sdk/index.md | 39 ++---- docs/admin-sdk/introduction.md | 36 ++++++ 7 files changed, 91 insertions(+), 158 deletions(-) delete mode 100644 docs/admin-sdk/README.md create mode 100644 docs/admin-sdk/introduction.md diff --git a/docs/admin-sdk/CHANGELOG.md b/docs/admin-sdk/CHANGELOG.md index adb4ce4ae..7ba3c6300 100644 --- a/docs/admin-sdk/CHANGELOG.md +++ b/docs/admin-sdk/CHANGELOG.md @@ -1,4 +1,4 @@ -# admin-sdk-docs +# Changelog ## 1.0.0 diff --git a/docs/admin-sdk/README.md b/docs/admin-sdk/README.md deleted file mode 100644 index bb8f7d16e..000000000 --- a/docs/admin-sdk/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Shopware release notes - -*This repository is embedded into [developer-portal](https://github.com/shopware/developer-portal) under the [/resources/admin-extension-sdk/](https://developer.shopware.com/resources/admin-extension-sdk). This repository is also connected to the Shopware Dev Docs connector GitHub app which manages commit status checks in PRs and triggers production deployments.* - -## Development - -1. Clone this repository - -``` -cd /www/ -git clone git@github.com:shopware/meteor.git -cd meteor/packages/admin-sdk -``` - -2. Make sure you have your local copy of the `developer-portal` repository in the same parent directory. - -``` -pnpm docs:env -``` - -3. Link articles from your local copy of the `meteor` into the `developer-portal`. - -``` -pnpm docs:link -``` - -4. Start the development server. - -``` -pnpm docs:preview -``` diff --git a/docs/admin-sdk/docs.yml b/docs/admin-sdk/docs.yml index 32d333629..1a0145169 100644 --- a/docs/admin-sdk/docs.yml +++ b/docs/admin-sdk/docs.yml @@ -13,5 +13,6 @@ redirects: tooling/index.html: develop/index.html tooling/vue-devtools.html: develop/devtools.html assets/sidebar-example.png: ui/assets/sidebar-example.png + README.html: introduction.html api-reference/data/in-app-purchases.html: api-reference/ui/purchases-and-payments/in-app-purchases.html api-reference/ui/paymentOverviewCard.html: api-reference/ui/purchases-and-payments/paymentOverviewCard.html diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index b92209b33..ed0e8c45e 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -7,115 +7,57 @@ nav: # Getting Started -Learn how to install and set up the Meteor Admin SDK to start building extensions for the Shopware Administration. +This guide helps you set up the Meteor Admin SDK and start building extensions for the Shopware Administration. -## Install the SDK - -There are two ways to install the Meteor Admin SDK: - -- **npm + Vite (recommended)**: for production extensions with a build pipeline -- **CDN**: for quick prototypes without a build step - -### Using npm and Vite (recommended) - -Using npm is recommended for production environments. It enables proper bundling and tree-shaking, ensuring that only the required functionality is included in your final bundle. - -[Vite](https://vitejs.dev/guide/) is a JavaScript build tool that bundles your frontend code and dependencies for use in the Shopware Administration. - -Install the SDK and Vite: +If you want to learn what the SDK is and what it can do first, see the [Introduction](../introduction.md). -```bash -npm install @shopware-ag/meteor-admin-sdk -npm install vite -``` +## Choose your extension type -#### Import variants +Shopware supports two extension types: **apps** and **plugins**. Both can use the Meteor Admin SDK. -The SDK can be imported in several ways depending on the bundling setup. You can import the SDK wherever you need it in your frontend code, for example in a module that uses it or in an entry file such as `main.js`. +### Apps (recommended) -Import the full SDK (for quick prototyping or when using many SDK features): +Apps run on an external server and communicate with Shopware through a defined API. They are the recommended approach because: -```js -import * as sw from '@shopware-ag/meteor-admin-sdk'; -``` +- They work with **Shopware Cloud** and self-hosted instances +- They can be distributed through the Shopware Store +- The frontend and backend are fully decoupled from the Shopware codebase -Import only the required module (recommended for better tree-shaking and reduced bundle size): +Set up an app: [App Installation Flow](./installation-apps.md) -```js -import { notification } from '@shopware-ag/meteor-admin-sdk'; -``` - -Direct method import (for maximum bundle optimization; imports a specific internal module): - -```js -import { dispatch as dispatchNotification } from '@shopware-ag/meteor-admin-sdk/es/notification'; -``` +### Plugins -The path depends on your build configuration. +Plugins run directly inside the Shopware instance. They have full access to the Shopware PHP codebase but are limited to **self-hosted** environments. -### Configure Vite +Set up a plugin: [Plugin Installation Flow](./installation-plugins.md) -Configure Vite according to your extension’s frontend setup. See the [official Vite documentation](https://vitejs.dev/guide/) for configuration details. +### Migrating an existing plugin -The extension frontend might have a structure similar to this: +If you already have a Twig-based Administration plugin and want to adopt the Meteor Admin SDK incrementally, see the [Migration Guide](../develop/migrating-admin-plugins.md). -```plaintext -custom/plugins/yourPlugin/src/Resources/app/meteor-app -├── index.html -├── vite.config.js (optional) -├── package.json -├── package-lock.json -├── src -│ ├── main.js -``` +## Install the SDK -### Run the development server +There are two ways to include the Meteor Admin SDK in your extension: -Start the Vite development server: +::: code-group -```bash -npx vite +```bash [npm] +npm install @shopware-ag/meteor-admin-sdk ``` -Vite will bundle the SDK and serve the frontend during development. - -### Verify the installation - -If the extension loads in the Administration and the notification example runs successfully, the SDK is installed correctly. - -## Minimal "Hello World" example with the CDN build - -If you do not want to use a build tool, the SDK can also be loaded directly from a CDN. The following example demonstrates the smallest possible working integration. - -Import the source from the CDN, using the latest version: - -```html +```html [cdn] ``` -It is also possible to use a fixed version (example: 1.2.3): -```html - -``` +::: -When using the CDN build, the SDK is available globally as `sw`: +**npm** is recommended for production. It enables bundling and tree-shaking so only the code you use is shipped. -```html - -``` - -If the notification appears in the top-right corner of the Administration, the SDK is working correctly. - -Using the CDN is quick and convenient, making it suitable for prototyping, experimentation, or simple setups without a build pipeline. It is not recommended for production use. +**CDN** is useful for quick prototypes or simple setups without a build pipeline. With the CDN build, the SDK is available globally as `sw` (e.g. `sw.notification.dispatch(...)`). ## Next steps -Choose your extension type: - -- [App Installation Flow](./installation-apps.md) -- [Plugin Installation Flow](./installation-plugins.md) +- [App Installation Flow](./installation-apps.md): Full walkthrough for app setup +- [Plugin Installation Flow](./installation-plugins.md): Full walkthrough for plugin setup +- [API Reference](../api-reference/index.md): All available SDK methods +- [Concepts](../concepts/index.md): Locations, positions, data handling, and more diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index 79486deb1..903519cce 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -71,17 +71,17 @@ Create an HTML file called `my-example-app.html`. This is the page that Shopware ::: code-group -```html [cdn] +```html [npm] - + - notification.dispatch({ + -``` - -::: - -**npm** is recommended for production. It enables bundling and tree-shaking so only the code you use is shipped. +This is the recommended setup. It enables bundling and tree-shaking so only the code you use is shipped. -**CDN** is useful for quick prototypes or simple setups without a build pipeline. With the CDN build, the SDK is available globally as `sw` (e.g. `sw.notification.dispatch(...)`). +If you want to use a CDN instead, see [Without npm](./without-npm.md). ## Next steps - [App Installation Flow](./installation-apps.md): Full walkthrough for app setup - [Plugin Installation Flow](./installation-plugins.md): Full walkthrough for plugin setup +- [Without npm](./without-npm.md): Alternative setup using a plain ` - + + + + + + ``` -```html [cdn] - - - - - - - - - - - -``` - -::: - When using npm, the SDK must be bundled with a build tool like Vite. See the [App development guide](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide). #### Serving the HTML file @@ -120,10 +96,10 @@ Create the file at `demo-app/my-example-app.html` (next to `index.ts` in the app The scaffolded Hono app server does not serve static files by default. Add a route to your `index.ts` that serves the HTML file: ```ts -import { readFileSync } from 'node:fs'; +import { readFileSync } from "node:fs"; -app.get('/my-example-app.html', (c) => { - const html = readFileSync('./my-example-app.html', 'utf-8'); +app.get("/my-example-app.html", (c) => { + const html = readFileSync("./my-example-app.html", "utf-8"); return c.html(html); }); ``` @@ -131,9 +107,9 @@ app.get('/my-example-app.html', (c) => { Alternatively, serve all files from a `public/` folder using Hono's static file middleware: ```ts -import { serveStatic } from '@hono/node-server/serve-static'; +import { serveStatic } from "@hono/node-server/serve-static"; -app.use('/*', serveStatic({ root: './public' })); +app.use("/*", serveStatic({ root: "./public" })); ``` With this approach, place the HTML file at `demo-app/public/my-example-app.html`. @@ -177,7 +153,7 @@ The `` and `` in the manifest must match the `appName` and `appSec configureAppServer(app, { appName: "MyExampleApp", appSecret: "S3cr3tf0re$t", - shopRepository: new BetterSqlite3Repository('shop.db'), + shopRepository: new BetterSqlite3Repository("shop.db"), }); ``` diff --git a/docs/admin-sdk/getting-started/installation-plugins.md b/docs/admin-sdk/getting-started/installation-plugins.md index e365ec758..9cccc165c 100644 --- a/docs/admin-sdk/getting-started/installation-plugins.md +++ b/docs/admin-sdk/getting-started/installation-plugins.md @@ -3,7 +3,6 @@ title: "Plugin Installation Flow" sidebar_position: 30 --- - # Plugin Installation Flow Plugins are supported on self-hosted Shopware instances only. @@ -57,11 +56,11 @@ Leave out `` — it is injecte In `src/main.js`, add a quick test to verify the SDK works: ```js -import { notification } from '@shopware-ag/meteor-admin-sdk'; +import { notification } from "@shopware-ag/meteor-admin-sdk"; notification.dispatch({ - title: 'Hello from your plugin', - message: 'Meteor Admin SDK is working' + title: "Hello from your plugin", + message: "Meteor Admin SDK is working", }); ``` diff --git a/docs/admin-sdk/getting-started/without-npm.md b/docs/admin-sdk/getting-started/without-npm.md new file mode 100644 index 000000000..70bb29c95 --- /dev/null +++ b/docs/admin-sdk/getting-started/without-npm.md @@ -0,0 +1,67 @@ +--- +title: "Without npm" +sidebar_position: 35 +--- + + +# Without npm + +If you want to try the Meteor Admin SDK without setting up npm or a bundler, you can load it directly with a ` +``` + +This exposes the SDK globally as `sw`, for example `sw.notification.dispatch(...)`. + +## Plugins + +In a plugin, you can place the script tag directly into your `index.html` and skip `npm install @shopware-ag/meteor-admin-sdk`. + +```html + + + + + + Your extension + + + + + + + +``` + +## Apps + +In an app, you can also load the SDK directly in `my-example-app.html`. This lets you skip the bundling step from the app installation flow. + +```html + + + + + + + + + + + +``` + +Apps still need the rest of the normal setup: the app server, the HTML file being served, and the `manifest.xml` registration. From 8d36b1a8b8ed51870cf043ededa56bab61097790 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Wed, 1 Apr 2026 23:16:23 +0200 Subject: [PATCH 48/59] docs: remove getRepository documentation and update references to useRepository --- .../composables/getRepository.md | 53 ------------------- .../api-reference/composables/index.md | 3 +- docs/admin-sdk/api-reference/index.md | 1 - .../api-reference/ui/actionButton.md | 6 +-- docs/admin-sdk/docs.yml | 1 + docs/admin-sdk/getting-started/index.md | 2 +- 6 files changed, 5 insertions(+), 61 deletions(-) delete mode 100644 docs/admin-sdk/api-reference/composables/getRepository.md diff --git a/docs/admin-sdk/api-reference/composables/getRepository.md b/docs/admin-sdk/api-reference/composables/getRepository.md deleted file mode 100644 index cc2dfaae8..000000000 --- a/docs/admin-sdk/api-reference/composables/getRepository.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "getRepository" -nav: - position: 10 ---- - - -# getRepository - -The `composables.getRepository` function returns a static repository instance for a given entity. It provides the same repository interface as the [data.repository](../data/repository.md) API, but as a composable that can be called directly inside Vue component setup functions. - -When called inside a Vue component, `getRepository` first checks for an injected `repositoryFactory` (provided by the Administration host). If none is found, it falls back to a lazy-loaded SDK repository that communicates with the Administration via postMessage. - -For a reactive variant that automatically updates when its inputs change, see [useRepository](./useRepository.md). - -## Usage - -```ts -import { composables } from '@shopware-ag/meteor-admin-sdk'; -const { getRepository } = composables; - -const productRepository = getRepository('product'); - -// Search for products -const products = await productRepository.search(criteria); - -// Get a single product -const product = await productRepository.get('some-product-id'); - -// Save changes -await productRepository.save(product); -``` - -## With a custom repository factory - -If you need to provide your own repository factory (for example in tests or custom setups), pass it as the second argument: - -```ts -const productRepository = getRepository('product', (entityName) => { - return myCustomFactory.create(entityName); -}); -``` - -## Parameters - -| Name | Required | Description | -|:--------------------|:---------|:-----------------------------------------------------------------------------------------| -| `entityName` | true | The name of the entity type (e.g. `'product'`, `'category'`, `'order'`) | -| `repositoryFactory` | false | Optional factory function that creates the underlying repository for the given entity | - -## Return value - -A repository instance with the same methods as described in the [Repository API reference](../data/repository.md): `search`, `get`, `save`, `clone`, `hasChanges`, `saveAll`, `delete`, `create`. diff --git a/docs/admin-sdk/api-reference/composables/index.md b/docs/admin-sdk/api-reference/composables/index.md index cd1af5778..103992199 100644 --- a/docs/admin-sdk/api-reference/composables/index.md +++ b/docs/admin-sdk/api-reference/composables/index.md @@ -13,6 +13,5 @@ They simplify common tasks such as accessing repositories or sharing reactive st Currently, the SDK exposes: -- [getRepository](./getRepository.md): Create a static repository instance for a given entity. -- [useRepository](./useRepository.md): Reactive wrapper around `getRepository` that updates when its inputs change. +- [useRepository](./useRepository.md): Create a reactive repository instance for a given entity. - [useSharedState](./useSharedState.md): Share reactive state between different extension components. diff --git a/docs/admin-sdk/api-reference/index.md b/docs/admin-sdk/api-reference/index.md index 6cc7db2a0..618e5674c 100644 --- a/docs/admin-sdk/api-reference/index.md +++ b/docs/admin-sdk/api-reference/index.md @@ -70,7 +70,6 @@ They simplify common patterns such as accessing repositories or sharing state be APIs in this section include: -- [getRepository](./composables/getRepository.md) - [useRepository](./composables/useRepository.md) - [useSharedState](./composables/useSharedState.md) diff --git a/docs/admin-sdk/api-reference/ui/actionButton.md b/docs/admin-sdk/api-reference/ui/actionButton.md index 92ef5d37e..53965dbfe 100644 --- a/docs/admin-sdk/api-reference/ui/actionButton.md +++ b/docs/admin-sdk/api-reference/ui/actionButton.md @@ -67,9 +67,7 @@ if (location.is(location.MAIN_HIDDEN)) { } ``` -## Example - -- Add action button in customer detail page +## Example: Add action button in customer detail page ![Action button example](./assets/add-action-button-example.png) @@ -92,7 +90,7 @@ ui.actionButton.add({ }); ``` -- Add action button in media item +## Example: Add action button in media item ![Action button media example](./assets/add-action-button-media-example.png) diff --git a/docs/admin-sdk/docs.yml b/docs/admin-sdk/docs.yml index f62ccc542..2d491b288 100644 --- a/docs/admin-sdk/docs.yml +++ b/docs/admin-sdk/docs.yml @@ -18,3 +18,4 @@ redirects: api-reference/ui/paymentOverviewCard.html: api-reference/ui/purchases-and-payments/paymentOverviewCard.html api-reference/notification.html: api-reference/ui/notification.html api-reference/toast.html: api-reference/ui/toast.html + api-reference/composables/getRepository.html: api-reference/composables/useRepository.html diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index 67cbeb82c..6e6c4be4c 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -14,7 +14,7 @@ If you want to learn what the SDK is and what it can do first, see the [Introduc Shopware supports two extension types: **apps** and **plugins**. Both can use the Meteor Admin SDK. -### Apps (recommended) +### Apps Apps run on an external server and communicate with Shopware through a defined API. They are the recommended approach because: From 4027a964744d2f104244df31fc44e31dbec1daf1 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Thu, 2 Apr 2026 09:06:12 +0200 Subject: [PATCH 49/59] docs: fix inconsistencies - Added return value descriptions for various methods in the CMS, data, and UI sections. - Updated method names in the context and location sections for consistency. - Improved usage examples and parameter descriptions across multiple API references. - Removed redundant sections and clarified the purpose of certain methods. - Ensured all methods return a promise without data where applicable. --- .../api-reference/cms/registerCmsBlock.md | 5 + .../api-reference/cms/registerCmsElement.md | 6 ++ .../composables/useRepository.md | 9 -- .../composables/useSharedState.md | 10 +- docs/admin-sdk/api-reference/context.md | 28 +++--- docs/admin-sdk/api-reference/data/get.md | 40 +++++--- .../admin-sdk/api-reference/data/subscribe.md | 47 +++++---- docs/admin-sdk/api-reference/data/update.md | 29 ++++-- docs/admin-sdk/api-reference/location.md | 95 ++++++++++++------- .../api-reference/ui/actionButton.md | 6 ++ .../api-reference/ui/component-sections.md | 82 ++++++++-------- docs/admin-sdk/api-reference/ui/mainModule.md | 12 +++ docs/admin-sdk/api-reference/ui/mediaModal.md | 6 +- docs/admin-sdk/api-reference/ui/menu.md | 42 ++++++-- docs/admin-sdk/api-reference/ui/modals.md | 18 +++- .../api-reference/ui/notification.md | 57 ++++++----- .../in-app-purchases.md | 21 +++- .../paymentOverviewCard.md | 32 ++++++- .../api-reference/ui/settingsItem.md | 8 +- docs/admin-sdk/api-reference/ui/sidebars.md | 18 +++- docs/admin-sdk/api-reference/ui/tabs.md | 8 +- docs/admin-sdk/api-reference/ui/toast.md | 29 +++--- 22 files changed, 387 insertions(+), 221 deletions(-) diff --git a/docs/admin-sdk/api-reference/cms/registerCmsBlock.md b/docs/admin-sdk/api-reference/cms/registerCmsBlock.md index 6fe05fee1..4cf522924 100644 --- a/docs/admin-sdk/api-reference/cms/registerCmsBlock.md +++ b/docs/admin-sdk/api-reference/cms/registerCmsBlock.md @@ -12,6 +12,8 @@ With `cms.registerCmsBlock` you can register CMS blocks to use in the Shopping E ![Register a CMS block in your Shopping Experiences Module via App](../assets/register-cms-block-example.png) +## registerCmsBlock() + #### Usage ```ts @@ -44,6 +46,9 @@ cms.registerCmsBlock({ | `previewImage` | false | The URL of the preview image. This image is shown in the Shopping Experiences Module when selecting the CMS block. | | `slotLayout` | false | The layout of the slots. This is used to define the grid layout of the slots. You can use the [CSS grid shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) here. | +#### Return value + +Returns a promise without data. ## Storefront usage diff --git a/docs/admin-sdk/api-reference/cms/registerCmsElement.md b/docs/admin-sdk/api-reference/cms/registerCmsElement.md index 45a694965..5aed06f9b 100644 --- a/docs/admin-sdk/api-reference/cms/registerCmsElement.md +++ b/docs/admin-sdk/api-reference/cms/registerCmsElement.md @@ -13,6 +13,8 @@ More information on how to develop CMS elements can be found in these guides for ![Register a CMS element in your Shopping Experiences Module via App](../assets/register-cms-element-example.png) +## registerCmsElement() + #### Usage ```ts @@ -37,3 +39,7 @@ void cms.registerCmsElement({ | `name` | true | The name of the cms element, which will also be used to generate locationIds - Should have vendor prefix | | `label` | true | The label, which is visible when selecting the cms element - Use snippet keys here! | | `defaultConfig` | true | Object containing the defaultConfig; same like in plugin development. | + +#### Return value + +Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/composables/useRepository.md b/docs/admin-sdk/api-reference/composables/useRepository.md index e69d06740..2f600f389 100644 --- a/docs/admin-sdk/api-reference/composables/useRepository.md +++ b/docs/admin-sdk/api-reference/composables/useRepository.md @@ -33,15 +33,6 @@ const repository = useRepository("product", myRepositoryFactory); const products = await repository.value.search(criteria); ``` -## Dynamic repository creation - -The main advantage of `useRepository` is that it automatically recreates the repository when its inputs change: - -1. If the entity name changes, a new repository for the different entity type is created -2. If the repository factory changes, a new repository using the different factory is created - -This reactivity is implemented using Vue's computed properties, ensuring that the repository is only recreated when necessary. - ## Parameters | Name | Required | Description | diff --git a/docs/admin-sdk/api-reference/composables/useSharedState.md b/docs/admin-sdk/api-reference/composables/useSharedState.md index 851f62e01..d6dda99c8 100644 --- a/docs/admin-sdk/api-reference/composables/useSharedState.md +++ b/docs/admin-sdk/api-reference/composables/useSharedState.md @@ -10,8 +10,6 @@ The `composables.useSharedState` function allows you to create shared state acro The value stored within the shared state can be any data type that can be serialized to JSON. Additionally, we have added support for Entities and EntityCollections. -## Why use `useSharedState`? - `useSharedState` solves a different problem than a normal Vue store: - It synchronizes data between multiple SDK locations and iframes. @@ -23,9 +21,7 @@ If your state only lives inside a single Vue application, Pinia is still a good ![useSharedState demo](../assets/useSharedState-demo.gif) -## Reference - -#### Usage +## Usage ```ts // Inside a Vue component setup @@ -38,13 +34,13 @@ const mySharedStateValue = useSharedState( ); ``` -#### Parameters +## Parameters | Name | Required | Description | | :------------- | :------- | :------------------------------------------------------------------------ | | `key` | true | The unique key used to share the state across different places | | `initial data` | true | The initial data value used when no data exists in the local shared state | -#### Return value +## Return value Returns a reactive state object with a `value` property. Reading or updating `value` accesses the shared state for the given key across all matching SDK locations. diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index 884efa425..b365cfb71 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -13,7 +13,7 @@ This is useful for adapting extension behavior based on the current Administrati import { context } from "@shopware-ag/meteor-admin-sdk"; ``` -## context.getLanguage() +## getLanguage() Returns the current Administration language ID and the system default language ID. Use this to load the correct translations or filter data by language. @@ -45,7 +45,7 @@ Promise<{ } ``` -## context.subscribeLanguage() +## subscribeLanguage() Subscribes to language changes in the Administration. The callback fires whenever the user switches languages, allowing extensions to react immediately (e.g. reloading translated content). @@ -81,7 +81,7 @@ context.subscribeLanguage(({ languageId, systemLanguageId }) => { } ``` -## context.getEnvironment() +## getEnvironment() Returns the current Administration environment mode. Use this to enable debug features or disable analytics in non-production environments. @@ -107,7 +107,7 @@ Promise<"development" | "production" | "testing">; "development"; ``` -## context.getLocale() +## getLocale() Returns the browser locale used by the Administration UI, including a fallback locale. Use this to format dates, numbers, or currencies according to the user's regional settings. @@ -139,7 +139,7 @@ Promise<{ } ``` -## context.subscribeLocale() +## subscribeLocale() Subscribes to locale changes in the Administration. The callback fires whenever the locale changes, allowing extensions to re-render locale-dependent content like formatted dates or currencies. @@ -175,7 +175,7 @@ context.subscribeLocale(({ locale, fallbackLocale }) => { } ``` -## context.getCurrency() +## getCurrency() Returns the system currency configured for the Shopware instance. Use this when displaying prices or working with monetary values. @@ -207,7 +207,7 @@ Promise<{ } ``` -## context.getShopwareVersion() +## getShopwareVersion() Returns the Shopware version as a string. Use this to conditionally enable features or check compatibility before using newer APIs. @@ -233,7 +233,7 @@ string; "6.4.0.0"; ``` -## context.compareShopwareVersion() +## compareShopwareVersion() Compares the current Shopware version against a target version. The current Shopware version is always the left-hand side of the comparison — so `context.compareShopwareVersion('>=', '7.0.0')` reads as "is the current Shopware version equal to or greater than 7.0.0?" @@ -270,7 +270,7 @@ boolean; true; ``` -## context.getAppInformation() +## getAppInformation() Returns metadata about the current app or plugin, including its name, version, type, and granted privileges. Use this to adapt behavior based on the extension type or check which permissions were granted. @@ -312,7 +312,7 @@ Promise<{ } ``` -## context.getUserInformation() +## getUserInformation() Returns details about the currently logged-in Administration user, including their roles, email, and admin status. Use this to personalize the extension UI or check user permissions. @@ -371,7 +371,7 @@ Promise<{ } ``` -## context.getUserTimezone() +## getUserTimezone() Returns the timezone setting of the currently logged-in user. Use this to display dates and times in the user's local timezone. @@ -395,7 +395,7 @@ Promise; This function returns a Promise that resolves to a string representing the user's timezone. -## context.getModuleInformation() +## getModuleInformation() Returns the list of all registered extension modules (created by adding menu items, settings items, etc.). Use the module ID to navigate between extensions. @@ -446,7 +446,7 @@ Promise<{ } ``` -## context.getShopId() +## getShopId() Returns the unique shop ID used by Shopware's app system. Use this to identify the shop instance when communicating with external services. @@ -468,7 +468,7 @@ No parameters needed. Promise; ``` -## context.can() +## can() Checks whether a specific privilege is granted for the current app. Use this to conditionally show features that require specific permissions. diff --git a/docs/admin-sdk/api-reference/data/get.md b/docs/admin-sdk/api-reference/data/get.md index 620f009d5..ed27cda40 100644 --- a/docs/admin-sdk/api-reference/data/get.md +++ b/docs/admin-sdk/api-reference/data/get.md @@ -12,20 +12,36 @@ Compared to `data.subscribe`, `data.get` only gives you the current state of the [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. -## Usage +## data.get() -```ts -import { data } from '@shopware-ag/meteor-admin-sdk'; +`get()` returns the current value of a dataset once. Compared to `subscribe()`, it does not continue listening for updates. + +#### Usage -data.get({ - id: 'sw-product-detail__product', - selectors: ['name', 'manufacturer.name'], -}).then((product) => { +```ts +import { data } from "@shopware-ag/meteor-admin-sdk"; + +data + .get({ + id: "sw-product-detail__product", + selectors: ["name", "manufacturer.name"], + }) + .then((product) => { console.log(product); -}); + }); ``` -## Output +#### Parameters + +| Name | Required | Description | +| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------ | +| `options` | true | Containing the unique `id` and optional `selectors`. Read more about selectors [here](../../concepts/selectors.md). | + +#### Return value + +Returns a promise that resolves with the current dataset value. + +For example: ```json { @@ -35,9 +51,3 @@ data.get({ } } ``` - -## Parameters - -| Name | Required | Description | -| :-------- | :------- |:---------------------------------------------------------------------------------------------------------------------| -| `options` | true | Containing the unique `id` and optional `selectors`. Read more about selectors [here](../../concepts/selectors.md). | diff --git a/docs/admin-sdk/api-reference/data/subscribe.md b/docs/admin-sdk/api-reference/data/subscribe.md index cd3a469f5..632e41129 100644 --- a/docs/admin-sdk/api-reference/data/subscribe.md +++ b/docs/admin-sdk/api-reference/data/subscribe.md @@ -4,30 +4,45 @@ nav: position: 40 --- - # Subscribe -With `data.subscribe`, you can subscribe to changes in the dataset. +With `data.subscribe`, you can subscribe to changes in the dataset. Every time the dataset you subscribed to changes, the callback will be called with the new data. An individual dataset is referenced by an ID. [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. -## Usage +## data.subscribe() + +`subscribe()` listens for dataset changes and calls your callback every time Shopware publishes a new value for the given dataset id. + +#### Usage ```ts -import { data } from '@shopware-ag/meteor-admin-sdk'; +import { data } from "@shopware-ag/meteor-admin-sdk"; data.subscribe( - 'sw-product-detail__product', - ({id, data}) => { - console.log(data); - }, - { - selectors: ['name', 'manufacturer.name'] - }, + "sw-product-detail__product", + ({ id, data }) => { + console.log(data); + }, + { + selectors: ["name", "manufacturer.name"], + }, ); ``` -## Output +#### Parameters + +| Name | Required | Description | +| :--------- | :------- | :---------------------------------------------------------------------------------------------------- | +| `id` | true | The unique id of the dataset you want to receive | +| `callback` | true | A callback function which will be called every time the Shopware Administration publishes the dataset | +| `options` | false | Allows to specify `selectors`. Read more about selectors [here](../../concepts/selectors.md) | + +#### Return value + +Returns an unsubscribe function. Call it to stop listening for dataset updates. + +For example: ```json { @@ -37,11 +52,3 @@ data.subscribe( } } ``` - -## Parameters - -| Name | Required | Description | -| :---------- | :------- |:------------------------------------------------------------------------------------------------------| -| `id` | true | The unique id of the dataset you want to receive | -| `callback` | true | A callback function which will be called every time the Shopware Administration publishes the dataset | -| `options` | false | Allows to specify `selectors`. Read more about selectors [here](../../concepts/selectors.md) | diff --git a/docs/admin-sdk/api-reference/data/update.md b/docs/admin-sdk/api-reference/data/update.md index 6249e96e7..70d9b489f 100644 --- a/docs/admin-sdk/api-reference/data/update.md +++ b/docs/admin-sdk/api-reference/data/update.md @@ -4,28 +4,37 @@ nav: position: 50 --- - # Update With `data.update` you can update datasets from the Shopware Administration. [The data handling guide](../../concepts/datahandling.md) explains how to find available datasets. -## Usage +## data.update() + +`update()` sends new data for a registered dataset to the Shopware Administration. + +#### Usage ```ts -import { data } from '@shopware-ag/meteor-admin-sdk'; +import { data } from "@shopware-ag/meteor-admin-sdk"; -data.update({ - id: 'sw-product-detail__product', +data + .update({ + id: "sw-product-detail__product", data: { - name: 'My updated name', + name: "My updated name", }, -}).then(() => { - console.log('success'); -}); + }) + .then(() => { + console.log("success"); + }); ``` -## Parameters +#### Parameters | Name | Required | Description | | :-------- | :------- | :------------------------------------------------- | | `options` | true | An object containing the id and the data to update | + +#### Return value + +Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/location.md b/docs/admin-sdk/api-reference/location.md index c9b627bae..5ac20bd28 100644 --- a/docs/admin-sdk/api-reference/location.md +++ b/docs/admin-sdk/api-reference/location.md @@ -17,11 +17,11 @@ import { location } from "@shopware-ag/meteor-admin-sdk"; See [Locations](../concepts/locations.md) for a full explanation of the concept. -## Location checks +## is() -### Check the current location ID +Check whether the current location matches the given location ID. Use this to decide which view to render or which extension logic to run for the active iframe. -Check if the current location matches the given location ID: +#### Usage ```ts if (location.is("my-location-id")) { @@ -39,9 +39,11 @@ if (location.is("my-location-id")) { Returns a boolean. It is `true` if the location ID matches the current location. -### Get the current location ID +## get() -Get the name of the current location ID: +Get the current location ID. + +#### Usage ```ts const currentLocation = location.get(); @@ -51,10 +53,11 @@ const currentLocation = location.get(); Returns a string with the name of the current location. -### Check if current location is inside iFrame +## isIframe() + +Check whether the current code runs inside an SDK iframe. This is mainly useful for hybrid extensions that combine plugin logic with Extension SDK logic, especially in Shopware 6.6 and lower. -Useful for hybrid extensions which are using plugin and Extension SDK functionalities together (Shopware 6.6 and lower). You can use this -check to separate code which should be executed inside the Extension SDK context and the plugin context. +#### Usage ```ts if (location.isIframe()) { @@ -66,19 +69,19 @@ if (location.isIframe()) { } ``` -## iFrame heights - #### Parameters No parameters needed. #### Return value -Returns a boolean. Returns `true` if executed inside an iFrame. +Returns `true` if the current code is executed inside an iframe. Otherwise returns `false`. -### Update the height of the location iFrame +## updateHeight() -Update the height of the iFrame with this method: +Update the height of the current location iframe. If no value is provided, the height is calculated automatically from the current content. + +#### Usage ```ts location.updateHeight(750); @@ -88,18 +91,20 @@ location.updateHeight(750); | Name | Required | Default | Description | | :-------------- | :------- | :------------- | :------------------------------------------------------------------------------------------------------------- | -| `iFrame height` | false | Auto generated | The height of the iFrame. If no value is provided it will be automatically calculated from the current height. | +| `height` | false | Auto generated | The height of the iframe. If no value is provided, it is calculated automatically from the current content height. | #### Return value This method does not have a return value. -### Start auto resizing of the iFrame height +## startAutoResizer() -This method starts the auto resizer of the iFrame height. +Start automatically resizing the current location iframe whenever the content height changes. ![Auto resizing example](../concepts/assets/auto-resizer.gif) +#### Usage + ```ts location.startAutoResizer(); ``` @@ -112,9 +117,11 @@ No parameters needed. This method does not have a return value. -### Stop auto resizing of the iFrame height +## stopAutoResizer() -This method stops the auto resizer of the iFrame height: +Stop the automatic iframe height updates started by `location.startAutoResizer()`. + +#### Usage ```ts location.stopAutoResizer(); @@ -128,16 +135,13 @@ No parameters needed. This method does not have a return value. -## URL changes inside your app +## updateUrl() > Available since Shopware v6.6.8.0 -You can track and emit your URL changes only inside your own main module or settings page. - -### Update URL +Send the current iframe URL to the Administration. This only applies inside your own main module or settings page. When the user reloads the whole page, the iframe can be restored to the last URL you sent. -Send the current URL of your iFrame to the administration. When the user reloads the whole page your iFrame will get the -last page you sent to the administration: +#### Usage ```ts const currentUrl = window.location.href; @@ -147,23 +151,50 @@ location.updateUrl(new URL(currentUrl)); #### Parameters -| Name | Required | Default | Description | -| :-------------- | :------- | :------ | :------------------------------------ | -| First parameter | true | | An URL object which contains your URL | +| Name | Required | Default | Description | +| :---- | :------- | :------ | :--------------------------- | +| `url` | true | | A `URL` object with your URL | -### Start automatic URL updates +#### Return value -To avoid manually sending URL changes, use this helper method that automatically sends changes in the URL to the -Administration: +This method does not have a return value. + +## startAutoUrlUpdater() + +> Available since Shopware v6.6.8.0 + +Start automatically sending URL changes from your iframe to the Administration. This only applies inside your own main module or settings page. + +#### Usage ```ts location.startAutoUrlUpdater(); ``` -### Stop automatic URL updates +#### Parameters -Stop automatic URL updaters by calling this method: +No parameters needed. + +#### Return value + +This method does not have a return value. + +## stopAutoUrlUpdater() + +> Available since Shopware v6.6.8.0 + +Stop the automatic URL updates started by `location.startAutoUrlUpdater()`. + +#### Usage ```ts location.stopAutoUrlUpdater(); ``` + +#### Parameters + +No parameters needed. + +#### Return value + +This method does not have a return value. diff --git a/docs/admin-sdk/api-reference/ui/actionButton.md b/docs/admin-sdk/api-reference/ui/actionButton.md index 53965dbfe..94ded8d01 100644 --- a/docs/admin-sdk/api-reference/ui/actionButton.md +++ b/docs/admin-sdk/api-reference/ui/actionButton.md @@ -12,6 +12,8 @@ Action buttons are typically used to trigger extension-specific actions such as ## actionButton.add() +#### Usage + ```ts import { location, ui } from "@shopware-ag/meteor-admin-sdk"; @@ -40,6 +42,10 @@ if (location.is(location.MAIN_HIDDEN)) { | `fileTypes` | false | Media file types you want the action button to be displayed for. Available since Shopware v6.7.6.0. | | `callback` | true | The callback function where you receive the entity and the entityIds for further processing | +#### Return value + +Returns a promise without data. + ## Calling app actions As an app developer you may want to receive the information of the callback function server side. diff --git a/docs/admin-sdk/api-reference/ui/component-sections.md b/docs/admin-sdk/api-reference/ui/component-sections.md index 0183caa59..393ebd4c4 100644 --- a/docs/admin-sdk/api-reference/ui/component-sections.md +++ b/docs/admin-sdk/api-reference/ui/component-sections.md @@ -10,11 +10,11 @@ Component sections allow extensions to render UI components inside existing Admi See the [Component Sections concept](../../concepts/component-sections.md) for an overview. -## Add +## componentSection.add() Add a new component to a component section. -### General usage +#### Usage ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; @@ -36,16 +36,16 @@ ui.componentSection.add({ #### Return value -This method does not have a return value. +Returns a promise without data. ## Available components ### Card -#### Properties +##### Properties | Name | Required | Default | Description | -|:-------------|:---------|:--------|:-----------------------------------| +| :----------- | :------- | :------ | :--------------------------------- | | `title` | false | | The main title of the card | | `subtitle` | false | | The subtitle of the card | | `locationId` | true | | The locationId for the custom view | @@ -54,17 +54,17 @@ This method does not have a return value. #### Example: Add a component to the product page ```js -import { ui } from '@shopware-ag/meteor-admin-sdk'; +import { ui } from "@shopware-ag/meteor-admin-sdk"; ui.componentSection.add({ - component: 'card', - positionId: 'sw-product-properties__before', - props: { - title: 'Hello from plugin', - subtitle: 'I am before the properties card', - locationId: 'my-awesome-app-card-before' - } -}) + component: "card", + positionId: "sw-product-properties__before", + props: { + title: "Hello from plugin", + subtitle: "I am before the properties card", + locationId: "my-awesome-app-card-before", + }, +}); ``` ![Card component example](./assets/example-card.png) @@ -72,43 +72,43 @@ ui.componentSection.add({ #### Example: Add tabs to the card ```js -import { ui } from '@shopware-ag/meteor-admin-sdk'; +import { ui } from "@shopware-ag/meteor-admin-sdk"; ui.componentSection.add({ - component: 'card', - positionId: 'sw-product-properties__before', - props: { - title: 'Hello from plugin', - subtitle: 'I am before the properties card', - locationId: 'my-awesome-app-card-before', - // Render tabs and custom tab content with the provided location id - tabs: [ - { - name: 'example-tab-1', - label: 'First tab', - locationId: 'example-tab-1' - }, - { - name: 'example-tab-2', - label: 'Second tab', - locationId: 'example-tab-2' - } - ], - } -}) + component: "card", + positionId: "sw-product-properties__before", + props: { + title: "Hello from plugin", + subtitle: "I am before the properties card", + locationId: "my-awesome-app-card-before", + // Render tabs and custom tab content with the provided location id + tabs: [ + { + name: "example-tab-1", + label: "First tab", + locationId: "example-tab-1", + }, + { + name: "example-tab-2", + label: "Second tab", + locationId: "example-tab-2", + }, + ], + }, +}); ``` To render the tabs introduced in this example, add matching entry points in your extension code using the `locationId` values that you freely chose when registering the component section. Read more about this pattern in [Locations](../../concepts/locations.md). ```js -import { location } from '@shopware-ag/meteor-admin-sdk'; +import { location } from "@shopware-ag/meteor-admin-sdk"; -if (location.is('example-tab-1')) { - document.body.innerHTML = '

First tab content

'; +if (location.is("example-tab-1")) { + document.body.innerHTML = "

First tab content

"; } -if (location.is('example-tab-2')) { - document.body.innerHTML = '

Second tab content

'; +if (location.is("example-tab-2")) { + document.body.innerHTML = "

Second tab content

"; } ``` diff --git a/docs/admin-sdk/api-reference/ui/mainModule.md b/docs/admin-sdk/api-reference/ui/mainModule.md index 7ebf14110..b6e33a37c 100644 --- a/docs/admin-sdk/api-reference/ui/mainModule.md +++ b/docs/admin-sdk/api-reference/ui/mainModule.md @@ -36,6 +36,10 @@ ui.mainModule.addMainModule({ | `displaySearchBar` | false | true | Toggles the sw-page search bar on/off | | `displayLanguageSwitch` | false | false | Toggles sw-page language switch on/off | +#### Return value + +Returns a promise without data. + #### Example ![Main module example](./assets/add-main-module-example.png) @@ -99,6 +103,10 @@ ui.mainModule.addSmartBarButton({ | `onClickCallback` | true | | Callback function which will be called once the button is clicked | | `disabled` | false | false | Toggle disabled state of the button | +#### Return value + +Returns a promise without data. + ## hideSmartBar() Turn the smart bar off as needed. @@ -116,3 +124,7 @@ ui.mainModule.hideSmartBar({ | Name | Required | Default | Description | Available at Shopware | | :----------- | :------- | :------ | :---------------------------------------------------------- | :-------------------- | | `locationId` | true | | The locationId of the module you want to hide the smart bar | v6.6.7.0 | + +#### Return value + +Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index 639584e63..6c5a89304 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -15,7 +15,7 @@ This method allows apps to interact with the Administration's media modal. Two m import { ui } from "@shopware-ag/meteor-admin-sdk"; ``` -## ui.mediaModal.open() +## mediaModal.open() Open the media modal in the current view. @@ -58,9 +58,7 @@ ui.mediaModal.open({ }); ``` -## Save media modal - -### Open save media modal +## mediaModal.openSaveMedia() Open save media modal in the current view. diff --git a/docs/admin-sdk/api-reference/ui/menu.md b/docs/admin-sdk/api-reference/ui/menu.md index 8cc54c3c4..28739760a 100644 --- a/docs/admin-sdk/api-reference/ui/menu.md +++ b/docs/admin-sdk/api-reference/ui/menu.md @@ -8,27 +8,53 @@ nav: Menu items allow extensions to add navigation entries to existing areas of the Shopware Administration menu. -They are typically used to expose extension functionality inside existing admin modules. +They are typically used to expose extension functionality inside existing admin modules. In practice, this refers to the left sidebar navigation of the Administration. ```ts import { ui } from "@shopware-ag/meteor-admin-sdk"; ``` -## Toggle menu +## collapseMenu() > Available since Shopware v6.6.2.0 -The Admin SDK allows you to manipulate the Admin menu of your application. One of the features it provides is the ability to toggle the Admin menu. This is done using the `collapseMenu` and `expandMenu` methods. +Collapse the Administration menu. #### Usage ```ts -ui.menu.collapseMenu(); // To collapse the Admin menu; +ui.menu.collapseMenu(); +``` + +#### Parameters + +This method does not accept parameters. + +#### Return value + +Returns a promise without data. + +## expandMenu() + +> Available since Shopware v6.6.2.0 + +Expand the Administration menu again after it has been collapsed. -ui.menu.expandMenu(); // To expand the Admin menu; +#### Usage + +```ts +ui.menu.expandMenu(); ``` -## Add menu item +#### Parameters + +This method does not accept parameters. + +#### Return value + +Returns a promise without data. + +## addMenuItem() Add a new menu item to the Shopware admin menu. The content of the menu item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. @@ -56,6 +82,10 @@ ui.menu.addMenuItem({ | `parent` | false | 'sw-extension' | Determines under which main menu entry your item is displayed | | `position` | false | 110 | Determines the position of your menu item | +#### Return value + +Returns a promise without data. + #### Example ![Menu item example](./assets/add-menu-item-example.png) diff --git a/docs/admin-sdk/api-reference/ui/modals.md b/docs/admin-sdk/api-reference/ui/modals.md index 1f74f5126..edbec8d81 100644 --- a/docs/admin-sdk/api-reference/ui/modals.md +++ b/docs/admin-sdk/api-reference/ui/modals.md @@ -18,7 +18,7 @@ See also: [Base Options](../base-options.md) for shared configuration options su import { notification, ui } from "@shopware-ag/meteor-admin-sdk"; ``` -## Open modal +## modal.open() Open a new modal in the current view. The content of the modal is determined by your `locationId` or by using plain text with `textContent`. @@ -102,7 +102,11 @@ ui.modal.open({ }); ``` -## Update modal +#### Return value + +Returns a promise without data. + +## modal.update() > Available since Shopware 6.7.1.0 @@ -139,7 +143,11 @@ ui.modal.update({ | `closable` | false | | If set to `false` then the modal can only be closed programmatically | | `buttons` | false | | Array of button configurations which will render buttons in the footer of the modal | -## Close modal +#### Return value + +Returns a promise without data. + +## modal.close() Closes an opened modal. You need use the correct `locationId` of the modal which should get closed. If you don't provide a `locationId` the last modal without a `locationId` gets closed. @@ -154,3 +162,7 @@ ui.modal.close({ locationId: "your-location-id" }); | Name | Required | Default | Description | | :----------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------ | | `locationId` | false | | The locationId of the modal which should get closed. If not provided, the last modal without a locationId will be closed. | + +#### Return value + +Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/ui/notification.md b/docs/admin-sdk/api-reference/ui/notification.md index f22ccf0ea..d88b50b07 100644 --- a/docs/admin-sdk/api-reference/ui/notification.md +++ b/docs/admin-sdk/api-reference/ui/notification.md @@ -4,56 +4,55 @@ nav: position: 55 --- - # Notification Notifications display messages in the Shopware Administration to inform users about events, errors, or completed actions. They remain visible in the notification center (bell icon) until dismissed by the user. See also: [Base Options](../base-options.md) for shared configuration options supported by SDK message APIs. -## Dispatch a notification +## notification.dispatch() ![notification example](../assets/notification-example.jpg) #### Usage ```ts -import { notification } from '@shopware-ag/meteor-admin-sdk'; +import { notification } from "@shopware-ag/meteor-admin-sdk"; function alertYes() { - alert('Yes'); + alert("Yes"); } notification.dispatch({ - title: 'Your title', - message: 'Your message', - variant: 'success', - appearance: 'notification', - growl: true, - actions: [ - { - label: 'Yes', - method: alertYes - }, - { - label: 'No', - method: () => { - alert('No') - } - }, - { - label: 'Cancel', - route: 'https://www.shopware.com', - disabled: false, - } - ] -}) + title: "Your title", + message: "Your message", + variant: "success", + appearance: "notification", + growl: true, + actions: [ + { + label: "Yes", + method: alertYes, + }, + { + label: "No", + method: () => { + alert("No"); + }, + }, + { + label: "Cancel", + route: "https://www.shopware.com", + disabled: false, + }, + ], +}); ``` #### Parameters | Name | Required | Default | Description | -|:-------------|:---------|:---------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| :----------- | :------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | true | | Defines a notification's **title**. | | `message` | true | | Defines a notification's main expression or message to the user. | | `variant` | false | `info` | Defines the notification type. Available `variant` types are `success`, `info`, `warning` and `error`. | @@ -61,6 +60,6 @@ notification.dispatch({ | `growl` | false | `true` | Displays a notification that is overlaying any module. Use `false` to display the notification in the notification center (bell symbol) only. | | `actions` | false | `[]` | Adds clickable buttons to the notification. Each button with a `label` can trigger a `method` or open a `route` (internal route or external link). Buttons can also be disabled using the attribute `disabled`. | -## Return value +#### Return value Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md index 1bcd06751..ea9ee6ad1 100644 --- a/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/in-app-purchases.md @@ -4,25 +4,36 @@ nav: position: 10 --- - # In-App Purchases > Available since Shopware v6.6.9.0 In-App purchases allow apps to unlock different functionality based on purchases made by the user. This guide covers how to start the in-app purchase flow directly from the Administration. -## Start the purchase flow +## purchase() + +Open a modal with details about the feature that can be purchased. -To open a modal with details about the feature that can be purchased: +#### Usage ```ts -import { iap } from '@shopware-ag/meteor-admin-sdk'; +import { iap } from "@shopware-ag/meteor-admin-sdk"; iap.purchase({ - identifier: 'your-in-app-purchase-id', + identifier: "your-in-app-purchase-id", }); ``` +#### Parameters + +| Name | Required | Description | +| :----------- | :------- | :-------------------------------------- | +| `identifier` | true | The id of the in-app purchase to start. | + +#### Return value + +Returns a promise without data. + ## Behavior When called, Shopware opens a purchase modal inside the Administration. The modal guides the merchant through the checkout flow for purchasing or subscribing to the feature. diff --git a/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md b/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md index 4d1a9fc40..cf09c3c25 100644 --- a/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md +++ b/docs/admin-sdk/api-reference/ui/purchases-and-payments/paymentOverviewCard.md @@ -13,7 +13,25 @@ Starting with Shopware **6.4.14.0**, extensions can replace the default payment For example, you might require merchants to complete an onboarding process with your payment provider before enabling the payment method. -## Parameters +## payment.overviewCard.add() + +#### Usage + +```ts +import { ui, location } from '@shopware-ag/meteor-admin-sdk'; + +if (location.is(location.MAIN_HIDDEN)) { + ui.module.payment.overviewCard.add({ + positionId: 'my-custom-payment-overview-position', + paymentMethodHandlers: [ + 'handler_my_custom_payment_method_one', + 'handler_my_custom_payment_method_two', + ], + }); +} +``` + +#### Parameters | Name | Required | Default | Description | |:------------------------|:---------| :------------- |:------------------------------------------------------------------------------------------------------------------------------------| @@ -21,7 +39,13 @@ For example, you might require merchants to complete an onboarding process with | `paymentMethodHandlers` | true | | A list of formatted payment method handlers, which are handled by your component and where the default card should not be rendered. | | `component` | false | | The component name of you custom payment overview card. Only useful, if you have a plugin with a registered component | -## Extension example +#### Return value + +Returns a promise without data. + +#### Example: Inside an extension + +Use the generated `positionId` together with `ui.componentSection.add()` to render your custom card content in the payment overview. ```ts import { ui, location } from '@shopware-ag/meteor-admin-sdk'; @@ -51,7 +75,9 @@ if (location.is('my-custom-payment-overview-position-before')) { } ``` -## Custom plugin component example +#### Example: Custom plugin component + +Plugin extensions can also render a custom registered Administration component directly instead of using a component section. ```ts import { ui } from '@shopware-ag/meteor-admin-sdk'; diff --git a/docs/admin-sdk/api-reference/ui/settingsItem.md b/docs/admin-sdk/api-reference/ui/settingsItem.md index f86a362d8..65b39b3e4 100644 --- a/docs/admin-sdk/api-reference/ui/settingsItem.md +++ b/docs/admin-sdk/api-reference/ui/settingsItem.md @@ -11,7 +11,7 @@ A settings item adds an entry to the Shopware Administration settings area. Use this when your extension provides configurable options that should appear in the central settings section. -## Add settings item +## addSettingsItem() Add a new settings item to the Shopware settings. The content of the settings item module is determined by your `locationId`. A specific view or a set of actions can be triggered based on the `locationId`. @@ -41,9 +41,11 @@ ui.settings.addSettingsItem({ | `displaySmartBar` | false | true | Toggles the sw-page smart bar on/off | | `tab` | false | 'plugins' | Determines in which tab your settings item will be displayed | -## Getting the right icon +#### Return value -If your editor supports TypeScript, you should get auto-completion when importing icons from the Meteor icon package. To browse available icons, see the [Meteor icon kit repository](https://github.com/shopware/meteor/tree/main/packages/icon-kit). +Returns a promise without data. + +To browse available icons, see the [Meteor icon kit repository](https://github.com/shopware/meteor/tree/main/packages/icon-kit). If your editor supports TypeScript, you should also get auto-completion when importing icons from the Meteor icon package. #### Example diff --git a/docs/admin-sdk/api-reference/ui/sidebars.md b/docs/admin-sdk/api-reference/ui/sidebars.md index 62eed42f8..ef2dc3d2c 100644 --- a/docs/admin-sdk/api-reference/ui/sidebars.md +++ b/docs/admin-sdk/api-reference/ui/sidebars.md @@ -12,7 +12,7 @@ A sidebar provides a contextual panel that displays at the right edge of the Adm import { ui } from "@shopware-ag/meteor-admin-sdk"; ``` -## Add a sidebar +## sidebar.add() Add a new sidebar. The content of the sidebar is determined by your `locationId`. @@ -35,11 +35,15 @@ ui.sidebar.add({ | `icon` | true | The icon to display in the sidebar. You can use any icon from the Shopware icon library | 6.7 | | `resizable` | false | Enables horizontal resizing of the sidebar | 6.7.2.0 | +#### Return value + +Returns a promise without data. + #### Example ![Menu item example](./assets/sidebar-example.png) -## Close a sidebar +## sidebar.close() Close an existing sidebar programmatically. @@ -57,7 +61,11 @@ ui.sidebar.close({ | :----------- | :------- | :----------------------------- | :-------------------- | | `locationId` | true | The id of the sidebar to close | 6.7 | -## Remove a sidebar +#### Return value + +Returns a promise without data. + +## sidebar.remove() Remove a sidebar completely from the DOM. @@ -74,3 +82,7 @@ ui.sidebar.remove({ | Name | Required | Description | Available at Shopware | | :----------- | :------- | :------------------------------ | :-------------------- | | `locationId` | true | The id of the sidebar to remove | 6.7 | + +#### Return value + +Returns a promise without data. diff --git a/docs/admin-sdk/api-reference/ui/tabs.md b/docs/admin-sdk/api-reference/ui/tabs.md index e1e3f68bb..9d828e953 100644 --- a/docs/admin-sdk/api-reference/ui/tabs.md +++ b/docs/admin-sdk/api-reference/ui/tabs.md @@ -11,9 +11,9 @@ Tabs allow extensions to add additional tabs to existing Administration pages. They are commonly used to extend entity detail pages such as products, customers, or orders. -## Add tab item +## addTabItem() -Add a new tab item to an existing tab bar. The content of the the new tab item +Add a new tab item to an existing tab bar. The content of the new tab item contains a component section. This works with tab bar's which have routing and also static tab bars. If the tab bar has routing then the route for the tab item will be generated automatically. @@ -36,6 +36,10 @@ ui.tabs('sw-product-detail' /* The positionId of the tab bar*/).addTabItem({ | `label` | true | | The label of the tab bar item | | `componentSectionId` | true | | The Id for for the component section in the tab content | +#### Return value + +Returns a promise without data. + #### Example ![Tab item example](./assets/add-tab-item-example.png) diff --git a/docs/admin-sdk/api-reference/ui/toast.md b/docs/admin-sdk/api-reference/ui/toast.md index 90df569ec..efea5b298 100644 --- a/docs/admin-sdk/api-reference/ui/toast.md +++ b/docs/admin-sdk/api-reference/ui/toast.md @@ -4,7 +4,6 @@ nav: position: 56 --- - # Toast > Available since Shopware v6.6.2.0 @@ -13,38 +12,38 @@ Toasts display short, temporary messages to provide feedback about user actions See also: [Base Options](../base-options.md) for shared configuration options supported by SDK message APIs. -## Dispatch a toast +## toast.dispatch() ![toast example](../assets/toast-example.png) #### Usage ```ts -import { toast } from '@shopware-ag/meteor-admin-sdk'; +import { toast } from "@shopware-ag/meteor-admin-sdk"; function alertYes() { - alert('Yes'); + alert("Yes"); } toast.dispatch({ - msg: 'Your message', - dismissible: true, - type: 'positive', - action: { - label: 'action', - callback: alertYes - }, -}) + msg: "Your message", + dismissible: true, + type: "positive", + action: { + label: "action", + callback: alertYes, + }, +}); ``` #### Parameters | Name | Required | Default | Description | -|:--------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------| +| :------------ | :------- | :------ | :------------------------------------------------------------------------------------------------------------- | | `msg` | true | | Defines a toast's main expression or message to the user. | | `type` | true | | Defines the toast type. Available `types` are `positive`, `informal` and `critical`. | -| `icon` | false | None | An icon that should be displayed in front of your message. | -| `dismissible` | false | `false` | Specifies if the toast can be manually dismissed. | +| `icon` | false | None | An icon that should be displayed in front of your message. | +| `dismissible` | false | `false` | Specifies if the toast can be manually dismissed. | | `action` | false | None | Adds a clickable button to the toast. The button receives a label and a callback which is called once clicked. | #### Return value From e4be5dcd3784b04a68ffc88d376df6f977f401bf Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Thu, 2 Apr 2026 09:08:49 +0200 Subject: [PATCH 50/59] docs: remove CDN usage section and streamline SDK usage instructions --- docs/admin-sdk/getting-started/usage.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/docs/admin-sdk/getting-started/usage.md b/docs/admin-sdk/getting-started/usage.md index b5b8f4462..00aa53847 100644 --- a/docs/admin-sdk/getting-started/usage.md +++ b/docs/admin-sdk/getting-started/usage.md @@ -7,11 +7,9 @@ sidebar_position: 40 After installing the Meteor Admin SDK, you can use it in your extensions. Most extensions should use the NPM package with a bundler such as Vite. This provides proper dependency management, type support, and better integration with modern development workflows. -Alternatively, you can load the SDK via a CDN, which exposes the SDK through the global `sw` object. This approach is mainly useful for simple setups or quick experiments. +## Show a notification -## Using the SDK with NPM (recommended) - -Import the SDK features you need directly into your JavaScript file. +One of the simplest SDK interactions is showing a notification in the Shopware Administration: ```js // import notification toolkit from the SDK @@ -70,18 +68,6 @@ data.subscribe('sw-product-detail', (payload) => { See [Subscribe](../api-reference/data/subscribe.md), [Get](../api-reference/data/get.md), and [Repository](../api-reference/data/repository.md) for more data access patterns. -## Using the SDK via CDN - -If you load the SDK from a CDN, its APIs are available on the global `sw` object. - -```js -// access the "notification" toolkit in the global "sw" object and dispatch a new notification -sw.notification.dispatch({ - title: 'My first notification', - message: 'This was really easy to do' -}); -``` - ## Find more examples For more complete examples and API details, continue with: From aab6a0abb174b1694d21d3ca44650cfe48f82b39 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Thu, 2 Apr 2026 09:39:30 +0200 Subject: [PATCH 51/59] docs: update installation guide for Meteor Admin SDK, add Vite setup instructions and restructure frontend creation steps --- .../getting-started/installation-apps.md | 125 +++++++++++++----- 1 file changed, 91 insertions(+), 34 deletions(-) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index b06b2ad35..c05d13b89 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -47,9 +47,12 @@ To scaffold a new app using the App Server SDK: npx tiged shopware/app-sdk-js/examples/node-hono demo-app cd demo-app -# install dependencies and start the dev server +# install dependencies npm install -npm run dev + +# install the Meteor Admin SDK and Vite for the administration frontend +npm install @shopware-ag/meteor-admin-sdk +npm install -D vite ``` Visit [the App Server SDK guide](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/javascript/01-getting_started.html) for detailed instructions. @@ -60,63 +63,109 @@ Every app must: - Handle the registration handshake - Expose a publicly reachable URL -- Serve an HTML page for the Administration +- Serve the Administration frontend Using the [App Server SDK](https://github.com/shopware/app-sdk-js) is recommended, as it handles the registration handshake, signature verification, webhook handling, and request validation. It is also possible to implement the registration and request validation manually for advanced setups. -### 2. Create the Administration HTML page +The `npx tiged` example gives you the backend for registration and webhook handling. The following steps add the Administration frontend with Vite under `meteor-app/`. + +### 2. Create the Administration frontend in `meteor-app/` -Create an HTML file called `my-example-app.html`. This is the page that Shopware loads inside the Administration when the app is active. +Create the folder `demo-app/meteor-app` with an `index.html` and a `src/main.js`. This is the frontend source that Vite will serve inside the Shopware Administration. + +For the underlying iframe-based architecture, see [Architecture](../concepts/architecture.md) and [Locations](../concepts/locations.md). + +Create `demo-app/meteor-app/index.html`: ```html - + + + My Example App - +
+ ``` -When using npm, the SDK must be bundled with a build tool like Vite. See the [App development guide](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide). +Create `demo-app/meteor-app/src/main.js`: + +```js +import { notification } from "@shopware-ag/meteor-admin-sdk"; + +notification.dispatch({ + title: "Meteor Admin SDK installed", + message: "Your app is connected successfully", +}); +``` -#### Serving the HTML file +### 3. Mount Vite on the app server -Create the file at `demo-app/my-example-app.html` (next to `index.ts` in the app server project). +Instead of serving a standalone HTML file, let the Hono app server serve the Vite frontend under `/admin/`. -The scaffolded Hono app server does not serve static files by default. Add a route to your `index.ts` that serves the HTML file: +In the scaffolded `demo-app/index.ts`, replace the default server startup with a custom HTTP server that forwards `/admin` requests to Vite and everything else to Hono: ```ts import { readFileSync } from "node:fs"; +import { createServer } from "node:http"; +import { getRequestListener } from "@hono/node-server"; + +// Keep your existing Hono app and configureAppServer(...) setup above. + +async function startServer() { + const honoListener = getRequestListener(app.fetch); + const { createServer: createViteServer } = await import("vite"); + + const httpServer = createServer(); + + const vite = await createViteServer({ + root: "./meteor-app", + base: "/admin/", + appType: "custom", + server: { + middlewareMode: true, + hmr: { server: httpServer }, + }, + }); + + httpServer.on("request", (req, res) => { + if (req.url?.startsWith("/admin")) { + vite.middlewares(req, res, async () => { + try { + let html = readFileSync("./meteor-app/index.html", "utf-8"); + html = await vite.transformIndexHtml(req.url, html); + res.writeHead(200, { "Content-Type": "text/html" }); + res.end(html); + } catch (error) { + console.error(error); + res.writeHead(500); + res.end(error instanceof Error ? error.message : "Unknown error"); + } + }); + return; + } -app.get("/my-example-app.html", (c) => { - const html = readFileSync("./my-example-app.html", "utf-8"); - return c.html(html); -}); -``` - -Alternatively, serve all files from a `public/` folder using Hono's static file middleware: + honoListener(req, res); + }); -```ts -import { serveStatic } from "@hono/node-server/serve-static"; + httpServer.listen(PORT, () => { + console.log(`App server running at http://localhost:${PORT}`); + console.log(`Administration frontend: http://localhost:${PORT}/admin/`); + }); +} -app.use("/*", serveStatic({ root: "./public" })); +void startServer(); ``` -With this approach, place the HTML file at `demo-app/public/my-example-app.html`. +This setup serves the Administration entry page at `/admin/`. Because Vite runs in middleware mode on the same path, requests for JavaScript modules, CSS, `@vite/client`, and HMR also work without adding separate static routes. -### 3. Register the Administration page in `manifest.xml` +### 4. Register the Administration page in `manifest.xml` -After the registration handshake is working, add the `` field inside the `` section of the [manifest file](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide#manifest-file). The `` field should contain the app's public URL. +After the registration handshake is working, add the `` field inside the `` section of the [manifest file](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide#manifest-file). It must point to the path where Vite serves the frontend, so in this example that is `/admin/`. As required by Shopware's app system, the `` section must already contain the `registrationUrl` and `secret`. @@ -142,7 +191,7 @@ Create the file at `/custom/apps/MyExampleApp/manifest.xml` in your Shopware ins - http://localhost:3000/my-example-app.html + http://localhost:3000/admin/ ``` @@ -159,7 +208,15 @@ configureAppServer(app, { If name or secret don't match between manifest and app server, the registration handshake will fail. -### 4. Install and activate the app +### 5. Start the dev server + +```bash +npm run dev +``` + +When the server starts successfully, the Administration frontend should be reachable at `http://localhost:3000/admin/`. + +### 6. Install and activate the app ```bash # if you are using Docker, run the following commands inside the container: docker compose exec -it web /bin/bash @@ -167,7 +224,7 @@ bin/console app:install --activate MyExampleApp bin/console cache:clear ``` -### 5. Verify installation +### 7. Verify installation Log in to the Shopware Administration. The notification should appear in the top-right corner on any page (the notification is not bound to a specific module — it appears on every page load). From 225ab082b36d004a67e1b55bc04c8b2bb2534001 Mon Sep 17 00:00:00 2001 From: Gerrit Weiermann Date: Thu, 2 Apr 2026 10:08:39 +0200 Subject: [PATCH 52/59] docs: update installation instructions for Meteor Admin SDK, add Vue installation and modify server setup details --- .../getting-started/installation-apps.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index c05d13b89..3a1c792a5 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -52,6 +52,7 @@ npm install # install the Meteor Admin SDK and Vite for the administration frontend npm install @shopware-ag/meteor-admin-sdk +npm install vue npm install -D vite ``` @@ -107,7 +108,7 @@ notification.dispatch({ Instead of serving a standalone HTML file, let the Hono app server serve the Vite frontend under `/admin/`. -In the scaffolded `demo-app/index.ts`, replace the default server startup with a custom HTTP server that forwards `/admin` requests to Vite and everything else to Hono: +In the scaffolded `demo-app/index.ts`, replace the default server startup `serve(...)` with a custom HTTP server that forwards `/admin` requests to Vite and everything else to Hono: ```ts import { readFileSync } from "node:fs"; @@ -116,6 +117,8 @@ import { getRequestListener } from "@hono/node-server"; // Keep your existing Hono app and configureAppServer(...) setup above. +const PORT = 3000; + async function startServer() { const honoListener = getRequestListener(app.fetch); const { createServer: createViteServer } = await import("vite"); @@ -180,12 +183,17 @@ Create the file at `/custom/apps/MyExampleApp/manifest.xml` in your Shopware ins MyExampleApp - + + This is my first example app + Developer + (c) Developer + 1.0.0 + MIT - http://host.docker.internal:3000/register + http://host.docker.internal:3000/app/register S3cr3tf0re$t @@ -211,7 +219,7 @@ If name or secret don't match between manifest and app server, the registration ### 5. Start the dev server ```bash -npm run dev +npm start ``` When the server starts successfully, the Administration frontend should be reachable at `http://localhost:3000/admin/`. From 1b20a858b2abb40afb9191254b8ea56cd03efdfe Mon Sep 17 00:00:00 2001 From: David Traum Date: Fri, 10 Apr 2026 16:07:16 +0200 Subject: [PATCH 53/59] docs: update code examples --- docs/admin-sdk/api-reference/base-options.md | 2 +- docs/admin-sdk/api-reference/context.md | 16 ++++++++-------- docs/admin-sdk/api-reference/ui/actionButton.md | 10 +++++----- docs/admin-sdk/develop/translations.md | 5 ++++- docs/admin-sdk/getting-started/index.md | 1 - .../getting-started/installation-apps.md | 4 +++- 6 files changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/admin-sdk/api-reference/base-options.md b/docs/admin-sdk/api-reference/base-options.md index ee8936c76..ad4e681e8 100644 --- a/docs/admin-sdk/api-reference/base-options.md +++ b/docs/admin-sdk/api-reference/base-options.md @@ -69,7 +69,7 @@ notification.dispatch({ }); ui.actionButton.add({ - action: 'generate-report', + name: 'generate-report', entity: 'product', view: 'detail', label: 'Generate Report', diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index b365cfb71..77dda0d86 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -233,14 +233,14 @@ string; "6.4.0.0"; ``` -## compareShopwareVersion() +## compareIsShopwareVersion() -Compares the current Shopware version against a target version. The current Shopware version is always the left-hand side of the comparison — so `context.compareShopwareVersion('>=', '7.0.0')` reads as "is the current Shopware version equal to or greater than 7.0.0?" +Compares the current Shopware version against a target version. The current Shopware version is always the left-hand side of the comparison — so `context.compareIsShopwareVersion('>=', '7.0.0')` reads as "is the current Shopware version equal to or greater than 7.0.0?" #### Usage ```ts -const isRightVersion = await context.compareShopwareVersion(">=", "7.0.0"); +const isRightVersion = await context.compareIsShopwareVersion(">=", "7.0.0"); ``` #### Parameters @@ -253,9 +253,9 @@ const isRightVersion = await context.compareShopwareVersion(">=", "7.0.0"); The function supports both Shopware's four-digit version number and semver versions. The following calls are equivalent: ```ts -await context.compareShopwareVersion(">=", "6.6.4.0"); +await context.compareIsShopwareVersion(">=", "6.6.4.0"); -await context.compareShopwareVersion(">=", "6.4.0"); +await context.compareIsShopwareVersion(">=", "6.4.0"); ``` #### Return value @@ -303,10 +303,10 @@ Promise<{ { name: 'my-extension', version: '1.2.3', - type: 'app' + type: 'app', privileges: { read: [ 'product', 'customer' ], - write: [ 'product' ], + update: [ 'product' ], additional: [ 'system.cache_clear' ] } } @@ -465,7 +465,7 @@ No parameters needed. #### Return value ```ts -Promise; +Promise; ``` ## can() diff --git a/docs/admin-sdk/api-reference/ui/actionButton.md b/docs/admin-sdk/api-reference/ui/actionButton.md index 94ded8d01..5e9700664 100644 --- a/docs/admin-sdk/api-reference/ui/actionButton.md +++ b/docs/admin-sdk/api-reference/ui/actionButton.md @@ -19,7 +19,7 @@ import { location, ui } from "@shopware-ag/meteor-admin-sdk"; if (location.is(location.MAIN_HIDDEN)) { ui.actionButton.add({ - action: "your-app_customer-detail-action", + name: "your-app_customer-detail-action", entity: "customer", view: "detail", label: "Test action", @@ -34,7 +34,7 @@ if (location.is(location.MAIN_HIDDEN)) { | Name | Required | Description | | :----------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `action` | true | A unique name of your action | +| `name` | true | A unique identifier for your action | | `entity` | true | The entity this action is for possible values: `product`, `order`, `category`, `promotion`, `customer` or `media`. Value `media` is available in Shopware version 6.7.1 | | `view` | true | Determines if the action button appears on the listing or detail page, possible values: `detail`,`list` or item. View `item` is only used for entity `media` and in version 6.7.1 | | `label` | true | The label of your action button | @@ -58,7 +58,7 @@ import { location, ui } from "@shopware-ag/meteor-admin-sdk"; if (location.is(location.MAIN_HIDDEN)) { ui.actionButton.add({ - action: "your-app_customer-detail-action", + name: "your-app_customer-detail-action", entity: "customer", view: "detail", label: "Test action", @@ -81,7 +81,7 @@ if (location.is(location.MAIN_HIDDEN)) { import { ui } from "@shopware-ag/meteor-admin-sdk"; ui.actionButton.add({ - action: "your-app_customer-detail-action", + name: "your-app_customer-detail-action", entity: "customer", view: "detail", meteorIcon: "regular-analytics", @@ -104,7 +104,7 @@ ui.actionButton.add({ import { ui } from "@shopware-ag/meteor-admin-sdk"; ui.actionButton.add({ - action: "test-media-button", + name: "test-media-button", entity: "media", view: "item", meteorIcon: "regular-tools-alt", diff --git a/docs/admin-sdk/develop/translations.md b/docs/admin-sdk/develop/translations.md index dc45b4260..0431a0269 100644 --- a/docs/admin-sdk/develop/translations.md +++ b/docs/admin-sdk/develop/translations.md @@ -37,8 +37,11 @@ Snippet files follow the same structure used by the Shopware Administration. Ove Reference snippet keys directly in the UI configuration. Example: ```js -sw.ui.componentSection('sw-manufacturer-card-custom-fields__before').add({ +import { ui } from '@shopware-ag/meteor-admin-sdk'; + +ui.componentSection.add({ component: 'card', + positionId: 'sw-manufacturer-card-custom-fields__before', props: { title: 'my-app-name.example-card.title', subtitle: 'my-app-name.example-card.subtitle', diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index 6e6c4be4c..b9eaa8c51 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -19,7 +19,6 @@ Shopware supports two extension types: **apps** and **plugins**. Both can use th Apps run on an external server and communicate with Shopware through a defined API. They are the recommended approach because: - They work with **Shopware Cloud** and self-hosted instances -- They can be distributed through the Shopware Store - The frontend and backend are fully decoupled from the Shopware codebase Set up an app: [App Installation Flow](./installation-apps.md) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index 3a1c792a5..50a212ae5 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -16,7 +16,9 @@ This guide discusses two SDKs: Each Shopware app must be hosted on its own domain. -It is NOT possible to host multiple apps under the same domain using different subfolders. Instead, use subdomains for each app. +It is NOT possible to host multiple apps under the same domain using different subfolders such as `your-company.com/app-one` and `your-company.com/app-two`. + +This is because the browser security model uses the app's **origin** (`scheme + host + port`) to isolate apps, and the path is not part of that origin. Apps hosted under different subfolders would still share the same origin, so they are not treated as separate apps. For more details, see the [FAQ entry](https://developer.shopware.com/resources/admin-extension-sdk/faq/#can-i-use-the-same-domain-with-subfolders-for-multiple-apps). Instead, use a dedicated subdomain for each app. Example: From 9bc7c9b395c97ba435a6d37f19da3beca20392c5 Mon Sep 17 00:00:00 2001 From: David Traum Date: Tue, 14 Apr 2026 15:35:14 +0200 Subject: [PATCH 54/59] chore: doc updates --- docs/admin-sdk/api-reference/data/repository.md | 8 ++++++-- docs/admin-sdk/api-reference/ui/mediaModal.md | 8 ++++---- docs/admin-sdk/api-reference/window.md | 10 +++++----- docs/admin-sdk/introduction.md | 2 +- 4 files changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/admin-sdk/api-reference/data/repository.md b/docs/admin-sdk/api-reference/data/repository.md index acb2a87c0..20e2c2137 100644 --- a/docs/admin-sdk/api-reference/data/repository.md +++ b/docs/admin-sdk/api-reference/data/repository.md @@ -150,14 +150,18 @@ Clones an existing entity ```ts const exampleRepository = data.repository('your_entity'); -const clonedEntityId = await exampleRepository.clone('theEntityIdToClone'); +const clonedEntityId = await exampleRepository.clone( + 'theEntityIdToClone', + yourApiContext +); ``` #### Parameters | Name | Required | Default | Description | | :--------- | :------- | :------ | :--------------------------------------------- | | `entityId` | true | | The entity id which should be cloned | -| `context` | false | {} | Change the [request context](#request-context) | +| `context` | true | | Change the [request context](#request-context) | +| `behavior` | false | | Optional clone behavior passed as the third argument | #### Return value This method returns the id of the cloned entity. diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index 6c5a89304..333d09654 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -27,7 +27,7 @@ ui.mediaModal.open({ allowMultiSelect: false, fileAccept: "image/png", selectors: ["fileName", "id", "url"], - callback: ({ fileName, id, url }) => {}, + callback: (mediaSelections) => {}, }); ``` @@ -42,8 +42,8 @@ All parameters are similar to the `sw-media-modal-v2` component's props. | `allowMultiSelect` | false | true | Define single or multiple selection | | `defaultTab` | false | library | Defines which tab should be opened by default | | `fileAccept` | false | image/\* | Define the file types which are allowed to be uploaded in Upload tab | -| `selectors` | false | ['fileName', 'id', 'url'] | Selected properties which should be returned in callback function | -| `callback` | true | | Callback function which will be called once the media item is selected. | +| `selectors` | false | ['fileName', 'id', 'url'] | Selected properties which should be returned for each item in the callback array | +| `callback` | true | | Callback function which receives an array of selected media items once a selection is made. | #### Example @@ -54,7 +54,7 @@ ui.mediaModal.open({ initialFolderId: "productMediaFolderId", allowMultiSelect: false, selectors: ["fileName", "id", "url"], - callback: ({ fileName, id, url }) => {}, + callback: (mediaSelections) => {}, }); ``` diff --git a/docs/admin-sdk/api-reference/window.md b/docs/admin-sdk/api-reference/window.md index 1edd09631..7b175c843 100644 --- a/docs/admin-sdk/api-reference/window.md +++ b/docs/admin-sdk/api-reference/window.md @@ -104,7 +104,7 @@ Returns a unique identifier for the current browser window. This is useful when #### Usage ```ts -adminWindow.getId(); +await adminWindow.getId(); ``` #### Parameters @@ -113,14 +113,14 @@ No parameters required. #### Return value -A `string` representing a unique identifier for the current window. +A `Promise` that resolves to a unique identifier for the current window. #### Example This example clears `sessionStorage` when a duplicated browser tab is detected. This can happen if a user uses the _Duplicate Tab_ feature of some browsers. ```ts -const windowId = adminWindow.getId(); +const windowId = await adminWindow.getId(); const storedWindowId = globalThis.sessionStorage.getItem("window-id"); if (windowId !== storedWindowId) { @@ -138,7 +138,7 @@ Retrieve the current Administration router path. #### Usage ```ts -adminWindow.getPath(); +await adminWindow.getPath(); ``` #### Parameters @@ -147,4 +147,4 @@ No parameters required. #### Return value -Returns a `string` containing the full path, or an empty string if the router is not available. +Returns a `Promise` containing the full path, or an empty string if the router is not available. diff --git a/docs/admin-sdk/introduction.md b/docs/admin-sdk/introduction.md index 4a3212136..925dc8474 100644 --- a/docs/admin-sdk/introduction.md +++ b/docs/admin-sdk/introduction.md @@ -21,7 +21,7 @@ What you can do with the SDK: - Provides a stable, backwards-compatible API for extending the Administration and reducing complexity during Shopware updates - Abstracts internal complexity, so deep knowledge of the Admin internals is not required - Written in [TypeScript](https://www.typescriptlang.org/) with full type safety and auto-completion support -- Lightweight and tree-shakable with no external dependencies, allowing granular imports and small bundle sizes +- Lightweight and tree-shakable, allowing granular imports and small bundle sizes ## Prerequisites From fd09877d7e86593789818a918b7324e63573ef12 Mon Sep 17 00:00:00 2001 From: David Traum Date: Tue, 14 Apr 2026 15:44:17 +0200 Subject: [PATCH 55/59] chore: remove instruction --- docs/admin-sdk/getting-started/installation-apps.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index 50a212ae5..f2833229a 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -18,8 +18,6 @@ Each Shopware app must be hosted on its own domain. It is NOT possible to host multiple apps under the same domain using different subfolders such as `your-company.com/app-one` and `your-company.com/app-two`. -This is because the browser security model uses the app's **origin** (`scheme + host + port`) to isolate apps, and the path is not part of that origin. Apps hosted under different subfolders would still share the same origin, so they are not treated as separate apps. For more details, see the [FAQ entry](https://developer.shopware.com/resources/admin-extension-sdk/faq/#can-i-use-the-same-domain-with-subfolders-for-multiple-apps). Instead, use a dedicated subdomain for each app. - Example: - `app-one.your-company.com` From b2b0587f85fe5f7d1857923cdffd4fd81eb62173 Mon Sep 17 00:00:00 2001 From: David Traum Date: Tue, 14 Apr 2026 15:45:41 +0200 Subject: [PATCH 56/59] chore: update installation-apps --- docs/admin-sdk/getting-started/installation-apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/getting-started/installation-apps.md b/docs/admin-sdk/getting-started/installation-apps.md index f2833229a..3a1c792a5 100644 --- a/docs/admin-sdk/getting-started/installation-apps.md +++ b/docs/admin-sdk/getting-started/installation-apps.md @@ -16,7 +16,7 @@ This guide discusses two SDKs: Each Shopware app must be hosted on its own domain. -It is NOT possible to host multiple apps under the same domain using different subfolders such as `your-company.com/app-one` and `your-company.com/app-two`. +It is NOT possible to host multiple apps under the same domain using different subfolders. Instead, use subdomains for each app. Example: From 31fd66b65f8724e33dea4f34c26dbfa13af6a88f Mon Sep 17 00:00:00 2001 From: David Traum Date: Wed, 15 Apr 2026 09:51:30 +0200 Subject: [PATCH 57/59] chore: add description for clone behavior, remove semicolons, change broken links --- docs/admin-sdk/api-reference/context.md | 24 +++++++++---------- .../api-reference/data/repository.md | 21 +++++++++++++++- docs/admin-sdk/api-reference/ui/mediaModal.md | 4 ++-- docs/admin-sdk/docs.yml | 4 ++-- 4 files changed, 36 insertions(+), 17 deletions(-) diff --git a/docs/admin-sdk/api-reference/context.md b/docs/admin-sdk/api-reference/context.md index 77dda0d86..f0f673e1d 100644 --- a/docs/admin-sdk/api-reference/context.md +++ b/docs/admin-sdk/api-reference/context.md @@ -33,7 +33,7 @@ No parameters needed. Promise<{ languageId: string; systemLanguageId: string; -}>; +}> ``` #### Example value @@ -98,7 +98,7 @@ No parameters needed. #### Return value ```ts -Promise<"development" | "production" | "testing">; +Promise<"development" | "production" | "testing"> ``` #### Example value @@ -127,7 +127,7 @@ No parameters needed. Promise<{ locale: string; fallbackLocale: string; -}>; +}> ``` #### Example value @@ -195,7 +195,7 @@ No parameters needed. Promise<{ systemCurrencyId: string; systemCurrencyISOCode: string; -}>; +}> ``` #### Example value @@ -224,7 +224,7 @@ No parameters needed. #### Return value ```ts -string; +string ``` #### Example value @@ -261,7 +261,7 @@ await context.compareIsShopwareVersion(">=", "6.4.0"); #### Return value ```ts -boolean; +boolean ``` #### Example value @@ -294,7 +294,7 @@ Promise<{ version: string; type: "app" | "plugin"; privileges: privileges; -}>; +}> ``` #### Example value @@ -349,7 +349,7 @@ Promise<{ title: string; type: string; username: string; -}>; +}> ``` #### Example value @@ -390,7 +390,7 @@ No parameters needed. #### Return value ```ts -Promise; +Promise ``` This function returns a Promise that resolves to a string representing the user's timezone. @@ -428,7 +428,7 @@ Promise<{ id: string; locationId: string; }>; -}>; +}> ``` #### Example value @@ -465,7 +465,7 @@ No parameters needed. #### Return value ```ts -Promise; +Promise ``` ## can() @@ -489,5 +489,5 @@ const isAllowed: boolean = await context.can("product:read"); #### Return value ```ts -boolean; +boolean ``` diff --git a/docs/admin-sdk/api-reference/data/repository.md b/docs/admin-sdk/api-reference/data/repository.md index 20e2c2137..9e5a2693e 100644 --- a/docs/admin-sdk/api-reference/data/repository.md +++ b/docs/admin-sdk/api-reference/data/repository.md @@ -161,7 +161,7 @@ const clonedEntityId = await exampleRepository.clone( | :--------- | :------- | :------ | :--------------------------------------------- | | `entityId` | true | | The entity id which should be cloned | | `context` | true | | Change the [request context](#request-context) | -| `behavior` | false | | Optional clone behavior passed as the third argument | +| `behavior` | false | | Configure the [clone behavior](#clone-behavior) | #### Return value This method returns the id of the cloned entity. @@ -254,3 +254,22 @@ const exampleContext = { liveVersionId: 'yourLiveVersionId' } ``` + +### Clone Behavior +You can optionally change the clone behavior of the request. The clone behavior controls how the entity is duplicated on the server. + +Use `overwrites` to replace values in the cloned entity before it is written, for example to set a different name or other field values on the copy. + +Use `cloneChildren` to control whether child entities are cloned as well. This value defaults to `true`. + +```ts +const exampleCloneBehavior = { + // Replace values in the cloned entity before it is saved + overwrites: { + name: 'Copy of the original entity', + active: false + }, + // Set to false if child entities should not be cloned + cloneChildren: true +} +``` diff --git a/docs/admin-sdk/api-reference/ui/mediaModal.md b/docs/admin-sdk/api-reference/ui/mediaModal.md index 333d09654..96c22f8f8 100644 --- a/docs/admin-sdk/api-reference/ui/mediaModal.md +++ b/docs/admin-sdk/api-reference/ui/mediaModal.md @@ -27,7 +27,7 @@ ui.mediaModal.open({ allowMultiSelect: false, fileAccept: "image/png", selectors: ["fileName", "id", "url"], - callback: (mediaSelections) => {}, + callback: ([{ fileName, id, url }]) => {}, }); ``` @@ -54,7 +54,7 @@ ui.mediaModal.open({ initialFolderId: "productMediaFolderId", allowMultiSelect: false, selectors: ["fileName", "id", "url"], - callback: (mediaSelections) => {}, + callback: ([{ fileName, id, url }]) => {}, }); ``` diff --git a/docs/admin-sdk/docs.yml b/docs/admin-sdk/docs.yml index 2d491b288..280d0a016 100644 --- a/docs/admin-sdk/docs.yml +++ b/docs/admin-sdk/docs.yml @@ -1,9 +1,9 @@ redirects: api-reference/ui/component-section.html: api-reference/ui/component-sections.html - api-reference/ui/module/paymentOverviewCard.html: api-reference/ui/paymentOverviewCard.html + api-reference/ui/module/paymentOverviewCard.html: api-reference/ui/purchases-and-payments/paymentOverviewCard.html internals/how-it-works.html: concepts/architecture.html internals/datahandling.html: concepts/datahandling.html - api-reference/in-app-purchases/in-app-purchases.html: api-reference/data/in-app-purchases.html + api-reference/in-app-purchases/in-app-purchases.html: api-reference/ui/purchases-and-payments/in-app-purchases.html api-reference/in-app-purchases/index.html: api-reference/data/index.html api-reference/ui/module/index.html: api-reference/ui/index.html faq/index.html: develop/translations.html From b31316f6a989904a65bd58aa945d57bc778f2ccd Mon Sep 17 00:00:00 2001 From: David Traum Date: Wed, 15 Apr 2026 10:05:29 +0200 Subject: [PATCH 58/59] chore: add SaaS mention to app advantages --- docs/admin-sdk/getting-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin-sdk/getting-started/index.md b/docs/admin-sdk/getting-started/index.md index b9eaa8c51..74544ff1a 100644 --- a/docs/admin-sdk/getting-started/index.md +++ b/docs/admin-sdk/getting-started/index.md @@ -18,7 +18,7 @@ Shopware supports two extension types: **apps** and **plugins**. Both can use th Apps run on an external server and communicate with Shopware through a defined API. They are the recommended approach because: -- They work with **Shopware Cloud** and self-hosted instances +- They work with **Shopware Cloud** and self-hosted instances, and they are the only extension type available for **Shopware SaaS** - The frontend and backend are fully decoupled from the Shopware codebase Set up an app: [App Installation Flow](./installation-apps.md) From 928651d96e2c01d0430a23572d849ba88201f4da Mon Sep 17 00:00:00 2001 From: David Traum Date: Thu, 16 Apr 2026 15:21:58 +0200 Subject: [PATCH 59/59] chore: Add title prop to notification --- docs/admin-sdk/api-reference/base-options.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/admin-sdk/api-reference/base-options.md b/docs/admin-sdk/api-reference/base-options.md index ad4e681e8..f463b3a15 100644 --- a/docs/admin-sdk/api-reference/base-options.md +++ b/docs/admin-sdk/api-reference/base-options.md @@ -20,6 +20,7 @@ In this example, the base options are passed on the same object as the method-sp import { notification } from '@shopware-ag/meteor-admin-sdk'; notification.dispatch({ + title: 'Product report ready', message: 'Your product report is ready', /* ... base options ... */ }); @@ -62,6 +63,7 @@ Pass the `privileges` array to any SDK method that supports base options: import { notification, ui } from '@shopware-ag/meteor-admin-sdk'; notification.dispatch({ + title: 'Product report ready', message: 'Your product report is ready', privileges: [ 'product:read',