Parrillas de búsqueda

Las parrillas de búsqueda son la vista de lista (grid) que aparece al abrir una opción de a3ERP — clientes, facturas, pedidos... — o en las pantallas de selección de ficheros. A diferencia de los listados de impresión, el resultado no se imprime: se presenta como tabla interactiva dentro de la aplicación, con sus filtros, su ordenación y su búsqueda por texto.

Personalizando el SQL de una parrilla se controla qué columnas ve el usuario y de dónde salen: se pueden añadir campos calculados, cruzar con otras tablas o traer información que la parrilla estándar no muestra. En las plantillas hay un esqueleto completo y los retoques más habituales.

Dónde se personaliza#

En la propia opción, sin ir a ninguna pantalla de configuración aparte: el desplegable Ver elige la consulta que alimenta el grid, y el botón SQL que tiene al lado abre la ventana de personalización. Ahí conviven las consultas de sistema — las que trae a3ERP de serie, cuyo SQL se puede consultar como referencia — y las consultas personalizadas, las tuyas, que una vez creadas aparecen en el desplegable Ver a disposición del usuario. Todas las opciones funcionan igual; esta es la de clientes:

Ventana de personalización de la SQL de la selección de Clientes, con las consultas de sistema y el SQL con sus marcadores

Parámetros runtime#

La parte delicada de una parrilla es que sus filtros — los rangos, el texto de búsqueda, la selección de registros — no los aplica tu SQL, sino el usuario desde la interfaz. El intérprete de a3ERP los inyecta en la consulta sustituyendo una serie de marcadores que deben estar presentes en el WHERE. Si quitas un marcador, la parrilla deja de respetar ese filtro sin dar ningún error: el usuario filtra y la parrilla le devuelve resultados como si no lo hubiera hecho.

Parámetro	Cuándo se inyecta
`[CondicionReferenciaDocumento, Sysname, 1 = 1]`	Filtro por documento de referencia
`[DevolverRegistros, SysName, 1 = 1]`	Limita el número de filas devueltas
`[CondicionTabla, SysName, 1 = 1]`	Condición sobre la tabla principal
`[Filtro, SysName, 1 = 1]`	Filtro genérico de la parrilla
`[CondicionIdentificadores, SysName, 1 = 1]`	Filtro por identificadores internos
`[CondicionCodigo, SysName, 1 = 1]`	Filtro por código de registro
`[CondicionRepresentante, Sysname, 1 = 1]`	Filtro por representante/agente
`[CondicionFechasDocumento, SysName, 1 = 1]`	Filtro por rango de fechas del documento
`[CondicionNumeroDocumento, Sysname, 1 = 1]`	Filtro por número de documento
`[TextoBusqueda, SysName, '']`	Texto libre — se usa para filtrar columnas propias de la consulta

El tercer campo de cada marcador es su valor por defecto — normalmente 1 = 1, o '' en el caso del texto — y es lo que el intérprete inyecta cuando el usuario no ha tocado ese filtro. Gracias a eso la consulta siempre es SQL válido, haya filtros activos o no.

El uso típico de [TextoBusqueda] se ve en las propias consultas de sistema: una primera condición lo hace opcional (si el usuario no escribe nada, pasan todas las filas) y el resto lo aplica con LIKE a cada columna donde tenga sentido buscar:

AND ( ( '[TextoBusqueda, SysName, '']' = '' ) OR
      ( CLIENTES.CODCLI LIKE '%[TextoBusqueda, SysName, '']%' ) OR
      ( CLIENTES.NOMCLI LIKE '%[TextoBusqueda, SysName, '']%' ) OR
      ( CLIENTES.TELCLI LIKE '%[TextoBusqueda, SysName, '']%' ) )

Si tu consulta personalizada añade columnas en las que el usuario querrá buscar, hay que sumarlas a esa cadena de OR — el texto libre solo busca en las columnas que tú le digas.

Una parrilla también puede llevar parámetros de usuario [Nombre,TIPO,Default] que a3ERP pide antes de cargar el grid. Es poco común, pero posible — la sintaxis completa está documentada en el artículo de vistas SQL, que es donde más se usan.

Trampas frecuentes#

No usar corchetes [...] como alias de columna. El intérprete de a3ERP los lee como marcadores de parámetro — igual que [CondicionTabla, SysName, 1 = 1] — y la parrilla peta. Los alias van siempre con comillas simples: CASE ... END 'Es venta nueva', no CASE ... END [Es venta nueva].
No usar : ni [...] en comentarios SQL. El intérprete los trata como parámetro y marcador también dentro de los comentarios (-- y /* */), y la parrilla falla con Sentencia incorrecta: Objeto Parameter mal definido. Se proporcionó información incompleta o incoherente. — la misma restricción que en listados y vistas. Reformular sin esos caracteres.
No usar parámetros con : (:nIdent, etc.). Ese mecanismo solo está activo en los listados de impresión; en una parrilla no hay documento "actual" que inyectar.
WITH (NOLOCK) en todos los joins, como en el resto de artefactos: la parrilla se carga cada vez que alguien abre la opción, en plena actividad de producción.

Cómo probar un cambio#

Abrir la opción, pulsar el botón SQL y pegar la consulta en la personalizada correspondiente.
Volver al grid y comprobar que devuelve las columnas esperadas, ordena bien y rinde a buen ritmo.
Probar con y sin filtros activos — rangos, texto de búsqueda, selección — para verificar que los marcadores [Condicion*] y [TextoBusqueda] siguen haciendo su trabajo.