Aller au contenu

sources

Les sources où le calendrier va chercher ses événements, quand la période montrée change.

Typereadonly EventSourceSpec[]
Par défautnon défini
Modifiable en direct (update())Oui
Déclaré danspackages/core/src/kernel.ts

Chaque source est une spécification faite par une fonction :

  • jsonSource(id, { url }) (@dzcalendar/core) : un GET avec start, end et timeZone dans la requête (un POST : dans son corps de formulaire) ; la réponse est la liste des événements, ou map la transforme en liste. Par défaut, un mois par requête.
  • fnSource(id, fetch) : votre fonction, qui reçoit { window, signal } — la tranche à récupérer (window.startDate, window.endDate, exclue) et un signal d’annulation — et rend les événements, ou une promesse.
  • icalSource(id, { url }) (@dzcalendar/ical) : un flux iCalendar.
  • sseSource(id, url, { map }) et liveSource(id, { connect }) (@dzcalendar/core/live) : un flux qui prévient au lieu d’être interrogé — Server-Sent Events, ou tout autre transport (un WebSocket…). map transforme chaque message en { create }, { update, patch } (champs posés par-dessus, extendedProps fusionnés), { remove } ou { reset } ; le navigateur reconnecte un flux coupé avec Last-Event-ID, et un flux que le serveur a fermé pour de bon est rouvert (reopenAfterMs, le dernier identifiant en ?lastEventId=). La connexion s’ouvre quand la source est ajoutée et se ferme quand elle est retirée ou le calendrier détruit.
import { sseSource } from '@dzcalendar/core/live';
const runs = sseSource('runs', '/api/runs/stream', {
map: (msg) => {
const m = msg as { kind: 'start' | 'end'; id: string; process: string; at: string; failed?: boolean };
return m.kind === 'start'
? { create: { id: m.id, title: 'Import', start: m.at, resourceId: m.process, ongoing: true } }
: { update: m.id, patch: { ongoing: false, end: m.at, tone: m.failed ? 'red' : 'green' } };
},
});

Une source récupère les morceaux de temps qu’on lui demande (chunk : un mois à la fois par défaut, prefetch de plus de chaque côté), les garde, et récupère de nouveau un morceau périmé (staleAfter) quand il est montré de nouveau. Le start et le end que reçoit un serveur sont des jours entiers autour du morceau, plus larges que l’écran. Une récupération échouée est retentée si retry le demande, puis signalée par onSource ; ce qui était montré reste. Avec save, les modifications de ses événements (celles d’une personne, d’une commande, d’une annulation) sont réécrites : montrées tout de suite, remises si la promesse est rejetée — ou, quand les événements ont changé entre-temps, récupérées de nouveau. (icalSource prend url, text, headers, defaults, staleAfter, retry et save.)

update({ sources }) prend la liste entière : les sources disparues sont retirées, les nouvelles ajoutées, les autres gardées — comparées par identité, donc gardez les mêmes objets (un nouvel objet est une nouvelle source, récupérée de nouveau). calendar.refetch(id) en récupère une à nouveau. L’identifiant 'events' est celui de l’option events : une source qui le porte est refusée (duplicate-id).

import { jsonSource, fnSource } from '@dzcalendar/core';
import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
sources: [
// GET /api/rendez-vous?start=…&end=…&timeZone=Europe%2FParis
jsonSource('appointments', { url: '/api/rendez-vous' }),
fnSource('holidays', async ({ window }) => {
const res = await fetch(`/api/holidays?from=${window!.startDate}&to=${window!.endDate}`);
return res.json();
}),
],
});
// Later: fetch the appointments again.
calendar.refetch('appointments');

Dans les frameworks, c’est une entrée : sources en Angular, en React et en Vue — gardez les spécifications hors du rendu (une constante de module, useMemo), sinon chaque rendu est une nouvelle source.