1# DokuWiki Calendar Plugin 2 3A feature-rich calendar plugin for DokuWiki with multiple themes, namespace management, Outlook/Google sync, recurring events, DokuWiki farm compatibility, and ACL-enforced security. 4 5## Features 6 7### Calendar Views 8- **Interactive Calendar** — Full-featured calendar with drag-friendly event management 9- **Static Calendar** — Read-only presentation mode for public display, with print support 10- **Event Panel** — Standalone scrollable event list with month navigation 11- **Sidebar Widget** — Compact week-at-a-glance itinerary for the sidebar 12 13### Event Management 14- Create, edit, and delete events with an inline dialog 15- Recurring events (daily, weekly, monthly, yearly) with interval control 16- Multi-day events with date ranges 17- Time conflict detection with visual badges 18- Task mode with completion tracking 19- Important event highlighting with ⭐ 20- Namespace-based organization (e.g., `work`, `personal`, `team:projects`) 21 22### Namespace Filtering 23- **Wildcard** — `namespace=*` loads events from all namespaces 24- **Multi-namespace** — `namespace="work;personal"` loads from specific namespaces 25- **Prefixed wildcard** — `namespace=team:*` loads all sub-namespaces under `team` 26- **Exclude** — `exclude=journal` hides specific namespaces from wildcard views 27- **Multiple excludes** — `exclude="journal;drafts"` hides multiple namespaces (semicolon-separated) 28- Exclude matches by prefix: `exclude=journal` also hides `journal:daily`, `journal:notes:2026`, etc. 29 30### Themes 31- **Matrix** — Green on dark (default) 32- **Purple** — Purple/violet on dark 33- **Professional** — Blue on white 34- **Pink** — Hot pink with particle effects ✨ 35- **Wiki** — Neutral gray (matches DokuWiki template) 36 37### Search 38- Real-time event filtering as you type 39- Configurable default search scope (current month or all dates) via admin setting 40- Toggle between month and all-dates search with the ��/�� button 41 42### Sync & Integration 43- **Outlook/Office 365** — Delta sync via Microsoft Graph API (cron-based) 44- **Google Calendar** — Two-way sync via OAuth 2.0 45- Full event backup/restore with versioned ZIP archives 46 47### Security 48- DokuWiki ACL enforcement on all read and write operations 49- CSRF token validation on all write actions 50- Rate limiting (60 req/min read, 30 req/min write) 51- Namespace path traversal prevention 52- Audit logging for admin operations 53 54### DokuWiki Farm Compatible 55- All data stored via `$conf['metadir']` and `$conf['cachedir']` (per-animal in farm setups) 56- Sync credentials can be stored per-animal in `data/meta/calendar/sync_config.php` 57- Falls back to shared plugin directory for non-farm installations 58- See [Farm Setup](#dokuwiki-farm-setup) for migration details 59 60### Localization 61- English (en) 62- German (de) 63- Czech (cs) 64 65## Installation 66 671. Download the latest release ZIP 682. Extract to `lib/plugins/calendar/` (the folder must be named `calendar`) 693. Clear DokuWiki's cache: **Admin → Configuration Settings → Save** 704. Access **Admin → Calendar Management** to configure themes and settings 71 72## Syntax 73 74### Interactive Calendar 75``` 76{{calendar}} 77{{calendar namespace=work}} 78{{calendar namespace="personal;work"}} 79{{calendar namespace=projects:*}} 80{{calendar namespace=* exclude=journal}} 81{{calendar namespace=* exclude="journal;drafts"}} 82``` 83 84### Static Calendar (Read-only) 85``` 86{{calendar static}} 87{{calendar namespace=meetings static}} 88{{calendar month=6 year=2026 static}} 89{{calendar title="Club Events" theme=professional static}} 90{{calendar static noprint}} 91``` 92 93### Event Panel 94``` 95{{eventpanel}} 96{{eventpanel namespace=work height=500px}} 97{{eventpanel namespace=* exclude=archive}} 98``` 99 100### Event List 101``` 102{{eventlist}} 103{{eventlist range=week}} 104{{eventlist range=month namespace=meetings}} 105{{eventlist namespace=* exclude="personal;drafts"}} 106{{eventlist range=>3m}} 107{{eventlist range=>100d}} 108{{eventlist range=>2w namespace=work}} 109{{eventlist range=>1y}} 110``` 111 112### Sidebar Widget 113``` 114{{eventlist sidebar}} 115{{eventlist sidebar namespace=important}} 116``` 117 118### Parameter Reference 119 120| Parameter | Description | Example | 121|-----------|-------------|---------| 122| `namespace=X` | Filter by namespace | `namespace=work` | 123| `namespace=*` | Show all namespaces | `namespace=*` | 124| `namespace="X;Y"` | Multiple namespaces | `namespace="work;personal"` | 125| `exclude=X` | Exclude namespace(s) from wildcard | `exclude=journal` | 126| `exclude="X;Y"` | Exclude multiple namespaces | `exclude="journal;drafts"` | 127| `static` | Read-only calendar mode | `{{calendar static}}` | 128| `month=X` | Lock to month (1-12) | `month=6` | 129| `year=X` | Lock to year | `year=2026` | 130| `title="X"` | Custom title | `title="Team Events"` | 131| `theme=X` | Override theme | `theme=professional` | 132| `height=X` | Panel height (eventpanel only) | `height=500px` | 133| `range=X` | Date range (eventlist only) | `range=week`, `range=>3m` | 134| `noprint` | Hide print button (static only) | `noprint` | 135| `noheader` | Hide header (eventlist only) | `noheader` | 136| `sidebar` | Sidebar widget mode | `{{eventlist sidebar}}` | 137 138## Extended Date Ranges 139 140The `range` parameter supports extended formats for showing events over longer periods: 141 142| Format | Description | Example | 143|--------|-------------|---------| 144| `range=>Nd` | Next N days | `range=>100d` | 145| `range=>Nw` | Next N weeks | `range=>2w` | 146| `range=>Nm` | Next N months | `range=>3m` | 147| `range=>Ny` | Next N years | `range=>1y` | 148 149All extended ranges include a 30-day lookback for past-due tasks. Headers are automatically localized (EN/DE/CS). 150 151``` 152{{eventlist range=>3m}} → Next 3 Months 153{{eventlist range=>100d namespace=work}} → Next 100 Days (work only) 154{{eventlist range=>2w}} → Next 2 Weeks 155{{eventlist range=>1y namespace=*}} → Next 1 Year (all namespaces) 156``` 157 158## Multi-Day Event Bars 159 160Events spanning multiple days display as continuous colored bars across the calendar grid. Bars maintain consistent vertical positions across all days they span — if two multi-day events overlap, each keeps its own row, just like Google Calendar. 161 162The alignment uses a stable slot assignment algorithm that runs in both PHP (initial page load) and JS (AJAX month navigation), ensuring bars line up correctly at all times. 163 164## Admin Features 165 166Access via **Admin → Calendar Management**: 167 168- **Manage Events** — Browse, search, filter, move, and bulk-delete events across namespaces 169- **Recurring Events** — Manage series with extend, trim, pause/resume, and pattern editing 170- **Namespace Management** — Create, rename, and delete namespaces 171- **Outlook Sync** — Configure Microsoft Graph API credentials and run/schedule syncs 172- **Google Sync** — OAuth 2.0 setup for Google Calendar integration 173- **Themes** — Select visual theme, configure week start day, itinerary default state, and default search scope 174- **Backup/Restore** — Create, download, and restore versioned backups 175- **Update** — Upload new plugin versions with automatic backup 176 177## DokuWiki Farm Setup 178 179This plugin is fully compatible with DokuWiki farm (multi-wiki) installations. 180 181### How It Works 182- Event data is stored in each animal's `$conf['metadir']/calendar/` directory 183- Plugin settings (theme, week start, etc.) are per-animal in `$conf['metadir']/calendar_*.txt` 184- Cache and rate-limit data use `$conf['cachedir']` (per-animal) 185- The plugin code itself is shared across the farm (standard DokuWiki behavior) 186 187### Sync Credentials 188Sync credentials (`sync_config.php`) can be stored per-animal: 189- **Per-animal (recommended):** `{animal}/data/meta/calendar/sync_config.php` 190- **Shared (fallback):** `lib/plugins/calendar/sync_config.php` 191 192The plugin checks the per-animal path first and falls back to the shared location. 193 194### Migration from Non-Farm 195If you're moving from a single-wiki install to a farm, move calendar data to each animal: 196```bash 197# Move calendar events 198mv /path/to/master/data/meta/calendar/ /path/to/animal/data/meta/calendar/ 199 200# Move settings 201mv /path/to/master/data/meta/calendar_*.txt /path/to/animal/data/meta/ 202``` 203 204## Event Description Formatting 205 206Descriptions support DokuWiki-style formatting: 207 208- `**bold**` or `__bold__` → **bold** 209- `//italic//` → *italic* 210- `[[page|text]]` → DokuWiki links 211- `[text](url)` → Markdown links 212- Line breaks preserved 213 214## Architecture 215 216| Component | Purpose | 217|-----------|---------| 218| `syntax.php` | Wiki syntax parsing and HTML rendering | 219| `action.php` | AJAX endpoint handling with ACL enforcement | 220| `admin.php` | Admin panel UI and management operations | 221| `calendar-main.js` | Client-side calendar logic and UI | 222| `classes/FileHandler.php` | Atomic file operations with locking | 223| `classes/EventCache.php` | Caching layer with TTL | 224| `classes/RateLimiter.php` | AJAX rate limiting | 225| `classes/EventManager.php` | Event CRUD operations | 226| `classes/AuditLogger.php` | Admin audit trail | 227| `classes/GoogleCalendarSync.php` | Google Calendar OAuth integration | 228| `sync_outlook.php` | CLI Outlook sync script (cron) | 229 230## Requirements 231 232- DokuWiki (Hogfather or later, including Librarian) 233- PHP 7.4+ 234- Modern browser (Chrome, Firefox, Edge, Safari) 235 236## License 237 238GPL-2.0 239 240## Author 241 242atari911 (atari911@gmail.com) 243 244## Links 245 246- [DokuWiki Plugin Page](https://www.dokuwiki.org/plugin:calendar) 247- [GitHub Repository](https://github.com/atari911/dokuwiki-plugin-calendar) 248- [Issue Tracker](https://github.com/atari911/dokuwiki-plugin-calendar/issues) 249 250## Version 251 2527.6.0 253