Category Archives: Notes

General Notes

The last week of the year is….

amr events, Ical RFC5545 / 2445

According to wikipedia,the last week of the ISO week-numbering year is the week before week 01; in accordance with the symmetry of the definition, equivalent definitions are:

* the week with the year’s last Thursday in it
* the week ending with the Sunday which is nearest in time to 31 December
* the week with December 28 in it
* the last week with the majority (four or more) of its days in the ending year
* the week starting with the Monday in the period 22 – 28 December
* the week with the Thursday in the period 25 – 31 December
* the week ending with the Sunday in the period 28 December – 3 January
* If 31 December is on a Monday, Tuesday, or Wednesday, it is in week 01 of the next year, otherwise in week 52 or 53.

So this plugin when calculating the weekno and if there is a WKST specification in the rule, uses “the week with December 28 in it” to calculate the last week and handle negative BYWEEKNO’s that way.

The logic is something like this

  • get the end of the year (ie 28th Dec)
  • determine the weekno (will be 52 or 53?)
  • go to the start of that week, using wkst
  • “save” the this and next 6 dates as our week

What do you think is the “first week” of the year ?

amr events, How To, Ical RFC5545 / 2445

Week numbers and BYWEEKNO and weeks start with Monday, Sunday, Saturday (WKST)

How the week number is entered and sent in an ics file is important in two areas of this events plugin.

  1. For communication with other calendar systems, one must stick to the ical RFC5545 (ie : ISO 8601) definition so that recurring dates will be accurately reflected.
  2. For listing of events (agenda or calendar style) however there may be expectations of other week numberings (For example many timeshare resorts use very different week numbering systems, depending on when “their” weeks start – eg: Friday, Saturday, Sunday.)  It is simply not possible to cope with all of these, at this stage .  The RFC5545 spec (see below) implies that one can combine BYWEEKNO and WKST to give some flexibility.  The amr events plugin will pick up the week start defined in your wordpress website.
Entering the week number
Entering the week number for a recurring date in wordpress event plugin

What does the plugin do wrt week numbers ?

When entering a week number, the ISO8601 in combination with the weekstart (WKST ) will be expected.  To aid data entry, it will be checked against the start date (which must be in the week number) and the error message will tell you the wek number of the start date.

At launch, the listing plugin is limited to using the PHP functions for calculating the week number.

Week number definitions:

Wikipedia has some discussion on various usages or week number definitions under the 7 day week, week numbering heading.   There are many – it is not just a case of

  • which day the week starts on (Monday, Sunday, Saturday, Wednesday (Hungary?)), but also
  • what defines where one begins in the year with partial weeks or full weeks
    • Week containing Jan 1 (Eastern European, India, Arabic countries, Canada, China etc..)
    • Week containing Jan 4 (European countries)
    • Week containing Jan 7 & Monday  (Eastonia and Pakistan)

A list of these is available at pjh2.de and more information from JR Stockton

Technical Definitions of BYWEEKNO

From the RFC5545 Specification:

The BYWEEKNO rule part specifies a COMMA-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. This corresponds to weeks according to week numbering as defined in [ISO.8601.2004]. A week is defined as a seven day period, starting on the day of the week defined to be the week start (see WKST). Week number one of the calendar year is the first week that contains at least four (4) days in that calendar year. This rule part MUST NOT be used when the FREQ rule part is set to anything other than YEARLY. For example, 3 represents the third week of the year.
Note: Assuming a Monday week start, week 53 can only occur when Thursday is January 1 or if it is a leap year and Wednesday is January 1.

This note from aspose.com advises: Use BYWEEKNO only when conformance with ISO 8601 is required. Week numbers as defined by ISO 8601 are very different from week numbers in “common” sense.    According to ISO 8601, week number one of the calendar year is the first week of a calendar year that contains at least four days. This rule makes the algorithm specific to applications requiring conformance to ISO 8601 and make it almost inapplicable to other “normal” uses.

ISO 8601 is supported by some European banking and financial applications. It is also used in Television for booking commercials. An ISO week calculator can be found at http://www.personal.ecu.edu/mccartyr/isowdcal.html

The BYWEEKNO rule specifies a comma-delimited list of numbers identifying weeks of the year. Valid values are 1 to 53 and 1 to 53. This corresponds to weeks according to week numbering as defined in ISO 8601. BYWEEKNO is only valid for YEARLY rules.

To illustrate, the following are two very different recurrence patterns:

  • Friday of 1st ISO 8601 week of the year: FREQ=YEARLY;BYWEEKNO=1;BYDAY=FR
  • 1st Friday of the year : FREQ=YEARLY;BYDAY=1FR

In 1999, for example, 1st Friday of the year is 1999/01/01, while Friday of the 1st ISO 8601 week is 1999/01/08.

