Configure Search Criteria

After generating the base of the search page, you can configure search criteria to allow users to filter existing data. It is necessary to add such criteria to both the user interface and the backend services to ensure proper data processing.

Steps to add Search Criteria

Adjust the OpenAPI specification to include new search criteria in the search request schema.
Update the TypeScript schema to represent the search criteria.
Modify the HTML of the search component to include input fields for the new criteria.
Add necessary translations for the input fields.

The search criteria added here are used as part of the URL parameters when making requests to the backend service. Ensure that the criteria names are URL-friendly and do not contain special characters that could interfere with URL encoding.
Examplarily, a search criteria named bookTitle will be used in the URL as ?bookTitle=value.

ACTION S1

Add Criteria to Search Request: The Search<Feature>Request component in the OpenAPI YAML file must be adapted by adding the desired search criteria as properties.
More details in NgRx Search Criteria.

Template: Generated Schema

Directory	`<root-of-ui-app>/src/assets/api`
File	`openapi-bff.yaml`

ACTION S1 in openapi-bff.yaml

    Search<Feature>Request:
      type: object
      properties:
        id:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
          default: 0
          description: 'The number of the page.'
        pageSize:
          type: integer
          format: int32
          default: 100
          maximum: 1000
          description: 'The size of the page.'
        changeMe:
          type: string
        # " ACTION S1: Add additional properties"

Where changeMe is here the example search criteria to be replaced. This criteria corresponds to the property added to the Search<Feature>Request.

Example

Directory	`bookstore/src/assets/api`
File	`openapi-bff.yaml`

Example: Adjustments in openapi-bff.yaml

    SearchBookRequest:
      type: object
      properties:
        pageNumber:
          type: integer
          format: int32
          default: 0
          description: The number of the page
        pageSize:
          type: integer
          format: int32
          default: 100
          maximum: 1000
          description: The size of the page.
        bookTitle:
          type: string
          maximum: 255
        # "ACTION S1: Add additional properties"

Where e.g. bookTitle is a search criteria, same as the one added to the SearchBookRequest.

After adding the new criteria to the OpenAPI specification, you need to regenerate the API client code to reflect these changes in your application.

Generate the API client code

npm run apigen

ACTION S2

Add Search Criteria in TypeScript Schema: The criteria you added in "Action S1" now have to be added to the TypeScript schema. Assure the keys and types match the ones you defined in the OpenAPI specification.
More details in NgRx Search Criteria.

Template: Generated Schema

Directory	`<root-of-ui-app>/src/app/<feature>/pages/<resource>-search`
File	`<resource>-search.parameters.ts`

Adjust in <resource>-search.parameters.ts

export const <feature>SearchCriteriasSchema = z.object({
  bookTitle: z.string().optional(),
  // ACTION S2: Define members for the <resource>SearchCriteriasSchema here
} satisfies Partial<Record<keyof SearchCustomerManagementRequest, ZodTypeAny>>);

Where bookTitle is an additional search criteria added to the Search<Feature>Request.

Example

Directory	`bookstore/src/app/book/pages/book-search`
File	`book-search.parameters.ts`

Example: Adjustments in book-search.parameters.ts

export const bookSearchCriteriasSchema = z.object({
  bookTitle: z.string().optional()
  // ACTION S2: Define members for the bookSearchCriteriasSchema here
} satisfies Partial<Record<keyof SearchBookRequest, ZodTypeAny>>);

Where bookTitle is the criteria added to the SearchBookRequest.

ACTION S3

Add input fields in HTML: To make the search criteria usable for the user, you need to add corresponding HTML input fields to the search component’s HTML file.
More details in Search Criteria HTML and Example input fields.

Template: Generated HTML

Directory	`<root-of-ui-app>/src/app/<feature>/pages/<resource>-<search>`
File	`<resource>-search.component.html`

