=== CalDav Calendar Viewer ===
Contributors: kaymanmk
Tags: ical, calendar, ics, events, shortcode
Requires at least: 5.6
Tested up to: 6.9
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Displays events from iCal (.ics) feeds in a responsive list. Supports recurring events, multiple feeds with Basic Auth and encrypted credentials.

== Description ==

CalDav Calendar Viewer fetches and displays events from any standard iCal (.ics) feed directly on your site using a simple shortcode. It supports multiple calendar feeds, each with its own URL and optional username/password for authenticated endpoints.

**Key Features:**

* **Multiple Calendar Feeds** – Configure as many feeds as you need, each with a unique ID.
* **iCal / RFC 5545 Support** – Parses standard `.ics` calendar feeds including all-day events, times, locations, and descriptions.
* **Recurring Events** – Expands RRULE recurrences (DAILY, WEEKLY, MONTHLY, YEARLY) including BYDAY, BYMONTHDAY, INTERVAL, COUNT, UNTIL, and EXDATE.
* **DURATION Support** – Derives the end time from a `DURATION` property when `DTEND` is absent.
* **Basic Authentication** – Supply a username and password per feed for protected calendars.
* **Encrypted Credentials** – Passwords are stored using AES-256-CBC encryption in the database.
* **Caching** – Configurable cache lifetime reduces external HTTP requests (defaults to 1 hour).
* **Cache Management** – View the number of currently cached feed entries and clear them with one click from the admin settings page.
* **Async Loading** – Calendar events are fetched via AJAX so the containing page renders immediately.
* **Label / Category Filtering** – Filter events by iCal `CATEGORIES` labels using the `label` shortcode attribute.
  Accepts a comma-separated list; **all** plain labels must be present on an event for it to be shown.
  Prefix a label with `!` to exclude events that carry that category. Matching is case-insensitive.
* **Clickable Events** – Events that carry a `URL` property in the iCal feed are rendered as clickable links.
* **7-Day Rolling Window** – Automatically fetches and displays only the next 7 days of events.
* **Responsive Event List** – Clean event list layout that adapts to all screen sizes.
* **Event Tooltips** – Hover over an event to see its description.
* **Description Prefix Filtering** – Remove lines from event descriptions that start with configurable prefixes. Useful for hiding internal metadata added by calendar applications.

== Installation ==

1. Upload the `caldav-calendar-viewer` folder to the `/wp-content/plugins/` directory, or install it directly through the WordPress plugin screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **Settings → CalDav Calendar Viewer** to add your calendar feeds.
4. Add the `[caldcavi_calendar id="your-feed-id"]` shortcode to any page or post.

== Configuration ==

Navigate to **Settings → CalDav Calendar Viewer** in the WordPress admin panel.

= Adding a Feed =

Click **+ Add Feed** and fill in:

* **Feed ID** – A unique lowercase identifier (letters, numbers, hyphens, underscores) used in the shortcode.
* **iCal Feed URL** – The full URL to the `.ics` calendar feed.
* **Username** – Username for Basic Authentication. Leave blank for public feeds.
* **Password** – Password for Basic Authentication. Stored encrypted. Leave blank to keep the current value.

You can configure multiple feeds — each gets its own ID.

= General Settings =

* **Cache Lifetime (seconds)** – How long fetched calendar data is cached. Set to `0` to disable caching. Default: `3600` (1 hour).
* **Description Line Prefixes to Remove** – Newline-separated list of prefixes. Any line in an event's description that starts with one of these prefixes is removed from the tooltip. Useful for hiding internal metadata added by calendar apps (e.g. `X-APPLE-`, `Reminder:`).

= Cache Management =

The settings page shows how many calendar feeds are currently cached. Use the **Clear Cache** button to delete all cached responses and force fresh fetches on the next page load.

== Usage ==

= Basic Shortcode =

`[caldcavi_calendar id="my-feed"]`

= Shortcode Attributes =

* `id` (required) – The feed ID configured in **Settings → CalDav Calendar Viewer**.
* `label` (optional) – A comma-separated list of iCal `CATEGORIES` values to filter events by. **All** plain labels
  must be present on an event for it to be shown. Prefix a label with `!` to exclude events that carry that category.
  Matching is case-insensitive. Omit to show all events.

= Examples =

`[caldcavi_calendar id="team-calendar"]`

`[caldcavi_calendar id="hr-events"]`

`[caldcavi_calendar id="team-calendar" label="Work"]`

`[caldcavi_calendar id="team-calendar" label="Work,Important"]`

`[caldcavi_calendar id="team-calendar" label="Work,!Cancelled"]`

`[caldcavi_calendar id="team-calendar" label="!Private"]`

== Frequently Asked Questions ==

= What iCal formats are supported? =

The plugin supports any standard iCal feed following RFC 5545 (`.ics` files). This includes feeds from Google Calendar, Microsoft Outlook/Exchange, Nextcloud, Apple Calendar, and most other calendar applications.

= Does it work with password-protected calendars? =

Yes. Each feed can be configured with a username and password for HTTP Basic Authentication. Credentials are stored encrypted using AES-256-CBC.

= Can I display multiple calendars on the same page? =

Yes. Configure multiple feeds in the settings, then use separate shortcodes:

`[caldcavi_calendar id="team"]`
`[caldcavi_calendar id="holidays"]`

= Can I filter events by category or label? =

Yes. Use the `label` attribute with a comma-separated list of iCal `CATEGORIES` values. **All** plain labels must be
present on an event for it to appear. Prefix a label with `!` to exclude events carrying that category.
The match is case-insensitive:

`[caldcavi_calendar id="team" label="Work"]`
`[caldcavi_calendar id="team" label="Work,Important"]`

If your calendar application does not populate the `CATEGORIES` field, all events are shown regardless of the `label` attribute.

= How often is the calendar data refreshed? =

By default, fetched data is cached for 1 hour (3600 seconds). You can change this in **Settings → CalDav Calendar Viewer** under Cache Lifetime. Set to `0` to fetch fresh data on every page load. You can also manually clear the cache using the **Clear Cache** button on the settings page.

= What if OpenSSL is not available? =

The plugin falls back to Base64 encoding for password storage. For production use, the OpenSSL PHP extension is strongly recommended.

= Can I style the calendar? =

Yes. The calendar uses CSS classes prefixed with `caldcavi-` that you can override in your theme's stylesheet or via the WordPress Customizer's Additional CSS section.

= How do I hide internal metadata lines from event tooltips? =

Enter line prefixes under **Description Line Prefixes to Remove** in the General Settings. Any description line that starts with one of those prefixes is stripped from the tooltip. For example, adding `X-APPLE-` will hide all lines starting with that prefix.

== Screenshots ==

1. Admin settings page with multiple feed configuration.
2. 7-day event list view on the front end.
3. Event tooltip showing the event description on hover.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
