Saltar a contenido

Scripting de formularios

Los formularios aceptan JavaScript: el control javascript guarda código que se ejecuta en el navegador con el formulario. Esta página lista a qué puede acceder ese código.

Encontrar un control

Función Encuentra un control por
getFieldById(id) El atributo id
getFieldByName(name) El nombre del control
getFieldByVariable(variable) La variable del caso a la que está asociado
getFieldByAttribute(attribute, value) Cualquier atributo
getFormById(id) El formulario
getSubformById(id) Un subformulario

getFieldByVariable es la que conviene usar cuando el código debe sobrevivir a un renombrado del control: la variable es la parte estable.

Un objeto de campo expone la propiedad value, y una casilla expone checked.

Leer y escribir un valor

var price = getFieldByName("price").getValue();
getFieldByName("total").setValue(price * 1.16);

getValue() devuelve lo que guarda el control: texto en un campo, un arreglo en un checkgroup y las filas en una grilla. setValue() escribe el valor de vuelta en el formulario; el caso lo guarda recién al enviarlo.

Trabajar con una grilla

Una grilla recibe fila y columna en ambos sentidos:

var grid = getFieldByName("items");
grid.addRow({});                    // una fila vacía nueva
grid.setValue(10, 0, "price");      // fila 0, columna "price"
var total = grid.getValue(0, "price");
grid.removeRow(0);

El índice de fila es la posición en la grilla y empieza en 0. Quitar una fila corre las demás, así que al limpiar varias conviene quitar desde la última hacia atrás.

Reaccionar a lo que hace el usuario

leimnud.event.add(getFieldByName('country'), 'change', function () {
  // se ejecuta cuando cambia el país
});

El evento que necesitas depende del control:

Control Evento que se dispara al cambiar el valor
text, textarea, currency, percentage blur — cuando el usuario sale del campo
checkbox click
dropdown, radiogroup, listbox, date change

Un blur no se dispara mientras el usuario sigue escribiendo, y es la razón habitual de que un cálculo "no se actualice" hasta que el usuario hace clic en otro lado.

Mostrar y ocultar

Las reglas de mostrar/ocultar condicionales usan estos ayudantes, y tu código puede llamarlos:

  • showRowById(id) y hideRowById(id) — un control.
  • showRowsById([...]) y hideRowsById([...]) — varios a la vez.

Ocultar un control no borra su valor: queda oculto, no eliminado.

Archivos externos

El código que comparten varios formularios puede vivir en un archivo público del proceso y ser incluido desde el formulario. Así hay una sola copia de la lógica en lugar de una por formulario.

Un ejemplo completo

Un formulario con quantity, price y total, donde el total sigue a los otros dos:

function recalculate() {
  var quantity = parseFloat(getFieldByName("quantity").getValue()) || 0;
  var price = parseFloat(getFieldByName("price").getValue()) || 0;
  getFieldByName("total").setValue((quantity * price).toFixed(2));
}

leimnud.event.add(getFieldByName("quantity"), "blur", recalculate);
leimnud.event.add(getFieldByName("price"), "blur", recalculate);

parseFloat con respaldo en 0 cubre el campo vacío: sin eso el resultado es NaN, que es lo que suele haber detrás de un cálculo "roto".

Depuración

La consola del navegador es el único lugar donde el script informa. Para ver qué guarda un control:

console.log("total", getFieldByName("total").getValue());

Si no aparece nada, el selector no encontró el control: revisa el nombre del control, no su etiqueta. Un script que falla en silencio normalmente lanzó el error antes de llegar al console.log, así que mira la primera línea roja de la consola, no la última.

Reglas que importan

  • El código corre en el navegador, así que un usuario puede saltearlo. Lo que debe cumplirse se verifica otra vez en un desencadenador.
  • Un error en el script detiene el resto del script; el formulario sigue funcionando, pero el comportamiento esperado no ocurre.
  • El script ve el formulario, no el servidor: no puede consultar la base de datos directamente. Usa un control con conexión de base de datos, o un desencadenador.
  • La depuración es la consola del navegador, no la vista de depuración del caso. Esa vista muestra el lado del servidor.

Relacionado