1====== Calendar Plugin - Installation & Upgrade Guide ====== 2 3===== Fresh Installation (New Plugin) ===== 4 5==== Step 1: Upload Plugin Files ==== 6 7 - **Extract** the ''calendar-compact.zip'' file 8 - **Upload** the entire ''calendar'' folder to: ''dokuwiki/lib/plugins/calendar/'' 9 10==== Step 2: Set Permissions ==== 11 12<code bash> 13# Make sure web server can write to data directory 14chmod 755 dokuwiki/lib/plugins/calendar 15chmod -R 755 dokuwiki/data/meta 16 17# Create calendar data directory 18mkdir -p dokuwiki/data/meta/calendar 19chmod 775 dokuwiki/data/meta/calendar 20chown -R www-data:www-data dokuwiki/data/meta/calendar 21</code> 22 23==== Step 3: Clear Cache ==== 24 25 - Go to DokuWiki Admin panel 26 - Click **"Clear Cache"** 27 - Or manually delete: ''dokuwiki/data/cache/'' 28 29==== Step 4: Use the Plugin ==== 30 31Add to any wiki page: 32 33<code> 34{{calendar}} 35</code> 36 37---- 38 39===== Upgrading from Previous Version ===== 40 41<WRAP center round important 60%> 42**⚠️ IMPORTANT: Backup First!** 43 44Before upgrading, backup your event data to prevent any data loss. 45</WRAP> 46 47==== Backup Your Event Data ==== 48 49<code bash> 50# Backup all calendar data 51cp -r dokuwiki/data/meta/calendar /backup/calendar-data-$(date +%Y%m%d) 52 53# Or create archive 54tar -czf calendar-backup-$(date +%Y%m%d).tar.gz dokuwiki/data/meta/calendar/ 55</code> 56 57==== Method 1: Overwrite (Recommended) ==== 58 59=== Step 1: Extract new version === 60 61<code bash> 62unzip calendar-compact.zip 63</code> 64 65=== Step 2: Remove old plugin files (KEEP DATA!) === 66 67<code bash> 68# Delete old plugin files only (NOT data!) 69rm -rf dokuwiki/lib/plugins/calendar/*.php 70rm -rf dokuwiki/lib/plugins/calendar/*.css 71rm -rf dokuwiki/lib/plugins/calendar/*.js 72rm -rf dokuwiki/lib/plugins/calendar/*.txt 73rm -rf dokuwiki/lib/plugins/calendar/*.md 74rm -rf dokuwiki/lib/plugins/calendar/*.html 75</code> 76 77=== Step 3: Upload new files === 78 79<code bash> 80# Upload entire new calendar folder 81cp -r calendar/* dokuwiki/lib/plugins/calendar/ 82</code> 83 84=== Step 4: Set permissions === 85 86<code bash> 87chmod 755 dokuwiki/lib/plugins/calendar 88chmod -R 644 dokuwiki/lib/plugins/calendar/* 89chmod 755 dokuwiki/lib/plugins/calendar 90</code> 91 92=== Step 5: Clear all caches === 93 94<code bash> 95# Clear DokuWiki cache 96rm -rf dokuwiki/data/cache/* 97 98# Clear browser cache 99# Press Ctrl+Shift+Delete in browser 100# Or hard refresh: Ctrl+F5 101</code> 102 103=== Step 6: Verify data is intact === 104 105<code bash> 106# Check your events are still there 107ls -la dokuwiki/data/meta/calendar/ 108cat dokuwiki/data/meta/calendar/2026-01.json 109</code> 110 111==== Method 2: Side-by-Side (Safer) ==== 112 113=== Step 1: Rename old plugin === 114 115<code bash> 116mv dokuwiki/lib/plugins/calendar dokuwiki/lib/plugins/calendar-old 117</code> 118 119=== Step 2: Install new version === 120 121<code bash> 122unzip calendar-compact.zip 123cp -r calendar dokuwiki/lib/plugins/ 124</code> 125 126=== Step 3: Copy data from old location (if needed) === 127 128<code bash> 129# If you had data in the old plugin 130cp -r dokuwiki/lib/plugins/calendar-old/data/* dokuwiki/data/meta/calendar/ 131</code> 132 133=== Step 4: Clear cache === 134 135<code bash> 136rm -rf dokuwiki/data/cache/* 137</code> 138 139=== Step 5: Test and remove old version === 140 141<code bash> 142# After confirming everything works: 143rm -rf dokuwiki/lib/plugins/calendar-old 144</code> 145 146---- 147 148===== Data Migration ===== 149 150Your event data is stored separately from the plugin in: 151 152<code> 153dokuwiki/data/meta/calendar/ 154</code> 155 156<WRAP center round tip 60%> 157**✅ The data WILL NOT be deleted** when you upgrade the plugin files. 158</WRAP> 159 160==== Data Location Check ==== 161 162<code bash> 163# Find all your event files 164find dokuwiki/data/meta -name "*.json" -path "*/calendar/*" 165 166# Example output: 167# dokuwiki/data/meta/calendar/2026-01.json 168# dokuwiki/data/meta/calendar/2026-02.json 169# dokuwiki/data/meta/team/calendar/2026-01.json 170</code> 171 172==== If Data is Missing After Upgrade ==== 173 174=== 1. Check backup === 175 176<code bash> 177ls -la /backup/calendar-data-*/ 178</code> 179 180=== 2. Restore from backup === 181 182<code bash> 183cp -r /backup/calendar-data-20260124/* dokuwiki/data/meta/calendar/ 184</code> 185 186=== 3. Fix permissions === 187 188<code bash> 189chmod -R 775 dokuwiki/data/meta/calendar 190chown -R www-data:www-data dokuwiki/data/meta/calendar 191</code> 192 193---- 194 195===== Verification Checklist ===== 196 197After installation/upgrade, verify: 198 199 * [ ] Plugin files exist in ''lib/plugins/calendar/'' 200 * [ ] Can see ''%%{{calendar}}%%'' on wiki page 201 * [ ] Calendar displays correctly 202 * [ ] Can click "+ Add" button 203 * [ ] Can add new events 204 * [ ] Can edit existing events 205 * [ ] Can delete events 206 * [ ] Old events still visible 207 * [ ] Checkboxes work for tasks 208 * [ ] Edit/delete buttons in top right 209 * [ ] Time bars show in calendar cells 210 * [ ] No JavaScript errors (F12 console) 211 212---- 213 214===== Troubleshooting Upgrade Issues ===== 215 216==== Problem: Calendar not showing ==== 217 218**Solution:** 219 220<code bash> 221# Clear all caches 222rm -rf dokuwiki/data/cache/* 223 224# Hard refresh browser 225# Ctrl+Shift+F5 (Windows/Linux) 226# Cmd+Shift+R (Mac) 227</code> 228 229==== Problem: Events disappeared ==== 230 231**Solution:** 232 233<code bash> 234# Check if data files exist 235ls -la dokuwiki/data/meta/calendar/ 236 237# If empty, restore from backup 238cp -r /backup/calendar-data-20260124/* dokuwiki/data/meta/calendar/ 239 240# Fix permissions 241chmod -R 775 dokuwiki/data/meta/calendar 242chown -R www-data:www-data dokuwiki/data/meta/calendar 243</code> 244 245==== Problem: Can't add/edit events ==== 246 247**Solution:** 248 249<code bash> 250# Check write permissions 251ls -la dokuwiki/data/meta/calendar/ 252 253# Should show: drwxrwxr-x (775) 254# If not, fix it: 255chmod -R 775 dokuwiki/data/meta/calendar 256chown -R www-data:www-data dokuwiki/data/meta/calendar 257</code> 258 259==== Problem: Old styling/features ==== 260 261**Solution:** 262 263<code bash> 264# Browser cache - clear it! 265# In browser: Ctrl+Shift+Delete 266 267# Also clear server cache 268rm -rf dokuwiki/data/cache/* 269 270# Force reload CSS/JS 271# Add ?v=2 to end of calendar page URL 272# Example: http://wiki.com/calendar?v=2 273</code> 274 275==== Problem: JavaScript errors ==== 276 277**Solution:** 278 279 - Open browser console (F12) 280 - Look for errors 281 - Common fix: 282 283<code bash> 284# Make sure script.js is uploaded 285ls -la dokuwiki/lib/plugins/calendar/script.js 286 287# Should be ~25KB 288# If missing or wrong size, re-upload 289</code> 290 291---- 292 293===== File List (Verify All Present) ===== 294 295After installation, you should have: 296 297<code> 298dokuwiki/lib/plugins/calendar/ 299├── action.php (AJAX handler) 300├── syntax.php (Main rendering) 301├── script.js (JavaScript functions) 302├── style.css (All styling) 303├── plugin.info.txt (Plugin metadata) 304├── README.md (Documentation) 305├── EXAMPLES_DOKUWIKI.txt (Usage examples) 306├── NEW_FEATURES.md (Feature list) 307├── TESTING_DATE_EDIT.md (Testing guide) 308├── UPGRADE_GUIDE.md (This guide) 309├── debug_html.php (Debug tool) 310└── test_date_field.html (Browser test) 311</code> 312 313**Verify files:** 314 315<code bash> 316cd dokuwiki/lib/plugins/calendar 317ls -lh *.php *.js *.css *.txt *.md *.html 318</code> 319 320---- 321 322===== What's New in Latest Version ===== 323 324==== New Features ==== 325 326 * ✅ **Super compact interface** - smaller fonts, tighter spacing 327 * ✅ **Task checkboxes on RIGHT** - positioned in top right corner 328 * ✅ **Edit/Delete buttons** - top right of each event 329 * ✅ **Colored time bars** - instead of dots on calendar 330 * ✅ **12-hour time format** - displays as "2:00 PM" 331 * ✅ **Multi-day events** - span across multiple days 332 * ✅ **Task management** - check off completed tasks 333 * ✅ **Namespace badges** - shows which namespace you're viewing 334 * ✅ **Draggable dialogs** - move popup windows 335 * ✅ **Mobile responsive** - works on phones/tablets 336 337==== Breaking Changes ==== 338 339<WRAP center round info 60%> 340**None!** Your existing events will work with the new version. 341</WRAP> 342 343==== Data Format ==== 344 345Still uses the same JSON format, but with optional new fields: 346 347 * ''isTask'' (boolean) 348 * ''completed'' (boolean) 349 * ''endDate'' (string) 350 351Old events without these fields will work fine. 352 353---- 354 355===== Backup Strategy ===== 356 357==== Before Every Upgrade ==== 358 359<code bash> 360#!/bin/bash 361# Quick backup script 362 363DATE=$(date +%Y%m%d-%H%M%S) 364BACKUP_DIR="/backup/dokuwiki-calendar" 365 366# Create backup directory 367mkdir -p $BACKUP_DIR 368 369# Backup event data 370cp -r dokuwiki/data/meta/calendar $BACKUP_DIR/data-$DATE 371 372# Backup plugin files 373cp -r dokuwiki/lib/plugins/calendar $BACKUP_DIR/plugin-$DATE 374 375echo "Backup saved to: $BACKUP_DIR" 376ls -lh $BACKUP_DIR 377</code> 378 379==== Automated Backups ==== 380 381<code bash> 382# Add to crontab for daily backups 3830 2 * * * /path/to/backup-script.sh 384</code> 385 386---- 387 388===== Rollback (If Needed) ===== 389 390If the new version has issues: 391 392<code bash> 393# 1. Remove new version 394rm -rf dokuwiki/lib/plugins/calendar 395 396# 2. Restore from backup 397cp -r /backup/dokuwiki-calendar/plugin-20260124 dokuwiki/lib/plugins/calendar 398 399# 3. Clear cache 400rm -rf dokuwiki/data/cache/* 401 402# 4. Reload page 403# Hard refresh: Ctrl+F5 404</code> 405 406---- 407 408===== Support & Debug ===== 409 410==== Debug Mode ==== 411 412 - Open ''debug_html.php'' in your browser:\\ ''%%http://yoursite.com/lib/plugins/calendar/debug_html.php%%'' 413 - Check browser console (F12) for errors 414 - Verify file permissions: 415 416<code bash> 417ls -la dokuwiki/lib/plugins/calendar/ 418ls -la dokuwiki/data/meta/calendar/ 419</code> 420 421==== Common Issues ==== 422 423^ Problem ^ Solution ^ 424| Events not saving | Check write permissions on ''data/meta/calendar/'' | 425| Calendar not showing | Clear browser cache (Ctrl+Shift+Delete) | 426| Old appearance | Clear server cache (''rm data/cache/*'') | 427| JavaScript errors | Check ''script.js'' uploaded correctly | 428| Buttons misaligned | Clear browser cache completely | 429 430---- 431 432===== Quick Upgrade Command ===== 433 434<WRAP center round important 60%> 435**For experienced users with SSH access:** 436</WRAP> 437 438<code bash> 439# One-line upgrade (be careful!) 440cd dokuwiki/lib/plugins && \ 441 tar -czf calendar-backup-$(date +%Y%m%d).tar.gz calendar && \ 442 rm -rf calendar/*.php calendar/*.js calendar/*.css && \ 443 unzip /path/to/calendar-compact.zip && \ 444 cp -r calendar/* calendar/ && \ 445 rm -rf dokuwiki/data/cache/* && \ 446 echo "Upgrade complete! Clear browser cache now." 447</code> 448 449<WRAP center round alert 60%> 450**Always backup first!** 451</WRAP> 452 453---- 454 455===== Post-Upgrade Testing ===== 456 457==== 1. View existing event ==== 458 459 - Open calendar page 460 - Check if old events display 461 462==== 2. Add new event ==== 463 464 - Click "+ Add" 465 - Fill form 466 - Save 467 468==== 3. Edit event ==== 469 470 - Click ✏️ on an event 471 - Modify details 472 - Save 473 474==== 4. Delete event ==== 475 476 - Click ��️ on an event 477 - Confirm deletion 478 479==== 5. Task checkbox ==== 480 481 - Create task (check "�� This is a task") 482 - Click checkbox to complete 483 - Verify strikethrough 484 485==== 6. Multi-day event ==== 486 487 - Create event with end date 488 - Verify shows date range 489 490<WRAP center round tip 60%> 491All working? ✅ **Upgrade successful!** 492</WRAP> 493 494---- 495 496===== Visual Guide ===== 497 498==== Event Item Layout ==== 499 500**After upgrade, your events should look like this:** 501 502<code> 503┌─────────────────────────────────────────┐ 504│ �� Team Meeting ☑ ✏️ ��️ │ ← Buttons in top right! 505│ Jan 22 • 2:00 PM │ 506│ Weekly standup meeting... │ 507└─────────────────────────────────────────┘ 508</code> 509 510==== Calendar Cell with Time Bars ==== 511 512<code> 513┌─────┐ 514│ 22 │ ← Day number 515│ │ │ ← Blue bar at 10am 516│ ││ │ ← Red bar at 2pm 517│││ │ ← Green bar (no time = bottom) 518└─────┘ 519</code> 520 521==== Full Calendar View ==== 522 523<code> 524┌────────────────┬─────────────────────────┐ 525│ January 2026 │ Events [team] [+ Add] │ 526├────────────────┼─────────────────────────┤ 527│ Su Mo Tu We │ �� Meeting ☑ ✏️ ��️ │ 528│ 1 2 3 │ Jan 22 • 2:00 PM │ 529│ 4 5 6 7 │ │ 530│ 8 9 10 11 │ �� Review ✏️ ��️ │ 531│ 12 13 14 15 │ Jan 25 • 4:00 PM │ 532│ 16 17 18 19 │ │ 533│ 20 21 22│23 │ ✅ Report ☑ ✏️ ��️ │ 534│ 24 25│26 27 │ Jan 28 (completed) │ 535└────────────────┴─────────────────────────┘ 536</code> 537 538---- 539 540===== Installation Video Guide ===== 541 542==== Step-by-Step Visual ==== 543 544 - **Download** ''calendar-compact.zip'' 545 - **Extract** to local folder 546 - **Connect** to server via FTP/SFTP 547 - **Navigate** to ''dokuwiki/lib/plugins/'' 548 - **Upload** entire ''calendar'' folder 549 - **Set permissions** (755 for folders, 644 for files) 550 - **Go to Admin** → Clear Cache 551 - **Test** by adding ''%%{{calendar}}%%'' to a page 552 - **Add event** to verify it works 553 554==== Common FTP Clients ==== 555 556 * FileZilla (Windows/Mac/Linux) 557 * WinSCP (Windows) 558 * Cyberduck (Mac) 559 * Command line: ''scp -r calendar user@server:/path/to/dokuwiki/lib/plugins/'' 560 561---- 562 563===== Need Help? ===== 564 565==== Before Asking for Help ==== 566 567 - [ ] Read this entire guide 568 - [ ] Checked troubleshooting section 569 - [ ] Cleared browser cache (Ctrl+Shift+Delete) 570 - [ ] Cleared server cache (''rm -rf data/cache/*'') 571 - [ ] Checked browser console for errors (F12) 572 - [ ] Verified file permissions 573 - [ ] Confirmed backup exists 574 575==== Information to Provide ==== 576 577When asking for help, include: 578 579 * DokuWiki version 580 * PHP version 581 * Browser and version 582 * Error messages (from browser console) 583 * What you were trying to do 584 * What actually happened 585 * Steps you've already tried 586 587==== Useful Debug Commands ==== 588 589<code bash> 590# Check PHP version 591php -v 592 593# Check file permissions 594ls -la dokuwiki/lib/plugins/calendar/ 595ls -la dokuwiki/data/meta/calendar/ 596 597# Check for errors in PHP logs 598tail -f /var/log/apache2/error.log 599# or 600tail -f /var/log/php-fpm/error.log 601 602# Test if files are accessible 603curl http://yoursite.com/lib/plugins/calendar/script.js 604</code> 605 606---- 607 608**Last Updated:** January 24, 2026\\ 609**Plugin Version:** 3.0 (Compact Edition)\\ 610**Compatible With:** DokuWiki 2020-07-29 "Hogfather" or newer 611