Creating custom actions

Custom action is a service (AngularJS service) that allows you to map an action to the UI elements in the View designer. You can create a custom action (JavaScript action) that can be mapped to an action button or a cell in a record grid in a view definition.

For example, if you want to display an alert box (that displays an alert message) on the click of an action button, you can create an action for the alert box (via code) and then map the action to an action button in the View designer.

Note

You must ensure that you follow naming conventions (namespacing) for all angular object names and all HTML filenames in shared code. See Naming conventions for angular objects.

To create a custom action

Create a service that implements the functionality for the action.
The functionality of the action is define in the execute method. This method accepts a list of parameters specified in the action descriptor. The name of the service should match the name of the action specified in the action descriptor. To support chaining of actions, an action needs to return a promise and resolve it when its completed. The following sample code illustrates Open view action:

angular.module('com.bmc.arsys.rx.standardlib.actions.open-view').service('rxOpenViewAction', function (rxLog) {
    execute: function (viewDefinitionName, viewParams, presentation) {
        return getViewDefinition(viewDefinitionName).then(function (data) {
            var stateParams = _.map(data.inputParams, function (param) {
                return viewParams[param.name];
            });
            switch (presentation.type) {
                case RX_OPEN_VIEW.type.fullWidth: {
                    openFullWidth(viewDefinitionName, presentation, stateParams);
                    return $q.reject();
                }
                case RX_OPEN_VIEW.type.centeredModal: {
                    return openModal('rx-runtime-view-dialog modal__', viewDefinitionName, presentation, stateParams, RX_OPEN_VIEW.template.modal);
                }
                case RX_OPEN_VIEW.type.dockedRightModal: {
                    return openModal('rx-runtime-view-dialog d-action-blade action-blade__', viewDefinitionName, presentation, stateParams, RX_OPEN_VIEW.template.blade);
                }
                case RX_OPEN_VIEW.type.dockedLeftModal: {
                    return openModal('rx-runtime-view-dialog d-action-blade is-left action-blade__', viewDefinitionName, presentation, stateParams, RX_OPEN_VIEW.template.blade);
                }
                default: {
                    openFullWidth(viewDefinitionName, presentation, stateParams);
                    return $q.reject();
                }
            }
        });
    }
});

You can use rxAction service to run an action. The following sample code illustrates usage of Open View action.

rxAction.executeAction('rxOpenViewAction')({
        propertiesByName: {
            viewDefinitionName: 'com.example.taskmanager:AnyView',

            presentation: {
                title: 'Edit Record',
                modalSize: RX_OPEN_VIEW.modalSize.large,
                type: RX_OPEN_VIEW.type.dockedRightModal
            }            
        }
    });

Register the action using rxActionProvider.

To make the action available in the View designer (Add/Remove Actions dialog), you must register with rxActionProvider. To register an action, must use rxActionProvider#registerAction class. This class consists of the following properties:

Property	Description
name	Name of the action. This is a required property. For example, rxSaveAction, rxDeleteRecordsAction.
bundleId	Name of the bundle. This is a required property.
label	User friendly action name that is displayed in the View designer
hidden	A boolean flag that determines whether an action is hidden in the View designer action list
parameters	An array of action parameters. This property of an action descriptor is used to list all parameters that are passed to the execute method. Every parameter is saved in action component definition. The parameter descriptor has the following options: name—Parameter name label—User friendly parameter name displayed in the action list. enableExpressionEvaluation—Boolean flag used to enable expression evaluation for the parameter value. The default value is false. editor—name of a UI control used to set parameter value (implemented as angular directive). The default value is rx-expression-field for a parameter with enableExpressionEvaluation set to true and rx-editor-input for others. isRequired—Boolean flag to enable auto validation for empty values. The default value is false. defaultValue—Default value for a parameter. You can specify additional properties in parameter descriptor.

The following sample code illustrates how to register and action using rxActionProvider:

rxActionProvider.registerAction({
    name: 'rxOpenViewAction',
    label: 'Open View',
    bundleId: RX.bundleId,
    parameters: [
        {
            name: 'viewDefinitionName',
            label: 'View',
            editor: 'rx-view-definition-selector',
            isRequired: true,
            definitionType: RX_DEFINITION_PICKER.definitionTypes.view.type
        },
        {
            name: 'viewParams',
            editor: 'rx-view-definition-params',
            enableExpressionEvaluation: true
        },
        {
            name: 'presentation',
            editor: 'rx-view-presentation-params'
        }
    ]
});

