An ics file may have ‘CATEGORIES’ in it. For formatting purposes, the plugin treats these similar to the wordpress ‘Category’, and will ‘mimic’ the links that are generated by wordpress categories.
Unlike wordpress event category or taxonomy based selection, selection of ics events via shortcode parameter is not currently offered. It is preferable (more efficient) to do your selection of events for your ics file page by selecting the events for your ics file at the providing system side. Hopefully the providing system offers the necessary parameters, as the amr-events plugin does when it offers ics feeds.
A tailored ics feed reduces the size of the file and the number of events that have to be parsed unneccesarily by this plugin. Those ics files can get big over time, so if you have the option to select only current and future events, do that too!
For example of tailored ics feeds, see the demo site for amr-events – one can see that multiple selections are available from the amr-events to tailor an ics feed.
The plugin will try to pretend that these are like wordpress categories, and will create ‘links’ behind the ics category names. To demonstrate, use the default list type with your ics file. The CATEGORIES should appear below the description:
Example formatting of ics categories:
One can click on the links generated to see just the events with that ics CATEGORY.
Note that the whole file still has to be parsed before event selection can take place.
Experiencing memory problems or timeouts ? Check the following:
Are your default wordpress and php memory settings up to handling all that you have added to the site?
Over time, as you add change themes, and add plugins, your wordpress setup starts needing more and more memory. Sometimes the last plugin added is the one that ‘tips it over the threshhold’. It may not be the main memory hog (or it may see below.) Please check your wordpress and php memory limits. Here are some helpful posts:
How old is your ics file and how many ‘old’ events does it have ?
If it’s a google calendar, the ics feed does not at time of writing offer a way to request future events only. This means your ics file will grow. The plugin has to parse ALL the events in the file, hold them in memory to check for a possible modifying VEVENT with a later sequence number that modifies the date. More info on google calendar ics files – and how to bulk delete old events.
In the list type settings, and as shortcode parameters, you can set the maximum number of events and the maximum number of days or months that the plugin will attempt to list. It also uses these to limit the recurring events it has to generate.
It is important to set a balance between number of days/months and number of events, particularly if you have recurring events and in particular for those people using ics files. An event, especially a recurring can be made up of multiple VEVENT definitions, additional definitions for each excluded date, or modified instance. So for each recurring event, the plugin has to
generate the possible instances, hold them all in memory
check for any modifications, exclusions etc and apply those to the instances, before it can start limiting.
Modifications of instances can change an instance date and time – pushing it out of the desired time range or WORSE, pulling an instance that is currently out of range, INTO the time range.
Try to balance the two parameters: the time period and the number of events based on your knowledge of the types of events and their frequency.
For example: If you specify 10 events and 1000 days, the recurring events have to be generated out to 1000 days and all held in memory, until all events generated and modifications applied, and then the number can be cut back to 10.
As a guideline, If you want to show 5 events and usually they’d be in the next two months, then maybe 90-120 days would be suitable.
Note also that there is a difference between how hours, days, months thresholds are treated.
hours start from current hour
days start from current day
months start from current month
So if you say months=1 and the list is running on the last few days of the month, you will not see many of ‘future’ events ie: next months day. Bette to perhaps either use: days=30 or months=2,
If you are using a google calendar ics file as event input you should be aware of the following:
At times the ics feed is slow to update – check what the actual feed contains if you think events are missing . Open the ics file in notepad, and check if your events or your changes are there. Note that an instance may have multiple VEVENTS with incremental SEQUENCE numbers later in the file.
the ics file may get rather large over time. At time of writing there is no way to get the feed to only show future events, so it will have ALL your old data. This all has ti be parsed, turned into event data and held in memeory to see if there any any modifications, or exclusions. If you don’t need the old events, try deleting them. You may need a bulk delete tool. I have used this GcalToolkit, not ideal but it does work.
On the other hand, using an amr-events feed in a google calendar:
Again google can be slow to refresh reading the feed, sometimes it will do the first one fine, then you make a change and expect google to show in instantly. It will not. Not much we can do about that.
See the pluggable files in each plugin folder. Use the function there as a base for your new function. Add your function to your custom themes function.php or to your own site specific snippets plugin.
Events can be grouped by date formats or by categories, tags or custom taxonomies.
Events can be grouped by days, weeks, months and some funkier options that no one will probably ever use, but I liked the challenge! Actually I imagined one could do some seasonal styling perhaps? each grouping has it’s own css classes, and date/time format
Grouping also allows one to do timetables (grouped by day), weekly schedules, or monthly, quarterly or seasonal event views.
Some folks have been using the free version of this plugin for several years. Some of them have recurring events with modified instances. Sometimes the frequency of modifications is high. In the last few months this has caused a fair bit of extra support required as anomalies crop up. Sometimes bugs are flushed out and sometimes almost unanswerable questions are raised as to what the plugin should do if it gets weird data.
The point of this post is to highlight some of the complexities that may develop and urge you to keep your ics files as clean as possible or use amr-events where it is possible to delete old events (hard to delete volumes of old events in google calendar).
An example is modifications to recurring rules or rdates and modifications to instances of those recurring rules (themselves already a modification.)
For example:Assume we have a recurring event. It starts with a SEQUENCE: 0
This generates an infinite set of mondays, including the following
Now, one of the instances gets modified. (This could be just the description or the actual date.) A RECURRENCE-ID VEVENT is created for each instance modification and the SEQUENCE NO is updated. The recurrence-id matches the date in the recurring rule that it applies to. The combination of UID, RECURRENCE-ID and SEQUENCE helps us identify the instance that is being updated.
For a given pair of "UID" and "SEQUENCE" property values,
the "RECURRENCE-ID" value for a recurrence instance is fixed.
DTSTART;VALUE=DATE:20140721 (ie no date change in this example)
Now assume the original RRULE is modified too, perhaps just the description or shock horror, the recurring date definition? It’s sequence-no is updated too BUT now what should happen to the RECURRENCE-ID instance? Should it be updated to indicate it is still valid? IE we now have:
generated date 21 July 2014 with UID and SEQUENCE = 3 and
RECURRENCE-ID;VALUE=DATE:20140721 with matching UID and SEQUENCE = 3
It appears that perhaps SEQUENCE numbers can increment separately, so one could conceivably receive a file with a RRULE with an equal to or greater sequence number than a RECURRENCE-ID. From this discussion, it is really not clear what the supplying calendar application will do:
Once UID 1/SEQUENCE 0 hits UID 1/SEQUENCE 1 (which would
mean something significant about the set of instances
has changed) all bets are off in regards to RECURRENCE-ID
values that previously existed.
If the UID/RECURRENCE-ID/SEQUENCE matches a generated date from the rrule with same SEQUENCE (ie both have been modified), then what? One cannot just use eg: LAST-MODIFIED:20140620T200327Z. Who is to say that a mod of the RRULE was intended to overwrite the RECURRENCE instance? Quite possibly not.
What does the plugin do:
For now (until further authoritative input to the contrary), the plugin will assume that a recurring instance (RECURRENCE-ID) in the file is intended to be still there. It will include the highest sequence number of the recurrence (even if the originating rrule is not there -an error in supplying application). Similarly it will include the recurrence even if the rrule does not have a matching date.
It will also assume that the recurrence instance overwrites the RRULE definition even if the RRULE has a later SEQUENCE number. The Plugin does not have to worry about the complications of syncing for now.
If you are ever struggling to figure out what the plugin has done. Create a test list and include the RECURRENCE-ID and SEQUENCE fields. You can reference the test lits by adding ?listtype=x to your events page url.
Some lengthy related discussions here and in other parts of the thread:
Complications that urge one to keep events as simple as possible:
Searching the web seems to indicate some folks believe RECURRENCE-IDS should not change. So should we assume that if the RECURRENCE-ID vevent is still in the file then it is still valid and should be included. (What does this mean for syncing and deletions? IE How does one ‘delete’ an existing event. Or should one always delete events from an ics file and reload ONLY what’s in the ics file?)
There are a number of date and time options for you to choose when displaying your events. The main ones you should be using are created by the plugin and will be formatted by the date and time settings you have specified in the plugin settings (and applying any localisation that may be available in your wordpress setup). You can specify these by listtype, so say a widget could have a very compact date format and a full list may be more detailed.
Event date fields formatted by your date settings:
EventDate: Mon, June 23, 2014
EndDate: Mon, June 30, 2014 (only if event greater than one day)
Event time fields formatted by your time settings:
StartTime: 9:00 am
EndTime: 10:00 am
Note there may be situations where there is no end time or no end date (eg: if there is no duration or the end date is the same as the start date. If a field has not been populated, it will not be displayed and neither will any ‘before’ or ‘after’ text.
Field from the ics specification that may be useful.
Formatted using human language function
DURATION:1 week , 1 hour
Other date fields in the ‘edit events’ admin screen
The ‘last’ date shown in the edit events admin screen shows the last recurrence date of an event. It is used to select events within a date range (ie exclude events whose recurrences are in the past, without having to rebuild the recurrence logic). It is also used to sort events in the admin screen by this last recurrence. It is therefore formatted yyyymmdd for the sorting. It is not intended to be displayed elsewhere.
These are direct from the ics specification formatted by the DateTime settings in the plugin settings. Note the DTEND has a special definition in the ics specification for all day events (it will have the next day as the end date) and may be confusing to normal users. Some ics generators get the DTEND logic wrong, so this plugin tries to work with duration just in case.
DTEND: Mon, June 30, 2014 10:00 am
DTSTART: Mon, June 23, 2014 9:00 am
As these are very technical, precise fields, they are by default not formatted but left as found.
the date and time that the instance of the iCalendar object was created.
the date and time last modified – works with the sequence number to determine the latest modification to an event instance.
Some theme language files can be found at http://i18n.svn.wordpress.org/ . You may have to click down various paths as sometimes somelanguages are stored differently.
Danish example: http://i18n.svn.wordpress.org/da_DK/trunk/messages/twentythirteen/
Updated plugin language files
Some folks have kindly provided translations. You can see the latest available here. These are not always up to date. See translation tools below. If you need to update your language files, please send me the update and I’ll upload it.
If you do NOT send an update, your version may be overwritten in a plugin update unless you move it.
Custom Language File Location
For these two plugins, you can store your custom .mo and .po files in your WP-CONTENT languages subfolder.
Do not use the subfolder /plugins as wordpresss may one day be auto loading translations to that folder.