====== Calendar Plugin - Debug Instructions ======

===== Debugging Recurring Event Issues =====

If recurring events are not appearing when navigating between months, the JSON event files may be corrupted or malformed. Follow these steps to diagnose the issue.

==== Method 1: Using the Debug Script (Recommended) ====

  - SSH into your server
  - Navigate to the calendar plugin directory:

<code bash>
cd /path/to/dokuwiki/lib/plugins/calendar/
</code>

  - Run the debug script for the month you want to inspect:

<code bash>
# Check March 2027
php debug_events.php "" 2027-03

# Check January 2026  
php debug_events.php "" 2026-01

# Check with namespace
php debug_events.php "team" 2027-03
</code>

The script will show you:
  * ✓ If the file exists
  * ✓ Raw file contents
  * ✓ JSON validation errors
  * ✓ All events in the file
  * ⚠️ Any problems (invalid UTF-8, unexpected fields, corrupted data)

==== Method 2: Manual File Inspection ====

Navigate to your DokuWiki data directory:

<code bash>
cd /path/to/dokuwiki/data/meta/calendar/
ls -la
</code>

You should see JSON files like:
  * ''2026-01.json'' (January 2026)
  * ''2026-03.json'' (March 2026)
  * ''2027-03.json'' (March 2027)
  * etc.

View the contents of a specific month:

<code bash>
cat 2027-03.json
</code>

Or use a text editor:

<code bash>
nano 2027-03.json
# or
vi 2027-03.json
</code>

==== What Good JSON Looks Like ====

A properly formatted event file should look like this:

<code json>
{
    "2027-03-15": [
        {
            "id": "abc123-1",
            "title": "Yearly Event",
            "time": "",
            "description": "",
            "color": "#3498db",
            "isTask": false,
            "completed": false,
            "endDate": "",
            "recurring": true,
            "recurringId": "abc123",
            "created": "2026-01-24 10:30:00"
        }
    ],
    "2027-03-20": [
        {
            "id": "xyz789",
            "title": "Another Event",
            "time": "14:00",
            "description": "Meeting notes",
            "color": "#008800",
            "isTask": false,
            "completed": false,
            "endDate": "",
            "recurring": false,
            "created": "2027-03-15 09:00:00"
        }
    ]
}
</code>

==== Common Problems to Look For ====

=== 1. Truncated/Corrupted File ===

