User Guide

Installing the Plugin

To install the free ICS Calendar plugin, log into your WordPress site’s admin and go to Plugins > Add New. Search for “ICS Calendar” and you’ll see the distinctive orange calendar icon. Click the Install button and after installation, click Activate.

You can also download the plugin zip file from the WordPress Plugin Directory and install it by going to Plugins > Add New > Upload Plugin and uploading the zip file you downloaded.

Important note for manual installation: If you are using Safari, it may be configured to automatically extract zip files upon download. If your download results in a folder rather than a zip file, look in your Trash for a file called ics-calendar.zip. Move it out of the trash and then proceed as directed above.

Downloading and Installing the Pro Version

The Pro version is an add-on to the free version. You will need both the free and Pro versions installed and activated. Please follow the instructions above for installing the free version before installing Pro.

After purchasing the Pro version, you will receive an email receipt containing a “Download Your Files” link. Click that link to download the ICS Calendar Pro files. You’ll receive a zip file called ics-calendar-pro.zip. (There may be additional characters preceding .zip in the filename.)

Log into your WordPress admin and go to Plugins > Add New > Upload Plugin. Upload and activate the ics-calendar-pro.zip file, then navigate to ICS Calendar > Settings & Tools > License to enter the license API key and product ID contained in your receipt email. ICS Calendar Pro is now ready to use!

If you are using Safari, see “Important note for manual installation” above.

Finding Your ICS Feed URL

Different calendar systems have different ways to obtain the feed URL. You may need to consult your calendar software’s documentation for assistance. You will also need to make sure that your calendar is public. Private calendars cannot be accessed by this plugin.

Documentation quick links:

• Google Calendar
• Microsoft Outlook
• iCloud Calendar (Mac/iOS)

Adding Your Calendar to a WordPress Page

You’ll be using a WordPress shortcode to insert your calendar. Both the classic editor and the new block editor (Gutenberg) support shortcodes. Please continue to the next section (Shortcode Overview) for details of creating your shortcode.

Basic Shortcode Example

To insert an ICS calendar in a page, use the following shortcode format, replacing the all-caps text with your information as appropriate.

[ics_calendar url="YOUR_ICAL_FEED_URL"]

Calendar Feed URL

Be sure you are using a subscribe URL (which may end in .ics or have no filename extension), not a web calendar URL (ending in .html).

Multiple Feeds in One Calendar

This plugin supports multiple feeds in a single calendar display. Enter multiple URLs in the url parameter, separated by one space, or by the pipe character |, as long as your feed URLs do not contain that character. Do not include other delimiter characters, as they will be interpreted as part of the URL. (We are using the space as a delimiter since properly formed URLs cannot contain spaces, but this has been known in rare cases to cause conflicts with some other third-party plugins.)

Display Title and Description

The title and description parameters are optional. If omitted, the title and description provided by the calendar feed will be displayed. Use “false” (e.g. title="false") to hide the title or description altogether.

Deprecation notice: For backwards compatibility with earlier versions, title and description also support "none" as a value for hiding the default title and description. This support may be removed in a future version.

General Notes

Shortcode Formatting

WordPress likes to convert “straight quotes” into “smart quotes,” which can cause problems with parsing shortcodes. Be sure that you are only using straight quotes in your shortcode. You can also omit the quotes entirely in most cases — parameters in the shortcode only need to be wrapped in quotes if they contain a space, such as if you’re including multiple URLs in your url parameter.

WordPress General Settings

Whenever possible, the plugin relies on your site’s general settings (Settings > General) to determine display parameters. Specifically: Site Language, Date Format, Time Format and Week Starts On. If any of these elements of the calendar are not displaying to your liking, please check these settings before trying anything else.

Month View

The default display is a month calendar grid. The month grid collapses to a CSS-styled list at phone screen sizes. You can use this view by setting view="month" or omitting this parameter entirely.

By default the grid’s column labels will be the full names of the days of the week. For tighter layouts you can add columnlabels="short" to use 3-letter abbreviations, or columnlabels="min" to use 1- or 2-letter abbreviations. (The full day names and abbreviations are in the plugin’s translation files for all supported languages.)

Week View

You can display just the current week (with a selector to choose the previous and next week) in a grid style similar to month view by using view="week". If desired, the selector can be hidden using custom CSS.

