Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 33 additions & 10 deletions DOCUMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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' => [
Expand All @@ -75,38 +75,61 @@ 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.

---

## Fields

### Location & Online URL

Provided by `events::location`:

| Field | Description |
|-------|-------------|
| `location` | Group: `name` (localizable text — venue, description, or address) and optional nested `coordinates` (`latitude` / `longitude`). |
| `online_url` | Join link for online or hybrid events (Zoom, livestream, etc.). Optional; independent of `location`. |

### 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

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
59 changes: 0 additions & 59 deletions resources/fieldsets/event.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.).'
51 changes: 51 additions & 0 deletions resources/fieldsets/location.yaml
Original file line number Diff line number Diff line change
@@ -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.).'
35 changes: 22 additions & 13 deletions tests/__fixtures__/blueprints/collections/events/event.yaml
Original file line number Diff line number Diff line change
@@ -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