Using the iCal Feeds
Events Manager publishes your events in two machine-readable formats. iCal (.ics) is what calendar apps such as Google Calendar, Apple Calendar and Outlook read, for a single event or for a feed that stays up to date. RSS is for feed readers and for services that post new items elsewhere.
Both are on from the moment the plugin is active. This page lists the addresses, the links you can show visitors, and the settings that control what the feeds contain.
Add to calendar on an event page
The default single event page already has an Add To Calendar button. Clicking it opens a short menu:
| Menu item | What it does |
|---|---|
| Download ICS | Downloads the event as an .ics file, which any calendar app can open. |
| Google Calendar | Opens Google Calendar with a new event filled in. |
| iCalendar | Opens the event in the visitor's default calendar app through a webcal:// link. |
| Office 365 | Opens Outlook on the web for work or school accounts with a new event filled in. |
| Outlook Live | The same for personal Outlook.com accounts. |
The Add To Calendar menu on a single event page.
The button comes from the #_EVENTADDTOCALENDAR placeholder. If you have written your own Single event page format, add the placeholder where you want the button.
Placeholders for single links
To show one link in place of the menu, or to put a link in an email, use these. Each comes as a ready-made link and as a bare address for your own HTML.
| Link | Address only | Gives |
|---|---|---|
#_EVENTICALLINK | #_EVENTICALURL | The event's .ics file. The link text is "iCal". |
#_EVENTWEBCALLINK | #_EVENTWEBCALURL | The same file as a webcal:// address, which opens straight in a calendar app. The link text is "webcal". |
#_EVENTGCALLINK | #_EVENTGCALURL | Google Calendar, with the event filled in. The link is a Google Calendar button image, loaded from Google. |
#_EVENTOFFICE365LINK | #_EVENTOFFICE365URL | Outlook on the web for work or school accounts. |
#_EVENTOUTLOOKLIVELINK | #_EVENTOUTLOOKLIVEURL | Outlook.com. |
For your own wording, use the address form:
<a href="#_EVENTICALURL">Save this event to your calendar</a>
A booking confirmation email is a good place for one of these, so the attendee can save the date as soon as they book.
iCal feeds
A feed is an address a calendar app can subscribe to. The app reads it again from time to time, so events you add later turn up in the subscriber's calendar without them doing anything.
| Feed | Address | Contains |
|---|---|---|
| All events | https://example.com/events.ics | Upcoming events, as set by iCal Scope and iCal Limit. |
| One event | The event's address followed by ical/, such as https://example.com/events/harbor-lights-jazz-night/ical/ | That event. |
| One location | The location's address followed by ical/ | Every event at that location. |
| One category or tag | The category's or tag's address followed by ical/ | Every event in it. |
On a site with plain permalinks (addresses with ?p=123), the all-events feed is still https://example.com/events.ics, or https://example.com/?ical=1, and the other feeds take &ical=1 on the end of the page's address in place of ical/.
Opening a feed address in a browser downloads an .ics file. That is expected: paste the address into a calendar app to subscribe instead.
Password-protected events are left out of every feed. So are drafts, pending events and private events.
Link to the feeds
| To link to | Use |
|---|---|
| The all-events feed | A normal link to /events.ics, or the [events_gcal] shortcode for a Google Calendar subscribe button. |
| A location's feed | #_LOCATIONICALLINK or #_LOCATIONICALURL, and #_LOCATIONWEBCALLINK or #_LOCATIONWEBCALURL, in a location format. |
| A category's feed | #_CATEGORYICALLINK or #_CATEGORYICALURL, and #_CATEGORYWEBCALLINK or #_CATEGORYWEBCALURL, in a category format. |
| A tag's feed | #_TAGICALLINK or #_TAGICALURL, and #_TAGWEBCALLINK or #_TAGWEBCALURL, in a tag format. |
For example, on a page of your own:
<a href="webcal://example.com/events.ics">Subscribe to all our events</a>
A webcal:// link is the same feed with a different prefix. It tells the visitor's device to open its calendar app and offer to subscribe, where an https:// link would download the file.
Subscribe in a calendar app
Every major calendar app can subscribe to a feed by its address. The option is usually called "subscribe", "add by URL" or "add from web":
- Google Calendar: add a calendar "From URL" and paste the feed address. See Google's instructions for adding a calendar by link.
- Apple Calendar: use the "New Calendar Subscription" command and paste the address, or click a
webcal://link. - Outlook: use "Add calendar" and choose to subscribe from the web.
Each app decides how often it reads the feed again. Some take a day or more to show a change, and that can't be sped up from your site.
iCal feed settings
The settings are at the bottom of Events then Settings then Formatting then Calendar, under iCal Feed Settings.
The iCal feed settings.
| Setting | Default | What it does |
|---|---|---|
| iCal Title | #_EVENTNAME | The title of each event in the subscriber's calendar. |
| iCal Description | #_EVENTEXCERPT | The description of each event. |
| iCal Location | #_LOCATIONNAME, #_LOCATIONFULLLINE, #_LOCATIONCOUNTRY | The location line of each event. |
| iCal Scope | Future events | The date range of the all-events feed. Choose All events to include past ones. |
| iCal Limit | 50 | The most events in a feed. 0 means no limit. |
The first three accept event and location placeholders. They apply to single-event files as well as to feeds.
Each event in a feed also carries its start and end with the event's timezone, a link back to its page, its categories, its featured image, and map coordinates when the location has them. An online event sends its link in place of an address.
For an iCal feed of only the events you choose, or to bring another calendar's iCal feed into your site, use the Events Manager I/O add-on: see export setup and import setup. Pro Plus
RSS feeds
The RSS feed lists your events for feed readers.
| Feed | Address |
|---|---|
| All events | https://example.com/events/feed/ |
| One category or tag | The category's or tag's address followed by feed/ |
| One location | The location's address followed by feed/ |
The first part of the all-events address is your events slug, events unless you have changed it. On a site with plain permalinks the address is https://example.com/?post_type=event&feed=rss2.
To print the right address for your site, use the [events_rss_url] shortcode, or [events_rss_link] for a ready-made link. In formats, #_LOCATIONRSSLINK, #_CATEGORYRSSLINK and #_TAGRSSLINK (and the same names ending in URL) link to the feed of a location, category or tag.
RSS settings
The settings are in Events then Settings then Formatting then RSS.
The RSS feed settings.
| Setting | Default | What it does |
|---|---|---|
| RSS main title | Your site title, then "Events" | The name of the feed. |
| RSS main description | Your site tagline, then "Events" | The description of the feed. |
| RSS title format | #_EVENTNAME | The title of each item. |
| RSS description format | Dates, times, location name, address and town | The body of each item. Accepts placeholders. |
| RSS limit | 50 | The most events in the feed. 0 means no limit. |
| RSS Scope | Future events | The date range of the feed. |
| Default event list ordering | Start date, start time, then name, ascending | The order of items. |
Customize the feed templates
A developer can change the structure of either feed by copying its template into the theme: events-manager/templates/templates/ical.php for iCal and rss.php in the same folder for RSS. See Using template files.
Troubleshooting
The feed address shows a "page not found" error
Feeds for single events, locations, categories and tags rely on WordPress rewrite rules. Go to Settings then Permalinks and click Save Changes without changing anything, which rebuilds them.
A subscribed calendar doesn't show a new event
The calendar app has not read the feed again yet. Check the feed itself by opening its address in a browser and looking for the event in the downloaded file. If it is there, the app will catch up. If it is not, check that the event is published, not password protected, and inside iCal Scope and iCal Limit.
Events show at the wrong time in the calendar app
The feed sends each event's own timezone. Check the event's timezone in the event editor, and the site timezone in Settings then General. See Timezone support.
The feed stops after 50 events
That is the default iCal Limit. Raise it, or set it to 0.