You can also display a fixed “week” (i.e. a short range of days) by adding startdate="YYYYMMDD" and setting limitdays="n" where n is the number of days. Use startdate="today" to always start from the current date. (Maximum supported number of days in this view is 7.)

Deprecation notice: For backwards compatibility with earlier versions, view="currentweek" is also supported and works interchangeably. This support may be removed in a future version.

List View

To display upcoming events as a plain list on all screen sizes (which you can style with your own CSS), add view="list" to the shortcode, with the optional count="5" parameter to indicate the number of events to display. (By default, all upcoming events will be displayed.)

By default list view will display dates in the U.S. standard day-month-date format (e.g. “Thursday March 14”). To customize the format to your locale, you can use standard PHP date format strings with the format parameter. For example, to use the day-month format (e.g. “14 March”), use format="j F", or for an abbreviated numbered month/day format (e.g. “Thu 3/14”), use format="D n/j".

Note: The count parameter are supported in list view only. The format parameter is supported in list view, and on the mobile breakpoint only for week and month views. The startdate parameter is supported in week view only.

Event Attachments

Use the attach="true" parameter to display attachments with events. Attachments that are browser-friendly images (e.g. JPEG or PNG) will display directly on the page along with the event’s description. Other attachments will display as a clickable download link. Note for Google Calendar users: Google Calendar handles all attachments as links to a Google Drive page, not direct file links, so images are treated as downloads. We hope to resolve this issue in a future update.

Event Descriptions

Use the eventdesc="true" parameter to display event descriptions. Note: In the month view, descriptions will display on hover; in the list view, descriptions will display in full on the page below the event title (and location/organizer, if shown). In the list view, you can choose to display an excerpt of the description by entering the number of words to show, e.g. eventdesc="12". Clicking the excerpt will reveal the full description. Other views always shows the full description.

Event Locations

Use the location="true" parameter to display event locations (if available). Note: In the month view, locations will display on hover; in the list view, locations will display in full on the page below the event title.

Event Organizers

Use the organizer="true" parameter to display event organizer (if available). Note: In the month view, organizers will display on hover; in the list view, locations will display in full on the page below the event title (and location, if shown).

Event URLs (Links)

If the event data contains a URL, the URL can be added to the display as a clickable link in one of two ways. Use the linktitles="true" parameter to make the event title into a clickable link to that URL. If linktitles is not used, and eventdesc="true" is used, then the URL will be displayed as a clickable link after the event description. These links will always open in a new tab/window. If you do not wish to have event URL links appear at all, use nolink="true".

Feed Color Coding

You can apply a color to events in your feed by using the color parameter. This is especially helpful if you have multiple feeds and you want to use color coding to distinguish the feeds within your calendar. Add hex color values to this parameter and they will be applied to your feeds in the same order as the feeds are entered in the url parameter. For example, if you have three feeds and you want to color them purple, green and orange, you could use color="#800080 #008000 #ffa500". The base color will be used as a left border on each event, and a lighter tint of that color will be used as the background on the events. Use a tool like the HTML Color Picker to select hex values, if necessary. (Note: the color parameter supports either space- or pipe-delimited lists.)

Feed Color Coding Legend

The legendposition and legendstyle parameters control the placement and display format of the legend. Use legendposition to determine where to display the legend relative to the calendar. Valid values are "above" and "below". If omitted or an invalid value, will default to above. Use legendstyle to determine how to display the legend. Valid values are "block", "inline" and "none". If omitted or an invalid value, will default to block.

Feed Labels

By default, each calendar in the color key will be labeled using the title provided in that calendar’s feed. You can override the titles by using feedlabel. Note that because feed labels may need to contain spaces, the values for this parameter are pipe-delimited | rather than space-delimited. You can provide custom labels for some feeds and use the default titles as labels for others. For example, if you had three feeds and wanted to keep the default title for the second one, you could use feedlabel="Calendar Label 1||Calendar Label 3". (Note two pipes together; this is leaving the second delimited value empty.)

Mask Event Details

In some cases, such as for vacation rental availability, you may not want to show any event details, but simply block out days and times. Use maskinfo="MASK", replacing MASK with the text you wish to display in place of the event title. Event details, location and organizer will also be hidden automatically, regardless of any other settings.

Month Navigation Options

