Add custom action button

Search…
v6.4.0 (stable)
One extension possibility in the administration is the ability to add custom action buttons to the smartbar. For now, you can add them in the smartbar of detail and list views:
Custom action buttons in the Administration
To get those buttons, you start in the admin section of your manifest file. There you can define <action-button> elements in order to add your button, as seen as below:
manifest.xml
1
<?xml version="1.0" encoding="UTF-8"?>
2
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">
3
    <meta>
4
        ...
5
    </meta>
6
    <admin>
7
        <action-button action="setPromotion" entity="promotion" view="detail" url="https://example.com/promotion/set-promotion">
8
            <label>set Promotion</label>
9
        </action-button>
10
        <action-button action="deletePromotion" entity="promotion" view="detail" url="https://example.com/promotion/delete-promotion">
11
            <label>delete Promotion</label>
12
        </action-button>
13
        <action-button action="restockProduct" entity="product" view="list" url="https://example.com/restock">
14
            <label>restock</label>
15
        </action-button>
16
    </admin>
17
</manifest>
Copied!
For a complete reference of the structure of the manifest file take a look at the Manifest reference.
An action button must have the following attributes:
action: Unique identifier for the action, can be set freely.
entity: Here you define which entity you're working on.
view: detailor list; to set the view the button should be added to. Currently, you can choose between detail and listing view.
When the user clicks on the action button your app receives a request similar to the one generated by a webhook. The main difference is that it contains the name of the entity and an array of ids that the user selected (or an array containing only a single id if the action button was executed on a detail page).
A sample payload may look like the following:
1
{
2
  "source":{
3
    "url":"http:\/\/localhost:8000",
4
    "appVersion":"1.0.0",
5
    "shopId":"F0nWInXj5Xyr"
6
  },
7
  "data":{
8
    "ids":[
9
      "2132f284f71f437c9da71863d408882f"
10
    ],
11
    "entity":"product",
12
    "action":"restockProduct"
13
  },
14
  "meta":{
15
    "timestamp":1592403610,
16
    "reference":"9e968471797b4f29be3e3cf09f52d8da",
17
    "language":"2fbb5fe2e29a4d70aa5854ce7ce3e20b"
18
  }
19
}
Copied!
Starting from Shopware version 6.4.1.0, the current shopware version will be sent as a sw-version header.
Again you can verify the authenticity of the incoming request, like with webhooks, by checking the shopware-shop-signature it too contains the sha256 hmac of the request body, that is signed with the secret your app assigned the shop during the registration.
Providing feedback in the Administration
This feature was added in Shopware 6.4.3.0, previous versions will ignore the response content.
Starting from Shopware version 6.4.8.0, the requests of the tab and custom modal have the following additional query parameters:
shop-id
shop-url
timestamp
sw-context-language
sw-user-language
shopware-shop-signature
You must make sure to verify the authenticity of the incoming request by checking the shopware-shop-signature, which is a hash of the request's query part, signed with the shop's secret key.
If you want to trigger an action inside the administration upon completing the action, the app should return a response with a valid body and the header shopware-app-signature containing the sha256 hmac of the whole response body signed with the app secret. If you do not need to trigger any actions, a response with an empty body is also always valid.
Opening a new tab for the user
Examples response body: To open a new tab in the user browser you can use the openNewTab action type. You need to pass the url that should be opened as the redirectUrl property inside the payload.
1
{
2
  "actionType": "openNewTab",
3
  "payload": {
4
    "redirectUrl": "http://google.com"
5
  }
6
}
Copied!
Show a notification to the user
To send a notification, you can use the notification action type. You need to pass the status property and the content of the notification as message property inside the payload.
1
{
2
  "actionType": "notification",
3
  "payload": {
4
    "status": "success",
5
    "message": "This is the successful message"
6
  }
7
}
Copied!
Reload the current page
To reload the data in the user's current page you can use the reload action type with an empty payload.
1
{
2
  "actionType": "reload",
3
  "payload": {}
4
}
Copied!
Open a custom modal
To open a modal with the embedded link in the iframe, you can use the openModal action type. You need to pass the url that should be opened as the iframeUrl property and the size property inside the payload.
1
{
2
  "actionType": "openModal",
3
  "payload": {
4
    "iframeUrl": "http://google.com",
5
    "size": "medium",
6
    "expand": true
7
  }
8
}
Copied!
General structure
actionType: The type of action the app want to be triggered, including notification, reload, openNewTab, openModal
payload: The needed data to perform the action.
redirectUrl: The url to open new tab
iframeUrl: The embedded link in modal iframe
status: Notification status, including success, error, info, warning
message: The content of the notification
size: The size of the modal in openModal type, including small, medium, large, fullscreen, default medium
expand: The expansion of the modal in openModal type, including true, false, default false
Using Custom Endpoints as target
It is also possible to use custom endpoints as target for action buttons.
This feature was added in Shopware 6.4.10.0, previous versions don't support relative target urls for action buttons.
To use custom endpoints as the target url for action buttons you can define the target url as a relative url in your apps manifest.xml:
manifest.xml
1
<?xml version="1.0" encoding="UTF-8"?>
2
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">
3
    <meta>
4
        ...
5
    </meta>
6
    <admin>
7
      <action-button action="test-button" entity="product" view="list" url="/api/script/action-button">
8
        <label>test-api-endpoint</label>
9
      </action-button>
10
    </admin>
11
</manifest>
Copied!
And then add the corresponding app script that should be executed when the user clicks the action button.
Resources/scripts/api-action-button/action-button-script.twig
1
{% set ids = hook.request.ids %}
2
​
3
{% set response = services.response.json({
4
    "actionType": "notification",
5
    "payload": {
6
        "status": "success",
7
        "message": "You selected " ~ ids|length ~ " products."
8
    }
9
}) %}
10
​
11
{% do hook.setResponse(response) %}
Copied!
As you can see it is possible to provide a JsonResponse to give feedback to the user in the administration.
Administration
Add custom module
Last modified 18d ago
Copy link
Edit on GitHub
Contents
Providing feedback in the Administration
Opening a new tab for the user
Show a notification to the user
Reload the current page
Open a custom modal
General structure
Using Custom Endpoints as target