Manual de EasyFields

EasyFields permite añadir campos personalizados a cualquier ficha de FacturaScripts (Cliente, Producto, Factura…) sin programar, organizados en pestañas. Los datos se guardan en tablas propias del plugin (almacenamiento EAV tipado), sin modificar el esquema del core, de modo que la desinstalación es limpia y robusta ante actualizaciones.

Versión del core: FacturaScripts 2025+ (probado en 2026.x, PHP 8.1+). Idiomas: esES / enEN.

Versión del plugin documentada: 0.1

Si esta versión no coincide con la del plugin instalado (Admin → Plugins), el manual podría estar desactualizado.

1. Conceptos

| Término | Significado |

|----------------|-------------|

| Target | Modelo del core al que se añaden campos: Cliente, Producto, FacturaCliente… |

| Campo | Una definición: clave, etiqueta, tipo, reglas, grupo… |

| Grupo | Nombre de la pestaña donde se agrupa el campo. Cada grupo distinto = una pestaña. |

| Catálogo | Lista de opciones reutilizable para campos select / multiselect. |

| Valor | El dato concreto guardado para un registro (p. ej. la talla del cliente nº 5). |

Cada group_name distinto genera una pestaña en la ficha del target. Los campos sin grupo caen en la pestaña por defecto "Campos personalizados", que siempre queda al final.

2. Crear un campo personalizado

Admin → Campos personalizados → Nuevo.

Datos generales

• Modelo destino (target): desplegable con los modelos del core (Cliente, Producto,

Factura de cliente, Pedido…).

• Clave: identificador único del campo dentro del target. Sin espacios (usa

talla_zapato, no talla zapato).

• Etiqueta: texto visible junto al campo en la ficha.
• Grupo (pestaña): nombre de la pestaña. Vacío = pestaña "Campos personalizados".
• Tipo: ver la tabla de tipos más abajo.
• Orden: posición del campo dentro de su pestaña (menor = antes).
• Activo: si está desmarcado, el campo no se muestra.
• Obligatorio: bloquea el guardado de la pestaña si se deja vacío.
• Filtrable en listado: añade un filtro por este campo en el listado del target

(ver sección 5).

Tipos de campo

| Tipo | Se muestra como | Notas |

|---------------|-----------------|-------|

| text | Caja de texto | Reglas de longitud / patrón. |

| textarea | Área de texto | Texto largo. |

| number | Numérico | Reglas de valor mínimo / máximo. |

| date | Selector de fecha | |

| boolean | Casilla | Sí / no. |

| select | Desplegable | Opciones desde catálogo, lista en línea o relación. |

| multiselect | Selección múltiple | Igual que select pero admite varios valores. |

| relation | Desplegable de registros | Apunta a otro modelo del core (ver sección 4). |

| file | Subida de fichero | Uno o varios adjuntos (Máximo de ficheros). |

| photo | Subida de imagen | Solo imágenes. |

Reglas de validación (pestaña Validación)

Según el tipo: longitud mínima/máxima, valor mínimo/máximo y patrón (expresión regular sin delimitadores, p. ej. ^[0-9]{9}$). La validación es de servidor y bloqueante: si algo no cumple, no se guarda nada de esa pestaña y se muestran los errores.

3. Opciones para select / multiselect

En la pestaña Opciones del campo, tres formas (excluyentes) de poblar las opciones:

1. Catálogo: elige un catálogo reutilizable (ver sección 6).
2. Opciones manuales: una por línea, formato valor|etiqueta

(p. ej. S|Pequeña, M|Mediana). Si omites la etiqueta, se usa el valor.

1. Relación: rellena Modelo de la relación (entonces el tipo suele ser relation).

4. Campos de tipo relation

Un campo relation con Modelo de la relación = Proveedor muestra en la ficha un desplegable con todos los proveedores (por su nombre), y guarda el código del proveedor elegido. Funciona con cualquier modelo del core (Cliente, Agente, Almacén…).

Ejemplo: en Producto, un campo relation a Proveedor para indicar el "proveedor predeterminado" de cada artículo.

5. Filtrar listados por un campo

Marca el campo como Filtrable en listado. En el listado del target (p. ej. Productos) aparecerá un desplegable de filtro con:

• (todos) — sin filtro.
• ✓ \<etiqueta> — registros que tienen valor.
• ✗ \<etiqueta> — registros sin valor.
• Para select/multiselect/relation: una opción por cada valor posible

(cada proveedor, cada opción del catálogo…).

El filtro restringe el listado con una subconsulta sobre los valores del plugin.

6. Catálogos (opciones reutilizables)

Admin → Campos personalizados → pestaña Catálogos.

Un catálogo es una lista de opciones con nombre que puedes reutilizar en varios campos select/multiselect. Cada opción tiene valor, etiqueta, orden y activo. Edita el catálogo y sus opciones en línea (maestro-detalle).

7. Rellenar los campos en una ficha

1. Abre una ficha del target (p. ej. un Cliente). Aparece una pestaña por grupo.
2. Rellena los campos y pulsa Guardar dentro de esa pestaña.
   • Cada pestaña es su propio formulario: tiene su botón de guardado independiente

del de la ficha nativa.

• Si un campo obligatorio está vacío (o falla una regla), no se guarda esa

pestaña y se muestran los errores conservando lo introducido.

1. Los valores se recargan al volver a abrir la ficha.

Nota: para campos de tipo fichero/foto, primero guarda la ficha del core (para que el registro tenga código) y luego sube los adjuntos.

8. Borrado en cascada

Al eliminar un registro del core (p. ej. borrar un Cliente), EasyFields elimina automáticamente todos sus valores personalizados y los adjuntos asociados. No quedan datos huérfanos.

9. Administración: las tres pestañas

Admin → Campos personalizados:

• Campos: alta/edición de definiciones (lo de la sección 2).
• Catálogos: gestión de catálogos y sus opciones (sección 6).
• Valores: vista de los valores guardados (auditoría / depuración).

10. Preguntas frecuentes

¿Modifica las tablas del core? No. Todo vive en tablas easyfields_* propias.

¿Qué pasa al desinstalar? Las tablas easyfields_* se conservan por seguridad de datos; el borrado se gestiona aparte con aviso.

Puse una clave con espacios y algo falla. Usa claves sin espacios (identificadores). La etiqueta sí puede tener espacios y acentos; la clave no.

El campo obligatorio no bloquea el guardado de la ficha nativa. Correcto: el core guarda la ficha antes de ejecutar la lógica del plugin. El required bloquea el guardado de su pestaña, no el de la pestaña principal del core.