By default, the month view shows a dropdown (select) menu to navigate available months. Add monthnav with a value of select, arrows, both or compact (both, inline without header) to change how this is displayed. Applies to month view only.

Month/Year Format

Headers and dropdowns that display a month and year (e.g. “March 2020”) can be customized using formatmonthyear="F Y", replacing F Y with a PHP date format string of your choice. Note: This option only supports month and year characters (F, m, M, n, Y, y), plus spaces, hyphens, periods and slashes. All other formatting characters will be stripped from the output.

Time Display

By default, start times are always displayed, and end times are displayed on hover. To hide all times (for instance, if the times are also in your event description), add the hidetimes="true" parameter. Conversely, to always display end times (not just on hover), add the showendtimes="true" parameter.

Custom Options

If you are writing your own custom code to extend the plugin’s functionality, use customoptions to create your own configuration options for the shortcode. The value passed in this attribute is automatically converted into an array using the pipe character | as a delimiter. (Note that if no pipes are present in the value, it will still be converted into an array with one node.)

Debugging

By default the plugin uses WordPress transients to cache parsed calendar data for one hour. This improves performance and avoids exceeding request limits that may be set on your calendar server. To temporarily bypass this caching while testing configuration changes, use reload="true". Please note: you should only use this feature when you need to force a reload for testing purposes. Do not leave this setting on permanently, especially if your site receives a large amount of traffic.

Use debug="true" to turn on the debugger. Only Administrator-level users will see debugging code. When turned on, a panel will appear at the bottom of the screen with a raw dump of the ICS data array, and possibly additional debugging information.

Extend Multi-Day Events

Per the iCalendar specification, the DTEND value on all-day events is the first free date in the range, i.e. the date after the event finishes. By default, multi-day all-day events are handled this way. If your feed includes multi-day all-day events that should include the date specified by DTEND, add extendmultiday="true" to your shortcode.

Hide “All Day” Indicator

By default, an “ALL DAY” label appears above all-day events in the display. You can set hidealldayindicator="true" to prevent displaying this label.

Limit Days

By default, the plugin limits the displayed date range to the farthest future event in your feed. Use limitdays="NUMBER" to override the default limit. Replace NUMBER with your desired number of days. Note: If your calendar has a very large number of events, setting this value above 365 may affect performance.

Method

The method attribute can be used to force the plugin to only try retrieving the ICS feed via either cURL or fopen. By default, the plugin tries cURL first and then falls back on fopen. In cases where cURL fails, but with a long timeout, you can use method="fopen" in the shortcode to bypass cURL. This can significantly improve page load times for calendars that experience this issue with cURL receiving an HTTP 500 error from the calendar server. Conversely, if you only want to load the feed via cURL, and not allow the fopen fallback, use method="curl" in your shortcode.

“No Mobile”

The standard treatment for month and week views on mobile is to stack the display in a list style, because the grid does not work well scaled to the small size of a mobile display. However, if you wish to retain the grid, add nomobile="true" to your shortcode. Note that you will probably need to add your own custom CSS to make this display usable. Be sure to wrap your CSS in @media screen and (max-width: 782px) { } and use .ics-calendar.nomobile .ics-calendar-month-grid in your CSS selectors.

Past Days

By default, list and month views do not include past dates (before the first of the current month, in month view) unless startdate is used to set an arbitrary start date. You can also set a rolling start by using pastdays="NUMBER" where NUMBER is replaced with the number of days back you wish to begin. For instance, to show 3 previous months you could enter pastdays="90". This option has no effect in week view. Note: You may need to make adjustments to the `limitdays` option when this is used, as it calculates from the first displayed date, not the current date.

Recurrence

By default, the plugin will show all instances of recurring events that fall within the displayed date range of your calendar. Add the skiprecurrence="true" parameter to skip parsing recurring events. Use of this setting is discouraged in most cases, as it will prevent recurring events from displaying; however it may be useful for improved performance with extremely large calendars, if recurrences are not needed.

Version 7.0 introduced recurrence frequency messages in the event description block. You can hide these using hiderecurrence="true", or you can hide specific frequency types by entering one or more pipe-delimited frequencies to hide, e.g. hiderecurrence="yearly" or hiderecurrence="yearly|monthly".

Timezone Override (new in version 6)

