🤖 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

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 por origen_tipo y origen_id en ZoltekaCalendarEvent, rellénalo y guárdalo. En deleteAfter(), bórralo.
  • Mostrar el calendario en tu pantalla: reutiliza las plantillas _calendar_timegrid o _calendar_base con allow_create y tu origen_tipo, y el modal _calendar_event_modal. No copies su HTML ni su JavaScript.
  • Guardar, mover y borrar: delega en CalendarEventAjax en lugar de repetir esa lógica.
  • Recordatorios por email: implementa CalendarNotificationProviderInterface y regístralo con CalendarNotificationRegistry::register().
  • Grupos de asistentes propios (opcional): CalendarParticipantGroupRegistry::register() con un CalendarParticipantGroupProviderInterface.

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_tipo y codigo, no por nombre: ZoltekaCalendarEventType::porCodigo($origen, $codigo) devuelve el tipo o null.
  • 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 devuelve null. Nunca borra ni renombra.
  • Los tipos creados a mano tienen codigo vací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() con getColumns() y, sin codigo, 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:

  1. 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 ejemplo ztaller-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 ejemplo EditZTallerOrden).
    • etiqueta(ZoltekaCalendarEvent $evento): string: título de la sección, ya traducido.
    • icono(): string: clases Font Awesome (por ejemplo fa-solid fa-screwdriver-wrench).
    • resumen(ZoltekaCalendarEvent $evento, User $user): ?array: los datos, o null si no existe o el usuario no puede verlo. Solo lee: nunca escribe.
  2. Regístrala en Init::init() con ZoltekaEventoResumenRegistry::register(new MiProveedorResumen()). Con una Zolteka anterior a la 2.22 no existen ni el registro ni la interfaz: protege la llamada con class_exists(ZoltekaEventoResumenRegistry::class) && interface_exists(ZoltekaEventoResumenProviderInterface::class). Una clave() que no cumple el patrón lanza InvalidArgumentException.
  3. Si quieres más control, resumen() puede devolver una plantilla Twig propia (@PluginX/....html.twig, sin ..) y unos datos que recibe como resumen.datos. Sin fsc, sin |raw y 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, devuelve null: «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:

  • color es el color propio (vacío si hereda) y color_heredado indica si la tarjeta hereda.
  • bg_color es el relleno ya resuelto, border_color el borde y text_color el texto que contrasta.
  • El modal, si color_heredado es verdadero, vuelve al punto «Color del calendario» y nunca copia bg_color como color propio.
  • El guardado convierte un color vacío en NULL y 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 color por 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:

  1. Estados en PHP con ZoltekaCalendarioEstado: clave (^[a-z][a-z0-9_]{0,29}$), etiqueta (ya traducida), color y descripcion. fromArray() lanza InvalidArgumentException si la clave o el color no valen. Colores admitidos: green, red, yellow, blue y gray.
  2. Endpoint GET en tu controlador: calcula el rango con ZoltekaCalendarioConsulta::rango(), reúne tus tarjetas por día y llama a ZoltekaCalendarioConsulta::renderizar(). Responde {ok, html, contadores, titulo, desde, hasta, vista, extra}; extra es libre.
  3. Parcial Twig Master/_calendario_consulta.html.twig en tu vista. No lleva <script>: zolteka-calendario-consulta.js arranca solo.
  4. Assets y modal del día en tu vista principal: zolteka-dashboard.css, zolteka-calendar-modal.js, zolteka-calendario-consulta.js y el modal Master/_calendar_event_modal.html.twig con include_event_form: false. No se registran en Init.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_modal y hoy.
  • Tarjeta: cada una es un array con title, subtitle, badge_text, badge_color, url, icon, estado (la clave de uno de tus estados) y datos (libre, para tu lista propia).
  • Lista propia: la vista Lista usa Master/_calendario_consulta_lista.html.twig; para otra, pasa plantilla_lista: '@PluginX/…' al llamar a renderizar().
  • JavaScript: window.ZoltekaCalendarioConsulta con iniciar(raiz), recargar(raiz) e iniciarTodos(contenedor), y los eventos zolteka-calendario-consulta:cargado y zolteka-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 en title, subtitle o datos llega 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 desde Dinamic\Lib: las clases son final.

💡 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.

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