1# DokuWiki Calendar Plugin - Matrix Edition 2 3A powerful, feature-rich calendar plugin with **Matrix theme**, integrated event management, **Outlook sync**, system monitoring, and advanced features. 4 5**Current Version**: 3.10.6 6 7--- 8 9## �� Key Features 10 11### �� Calendar Views 12- **Full Calendar** - Traditional month grid with event panel 13- **Sidebar Widget** - Compact week view with live system stats 14- **Event Panel** - Standalone event management 15- **Event List** - Flexible date range displays 16 17### �� Matrix Theme 18- **Green Glow Effects** - Authentic Matrix-style aesthetics 19- **Dual Color Bars** - Section color (4px) + Event color (3px) with 6px gap 20- **Live Clock** - Updates every second 21- **Weather Display** - Real-time temperature with geolocation 22- **System Monitoring** - CPU load, memory usage with tooltips 23 24### ⚡ Advanced Features 25- **Outlook Sync** - Bi-directional sync with Microsoft Outlook calendars 26- **Time Conflict Detection** - Automatic detection with warning badges (⚠) 27- **DokuWiki Formatting** - Full support for **bold**, [[links]], //italic//, etc. 28- **Event HTML Rendering** - Rich content in event titles and descriptions 29- **Click-to-View** - Click week grid days to see all events 30- **Quick Add** - Ultra-thin orange bar for instant event creation 31 32### �� Admin Interface 33- **Update Plugin Tab** (default) - Version info, changelog, cache management 34- **Outlook Sync Tab** - Configure Microsoft Azure integration 35- **Manage Events Tab** - Browse, edit, delete, move events 36 37--- 38 39## �� Installation 40 41### 1. Extract Plugin 42```bash 43# Extract to DokuWiki plugins directory 44cd /path/to/dokuwiki/lib/plugins/ 45unzip calendar-matrix-update-v3.10.6.zip 46``` 47 48### 2. Set Permissions 49```bash 50# Create data directories 51mkdir -p data/meta/calendar 52chmod -R 775 data/meta/calendar 53chown -R www-data:www-data data/meta/calendar 54``` 55 56### 3. Clear Cache 571. Go to **Admin → Calendar Management** 582. Update Plugin tab opens automatically 593. Click **��️ Clear Cache** button 604. Refresh your wiki page 61 62--- 63 64## �� Usage 65 66### Basic Calendar Syntax 67 68#### Full Calendar (Month View) 69``` 70{{calendar}} 71``` 72Displays current month with event panel on the right. 73 74#### Specific Month 75``` 76{{calendar year=2026 month=6}} 77``` 78 79#### With Namespace 80``` 81{{calendar namespace=team}} 82``` 83Separate calendars for different teams/projects. 84 85### Sidebar Widget 86 87#### Week View with System Stats 88``` 89{{calendar sidebar}} 90``` 91 92**Features**: 93- Current week grid (7 days) 94- Live clock (updates every second) 95- Real-time weather with temperature 96- System monitoring bars: 97 - **Green bar**: 5-min CPU load average 98 - **Purple bar**: Real-time CPU usage 99 - **Orange bar**: Memory usage 100- Hover tooltips with detailed stats 101- Click days to view all events 102- **+ ADD EVENT** bar for quick access 103- Today/Tomorrow/Important event sections 104 105#### With Namespace 106``` 107{{calendar sidebar namespace=team}} 108``` 109 110### Event Panel Only 111``` 112{{eventpanel}} 113``` 114320px wide panel - perfect for page sidebars. 115 116### Event List 117``` 118{{eventlist date=2026-01-22}} 119``` 120 121**Date Range**: 122``` 123{{eventlist daterange=2026-01-01:2026-01-31}} 124``` 125 126**With Namespace**: 127``` 128{{eventlist daterange=2026-01-01:2026-01-31 namespace=team}} 129``` 130 131--- 132 133## �� Creating Events 134 135### Method 1: Sidebar Widget 1361. Click the **+ ADD EVENT** bar (thin orange line below header) 1372. Opens Admin → Manage Events tab 1383. Fill in event details 1394. Click **Save** 140 141### Method 2: Calendar Grid 1421. Click **+ Add** button in event panel 1432. Fill in event details 1443. Click **Save** 145 146### Method 3: Day Popup 1471. Click any day in calendar grid 1482. Click **+ Add** in popup 1493. Fill in event details 1504. Click **Save** 151 152### Event Fields 153 154**Required**: 155- **Date** - YYYY-MM-DD format (can be changed to move events) 156- **Title** - Event name (supports **bold**, [[links]], //italic//) 157 158**Optional**: 159- **Time** - HH:MM format (24-hour) 160 - Leave blank for all-day events 161- **End Time** - HH:MM format (for duration) 162- **Color** - Choose from color picker or enter hex code 163- **Category** - For organization 164- **Description** - Full DokuWiki formatting supported 165 166### DokuWiki Formatting Support 167 168Events support full DokuWiki syntax: 169 170``` 171**Meeting with [[team:bob|Bob]]** 172 173Discuss: 174 * Project timeline 175 * //Budget review// 176 * [[projects:alpha|Project Alpha]] status 177``` 178 179Renders with proper HTML formatting including clickable links. 180 181--- 182 183## �� Viewing Events 184 185### Sidebar Widget 186 187**Week Grid**: 188- 7 days displayed (current week) 189- Event count badges on days with events 190- Click any day → View all events in expandable section 191- Events sorted: All-day first, then by time 192 193**Today Section** (Orange): 194- All events happening today 195- Sorted: All-day events first, then chronologically 196 197**Tomorrow Section** (Green): 198- All events happening tomorrow 199- Same sorting as Today 200 201**Important Events Section** (Purple): 202- Future events from "important" namespace 203- Configurable in Outlook Sync settings 204 205### Clicked Day Events 206 207When you click a day in the week grid: 208 209**Display**: 210``` 211Monday, Feb 5 212├─ [Blue][Green] All Day - Project Deadline 213├─ [Blue][Green] 8:00 AM - Morning Standup 214├─ [Blue][Orange] 10:30 AM - Coffee with Bob ⚠ 215└─ [Blue][Purple] 2:00 PM - Team Meeting 216``` 217 218**Color Bars**: 219- **First bar** (4px, blue) - Section color (selected day = blue) 220- **Second bar** (3px) - Event's assigned color 221- 6px gap between bars 222 223**Conflict Badge**: 224- **⚠** appears if event overlaps with another 225- Orange warning triangle on the right 226- Small (10px) and unobtrusive 227 228**Sorting Order**: 2291. All-day events (no time) appear **first** 2302. Timed events sorted chronologically (earliest → latest) 231 232--- 233 234## ⚙️ Admin Interface 235 236### Access 237Go to **Admin → Calendar Management** 238 239### Tabs 240 241#### 1. �� Update Plugin (Default Tab) 242 243**Features**: 244- Current version and date 245- Author information 246- Installation path 247- Permission check 248- **��️ Clear Cache** button (prominent orange button) 249- Recent changelog (last 10 versions) 250 251**Clear Cache**: 252- Click orange button 253- Confirm dialog 254- Clears all DokuWiki cache 255- **Use after every plugin update!** 256- Success message displays on same tab 257 258#### 2. ⚙️ Outlook Sync 259 260**Azure Configuration**: 261- Tenant ID 262- Client ID 263- Client Secret 264- User Email 265- Timezone 266 267**Sync Settings**: 268- Default category 269- Reminder minutes 270- Sync completed tasks (checkbox) 271- Delete Outlook events (checkbox) 272- Important namespaces (comma-separated) 273 274**Namespace Selection**: 275- Sync all namespaces (checkbox) 276- Or select specific namespaces 277 278**Category Mapping**: 279- Map DokuWiki colors to Outlook categories 280- Visual color picker 281- Custom mappings 282 283**Buttons**: 284- **�� Export Config** - Download encrypted config 285- **�� Import Config** - Upload encrypted config 286- **Save Configuration** 287 288#### 3. �� Manage Events 289 290**Features**: 291- Browse all events across all namespaces 292- Filter by namespace 293- Search events 294- Edit event details 295- Delete events 296- Move events between dates/namespaces 297- Bulk operations 298 299--- 300 301## �� Outlook Sync Setup 302 303### Prerequisites 3041. Microsoft Azure account 3052. Registered application in Azure Portal 3063. Calendar permissions granted 307 308### Configuration Steps 309 3101. **Register Azure App**: 311 - Go to https://portal.azure.com 312 - Navigate to App Registrations 313 - Create new registration 314 - Note: Tenant ID, Client ID 315 3162. **Create Client Secret**: 317 - In your app, go to Certificates & secrets 318 - Create new client secret 319 - Copy the secret value (shown once!) 320 3213. **Configure Permissions**: 322 - Add API permissions: 323 - Calendars.ReadWrite 324 - Calendars.ReadWrite.Shared 325 - Grant admin consent 326 3274. **Enter in DokuWiki**: 328 - Admin → Calendar Management → Outlook Sync 329 - Enter Tenant ID, Client ID, Client Secret 330 - Enter your email address 331 - Select timezone 332 - Configure sync settings 333 - Click **Save Configuration** 334 3355. **Test Sync**: 336 - Create event in DokuWiki 337 - Run sync (cron job or manual) 338 - Check Outlook calendar 339 - Create event in Outlook 340 - Run sync 341 - Check DokuWiki calendar 342 343### Sync Behavior 344 345**DokuWiki → Outlook**: 346- New events created in Outlook 347- Updates sync to existing events 348- Deletes sync if "Delete Outlook events" enabled 349 350**Outlook → DokuWiki**: 351- New events created in DokuWiki 352- Updates sync to existing events 353- Category colors mapped to DokuWiki colors 354 355**Conflict Resolution**: 356- Last-write-wins 357- Sync timestamp tracked 358 359--- 360 361## �� Color Scheme 362 363### Section Colors (Left Bar, 4px) 364 365- **Today**: Orange `#ff9800` 366- **Tomorrow**: Green `#4caf50` 367- **Important Events**: Purple `#9b59b6` 368- **Selected Day**: Blue `#3498db` 369 370### Event Colors (Right Bar, 3px) 371 372- **Default**: Matrix Green `#00cc07` 373- **Custom**: User-assigned color 374- **Gap**: 6px between section and event bars 375 376### System Bars 377 378- **Green**: 5-min CPU load average 379- **Purple**: Real-time CPU usage (5-sec average) 380- **Orange**: Real-time memory usage 381 382### UI Elements 383 384- **Add Event Bar**: Orange `#ff9800` (6px height) 385- **Conflict Badge**: Orange `#ff9800` (⚠ symbol) 386- **Clear Cache Button**: Orange `#ff9800` 387 388--- 389 390## �� System Monitoring 391 392### Sidebar Widget Stats 393 394**Green Bar Tooltip** (5-min CPU Load): 395``` 396CPU Load Average 3971-min: 2.45 3985-min: 2.12 39915-min: 1.98 400Uptime: 5 days, 3 hours 401``` 402 403**Purple Bar Tooltip** (Real-time CPU): 404``` 405CPU Load (Short-term) 406Current: 25.3% 407 408Top Processes: 4091. apache2 (8.2%) 4102. mysql (6.1%) 4113. php-fpm (4.5%) 412``` 413 414**Orange Bar Tooltip** (Memory): 415``` 416Memory Usage 417Total: 16.0 GB 418Used: 8.2 GB (51%) 419Available: 7.8 GB 420 421Top Processes: 4221. mysql (2.1 GB) 4232. apache2 (1.3 GB) 4243. php-fpm (845 MB) 425``` 426 427**Update Frequency**: 428- Stats: Every 2 seconds 429- Weather: Every 10 minutes 430- Clock: Every second 431 432--- 433 434## �� File Structure 435 436### Event Storage 437``` 438data/meta/calendar/2026-01.json 439data/meta/calendar/2026-02.json 440data/meta/[namespace]/calendar/2026-01.json 441data/meta/team/calendar/2026-03.json 442``` 443 444### Event JSON Format 445```json 446{ 447 "2026-02-06": [ 448 { 449 "id": "evt_abc123", 450 "title": "**Team Meeting** with [[team:bob|Bob]]", 451 "title_html": "<strong>Team Meeting</strong> with <a href=\"...\">Bob</a>", 452 "time": "14:00", 453 "end_time": "15:00", 454 "description": "Discuss //project timeline//", 455 "description_html": "Discuss <em>project timeline</em>", 456 "color": "#3498db", 457 "category": "Meetings", 458 "namespace": "team", 459 "created": "2026-02-05 10:00:00", 460 "modified": "2026-02-05 10:30:00", 461 "conflict": true 462 } 463 ] 464} 465``` 466 467### Fields Explained 468 469- **id**: Unique identifier (auto-generated) 470- **title**: Raw DokuWiki syntax 471- **title_html**: Pre-rendered HTML for JavaScript display 472- **time**: Start time (HH:MM, 24-hour) 473- **end_time**: End time (optional) 474- **description**: Raw DokuWiki syntax 475- **description_html**: Pre-rendered HTML 476- **color**: Hex color code 477- **category**: Category name 478- **namespace**: Calendar namespace 479- **created**: Timestamp (YYYY-MM-DD HH:MM:SS) 480- **modified**: Last modified timestamp 481- **conflict**: Boolean - time conflict detected 482 483--- 484 485## ��️ Troubleshooting 486 487### Events Not Displaying 488 489**Check 1**: Clear cache 490- Admin → Calendar Management 491- Click **��️ Clear Cache** 492- Confirm and refresh page 493 494**Check 2**: File permissions 495```bash 496ls -la data/meta/calendar/ 497# Should show www-data:www-data ownership 498# Should show 775 permissions 499 500# Fix if needed: 501chown -R www-data:www-data data/meta/calendar/ 502chmod -R 775 data/meta/calendar/ 503``` 504 505**Check 3**: Check JSON validity 506```bash 507cat data/meta/calendar/2026-02.json 508# Should be valid JSON 509# Check for syntax errors 510``` 511 512### Color Bars Not Showing 513 514**Symptom**: No colored bars in clicked day events 515 516**Solution**: 5171. Clear browser cache (Ctrl+Shift+R) 5182. Clear DokuWiki cache (admin button) 5193. Check browser console for errors 5204. Verify plugin version is 3.10.6+ 521 522### Tooltips Not Working 523 524**Symptom**: Hover over system bars shows no tooltip 525 526**Solution**: 5271. Verify JavaScript is enabled 5282. Clear cache 5293. Check console for "showTooltip_sidebar_* is not defined" 5304. Update to version 3.10.6+ 531 532### Weather Shows "--°" 533 534**Solution**: 5351. Clear cache 5362. Allow geolocation in browser (or uses Irvine, CA default) 5373. Wait 10 seconds for initial update 5384. Check console for weather API errors 539 540### Outlook Sync Not Working 541 542**Check 1**: Azure credentials 543- Verify Tenant ID, Client ID, Client Secret 544- Check app permissions in Azure Portal 545- Ensure admin consent granted 546 547**Check 2**: Sync logs 548- Check `/lib/plugins/calendar/sync.log` 549- Look for authentication errors 550- Verify API call responses 551 552**Check 3**: Cron job 553```bash 554# Check cron is running 555crontab -l 556 557# Should show: 558*/15 * * * * /usr/bin/php /path/to/dokuwiki/lib/plugins/calendar/sync_outlook.php 559``` 560 561### HTML Formatting Not Rendering 562 563**Symptom**: Event shows `**bold**` instead of **bold** 564 565**Solution**: 5661. Clear cache (critical!) 5672. Verify DokuWiki parser is working 5683. Check `title_html` and `description_html` fields exist in JSON 5694. Update to version 3.10.2+ 570 571--- 572 573## �� Performance 574 575### Optimizations 576 577- **Event Caching**: JSON files cached per month 578- **Lazy Loading**: Events loaded on demand 579- **AJAX Updates**: No full page reloads 580- **Minimal DOM**: Only visible events rendered 581 582### Recommended Limits 583 584- **Events per month**: < 500 (no performance issues) 585- **Events per day**: < 50 (UI remains clean) 586- **Namespaces**: Unlimited (loaded separately) 587- **Event description**: < 500 characters (for readability) 588 589--- 590 591## �� Security 592 593### Data Storage 594- Events stored server-side in JSON 595- No client-side storage used 596- File permissions protect data 597 598### Outlook Sync 599- Credentials encrypted in config file 600- OAuth 2.0 authentication 601- Secrets never logged or displayed 602 603### Admin Access 604- Requires DokuWiki admin permissions 605- All actions logged 606- CSRF protection on forms 607 608--- 609 610## �� Browser Support 611 612| Browser | Version | Status | 613|---------|---------|--------| 614| Chrome | 90+ | ✅ Full | 615| Firefox | 88+ | ✅ Full | 616| Safari | 14+ | ✅ Full | 617| Edge | 90+ | ✅ Full | 618| Mobile | Modern | ⚠️ Limited (sidebar may need scrolling) | 619 620**Required Features**: 621- Flexbox 622- Fetch API 623- ES6 JavaScript 624- CSS Grid 625 626--- 627 628## �� Support 629 630### Documentation 631- `CHANGELOG.md` - Version history 632- `OUTLOOK_SYNC_SETUP.md` - Detailed sync guide 633- `QUICK_REFERENCE.md` - Syntax quick reference 634 635### Getting Help 6361. Check this README first 6372. Review CHANGELOG for recent changes 6383. Clear cache after updates 6394. Check browser console for errors 6405. Verify file permissions 641 642--- 643 644## �� License 645 646GPL 2.0 647 648--- 649 650## ✨ Credits 651 652**Author**: atari911 653**Email**: atari911@gmail.com 654**Version**: 3.10.6 655**Date**: February 6, 2026 656 657**Special Features**: 658- Matrix theme design 659- Outlook synchronization 660- System monitoring integration 661- Real-time weather display 662- Advanced event conflict detection 663 664--- 665 666## �� Quick Start Examples 667 668### Personal Calendar 669``` 670====== My Schedule ====== 671 672{{calendar sidebar namespace=personal}} 673 674**Quick Add**: Click the orange "+ ADD EVENT" bar 675``` 676 677### Team Dashboard 678``` 679====== Development Team ====== 680 681{{calendar sidebar namespace=team:dev}} 682 683**System Stats**: Hover over colored bars for details 684**Today's Events**: Automatically displayed below calendar 685``` 686 687### Project Timeline 688``` 689====== Project Alpha ====== 690 691{{calendar namespace=projects:alpha year=2026 month=3}} 692 693**Milestones**: 694 * [[projects:alpha:kickoff|Mar 1 - Kickoff]] 695 * [[projects:alpha:design|Mar 15 - Design Review]] 696 * [[projects:alpha:launch|Mar 31 - Launch]] 697``` 698 699--- 700 701**�� Enjoy your Matrix-themed calendar with full Outlook integration!** 702