calendar-plugin/requirements/settings.md

Plugin Settings Requirements

Purpose

Define implemented setup/settings and diagnostics behavior for the calendar plugin admin pages.

Scope

This document covers:

• Admin menu structure for plugin management pages
• Setup page controls and persisted settings
• Diagnostics page and diagnostics download behavior

Admin Navigation

The plugin must provide a single WordPress admin menu entry with these pages:

• Top-level menu: Calendar Plugin
• Sub-pages: Setup, Users, Diagnostics
• Access capability: manage_options

The top-level duplicate submenu entry should be removed so only the explicit pages appear in navigation.

Setup Page

The Setup page must support:

• Saving plugin settings
• Seeding default events
• Deleting all event and recurrence-exception data

Setup form controls:

• CalDAV/ICS Calendar Name (caldav_calendar_name)
• URL Slug Prefix (url_slug)
• Verification Page Path (verification_page_path)
• Plugin Table Prefix (table_prefix)
• ICS Access Mode (ics_access_mode: public_read or authenticated_read)
• Diagnostics Enabled (diagnostics_enabled)
• Uninstall Cleanup (uninstall_cleanup_mode: keep or remove)

Behavior requirements:

• Save, seed, and delete-all actions provide success/failure messaging on the Setup page.
• Setup POST actions are nonce-protected.
• table_prefix updates rename plugin tables (events, exceptions, users, tokens, audit log) without dropping existing data.
• Prefix changes must fail safely if target tables already exist.
• url_slug affects canonical routed paths for ICS and CalDAV endpoints.

Settings Persistence

• Settings are persisted through plugin options storage and returned by the admin settings API (/wp-json/calendar/v1/settings).
• Runtime endpoints and UI links must reflect the latest saved settings.

Diagnostics Page

The Diagnostics page must be admin-only and show:

• Whether diagnostics are enabled
• Runtime metadata snapshot (generation time, endpoint paths, user context, table stem)
• Recent audit log rows when diagnostics are enabled

Diagnostics download behavior:

• Download action is available only when diagnostics_enabled=1
• Download uses a nonce-protected admin-post action
• Response is JSON attachment (calendar-diagnostics-*.json)

Security and Access

• Setup, Users, and Diagnostics pages require manage_options.
• Form actions must validate WordPress nonces.
• Inputs must be sanitized/normalized before persistence.