Version 6 introduces a new way of parsing date/time values from the feed that allows for timezone overrides. By default, the feed will display events with times adjusted for the local timezone configured under Settings > General > Timezone. You can override the site’s timezone for individual feeds by adding the tz="TIMEZONE" parameter. You must use a valid named timezone value or the setting will be ignored and the site’s local timezone setting will be used. If your calendar is displaying multiple feeds, you can assign each a separate timezone override, as with feed labels or colors, by entering multiple values, pipe-delimited, in the same order as the feeds in the url parameter, e.g. tz="America/New_York|Europe/London|Pacific/Auckland". If you have multiple feeds but all are in the same timezone, you only need to enter the timezone once.

attach

Use the attach="true" parameter to display attachments with events. Attachments that are browser-friendly images (e.g. JPEG or PNG) will display directly on the page along with the event’s description. Other attachments will display as a clickable download link. Note for Google Calendar users: Google Calendar handles all attachments as links to a Google Drive page, not direct file links, so images are treated as downloads. We hope to resolve this issue in a future update.

color

You can apply a color to events in your feed by using the color parameter. This is especially helpful if you have multiple feeds and you want to use color coding to distinguish the feeds within your calendar. Add hex color values to this parameter and they will be applied to your feeds in the same order as the feeds are entered in the url parameter. For example, if you have three feeds and you want to color them purple, green and orange, you could use color="#800080 #008000 #ffa500". The base color will be used as a left border on each event, and a lighter tint of that color will be used as the background on the events. Use a tool like the HTML Color Picker to select hex values, if necessary. (Note: the color parameter supports either space- or pipe-delimited lists.)

columnlabels

By default the grid’s column labels will be the full names of the days of the week. For tighter layouts you can add columnlabels="short" to use 3-letter abbreviations, or columnlabels="min" to use 1- or 2-letter abbreviations. (The full day names and abbreviations are in the plugin’s translation files for all supported languages.) Applies to month and week views only.

count

Number of events to display, e.g. count="5". By default, all upcoming events will be displayed. Applies in list view only.

customoptions

If you are writing your own custom code to extend the plugin’s functionality, use customoptions to create your own configuration options for the shortcode. The value passed in this attribute is automatically converted into an array using the pipe character | as a delimiter. (Note that if no pipes are present in the value, it will still be converted into an array with one node.)

debug

Use debug="true" to turn on the debugger. Extended debugging output is available by setting debug="2". Only Administrator-level users will see debugging code. When turned on, a panel will appear at the bottom of the screen with a raw dump of the ICS data array, and possibly additional debugging information. When debugging you may also want to set reload="true" to reload the feed on each page load.

description

Text string to display as a general description of the calendar. Displays above the calendar, just below title. If omitted, the feed’s description will display (if any). Use "false" to display no description.

eventdesc

Use the eventdesc="true" parameter to display event descriptions. Note: In the month view, descriptions will display on hover; in the list view, descriptions will display in full on the page below the event title (and location/organizer, if shown). In the list view, you can choose to display an excerpt of the description by entering the number of words to show, e.g. eventdesc="12". Hovering over the shortened description will show the full description in a tooltip. Month view always shows the full description.

extendmultiday

Per the iCalendar specification, the DTEND value on all-day events is the first free date in the range, i.e. the date after the event finishes. By default, multi-day all-day events are handled this way. If your feed includes multi-day all-day events that should include the date specified by DTEND, add extendmultiday="true" to your shortcode.

feedlabel

By default, each calendar in the color key will be labeled using the title provided in that calendar’s feed. You can override the titles by using feedlabel. Note that because feed labels may need to contain spaces, the values for this parameter are pipe-delimited | rather than space-delimited. You can provide custom labels for some feeds and use the default titles as labels for others. For example, if you had three feeds and wanted to keep the default title for the second one, you could use feedlabel="Calendar Label 1||Calendar Label 3". (Note two pipes together; this is leaving the second delimited value empty.)

format

By default list view will display dates in the U.S. standard day-month-date format (e.g. “Thursday March 14”). To customize the format to your locale, you can use standard PHP date format strings with the format parameter. For example, to use the day-month format (e.g. “14 March”), use format="j F", or for an abbreviated numbered month/day format (e.g. “Thu 3/14”), use format="D n/j".

formatmonthyear

