FAQs and Tips

Apple recently made server configuration changes that are requiring some users to re-share their calendar feeds and update the URL in their ICS Calendar shortcodes. You can find out more in the WordPress support forums, and read Apple’s support page for sharing your iCloud calendar.

By default, the Block Editor starts each new block as a Paragraph block. If you type your shortcode directly into a Paragraph block, WordPress recognizes that it’s a shortcode, but it does weird things with the feed URL, and your calendar will come up blank.

Be sure you are using a Shortcode block. To do that, when you start a new block and see this text:

Type / to choose a block

Type /shortcode to select a shortcode block, as shown in the video clip below.

All jokes aside, it’s a legitimate question: Why does ICS Calendar cache the feed data?

There are a couple of reasons:

1. Performance. When ICS Calendar initially retrieves your calendar, it has to contact the source calendar server, wait for its response, parse out that response into a format it can work with, and then build your calendar. Under optimal conditions this can be almost instantaneous, but there are a number of potential bottlenecks, and since it can only retrieve the feed when the page is requested, your site visitors may have to wait for all of this to happen.
2. Access limits. Many source calendars have access limits — they’ll only respond to the same IP address a certain number of times within a given time frame. If your calendar page gets a lot of traffic, and if the page was requesting the feed from the source for every one of those hits, you’ll reach your access limit quickly, and then no one will be able to see the calendar until the source server stops throttling your access.

By default ICS Calendar caches data for one hour, which means that it will only request the feed from the source at most that often. The cache includes both the raw feed data — useful if you have the same feed displayed in multiple different shortcodes — and the parsed data for each individual instance on your site.

You can change the duration of the cache for individual shortcodes by using the reload parameter, or on your entire site with the Transient (cache) expiration setting on the ICS Calendar admin page.

What about other caching plugins? If your site is using another caching plugin, there may be a compound effect of the caching, and your calendar may not update for days, or ever. There are three potential fixes:

1. Turn off ICS Calendar caching. This is done by setting either the reload shortcode parameter or the Transient (cache) expiration to 1.
2. Configure the other caching plugin to exclude the page your calendar is on. Some caching plugins let you specify certain pages to exclude from the cache, but this is not always an option.
3. Use the AJAX parameter. When you add ajax="1" to your shortcode, ICS Calendar does not load the calendar data directly within the page HTML (which is what causes it to be caught by external caching); instead it uses AJAX to dynamically load the calendar data into the page after it is rendered. These AJAX calls are generally not affected by caching plugins.

If your calendars are displaying outdated information, or if you’ve recently added new events to your source calendar that aren’t displaying on the site, you may need to clear the calendar data cache.

Both the free and Pro versions have a utility to clear the calendar cache. Just click a button and the caches will clear, forcing any calendars on your site to immediately reload fresh calendar data.

In the free version, click ICS Calendar in the admin sidebar. In the Pro version, navigate to ICS Calendar > Settings & Tools > Admin. Then click the Clear Cached Calendar Data button.

If you’re using a caching plugin like LiteSpeed Cache, you may notice your calendar isn’t updating. This is because, by default the caching plugin is caching your entire page, including the contents of the calendar.

To address the issue of caching plugins/caching servers preventing the calendar from updating, version 10.3 introduces the ajax parameter. By adding ajax="true" to your shortcode, the HTML within your page will only include a simple placeholder tag for the calendar, and ICS Calendar’s new AJAX functionality will dynamically load the calendar after the initial page render.

See the ajax documentation for more.

Note: In some configurations, LiteSpeed may cache AJAX requests. If you find that your calendar intermittently fails to load when using AJAX with LiteSpeed, try adding admin-ajax.php to the list of exclusions in your LiteSpeed Cache configuration, as shown in the screenshot below.

If you’ve tried all of our other troubleshooting techniques, and your calendar still isn’t updating, check with your hosting provider to see if they are doing any caching at the server level.

