diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 1cc503a..b95a810 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -11,7 +11,7 @@ composer require transformstudios/events Get up and running in three steps: 1. Create or use a Statamic collection (default: `events`) -2. Import the provided fieldset: `events::event` +2. Import the provided fieldsets: `events::event` (schedule) and `events::location` (optional) 3. Add a template: ```antlers @@ -57,7 +57,7 @@ ICS downloads read the following entry fields when present: | Online only | `online_url` | `online_url` | — | | Hybrid | `location.name` | `online_url` | `location.coordinates` | -`location` must be a group. A string or other non-group value is skipped (no `LOCATION:` from it). Nested coordinates shape: +`location` must be a group. A string or other non-group value is skipped (no `LOCATION:` from it). Nested coordinates: ```php 'location' => [ @@ -75,16 +75,36 @@ If your field names differ from the defaults above, use a [Computed Value](https --- -## Fieldset +## Fieldsets -Your collection blueprint must include the required event fields for Events to work correctly. +Your collection blueprint must include the schedule fields for Events to work. Location fields are optional but required for ICS `LOCATION:` / `URL:` / `GEO:`. -You can: +| Fieldset | Contents | +|---|---| +| `events::event` | Recurrence, dates, times, multi-day days | +| `events::location` | `location` group (`name` + `coordinates`) and `online_url` | -- Define fields manually -- Import the provided fieldset: `events::event` +Import both into one tab, or put them on separate tabs: -Using the sample fieldset is the fastest way to get started. +```yaml +tabs: + schedule: + display: Schedule + sections: + - + fields: + - + import: events::event + location: + display: Location + sections: + - + fields: + - + import: events::location +``` + +You can also define the fields manually instead of importing. --- @@ -92,6 +112,8 @@ Using the sample fieldset is the fastest way to get started. ### Location & Online URL +Provided by `events::location`: + | Field | Description | |-------|-------------| | `location` | Group: `name` (localizable text — venue, description, or address) and optional nested `coordinates` (`latitude` / `longitude`). | @@ -99,14 +121,15 @@ Using the sample fieldset is the fastest way to get started. ### Upgrading to 7.0 -Breaking changes for location fields: +Breaking changes: - `location` is now a **group** (`name` + nested `coordinates`), not a string - `address`, `link`, and top-level `coordinates` are no longer read - URL sniffing on a string `location` is gone — use `online_url` for join links - Protected `eventUrl()` / `icsAddress()` were replaced by `icsUrl()` / `icsLocation()` +- Location fields moved out of `events::event` into **`events::location`**. Import that fieldset (same tab or a Location tab) or add the fields yourself. `type: section` dividers were removed from `events::event`. -An update script (#196) migrates common legacy handles. Back up content before upgrading. Computed-value mappings and foreign (e.g. Prime) `location` shapes need a separate cutover. +An update script migrates common legacy content handles. Back up content before upgrading. Computed-value mappings and `location` values that are already a group need a separate cutover. ### Single-Day Events diff --git a/README.md b/README.md index 2bfbad4..0fc0e44 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,14 @@ Dates, timezones, and calendars are hard. Events makes recurring, multi-day, and ### Key Benefits - **Render Calendars with Minimal Code** – Generate calendar views and event listings using simple template tags. -- **Drop-In Event Fieldset** – Start fast with a ready-to-use fieldset that handles recurrence, multi-day events, and timezones. +- **Drop-In Event Fieldsets** – Start fast with ready-to-use fieldsets for schedule (`events::event`) and location (`events::location`). - **Add to Calendar (ICS)** – Let users download events and add them directly to their calendar. --- ## How It Works -After installing via Composer, create or use a standard Statamic collection with structured event fields. You can use the provided [sample fieldset](https://github.com/transformstudios/statamic-events/blob/main/resources/fieldsets/event.yaml) to get started quickly. +After installing via Composer, create or use a standard Statamic collection with structured event fields. You can use the provided [schedule](https://github.com/transformstudios/statamic-events/blob/main/resources/fieldsets/event.yaml) and [location](https://github.com/transformstudios/statamic-events/blob/main/resources/fieldsets/location.yaml) fieldsets to get started quickly. Once configured, use simple template tags like: diff --git a/resources/fieldsets/event.yaml b/resources/fieldsets/event.yaml index a503206..70eb319 100644 --- a/resources/fieldsets/event.yaml +++ b/resources/fieldsets/event.yaml @@ -111,11 +111,6 @@ fields: input_format: YYYY/M/D/YYYY display: Date format: Y-m-d - - - handle: times_sections - field: - type: section - display: Times - handle: all_day field: @@ -203,57 +198,3 @@ fields: field: 'events::event.all_day' config: width: 25 - - - handle: location_section - field: - type: section - display: Location - - - handle: location - field: - type: group - display: Location - fullscreen: false - border: false - localizable: true - instructions: 'Physical place for the event — a plain description or an address. Optional; combine with Online URL for hybrid events.' - fields: - - - handle: name - field: - type: text - display: Name - localizable: true - instructions: 'Venue name, plain description, or street address (ICS LOCATION).' - - - handle: coordinates - field: - type: group - display: Coordinates - fullscreen: false - border: false - instructions: 'Optional map coordinates for ICS GEO.' - fields: - - - handle: latitude - field: - type: float - display: Latitude - width: 50 - - - handle: longitude - field: - type: float - display: Longitude - width: 50 - - - handle: online_url - field: - type: text - input_type: url - display: 'Online URL' - localizable: false - validate: - - nullable - - url - instructions: 'Join link for online or hybrid events (Zoom, livestream, etc.).' diff --git a/resources/fieldsets/location.yaml b/resources/fieldsets/location.yaml new file mode 100644 index 0000000..860acc9 --- /dev/null +++ b/resources/fieldsets/location.yaml @@ -0,0 +1,51 @@ +title: Location +fields: + - + handle: location + field: + type: group + display: Location + fullscreen: false + border: false + localizable: true + instructions: 'Physical place for the event — a plain description or an address. Optional; combine with Online URL for hybrid events.' + fields: + - + handle: name + field: + type: text + display: Name + localizable: true + instructions: 'Venue name, plain description, or street address (ICS LOCATION).' + - + handle: coordinates + field: + type: group + display: Coordinates + fullscreen: false + border: false + instructions: 'Optional map coordinates for ICS GEO.' + fields: + - + handle: latitude + field: + type: float + display: Latitude + width: 50 + - + handle: longitude + field: + type: float + display: Longitude + width: 50 + - + handle: online_url + field: + type: text + input_type: url + display: 'Online URL' + localizable: false + validate: + - nullable + - url + instructions: 'Join link for online or hybrid events (Zoom, livestream, etc.).' diff --git a/tests/__fixtures__/blueprints/collections/events/event.yaml b/tests/__fixtures__/blueprints/collections/events/event.yaml index edac8dc..934e58d 100644 --- a/tests/__fixtures__/blueprints/collections/events/event.yaml +++ b/tests/__fixtures__/blueprints/collections/events/event.yaml @@ -1,16 +1,25 @@ title: Event -sections: - main: - display: Main - fields: +tabs: + schedule: + display: Schedule + sections: - - import: events::event + fields: + - + import: events::event + - + handle: categories + field: + type: terms + taxonomies: + - categories + display: Categories + mode: tags + width: 50 + location: + display: Location + sections: - - handle: categories - field: - type: terms - taxonomies: - - categories - display: Categories - mode: tags - width: 50 + fields: + - + import: events::location