README

A comprehensive WordPress plugin for managing events with different date configurations (single day, multiple days, recurring) and displaying them in a calendar or list format.

Features

Event Types

Simple Events - Single day or date range events
Recurring Events - Weekly or monthly recurring events with complex patterns
Multiple Date Events - Events occurring on specific non-consecutive dates

Event Management

Advanced Custom Fields (ACF) integration for event configuration
Conditional field logic based on event type
Time-based events with all-day support
Custom database table for efficient date-range queries

Recurring Event Patterns

Weekly: Select specific days of the week
Monthly: "First Tuesday of month" style patterns
Smart date calculation with edge case handling

REST API

Endpoint: /wp-json/polar-events/v1/agenda

Parameters:

days - Number of days to return (default: 7)
offset - Days to skip from today (pagination)
date - Custom start date (Y-m-d format)
event_category - Filter by event category slug

Response Features:

Events grouped by day
Smart date labels ("Avui", "Demà", or formatted date)
Rich event data (images, excerpts, categories, times)
Multilingual date formatting

Template Functions

Date & Time Functions

// Get full date + time string
polar_get_date_range_string($post, $shortFormat = false)

// Get concise date string
polar_get_short_date_range_string($post)

// Get time-only string
polar_get_time_string($post, $concise = false)

Event Query Functions

// Get events in date range
polar_get_events_in_range($startDate, $endDate, $args = [])

// Get upcoming events
polar_get_upcoming_events($days = 7, $args = [])

// Get events for specific day
polar_get_events_for_day($date, $args = [])

Event Data Functions

// Get array of days event occurs (Ymd format)
polar_get_event_days($post)

// Group events by day with smart labels
polar_group_events_by_day($events)

// Get localized day labels
polar_get_day_label($date)

Event Properties

// Check event properties
polar_is_event_today($post)
polar_is_event_upcoming($post)
polar_is_all_day_event($post)
polar_get_event_type($post) // simple|recurring|multiple

Database Schema

The plugin creates a custom table wp_polar_events for efficient event indexing:

CREATE TABLE wp_polar_events (
    event_id bigint(20) NOT NULL AUTO_INCREMENT,
    post_id bigint(20) NOT NULL,
    event_type varchar(20) NOT NULL DEFAULT 'simple',
    event_start_date date NOT NULL,
    event_end_date date NOT NULL,
    created_at timestamp DEFAULT CURRENT_TIMESTAMP,
    updated_at timestamp DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (event_id),
    KEY post_id (post_id),
    KEY event_type (event_type),
    KEY date_range (event_start_date, event_end_date)
);

ACF Field Configuration

The plugin automatically registers the following ACF fields for the polar_event post type:

Event Type (Radio) - simple|recurring|multiple
Start/End Dates (Date Pickers) - conditional on event type
Start/End Times (Time Pickers) - conditional on all-day setting
All Day Event (True/False)
Multiple Dates (Textarea) - for multiple event type, one date per line
Recurrence Frequency (Radio) - weekly|monthly
Days of Week (Checkbox) - for weekly recurrence
Week of Month (Radio) - 1st|2nd|3rd|4th|last for monthly
Day of Week (Radio) - for monthly recurrence

Frontend Display

The plugin includes CSS classes for styling events:

<div class="polar-events-calendar">
  <div class="polar-events-day">
    <h3 class="polar-events-day-label">Today</h3>
    <div class="polar-events-event">
      <img class="polar-events-event-image" src="...">
      <div class="polar-events-event-content">
        <h4 class="polar-events-event-title">Event Title</h4>
        <div class="polar-events-event-time">2:00 PM - 5:00 PM</div>
        <div class="polar-events-event-excerpt">Event description...</div>
      </div>
    </div>
  </div>
</div>

Installation

Upload the plugin files to /wp-content/plugins/polar-events/
Activate the plugin through the WordPress admin
Ensure Advanced Custom Fields (ACF) is installed and active
Start creating events using the "Events" post type

Requirements

WordPress 6.0+
PHP 8.4+
Advanced Custom Fields plugin

Post Types & Taxonomies

Post Type: polar_event with archive support
Taxonomy: polar_event_category for event categorization

API Usage Example

// Get next 7 days of events
fetch('/wp-json/polar-events/v1/agenda?days=7')
  .then(response => response.json())
  .then(data => {
    console.log(data.data); // Events grouped by day
  });

// Get events for specific category
fetch('/wp-json/polar-events/v1/agenda?event_category=workshops&days=14')
  .then(response => response.json())
  .then(data => {
    // Handle filtered events
  });

License

GPL-2.0-or-later

Author

Victor Guerrero - https://polar.cat

polar / events

Maintainers

Package info

Statistics

Security