Related to this, if your site is on a load balancer, it’s possible that the servers are out of sync. (That is, ICS Calendar data may have been updated on one of the load balancing servers, but your request is being handled by another.) If your host offers a way to trigger a load balancer re-sync, give it a try.

ICS Calendar Pro includes a pre-caching option to retrieve and parse your feed data in the background, helping large calendars to load faster when users visit your site.

But, sometimes it may not seem to be doing anything. And that’s probably because it isn’t.

To understand why, you need to know that any kind of “scheduled tasks” that WordPress does, such as this pre-caching, are managed by something called WP-Cron.

“Cron” is a utility on Unix/Linux servers that lets admins schedule tasks to run automatically at designated intervals. If you tell a backup script to run at 3:42 AM every day, it will run, without fail, at 3:42 AM every day.

WP-Cron, in principle, works the same way. But because WP-Cron is part of WordPress, it works the way a web site works. Web sites are passive applications. They respond to requests. That’s it. They can’t do anything on their own. So a task scheduler like WP-Cron relies on users visiting your site at semi-regular intervals.

A user visiting the site causes WordPress to jump into action. And one of the last things WordPress does before it closes each request is check to see if there are any pending WP-Cron tasks that it needs to run.

If your site is not receiving a relatively constant stream of traffic, these WP-Cron tasks can become overdue. They’ll still run whenever a user visits the site, but they’ll be late.

What does this have to do with pre-caching my calendars?

Since WP-Cron is not only limited to running when a user visits a page of your website, but because it also runs as the last thing WordPress does on the request (so as not to slow down the response to the user), if the pre-caching WP-Cron task is overdue, and the page that user visits contains the calendar, the calendar won’t be cached, and the user will have to wait for it to process.

There’s no other way for a plugin like ICS Calendar Pro to initiate a scheduled task, and there’s no way around this limitation of WP-Cron. Well, OK, there is one way.

Hooking WP-Cron Into the System Task Scheduler

By setting up a real cron job on your server’s operating system that makes the WP-Cron request on regular intervals, you can effectively turn WP-Cron into a true cron event, and get the scheduled tasks, including ICS Calendar Pro’s pre-caching, to run automatically, without a user having to visit your site first.

In short, if your site receives a low amount of traffic (typically less than one visitor per hour), and especially if the majority of that traffic goes to the page your calendar is on, you’ll probably need to set up a system task for WP-Cron to see any benefit from ICS Calendar Pro pre-caching.

This question mainly pertains to the two most widely used source calendars: Google Calendar and Microsoft Office 365/Outlook.

Unfortunately, neither Google nor Microsoft includes the event color (Google) or category (Microsoft) in the data they provide in ICS feeds, and there is no setting within either of their systems to add this to the feed.

Since ICS Calendar is strictly relying on the content of your feeds, and does not connect directly to your Google or Microsoft account, it can only work with the data provided in the feed.

CATEGORIES is a supported field in the iCalendar specification, so we are hopeful that Microsoft may add this option in the future, however it seems at this point that is unlikely.

Some other source calendars do provide support for the CATEGORIES field, and as of version 9.4.1, ICS Calendar adds a data-categories attribute to the HTML for events that contain this data. Presently this allows you to write your own custom CSS and jQuery code to manipulate the appearance of these events; a future ICS Calendar update will enhance this functionality further.

As of version 11.5.2, we have also introduced the category shortcode parameter. This provides an easy way to filter your feed to only include events from one or more categories.

There is a potential compatibility issue when using ICS Calendar in conjunction with certain other plugins, e.g. Directorist, where the plugin runs its output through wp_kses_post() or a similar string escaping function.

In these cases, ICS Calendar’s select and option tags will get stripped from the output, causing the month dropdown menu not to render properly, among other functionality issues. This can be resolved by adding the following code to your theme’s functions.php file, or to a custom plugin.

