🤖 12.3. Calendario y agenda
Cómo conectar tu plugin con la agenda y el calendario de Zolteka: eventos con su origen, recordatorios por email, grupos de asistentes, tipos de evento con código estable, resumen de vínculos de la cita, color heredado y calendario de consulta de solo lectura con estados de color.
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.3.1. Conectar tu plugin al calendario
- 12.3.2. Tipos de evento con código estable
- 12.3.3. Resumen de vínculos en el modal de evento
- 12.3.4. Color heredado del calendario
- 12.3.5. Calendario de consulta reutilizable
12.3.1. Conectar tu plugin al calendario
Cada evento de tu plugin se identifica con origen_tipo y origen_id (el id de tu registro). Los eventos creados a mano en la agenda usan general; tu plugin usa su propio nombre corto, por ejemplo miplugin.
- Crear o actualizar eventos desde tu modelo: en
saveAfter(), busca el evento pororigen_tipoyorigen_idenZoltekaCalendarEvent, rellénalo y guárdalo. EndeleteAfter(), bórralo. - Mostrar el calendario en tu pantalla: reutiliza las plantillas
_calendar_timegrido_calendar_baseconallow_createy tuorigen_tipo, y el modal_calendar_event_modal. No copies su HTML ni su JavaScript. - Guardar, mover y borrar: delega en
CalendarEventAjaxen lugar de repetir esa lógica. - Recordatorios por email: implementa
CalendarNotificationProviderInterfacey regístralo conCalendarNotificationRegistry::register(). - Grupos de asistentes propios (opcional):
CalendarParticipantGroupRegistry::register()con unCalendarParticipantGroupProviderInterface.
12.3.2. Tipos de evento con código estable
(Desde la 2.14.) Los tipos de evento (Administrador → Zolteka → Agenda → Tipos de Evento) llevan una columna codigo, única por origen_tipo, con la que tu plugin reencuentra los tipos que siembra aunque el usuario cambie su nombre o su traducción.
- Busca siempre por
origen_tipoycodigo, no por nombre:ZoltekaCalendarEventType::porCodigo($origen, $codigo)devuelve el tipo onull. - Para adoptar tipos que ya existían sin código,
ZoltekaCalendarEventType::asignarCodigo($origen, $codigo, $nombresPosibles)pone el código solo si hay exactamente una fila sin código con alguno de esos nombres. Con cero o varias no toca nada y devuelvenull. Nunca borra ni renombra. - Los tipos creados a mano tienen
codigovacío. Un código repetido dentro del mismo origen se rechaza con un aviso. - Con una Zolteka anterior a la 2.14 la columna no existe: comprueba
ZoltekaCalendarEventType::tableName()congetColumns()y, sincodigo, sigue con tu lógica anterior.
12.3.3. Resumen de vínculos en el modal de evento
(Desde la 2.22.) En la cabecera del modal de evento hay un botón de enlace con un contador. Al pulsarlo se abre un panel de solo lectura con lo que el evento tiene vinculado: Zolteka trae el del documento de venta y otros plugins añaden el suyo. Para añadir una sección, sigue estos pasos:
- Implementa
FacturaScripts\Plugins\Zolteka\Lib\ZoltekaEventoResumenProviderInterface:clave(): string: clave única con el prefijo de tu plugin, patrón^[a-z][a-z0-9_-]{0,39}$(por ejemploztaller-orden).orden(): int: posición en el panel; el menor va primero.aplica(ZoltekaCalendarEvent $evento): bool: si el evento tiene algo vinculado de tu plugin. Debe ser ligero.pagina(ZoltekaCalendarEvent $evento): string: página del núcleo cuyo acceso se exige para ver el resumen (por ejemploEditZTallerOrden).etiqueta(ZoltekaCalendarEvent $evento): string: título de la sección, ya traducido.icono(): string: clases Font Awesome (por ejemplofa-solid fa-screwdriver-wrench).resumen(ZoltekaCalendarEvent $evento, User $user): ?array: los datos, onullsi no existe o el usuario no puede verlo. Solo lee: nunca escribe.
- Regístrala en
Init::init()conZoltekaEventoResumenRegistry::register(new MiProveedorResumen()). Con una Zolteka anterior a la 2.22 no existen ni el registro ni la interfaz: protege la llamada conclass_exists(ZoltekaEventoResumenRegistry::class) && interface_exists(ZoltekaEventoResumenProviderInterface::class). Unaclave()que no cumple el patrón lanzaInvalidArgumentException. - Si quieres más control,
resumen()puede devolver unaplantillaTwig propia (@PluginX/....html.twig, sin..) y unosdatosque recibe comoresumen.datos. Sinfsc, sin|rawy con los valores ya formateados en PHP.
El array de resumen() lo sanea Zolteka: titulo es obligatorio (máximo 200 caracteres; sin título, la sección no sale), subtitulo es opcional (255), url es una ruta interna relativa Controlador?query para el botón «Abrir» y campos es una lista de pares etiqueta y valor (máximo 20).
namespace FacturaScripts\Plugins\zTaller\Lib;
use FacturaScripts\Core\Tools;
use FacturaScripts\Dinamic\Model\User;
use FacturaScripts\Dinamic\Model\ZoltekaCalendarEvent;
use FacturaScripts\Dinamic\Model\ZTallerOrden;
use FacturaScripts\Plugins\Zolteka\Lib\ZoltekaEventoResumenProviderInterface;
use FacturaScripts\Plugins\Zolteka\Lib\ZoltekaSecurity;
final class ZTallerEventoResumen implements ZoltekaEventoResumenProviderInterface
{
public function clave(): string { return 'ztaller-orden'; }
public function orden(): int { return 20; }
public function pagina(ZoltekaCalendarEvent $evento): string { return 'EditZTallerOrden'; }
public function etiqueta(ZoltekaCalendarEvent $evento): string { return Tools::trans('orden-de-trabajo'); }
public function icono(): string { return 'fa-solid fa-screwdriver-wrench'; }
public function aplica(ZoltekaCalendarEvent $evento): bool
{
return $evento->origen_tipo === 'ztaller' && !empty($evento->origen_id);
}
public function resumen(ZoltekaCalendarEvent $evento, User $user): ?array
{
$orden = new ZTallerOrden();
if (false === $orden->loadFromCode($evento->origen_id)) {
return null;
}
if (false === ZoltekaSecurity::canAccessEmpresa((int)$orden->idempresa)) {
return null;
}
// Aquí, además, la regla «solo sus datos» de tu plugin (KanbanPropiedad::esPropietario()).
return [
'titulo' => (string)$orden->codigo,
'subtitulo' => Tools::fixHtml((string)$orden->descripcion),
'url' => 'EditZTallerOrden?code=' . (int)$orden->id,
'campos' => [
['etiqueta' => Tools::trans('estado'), 'valor' => Tools::fixHtml((string)$orden->estado)],
],
];
}
}
💡 Tip Experto: este ejemplo es orientativo: cómo se localiza la orden de trabajo desde el evento es cosa de cada plugin. Aquí se supone que la orden guarda el id del evento. No está garantizado entre versiones.
Permisos en tres capas. Una sección solo se ve si pasa las tres:
- Zolteka exige poder ver el evento. Un evento «ocupado» no enseña nada.
- Zolteka exige que el usuario pueda acceder a la página que declara tu proveedor en
pagina(). Quien no puede abrir esa ficha no ve su resumen. - Tu proveedor aplica las reglas de datos dentro de
resumen(): «solo sus datos» (KanbanPropiedad::esPropietario()) y empresa (ZoltekaSecurity::canAccessEmpresa()). Si el dato no existe o no se puede ver, devuelvenull: «no existe» y «sin permiso» dan la misma respuesta.
El panel es de solo lectura. Sirve para informar, no para trabajar: nada de campos con name ni de botones que guarden, porque el panel está dentro del formulario del evento. Para acciones, usa el botón «Abrir» (url) o un botón propio con un data-* que tu JavaScript atienda al recibir el evento zolteka-calendar:resumen-cargado. window.ZoltekaCalendarResumen.recargar() vuelve a cargar el panel. Para apagarlo en un calendario, pasa show_resumen: false al incluir el modal. El HTML del panel se sanea al insertarlo: se quitan <script>, <style>, iframes, atributos on* y URL de otros dominios.
12.3.4. Color heredado del calendario
(Desde la 2.27.) Un evento sin color propio toma el color del calendario en el que se ve: el personal del usuario o, si no tiene, el del calendario. Si tu plugin pinta tarjetas de evento:
colores el color propio (vacío si hereda) ycolor_heredadoindica si la tarjeta hereda.bg_colores el relleno ya resuelto,border_colorel borde ytext_colorel texto que contrasta.- El modal, si
color_heredadoes verdadero, vuelve al punto «Color del calendario» y nunca copiabg_colorcomo color propio. - El guardado convierte un color vacío en
NULLy un valor no vacío e inválido cae a#4285f4. Los eventos anteriores a la 2.27 conservan su color guardado. - Las integraciones que fijan
colorpor código no cambian.
12.3.5. Calendario de consulta reutilizable
(Desde la 2.28.) Es un calendario de solo lectura con estados, para mostrar fechas de tu plugin (recibos, vacunas, vencimientos…) con la misma barra, vistas (1 día, 3 días, Semana, Mes y Lista), leyenda con contadores y «+N más» que Tesorería. No crea ni mueve eventos: para eso están las agendas con hora. Zolteka pone la interfaz; tu plugin pone sus estados, su endpoint y sus datos. Se monta en cuatro pasos:
- Estados en PHP con
ZoltekaCalendarioEstado:clave(^[a-z][a-z0-9_]{0,29}$),etiqueta(ya traducida),colorydescripcion.fromArray()lanzaInvalidArgumentExceptionsi la clave o el color no valen. Colores admitidos:green,red,yellow,blueygray. - Endpoint GET en tu controlador: calcula el rango con
ZoltekaCalendarioConsulta::rango(), reúne tus tarjetas por día y llama aZoltekaCalendarioConsulta::renderizar(). Responde{ok, html, contadores, titulo, desde, hasta, vista, extra};extraes libre. - Parcial Twig
Master/_calendario_consulta.html.twigen tu vista. No lleva<script>:zolteka-calendario-consulta.jsarranca solo. - Assets y modal del día en tu vista principal:
zolteka-dashboard.css,zolteka-calendar-modal.js,zolteka-calendario-consulta.jsy el modalMaster/_calendar_event_modal.html.twigconinclude_event_form: false. No se registran enInit.php: cada página carga los suyos.
Ejemplo del endpoint:
use FacturaScripts\Core\Template\Controller;
use FacturaScripts\Core\Tools;
use FacturaScripts\Plugins\Zolteka\Lib\ZoltekaCalendarioConsulta;
use FacturaScripts\Plugins\Zolteka\Lib\ZoltekaCalendarioEstado;
use FacturaScripts\Plugins\Zolteka\Lib\ZoltekaSecurity;
use Throwable;
class MiControlador extends Controller
{
public function run(): void
{
parent::run(); // login y permiso de acceso a esta página
if ((string)$this->request()->query('action', '') === 'citas') {
$this->ajaxCitas();
return;
}
$this->view('MiControlador.html.twig');
}
/** @return list<ZoltekaCalendarioEstado> */
public static function estados(): array
{
return [
new ZoltekaCalendarioEstado('pendiente', Tools::trans('pending'), 'yellow', Tools::trans('mi-plugin-pendiente-desc')),
new ZoltekaCalendarioEstado('hecho', Tools::trans('done'), 'green', Tools::trans('mi-plugin-hecho-desc')),
];
}
private function ajaxCitas(): void
{
try {
$fecha = ZoltekaSecurity::sanitizeIsoDate((string)$this->request()->query('fecha', '')) ?? date('Y-m-d');
$vista = ZoltekaCalendarioConsulta::vistaValida((string)$this->request()->query('vista', ''));
$rango = ZoltekaCalendarioConsulta::rango($fecha, $vista);
// 'Y-m-d' => [tarjeta, ...]. Consulta con Where::between() sobre $rango['desde'] y $rango['hasta'],
// aplicando empresa y «solo sus datos».
$tarjetasPorDia = [];
$resultado = ZoltekaCalendarioConsulta::renderizar([
'vista' => $vista,
'desde' => $rango['desde'],
'hasta' => $rango['hasta'],
'tarjetas_por_dia' => $tarjetasPorDia,
'estados' => self::estados(),
'estado' => (string)$this->request()->query('estado', ''),
]);
} catch (Throwable $e) {
Tools::log()->warning('mi-plugin-error-calendario', ['%error%' => mb_substr($e->getMessage(), 0, 200)]);
$this->response()->setHttpCode(500)->json([
'ok' => false,
'error' => Tools::trans('zolteka-cc-error-carga'),
]);
return;
}
$this->response()->json(['ok' => true] + $resultado + ['extra' => []]);
}
}
Y en la vista Twig:
{% include 'Master/_calendario_consulta.html.twig' with {
id: 'mis_citas', url: 'MiControlador', accion: 'citas',
vistas: ['week', 'month', 'lista'], estados: fsc.estados(), pestana_nueva: true,
textos: { day_modal_title: trans('mi-plugin-citas') },
hoy: 'now'|date('Y-m-d')
} only %}
- Parámetros del parcial:
id(obligatorio y único en la página,^[a-z][a-z0-9_-]{0,39}$),url,accion,vistas(1day,3days,week,month,lista),vista_inicial,estados,pestana_nueva,filtros_view,textos(ya traducidos),icono_modalyhoy. - Tarjeta: cada una es un array con
title,subtitle,badge_text,badge_color,url,icon,estado(la clave de uno de tus estados) ydatos(libre, para tu lista propia). - Lista propia: la vista Lista usa
Master/_calendario_consulta_lista.html.twig; para otra, pasaplantilla_lista: '@PluginX/…'al llamar arenderizar(). - JavaScript:
window.ZoltekaCalendarioConsultaconiniciar(raiz),recargar(raiz)einiciarTodos(contenedor), y los eventoszolteka-calendario-consulta:cargadoyzolteka-calendario-consulta:error. - Seguridad: el componente solo pinta lo que recibe. La empresa (
ZoltekaSecurity::resolveCodEmpresa()), el permiso de la página y «solo sus datos» los aplica el endpoint de tu plugin. Lo que pongas entitle,subtitleodatosllega al navegador. - Compatibilidad: con una Zolteka anterior a la 2.28 la clase no existe. Comprueba
class_exists(ZoltekaCalendarioConsulta::class)y, si falta, responde{ok: false, error}con un texto traducido y no pintes el parcial. - Importación: importa desde
FacturaScripts\Plugins\Zolteka\Lib, no desdeDinamic\Lib: las clases sonfinal.
💡 Tip Experto: el ejemplo del endpoint es orientativo y no está garantizado entre versiones.
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.