So what is the current week number?

These sites help if your week starts on a Monday:

Paydays, Last working days and why BYSETPOS is useful

amr events, Ical RFC5545 / 2445

Have you ever wondered how to represent important recurring events like a ‘payday’ or a last business day?

If your calendar application allows you to enter the “set position” along with other recurring rules, then you’ll need to know about BYSETPOS.

In a ical recurring event, the BYSETPOS is a comma separated list of numbers (1 to 366 or -1 to -366). It MUST be used with another ‘BY’ rule such as BYDAY, BYMONTH etc.

It “chooses” the ‘nth’ occurrence within a set of dates determined by the preceding rules.

For example, in a WEEKLY rule, the interval would be one week. (Remember to consider what the “start of the week” is for the set you are using). A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part.

Formal definition

For the formal definition see http://www.ietf.org/rfc/rfc5545.txt

Examples

The last work day of the month

FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1

‘PAY DAY’ – the last week day in the month!

RRULE:FREQ=MONTHLY;BYDAY=-1MO,-1TU,-1WE,-1TH,-1FR;BYSETPOS=-1

The 30th of every month; or the last day of the month if the 30th doesn’t exist

FREQ=MONTHLY;BYMONTHDAY=28,29,30;BYSETPOS=-1

For Developers

According to the very useful table of recurring rule precedence of page 43, the BYSETPOS is applied last within an iteration of the ‘FREQ’ on the set of dates generated by the rule.  If you programmaticaly follow the table logic, you should be able to avoid problems implementing BYSETPOS.

TZID’s with quotes around them

Ical RFC5545 / 2445, Notes

Some ics files (eg: a zimbra file)  I have encountered have the TZID enclosed in quotes.

DTSTART;TZID=”America/New_York”:20080908T130000

The usual use (google calendar etc) is:

DTSTART;TZID=America/New_York:20080908T130000

The spec examples do not show quotes and the quotes in the terminology definition are not I think meant to be included in the data.  However this is relatively easy to deal with, so the next version of the plugin > 2.9.4 will cope with these.

Please note that the plugin currently ignores the VTIMEZONE in the ics file and uses the php database timezone.

The plugin will also not cope with the following yet (I have not yet encountered an ics file with it’s own timezone identifiers yet!):

fictitious globally unique time zone identifier example:

TZID:/US-New_York-New_York

Importance of timezones in recurring events

Notes

Following is a table of dates for a weekly recurring event. The original event (in an ics file) is specified in the Europe/London timezone. For the purposes of demonstration here, assume that the dates for event are to be displayed in the Sydney timezone.

Both London and Sydney have daylight saving changes. The table shows the perils of not adequately dealing with the timezones.

If one converts the start date to Sydney and then generates the repeating dates, one will end up with the wrong times. The correct way to do it, is to stay in the event timezone while one generates the repeating dates, and then at display time only, convert the datetime object to the display timezone.

London, recurring Convert to Sydney then recur (wrong) London recurring then convert to Sydney (right)
2010-03-08T19:00:00+00:00 2010-03-09T06:00:00+11:00 2010-03-09T06:00:00+11:00
2010-03-15T19:00:00+00:00 2010-03-16T06:00:00+11:00 2010-03-16T06:00:00+11:00
2010-03-22T19:00:00+00:00 2010-03-23T06:00:00+11:00 2010-03-23T06:00:00+11:00
2010-03-29T19:00:00+01:00 2010-03-30T06:00:00+11:00 2010-03-30T05:00:00+11:00
2010-04-05T19:00:00+01:00 2010-04-06T06:00:00+10:00 2010-04-06T04:00:00+10:00
2010-04-12T19:00:00+01:00 2010-04-13T06:00:00+10:00 2010-04-13T04:00:00+10:00
2010-04-19T19:00:00+01:00 2010-04-20T06:00:00+10:00 2010-04-20T04:00:00+10:00
2010-04-26T19:00:00+01:00 2010-04-27T06:00:00+10:00 2010-04-27T04:00:00+10:00
2010-05-03T19:00:00+01:00 2010-05-04T06:00:00+10:00 2010-05-04T04:00:00+10:00
2010-05-10T19:00:00+01:00 2010-05-11T06:00:00+10:00 2010-05-11T04:00:00+10:00

Ical Local or Floating Date Times?

Notes,

A personal time?

According to the spec  local times (eg DTSTART:20100202T161500) are the same whatever the attendees timezone.  Eg: if you go for a run at 8am in the morning, where ever you are in the world, then it does not matter what timezone you are in, you want this note or alarm or reminder to say 8am.

The requirement is quite different for an international conference call with attendees in different timezones, or for a location specific conference.

Are  fbcalendar/facebook and artistdata using them correctly?

