Creating a configuration-driven search experience

Generate a complete search experience by using a single JSON configuration file. This approach creates the search page, results page, table, and optional API service, which helps to reduce manual setup and maintain consistent behavior across features.

Overview

The Search From Config schematic is a JSON-driven code generator that creates complete search functionality with minimal configuration. The schematic generates the following components.

Search panel component with customizable fields.
Search results component with breadcrumbs.
Table component with pagination (client-side or server-side).
API service for data fetching (optional).
JSON configuration files for search fields and table columns.
Translation files with breadcrumb labels.

Key benefits

Creating a search experience by using this schematic has the following key benefits.

Reduce boilerplate by up to 80%.
Control behavior through one JSON configuration file.
Flexibility in supporting client-side and server-side pagination.
Additional features such as enable or disable save search and refresh.

Procedure

In your repository, create a configuration file such as order-search.json.
In the file, define the required metadata.
Optionally, add an oms-api section to configure API integration.
Optionally, add a search section to configure the search page.
Optionally, add a search-results section to configure the results page.
From the command line, run the schematic with the configuration file.
```
ng g @buc/schematics:search-from-config --config=order-search.json
```
Review the generated components and configuration files.
Update the placeholder logic so that it correctly builds the API query that is based on the selected search fields.
If routing is not registered automatically, add routes in your routing module.

Command reference

Use the following command variations to run the schematic in different scenarios.

Generate by using a configuration file.

ng g @buc/schematics:search-from-config --config=config/my-search.json

Preview changes without creating files.

ng g @buc/schematics:search-from-config --config=config/my-search.json --dry-run

Use a custom path for the configuration file.

ng g @buc/schematics:search-from-config --config=../configs/my-search.json

File naming conventions

Use consistent naming patterns to help ensure predictable component and configuration names.

Table 1. File naming conventions
Component type	Naming pattern	Example
Search panel	`{name}-search`	`order-new-search`
Search results	`{name}-search-result`	`order-new-search-result`
Table	`{name}-table`	`order-new-search-table`
Service	`{name}.service`	`order-new-search.service`
Search fields JSON key	`{name}-search`	`order-new-search`
Table config JSON key	`{name}-table`	`order-new-search-table`

The complete JSON structure

{
  "metadata": {
    "name": "order-new-search",
    "displayName": "Order Search",
    "module": "order",
    "paths": {
      "component": "packages/order-search/src/app/features/order",
      "table": "packages/order-search/src/app/features/order",
      "jsonFile": "packages/order-shared/assets/buc-app-order",
      "translationFile": "packages/order-shared/assets/buc-app-order"
    },
    "options": {
      "sharedLib": "order-shared",
      "routing": true,
      "prefix": "buc"
    }
  },
  "oms-api": {
    "endpoints": {
      "search": {
        "apiName": "getOrderList",
        "method": "POST"
      }
    },
    "requestMapping": {
      "pageNumber": "PageNumber",
      "pageSize": "PageSize"
    },
    "responseMapping": {
      "data": "Output.OrderList.Order",
      "totalCount": "Output.OrderList.TotalNumberOfRecords"
    },
    "requestDefaults": {
      "Order": {
        "DocumentType": "0001"
      }
    }
  },
  "search": {
    "fileName": "search_fields.json",
    "route": "/order-search/order/order-new-search",
    "breadcrumb": {
      "label": "Order Search"
    },
    "saveSearch": {
      "enabled": false
    },
    "customizeSearchCriteria": {
      "preferenceName": "order-new-search"
    },
    "searchFieldsJson": {
      "groups": {
        "paths": {
          "default": "Status",
          "searchBy": [
            {
              "content": "order-new-search.schematics.search.LABEL_STATUS",
              "value": "Status",
              "selected": true,
              "oob": true,
              "override": {
                "show": ["sampleStatusField"]
              }
            },
            {
              "content": "order-new-search.schematics.search.LABEL_ITEM",
              "value": "Item",
              "selected": false,
              "oob": true,
              "override": {
                "show": ["sampleItemField"]
              }
            }
          ]
        }
      },
      "fields": [
        {
          "id": "sampleGenField",
          "locked": true,
          "internalConfig": {
            "id": "sampleGenField",
            "title": "order-new-search.schematics.search.LABEL_GENERAL_FIELD_SAMPLE",
            "type": "dropdownQuery"
          }
        },
        {
          "id": "searchBy",
          "locked": true,
          "placementOnly": true
        },
        {
          "id": "sampleItemField",
          "render": {
            "hide": [{"searchBy": "status"}],
            "show": [{"searchBy": "item"}]
          },
          "internalConfig": {
            "id": "sampleItemField",
            "title": "order-new-search.schematics.search.LABEL_NON_GENERAL_ITEM_SAMPLE",
            "type": "dropdownQuery"
          }
        },
        {
          "id": "sampleStatusField",
          "render": {
            "hide": [{"searchBy": "item"}],
            "show": [{"searchBy": "status"}]
          },
          "internalConfig": {
            "id": "sampleStatusField",
            "title": "order-new-search.schematics.search.LABEL_NON_GENERAL_STATUS_SAMPLE",
            "type": "dropdownQuery"
          }
        }
      ]
    }
  },
  "search-results": {
    "route": "/order-search/order/order-new-search-result",
    "breadcrumb": {
      "label": "Order Search Results"
    },
    "saveSearch": {
      "enabled": true
    },
    "pagination": {
      "type": "server-side",
      "defaultPageSize": 10
    },
    "refresh": {
      "enabled": false
    },
    "tableConfigJson": {
      "name": "order-new-table",
      "headers": [
        {
          "id": "orderNo",
          "name": "Order Number",
          "sortKey": "OrderNo",
          "dataBinding": "OrderNo"
        }
      ]
    }
  }
}

