Modifying application-provided wizard screens

A wizard is a structured sequence of screens that can be displayed in the application. A wizard is used to create flows where more than one screen is required to complete a task. Some of the examples of wizards in Sterling Store Engagement application includes Batch Pick, Move Inventory, Putaway, Create order and others.

A wizard flow in Sterling Store Engagement is modeled as an angular child routes. The parent route includes the logic to validate and initialize the wizard flow, along with the navigation to a specific screen or child route in the flow. Each child route represents a step in the wizard flow. As a developer, you can customize the child routes of the application-provided wizard flows as needed for your business.

Note: You cannot customize the parent route of the wizard.

The following route definition depicts a route definition for the Adhoc Move Inventory wizard flow.

AdhocMoveCreateWizardPageComponent - Depicts the parent route component of the wizard, which you cannot customize.
AdhocDepositProductsPageComponent and AdhocPickProductsPageComponent - Depicts the child route components of the wizard, which you can customize.

{
path: 'adhoc-request/:requestKey',
component: AdhocMoveCreateWizardPageComponent,
canDeactivate: [BackClickHandlerGuard],
children: [
{
path: 'deposit-products',
component: AdhocDepositProductsPageComponent
},
{
path: 'pick-products',
component: AdhocPickProductsPageComponent
}
]
}

Before you begin

To customize the application-provided screens wizard child route components, complete the following prerequisites:

Identify the screen and the corresponding single-spa application that you want to customize.
Identify the entries in feature-import-map.json and feature-routes.json for the selected single-spa application.

Identifying the screen and the corresponding single-spa application

To customize any screen, identify the angular component route that corresponds to the screen being customized, and also the corresponding single-spa angular application.

For example, if you want to customize the Shipment summary screen, complete the following steps to identify the angular component to override:

Log on to Sterling Store Engagement in Google Chrome browser and open the Developer tools.
Go to the Shipment summary screen.
In Developer tools > Network tab determine the following URLs:
- The main.js bundle URL, <http://hostname:port/isf/store-frontend/shell/shipment/summary/<shipmentKey>>
- The shipment summary route URL, <http://hostname:port/isf/store-frontend/shell/shipment/summary/<shipmentKey>>
Here,
- isf/store-frontend refers to the application path.
- shipment refers to the single-spa angular application.
- summary/<shipmentKey> refers to the angular route.
  In this case, it is the shipment-list-summary angular application, which contains the angular route, summary/<shipmentKey>, and the corresponding route component is ShipmentSummaryPageComponent. The source code for the shipment list summary application is present in the <store-temp>/packages/features/shipment-list-summary directory. To customize the Shipment summary screen, extend the shipment-list-summary application.

You can adopt the same process to identify the angular component route, source folder that contains the component code, and the corresponding single-spa angular application to override the application-provided screen.

Identify the entries in `feature-import-map.json` and `feature-routes.json` for the selected single-spa application

feature-import-map.json - The UMD module bundles for each of the single-spa application is configured in feature-import-map.json that is present in <store-temp>/packages/apps/store-root-app/src/assets/root-config/config/feature-import-map.json. To identify the entry in feature-import-map.json, use the "shipment-list-summary" application name. Then, determine the entry for "shipment-list-summary" in feature-import-map.json. For example, "shipment-list-summary": "//localhost:4227/isf/store-frontend/shipment-list-summary/main.js",
feature-routes.json - Routes in Sterling Store Engagement is configured as part of feature-routes.json that is present in <store-temp>/packages/apps/store-root-app/src/assets/root-config/config/feature-routes.json. Identify the route definitions for the shipment-list-summary application by searching for "name": "shipment-list-summary" in feature-routes.json.
The following list of routes is applicable for the "shipment-list-summary" application:
```
{
"type": "route",
"path": "shell/shipment",
"routes": [
{
"type": "application",
"name": "shipment-list-summary"
}
]
},
{
"type": "route",
"path": "shell/shipment/list",
"routes": [
{
"type": "application",
"name": "shipment-list-summary"
}
]
},
{
"type": "route",
"path": "shell/shipment/summary/:shipmentKey",
"routes": [
{
"type": "application",
"name": "shipment-list-summary"
}
]
}
```
To identify the route definition for the Shipment summary screen, consider the http://hostname:port/isf/store-frontend/shell/shipment/summary/<shipmentKey> URL for the Shipment summary screen.

The relative URL for shipment summary route is, shell/shipment/summary/<shipmentKey>. Find the matching entry from the list for relative URL by comparing with the path attribute.

The following code snippet illustrates feature-routes.json:
```
{
"type": "route",
"path": "shell/shipment/summary/:shipmentKey",
"routes": [
{
"type": "application",
"name": "shipment-list-summary"
}
]
}
```

Procedure

After you identify the screen and the corresponding angular application to override, complete the following steps to customize the application-provided wizard screen.

