Creación de una experiencia de búsqueda basada en la configuración

Crea una experiencia de búsqueda completa utilizando un único archivo de configuración JSON. Este enfoque permite crear la página de búsqueda, la página de resultados, la tabla y un servicio API opcional, lo que ayuda a reducir la configuración manual y a garantizar un comportamiento coherente en todas las funciones.

Visión general

El esquema «Search From Config» es un generador de código basado en JSON que crea una funcionalidad de búsqueda completa con una configuración mínima. El esquema genera los siguientes componentes.

  • Componente de panel de búsqueda con campos personalizables.
  • Componente de resultados de búsqueda con ruta de navegación.
  • Componente de tabla con paginación (del lado del cliente o del lado del servidor).
  • Servicio API para la obtención de datos (opcional).
  • Archivos de configuración JSON para campos de búsqueda y columnas de tabla.
  • Archivos de traducción con etiquetas de la ruta de navegación.

Principales ventajas

Crear una experiencia de búsqueda utilizando este esquema ofrece las siguientes ventajas clave.
  • Reduce el código repetitivo hasta en un 80 %.
  • Controla el comportamiento mediante un único archivo de configuración JSON.
  • Flexibilidad a la hora de admitir la paginación tanto del lado del cliente como del lado del servidor.
  • Funciones adicionales, como activar o desactivar la opción de guardar búsquedas y actualizar.

Procedimiento

  1. En tu repositorio, crea un archivo de configuración, por ejemplo, order-search.json.
  2. En el archivo, define los metadatos necesarios.
  3. Si lo deseas, añade una sección «oms-api» para configurar la integración de la API.
  4. Si lo deseas, añade una sección de búsqueda para configurar la página de búsqueda.
  5. Si lo deseas, añade una sección de resultados de búsqueda para configurar la página de resultados.
  6. Desde la línea de comandos, ejecuta el esquema con el archivo de configuración.
    ng g @buc/schematics:search-from-config --config=order-search.json
  7. Revisa los componentes y los archivos de configuración generados.
  8. Actualiza la lógica de los marcadores de posición para que genere correctamente la consulta de la API basada en los campos de búsqueda seleccionados.
  9. Si el enrutamiento no se registra automáticamente, añade rutas en tu módulo de enrutamiento.

Referencia de mandatos

Utiliza las siguientes variantes del comando para ejecutar el esquema en diferentes situaciones.

  • Generar utilizando un archivo de configuración.
    ng g @buc/schematics:search-from-config --config=config/my-search.json
  • Previsualiza los cambios sin crear archivos.
    ng g @buc/schematics:search-from-config --config=config/my-search.json --dry-run
  • Utiliza una ruta personalizada para el archivo de configuración.
    ng g @buc/schematics:search-from-config --config=../configs/my-search.json
    .

Convenios de denominación de archivos

Utiliza patrones de nomenclatura coherentes para garantizar que los nombres de los componentes y las configuraciones sean predecibles.

Tabla 1. Convenios de denominación de archivos
Tipo de componente Patrón de nomenclatura Ejemplo
Panel de búsqueda {name}-search order-new-search
Resultados de la búsqueda {name}-search-result order-new-search-result
Tabla {name}-table order-new-search-table
Servicio {name}.service order-new-search.service
Campos de búsqueda: clave JSON {name}-search order-new-search
Clave JSON de configuración de la tabla {name}-table order-new-search-table

La estructura JSON completa

{
  "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"
        }
      ]
    }
  }
}

Metadatos

nombre
(Obligatorio) El nombre base de los componentes generados. Utiliza este valor para nombrar el panel de búsqueda, los resultados y los elementos relacionados. Por ejemplo, order-new-search.
displayName
(Obligatorio) El nombre legible para el usuario que aparece en los registros y los informes de diagnóstico. Utiliza este valor para que el contenido de los registros sea más fácil de entender.
módulo
(Opcional) El módulo de Angular en el que están registrados los componentes. Si omites este valor, el esquema generará los componentes sin registrarlos en un módulo.
paths.component
(Obligatorio) La ruta en la que se crean los componentes del panel de búsqueda y de resultados. Indique una ruta válida del proyecto donde deben ubicarse estos componentes.
paths.table
(Obligatorio) La ruta en la que se crea el componente de tabla. Utiliza esta ruta para guardar la implementación de la tabla generada.
paths.jsonFile
(Obligatorio) La ruta en la que se almacenan los archivos JSON de configuración. El esquema guarda archivos como search_fields.json y buc-table-config.json en esta ubicación.
paths.translationFile
(Obligatorio) La ruta a los archivos de traducción. Utiliza esta ruta para actualizar o crear archivos de localización, como en.json.
options.sharedLib
(Obligatorio) El nombre de la biblioteca compartida. Este valor identifica la biblioteca compartida que contiene lógica y recursos reutilizables.
options.routing
(Opcional) Activa o desactiva el enrutamiento para los componentes generados. El valor predeterminado es true. Establezca este valor en false para omitir la configuración del enrutamiento.
options.prefix
(Opcional) El selector HTML que se utilizará para los componentes generados. El valor predeterminado es buc.

Parámetros de la API de OMS