<code json>
{
    "2027-03-15": [
        {
            "id": "abc123-1",
            "title": "Yearly
</code>

**Problem:** File is incomplete, missing closing braces.

**Fix:** Delete the corrupted file and recreate the event.

=== 2. Invalid Characters ===

<code json>
{"2027-03-15":[{"title":"Test\x00Event"}]}
</code>

**Problem:** Null bytes or invalid UTF-8 characters.

**Fix:** Edit the file and remove invalid characters, or delete and recreate.

=== 3. Empty or Malformed ===

<code json>
{}[]
</code>

**Problem:** Invalid JSON structure.

**Fix:** Delete the file or replace with ''{}''

=== 4. Multiple Root Objects ===

<code json>
{"2027-03-15":[...]}
{"2027-03-16":[...]}
</code>

**Problem:** Two separate JSON objects instead of one merged object.

**Fix:** Manually merge into a single object or delete and recreate events.

==== Browser Console Debugging ====

  - Open your browser's Developer Tools (''F12'')
  - Go to the **Console** tab
  - Navigate between months in the calendar
  - Look for messages like:

<code>
Month navigation data: {success: true, events: {...}, year: 2027, month: 3}
Rebuilding calendar for 2027 3 with 1 date entries
</code>

**Key things to check:**
  * ''success: true'' - API call worked
  * ''events: {...}'' - Should contain event data
  * ''"with X date entries"'' - Should be > 0 if events exist

**If you see "with 0 date entries":**
  * The JSON file is empty, missing, or corrupted
  * Check the actual file with the debug script

==== Fixing Corrupted Files ====

=== Option 1: Delete and Recreate ===

<code bash>
# Back up first!
cp /path/to/dokuwiki/data/meta/calendar/2027-03.json /tmp/backup-2027-03.json

# Delete corrupted file
rm /path/to/dokuwiki/data/meta/calendar/2027-03.json

# Recreate the recurring event in the calendar UI
</code>

=== Option 2: Manual Fix ===

<code bash>
# Edit the file
nano /path/to/dokuwiki/data/meta/calendar/2027-03.json

# Ensure it's valid JSON - use a validator like:
# https://jsonlint.com/

# Save and test
</code>

=== Option 3: Reset Empty File ===

If the file exists but is corrupted, reset it to empty:

<code bash>
echo '{}' > /path/to/dokuwiki/data/meta/calendar/2027-03.json
</code>

Then recreate events through the UI.

==== Checking DokuWiki Error Logs ====

The updated plugin now logs JSON errors to DokuWiki's error log:

<code bash>
# Check for JSON decode errors
tail -f /path/to/dokuwiki/data/cache/error.log | grep Calendar

# Or view recent errors
tail -100 /path/to/dokuwiki/data/cache/error.log | grep Calendar
</code>

Look for messages like:
  * ''Calendar: JSON decode error in /path/to/2027-03.json: Syntax error''
  * ''Calendar: JSON decode error in /path/to/2027-03.json: Unexpected end of file''

==== Full Diagnostic Checklist ====

Run through this checklist:

<HTML>
<table>
<tr><th>Step</th><th>Command</th><th>Expected Result</th></tr>
<tr>
  <td>1. Check file exists</td>
  <td><code>ls -la /path/to/dokuwiki/data/meta/calendar/2027-03.json</code></td>
  <td>File should exist with size > 0</td>
</tr>
<tr>
  <td>2. View file contents</td>
  <td><code>cat /path/to/dokuwiki/data/meta/calendar/2027-03.json</code></td>
  <td>Valid JSON structure</td>
</tr>
<tr>
  <td>3. Validate JSON</td>
  <td><code>php debug_events.php "" 2027-03</code></td>
  <td>"✓ Valid JSON"</td>
</tr>
<tr>
  <td>4. Check event count</td>
  <td>Output from debug script</td>
  <td>Shows recurring events</td>
</tr>
<tr>
  <td>5. Check error logs</td>
  <td><code>tail /path/to/dokuwiki/data/cache/error.log</code></td>
  <td>No Calendar errors</td>
</tr>
<tr>
  <td>6. Browser console</td>
  <td>F12 → Console tab</td>
  <td>"Rebuilding calendar... with X date entries"</td>
</tr>
</table>
</HTML>

==== Common File Locations ====

Depending on your DokuWiki installation:

  * **Default:** ''/var/www/html/dokuwiki/data/meta/calendar/''
  * **Debian/Ubuntu:** ''/usr/share/dokuwiki/data/meta/calendar/''
  * **Custom:** Check your DokuWiki ''conf/local.php'' for ''savedir''

To find your data directory:

<code bash>
# From DokuWiki root
php -r "include 'inc/init.php'; echo DOKU_INC . 'data/meta/calendar/';"
</code>

==== Still Having Issues? ====

If you've checked everything and events still don't appear:

  - Share the output of: ''php debug_events.php "" 2027-03''
  - Share the browser console output when navigating to the month
  - Share the contents of the JSON file: ''cat 2027-03.json''
  - Check file permissions: ''ls -la /path/to/dokuwiki/data/meta/calendar/''

The web server needs read/write access to the calendar directory:

<code bash>
# Fix permissions (adjust www-data to your web server user)
chown -R www-data:www-data /path/to/dokuwiki/data/meta/calendar/
chmod -R 755 /path/to/dokuwiki/data/meta/calendar/
</code>

===== Quick Reference =====

<code bash>
# View March 2027 events
php /path/to/dokuwiki/lib/plugins/calendar/debug_events.php "" 2027-03

# View all calendar files
ls -la /path/to/dokuwiki/data/meta/calendar/

# Check for errors
tail -f /path/to/dokuwiki/data/cache/error.log | grep Calendar

# Validate JSON online
cat 2027-03.json | curl -X POST -H "Content-Type: application/json" -d @- https://jsonlint.com/
</code>

----

**Version:** 3.2\\
**Last Updated:** January 24, 2026