Interacción: cálculos, condiciones y validaciones

Nota

Página generada a partir de histrix-1.0.xsd con scripts/gen_schema_docs.py. Las descripciones salen del schema, que está verificado contra el código del motor. Para corregir un texto hay que corregir el XSD y volver a generar.

Los elementos que dan comportamiento a un campo sin escribir código en un archivo aparte: cálculos en el navegador, evaluación condicional en el servidor, propagación de valores entre campos y validaciones.

<jseval>

Evaluación de código JavaScript al cambiar el campo. El resultado se asigna al destino. Debe estar presente uno de campodestino o fielddestino (alias).

Regla crítica: para cálculos aritméticos puros usar actxml="false" — sin ese atributo el motor envía un PUT al server por cada cambio (en grillas grandes esto explota en cientos de requests innecesarios).

• Va dentro de: <campo> (0..n), <field> (0..n)
• Contenido: texto libre.
• Atributos: 4 (propios)

Atributos

actxml

ActXmlValor · opcional

Default “true”: envía request al server por cada cambio. “false”: el JS se resuelve en el browser sin request (preferido para aritmética pura).

campodestino

texto · opcional

id del campo destino donde se asigna el resultado del JS.

fielddestino

texto · opcional

Alias inglés de campodestino.

total

BoolEstricto · opcional

Si “true”, el JS calcula el total de columna (footer del grid).

<jsfunction>

Función JS asociada a un evento del campo (onfocus, onblur, onkeypress…). El atributo event declara el nombre del evento.

• Va dentro de: <campo> (0..n), <field> (0..n)
• Contenido: texto libre.
• Atributos: 1 (propios)

Atributos

event

texto · obligatorio

Nombre del evento DOM (sin “on”: “focus”, “blur”, “change”…).

<if>

Estructura condicional de un <field>: <if exp="..."><true>X</true><false>Y</false></if>. exp se evalúa como PHP en el servidor y el campo toma el contenido de la rama que corresponda. Los identificadores sin comillas se reemplazan por el valor de los <field> declarados en el XML: un identificador que no esté declarado como <field> hace fallar la evaluación en silencio y se toma la rama <false> — el síntoma es un campo vacío sin ningún error (y si ese campo es el idCampoCond de una tabla, el registro no graba).

La comparación entera va dentro de exp: operador y valor no se leen — el parser los guarda pero la evaluación del <if> nunca los consume, así que los 75 XMLs que escriben <if operador="..."> no obtienen nada de eso.

Sólo el <if> de un <field> tiene esta forma. El de <order>, <group>, <filters>, <fieldGroup> e <include> es otra cosa: no lleva exp ni ramas, es texto PHP que decide si el bloque entero se procesa.

• Va dentro de: <campo> (0..n), <field> (0..n), <orden> (0..1), <order> (0..1)
• Atributos: 1 (propios)

Contenido

Elemento	Veces	Descripción
<true>	1	Valor/expresión devuelto si la condición es truthy.
<false>	0..1	Valor/expresión devuelto si la condición es falsy. Opcional: sin esta rama, cuando la condición da falso el campo queda vacío.
<verdadero>	1	Alias español legacy de <true>. El motor lo reconoce explícitamente como forma vieja: al encontrarlo activa el modo de compatibilidad del parser.
<falso>	0..1	Alias español legacy de <false>.

Atributos

exp

texto · opcional

Expresión PHP a evaluar. Los <field> declarados son referenciables por nombre sin comillas.

<true>

Valor/expresión devuelto si la condición es truthy.

• Va dentro de: <if> (1)
• Contenido: texto libre.

No acepta atributos.

<false>

Valor/expresión devuelto si la condición es falsy. Opcional: sin esta rama, cuando la condición da falso el campo queda vacío.

• Va dentro de: <if> (0..1)
• Contenido: texto libre.

No acepta atributos.

<visibleWhen>

Muestra u oculta este campo según una condición: el tag va sobre el campo controlado, no sobre el que dispara la condición. Al ocultarlo esconde la celda entera del campo y la de su <label>, y le saca el required, para que el formulario no quede trabado pidiendo un campo que no se ve.

La condición se escribe como la de un <jseval>: los id de otros campos van sin comillas y el motor los reemplaza por su valor, así que exige_obs == 1 muestra el campo cuando exige_obs vale 1. Ese reemplazo convierte el valor a número, de modo que la comparación contra un número funciona y la comparación contra texto —== 'A'— no es confiable.

Se resuelve entero en el navegador: no genera SQL, no pide nada al servidor y se re-evalúa con cada cambio de cualquier campo del formulario, incluidos los que llena un combo o un helper. No es lo mismo que <if> o noshow, que deciden en el servidor una sola vez, al armar la pantalla, y no vuelven a mirar nada.

Es el reemplazo declarativo del <customScript> que había que escribir para esto. Si se declara más de una vez en el mismo campo, vale la última.

• Va dentro de: <campo> (0..n), <field> (0..n)
• Contenido: texto libre.

No acepta atributos.

<requiredWhen>

Hace obligatorio este campo mientras se cumpla la condición, y le saca la marca cuando deja de cumplirse. Va sobre el campo que se vuelve obligatorio.

Un campo oculto nunca queda obligatorio: si la condición da verdadera pero la celda del campo está escondida —por un <visibleWhen> o por cualquier otro motivo— el required no se aplica.

La condición se escribe igual que la de <visibleWhen>, con las mismas reglas de reemplazo y la misma reactividad; el detalle está ahí. Si se declara más de una vez en el mismo campo, vale la última.

• Va dentro de: <campo> (0..n), <field> (0..n)
• Contenido: texto libre.