endpoints.search.apiName
(Obligatorio) El nombre del método de la API utilizado para las solicitudes de búsqueda. Por ejemplo, getOrderList.
endpoints.search.method
(Opcional) El método « HTTP » para la solicitud de la API. El valor predeterminado es POST.
requestMapping.pageNumber
(Opcional) El nombre del parámetro de la API correspondiente al número de página. El valor predeterminado es PageNumber.
requestMapping.pageSize
(Opcional) El nombre del parámetro de la API correspondiente al tamaño de la página. El valor predeterminado es PageSize.
requestDefaults
(Opcional) Valores predeterminados incluidos en cada solicitud de API. Utiliza este objeto para enviar parámetros estáticos junto con cada solicitud.
responseMapping.data
(Opcional) La ruta JSON a la matriz de datos en la respuesta de la API. El valor predeterminado es data.
responseMapping.totalCount
(Opcional) La ruta JSON que lleva al recuento total de registros en la respuesta de la API. El valor predeterminado es totalCount.

parámetros de búsqueda

fileName
(Opcional) El nombre del archivo de configuración de los campos de búsqueda. El valor predeterminado es search_fields.json.
direccionar
(Opcional) La ruta de acceso al panel de búsqueda. Si omites este valor, la ruta se generará automáticamente.
breadcrumb.label
(Opcional) La etiqueta que se utiliza en la navegación por la ruta de navegación. Si no se introduce este valor, la etiqueta se generará automáticamente.
saveSearch.enabled
(Opcional) Activa o desactiva la función de guardar búsquedas. El valor predeterminado es true.
customizeSearchCriteria.preferenceName
(Opcional) La clave de preferencias que se utiliza para almacenar la configuración del usuario. El valor predeterminado es el valor de metadata.name.
searchFieldsJson
(Opcional) El objeto de configuración del campo de búsqueda. El esquema utiliza datos de ejemplo si no se introduce ningún valor.
Nota: En la fields sección, debes actualizar las claves de traducción de los títulos en el archivo de traducción. Utilice groups para permitir la configuración a través de customizeSearchCriteria. Puedes seleccionar un grupo para incluir todos los campos de uso general.

parámetros de resultados de búsqueda

direccionar
(Opcional) La ruta de la página de resultados de búsqueda. Si omites este valor, la ruta se generará automáticamente.
breadcrumb.label
(Opcional) La etiqueta que se utiliza en la navegación por la ruta de navegación. Si no se introduce este valor, la etiqueta se generará automáticamente.
saveSearch.enabled
(Opcional) Activa o desactiva la opción de guardar búsquedas en la vista de resultados. El valor predeterminado es true.
pagination.type
(Opcional) El modo de paginación utilizado para los resultados. El valor predeterminado es server-side. Los valores admitidos son client-side y server-side.
pagination.defaultPageSize
(Opcional) El número predeterminado de registros que se muestran por página. El valor predeterminado es 25.
pagination.strategy
(Opcional) La estrategia de paginación utilizada para cargar datos adicionales. El valor predeterminado es NEXTPAGE.
refresh.enabled
(Opcional) Activa o desactiva la acción de actualización. El valor predeterminado es true.
fileName
(Opcional) El nombre del archivo de configuración de la tabla. El valor predeterminado es buc-table-config.json.
tableConfigJson
(Opcional) La configuración de las columnas de la tabla. El esquema utiliza datos de ejemplo si no se introduce ningún valor.

Características avanzadas

Utiliza estas funciones avanzadas para ampliar tu experiencia de búsqueda y hacer frente a situaciones más complejas. Estas opciones te ayudan a gestionar grandes conjuntos de datos, mejorar la usabilidad y evitar conflictos de configuración.

Estrategia de paginación de NEXTPAGE

Caso de uso
Utiliza esta estrategia cuando necesites cargar la página siguiente utilizando el último registro de la página anterior como referencia.
Configuración
{
  "search-results": {
    "pagination": {
      "type": "server-side"
    }
  }
}
Cómo funciona
  • En la primera página no se envía ningún registro anterior.
  • En las páginas siguientes, se envía la clave del último registro como PreviousPage.
  • El componente de tabla realiza un seguimiento del último registro de cada página mediante un mapa interno.

Integración de la función «Guardar búsqueda»

Activa la opción «Guardar búsqueda» para que los usuarios puedan guardar y reutilizar los criterios de búsqueda.
Comportamiento
Cuando saveSearch.enabled se establece en true, el esquema genera componentes con compatibilidad integrada para la función «Guardar búsqueda».
Características generadas
  • Guarda la búsqueda en el panel de búsqueda.
  • Posibilidad de cargar búsquedas guardadas.

Nombres de archivo personalizados

Utiliza nombres de archivo personalizados cuando gestiones varias configuraciones de búsqueda en el mismo directorio.
Configuración
{
  "search": {
    "fileName": "order-advanced-search-fields.json"
  },
  "search-results": {
    "fileName": "order-advanced-table-config.json"
  }
}
Resultado
  • Utiliza nombres de archivo personalizados en lugar de los predeterminados.
  • Ayuda a evitar conflictos entre varias configuraciones de búsqueda en la misma ubicación.