Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
299 lines (202 loc) · 7.42 KB

DOCUMENTATION.md

File metadata and controls

299 lines (202 loc) · 7.42 KB
Raw

Installation

Install via Composer:

composer require transformstudios/events

Quick Start

Get up and running in three steps:

  1. Create or use a Statamic collection (default: events)
  2. Import the provided fieldset: events::event
  3. Add a template:
{{ events:upcoming limit="5" }}
  {{ title }} – {{ start }}
{{ /events:upcoming }}

You now have a working event listing.

Configuration

Default Timezone

By default, events use your application timezone (typically UTC).

You can override this in the Control Panel. This value is used when an event does not have a timezone set.

Collection

The default collection is events.

If you are using a different Statamic collection, update it in the addon settings.

ICS Downloads

ICS downloads read the following entry fields when present:

ICS property Source
LOCATION location.name, falling back to online_url when the name is empty
URL online_url
GEO location.coordinates (latitude / longitude)
DESCRIPTION description

location and online_url are independent and combinable (hybrid events).

Event LOCATION: URL: GEO:
Physical only location.name — location.coordinates
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' => [
    'name' => '123 Main St',
    'coordinates' => [
        'latitude' => 40,
        'longitude' => 50,
    ],
],

Partial or non-numeric coordinates are skipped (no GEO:) rather than failing the download.

If your field names differ from the defaults above, use a Computed Value to map them.

Fieldset

Your collection blueprint must include the required event fields for Events to work correctly.

You can:

  • Define fields manually
  • Import the provided fieldset: events::event

Using the sample fieldset is the fastest way to get started.

Fields

Location & Online URL

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:

  • 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()

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.

Single-Day Events

Field Required Description
start_date Yes Start date of the event
start_time No Start time (not required if all_day is true)
end_time No End time
all_day No If true, times are not required

Recurring Events

Extends single-day events with recurrence rules:

Field Description
recurrence daily, weekly, monthly, annually, every
specific_days For rules like “3rd Tuesday”
interval Required when using every
period days, weeks, months, years
end_date Optional end to recurrence
exclude_dates Dates to exclude from occurrences

If no end_date is set, the event continues indefinitely.

Multi-Day Events

Use this when events span specific dates.

Field Required Description
multi_day Yes Enables multi-day mode
days Yes Array of event days

Example:

multi_day: true
days:
  -
    date: '2019-11-23'
    start_time: '19:00'
    end_time: '21:00'
  -
    date: '2019-11-24'
    start_time: '11:00'
    end_time: '15:00'

When multi_day is enabled, standard single-day and recurrence fields are ignored.

Usage

Available Tags

  • events:between
  • events:calendar
  • events:in
  • events:today
  • events:upcoming
  • events:download_link

These tags return event occurrences (individual dates generated from your events).

Common Parameters

Parameter Description
site Site handle (defaults to current site)
timezone Adjusts all occurrences to this timezone

Returned Data

Each occurrence includes:

Field Description
start Start datetime
end End datetime
has_end_time Boolean

Multi-day events also include a days array with per-day data.

Pagination

Supported on:

  • between
  • in
  • today

Example:

paginate="10"

Filtering

Supports both standard conditions and taxonomy filtering using standard Statamic syntax:

taxonomy:categories:not="example" title:contains="awesome"

Sorting

Default: ascending To reverse:

sort="desc"

Tag Reference

Note: collection and event are mutually exclusive. Pass collection to list occurrences from a whole collection, or event to get occurrences for a single entry — not both. Using them together throws an exception. (This does not apply to events:download_link, which accepts both.)

events:between

Returns events within a date range.

Parameters:

  • collection (optional, defaults to 'events'; cannot be combined with event)
  • event (optional) Pass id of the event you want occurrences for; cannot be combined with collection
  • from (optional, defaults to now)
  • to (required)

events:calendar

Returns a full calendar grid for a given month.

Each day contains either:

  • no_results
  • occurrences

Additional flags:

  • spanning
  • spanning_start
  • spanning_end

events:in

Returns events within a future time window.

Parameters:

  • collection (optional, defaults to 'events'; cannot be combined with event)
  • event (optional) Pass id of the event you want occurrences for; cannot be combined with collection

Example:

next="90 days"

events:today

Returns events occurring today.

Parameters:

  • collection (optional, defaults to 'events'; cannot be combined with event)
  • event (optional) Pass id of the event you want occurrences for; cannot be combined with collection
  • ignore_past (optional, defaults to 'false')

events:upcoming

Returns the next set of event occurrences.

Parameters:

  • limit (required)
  • collection (optional, defaults to 'events'; cannot be combined with event)
  • event (optional) Pass id of the event you want occurrences for; cannot be combined with collection
  • collapse_multi_days (optional)
  • offset (optional)

events:download_link

Generates an ICS download link.

Parameters:

  • date date get occurrences to download

Includes the fields documented under ICS Downloads.