Bulk Actions

You might need to execute a custom action for each entity in a selection while extending Umbraco Commerce. For example, being able to trigger label printing for a series of orders, or printing physical gift cards for specific gift card entities.

Umbraco Commerce allows extending the different table views, adding in Bulk Actions to the bulk action bar that appears when you select multiple items. Out of the box all list views contain at minimum a Delete bulk action.

Injecting a Bulk Action

Bulk actions are client-side concepts and so additional bulk actions are injected with JavaScript in an AngularJS configuration module.

To create a configuration module you can create a custom folder in the App_Plugins directory and create a JavaScript file to hold your configuration in.

1. Create a custom folder in the App_Plugins directory.

2. Create a JavaScript file with this new folder.

App_Plugins\MyPlugin\backoffice\config\umbraco-commerce-bulk-actions-config.js

1. Register the file in a package.manifest file within the same folder.

App_Plugins\MyPlugin\package.manifest

1. Add the following JSON to the package.manifest file:

{
    "javascript": [
        "~/App_Plugins/MyPlugin/backoffice/config/umbraco-commerce-bulk-actions-config.js"
    ]
}

1. Inject a bulk action inside the umbraco-commerce-bulk-actions-config.js by adding the following:

angular.module('umbraco.commerce')
    .config(['ucActionsProvider', function (ucActionsProvider) {
        ucActionsProvider.bulkActions.push(['myResource', function (myResource)
        {
            return {
                name: 'My Action',
                icon: 'icon-box',
                itemAction: function (bulkItem) {
                    return myResource.doAction(bulkItem.id);
                },
                condition: function (ctx) {
                    return ctx.entityType == 'Order'
                },
                sortOrder: 110
            }
        }]);
    }]);

Once created, the bulk action will be displayed in the bulk actions bar for the configured entities.

Bulk Action Options

Only an itemAction or a bulkAction method can be defined for a bulk action configuration. If both are present, the bulkAction will be used and the itemAction will be ignored. If processing of items can be done individually, it is better to use the itemAction in order to provide user feedback. The bulkAction can only be used where items need to be processed in a single action.

Important Notes

• Most methods apart from itemAction or bulkAction are optional. If methods aren't present, a default implementation will be used. Where the methods trigger, specific functionality such as the configure or getConfirmMessage methods will become disabled.

• The array-based syntax for registering is a bulk action with angular dependencies. Each bulk action is registered as an array, where all dependencies are defined first and then a factory function is defined last which returns the actual bulk action definition.

• Whilst these docs outline how to define a bulk action, you will likely need to register further resources or services that can perform the given bulk operation and include these as a dependency for your action.

Examples

The following section display an example of a bulk action with dialog configuration step:

angular.module('umbraco.commerce')
    .config(['ucActionsProvider', function (ucActionsProvider) {
        ucActionsProvider.bulkActions.push(['$q', 'editorService', 'myResource', function ($q, editorService, myResource)
        {
            return {
                name: 'My Action',
                icon: 'icon-box',
                configure: function (selected) {
                    return $q(function (resolve, reject) {
                        editorService.open({
                            view: '/app_plugins/myplugin/views/dialogs/config.html',
                            size: 'small',
                            config: {
                                items: selected
                            },
                            submit: function (model) {
                                editorService.close();
                                resolve(model);
                            },
                            close: function () {
                                editorService.close();
                                reject();
                            }
                        });
                    });
                },
                bulkAction: function (items) {
                    var ids = items.map(itm => itm.id);
                    return myResource.doAction(ids);
                },
                condition: function (ctx) {
                    return ctx.entityType == 'Order'
                },
                sortOrder: 110
            }
        }]);
    }]);