1# Installation & Upgrade Guide 2 3## �� Fresh Installation (New Plugin) 4 5If you're installing the calendar plugin for the first time: 6 7### Step 1: Upload Plugin Files 81. **Extract** the `calendar-compact.zip` file 92. **Upload** the entire `calendar` folder to: 10 ``` 11 dokuwiki/lib/plugins/calendar/ 12 ``` 13 14### Step 2: Set Permissions 15```bash 16# Make sure web server can write to data directory 17chmod 755 dokuwiki/lib/plugins/calendar 18chmod -R 755 dokuwiki/data/meta 19 20# Create calendar data directory 21mkdir -p dokuwiki/data/meta/calendar 22chmod 775 dokuwiki/data/meta/calendar 23chown -R www-data:www-data dokuwiki/data/meta/calendar 24``` 25 26### Step 3: Clear Cache 271. Go to DokuWiki Admin panel 282. Click **"Clear Cache"** 293. Or manually delete: `dokuwiki/data/cache/` 30 31### Step 4: Use the Plugin 32Add to any wiki page: 33```wiki 34{{calendar}} 35``` 36 37--- 38 39## �� Upgrading from Previous Version 40 41If you already have an older version installed: 42 43### ⚠️ IMPORTANT: Backup First! 44 45**Before upgrading, backup your event data:** 46 47```bash 48# Backup all calendar data 49cp -r dokuwiki/data/meta/calendar /backup/calendar-data-$(date +%Y%m%d) 50 51# Or create archive 52tar -czf calendar-backup-$(date +%Y%m%d).tar.gz dokuwiki/data/meta/calendar/ 53``` 54 55### Method 1: Overwrite (Recommended) 56 57**Step 1:** Extract new version 58```bash 59unzip calendar-compact.zip 60``` 61 62**Step 2:** Remove old plugin files (KEEP DATA!) 63```bash 64# Delete old plugin files only (NOT data!) 65rm -rf dokuwiki/lib/plugins/calendar/*.php 66rm -rf dokuwiki/lib/plugins/calendar/*.css 67rm -rf dokuwiki/lib/plugins/calendar/*.js 68rm -rf dokuwiki/lib/plugins/calendar/*.txt 69rm -rf dokuwiki/lib/plugins/calendar/*.md 70rm -rf dokuwiki/lib/plugins/calendar/*.html 71``` 72 73**Step 3:** Upload new files 74```bash 75# Upload entire new calendar folder 76cp -r calendar/* dokuwiki/lib/plugins/calendar/ 77``` 78 79**Step 4:** Set permissions 80```bash 81chmod 755 dokuwiki/lib/plugins/calendar 82chmod -R 644 dokuwiki/lib/plugins/calendar/* 83chmod 755 dokuwiki/lib/plugins/calendar 84``` 85 86**Step 5:** Clear all caches 87```bash 88# Clear DokuWiki cache 89rm -rf dokuwiki/data/cache/* 90 91# Clear browser cache 92# Press Ctrl+Shift+Delete in browser 93# Or hard refresh: Ctrl+F5 94``` 95 96**Step 6:** Verify data is intact 97```bash 98# Check your events are still there 99ls -la dokuwiki/data/meta/calendar/ 100cat dokuwiki/data/meta/calendar/2026-01.json 101``` 102 103### Method 2: Side-by-Side (Safer) 104 105**Step 1:** Rename old plugin 106```bash 107mv dokuwiki/lib/plugins/calendar dokuwiki/lib/plugins/calendar-old 108``` 109 110**Step 2:** Install new version 111```bash 112unzip calendar-compact.zip 113cp -r calendar dokuwiki/lib/plugins/ 114``` 115 116**Step 3:** Copy data from old location (if needed) 117```bash 118# If you had data in the old plugin 119cp -r dokuwiki/lib/plugins/calendar-old/data/* dokuwiki/data/meta/calendar/ 120``` 121 122**Step 4:** Clear cache 123```bash 124rm -rf dokuwiki/data/cache/* 125``` 126 127**Step 5:** Test and remove old version 128```bash 129# After confirming everything works: 130rm -rf dokuwiki/lib/plugins/calendar-old 131``` 132 133--- 134 135## ��️ Data Migration 136 137Your event data is stored separately from the plugin in: 138``` 139dokuwiki/data/meta/calendar/ 140``` 141 142**The data WILL NOT be deleted** when you upgrade the plugin files. 143 144### Data Location Check: 145```bash 146# Find all your event files 147find dokuwiki/data/meta -name "*.json" -path "*/calendar/*" 148 149# Example output: 150# dokuwiki/data/meta/calendar/2026-01.json 151# dokuwiki/data/meta/calendar/2026-02.json 152# dokuwiki/data/meta/team/calendar/2026-01.json 153``` 154 155### If Data is Missing After Upgrade: 156 1571. **Check backup** 158 ```bash 159 ls -la /backup/calendar-data-*/ 160 ``` 161 1622. **Restore from backup** 163 ```bash 164 cp -r /backup/calendar-data-20260124/* dokuwiki/data/meta/calendar/ 165 ``` 166 1673. **Fix permissions** 168 ```bash 169 chmod -R 775 dokuwiki/data/meta/calendar 170 chown -R www-data:www-data dokuwiki/data/meta/calendar 171 ``` 172 173--- 174 175## ✅ Verification Checklist 176 177After installation/upgrade, verify: 178 179- [ ] Plugin files exist in `lib/plugins/calendar/` 180- [ ] Can see `{{calendar}}` on wiki page 181- [ ] Calendar displays correctly 182- [ ] Can click "+ Add" button 183- [ ] Can add new events 184- [ ] Can edit existing events 185- [ ] Can delete events 186- [ ] Old events still visible 187- [ ] Checkboxes work for tasks 188- [ ] Edit/delete buttons in top right 189- [ ] Time bars show in calendar cells 190- [ ] No JavaScript errors (F12 console) 191 192--- 193 194## �� Troubleshooting Upgrade Issues 195 196### Problem: Calendar not showing 197 198**Solution:** 199```bash 200# Clear all caches 201rm -rf dokuwiki/data/cache/* 202 203# Hard refresh browser 204# Ctrl+Shift+F5 (Windows/Linux) 205# Cmd+Shift+R (Mac) 206``` 207 208### Problem: Events disappeared 209 210**Solution:** 211```bash 212# Check if data files exist 213ls -la dokuwiki/data/meta/calendar/ 214 215# If empty, restore from backup 216cp -r /backup/calendar-data-20260124/* dokuwiki/data/meta/calendar/ 217 218# Fix permissions 219chmod -R 775 dokuwiki/data/meta/calendar 220chown -R www-data:www-data dokuwiki/data/meta/calendar 221``` 222 223### Problem: Can't add/edit events 224 225**Solution:** 226```bash 227# Check write permissions 228ls -la dokuwiki/data/meta/calendar/ 229 230# Should show: drwxrwxr-x (775) 231# If not, fix it: 232chmod -R 775 dokuwiki/data/meta/calendar 233chown -R www-data:www-data dokuwiki/data/meta/calendar 234``` 235 236### Problem: Old styling/features 237 238**Solution:** 239```bash 240# Browser cache - clear it! 241# In browser: Ctrl+Shift+Delete 242 243# Also clear server cache 244rm -rf dokuwiki/data/cache/* 245 246# Force reload CSS/JS 247# Add ?v=2 to end of calendar page URL 248# Example: http://wiki.com/calendar?v=2 249``` 250 251### Problem: JavaScript errors 252 253**Solution:** 2541. Open browser console (F12) 2552. Look for errors 2563. Common fix: 257 ```bash 258 # Make sure script.js is uploaded 259 ls -la dokuwiki/lib/plugins/calendar/script.js 260 261 # Should be ~25KB 262 # If missing or wrong size, re-upload 263 ``` 264 265--- 266 267## �� File List (Verify All Present) 268 269After installation, you should have: 270 271``` 272dokuwiki/lib/plugins/calendar/ 273├── action.php (AJAX handler) 274├── syntax.php (Main rendering) 275├── script.js (JavaScript functions) 276├── style.css (All styling) 277├── plugin.info.txt (Plugin metadata) 278├── README.md (Documentation) 279├── EXAMPLES_DOKUWIKI.txt (Usage examples) 280├── NEW_FEATURES.md (Feature list) 281├── TESTING_DATE_EDIT.md (Testing guide) 282├── debug_html.php (Debug tool) 283└── test_date_field.html (Browser test) 284``` 285 286**Verify files:** 287```bash 288cd dokuwiki/lib/plugins/calendar 289ls -lh *.php *.js *.css *.txt *.md *.html 290``` 291 292--- 293 294## �� What's New in Latest Version 295 296### New Features: 297- ✅ **Super compact interface** - smaller fonts, tighter spacing 298- ✅ **Task checkboxes on RIGHT** - positioned in top right corner 299- ✅ **Edit/Delete buttons** - top right of each event 300- ✅ **Colored time bars** - instead of dots on calendar 301- ✅ **12-hour time format** - displays as "2:00 PM" 302- ✅ **Multi-day events** - span across multiple days 303- ✅ **Task management** - check off completed tasks 304- ✅ **Namespace badges** - shows which namespace you're viewing 305- ✅ **Draggable dialogs** - move popup windows 306- ✅ **Mobile responsive** - works on phones/tablets 307 308### Breaking Changes: 309**None!** Your existing events will work with the new version. 310 311### Data Format: 312Still uses the same JSON format, but with optional new fields: 313- `isTask` (boolean) 314- `completed` (boolean) 315- `endDate` (string) 316 317Old events without these fields will work fine. 318 319--- 320 321## �� Backup Strategy 322 323### Before Every Upgrade: 324 325```bash 326#!/bin/bash 327# Quick backup script 328 329DATE=$(date +%Y%m%d-%H%M%S) 330BACKUP_DIR="/backup/dokuwiki-calendar" 331 332# Create backup directory 333mkdir -p $BACKUP_DIR 334 335# Backup event data 336cp -r dokuwiki/data/meta/calendar $BACKUP_DIR/data-$DATE 337 338# Backup plugin files 339cp -r dokuwiki/lib/plugins/calendar $BACKUP_DIR/plugin-$DATE 340 341echo "Backup saved to: $BACKUP_DIR" 342ls -lh $BACKUP_DIR 343``` 344 345### Automated Backups: 346 347```bash 348# Add to crontab for daily backups 3490 2 * * * /path/to/backup-script.sh 350``` 351 352--- 353 354## �� Rollback (If Needed) 355 356If the new version has issues: 357 358```bash 359# 1. Remove new version 360rm -rf dokuwiki/lib/plugins/calendar 361 362# 2. Restore from backup 363cp -r /backup/dokuwiki-calendar/plugin-20260124 dokuwiki/lib/plugins/calendar 364 365# 3. Clear cache 366rm -rf dokuwiki/data/cache/* 367 368# 4. Reload page 369# Hard refresh: Ctrl+F5 370``` 371 372--- 373 374## �� Support 375 376### Debug Mode: 377 3781. Open `debug_html.php` in your browser: 379 ``` 380 http://yoursite.com/lib/plugins/calendar/debug_html.php 381 ``` 382 3832. Check browser console (F12) for errors 384 3853. Verify file permissions: 386 ```bash 387 ls -la dokuwiki/lib/plugins/calendar/ 388 ls -la dokuwiki/data/meta/calendar/ 389 ``` 390 391### Common Issues: 392 393| Problem | Solution | 394|---------|----------| 395| Events not saving | Check write permissions on data/meta/calendar/ | 396| Calendar not showing | Clear browser cache (Ctrl+Shift+Delete) | 397| Old appearance | Clear server cache (rm data/cache/*) | 398| JavaScript errors | Check script.js uploaded correctly | 399| Buttons misaligned | Clear browser cache completely | 400 401--- 402 403## ✨ Quick Upgrade Command 404 405**For experienced users with SSH access:** 406 407```bash 408# One-line upgrade (be careful!) 409cd dokuwiki/lib/plugins && \ 410 tar -czf calendar-backup-$(date +%Y%m%d).tar.gz calendar && \ 411 rm -rf calendar/*.php calendar/*.js calendar/*.css && \ 412 unzip /path/to/calendar-compact.zip && \ 413 cp -r calendar/* calendar/ && \ 414 rm -rf dokuwiki/data/cache/* && \ 415 echo "Upgrade complete! Clear browser cache now." 416``` 417 418**Always backup first!** 419 420--- 421 422## �� Post-Upgrade Testing 423 4241. **View existing event** 425 - Open calendar page 426 - Check if old events display 427 4282. **Add new event** 429 - Click "+ Add" 430 - Fill form 431 - Save 432 4333. **Edit event** 434 - Click ✏️ on an event 435 - Modify details 436 - Save 437 4384. **Delete event** 439 - Click ��️ on an event 440 - Confirm deletion 441 4425. **Task checkbox** 443 - Create task (check "�� This is a task") 444 - Click checkbox to complete 445 - Verify strikethrough 446 4476. **Multi-day event** 448 - Create event with end date 449 - Verify shows date range 450 451All working? ✅ Upgrade successful! 452