Creating components with Angular schematics

Edit online

Within the developer toolkit, IBM provides Angular schematics to quickly generate components with starter code that you can use in applications. Components include search pages, tables, and field details.

Use the schematics to generate components with the same design and functions as existing components in Order Hub. The generated components also include the necessary libraries to communicate with various services, such as:
  • The Sterling Order Management system backend.
  • Sterling Inventory Visibility tenants.
  • Other microservice tenants.
  • The Carbon UI libraries that are used in existing pages.
For information about how to use the schematics to create new applications, see Creating new applications.

Before you begin

  1. Ensure that you have extracted the Order Hub code. For more information, see Getting started with customizing Order Hub.
  2. Run the following command to set strict-ssl to false.
    npm config set "strict-ssl" false
  3. Run the following command to reinstall the latest version of @buc/schematics to access the IBM-provided schematics.
    npm uninstall -g @buc/schematics
npm install -g ./lib/buc/schematics/schematics-v2latest.tgz
  4. For help with a schematic script, run.
    ng g @buc/schematics:<component> --help
  5. Create components.

Creating a Search page component

Create a search page component for users to specify search criteria and search for data.

The search-panel schematic creates the search page component and includes code to support the following features:
  1. A breadcrumb trail
  2. Save search function
  3. Customize search criteria function
  4. Search by groupings
The following screen capture shows the Shipment search page and highlights the features within the search page.
A screen capture of the shipment search page. The breadcrumb trail is surrounded by a box with the label number 1. The Saved search button is surrounded by a box with the label 2. The Customize search criteria button is surrounded by a box with the label 3. The Search-by grouping is surrounded by a box with the label 4.

Procedure

  1. Open a terminal and go to the module where you want to add the component. For example, devtoolkit_docker/orderhub-code/buc-app-order.
  2. Create the component by running the following command.
    ng g @buc/schematics:search-panel --name <name> \
--json-file-path <json-file-path> \
--translation-file-path <translation-file-path> \
--shared-lib <shared-lib> \
--path <path> \
--json-file-name <json-file-name> \
--skip-import
    Parameters
    name
    (Required) The name of the component.
    The schematic creates a component class name by removing special characters and appending the word "SearchComponent". For example, if you specify the name my-sample, the generated class name is MySampleSearchComponent.
    json-file-path
    (Required) The path to where you want to update or create the configuration file (search_fields.json). For example, packages/order-shared/assets/buc-app-order.
    In the search_fields.json file, the schematic creates an object name by appending "-search" to the name. For example, my-sample-search.
    translation-file-path
    (Required) The path to where you want to update or create the translation literals (en.json). For example, packages/order-shared/assets/buc-app-order/i18n.
    In the en.json file, the schematic creates an object name by appending "-search" to the name. For example, my-sample-search.
    shared-lib
    (Required) The name of the shared library folder.
    path
    (Optional) The path to create the component file, relative to the current module. By default, a folder with the same name as the component is created in the module's root folder.
    json-file-name
    (Optional) By default, the schematic updates search_fields.json with test data. If you need to update or add your object to a different file, then use this parameter. If you specify a file name that does not exist in the assets folder, then a new file is created.
    The following command provides an example with parameters.
    ng g @buc/schematics:search-panel --name my-sample --path packages/order-search/src-custom/app/features/search --json-file-path packages/order-shared/assets/buc-app-order --translation-file-path packages/order-shared/assets/buc-app-order/i18n --shared-lib order-shared --skip-import
  3. The schematic creates the new component and updates the shared files. The output in the terminal summarizes the files that were created and updated.

Creating a Search results page component

Create a search results page component to display the results after a user runs a query from the search page component.

The search-result-component schematic generates two components:
  1. A search result component.
  2. A table component (BaseTableComponent type), whose selector is included in the search result component template.
The following screen capture shows the Shipment search results page and highlights the features within the results page.
A screen capture of the Search results page. Box 1 represents the search result component. Box 2 represents the table component.
Procedure
  1. Open a terminal and go to the module where you want to add the component. For example, devtoolkit_docker/orderhub-code/buc-app-order.
  2. Create the search results page component by running the following command. The schematic creates the component and updates the sample routing object for the search result component in the nearest routing module.
    ng g @buc/schematics:search-result-component --name <name> \
--path <resultsPageComponentPath> \
--table-path <tableComponentPath> \
--json-file-path <json-file-path> \
--translation-file-path <translation-file-path> \
--shared-lib <shared-lib> \
--skip-import
    Parameters
    name
    (Required) The name of the component.
    The schematic creates a component class name by removing special characters and appending the word "SearchResultComponent" to indicate a search results component and the word "TableComponent" to indicate a table component. For example, if you specify the name my-sample, the generated class names are MySampleSearchResultComponent and MySampleTableComponent.
    json-file-path
    (Required) The path to where you want to update or create the configuration file (buc-table-config.json).
    In the buc-table-config.json file, the schematic creates an object name by appending "-table" to the name. For example, my-sample-table.
    translation-file-path
    (Required) The path to where you want to update or create the translation literals (en.json).
    In the en.json file, the schematic creates an object name by appending "-table" to the name. For example, my-sample-table.
    shared-lib
    (Required) The name of the shared library folder.
    path
    (Optional) The path to create the search result component, relative to the current module. By default, a folder with the same name as the component is created in the module's root folder.
    table-path
    (Optional) The path to create the table component, relative to the current module. By default, a folder with the same name as the component is created in the module's root folder.
    json-file-name
    (Optional) By default, the schematic updates buc-table-config.json with test data. If you need to update or add your object to a different file, then use this parameter. If you specify a file name that does not exist in the assets folder, then a new file is created.
    The following command provides an example with parameters.
    ng g @buc/schematics:search-result-component --name my-sample --path packages/order-search/src-custom/app/features/search --table-path packages/order-search/src-custom/app/features/search --json-file-path packages/order-shared/assets/buc-app-order --translation-file-path packages/order-shared/assets/buc-app-order/i18n --shared-lib order-shared --skip-import
  3. The schematic creates the new component and updates the shared files. The output in the terminal summarizes the files that were created and updated.

