Developer Resources

This action runs when the calendar data from your shortcode is fully parsed and ready to be rendered on the page. It allows you to use your own custom view template, rather than one of the provided views.

Input parameters:

$view
String. The name of your custom view. Should match standard file naming conventions (all-lowercase, no spaces).

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$ics_data
Array. The fully parsed set of calendar event data matching the parameters of the shortcode, organized hierarchically by year, month, day and time. Your template should loop through the array to render the events.

Return value:

None. Your function should include the template file, which will render output directly.

Example usage:

First, add the following code to your theme’s functions.php file:

function my_custom_ics_template($view, $args, $ics_data) {
    include(get_template_directory() . '/ics-calendar/calendar-' . $view . '.php');
}
add_action('r34ics_display_calendar_render_template', 'my_custom_ics_template', 10, 3);

Next, inside your theme, create a folder called ics-calendar and inside that folder, create a file called calendar-my-custom-view.php. (Replace my-custom-view with the name you’d like to use for your view.)

Once the file has been created, you can use it to render your calendar by referencing its unique name in your shortcode as such:

[ics_calendar view="my-custom-view" …]

Your template file has full access to the $args array, which is all of the parameters from the shortcode, and the $ics_data array, which is all of the parsed event data, organized hierarchically by year, month, day, time.

The best way to get started building your custom template is to make a copy of one of the existing ICS Calendar template files and modify it as needed. Especially good options for understanding the structure of the output are calendar-month.php if you want a table-based view, or calendar-basic.php if you want a list-based view.

For custom CSS, note that your calendar will have a wrapper element you can reference with the .ics-calendar.layout-my-custom-view selector.

Note: There are additional (currently undocumented) hooks inside the R34ICS::display_calendar() method that can be used to customize details such as the exact date range to be parsed from the ICS feed(s). Those hooks are not strictly necessary to create a custom view, but may be desirable for fine-tuning your view’s output.

This action runs immediately after the HTML content of the event description has been generated. Use this action to insert additional content inside the container element (e.g. the hover box) for the event description.

Note that this is an action that can insert additional content; it is not a filter that allows you to manipulate the default output. If you need to change the default output, please use the r34ics_event_description_html_filter filter instead.

Input parameters:

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$event
Array. All of the data for the current event. Use this array to get specific event details dynamically.

$classes
Array. The CSS classes that will be applied to the container element for the event description.

Return value:

None. Your function should echo any output directly.

Example usage:

add_action('r34ics_event_description_html', function($args, $event, $classes) {
    // Add your custom output to append to the event description
}, 10, 3);

This action runs immediately after the HTML content of the event label (i.e. title) has been generated. Use this action to insert additional content inside the container element for the event label (title).

Note that this is an action that can insert additional content; it is not a filter that allows you to manipulate the default output. If you need to change the default output, please use the r34ics_event_label_html_filter filter instead.

Input parameters:

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$event
Array. All of the data for the current event. Use this array to get specific event details dynamically.

$classes
Array. The CSS classes that will be applied to the container element for the event description.

Return value:

None. Your function should echo any output directly.

Example usage:

add_action('r34ics_event_label_html', function($args, $event, $classes) {
    // Add your custom output to append to the event label (title)
}, 10, 3);

This action runs immediately after the HTML content of the event sub-label has been generated. (The event sub-label is usually blank but sometimes includes elements such as a “carryover” symbol for events that end after midnight.) Use this action to insert additional content inside the container element for the event sub-label.

Note that this is an action that can insert additional content; it is not a filter that allows you to manipulate the default output. If you need to change the default output, please use the r34ics_event_sublabel_html_filter filter instead.

Input parameters:

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$event
Array. All of the data for the current event. Use this array to get specific event details dynamically.

$classes
Array. The CSS classes that will be applied to the container element for the event description.

Return value:

None. Your function should echo any output directly.

Example usage:

