Skip to content

ICS Export Architecture

This document details the architectural design and implementation of the ICS Export feature in Full Calendar Remastered. The feature provides functionality to serialize the in-memory event cache into a standard .ics (iCalendar RFC 5545) document.

Architectural Workflow

The pipeline for selecting, serializing, and writing calendar cache entries as .ics is outlined below:

[IcsExportModal] ──► Query Event Cache (retrieves active events)
       │
       ▼
[Filter & Compile] ──► Filter by user-selected Calendars
       │
       ▼
[formatter.ts: eventsToIcs] ──► Map each event to VEVENT/VTODO
       │
       ├──► [Save to Vault] ──► Write to selected folder in vault (app.vault)
       │
       └──► [Direct Download] ──► Generate Blob & trigger browser download

Key Components

1. Multi-Event Formatter (src/providers/ics/formatter.ts)

We extend the existing iCal formatter (formatter.ts) by introducing and exporting eventsToIcs(events: OFCEvent[]): string:

  • Instantiates a single top-level ical.Component('vcalendar') envelope.
  • Loops through the compiled OFCEvent list.
  • Calls the internal createVEventComponent (for standard events) or createVTodoComponent (for tasks) to format each event.
  • Serializes the entire component tree into a single standard .ics string.

2. User Interface Modal (src/features/export/IcsExportModal.ts)

The IcsExportModal orchestrates the user interaction:

  • Calendar Registry Integration: Retrieves all active calendars using PluginState.getProviderRegistry().getAllSources().
  • Toggle Settings: Renders toggle items for each calendar so users can selectively export subsets of calendars.
  • Export Paths: Persists default export folder path configurations to the icsExportPath plugin settings.
  • Advanced Filtration Controls:
  • Export Period: Options for "Export All Events" (entire history) or "Specific Date Range" (with side-by-side date pickers).
  • Daily Time Range Filter: Restricts exported timed events to a daily time window (with side-by-side time pickers).
  • Include All-Day Events: Toggle to include or exclude all-day events/tasks.
  • Exclude Weekends: Toggle to filter out weekend occurrences.
  • Categories to Include: Checklist dynamically populated from unique categories present in the event store.
  • Include Types & Task Completion: Dropdowns to filter by events, tasks, and task completion status.
  • Save to Vault Pipeline: Resolves file paths, automatically creates target subfolders if they do not exist, checks for file existence, and writes to disk utilizing app.vault.
  • Direct Download Pipeline: Uses standard HTML5 Blob ObjectURLs (URL.createObjectURL) to trigger local browser download prompts, working seamlessly across desktop and mobile.

3. Settings Rendering (src/features/export/ui/renderExportSettings.ts)

Exposes settings for default export configuration:

  • Placed in the "Integrations" section of the main settings panel (SettingsTab.tsx).
  • Allows editing the default icsExportPath vault directory folder.

Data Model and iCalendar Mapping

The mapping from the plugin's canonical OFCEvent model to standard iCalendar structures is handled as follows:

OFCEvent Property iCalendar Component Property Type Details
title VEVENT/VTODO SUMMARY Cleaned title string
description VEVENT/VTODO DESCRIPTION Markdown/text
date/startTime/timezone VEVENT/VTODO DTSTART Formatted based on all-day and timezone settings
endDate/endTime/timezone VEVENT/VTODO DTEND / DUE Formatted based on all-day and timezone settings
completed (task) VTODO STATUS / COMPLETED Marks COMPLETED or NEEDS-ACTION
alarms VEVENT/VTODO VALARM Nested alarm triggers
rrule/recurring VEVENT/VTODO RRULE Recurrence rules
skipDates VEVENT/VTODO EXDATE Exception dates