Adding custom actions to existing pages

Add custom actions to existing pages by using the differential customization approach, which updates the buc-page-definitions.json file to customize the page. By using the differential customization approach, your updates are preserved when Order Hub releases updates to the same pages that you customized.

Procedure

  1. Create or edit the buc-page-definitions.json file for the page that you want to add the custom action to.
    To find which pages support adding actions to, see the pages listed in the following file:
    • buc-app-<module>/packages/<module>-shared/assets/buc-app-<module>/buc-page-definitions.json

    The order details page is used as an example in this task, located at packages/order-details/src-custom/assets/custom/buc-page-definitions.json.

  2. Add a custom action to the page with the following properties:
    id
    A unique ID.
    label
    A string that will get displayed as a page action label in the UI. You can provide a translatable string.
    resourceId
    A unique ID to show or hide the action. Create a new resource ID and enter the value.
    For example, to update the order details page, update the packages/order-details/src-custom/assets/custom/buc-page-definitions.json file with the following details:
    
{
	"order-details": {
		"name": "order-details",
		"actions": [
			{
				"id": "custom-action",
				"label": "custom.LABEL_CUSTOM_ACTION",
				"resourceId": "BUCORD0014AT0001"
			}
		]
	}
}
  3. Add translation strings for the custom action.
    1. Create or edit the en.json file. For example, for the order details page, packages/order-details/src-custom/assets/custom/i18n/en.json.
    2. Write the following JSON content into the en.json file. This label is used for the new custom action that you will add to the page. 
      
{
	"custom": {
		"LABEL_CUSTOM_ACTION": "Custom action"
	}
}
  4. Verify that the new custom action displays in Order Hub.
    1. Log in to Order Hub. If you were already logged in, reload the frame.
    2. Go to the page that you updated so that you can verify the custom action display.

      For example, if you updated the order details page, click Orders (DEV mode) and search for orders. Click any order to go to the order details page.

    3. Click Actions and verify that the new custom action is shown in the menu. For example:
      Custom action
  5. Create an action service file custom-action.service.ts and pass an action ID (which was specified as id for custom action in the buc-page-definitions.json file) to the select method of ActionProcessorService.
    For example, for the order details page, packages/order-details/src-custom/app/services/custom-action.service.ts is updated in the following code, and Custom action will show an alert pop-up:
    
import { Injectable } from '@angular/core';
import {ActionProcessorService } from '@buc/order-shared';

@Injectable()
export class CustomActionService{
	constructor(
		private actionProcessorService: ActionProcessorService
	)	{
		this.actionProcessorService.select<any>('custom-action').subscribe(({params}) => {
			const componentId = params.component; // component id of the order-details-page
			const orderDetailsData = params.data;
			// params.data contains the following properties
			// params.data = {
				// pageObject -> details page data
				// routeData -> the page router object
				// context -> sometimes a page has a context object
			// }
			alert('Custom action invoked');
		});
	}
}
  6. Register a custom action service in the app-customization.impl.ts file.
    For example, for the order details page, packages/order-details/src-custom/app/app-customization.impl.ts.
    1. Import a custom action service, which was created in the previous step.
    2. Import BucActionsModule from "@buc/common-components".
    3. Add custom action service to imports as shown in the following example: 
      
import { BucActionsModule } from "@buc/common-components";
import { CustomActionService } from "./services/custom-action-service";

export class AppCustomizationImpl {
	static readonly components = [];
	
	static readonly providers = [];
	
	static readonly imports = [
		BucActionsModule.forChild(
			[
				{
					name: 'custom-action',
					action: CustomActionService
				}
			]
		)
	];
	
}
      Note: The value for the name property must be the same as the action ID specified in the buc-page-definitions.json file.
  7. Reload the frame and verify that an alert pop-up is displayed when selecting the new custom action. For example:
    Alert popup