🤖 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
- 12.5.2. Pestañas propias del panel
- 12.5.3. Clases comunes para el diseño de tu pestaña
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) yDashBoardZolteka::addTreasuryReceiptPaymentExclude()(formas de pago). Compruébalos antes conclass_exists()ymethod_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.ZoltekaDashboardTabse crea con el constructor o conZoltekaDashboardTab::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..),lazyy los callablesvisible,datos,contadoryavisos. Un dato no válido lanzaInvalidArgumentException.- Los callables reciben un
ZoltekaDashboardContextocondesde,hasta,rango,vsAnterior,idempresa,codEmpresa,userypermissions. El periodo y la empresa de la cabecera valen para todas las pestañas. - La plantilla de la pestaña recibe solo
fsc,pestana,datosyctx, y se pinta también por AJAX con la accióntabdel controladorDashBoardZolteka. No puede llevar<script>: tu JavaScript escuchazolteka:panel-pendienteyzolteka:panel-inicializado, que suben hastadocument. - Las pestañas
lazyse 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 nivelinfo,atencionograve. El texto se sanea y se corta en 300 caracteres, yurlsolo 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 callableavisosderiva 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 conPlugins::isEnabled('Zolteka'),class_exists()ymethod_exists(), todo dentro detry/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-tarjetay.zd-tarjeta--accion(pulsable entera, con unstretched-linkyaria-label), con.zd-tarjeta__titulo,.zd-tarjeta__cifray.zd-tarjeta__variacion..zd-tarjeta__accion-iconollevafa-chevron-rightpara ir a otra pantalla yfa-window-maximizepara abrir un modal..zd-vacioes 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__cifray.zd-franja__detalle)..zd-franja__cifra--problemasolo para problemas reales;.zd-franja__item--accionpara un indicador pulsable. La variación lleva.zd-variacion--mejoro.zd-variacion--peor, siempre con flecha o signo. - Secciones y avisos:
.zd-seccioncon.zd-seccion__cabecera,.zd-seccion__tituloy.zd-seccion__enlace; filas de avisoul.zd-avisos>li.zd-aviso.zd-aviso--{grave|atencion|info}. - Tamaños de letra: no se escriben en
remni enpx. Usa las variables--zd-fs-xxs,-xs,-sm,-md,-base,-lg,-cifray-titulo. - Reparto por ancho (desde la 2.27): las rejillas de las pestañas se deciden con
@container zd-panely no con@mediade 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.