Developer

ICS Calendar includes a number of hooks that were created primarily to allow 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.

Where do I put this code? We do not recommend making these types of changes unless you have at least a basic understanding of working with PHP. If you are comfortable directly editing files, these changes should generally be made in your theme’s functions.php file. Important: If you are using a third-party theme, you should not edit the files directly, as any automated updates will overwrite your changes. Create a child theme or custom plugin instead.

Actions

`r34ics_event_description_html`

Append your own dynamically-generated content to event descriptions in the calendar display.

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

`r34ics_event_label_html`

Append your own dynamically-generated content to event labels (titles) in the calendar display.

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:

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

`r34ics_event_sublabel_html`

Append your own dynamically-generated content to event sub-labels (small text inserted under event labels) in the calendar display.

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:

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

Filters

`http_request_host_is_external`

Use this core WordPress filter to allow ICS Calendar to access feed URLs on an internal network (private/reserved IP addresses).

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

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

`r34ics_day_classes`

Conditionally add your own custom CSS classes to the day container in table-based views.

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.

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

`r34ics_display_calendar_args`

Write your own logic to set the values for shortcode attributes dynamically.

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:

$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;
}

`r34ics_display_calendar_exclude_event`

Add conditional logic to exclude individual events from display.

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

`r34ics_display_calendar_filter_ics_data`

Loop through the entire parsed array of events and modify the contents prior to display.

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.

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 newer versions of the plugin the situation described here could be dealt with more effectively using r34ics_event_label_html_filter.

`r34ics_display_calendar_preprocess_raw_feed`

Manipulate the raw iCalendar feed data, prior to parsing by the ics-parser library.

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.

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

`r34ics_event_css_classes`

Conditionally add your own custom CSS classes to events in the calendar.

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.

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.

`r34ics_event_description_html_filter`

Modify the default output of event descriptions, using dynamic data.

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.

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

`r34ics_event_label_html_filter`

Modify the default output of event label (title), using dynamic data.

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.

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

`r34ics_event_sublabel_html_filter`

Modify the default output of event sub-label, using dynamic data.

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.

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

Functions

`r34ics_get_ics_data`

Retrieve the fully parsed calendar data as an array, without generating template output.

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.

jQuery

ICS Calendar version 10.10.0 introduces custom jQuery events, allowing you to write your own callback functions to fire off immediately before or after ICS Calendar initializes. These work similarly to WordPress hooks (actions and filters), but in jQuery. You can read more about the general concept here.

ICS Calendar includes a JavaScript function called r34ics_init(), which is fired off when the page first loads, but also after any AJAX calendar is loaded into the page. (Note that this means it fires multiple times if the page contains both regular and AJAX-loaded calendars, or if the page contains multiple AJAX-loaded calendars.)

The new jQuery events are called r34ics_init_start and r34ics_init_end, and as you may guess, they fire at the start and end of the function. (As of version 4.8.0, ICS Calendar Pro also includes its own corresponding events called r34icspro_init_start and r34icspro_init_end, which are contained in the r34icspro_init() function.)

How does it work?

Much like WordPress hooks, your code will enqueue to be fired off on the designated jQuery event. And also like WordPress hooks, your code must be enqueued before the event happens. Assuming your code relies on jQuery, the best approach is to write your code so it runs as soon as jQuery is available, but before the load event, which is when r34ics_init() is called.

Code Example

jQuery(function() {
    jQuery(document).on('r34ics_init_end', function() {
        // Your code goes here
    });
});

Where do I put this code?

Your custom jQuery that uses the new events should be placed inside a JavaScript file in your theme (often named script.js), or a custom plugin that enqueues a JavaScript file.

User Guide

On This Page

More Help

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

Input parameters:

Return value:

Example usage:

jQuery

How does it work?

Code Example

Where do I put this code?