In places where the month and year are displayed without the day number (e.g. headers and month selection dropdown menu in month view), the default format is F Y (e.g. “March 2020”). Use the formatmonthyear parameter with PHP date format strings to customize the display. Note: This option only supports month and year characters (F, m, M, n, Y, y), plus spaces, hyphens, periods and slashes. All other formatting characters will be stripped from the output.

hidealldayindicator

Hides the “ALL DAY” label that appears above all-day events.

hiderecurrence

Version 7.0 introduced recurrence frequency messages in the event description block. You can hide these using hiderecurrence="true", or you can hide specific frequency types by entering one or more pipe-delimited frequencies to hide, e.g. hiderecurrence="yearly" or hiderecurrence="yearly|monthly".

hidetimes

By default, start times are always displayed, and end times are displayed on hover. To hide all times (for instance, if the times are also in your event description), add the hidetimes="true" parameter.

legendinline

Deprecated. Use legendstyle="inline" instead.

legendposition

Determines where to display the legend relative to the calendar. Valid values are "above" and "below". If omitted or an invalid value, will default to above.

legendstyle

Determines how to display the legend. Valid values are "block", "inline" and "none". If omitted or an invalid value, will default to block.

limitdays

By default, the plugin limits the displayed date range to the farthest future event in your feed. Use limitdays="NUMBER" to override the default limit. Replace NUMBER with your desired number of days. Note: If your calendar has a very large number of events, setting this value above 365 may affect performance.

linktitles

If the event data contains a URL, the URL can be added to the display as a clickable link in one of two ways. Use the linktitles="true" parameter to make the event title into a clickable link to that URL. If linktitles is not used, and eventdesc="true" is used, then the URL will be displayed as a clickable link after the event description. These links will always open in a new tab/window. If you do not wish to have event URL links appear at all, use nolink="true".

location

Use the location="true" parameter to display event locations (if available). Note: In the month view, locations will display on hover; in the list view, locations will display in full on the page below the event title.

maskinfo

In some cases, such as for vacation rental availability, you may not want to show any event details, but simply block out days and times. Use maskinfo="MASK", replacing MASK with the text you wish to display in place of the event title. Event details, location and organizer will also be hidden automatically, regardless of any other settings.

method

The method attribute can be used to force the plugin to only try retrieving the ICS feed via either cURL or fopen. By default, the plugin tries cURL first and then falls back on fopen. In cases where cURL fails, but with a long timeout, you can use method="fopen" in the shortcode to bypass cURL. This can significantly improve page load times for calendars that experience this issue with cURL receiving an HTTP 500 error from the calendar server. Conversely, if you only want to load the feed via cURL, and not allow the fopen fallback, use method="curl" in your shortcode.

monthnav

By default, the month view shows a dropdown (select) menu to navigate available months. Add monthnav with a value of select, arrows, both or compact (both, inline without header) to change how this is displayed. Applies to month view only.

nolink

Suppresses display of event links. Useful if your calendar feed automatically inserts a default link on all events that you do not wish to display along with the event description.

nomobile

The standard treatment for month and week views on mobile is to stack the display in a list style, because the grid does not work well scaled to the small size of a mobile display. However, if you wish to retain the grid, add nomobile="true" to your shortcode. Note that you will probably need to add your own custom CSS to make this display usable. Be sure to wrap your CSS in @media screen and (max-width: 782px) { } and use .ics-calendar.nomobile .ics-calendar-month-grid in your CSS selectors.

organizer

Use the organizer="true" parameter to display event organizer (if available). Note: In the month view, organizers will display on hover; in the list view, locations will display in full on the page below the event title (and location, if shown).

pastdays

By default, list and month views do not include past dates (before the first of the current month, in month view) unless startdate is used to set an arbitrary start date. You can also set a rolling start by using pastdays="NUMBER" where NUMBER is replaced with the number of days back you wish to begin. For instance, to show 3 previous months you could enter pastdays="90". This option has no effect in week view. Note: You may need to make adjustments to the `limitdays` option when this is used, as it calculates from the first displayed date, not the current date.

reload

By default the plugin uses WordPress transients to cache parsed calendar data for one hour. This improves performance and avoids exceeding request limits that may be set on your calendar server. To temporarily bypass this caching while testing configuration changes, use reload="true". Please note: you should only use this feature when you need to force a reload for testing purposes. Do not leave this setting on permanently, especially if your site receives a large amount of traffic.