add_action('r34ics_event_sublabel_html', function($args, $event, $classes) {
    // Add your custom output to append to the event sub-label
}, 10, 3);

A security-focused change introduced in ICS Calendar 10.12.2 requires special use of this filter in order to access ICS feeds over an internal network — specifically, if your mail/calendar server’s URL resolves to an IP address in one of the private or reserved ranges.

Using this filter, site developers can write a function that defines a set of allowed hostnames, as such:

function my_http_request_host_is_external($external, $host, $url) {
	$allowed_hosts = array(
		'mail.example.com', // Add your allowed hosts to this array
	);
	if (in_array($host, $allowed_hosts)) { $external = true; }
	return $external;
}
add_filter('http_request_host_is_external', 'my_http_request_host_is_external', 10, 3);

Note: It is no longer necessary to write a custom function to use this filter; you can simply add your local hostnames into the Allow access to these hostnames that resolve to reserved IP addresses field on the ICS Calendar Settings page.

This filter is part of WordPress core. See the official WordPress Developer Resources for more information.

This filter runs when adding CSS classes to the day container (<td> tag) in table-based views. Use it to conditionally add your own custom CSS classes to the array.

Input parameters:

$classes
Array. The default classes are passed in by each individual view template.

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

Return value:

Array. The $classes array, including any modifications you’ve made.

Example usage:

add_filter('r34ics_day_classes', function($classes, $args) {
    // Add your code to modify $classes array
    return $classes;
}, 10, 2);

This filter allows you to hide the Add ICS Calendar button that appears in the Classic Editor above the WYSIWYG box.

By default the button displays. Use this filter with your own custom function if you want to restrict the button to only certain user roles, for instance, or use it with the built-in __return_false() function to hide the button for all users, as shown in the code example below.

Input parameters:

$display_button
Boolean. Whether or not to display the button.

Return value:

Boolean. Whether or not to display the button.

Example usage:

add_filter('r34ics_display_add_calendar_button', '__return_false');

This filter runs after ICS Calendar initially loads all of the attributes of the shortcode, prior to processing the feed. Use it to write your own conditional logic to set the values for the attributes.

Input parameters:

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$atts
Array. The initial, unvalidated attribute settings from the shortcode. Use this array if you need to access the unaltered shortcode attribute values, but in general you should rely on the values from the $args array.

Return value:

Array. The $args array, including any modifications you’ve made.

Example usage:

Here is a practical example of how to use this filter to dynamically set an attribute value. Specifically, it lets you create a front-end “reload” link, to allow users purge the calendar cache. (Please use this with caution; if your site depends on ICS Calendar’s caching for performance, giving users the ability to clear the cache at will can be dangerous.)

Note: This code assumes that you’ve added a link to your page that appends a ?reload=1 query string to the current URL.

For security purposes it does not use the value from the query string; it merely checks that it is set to a non-empty value.

Be sure to set the priority to 11 or higher, as shown here, to be sure your logic is processed after the logic built into ICS Calendar Pro.

add_filter('r34ics_display_calendar_args', 'my_r34ics_args', 11, 2);
function my_r34ics_args($args, $atts) {
	if (!empty($_GET['reload'])) {
		$args['reload'] = true;
	}
	return $args;
}

This filter was introduced in ICS Calendar v. 11.3.

This filter runs just before a fully parsed event gets added to the array of events for the displayed calendar. Use it to modify any event data as needed.

Input parameters:

$event_item
Array. The prepared array of event details, ready to go into the displayed calendar.

$event
Object. The original event object parsed out of the ICS feed. Use this if you need to access custom event data fields that are not already present in the $event_item array.

$args
Array. All attributes passed in the shortcode. Use this to determine the configuration of the shortcode.

Return value:

Array. $event_item, including any of your modifications.

Example usage:

add_filter('r34ics_display_calendar_event_item', function($event_item, $event, $args) {
	$delete_string = 'Acme Widgets, Inc.';
	if (strpos($event_item['label'], $delete_string) !== false) {
		$event_item['label'] = str_replace($delete_string, '', $event['label']);
	}
	return $event_item;
}, 10, 3);

Prior to version 11.3, similar modifications can be achieved with the r34ics_display_calendar_filter_ics_data filter, but it requires deeply nested foreach loops as shown in the second example code here.

This filter runs on the loop that parses events. Use it to write additional logic to determine whether or not an event should be displayed. Avoid redundant or processor-heavy logic in uses of the filter. (For example, if a query is being run, execute it outside of the filter and pass its results into the filter as global variable.)

Input parameters:

$exclude
Boolean. Indicates whether or not the event should be excluded from display.

$event
Object. The current event object from the loop. Use this to evaluate details of the event in your logic.

$args
Array. All attributes passed in the shortcode. Use this to determine the configuration of the shortcode. Include the customoptions attribute in your shortcode to introduce your own non-standard, pipe-delimited configuration options. Note: the plugin converts this attribute’s value into an array based on the pipe delimiter.

Return value:

Boolean. Used to determine whether or not to display the event.

Example usage:

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);

The $event object contains keys generated by the ICS Parser library, which in some case differ from the keys for the $event array that is generated later by ICS Calendar itself. The keys are lowercase equivalents to the all-uppercase keys in the raw ICS feed. So for example, the event’s title or “label” as referred to by ICS Calendar is the SUMMARY in the ICS feed. A conditional that would exclude events based on a text string in the SUMMARY would look like this:

add_filter('r34ics_display_calendar_exclude_event', function($exclude, $event, $args) {
    if (stripos($event->summary, 'Exclude Me') !== false) {
        $exclude = true;
    }
    return $exclude;
}, 10, 3);

This filter allows you to write your own customized code to manipulate the contents of the fully parsed ICS data array just prior to rendering the calendar output to the browser.

Input parameters:

$ics_data
Array. The full parsed data array. You may wish to turn on the debugger (add debug="1" to your shortcode) to see the structure of the array during development.

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

Return value:

Array. Be sure that your manipulations do not modify the overall structure of the array, or the calendar will not display properly.

Example usage:

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

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, $args) {
	$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, 2);

Note: For historical reasons this example is retained here in the documentation; however with version 11.3 and later, the situation described here could be dealt with more effectively using r34ics_display_calendar_event_item.

This filter allows pre-processing of raw ICS feed data, after loading and immediately before sending to ICS Parser library for parsing. Can be used by ICS Calendar Pro, or custom code in theme or external plugins, to modify the contents of the feed before parsing. An understanding of proper iCalendar syntax will be helpful in using this filter.

Input parameters:

$ics_contents
String. The raw contents of the ICS feed file retrieved directly from the feed URL.

$range_start
String. The rough start date for the range of dates to be parsed, in Y/m/d format.

$range_end
String. The rough end date for the range of dates to be parsed, in Y/m/d format.

$args
Array. All attributes passed in the shortcode. Use this to determine the configuration of the shortcode. Include the customoptions attribute in your shortcode to introduce your own non-standard, pipe-delimited configuration options. Note: the plugin converts this attribute’s value into an array based on the pipe delimiter.

Return value:

String. The modified value of $ics_contents. Be sure that any manipulations you make result in a string that still parses as valid iCalendar data.

Example usage:

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);

This filter runs when adding CSS classes to the event container (li.event in table-based views and dd.event in list view). Use it to conditionally add your own custom CSS classes to the array.

Input parameters:

$classes
Array. The default classes are passed in by each individual view template.

$event
Array. The subarray containing all of the details of the event currently being filtered.

$time
String. A specially formatted CSS class that is automatically added to each event, indicating its start time, in the format thhmmss. For example, an event starting at 9:00 AM would have a $time class of t090000.

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

Return value:

Array. The $classes array, including any modifications you’ve made.

Example usage:

Here is a specific example where you might apply different CSS classes to your events based on whether an event’s label (the SUMMARY field in the .ics file) contains “Booked” or “Available”.

add_filter('r34ics_event_css_classes', function($classes, $event, $time, $args) {
    if (strpos($event['label'], 'Available') !== false) {
        $classes[] = 'available';
    }
    elseif (strpos($event['label'], 'Booked') !== false) {
        $classes[] = 'booked';
    }
    return $classes;
}, 10, 4);

Then, in conjunction with this new filter, you might add the following CSS to your theme’s style.css file:

.ics-calendar .event.available {
    background: green;
}
.ics-calendar .event.booked {
    background: red;
}

You can use any key from the $event array in your conditional logic. Use the debug parameter to see the full array output. Note that for legacy code reasons, some array keys are different from the iCalendar spec. For example, as noted above, SUMMARY becomes $event['label']. Also, DESCRIPTION becomes $event['eventdesc'].

If you are using the color parameter to color-code your feeds, you’ll need to use !important with your CSS color specifications in the example code above, e.g.: background: green !important;

Note: This is a basic example written for clarity of intent; these background colors may not provide adequate contrast with your site’s text color.

This filter runs immediately after event description HTML has been prepared. Use it to modify the output of event descriptions. Be sure not to alter the outer HTML formatting of the output string, and make sure your alterations return valid, properly nested HTML.

Input parameters:

$descloc_content
String. This is the HTML output of the event description. Your filter should return a string that contains your modifications to this value.

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$event
Array. All of the data for the current event. Use this array to get specific event details dynamically.

$classes
Array. The CSS classes that will be applied to the container element for the event description.

$has_desc
Boolean. Indicates whether or not the event has a description.

Return value:

String. The $descloc_content string, including any modifications you’ve made.

Example usage:

add_filter('r34ics_event_description_html_filter', function($descloc_content, $args, $event, $classes, $has_desc) {
    // Add your code to modify the output HTML
    return $descloc_content;
}, 10, 5);

This filter runs immediately after event label (title) HTML has been prepared. Use it to modify the output of event labels. Be sure not to alter the outer HTML formatting of the output string, and make sure your alterations return valid, properly nested HTML.

Input parameters:

$label_content
String. This is the HTML output of the event label (title). Your filter should return a string that contains your modifications to this value.

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$event
Array. All of the data for the current event. Use this array to get specific event details dynamically.

$classes
Array. The CSS classes that will be applied to the container element for the event description.

Return value:

String. The $label_content string, including any modifications you’ve made.

Example usage:

add_filter('r34ics_event_label_html_filter', function($label_content, $args, $event, $classes) {
    // Add your code to modify the output HTML
    return $label_content;
}, 10, 4);

This filter runs immediately after event sub-label HTML has been prepared. Use it to modify the output of event sub-labels. Be sure not to alter the outer HTML formatting of the output string, and make sure your alterations return valid, properly nested HTML.

Input parameters:

$sublabel_content
String. This is the HTML output of the event sub-label. Your filter should return a string that contains your modifications to this value.

$args
Array. This is the collection of attribute settings, after they’ve been validated and processed by the plugin (for example, to scrub invalid values, and to explode pipe-delimited strings into arrays), that will be used to determine how your calendar is displayed.

$event
Array. All of the data for the current event. Use this array to get specific event details dynamically.

$classes
Array. The CSS classes that will be applied to the container element for the event description.

Return value:

String. The $label_content string, including any modifications you’ve made.

Example usage:

add_filter('r34ics_event_label_html_filter', function($sublabel_content, $args, $event, $classes) {
    // Add your code to modify the output HTML
    return $sublabel_content;
}, 10, 4);

This filter is for use in conjunction with r34icspro_illustration_path to allow you to add your own custom keywords to match illustrations to events.

