Category Archives: amr ical events list

Posts related to Version Releases of amr ical events list

GDPR Compliance for event plugins

amr events, amr ical events list, Feeds, Ical RFC5545 / 2445

This statement is for the wordpress plugins amr-events, amr-ical-events-list  and amr events attendees at https://icalevents.com/plugins_downloads/

Briefly: the amr-events plugin creates events as wordpress custom posts. No additional user data is created or stored. The post author (display name and email) is assumed to be the event organiser for purposes of complying with the ics feed RFC5545 standard. The plugins do not send or store data on any other servers.


Collecting & storing of user data:


The amr-events plugin creates events as wordpress posts.  As per standard wp processing the author of the post is recorded.  That is the extent of any collecting any personal user data that is within the plugins control – only as per standard wordpress user functioning.   The plugin does not of itself collect and store user data.  Control of that user data rests with the website owner.


Processing or use of user data (email and display name):

In event feeds (ics feed) as per the RFC5545 standard the event organizer must be included in the RFC 5545 ics file.  Refer https://tools.ietf.org/html/rfc5545#section-3.8.4.3   – see Organizer

This property MUST be specified in an iCalendar object
      that specifies a group-scheduled calendar entity.  This property
      MUST be specified in an iCalendar object that specifies the
      publication of a calendar user's busy time.

To conform to this, the event post author’s data is then included in the ics file as per the example in the specification :

ORGANIZER;CN=John Smith:mailto:jsmith@example.com

The plugin uses the wordpress post authors “display name” if it exists, if not then the wordpress users “userlogin”, and then the wordpress users ‘user_email’ to provide the required ORGANIZER details.  The plugin does not have any means to validate this data and simply uses what has been stored the user records by the website.

A web developer can choose to display (or not) the public ics url.  The web developer can also control whether a real user or a dummy user is recorded as the post author.

The plugins can also list events from external public ics files.  These ics files may contain attendee data.  The ics files are cached and refreshed daily or as requested.  The cache purpose is to continue to be able to list events should there be a disruption in access to source url.   If the web designer chooses to use the addon https://icalevents.com/downloads/amr-events-attendees/  then the web designer can choose to display that attendee data in the event list.  That list may be displayed in a  public or private page as setup by the web designer.  There is currently no provision to add attendee data to the custom events created inside wordpress.  If this becomes available, a link to the user data such as the user id or email address is what would be stored.

GDPR Summary

The plugins use a minimal amount of user data required to provide event functionality in adherence with the ‘purpose’ and ‘data minimisation’ principles.  With respect to the other GDPR principles, the plugins do not control the accuracy, storage, or security of this user data.   The plugin does not pass user data on to any other parties except as required by the RFC5545 ics specification and as configured by the website developer.

Categories from ics files

amr ical events list, ,

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.

Example ICS Extract:

DTEND:20170429T010000Z
CATEGORIES:New Technology,User Experience,Web Technology,Web Development,Computer programming,Software Development,Technology,Interaction Design,Internet Startups,Web Design,iOS Development,Graphic Design,Ruby On Rails,Python
DTSTART:20170428T150000Z

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.

 

 

Memory Problems or Timeouts ?

amr events, amr ical events list,

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:

If your memory setting is already quite high, then evaluate whether you are asking the plugin to do too much:

Do you have recurring events ?

If you do have recurring events, please consider the following carefully:

How many days, months and number of events have you set as your maximum ?

This can influence how much work are you expecting the plugin to do.  Setting unnecessary high thresholds can cause a lot of extra work.   More info on number of events, number of days or months here.

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.

 

Event List Parameters, number of events, days, months, years

amr events, amr ical events list, , , ,

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.

maximum events and number of days, or months
maximum events and number of days, or months

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,

 

Google calendar ics files

amr events, amr ical events list,

If you are using a google calendar ics file as event input you should be aware of the following:

  • 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.
  • At times the ics feed used to be 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.

On the other hand, when using an amr-events feed in a google calendar,  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.

How to change icon images (subscribe to calendar, add to google)

amr events, amr ical events list, Css, How To, ,

The plugin comes with two sets of default icons (16px and 32 px).  It also includes extra icons that match those for your use.

screenshot of icon listing
some of the available icons

Don’t like those icons?

You could do one or more of the following:

  1. Switch images off
  2. Use Css to replace the text with your own images
  3. Write own formatting routines

Switch images off

You could choose just to have the link text for the actions behind the icons.  See the “Listing events’ settings.

settings screenshot to show you how to switch images off
Switch images off

Use Css to replace the text with your own images

First switch the default  images off and then use css to show your chosen icons instead.

text replaced with image
text replaced with image

There are various techniques that one can use to replace text with an image. The following was used to demonstrate the above replacement using the plugins html classes.

