Scripts de Cliente (JavaScript Personalizado)
Los Scripts de Cliente te permiten agregar tu propio código JavaScript que se ejecuta automáticamente dentro de las pantallas de AdmCloud, sin necesidad de modificar el producto ni depender de un desarrollo a la medida. Sirven para personalizar el comportamiento de un formulario específico (por ejemplo, calcular un valor, mostrar u ocultar un campo, o validar algo antes de guardar) usando la API de JavaScript que AdmCloud expone para este fin.
¿Qué es y para qué sirve?
Un Script de Cliente es un fragmento de código JavaScript que guardas en AdmCloud para que se inyecte automáticamente en una pantalla determinada. Existen dos formas de usarlo:
- Al Cargar (por objeto/pantalla): el modo disponible para clientes finales. Eliges la pantalla (por ejemplo, una factura, un artículo o cualquier otra tarjeta o transacción) y escribes un código distinto para cuando esa pantalla se abre en modo Agregar, Editar o Ver. AdmCloud ejecuta ese código automáticamente cada vez que cualquier usuario del grupo indicado abre esa pantalla.
- Por Evento: un único script disparado por un evento específico del sistema (por ejemplo, antes o después de guardar, antes o después de un cambio de estado, o al escanear un código de barras). Esta opción solo la puede crear el personal de soporte técnico de AdmCloud o un Partner, ya que suele usarse para personalizaciones más avanzadas o para empaquetar un comportamiento dentro de un Plugin.
Esta función está pensada para negocios que necesitan un comportamiento muy específico que AdmCloud no ofrece de forma nativa, y que cuentan con alguien (interno o un Partner) capaz de escribir JavaScript usando la API que AdmCloud documenta para este propósito.
Cómo se usa
- Entra a la lista de Scripts de Cliente. Verás todos los scripts existentes con su descripción, la pantalla (objeto) a la que aplican, su propietario y si están marcados como protegidos.
- Haz clic en "Nuevo" y elige "Al Cargar". Esta es la opción disponible para usuarios finales; "Por Evento" solo aparece para soporte técnico de AdmCloud o Partners.
- Escribe un Nombre descriptivo para identificar el script en la lista, y elige el Objeto (la pantalla del sistema) donde quieres que se ejecute.
- Escribe el código JavaScript en el editor correspondiente a cada modo del formulario: cuando se está Agregando, Editando o Viendo un registro de ese objeto. Puedes dejar en blanco los modos que no necesites.
- Define quién puede usarlo y quién puede editarlo: el Grupo de Usuarios determina a quién se le ejecutará el script al abrir esa pantalla; el Propietario es responsable del script; y la casilla Protegido limita la edición o eliminación de su estructura únicamente al propietario.
- Guarda. AdmCloud valida la información (ver más abajo) y, si todo está correcto, el script queda activo de inmediato para los usuarios del grupo indicado.
- Consulta, edita o elimina un script existente desde su detalle. Si eres el propietario y tu plan lo permite, también puedes transferirlo a otra empresa del mismo Partner, indicando el correo del usuario destino.
Un script mal escrito puede romper la pantalla donde se inyecta. AdmCloud no valida la sintaxis de tu código al guardar (el editor solo resalta la sintaxis JavaScript); un error en el código puede impedir que ese formulario cargue correctamente para todos los usuarios del grupo afectado. Pruébalo primero con un grupo reducido de usuarios.
Capacidades principales
- Código JavaScript propio, inyectado automáticamente en las pantallas Agregar, Editar y Ver de un objeto del sistema, sin tocar el producto.
- Alcance controlado por Grupo de Usuarios, para que el script solo se ejecute a quienes corresponda.
- Un script "Protegido" solo puede editarlo o eliminarlo su propietario, útil cuando lo instaló un Partner o un técnico.
- Modo "Por Evento" (reservado a soporte técnico/Partners) para disparar código antes o después de guardar, de un cambio de estado, de una asignación de empleado, o al escanear un código de barras.
- Transferencia de un script a otra empresa del mismo Partner, para reutilizar una misma personalización en varios clientes.
- Enlace directo a la documentación de la API de JavaScript que AdmCloud expone, para saber qué funciones y datos puedes usar dentro del script.
Campos clave
| Campo | Para qué sirve |
|---|---|
| Nombre | Descripción del script, para identificarlo en la lista. Debe ser único. |
| Objeto | La pantalla del sistema (tarjeta o transacción) donde se ejecutará el script en modo "Al Cargar". |
| Grupo de Usuarios | Determina a qué usuarios se les ejecutará este script al abrir la pantalla indicada. |
| Propietario | El usuario responsable del script; debe ser un usuario activo. Es quien puede editarlo o eliminarlo si está marcado como Protegido. |
| Protegido | Si está marcado, solo el propietario puede modificar o eliminar la estructura del script. |
| Script al Agregar / Editar / Ver | El código JavaScript que se ejecuta cuando la pantalla del objeto elegido se abre para crear, editar o solo consultar un registro, respectivamente. |
| Evento y Código | Disponibles únicamente en el modo "Por Evento": el evento del sistema que dispara el código y el código en sí. |
Validaciones al guardar
- El Nombre es obligatorio y no puede repetirse con el de otro Script de Cliente.
- El Objeto (pantalla) debe existir dentro de las pantallas soportadas por AdmCloud.
- En scripts "Por Evento", el evento elegido debe ser compatible con el objeto seleccionado (por ejemplo, algunos eventos de cambio de estado solo aplican a Viajes o Solicitudes de Servicio, y otros eventos solo a ciertas pantallas de inventario).
- El Propietario es obligatorio y debe corresponder a un usuario activo del sistema.
- Un script Protegido solo puede ser editado o eliminado por su propietario; otros usuarios recibirán un mensaje de que no tienen permiso.
- No se puede eliminar un script si está siendo utilizado dentro de un Plugin; primero debes desvincularlo del Plugin.
Disponibilidad y permisos
- Crear, ver, editar y eliminar scripts requiere el permiso correspondiente a Personalización dentro de tu grupo de usuarios.
- La opción "Por Evento" solo se muestra a usuarios con rol de administrador o soporte de AdmCloud, gerente técnico o Partner; los usuarios finales solo pueden crear scripts "Al Cargar" por objeto.
- Transferir un script a otra empresa requiere además el permiso para crear Plugins.
Consejos y errores comunes
"No tienes permiso para modificar este script": aparece cuando el script está marcado como Protegido y quien intenta editarlo o eliminarlo no es su propietario. Solicita el cambio al propietario registrado.
No se puede eliminar el script: si el mensaje indica que está en uso dentro de un Plugin, entra al Plugin correspondiente y quita la referencia al script antes de intentar eliminarlo de nuevo.
Consulta la documentación de la API de JavaScript antes de escribir tu código; desde la lista de Scripts de Cliente hay un enlace directo a esa documentación con las funciones y datos disponibles para tus personalizaciones.
¿Necesitas que tu script se dispare por un evento del sistema (antes/después de guardar, cambio de estado, etc.) en vez de simplemente al abrir el formulario? Esa modalidad la configura el soporte técnico de AdmCloud o tu Partner; contáctalos para evaluar tu caso.