showendtimes

By default, start times are always displayed, and end times are displayed on hover. To always display end times (not just on hover), add the showendtimes="true" parameter.

skip

Add the skip="NUMBER" parameter in conjunction with the count parameter in list view to split a calendar across multiple shortcodes within a page (e.g. a multi-column layout). This NUMBER of events will be skipped in display. Should match the sum of the count value(s) from previous shortcode(s) on the page for the same feed.

skiprecurrence

Add the skiprecurrence="true" parameter to skip parsing recurring events. Use of this setting is discouraged in most cases, as it will prevent recurring events from displaying; however it may be useful for improved performance with extremely large calendars, if recurrences are not needed.

startdate

By default, the calendar display will start from the current date. To have the calendar start from an arbitrary date (either in the future or the past), use this parameter with the date in an 8-digit "YYYYMMDD" format.

title

The title parameter is optional. If omitted, the title provided by the calendar feed will be displayed. Use “false” (e.g. title="false") to hide the title altogether.

toggle

If your event descriptions are long, you may wish to use toggle="true" to turn on click-to-toggle for descriptions. Users can click an event’s title to view its description. Applies in list view only. Deprecated: Use eventdesc="NUMBER" instead to show a short description excerpt that will show the full description on click. This feature will be removed in a future update.

tz

Version 6 introduces a new way of parsing date/time values from the feed that allows for timezone overrides. By default, the feed will display events with times adjusted for the local timezone configured under Settings > General > Timezone. You can override the site’s timezone for individual feeds by adding the tz="TIMEZONE" parameter. You must use a valid named timezone value or the setting will be ignored and the site’s local timezone setting will be used. If your calendar is displaying multiple feeds, you can assign each a separate timezone override, as with feed labels or colors, by entering multiple values, pipe-delimited, in the same order as the feeds in the url parameter, e.g. tz="America/New_York|Europe/London|Pacific/Auckland". If you have multiple feeds but all are in the same timezone, you only need to enter the timezone once.

url

The ICS subscription URL for your feed. This must be a subscription URL, not a URL that displays your calendar in a web view. (Loading the URL directly in your browser’s address bar should download an .ics file.) Enter multiple URLs, space- or pipe-delimited, to combine multiple feeds into one calendar display.

view

Determines which layout to use. View options included in the base plugin are "month", "week" and "list". Month view is the default, and this parameter can be omitted entirely. See View/Layout Options for more details about each view. Additional view options are available in the Pro version, and a future update will provide support for building your own custom views.

ICS Calendar includes a number of hooks that are used by ICS Calendar Pro to extend its functionality. Many of these hooks are still in development and subject to change, but we will document them here as they become available for theme and add-on developers’ use.

add_filter('r34ics_display_calendar_exclude_event', function($exclude, $event, $args) {
    // Add your logic to determine whether or not to exclude this event (set $exclude value)
    return $exclude;
}, 10, 3);

add_filter('r34ics_display_calendar_filter_ics_data', function($ics_data) {
    // Add your logic to manipulate the data array
    return $ics_data;
}, 10, 1);

Here’s another practical example, showing how you can manipulate the deeply nested data within the $ics_data array. Say a large number of your calendar’s events have the same text string in their title (“label”), for example, “Acme Widgets, Inc.” You could strip that text out of all of the event labels that contain it with the following code:

add_filter('r34ics_display_calendar_filter_ics_data', function($ics_data) {
	$delete_string = 'Acme Widgets, Inc.';
	foreach ((array)$ics_data['events'] as $year => $months) {
		foreach ((array)$months as $month => $days) {
			foreach ((array)$days as $day => $times) {
				foreach ((array)$times as $time => $events) {
					foreach ((array)$events as $key => $event) {
						if (strpos($event['label'], $delete_string) !== false) {
							$ics_data['events'][$year][$month][$day][$time][$key]['label'] = str_replace($delete_string, '', $event['label']);
						}
					}
				}
			}
		}
	}
return $ics_data;
}, 10, 1);

add_filter('r34ics_display_calendar_preprocess_raw_feed', function($ics_contents, $range_start, $range_end, $args) {
    // Add your logic to manipulate the raw ICS feed contents
    return $ics_contents;
}, 10, 4);