Modifying application-provided modals

The modal dialogs are used to present critical information or to request user input that is needed to complete specific user actions. User actions include canceling an order, viewing serials, adding or viewing notes for an order or order line, and so on.

A modal dialog is similar to a pop-up screen, which opens a dialog box to display a screen over the main application content. All modal dialogs are displayed in the parent screen. When a modal dialog is open, users cannot return to the parent screen. Also, any user action is ignored until the modal task is completed or the modal dialog closed.

You can customize the application-provided modals as needed for your business.

Before you begin

The application-provided modals are present in the modals directory of the corresponding page components or screen as explained in the following examples:

The cancel order modal component is displayed when you click the Cancel order related task in the Order summary screen. The cancel order modal component is present in the <store-temp>/packages/features/orders/src/app/features/orders/order-summary-page/modals/cancel-order-modal directory.
The record shortage modal component is displayed when you want to mark a product quantity as shortage in the Pick page of the move inventory flow. The record shortage modal component is present in the <store-temp>/packages/features/move-inventory/src/app/features/move-inventory/move-inventory-wizard-page/modals/record-shortage directory.

To override any application-provided modal, you must know the modalId of the modal. The modalId is used to uniquely identify the application-provided modal. Therefore, it is used by the override-modal command that enables you customize the modal.

The modalId is defined as a variable within the application-provided modal component class as illustrated in the following example:

export class OrderTotalModalComponent implements OnInit {
  public static modalId = 'orders.order-total-modal';
  ...
  ...

When you override an application-provided modal, the entire modal component directory is copied in the <store-temp>/extensions/features/override-modals directory. You can modify the modal component that is copied as needed for your business.

Note: When you want to modify only the modal code, do not copy the parent screen or component code.

To map the application-provided modal with the custom or override modal, use the <store-temp>/extensions/features/override-modals/src/assets/override-modals/config/isf-modal-config.json configuration file. You can easily determine the application-provided modal that is overridden, and the custom modal component that is used to override.

The following table describes the schema definition of isf-modal-config.json file:

Attribute name	Description
applicationProvidedModalId	A unique identifier that is assigned to the application-provided modals for which the naming convention is, `<feature-name>.<parent-page-name>.<modal-name>`. For example, `orders.order-summary-page.cancel-order-modal`.
overrideModalId	A unique identifier that is assigned to the overridden or custom modals for which the naming convention is, `custom-<applicationProvidedModalId>`. For example, `custom-orders.order-summary-page.cancel-order-modal`.

Procedure

Go to the <store-temp> directory, and run the following command:
```
yarn override-modal --application-provided-modal-id=<component-modal-id>
```
For example,
```
yarn override-modal --application-provided-modal-id=functional-components.identify-customer-modal
```
Here, --application-provided-modal-id refers to the modal ID of the application-provided modal component that you want to modify.

You can identify the modalId of the application-provided modal by referring the source code of the modal component that you want to customize.
The command completes the following tasks:
- Copies the application-provided modal component folder to <store-temp>/extensions/features/override-modals/src/app/<feature-name>.
  To organize the modals that belongs to the same application in a single folder, it is recommended that you create a <feature-name> folder in <store-temp>/extensions/features/override-modals/src/app directory.
- Automatically imports the component and creates an entry of the component in customModalsDeclarations object in the app.module.ts file that is present in the <store-temp>/extensions/features/override_modals/src/app folder.
- To avoid modal name collisions with the application-provided modalIds, the command updates the modalId of the custom modal component by prefixing custom- to the existing modalId as shown in the code snippet.
- To map the application-provided modalId with the custom or override modalId, updates the isf-modal-config.json file that is present in the <store-temp>/extensions/features/override-modals/src/assets/override-modals/config/ folder.
  The following code snippet illustrates the sample entry in isf-modal-config.json:
  [ { "applicationProvidedModalId": "orders.order-summary-page.cancel-order-modal", "overrideModalId": "custom-orders.order-summary-page.cancel-order-modal" }]
  Note: The CLI command copies only the files that are present in the component folder. If the extended component imports files outside of the component folder, ensure that you manually copy such files to the appropriate location within the new modal component folder. Also, ensure that you import and declare in the app.module.ts file that is present in the <store-temp>/extensions/features/override_modals/src/app folder.
In the custom modal component, you can find a private _activeModal: NgbActiveModal in constructor. Replace the NgbActiveModal service with StoreWrapperModalService, and make sure that you import StoreWrapperModalService from '@store/core'. This change is necessary to pass the modal data from the override-modal application to the out-of-the-box application.

Note: If the application-provided modal sends data to the parent screen, the custom modal must also send data to the parent screen. Ensure that you retain the original data model schema without modifying the type, or removing any attributes from the data object.
To support localization and internationalization, the i18n folders are present in the <store-temp>/extensions/features/override-modals/src/assets/override-modals/i18n/ folder. You can create language-specific bundle JSON files, and add the custom bundle entries language-specific JSON file. For example, for the English locale, create en.json and add the custom bundle entries language-specific JSON file.
To reuse the existing application-provided bundle entries that are required for the overridden modal configure the path of the corresponding feature module as illustrated in the sample code snippet.

For example, if you override the assign task modal of cycle count feature, then add cycle count to bundles array in <store-temp>/extensions/features/override_modals/src/app/app.module.ts.
```
static bundles: Array<any> = [
    {
      prefix: './assets/cycle-count/i18n/',
      suffix: '.json'
    },
    {
      prefix: './assets/override-modals/i18n/',
      suffix: '.json'
    }
  ].concat(CommonBundlesModule.bundles);
};
```
Note: In the bundles array, add './assets/override-modals/i18n/' at the end.

What to do next

To locally verify the extended application-provided screen, start the application by running the following command, and navigate to the screen where the modal is displayed.
```
yarn start-app
```
To verify the changes in the developer toolkit, extract and deploy the customizations. For more information about extracting and deploying customizations, see Extracting customizations.