a.icalsubscribe { 
    display: block;
    height: 50px;
    width: 50px;
    background-image: url(http://i.stack.imgur.com/XtpTm.png);
    background-size: 50px 50px;
    text-indent: -9999px;
    overflow: hidden;
}

Some of the link classes that you may wish to define image icons for are:

  • subscribe
  • icalsubscribe
  • addtogoogle
  • hrefaddtogoogle
  • hrefmap
  • timezone
  • refresh

Add the extra css :

  1. Either to your custom themes stylesheet (not to one that gets updated automatically, because you will lose your modifications), or
  2. use something like jetpacks wordpress custom css, or
  3. use a custom ical events list css

Write own formatting routines

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.

some pluggable functions in amr-icalevents-list

  • add_cal_to_google
  • add_event_to_google
  • amr_ical_showmap
  • amr_show_refresh_option
  • amr_format_tz

some pluggable functions in amr-events

  • amr_subscribe_to_event_series
  • amr_subscribe_to_event

 

Groupings of events, expanding and collapsing the groupings

amr events, amr ical events list, Css, How To

Events can be grouped in many ways. To set up groupings see this post on event grouping and styling.

Expand and Contract Groupings

To expand and contract groupings, tick the ‘load js’ in the listing events settings

Use js
Use js

and optionally add a shortcode to add text to showall or hideall detail of groupings

[expandall]
[events]

Events collapsed behind groupings
Events collapsed behind groupings

One event grouping expanded
One event grouping expanded

Grouping events

amr events, amr ical events list, Css, How To, Html

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.
  • See how to format the date related groupings here.
  • Each grouping comes with css classes so you could for example do seasonal styling of event groups.
  • By adding in the javascript in the settings, one could also expand and collapse the groupings.

Settings

 

Grouping settings
Grouping settings

Styling Groupings – use the css classes

Example of html produced with css classes
Example of html produced with css classes

Correct Handling of UID, RECURRENCE-ID, SEQUENCE

amr events, amr ical events list, Ical RFC5545 / 2445, Notes

Modifications to events, especially to an instance of a recurring event, or an update to a modified instance can all seem quite complex.  It’s not that bad once you understand the various bits that you need to provide for the receiving application to make sense of it. See the RFC5545 spec for details.  This tools.ietf.org version or icalendar.org or the kanzaki version.

  • UID – must have and must be unique
  • SEQUENCE – numerically update to indicate which is the latest version
  • RECURRENCE-ID – if modifying a single instance with in a recurring stream.  Note that for a UID and SEQUENCE pair, the “RECURRENCE-ID” value for a recurrence instance is fixed. The event date may change but the “RECURRENCE-ID” does not. It must always be the original date as generated by the RRULE.
  • LAST-MODIFIED – Probably a good idea top update this too

Note also:

  • if a user subscribes to an ICS URL, then the receiving application will check for updates on a regular basis at a frequency determined by it.  It will be seen as a separate calendar.  It will use the SEQUENCE numbers to determine the latest event details. There may be a delay in an update being made on the originating system and it being reflected in the receiving system.   The only reliable way to be sure that users will have updates seen in their calendars is if you can get them to subscribe to the url (or ‘import’ the url, not the file)
  • if an ics file is imported (eg: when event details are sent as an ics file attachment, not as a url, or if the user downloads the ics file from a url and then imports it), then it will be added as events into the calendar chosen by the user.  Updates may overwrite IF the user re-imports the events AND the application is clever enough to match up the UID’s (and RECURRENCE-IDs if it’s part of a recurring set).  It should then also use the SEQUENCE to determine if the details are actually the latest.  There is no way on devices to force a user to load an updated ics file sent to them.

Example

Modifications to recurring rules or rdates and modifications to instances of those recurring rules (themselves already a modification.)

Assume we have a recurring event.  It starts with a SEQUENCE: 0

DTSTART;VALUE=DATE:20140421
 RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=3MO
 UID:1f4irrb5uh6q3cdfsnq15vd00g_R20140421@google.com
 SEQUENCE:0

This generates an infinite set of mondays, including the following

  • 19th May
  • 16th June
  • 21 July
  • 18 August
  • etc

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)
 DTSTAMP:20140720T064853Z
 UID:1f4irrb5uh6q3cdfsnq15vd00g_R20140421@google.com
 RECURRENCE-ID;VALUE=DATE:20140721

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.

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

Dates, Times, Formatting

amr events, amr ical events list, Ical RFC5545 / 2445,

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.

screnshot Date Time Formats
Date Time Format settings by listtype

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

screenshot of show screen options in edit events
show screen options in edit events

  • Last 20140630

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.

Technical fields

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

Other fields

As these are very technical, precise fields, they are by default not formatted but left as found.

  • DTSTAMP: 20140616T021842Z
    • the date and time that the instance of the iCalendar object was created.
  • LAST-MODIFIED:20140616T025756Z
    • the date and time last modified – works with the sequence number to determine the latest modification to an event instance.