getOutputParams function

In the View designer, in the Add/Remove Actions, you can add, remove, rearrange and configure actions associated with a actionable view component. When you configure actions you can set the execution order of actions by placing them in a sequence. Every action configuration section contain editors that allow you to set the action parameters. Each action can expose data that is available to the following action in the action chain. These exposed properties are referred as action output parameters. If an action has output parameters, the service that defines the action should consist of getOuputParameters method and execute method. The getOuputParameters function accepts the configured action data and returns an array of objects, where each object has name property that specifies a parameter name.

Sample code:

module.service('rxOpenViewAction', function () {
    return {
        execute: function() {},
        getOutputParams: function (actionConfig) {
            // returns the list of output parameters exposed by the selected view
            if (actionConfig.viewDefinitionName) {
                return getViewDefinition(actionConfig.viewDefinitionName).then(function (viewDefinition) {
                    return _.map(viewDefinition.outputParams, function (outputParam) {
                        return {
                            name: outputParam.name
                        };
                    });
                });
            }
        }
    }
}

Storing actions

An action is stored in the view definition in the componentDefinitions property as a view component with rx-action type. Action input parameters are stored in the propertiesByName property. Actionable view components must be defined as containers in order to keep the associated actions as their child view components.

The following sample code illustrates how to define an action as a service

"resourceType": "com.bmc.arsys.rx.services.view.domain.ContainerViewComponentDefinition",
"id": "93ba11a4-8e58-470d-95ac-23a8aa0ddcb7",
"type": "rx-action-button",
"componentDefinitions": [
    {
    "resourceType": "com.bmc.arsys.rx.services.view.domain.ViewComponentDefinition",
    "id": "2a3d227d-2643-4b3b-9a29-a5ea72243988",
    "type": "rx-action",
    "propertiesByName": {
        "index": 0,
        "name": "rxOpenViewAction",
        "viewDefinitionName": "com.example.taskmanager:Edit Task",
        "viewParams.taskId": "${view.api}",
        "presentation.type": "fullWidth",
        "presentation.launchBehavior": "newWindow"
    }
}

Example to create an alert box action

Let us consider you want to display an alert box (that displays an alert message) on the click of an action button. To implement this, you can create an action for the alert box (via code) and then map the action to an action button in the View designer.

Creating action to display an alert box

In Eclipse, open the library project, navigate to projects\<library>\bundle\src\main\webapp\scripts\actions, and perform the following steps:

Declare the AngularJS module for the action.

For example, declare show-alert AngularJS module in show-alert.module.js.

(function () {
    'use strict';

    angular.module('com.example.samplelibrary.actions.show-alert', [
        'com.bmc.arsys.rx.standardlib.action'
    ]);
})();

Define service for the action.
For example, define an AngularJS service which invokes alert() from the execute() method in show-alert.service.js.

(function () {
    'use strict';

    angular.module('com.example.samplelibrary.actions.show-alert')
        .service('comExampleSamplelibraryShowAlertAction', function () {
            this.execute = function (message) {
                alert(message);
            };
        });
})();

Register the action and its parameter with BMC Helix Innovation Studio.

For example, register the action in show-alert.config.js.

(function () {
    'use strict';

    angular.module('com.example.samplelibrary.actions.show-alert').config(function (rxActionProvider) {
        rxActionProvider.registerAction({
            name: 'comExampleSamplelibraryShowAlertAction',
			bundleId: 'com.example.samplelibrary',
			label: 'Show Alert',
            parameters: [
                {
                    name: 'message',
                    label: 'Alert Message',
					enableExpressionEvaluation: true
                }
            ]
        });
    });
})();

If you are creating actions in an application bundle, you must ensure that the path to the JavaScript files that implements the action is referenced in bundle.conf.json.

For example,

"ext": {
    "scripts": [
        ...
        "scripts/actions/**/*.module",
        "scripts/actions/**/*.config",
        "scripts/actions/**/*.service",
        ...
    ],

Add a dependency on the action's module to the main library module in com.example.samplelibrary.module.js, or to the application's extension module (for example, com.example.myapp-ext.module.js), if you are adding a custom action to an application bundle.
Sample code:
```
angular.module('com.example.samplelibrary', [
    // Existing View components (not shown here)

    // Actions
    'com.example.myapp.actions.show-alert'
]);
```

Build and deploy the project.