Adust Form in <resource>-search.component.html

    <form [formGroup]="bookSearchFormGroup">
      <div class="grid mt-0 p-fluid">
        <div class="col-12 md:col-3">
          <span class="p-float-label">
            <!-- ACTION S3: Change this search criteria -->
            <input
              pInputText
              id="changeMe"
              type="text"
              class="w-18rem"
              formControlName="changeMe"
              [pTooltip]="'CUSTOMER_MANAGEMENT_SEARCH.CRITERIA.CHANGE_ME.TOOLTIP' | translate"
              tooltipPosition="top"
              tooltipEvent="hover"
              role="main"
              [attr.aria-label]="
                'CUSTOMER_MANAGEMENT_SEARCH.CRITERIA.CHANGE_ME.ARIA_LABEL'
                  | translate
              "
            />
            <label for="changeMe" style="white-space: nowrap">
              {{ 'CUSTOMER_MANAGEMENT_SEARCH.CRITERIA.CHANGE_ME.LABEL' | translate }}
            </label>
          </span>
        </div>
        <!-- ACTION S3: Specify search criteria here -->
      </div>
    </form>

Where changeMe is an additional search criteria added to the Search<Feature>Request.

Example

Directory	`bookstore/src/app/book/pages/book-search`
File	`book-search.component.html`

Example: Form in book-search.component.html

    <form [formGroup]="bookSearchFormGroup">
      <div class="grid mt-0 p-fluid">
        <div class="col-12 md:col-3">
          <span class="p-float-label">
            <input
              pInputText
              id="bookstore_book_search_book_title"
              type="text"
              class="w-18rem"
              formControlName="bookTitle"
              [pTooltip]="'HELP_SEARCH.CRITERIA.BOOK_TITLE.TOOLTIP' | translate"
              tooltipPosition="top"
              tooltipEvent="hover"
              role="main"
              [attr.aria-label]="
                'HELP_SEARCH.CRITERIA.BOOK_TITLE.ARIA_LABEL' | translate
              "
            />
            <label for="bookstore_book_search_book_title" style="white-space: nowrap">
              {{ 'HELP_SEARCH.CRITERIA.BOOK_TITLE.LABEL' | translate }}</label
            >
          </span>
        </div>
        <!-- ACTION S3: Specify search criteria here -->
      </div>
    </form>

Where bookTitle is the criteria added to the SearchBookRequest.

ACTION S4

Add Translations: Ensure that all input field labels have the necessary translations added.
More details in Multi-Language.

Template: Generated Translations

Directory	`<root-of-ui-app>/src/assets/i18n`
Files	`de.json`, `en.json`

Adust translations in en.json

  "BOOK_SEARCH": {
    "CHANGE_ME": "ACTION S4: Adjust translation keys for search header",
    "HEADER": "Item Search",
    "SUB_HEADER": "Searching and displaying of items",
    ...
    "CRITERIA": {
      "INPUT_FIELDS": "ACTION S4: Adjust translation keys for input fields",
      "CHANGE_ME": {
        "LABEL": "Change Me",
        "ARIA_LABEL": "Change Me",
        "TOOLTIP": "Change Me"
      }
    }
  }

Where CHANGE_ME is an search criteria.

Example

Directory	`bookstore/src/assets/i18n`
Files	`de.json`, `en.json`

Example: Translations in en.json

  "BOOK_SEARCH": {
    "HEADER": "Book Search",
    "SUB_HEADER": "Searching and displaying of Books",
    ...
    "CRITERIA": {
      "BOOK_TITLE": {
        "LABEL": "Title",
        "ARIA_LABEL": "Title",
        "TOOLTIP": "Book title"
      }
    }
  }

Where BOOK_TITLE is the criteria added to the SearchBookRequest.

Example: Translations in de.json

  "BOOK_SEARCH": {
    "HEADER": "Büchersuche",
    "SUB_HEADER": "Suchen und Anzeigen von Büchern",
    ...
    "CRITERIA": {
      "BOOK_TITLE": {
        "LABEL": "Titel",
        "ARIA_LABEL": "Buchtitel",
        "TOOLTIP": "Buchtitel"
      }
    }
  }