Creating a Table component

Create a table component to display data in a table.

The table-component schematic supports creating a table component by extending one of the two table classes:
  1. ClientSidePaginationBaseTableComponent: For client-side pagination, where all table row entries are retrieved in one API call.
  2. BaseTableComponent: For server-side page-based results from the API.
The following screen capture shows the Shipment search results page and highlights the table component.
A screen capture of the search results page. A box surrounds the table component.
Procedure
  1. Open a terminal and go to the module where you want to add the component. For example, devtoolkit_docker/orderhub-code/buc-app-order.
  2. Create the table component by running the following command. 
    ng g @buc/schematics:table-component --name <name> \
--extend <extendableClassName> \
--json-file-path <json-file-path> \
--translation-file-path <translation-file-path> \
--path <path> \
--skip-import
    Parameters
    name
    (Required) The name of the component.
    The schematic creates a component class name by removing special characters and appending the word "TableComponent". For example, if you specify the name my-sample, the generated class name is MySampleTableComponent.
    extend
    (Optional) The name of the extendable table class. Valid values are ClientSidePaginationBaseTableComponent or BaseTableComponent. If you do not specify a value in the command, then you are prompted in the terminal to choose a component. In Git Bash for Windows, the extend parameter is mandatory.
    json-file-path
    (Required) The path to where you want to update or create the configuration file (buc-table-config.json).
    In the buc-table-config.json file, the schematic creates an object name by appending "-table" to the name. For example, my-sample-table.
    translation-file-path
    (Required) The path to where you want to update or create the translation literals (en.json).
    In the en.json file, the schematic creates an object name by appending "-table" to the name. For example, my-sample-table.
    path
    (Optional) The path to create the component file, relative to the current module. By default, a folder with the same name as the component is created in the module's root folder.
    json-file-name
    (Optional) By default, the schematic updates buc-table-config.json with test data. If you need to update or add your object to a different file, then use this parameter. If you specify a file name that does not exist in the assets folder, then a new file is created.
    The following command provides an example with parameters.
    ng g @buc/schematics:table-component --name my-sample2 --extend ClientSidePaginationBaseTableComponent --json-file-path packages/order-shared/assets/buc-app-order --translation-file-path packages/order-shared/assets/buc-app-order/i18n --path packages/order-search/src-custom/app/features/search --skip-import
  3. The schematic creates the new component and updates the shared files. The output in the terminal summarizes the files that were created and updated.

Creating a Field component

Create a Field component to display details for a specific record. For example, order dates, order lines, and ship node information for an order.

The summary-component schematic supports creating two types of components:
  1. Field component: To display attributes in the content area of a page.
  2. Summary component: To display attributes in the right side panel of a details page.
The following screen capture shows the Shipment details page and highlights the different components.
A screen capture of the shipment details page. Box 1 represents the Field component. Box 2 represents a Summary component.
Procedure
  1. Open a terminal and go to the module where you want to add the component. For example, devtoolkit_docker/orderhub-code/buc-app-order.
  2. Create the field component by running the following command. 
    ng g @buc/schematics:summary-component \
--name <name> \
--json-file-path <json-file-path> \
--is-summary-panel <true|false> \
--path <path> \
--skip-import
    Parameters
    name
    (Required) The name of the component.
    The schematic creates a component class name by removing special characters and appending the word "FieldsComponent". For example, if you specify the name my-sample, the generated class name is MySampleFieldsComponent.
    json-file-path
    (Required) The path to where you want to update or create the configuration file (buc-field-details.json).
    In the buc-field-details.json file, the schematic creates an object name by appending "-fields" to the name. For example, my-sample-fields.
    is-summary-panel
    (Optional) Boolean to determine the type of component to create. Specify true to create a Summary component. Specify false to create a Field component. Default value is true.
    path
    (Optional) The path to create the component file, relative to the current module. By default, a folder with the same name as the component is created in the module's root folder.
    json-file-name
    (Optional) By default, the schematic updates buc-field-details.json with test data. If you need to update or add your object to a different file, then use this parameter. If you specify a file name that does not exist in the assets folder, then a new file is created.
    The following command provides an example with parameters.
    ng g @buc/schematics:summary-component --name my-sample --path packages/order-search/src-custom/app/features/search --json-file-path packages/order-shared/assets/buc-app-order --is-summary-panel true --skip-import
  3. The schematic creates the new component and updates the shared files. The output in the terminal summarizes the files that were created and updated.
  4. If you created a Field Component, edit the generated HTML file to pass the header parameter to specify a label for the tab. For example, if you refer to the screen capture, the active tab has the label "Details". The "Details" label is specified by adding a header with the path to the translation literal in the en.json file: 
    [header]="'SHIPMENT_DETAILS.SHIPMENT_TABS.SHIPMENT_DETAILS'"