function my_pre_kses_filter($string) {
	global $allowedposttags;
	$allowedposttags['select'] = array(
		'class' => true,
		'autocomplete' => true,
		'data-this-month' => true,
	);
	$allowedposttags['option'] = array(
		'value' => true,
		'selected' => true,
	);
	return $string;
}
add_filter('pre_kses', 'my_pre_kses_filter', 10, 1);

ICS Calendar Pro includes a set of tools for the WordPress Customizer (Appearance > Customize > ICS Calendar Pro in the WP admin) that let you change the colors of your calendar to either one of our preset color palettes or to any colors you choose, along with tools to change your font, text size, and various other layout details.

Beyond these settings in Pro, both versions allow you to customize your appearance using CSS. We have made a concerted effort to use a consistent set of CSS classes throughout the ICS Calendar templates, allowing users with a general understanding of CSS coding to modify the calendar appearance extensively.

See our CSS Guide for a list of the CSS classes built into ICS Calendar. We recommend using the “inspector” in your browser’s developer tools to learn all of the details of the CSS classes. Your CSS overrides can be placed directly into your theme’s CSS files or entered in the Customizer (Appearance > Customize > Additional CSS).

As a head start, please note that the entire ICS Calendar output is wrapped inside a <section> tag with the .ics-calendar class. Inside that container, each view has a class that is used to wrap the iterations of its output, e.g. the month view puts each individual month into an <article> tag with the .ics-calendar-month-wrapper class. The wrapper for list view uses .ics-calendar-list-wrapper and so on.

This truly is one of the most frequently asked questions about ICS Calendar Pro’s Calendar Builder: How do I duplicate a calendar?

Since ICS Calendar Pro’s saved calendars are really just a WordPress Custom Post Type, they’ll work with any standard post duplicator plugin that is capable of copying CPTs, including all of their custom field data. That’s also the reason we haven’t included this functionality in the plugin directly… it’s a fairly complex operation that is already handled really well by a handful of other, free plugins.

We like Yoast Duplicate Post, and have verified that it works seamlessly with the Calendar Builder.

When you install Yoast Duplicate Post, you’ll need to give it permission to work on the Calendar Builder custom post type. Go to Settings → Duplicate Post, click the Permissions tab, and tick the Calendar Builder checkbox. If you’re using ICS Events you may want to tick that box as well.

In fact, Yoast Duplicate Post almost works too well. The one caveat we have is that it duplicates a value that really needs to be unique: the ID Attribute field, under the Advanced tab. We’ve built in some safeguards to prevent duplicate id attributes if multiple calendars are included on the same page, but we still recommend that you make sure to manually edit the ID Attribute to be something unique whenever you copy a saved calendar.

Whenever possible, the plugin relies on your site’s general settings (Settings > General) to determine display parameters. Specifically: Site Language, Timezone, 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.

Day and month names are automatically translated into the designated Site Language. Likewise, table-style calendars will always use Week Starts On, and times will always use Time Format. These general settings cannot be overridden in your ICS Calendar shortcode.

The other settings — Timezone and Date Format — can be overridden in your shortcode, by using the tz and format parameters.

For attachments in an ICS (iCalendar) feed to work, they either need to be embedded directly into the feed, or they need to be directly accessible at a public URL.

The iCalendar specification supports attachments, but many software providers — including Google and Microsoft (Outlook/Office 365) — do not properly honor the spec.

ICS Calendar supports image display directly in event descriptions; however, this can only work when the source feed includes direct image file URLs. Neither Google nor Microsoft provide these direct URLs, so it is therefore not possible to display images directly from these sources.

Google makes attachments — both images and other downloadable file types — available in feeds via Google Drive links. If your shortcode includes attach="true" or attach="image", then clickable links to the images should appear in your event descriptions.

Images shared from Google Drive will be clickable links, rather than displaying inline, due to the structure of Google Drive links and file access permissions.

If a user who does not have permission to access a particular file on your Google Drive clicks the link, you will receive an automated email from Google requesting permission for that user to access the file. For this reason, you may not want to include attachments in your feed if your site is public.

