🤖 12.4. Tablero Kanban

Cómo añadir un tablero propio al Kanban de Zolteka (proveedor, filtros y filtros plegables), ofrecer una ventana de detalle de la tarjeta, abrirla desde otra página y registrar criterios de orden y etiquetas de tarjeta.

Requisitos: Zolteka 2.30 o superior, FacturaScripts 2026.65 o superior y PHP 8.1 o superior. Cada apartado indica desde qué versión de Zolteka existe lo que describe; esta subpágina recoge hasta la 2.30.

📍 Esta es una subpágina de 12. Zolteka para desarrolladores. Antes de empezar, lee su apartado Antes de empezar: comprobar que Zolteka está activo y registrar en Init::init().

📍 En esta página:

12.4.1. Proveedor del tablero y registros

  • Tablero propio: implementa KanbanProviderInterface y regístralo con KanbanRegistry::register(). Opcionales: KanbanDetalleInterface (ventana de detalle), KanbanFiltrosInterface (barra de filtros), KanbanFiltrosPlegadosInterface (barra de filtros plegada al empezar) y KanbanOrdenableInterface (ordenar por). Los cuatro tableros de presupuestos y pedidos ya los registra Zolteka.
  • Etiquetas en las tarjetas (experimental, desde la 1.77): KanbanEtiquetaRegistry::register() con un KanbanEtiquetaProviderInterface.
  • Criterios de «Ordenar por» (experimental, desde la 1.77): KanbanOrdenRegistry::register() con un KanbanCriterioOrdenInterface. Tu plugin no escribe SQL: indica la tabla y la columna de donde sale el dato.
  • Los pasos que crean otro documento siguen haciéndose desde la ficha. No copies el controlador, el JavaScript ni el CSS del tablero.

Las etiquetas de documentos y de tus modelos (no las de tarjeta) están en 12.2. Etiquetas de colores. Para un calendario de consulta de solo lectura, mira 12.3.5. Calendario de consulta reutilizable.

12.4.2. Filtros plegados al empezar

(Desde la 2.06.) Si tu proveedor implementa además KanbanFiltrosPlegadosInterface, su tablero nace con la barra de filtros plegada hasta que el usuario elija. KanbanFiltrosInterface no cambia: el proveedor implementa las dos.

class MiProveedor implements KanbanProviderInterface, KanbanFiltrosInterface, KanbanFiltrosPlegadosInterface
{
    public function filtrosPlegadosPorDefecto(): bool
    {
        return true;
    }
    // ... resto del contrato
}

El estado inicial del panel de escritorio se decide por este orden: filtros activos en la URL (abierto), preferencia guardada por el usuario, defecto que declara el tablero y, por último, el ancho de la pantalla.

12.4.3. Detalle de la tarjeta en ventana

Interfaz KanbanDetalleInterface. Para tareas, proyectos u oportunidades, un tablero puede ofrecer una ventana de detalle: modal en escritorio y pantalla completa en móvil. Zolteka pone la carcasa; el plugin declara sus campos o su plantilla. Se activa con KanbanZolteka?board=<clave>&detalle=modal o con detail: 'modal' en el parcial Master/_kanban_board.html.twig. Los métodos de la interfaz son modoDetallePorDefecto(), detalle(), guardarDetalle(), tarjeta() y detalleAssets().

detalle() devuelve titulo (obligatorio), subtitulo, url, tamano (md, lg o xl), campos, plantilla y datos. Desde la 2.07 admite además:

  • cabecera: plantilla Twig que se pinta al principio del cuerpo, fuera del formulario de los campos. Recibe detalle y puedeEditar.
  • barra: plantilla Twig en una franja fija abajo, fuera de la zona con scroll, también a pantalla completa en móvil. Sus botones no guardan y sus controles no viajan al guardar. Tu JavaScript se engancha con detail.barra del evento zolteka-kanban:detalle-abierto.
  • secciones: pestañas (máximo 8) con clave, etiqueta, contador opcional, campos y plantilla. El contador se actualiza con window.ZoltekaKanban.detalleContador(clave, texto).
  • pie: 'siempre' (por defecto) o 'cambios'. Con 'cambios' la franja «N cambios sin guardar», con Descartar y Guardar, solo aparece cuando hay cambios y permiso de edición; cerrar con cambios pide confirmación. Descartar lanza zolteka-kanban:detalle-descartado.

12.4.4. Abrir el detalle desde otra página

(Desde la 2.07.) Para abrir el detalle de una tarjeta fuera del tablero, incluye en {% block body %} de tu página:

{% include 'Master/_kanban_detalle_suelto.html.twig' with {board: '<clave>'} %}

Variables: board, url (por defecto KanbanZolteka), assets (por defecto true: carga el CSS y el JavaScript del tablero y los detalleAssets() del proveedor) y tom_select (por defecto false). No carga columnas, tarjetas, filtros ni arrastre, y si el tablero no está disponible para el usuario no pinta nada. En JavaScript, window.ZoltekaKanban.detalleDisponible() indica si hay detalle (si es false, sigue el enlace a la ficha) y abrirDetalle(id) lo abre sin navegar por su cuenta. El token CSRF se renueva en todos los input[name="multireqtoken"] de la página: si tu código consume tokens, debe hacer lo mismo, porque cada token es de un solo uso.

Eventos en document: zolteka-kanban:detalle-abierto, zolteka-kanban:detalle-cerrado, zolteka-kanban:detalle-guardado y, de entrada, zolteka-kanban:tarjeta-actualizada. El JavaScript y el CSS de tu plugin llegan por detalleAssets(), nunca dentro del HTML.


Las Condiciones de uso de la página de entrada valen para esta subpágina, incluido el aviso de que los ejemplos de código son orientativos y se ofrecen sin garantía.

Cookies
Usamos cookies necesarias para el funcionamiento del sitio y cookies opcionales para recordar tus preferencias y mejorar tu experiencia. Puedes aceptarlas todas, rechazarlas o configurar tus preferencias

Soporte