Developer

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

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_action('r34ics_day_classes', function($classes, $args) {
    // Add your code to modify $classes array
    return $classes;
}, 10, 2);

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 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 is “Booked” or “Available”.

add_action('r34ics_event_css_classes', function($classes, $event, $time, $args) {
    if ($event['label'] == 'Available') {
        $classes[] = 'available';
    }
    elseif ($event['label'] == 'Booked') {
        $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;
}

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

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