AA-Events/docs/IMPLEMENTATION_PLAN_REPEATER.md

Multiple Event Dates Implementation Plan

Goal: Add support for events with multiple dates/times using an ACF repeater field, with backward compatibility for legacy event_datetime and date/start_time fields.

Architecture: Add a new ACF repeater field group event_dates containing date and start_time sub-fields. Update display logic to prioritize repeater, then fall back to legacy fields. Update sorting to use earliest date from repeater. Add migration helper for data consolidation.

Tech Stack: Advanced Custom Fields (ACF), WordPress query (WP_Query), ACF repeater fields

---

File Structure Changes

Modified Files:

• includes/acf-fields.php - Add repeater field to ACF group
• includes/post-types.php - Update display and sorting logic
• templates/calendar.php - Update to use repeater field (if needed)

No new files needed initially - Keep changes focused.

---

Task 1: Add ACF Repeater Field Group

Files:

• Modify: includes/acf-fields.php

• Step 1: Add repeater field definition to ACF group

Insert a new field in the $fields array that defines a repeater group with date and start_time sub-fields. The repeater should:

• Be named event_dates
• Allow multiple rows
• Contain sub-fields: date (date picker) and start_time (time picker)
• Be positioned after existing fields but before location fields
• Have conditional logic to display only if no external admin field group exists

Insert this after event_cost field and before event_location_type.

• Step 2: Verify ACF field appears in post editor

Test that the field group loads and the repeater appears in the post editor for event CPT.

---

Task 2: Update Admin Column Display

Files:

• Modify: includes/post-types.php - function events_display_admin_column_content()

• Step 1: Update display logic to use repeater

Modify the column display function to:

1. Check if event_dates repeater has rows
   • If yes: display first date/time + badge showing total count (e.g., "Jan 5, 2025 2:00 PM (3 dates)")
   • If no: fall back to legacy event_datetime field
   • If no legacy field: fall back to new date/start_time fields

Logic flow:

if has repeater rows:
  show first date/time + " (X dates)" badge
elif has event_datetime:
  show event_datetime
elif has date field:
  show date + start_time
else:
  show nothing

• Step 2: Test display in admin list

Verify the column shows:

• First date with count badge for events with repeater data
• Legacy format for old events
• Nothing for events with no dates

---

Task 3: Update Sorting Logic

Files:

• Modify: includes/post-types.php - functions events_get_sortable_meta_map() and events_sort_by_custom_column()

• Step 1: Add repeater field to sortable map

Note: ACF repeater fields cannot be directly sorted by orderby=meta_value. Instead, we'll sort by the earliest date.

• Step 2: Update sort handler

When sorting by event_datetime column:

1. If repeater has data: query by first row's event_dates_0_date meta key (ACF stores repeater rows as sequential meta keys)
2. If repeater empty: use legacy sort (event_datetime or date field)

This ensures posts sort by their earliest event date.

• Step 3: Test sorting

Verify that:

• Posts with repeater data sort by earliest date
• Legacy posts sort correctly
• Mixed results display in correct order

---

Task 4: Update Calendar Template (if needed)

Files:

• Check: templates/calendar.php

• Step 1: Inspect calendar usage

Review how calendar.php queries and displays events. Determine if it needs updates to handle repeater field.

• Step 2: Update if necessary

If calendar shows single events per date:

• Update query to use earliest date from repeater
• Add note in template comments about repeater structure

---

Task 5: Document Migration Path (Optional)

Files:

• Create reference docs in README or code comments

• Step 1: Document field deprecation

Add comments in acf-fields.php explaining:

• Legacy event_datetime field is deprecated but still supported

• New events should use event_dates repeater

• Old events continue to work via fallback logic

• Step 2: Add helper function comment

Document that a future migration tool could consolidate old data into repeater format, but it's not urgent since fallback works.

---

Implementation Notes

• ACF Repeater Meta Storage: ACF stores repeater rows as numbered meta keys: event_dates_0_date, event_dates_0_start_time, event_dates_1_date, etc.
• Backward Compatibility: Never remove old fields—just add fallback logic in display/sort functions.
• Performance: Querying repeater fields for sorting can be slow on large datasets. Consider date-based sorting as primary option if performance degrades.
• Frontend: Templates on the frontend may also need updates to loop through all dates instead of showing one. This is separate from admin display.

---

Testing Checklist

• Post with repeater data displays first date + badge in admin list
• Post with old event_datetime field displays correctly (fallback)
• Post with new date/start_time fields displays correctly (second fallback)
• Admin list sorts correctly by earliest date when column clicked
• Posts without any date fields show nothing (don't error)
• Calendar template still works (if uses event dates)