I have now encountered another ical feed (fbcalendar) that is issuing the event dates as “local” ie: without a timezone spec for the event. Thus far  the ical plugin is intended to reflect them as “local” no matter what the timezone.  It has to create the date time with a timezone, so it uses whatever it has determined as the plugin’s default timezone.      This can be overwritten in by URL request.  If the plugin is working correctly, then no matter what timezone is requested in the url, the loacl or floating time should stay the “same”.

Now we have the puzzling question of what to do when a ics file with  times defined as “local” is passed through another calendar application which changes that definition?

For example, one of the plugin users has a complicated url that includes a comma.  The shortcode is happy with, but the widget is not.  So he has passed it through google calendar to get a url that works in the widget.

So a event that was defined with start and end dates like this:

X-WR-TIMEZONE;VALUE=TEXT:Europe/Oslo (for ics file)

DTSTART:20100202T161500
DTEND:20100202T180000
LAST-MODIFIED:20100127T074205Z
LOCATION:Auditorium 4\, Eilert Sundts hus
SUMMARY:A.C. Grayling: ‘On the Age of Terror and other threats to liberty’

has become after being goooglized:

X-WR-TIMEZONE:Europe/Oslo (at calendar level)

DTSTART:20100202T151500Z
DTEND:20100202T170000Z
DTSTAMP:20100130T034724Z
…
SUMMARY:A.C. Grayling: ‘On the Age of Terror and other threats to liberty’

The Z means “utc” timezone.   The resulting time when converted to Oslo time is the same.  However if those same files are used in other timezones, the resulting times will be different!  The second one will be converted to the timezone that it is being displayed in.

An Error?

Arguably, the original event specification was in error. If this is a specific event at a specific location, then the local or floating datetime spec is incorrect.   It should be specified in the timezone of that location.

What should the plugin (or any ics reader) do?

I think my interpretation of what the plugin should do is correct – however this may occasionally give unexpected results.  However I think the error is then in the generation of the Ical feed, or specification of the event – floating times should be carefully used.

All day events – adding a day or not?

Notes,

The definition of an untimed all day and/or multi day event in the ical spec can be confusing.  See an extract from http://www.innerjoin.org/iCalendar/all-day-events.html for an explanation of the logic.

Google calendar certainly adheres to this , as does Thunderbird Calendar.

All Day Events

Applying the logic of an event to a date, an ‘all day’ event is flagged as starting at the beginning of one day and lasting until the beginning of the next:

  • DTSTART;VALUE=DATE:20020923
  • DTEND;VALUE=DATE:20020924

gives an event lasting the whole day. Or to be very precise:

  • DTSTART:20020923T000000
  • DTEND:20020924T000000

So what happens if your ics file generator does not adhere to this logic?

It may give the wrong  end dates, and tt may not be “subscribeable” – Certainly I cannot load into google or thunderbird any ics generated by “PRODID:-//WebCalendar-ics-v1.2.0”, as they do not follow this logic.  This may of course be due to other errors.  For example it also has no timezone definition.

So what should my plugin do?  For single day all day events, one can certainly check the dates, however for multi day all day events, there is no way of knowing what the event creator intended!.

Version 2.5.6 being uploaded as I type attempts to cope with the good and the erroneous!

Ical Calendar to html options

Ical RFC5545 / 2445, Notes

Some considerations in choosing a plugin or script to import one or more shared calendar ical feeds:

  • Completeness and/or robustness of ical implementation? vs type of dates expected by your application. A complete implementation may of necessity be more complex than a simple one. If your dates are simple, may be a simple solution is the answer. Or do you need to allow for all the variations of recurring specifications?
  • Does it cater for all the fields you need? (attendees etc….)
  • Box Calendar or List of Events (Agenda Style)
  • Verbose or concise text (eg: Mo, Tu vs Monday, Tuesday)
  • Explanatory Text options to change?
  • Hardcoded english? or are there language translation options?
  • Possibilities for css styling – does the html code produced allow adequate styling opportunities?
  • Caching? If you have a high volume site, or you want the calendar or agenda in your sidebar, then you need to cache the ics file to avoid placing too much of a load on the server that is hosting the ics file (and slowing down your site)
  • Can it handle or combine multiple calendars?
  • Will it repeat the recurring events per day? or does it note the fact that they repeat on the first day or the current day?

Resources

WordPress Ical (ics file) import options:

These are ‘old’ – please see http://webdesign.anmari.com/95/comparison-of-event-calendar-plug-ins/

 

 

  • http://wordpress.org/extend/plugins/wordpress-ics-importer/ This one looks good, not a full implementation of the code, but the code that is there is well structured, allowing for additional implementation in a clean fashion. Provides a cache. No language translation and alternative css and html options are possible, but not that obvious or easy until you dig into the code. One calendar at a time.