No acepta atributos.

<enabledWhen>

Habilita este campo mientras se cumpla la condición y lo deshabilita cuando deja de cumplirse. Va sobre el campo que se habilita.

Deshabilitar es sólo apagar el control: el campo sigue en la pantalla y en el formulario, a diferencia de <visibleWhen>, que lo esconde. Tampoco toca el required.

La condición se escribe igual que la de <visibleWhen>, con las mismas reglas de reemplazo y la misma reactividad; el detalle está ahí. Si se declara más de una vez en el mismo campo, vale la última.

• Va dentro de: <campo> (0..n), <field> (0..n)
• Contenido: texto libre.

No acepta atributos.

<actualiza>

Al cambiar el campo padre, propaga su valor a otros campos/combos/grilla/helpers. Cada <field> declara un destino. Para combos: el valor se inserta en un campo del combo con <detalle> que define el nombre lógico.

De cada <field> destino sólo se leen id, destino y xml. Cualquier otro atributo (oculto, por ejemplo, que 23 XMLs escriben acá) y el texto del tag se ignoran.

• Va dentro de: <campo> (0..n), <field> (0..n)

Contenido

Elemento	Veces	Descripción
<field>	0..n	Destino de la actualización: campo, combo o grid embebido.
<campo>	0..n	Alias español de <field> como destino de la actualización.

No acepta atributos.

<validations>

Validaciones por campo, en plural. Es un mecanismo distinto del <validation> singular: construye una validación por cada <field> del bloque, que compara el valor del campo contra el resultado de una <expression> SQL usando el <operator>.

El plural es obligatorio. Con <validation> (singular) el bloque se ignora en silencio: el singular busca <condition> y <message> directos y no mira los <field>. No hay error en ningún log — la validación simplemente deja de existir.

• Va dentro de: <tabla> (0..n), <table> (0..n)

Contenido

Elemento	Veces	Descripción
<field>	1..n	Campo a validar. El id es el campo del form cuyo valor se compara.

No acepta atributos.

<validation>

Validación del formulario, en singular: <condition> + <message>. Si la condición no se cumple se muestra el mensaje y no se graba.

La condición es JavaScript que corre en el browser, no SQL ni PHP. Se evalúa reemplazando los nombres de campo por el valor del input correspondiente del DOM, así que sólo ve campos que existan como input: con oculto="true" el campo no se renderiza y la validación nunca dispara; con noshow="true" el input sigue en el DOM y sí funciona. Los atributos operador y valorde que admite el tipo de la <condition> pertenecen a la <condicion> SQL de un campo: acá no se leen.

No confundir con <validations> (plural), que es otro mecanismo — compara el valor de un campo contra el resultado de un SELECT. Y en singular no hay alias español: hay 20 validaciones escritas con <condicion> que no existen.

• Va dentro de: <fieldGroup> (0..n), <include> (0..n), <tabla> (0..n), <table> (0..n)
• Atributos: 1 (propios)

Contenido

Elemento	Veces	Descripción
<condition>	1	Condición (expresión) que debe cumplirse para pasar la validación.
<message>	1	Mensaje a mostrar si la condición no se cumple.

Atributos

optional

BoolEstricto · opcional

Sin descripción en el schema.

<message>

Mensaje de error si la validación falla. Default “Valor invalido”.

• Va dentro de: <field> (0..n), <validation> (1)
• Contenido: texto libre.

No acepta atributos.

<eval>

No es JavaScript: es PHP que corre server-side al parsear el XML, y decide si el campo existe. Si el código no devuelve un valor verdadero, el <field> no se agrega al contenedor: no se renderiza, no entra al SELECT y no graba. La forma habitual es if (...) return true;.

• Va dentro de: <campo> (0..n), <field> (0..n)
• Contenido: texto libre.

No acepta atributos.

<falso>

Alias español legacy de <false>.

• Va dentro de: <if> (0..1)
• Contenido: texto libre.

No acepta atributos.

<verdadero>

Alias español legacy de <true>. El motor lo reconoce explícitamente como forma vieja: al encontrarlo activa el modo de compatibilidad del parser. Funciona, pero en código nuevo va <true>.

• Va dentro de: <if> (1)
• Contenido: texto libre.

No acepta atributos.

<campo> en <actualiza>

Alias español de <field> como destino de la actualización.

• Va dentro de: <actualiza> (0..n)
• Contenido: texto libre.
• Atributos: 3 (propios)

Acepta los mismos 3 atributos que <field>, que es donde están documentados.

<field> en <actualiza>

Destino de la actualización: campo, combo o grid embebido.

• Va dentro de: <actualiza> (0..n)
• Contenido: texto libre.
• Atributos: 3 (propios)

Atributos

destino

texto · opcional

Si el destino es un combo/grid: nombre del subcampo dentro del helper (matchea con <detalle>).

id

texto · obligatorio

id del campo o helper destino.

xml

texto · opcional

XML del helper destino (cuando ambiguo).

<field> en <validations>

Campo a validar. El id es el campo del form cuyo valor se compara.

• Va dentro de: <validations> (1..n)
• Atributos: 1 (propios)

Contenido

Elemento	Veces	Descripción
<expression>	0..n	SELECT cuyo resultado se compara con el valor del campo. Soporta '[__campo__]' para interpolar otros campos del form.
<operator>	0..n	Operador de comparación (==, !=, …). Default ==. Suele ir en CDATA cuando lleva < o >.
<message>	0..n	Mensaje de error si la validación falla. Default “Valor invalido”.
<value>	0..n	Valor literal contra el que comparar, como alternativa a <expression>.

Atributos

id

texto · obligatorio

Sin descripción en el schema.