Google does not provide any way around this limitation, nor a way to make event images/attachments directly publicly accessible.

Microsoft does not automatically make attachments available in this way. The default handling may result in your event descriptions including code that looks like this: [cid] That is the internal reference code for your file within Office 365, but it is useless outside of their platform.

You can get Microsoft to include a clickable link, similar to what Google does, by uploading your files to OneDrive. This can be done by editing the full details of your event, hovering over the image/attachment, clicking the down arrow, and then selecting “Upload to OneDrive” from the contextual menu.

As with Google, you’ll need to be sure attach="true" or attach="image" is part of your shortcode.

After the file has been uploaded, save your event. You may then need to use the Clear Cached Calendar Data tool on your WordPress site to update the calendar data.

We have heard about a few instances lately where users get the following message when attempting to upload ICS Calendar Pro to their sites:

The link you followed has expired. Please try again.

Although it seems unintuitive from the text of the error, this issue can sometimes be resolved by increasing the upload size limits in your PHP configuration.

Despite some tips that this can be done with a plugin, it is important that these settings be changed very early in the process; some plugins may not change the value until after WordPress has started processing the upload, in which case they will have no effect.

The easiest place to make this change is in your site’s wp-config.php file, where you would need to add something like this:

ini_set('upload_max_size', '96M');
ini_set('post_max_size', '96M');
ini_set('max_execution_time', '90');

The first two lines will allow a file upload of up to 96 MB. The last line will allow a PHP process to run for up to 90 seconds, which should be more than enough time to upload a file over an average broadband connection. If these changes do not resolve the issue for you, you may want to temporarily try much larger numbers, e.g. 256M and 300 (for 256 MB and 5 minutes).

If you do not have access to your site’s wp-config.php file, you may need to contact your hosting provider for assistance.

What if it still doesn’t work?

There are a few options if the above does not resolve the issue. If you have FTP, or better yet, SFTP/SSH access to your server, you can manually upload the plugin.

With SFTP/SSH, you can upload the zip file and then extract it directly on the server. With regular FTP, you’ll need to extract the zip file on your computer, and then upload the entire extracted folder.

Either way, you’ll need to place the extracted ics-calendar-pro folder inside your [SITE PATH]/wp-content/plugins/ folder. After the folder is uploaded, go to Plugins in your WP admin and look for ICS Calendar Pro. Activate it, and you should be all set.

Note: If you manually upload the plugin, it’s possible that the file permissions will not be set correctly, which could prevent future updates to the plugin from installing properly. If this happens, please contact your hosting provider for assistance with resetting the permissions.

Security researchers identified a moderate-level risk in an ICS Calendar function, which was patched in version 10.12.0.4. However, the patch introduced a new issue that prevented access to ICS feeds over an internal network — specifically, if the source calendar server’s URL resolved to an IP address in one of the private or reserved ranges.

An update in version 10.12.2 addresses this, via the WordPress core http_request_host_is_external filter.

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.

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 code can go in your theme’s functions.php file or in a custom plugin. (If you are using a pre-built theme, be sure not to edit the theme’s files directly, as the changes will get overwritten when the theme is updated. Use a child theme instead.)

By default, Microsoft Outlook/Office 365 only includes the next 6 months’ worth of events in the iCalendar subscription (ICS) feed. Most users of ICS Calendar will want their calendar to show at least a year. There is not an easily accessed option to make this change, but Microsoft does provide a way to change the setting, if you have the proper account access.

The change requires using Exchange Online Powershell. There, you will need to run the following command. (Be sure to change username and domain.com as appropriate.)

Set-MailboxCalendarFolder -Identity username@domain.com:\Calendar –PublishEnabled $true -PublishDateRangeFrom SixMonths -PublishDateRangeTo OneYear

More details can be found in the Microsoft support forums.

Update: The new ajax parameter (introduced in version 10.3) may be useful in improving page load for sites with large amounts of calendar data.

