Keith Solomon
51147ef36f
- Introduced a new specification for adding an optional contact email field to events, including front-end output and compatibility testing. - Added a comprehensive design document for multi-day event occurrences, detailing the new occurrence data model, validation, normalization, and calendar architecture. - Created specifications for ACF field-key switching compatibility and local ACF override compatibility to ensure seamless integration with existing themes. - Implemented a desktop calendar view toggle design, allowing users to switch between calendar and list views, with persistent preferences and responsive behavior.
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# Local ACF Override Compatibility Design
|
|
|
|
## Problem
|
|
|
|
AA Events suppresses its built-in ACF field group when the MNBC theme's local
|
|
field group is enabled. The theme group stores repeating dates under
|
|
`multiple_dates` and returns dates and times as `F j, Y` and `g:i a`. The
|
|
plugin's occurrence reader only reads `event_dates` and strictly parses
|
|
`Y-m-d` dates and 24-hour times. As a result, the plugin detects the local
|
|
group as an override but cannot turn its schedule values into occurrences, so
|
|
the events do not appear in schedule-driven views.
|
|
|
|
## Scope
|
|
|
|
This change makes the plugin compatible with the existing MNBC schedule fields
|
|
and normalizes the theme's local ACF JSON to the documented AA Events schedule
|
|
contract. It does not rename or otherwise change unrelated cost, location, or
|
|
contact fields.
|
|
|
|
## Plugin Compatibility
|
|
|
|
`aa_events_get_occurrences()` will use schedule sources in this order:
|
|
|
|
1. The canonical `event_dates` repeater when it contains rows.
|
|
2. The legacy local-override `multiple_dates` repeater when it contains rows.
|
|
3. The existing `event_datetime` fallback.
|
|
4. The existing standalone `date` and `start_time` fallback.
|
|
|
|
Canonical rows take precedence when both repeaters contain data. Legacy
|
|
`multiple_dates` rows will normalize to the same public occurrence shape as
|
|
canonical rows, without adding a new public source type.
|
|
|
|
The occurrence parsing boundary will accept the plugin's canonical return
|
|
formats and the formats emitted by the existing theme override:
|
|
|
|
- Dates: `Y-m-d`, compact ACF `Ymd`, and `F j, Y`.
|
|
- Times: `H:i:s`, `H:i`, and `g:i a`.
|
|
|
|
All accepted values will be normalized to `Y-m-d` and `H:i:s` before existing
|
|
range validation, sorting, and rendering logic runs. Invalid or ambiguous
|
|
values will continue to be rejected rather than guessed.
|
|
|
|
Metadata-change synchronization will recognize both repeater names and their
|
|
schedule subfields. ACF value-cache flushing will include `multiple_dates`, so
|
|
direct metadata changes cannot leave stale canonical occurrence indexes.
|
|
|
|
## Theme ACF JSON
|
|
|
|
The MNBC theme field group at
|
|
`wp-content/themes/MNBC/acf/group_69fb58894f83f.json` will be updated as
|
|
follows:
|
|
|
|
- Rename the repeater field from `multiple_dates` to `event_dates`, retaining
|
|
its stable ACF field key.
|
|
- Change the standalone and repeater Date fields' return format to `Y-m-d`.
|
|
- Change the standalone and repeater Start Time and End Time fields' return
|
|
format to `H:i:s`.
|
|
|
|
The existing field keys remain unchanged. No unrelated field definitions will
|
|
be modified.
|
|
|
|
## Existing Data
|
|
|
|
Renaming the ACF field does not rename previously saved WordPress metadata.
|
|
Existing rows stored as `multiple_dates_*` therefore remain in place and are
|
|
read through the plugin compatibility fallback. Newly edited schedule data
|
|
will be saved under canonical `event_dates_*` keys.
|
|
|
|
No destructive or automatic bulk database migration is included. If both old
|
|
and new repeater data exist on an event, canonical `event_dates` data is
|
|
authoritative.
|
|
|
|
## Testing
|
|
|
|
Regression tests will first reproduce the current theme override:
|
|
|
|
- `multiple_dates` rows using `F j, Y` dates and `g:i a` times produce
|
|
normalized occurrences.
|
|
- Standalone legacy fields in those formats produce an occurrence.
|
|
- Canonical `event_dates` rows win when both repeater names contain data.
|
|
- Invalid formatted values remain excluded.
|
|
- Metadata synchronization recognizes and flushes the legacy repeater.
|
|
|
|
The focused occurrence tests and complete plugin test suite must pass after
|
|
the implementation. The theme JSON will also be parsed to confirm it remains
|
|
valid JSON and contains the canonical schedule names and return formats.
|