🤖 12.5. Cuadro de mando

Cómo añadir pestañas, avisos y bloques al cuadro de mando de Zolteka desde otro plugin, excluir datos de los indicadores de tesorería y reutilizar las clases 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.5.1. Bloques debajo de los recibos y exclusiones de tesorería

  • Añadir un bloque debajo de los recibos: crea en tu plugin la vista Extension/View/DashBoardZolteka_AfterReceiptsSummary_MiPlugin.html.twig. El sufijo con el nombre de tu plugin evita que otro plugin con el mismo archivo tape el tuyo. (Solo por compatibilidad con plugins anteriores; para lo nuevo usa una pestaña.)
  • Excluir datos de los indicadores de tesorería: DashBoardZolteka::addTreasuryCycleInvoiceExclude() (facturas) y DashBoardZolteka::addTreasuryReceiptPaymentExclude() (formas de pago). Compruébalos antes con class_exists() y method_exists().

12.5.2. Pestañas propias del panel

(Desde la 2.16.) El panel tiene una cabecera común y luego las pestañas. Zolteka no conoce a otros plugins: cada uno añade la suya con el registro ZoltekaDashboardTabs. Zolteka registra resumen (posición 10) y tesoreria (20); la de zAnticipos es anticipos (30).

  • ZoltekaDashboardTabs::registrar(ZoltekaDashboardTab $pestana): void. Si el id ya existe, gana el último registro.
  • ZoltekaDashboardTab se crea con el constructor o con ZoltekaDashboardTab::fromArray(). Campos: id (^[a-z0-9-]{1,40}$, es también el ancla #tab-{id}), titulo (clave de traducción), icono, posicion, plantilla (.twig, sin ..), lazy y los callables visible, datos, contador y avisos. Un dato no válido lanza InvalidArgumentException.
  • Los callables reciben un ZoltekaDashboardContexto con desde, hasta, rango, vsAnterior, idempresa, codEmpresa, user y permissions. El periodo y la empresa de la cabecera valen para todas las pestañas.
  • La plantilla de la pestaña recibe solo fsc, pestana, datos y ctx, y se pinta también por AJAX con la acción tab del controlador DashBoardZolteka. No puede llevar <script>: tu JavaScript escucha zolteka:panel-pendiente y zolteka:panel-inicializado, que suben hasta document.
  • Las pestañas lazy se piden la primera vez que se abren. La pestaña activa se guarda en el hash de la URL y en el navegador.
  • Avisos «Requiere atención»: cada aviso es {texto, importe?, url?, tab?, nivel} con nivel info, atencion o grave. El texto se sanea y se corta en 300 caracteres, y url solo admite rutas relativas. El contador de la pestaña es el número de tipos de aviso con pendientes (no de documentos) y su nivel es el del aviso más grave; una pestaña con callable avisos deriva el contador de ellos (desde la 2.17).

⚠️ Protección obligatoria al registrar desde otro plugin. Registra desde tu Init, con las clases nombradas en texto, y protege la llamada con Plugins::isEnabled('Zolteka'), class_exists() y method_exists(), todo dentro de try/catch(Throwable). Así no importa el orden de carga y un registro roto no tumba todas las páginas.

Registro mínimo en el init() de tu plugin (el ejemplo de referencia es la pestaña de zAnticipos):

$tabs = 'FacturaScripts\\Plugins\\Zolteka\\Lib\\ZoltekaDashboardTabs';
$tab = 'FacturaScripts\\Plugins\\Zolteka\\Lib\\ZoltekaDashboardTab';
if (Plugins::isEnabled('Zolteka') && class_exists($tabs) && method_exists($tabs, 'registrar')
    && class_exists($tab) && method_exists($tab, 'fromArray')) {
    try {
        $tabs::registrar($tab::fromArray([
            'id' => 'mi-plugin', 'titulo' => 'mi-plugin-pestana', 'icono' => 'fa-solid fa-coins',
            'posicion' => 40, 'plantilla' => '@PluginMiPlugin/DashBoardZoltekaTabMiPlugin.html.twig', 'lazy' => true,
            'datos' => static fn($ctx): array => MiPluginResumen::datos($ctx),
        ]));
    } catch (Throwable $e) {
        Tools::log('MiPlugin')->warning('No se pudo registrar la pestaña en Zolteka: ' . $e->getMessage());
    }
}

Cada callable ajeno se ejecuta dentro de un try/catch: si falla visible, la pestaña se oculta; si falla datos o avisos, devuelven []; si falla contador, null.

12.5.3. Clases comunes para el diseño de tu pestaña

(Desde la 2.16 y la 2.17.) Las pestañas de otros plugins usan las mismas clases que las de Zolteka, con var(--bs-*) y sin colores fijos:

  • Tarjeta: .zd-tarjeta y .zd-tarjeta--accion (pulsable entera, con un stretched-link y aria-label), con .zd-tarjeta__titulo, .zd-tarjeta__cifra y .zd-tarjeta__variacion. .zd-tarjeta__accion-icono lleva fa-chevron-right para ir a otra pantalla y fa-window-maximize para abrir un modal. .zd-vacio es el estado vacío en una línea.
  • Franja de indicadores: contenedor ul.zd-franja, con cada indicador en .zd-franja__item (con .zd-franja__titulo, .zd-franja__cifra y .zd-franja__detalle). .zd-franja__cifra--problema solo para problemas reales; .zd-franja__item--accion para un indicador pulsable. La variación lleva .zd-variacion--mejor o .zd-variacion--peor, siempre con flecha o signo.
  • Secciones y avisos: .zd-seccion con .zd-seccion__cabecera, .zd-seccion__titulo y .zd-seccion__enlace; filas de aviso ul.zd-avisos > li.zd-aviso.zd-aviso--{grave|atencion|info}.
  • Tamaños de letra: no se escriben en rem ni en px. Usa las variables --zd-fs-xxs, -xs, -sm, -md, -base, -lg, -cifra y -titulo.
  • Reparto por ancho (desde la 2.27): las rejillas de las pestañas se deciden con @container zd-panel y no con @media de la ventana. Una pestaña de otro plugin no debe poner borde propio a los indicadores.

Si tu pestaña muestra un calendario de consulta, mira 12.3.5. Calendario de consulta reutilizable.


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