Data Machine Events

Frontend-focused WordPress events plugin with a block-first architecture that ties Event Details data storage to Calendar block progressive enhancement and REST API-driven filtering.

Version: 0.8.1

Architecture Overview

• Blocks First: inc/Blocks/EventDetails captures authoritative event data while inc/Blocks/Calendar renders Carousel List views informed by _datamachine_event_datetime post meta and REST responses.
• Data Machine Imports: The pipeline runs through inc/Steps/EventImport/EventImportStep and 15 registered handlers. Each handler builds a DataPacket, normalizes titles/dates/venues via Utilities/EventIdentifierGenerator, marks items processed, and returns immediately after a valid event to enable incremental syncing.
• EventUpsert Workflow: Steps/Upsert/Events/EventUpsert merges engine data snapshots, runs field-by-field change detection, delegates taxonomy assignments to DataMachine\Core\WordPress\TaxonomyHandler, uses WordPressPublishHelper for images, and keeps _datamachine_event_datetime synced for performant calendar queries.

Import Pipeline

1. EventImportStep discovers handlers that register themselves via HandlerRegistrationTrait and exposes configuration through handler settings classes.
2. Handlers: Bandzoogle Calendar, Dice FM, DoStuff Media API, Eventbrite, EventFlyer, GoDaddy Calendar, Google Calendar (with GoogleCalendarUtils for ID/URL resolution), ICS Calendar, Prekindle, SingleRecurring, SpotHopper, Ticketbud, Ticketmaster, Universal WebScraper, and WordPress Events API.
3. Each handler applies EventIdentifierGenerator::generate($title, $startDate, $venue) to deduplicate, merges venue metadata into EventEngineData, and forwards standardized payloads to EventUpsert.
4. VenueService/Venue_Taxonomy find or create venue terms and store nine meta fields (address, city, state, zip, country, phone, website, capacity, coordinates) for use in blocks and REST endpoints.
5. EventUpsertSettings exposes status, author, taxonomy, and image download toggles via WordPressSettingsHandler so runtime behavior remains configurable.

REST APIs

Routes live under /wp-json/datamachine/v1/events/* and are registered in inc/Api/Routes.php with controllers in inc/Api/Controllers.

• GET /events/calendar: Calendar controller returns fragments (html, pagination, navigation, counter) plus success metadata; accepts event_search, date_start, date_end, tax_filter[taxonomy][], paged, and past, sanitizes inputs, uses SQL-based query logic, and caches taxonomy counts for pagination.
• GET /events/filters: Filters controller lists taxonomy terms with counts, hierarchy, and dependency hints; accepts active, context, date_start, date_end, and past and powers the filter modal in the Calendar block.
• GET /events/venues/{id}: Venues controller (capability manage_options) returns venue description and nine meta fields including coordinates from Venue_Taxonomy::get_venue_data().
• GET /events/venues/check-duplicate: Venues controller checks name/address combinations, sanitizes input, and returns is_duplicate, existing_venue_id, and friendly messaging to avoid duplicates during admin venue creation.
• POST /events/geocode/search: Geocoding controller validates the Nominatim query and returns display_name, lat, lon, and structured address parts for venue creation flows; relies on OpenStreetMap data.

Blocks & Frontend

• Calendar Block (inc/Blocks/Calendar): Carousel List display with day grouping, time-gap separators, pagination, filter modal, and server-rendered templates (event-item, date-group, pagination, navigation, results-counter, no-events, filter-bar, time-gap-separator, modal/taxonomy-filter).
• Templates & Helpers: Template_Loader, Taxonomy_Helper, and Taxonomy_Badges sanitize variables, build taxonomy hierarchies, and render badges with filters for wrapper/classes and button styles.
• JavaScript Modules: src/frontend.js initializes .datamachine-events-calendar instances and orchestrates modules/api-client.js, modules/carousel.js, modules/date-picker.js, modules/filter-modal.js, modules/navigation.js, and modules/state.js for REST communication, carousel controls, Flatpickr integration, filter modal accessibility, navigation handling, and URL state.
• Progressive Enhancement: Server-first rendering works without JavaScript; REST requests enrich filtering and pagination when scripts are active while preserving history state and debounced search.
• Event Details Block (inc/Blocks/EventDetails): Provides 15+ attributes (dates, venue, pricing, performer/organizer metadata, status, display toggles) plus InnerBlocks. Leaflet assets (leaflet.css, leaflet.js, assets/js/venue-map.js) and root CSS tokens (inc/Blocks/root.css) load conditionally via enqueue_root_styles() to render venue maps and maintain consistent styling.

Documentation & Guides

Handler and feature guides live under /docs, covering the REST API (docs/rest-api.md), block behavior (docs/calendar-block.md, docs/event-details-block.md), pipeline helpers (docs/event-identifier-generator.md, docs/event-schema-provider.md, docs/pipeline-components-js.md), pagination (docs/pagination-system.md), venue management (docs/venue-management.md, docs/venue-parameter-provider.md), geocoding (docs/geocoding-integration.md), and handler-specific notes (e.g., docs/ticketmaster-handler.md).

Project Structure

datamachine-events/
├── datamachine-events.php           # Bootstraps constants, loads meta storage, and registers REST routes
├── inc/
│   ├── Admin/                       # Settings page, admin bar, capability checks
│   ├── Api/                         # Routes + controllers (Calendar, Venues, Filters, Geocoding)
│   ├── Blocks/
│   │   ├── Calendar/                # Carousel block templates, JS modules, pagination
│   │   ├── EventDetails/             # Schema-aware block with webpack build
│   │   └── root.css                 # Shared design tokens
│   ├── Core/                        # Post type, taxonomies, meta storage, helpers
│   ├── Steps/
│   │   ├── EventImport/             # EventImportStep + registered handlers
│   │   └── Upsert/Events/            # EventUpsert handler, settings, filters, schema helpers
│   └── Utilities/                   # EventIdentifierGenerator, schema helpers, taxonomy helpers
├── assets/                          # Admin JS/CSS (pipeline components, venue autocomplete/map)
├── docs/                            # Handler and feature documentation
└── build.sh                         # Production packaging script

Commands

composer install                                # PHP dependencies
cd inc/Blocks/Calendar && npm install && npm run build
cd ../EventDetails && npm install && npm run build
npm run start                                   # Run watchers for Calendar and Event Details blocks from their directories
npm run lint:js && npm run lint:css             # Event Details block linting
./build.sh                                      # Creates /dist/datamachine-events.zip

Watchers should run inside their respective block directories (inc/Blocks/Calendar and inc/Blocks/EventDetails).