The keys in this array, identified as {KEYWORD} in the example code below, should be the unique portion of filenames that match the format img_{KEYWORD}_2x.jpg and that are stored at the path you’ve defined with the r34icspro_illustration_path filter.

Input parameters:

$array
Array. This is the array of keywords, to which your custom keywords will be appended.

Return value:

Array. The modified array.

Example usage:

add_filter('r34icspro_calendar_illustration_keywords', function($array) {
    $array['filename-segment'] = array('keyword-1', 'keyword-2', 'keyword-3');
    return $array;
}, 10, 1);

This feature was introduced in ICS Calendar Pro version 4.11.0. It is still in beta and is subject to change. Currently only English-language calendars are supported.

If your source is Google Calendar, you can use this option to automatically insert Google’s keyword-based event illustrations in your calendar. You can also create your own set of illustrations to use with this feature, with a few specific details described below.

First, you must use the r34icspro_illustration_path filter to define the path to the directory on your site where the illustration images are stored. This can be a subdirectory of your Media Library or another folder outside of WordPress, but it must be a path under the same URL as your site, all of the images must be stored in the same folder, and they must be JPEG images with the following naming convention: img_{KEYWORD}_2x.jpg where {KEYWORD} exactly matches one of the keywords in the list below.

Display within ICS Calendar Pro templates is optimized for images with an 8:5 aspect ratio, e.g. 800 pixels wide by 500 pixels tall. (Google Calendar images are wider, but are deliberately designed with an area of solid color at one end; these images are dynamically cropped to an 8:5 aspect in the browser when used by ICS Calendar Pro.)

Note: The keywords in the filename are case-sensitive (must be all-lowercase), but the matching terms are not.

Example usage:

add_filter('r34icspro_illustration_path', function() {
    return 'wp-content/uploads/my-event-illustrations'; // Replace with a relative path under your site URL
});

Image filename keywords and matching terms

If an event includes any of the matching words or phrases in its title or description, the image with the associated keyword in its filename will be displayed.

This filter was added in ICS Calendar 11.2.0. Custom add-ons that define their own templates must now use this filter to add those template names to the array of valid views.

Previous to the introduction of this filter, if a shortcode’s view parameter contained the name of a view template that did not exist, the calendar would simply not display. Now, the designated view is validated against a list of registered views, and if it is not in the list, the calendar will default to month view.

If you’ve created your own custom templates, you’ll need to add the name of the view to this list. Note that the filename is assumed to be calendar-[VIEW_NAME].php, or as in the example code shown below, calendar-my-custom-view.php.

Example usage:

add_filter('r34ics_views', function($views) {
    $views[] = 'my-custom-view'; // Replace with the name of your view
    return $views;
});

This function provides a way for developers to access the fully parsed $ics_data array ICS Calendar creates, just prior to generating template output. It is useful if you need to retrieve and manipulate calendar data, without displaying directly as the shortcode does, or if you need to access the data in your template before the shortcode appears.

Keep in mind that there is a performance cost for loading and parsing ICS data. This function does use the same WordPress transient-based caching as the shortcode, but each unique set of arguments passed to the function is parsed and cached separately. Avoid calling this function more than once per page load.

Input parameters:

$args
Array. The keys in this array are identical to the attributes used in the ICS Calendar shortcode.

Return value:

Array. This is the same $ics_data array generated by the shortcode and used in template output. Parsed event data is contained in the $ics_data['events'] subarray.

Example usage:

$ics_data = r34ics_get_ics_data(array(
    'limitdays' => 455,
    'pastdays' => 90,
    'url' => 'https://example.com/calendar.ics',
));
// Your code that relies on $ics_data goes here

Note: Some ICS Calendar shortcode parameters only apply to specific views (and may, in fact, only be referenced in the view templates themselves), therefore using them with this function will have no effect on the output. For example, the pagination parameter is only used in the List view template, and will not have any effect on the output of this function.