Go to <store-temp> directory, and run the following command:
```
yarn override-route --module-name=<module-name> --override-module-name=<override-module-name> --override-component-folder-name=<component-name-path> --port=<port>
```
For example,
```
yarn override-route --module-name=custom-orders --override-module-name=orders --override-component-folder-name=order-capture-wizard-page/add-product-page --port=5100
```
Here,
- --module-name refers to the name of the extension module that needs to be created.
  
  Note: Ensure that each word in the <module-name> attribute value is separated by a hyphen (-). For example, if the module name is custom move inventory, specify the value as custom-move-inventory.
- --override-module-name refers to the name of the module that contains the application-provided screen. For example, move-inventory.
- --override-component-folder-name refers to the folder name of the application-provided screen that you want to override.
  
  Note: When you extend the application-provided wizard screen, include the parent wizard folder name along with the child route or component folder name.
  For example, in the Adhoc Move Inventory wizard flow, you want to customize the AdhocDepositProductsPageComponent screen. Then, set the value of the override-component-folder-name parameter to adhoc-move-create-wizard-page/adhoc-depositproducts-page.
- --port refers to the port number where the new application runs.
The command completes the following tasks:
- Creates a new angular application in the <store-temp>/extensions/features folder. You can find the source code in the <storetemp>/extensions/features/<module-name> folder.
- Installs the single-spa-angular node module in the angular application that is created.
- Generates a main.single-spa.ts in your src project folder.
- Generates a lazy loaded module with <module-name> in your <store-temp>/extensions/features/<module-name>/src/app project folder.
- Updates the <store-temp>/extensions/features/<module-name>/src/app-routing.module.ts routing module file with the following route definitions:
  - Lazy loaded module with the appropriate route path definition.
  - EmptyRouteComponent for unmatched routes.
- Updates the package.json with the start and build scripts of the application.
- Registers the new application in <store-temp>/extensions/override-static-assets/root-config/custom/import-map.json. The import-map.json file registers the JavaScript module to load a specific application.
- To support localization and internationalization, the i18n folders are generated in the <store-temp>/extensions/features/<module-name>/src/assets project folder to maintain the language-specific bundles. An empty en.json bundle JSON file is generated in the <store-temp>/extensions/features/<module-name>/src/assets/<module-name>/i18n project folder. The code is also updated to set up TranslateModule to load the appropriate translation bundle JSON files.
- Copies the entire component folder specified in the --override-component-folder-name parameter to the <store-temp>/extensions/features/<module-name>/src/app/features/<module-name> folder. This folder contains all the files that are required to override the application-provided screen.
- The CLI command automatically imports the dependent angular services and components into extension application module ts file, <store-temp>/extensions/features/<module-name>/src/app/features/<module-name>/<module-name>.module.ts
  
  Note: The CLI command only copies the files that are present in the component folder. If the extended component imports files that are outside of the component folder, ensure that you manually copy such files to the appropriate location within the new extension application. Also, ensure that you import and declare in the <store-temp>/extensions/features/<module-name>/src/app/features/<module-name>/<module-name>.module.ts extension module file.
Initialize the wizard in the ngOnInit method of the custom component. This ensures that the custom wizard component in the new angular application shares the same wizard state as the application-provided wizard.
```
ngOnInit() {
this._wizardService.initialiseWizardForCustomRoute();
......
}
```
Update the route definition of the overridden route in the lazy loaded routing module ts file, (<store-temp>/extensions/features/<module-name>/src/app/features/<module-name>/<module-name>-routing.module.ts).
```
const routes: Routes = [
{
path: 'adhoc-request/:requestKey/deposit-products',
component: AdhocDepositProductsPageComponent,
```
Update the custom routes.json, which is present in the <store-temp>/extensions/override-static-assets/root-config/custom/ folder with the following entry:
```
{
"routes": [{
"type": "route",
"path": "shell/move-inventory/adhoc-request/:requestKey/depositproducts",
"routes": [
{
"type": "application",
"name": "custom-move"
}
]
}]
}
```
This entry maps the application-provided route to the new custom application, and also ensures that the route is loaded from the new custom application.

Guidelines

To access the query parameters or route parameters that are passed to the new custom wizard screen component, remove the parent reference from activatedRouteSnapshot that is used to read the route parameters.

this.requestKey = this.route.parent.snapshot.params.requestKey; // This does not work. Remove parent
this.requestKey = this.route.snapshot.params.requestKey; // This works

The wizard data model provides a method to share data between the wizard screens in scenarios as follows:

When the wizard data model that is set in the application-provided wizard screen must be accessed in the custom wizard screen.
When the custom wizard screens must share data between them.

In such cases, you can use the following pseudo-code for data sharing and access:

this._wizardService.wizardDataModel.orderHeaderKey = ‘123456‘
this._wizardService.wizardDataModel.addedSerials = [‘123‘,’2345’]
this.orderHeaderKey = this._wizardService.wizardDataModel.orderHeaderKey;

What to do next

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