Does your calendar have a large number of recurring events? There is an inherent issue with the way ICS works, in that parsing a calendar with a large number of recurring events can be a very slow process.

Normally when a feed is loaded into calendar software this is not a noticeable issue because it happens behind the scenes, but with a website, there are not so many reliable ways of making that “behind the scenes” processing happen.

ICS Calendar Pro does include a “pre-caching” feature, but depending on your site’s setup and amount of traffic, it doesn’t always make that much of a difference. Generally on a website, the only time any processing happens is when a visitor actually comes to the site and loads a page. Servers can have scheduled tasks called “cron jobs” that do processing automatically, and the pre-caching feature is dependent on that. But by default WordPress doesn’t use true cron jobs, because that requires configuration directly by a systems administrator at the OS level on the server. WordPress fakes it with WP-Cron, a task scheduling system that fires off periodically at the end of page loads, when users visit the site.

The problem with depending on WP-Cron for this is that it requires your site to get a certain base level of traffic to be effective. And, for ICS Calendar Pro in particular, if the page being visited (and therefore firing off WP-Cron when it’s done loading) contains the calendar, it has to load the calendar first, with all of the involved data parsing, during the initial loading of the page anyway… making WP-Cron effectively useless at improving performance.

It is possible though, if you do have direct server access, to set up the firing of WP-Cron as a real cron job at the OS level, which can make a big difference here.

The Pro version also lets you change the default caching duration. By default the plugin caches your calendar for one hour. Meaning, one person hits the page and has to wait for it to do all of that processing, but then for the next hour, anyone else who loads the page sees it quickly because it just loads the already-parsed data from the cache. If you combine pre-caching, a true server OS cron job to fire WP-Cron, and a longer caching duration, e.g. 12 hours (43200 seconds), then you can significantly mitigate the slow loading issues.

Unfortunately, since these features are not in the free version, and the preview tool obviously can’t pre-cache your calendar, there’s no way to see this in action without actually installing ICS Calendar Pro and trying it out.

This is part of the reason we offer a 14-day refund for ICS Calendar Pro — so you can try it out for a couple of weeks, and if you’re not able to get it working the way you’d like, we’ll refund your purchase. We’re also continually looking for ways to improve the way the plugin handles this particular situation, so if you buy Pro and are running into performance problems with your recurrence-heavy calendars, please submit a support request and we’ll work with you directly to find a solution.

There are two ways to fix timezone issues.

First, you should make sure your WordPress site is configured with the correct timezone. This is under Settings > General. Be sure to set the Timezone to the city closest to you in the same timezone. For instance, here in Minneapolis we set the timezone to “America/Chicago.”

Do not use the UTC hour offset options. UTC hour offsets cannot adequately account for varying regional Daylight Saving Time rules. Both your WordPress settings and your source ICS feed should use the named region/city pair that matches your local DST rules.

The second option is to use the tz parameter directly in your shortcode. While we recommend using the general WordPress setting, you may have a situation where you need to display a particular calendar in a different timezone than the one in your WordPress settings. In that case, you can change the timezone for a specific calendar by adding, for example, tz="America/New_York" to your shortcode. If your calendar includes multiple feeds, you can set a different timezone for each by pipe-delimiting the value in quotation marks, such as tz="America/New_York|America/Chicago", in the same order as the feeds in your url parameter.

In ICS Calendar Pro, you can set the timezone for each feed in a saved calendar by picking from the dropdown menu on the calendar editing screen.

Be sure you are using a valid named timezone. You can find a full list in the PHP documentation.

WordPress includes built-in functionality to translate basic date text like month and day names into the language configured under Settings → General in your WordPress admin.

ICS Calendar includes several dozen translations to render its custom text in your configured language as well.

All of this translation is done in advance. There is no live, “on-the-fly” translation happening. As such, it is not possible to translate the text of your feed data. The text of event titles and descriptions will be displayed in whatever language the original source feed is in.

Live translation plugins like GTranslate may be helpful.