sources
Sources the calendar fetches its events from, as the period shown changes.
| Type | readonly EventSourceSpec[] |
|---|---|
| Default | not set |
Live update (update()) | Yes |
| Declared in | packages/core/src/kernel.ts |
What it does
Section titled “What it does”Each source is a spec made by a helper:
jsonSource(id, { url })(@dzcalendar/core): aGETwithstart,endandtimeZonein the query (aPOST: in its form body); the answer is the list of events, ormapturns it into one. By default one month a request.fnSource(id, fetch): your function, given{ window, signal }— the stretch to fetch (window.startDate,window.endDate, exclusive) and an abort signal — returning the events, or a promise of them.icalSource(id, { url })(@dzcalendar/ical): an iCalendar feed.sseSource(id, url, { map })andliveSource(id, { connect })(@dzcalendar/core/live): a feed that tells rather than being asked — Server-Sent Events, or any transport (a WebSocket…).mapturns each message into{ create },{ update, patch }(fields laid over,extendedPropsmerged),{ remove }or{ reset }; the browser reconnects a dropped stream withLast-Event-ID, and a stream the server closed for good is opened again (reopenAfterMs, the last id as?lastEventId=). The connection opens when the source is added and closes when it is removed or the calendar destroyed.
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' } }; },});A source fetches the pieces of time it is asked for (chunk: a month at a
time by default, prefetch more on each side), keeps them, and fetches again
one gone stale (staleAfter) when it is shown again. The start and end a
server receives are whole days around the piece, wider than the screen. A
failed fetch is retried when retry asks, then told through onSource; what
was shown stays. With save, the changes to its events (a person’s, a
command’s, an undo) are written back: shown at once, put back if the promise
rejects — or, when the events changed again meanwhile, fetched again.
(icalSource takes url, text, headers, defaults, staleAfter,
retry and save.)
update({ sources }) takes the whole list: sources gone are removed, new
ones added, the others kept — compared by identity, so keep the same spec
objects (a new object is a new source, fetched again). calendar.refetch(id)
fetches one again. The id 'events' is the events option’s: a source with
it is refused (duplicate-id).
Example
Section titled “Example”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');import { Component } from '@angular/core';import { jsonSource } from '@dzcalendar/core';import { DZ_CALENDAR } from '@dzcalendar/angular';
@Component({ selector: 'app-agenda', imports: [DZ_CALENDAR], template: `<dz-calendar timeZone="Europe/Paris" [sources]="sources" />`,})export class Agenda { // The same spec objects for the component's life: a new one would be fetched again. readonly sources = [jsonSource('appointments', { url: '/api/rendez-vous' })];}import { jsonSource } from '@dzcalendar/core';import { DzCalendar } from '@dzcalendar/react';
// Outside the component: one spec, not a new one at each render.const SOURCES = [jsonSource('appointments', { url: '/api/rendez-vous' })];
export function Agenda() { return <DzCalendar timeZone="Europe/Paris" sources={SOURCES} />;}<script setup lang="ts">import { jsonSource } from '@dzcalendar/core';import { DzCalendar } from '@dzcalendar/vue';
const sources = [jsonSource('appointments', { url: '/api/rendez-vous' })];</script>
<template> <DzCalendar time-zone="Europe/Paris" :sources="sources" /></template>In the frameworks it is an input: Angular’s sources, React’s sources, Vue’s sources — keep the specs outside the render (a module constant, useMemo), or each render is a new source.
See also
Section titled “See also”events— an array, the simplest source.onSource— loading, errors, problems, saves.- Event sources.