Desplegables de relación

Convierte una columna de clave foránea en bruto en un desplegable, un combobox con búsqueda o una selección múltiple resuelta contra otra tabla con relation().

Qué hace relation()

relation() vincula una columna real y editable de la tabla actual (por ejemplo, payments.customerNumber) con una búsqueda contra otra tabla. El formulario de creación/edición muestra un desplegable con las filas de esa tabla en lugar de un simple campo numérico de id, y el listado muestra el nombre resuelto en lugar del id en bruto.

$xcrud->relation(
    'customerNumber', 'customers', 'customerNumber', 'customerName',
    "country = 'USA'", null, false, ' ', null, null, null, true
);

La tabla de destino debe ser accesible de la misma forma que cualquier otra tabla del sitio: una tabla real, no incluida en la lista negra, con una clave primaria de una sola columna. No necesita tener su propia página CRUD; relation() puede leer una tabla que nada más en el sitio explora directamente.

Parámetros

Parámetro	Tipo	Por defecto	Descripción
`$field`	string	-	La columna real y editable de esta tabla que se vincula (por ejemplo, `customerNumber`).
`$targetTable`	string	-	La tabla en la que se buscan los valores.
`$targetId`	string	-	Columna de `$targetTable` cuyo valor se guarda de vuelta en `$field`.
`$targetName`	string\|array	-	Columna(s) mostradas como etiqueta de la opción. Un array (por ejemplo, `['contactFirstName', 'contactLastName']`) se une con `$concatSeparator` para mostrar algo como "Nombre Apellido".
`$where`	array\|string\|null	`null`	Restringe qué filas de destino se ofrecen. Un array es una igualdad segura columna=>valor, combinada con AND y vinculada como parámetros. Una cadena es SQL en bruto de confianza, escrita por el desarrollador (mismo nivel de confianza que `where_raw()`), opcionalmente con marcadores `{field}` sustituidos por el valor propio de la fila actual.
`$orderBy`	string\|null	`null`	Orden de la lista de opciones.
`$multi`	bool	`false`	Renderiza una selección múltiple en lugar de un desplegable único; el valor almacenado se convierte en una lista de ids separada por comas.
`$concatSeparator`	string	`' '`	Separador usado cuando `$targetName` es un array de columnas.
`$tree`	mixed	`null`	Reservado para un futuro desplegable jerárquico/en árbol con sangría; aún no implementado; pasar un valor distinto del predeterminado lanza una excepción.
`$dependField`	string\|null	`null`	Columna de `$targetTable` por la que filtrar, comparada con el valor actual de `$dependOn`. Consulta Desplegables en cascada / dependientes.
`$dependOn`	string\|null	`null`	Nombre de otro campo configurado con `relation()` en esta tabla cuya selección actual controla el filtro anterior.
`$search`	bool	`false`	Renderiza un combobox con búsqueda (un campo de texto que filtra la lista de opciones obtenida a medida que se escribe) en lugar de un simple `<select>`; útil en cuanto hay decenas de opciones. Se combina con `$multi` para obtener chips eliminables.

Filtrar la lista de opciones

La forma en array de $where es la opción segura por defecto: igualdad simple, parametrizada:

$xcrud->relation('catid', 'categories', 'cid', 'name', ['published' => 1]);

La forma en cadena es un fragmento SQL en bruto para cualquier cosa que un array de igualdad no pueda expresar; es SQL de confianza, escrito por el desarrollador, nunca construido a partir de entrada del usuario:

$xcrud->relation('customerNumber', 'customers', 'customerNumber', 'customerName', "country = 'USA'");

Sea cual sea la forma usada, toda la configuración de la relación -tabla, columna de id, columna(s) de nombre, where, orden, multi- está firmada con HMAC mediante XcrudConfig::$appSecret de la misma forma que un filtro where() base, de modo que no puede reorientarse ni ampliarse editando nada del lado del cliente.

subselect(): una columna calculada de solo lectura

Mientras que relation() resuelve una clave foránea editable, subselect() añade una columna de solo visualización calculada a partir de una expresión SQL correlacionada arbitraria; no se guarda nada de vuelta en ella, y nunca es editable, ordenable ni buscable.

$xcrud->subselect(
    'orderCount',
    'SELECT COUNT(*) FROM orders o WHERE o.customerNumber = payments.customerNumber'
);

$field se convierte en una nueva columna junto a las reales de la tabla y debe ser un identificador válido que aún no sea el nombre de una columna real. $sql es SQL de confianza, escrito por el desarrollador; al igual que la cadena $where en bruto de relation(), se firma con HMAC mediante XcrudConfig::$appSecret cuando se renderiza la página y se vuelve a verificar en cada solicitud, de modo que un visitante no puede manipularlo, pero nunca se valida ni se ejecuta en un entorno aislado frente a lo que escribas; mantenlo siempre escrito por el servidor, nunca ensamblado a partir de la entrada de la solicitud.

Desplegables en cascada

$dependField/$dependOn hacen que las opciones de un desplegable de relación se filtren según el valor actualmente seleccionado de otro campo en el mismo formulario; por ejemplo, un desplegable de Ciudad que solo ofrece ciudades del País actualmente seleccionado. Consulta Desplegables en cascada / dependientes para el recorrido completo, incluidas las cadenas de varios niveles.