Metadata

name: (Required) The base name for the generated components. Use this value to name the search panel, results, and related artifacts. For example, order-new-search.
displayName: (Required) The human-readable name shown in logs and diagnostics. Use this value to make log output easier to understand.
module: (Optional) The Angular module where the components are registered. If you omit this value, the schematic generates the components without registering them in a module.
paths.component: (Required) The path where the search panel and results components are created. Provide a valid project path where these components should reside.
paths.table: (Required) The path where the table component is created. Use this path to store the generated table implementation.
paths.jsonFile: (Required) The path where configuration JSON files are stored. The schematic saves files such as search_fields.json and buc-table-config.json in this location.
paths.translationFile: (Required) The path to the translation files. Use this path to update or create localization files such as en.json.
options.sharedLib: (Required) The name of the shared library. This value identifies the shared library that contains reusable logic and assets.
options.routing: (Optional) Enable or disable routing for the generated components. The default value is true. Set this value to false to skip routing setup.
options.prefix: (Optional) The html selector to use for generated components. The default value is buc.

oms-api parameters

endpoints.search.apiName: (Required) The API method name used for search requests. For example, getOrderList.
endpoints.search.method: (Optional) The HTTP method for the API request. The default value is POST.
requestMapping.pageNumber: (Optional) The API parameter name for the page number. The default value is PageNumber.
requestMapping.pageSize: (Optional) The API parameter name for the page size. The default value is PageSize.
requestDefaults: (Optional) Default values included in every API request. Use this object to pass static parameters along with each request.
responseMapping.data: (Optional) The JSON path to the data array in the API response. The default value is data.
responseMapping.totalCount: (Optional) The JSON path to the total record count in the API response. The default value is totalCount.

search parameters

fileName: (Optional) The file name for the search fields configuration. The default value is search_fields.json.
route: (Optional) The route path for the search panel. If you omit this value, the route is generated automatically.
breadcrumb.label: (Optional) The label used in the breadcrumb navigation. If you omit this value, the label is generated automatically.
saveSearch.enabled: (Optional) Enable or disable the save search functionality. The default value is true.
customizeSearchCriteria.preferenceName: (Optional) The preference key used for storing user settings. The default value is the value of metadata.name.
searchFieldsJson: (Optional) The search field configuration object. The schematic uses sample data if you do not provide a value.; Note: In the fields section, you need to update the title translation keys in the translation file. Use groups to allow configuration through customizeSearchCriteria. You can specify one group to include all fields for general use.

search-results parameters

route: (Optional) The route path for the search results page. If you omit this value, the route is generated automatically.
breadcrumb.label: (Optional) The label used in the breadcrumb navigation. If you omit this value, the label is generated automatically.
saveSearch.enabled: (Optional) Enable or disable save search in the results view. The default value is true.
pagination.type: (Optional) The pagination mode used for results. The default value is server-side. Supported values include client-side and server-side.
pagination.defaultPageSize: (Optional) The default number of records displayed per page. The default value is 25.
pagination.strategy: (Optional) The pagination strategy used to load additional data. The default value is NEXTPAGE.
refresh.enabled: (Optional) Enable or disable the refresh action. The default value is true.
fileName: (Optional) The file name for the table configuration. The default value is buc-table-config.json.
tableConfigJson: (Optional) The table column configuration. The schematic uses sample data if you do not provide a value.

Advanced features

Use these advanced features to extend your search experience and support more complex scenarios. These options help you handle large datasets, improve usability, and avoid configuration conflicts.

NEXTPAGE pagination strategy

Use case

Use this strategy when you need to fetch the next page by using the last record from the previous page as a reference.

Configuration

{
  "search-results": {
    "pagination": {
      "type": "server-side"
    }
  }
}

How it works

For the first page, no previous record is sent.
For subsequent pages, the last record key is sent as PreviousPage.
The table component tracks the last record of each page by using an internal map.

Save search integration

Enable save search to let users store and reuse search criteria.

Behavior

When saveSearch.enabled is set to true, the schematic generates components with built-in save search support.

Generated features

Save search option in the search panel.
Ability to load saved searches.

Custom file names

Use custom file names when you manage multiple search configurations in the same directory.

Configuration

{
  "search": {
    "fileName": "order-advanced-search-fields.json"
  },
  "search-results": {
    "fileName": "order-advanced-table-config.json"
  }
}

Result

Uses custom file names instead of defaults.
Helps prevent conflicts between multiple search configurations in the same location.