Skip to content

Latest commit

 

History

History
136 lines (114 loc) · 5.51 KB

add-custom-action-button.md

File metadata and controls

136 lines (114 loc) · 5.51 KB

Add custom action button

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:

{% code title="manifest.xml" %}

<?xml version="1.0" encoding="UTF-8"?>
<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">
    <meta>
        ...
    </meta>
    <admin>
        <action-button action="setPromotion" entity="promotion" view="detail" url="https://example.com/promotion/set-promotion">
            <label>set Promotion</label>
        </action-button>
        <action-button action="deletePromotion" entity="promotion" view="detail" url="https://example.com/promotion/delete-promotion">
            <label>delete Promotion</label>
        </action-button>
        <action-button action="restockProduct" entity="product" view="list" url="https://example.com/restock">
            <label>restock</label>
        </action-button>
    </admin>
</manifest>

{% endcode %}

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 just a single id in case the detail page).

A sample payload may look like the following:

{
  "source":{
    "url":"http:\/\/localhost:8000",
    "appVersion":"1.0.0",
    "shopId":"F0nWInXj5Xyr"
  },
  "data":{
    "ids":[
      "2132f284f71f437c9da71863d408882f"
    ],
    "entity":"product",
    "action":"restockProduct"
  },
  "meta":{
    "timestamp":1592403610,
    "reference":"9e968471797b4f29be3e3cf09f52d8da",
    "language":"2fbb5fe2e29a4d70aa5854ce7ce3e20b"
  }
}

{% hint style="info" %} Starting from Shopware version 6.4.1.0, the current shopware version will be sent as a sw-version header. {% endhint %}

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

{% hint style="info" %} This feature was added in Shopware 6.4.3.0, previous versions will ignore the response content. {% endhint %}

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.

{
  "actionType": "openNewTab",
  "payload": {
    "redirectUrl": "http://google.com"
  }
}

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.

{
  "actionType": "notification",
  "payload": {
    "status": "success",
    "message": "This is the successful message"
  }
}

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.

{
  "actionType": "reload",
  "payload": {}
}

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.

{
  "actionType": "openModal",
  "payload": {
    "iframeUrl": "http://google.com",
    "size": "medium",
    "expand": true
  }
}

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