Modifying application-provided screens

The screens in Sterling Store Engagement are modeled as an angular route. Developers can customize the application-provided screens as needed for their business.

In an angular application, components are the most basic user interface building blocks. An angular application contains a tree of angular components. A page component is a route level angular component that is used to define a route in a routing module. These components are suffixed with PageComponent in the class.

The following sample example depicts a route definition where ShipmentSummaryPageComponent is a page component.

{
path: 'summary/:shipmentKey',
component: ShipmentSummaryPageComponent
}

Before you begin

To customize the application-provided screens, 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 screen.

Go to the <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> --port=<port>
```
For example,
```
yarn override-route --module-name=configurations-extn --override-module-name=configurations --override-component-folder-name=view-location-page --port=5300
```
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.ya
- --override-module-name refers to the name of the module that contains the application-provided screen.
- --override-component-folder-name refers to the folder name of the application-provided screen that you want to override.
- --port refers to the port number where the new application runs.
The command completes the following tasks:
- Creates a new angular application with the prefix, isf in the <store-temp>/extensions/features folder. You can find the source code in the <store-temp>/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.
- Updates the following entry for the custom import-map.json that is present in the <store-temp>/extensions/override-static-assets/root-config/custom/ folder.
```
{
  "imports": {
    "<module-name>": "/<module-name>/main.js"
  }
}
```
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).
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/shipment/summary/:shipmentKey",
      "routes": [
        {
          "type": "application",
          "name": "shipment-list-summary-extn"
        }
      ]
    }
  ]
}
```
This entry maps the application-provided route to the new custom application. It also ensures that the route is loaded from the new custom application.

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.