Category Archives: Notes

General Notes

An accent for your website

Have you ever wanted to change the original text for a plugin?  Do you have an audience who would respond to their unique way of speaking being used on your website?

Even if you’re english and it’s in english you can still “translate”.

WordPress is so amazing when it comes to language support (if theme and plugin developers have done their job well)

  • it will use a language file if it finds one
  • it will use a translation if there is one, else will revert to the default language
  • it allows for variations of language (en_US, en_AU etc)

So if you want to talk strine, BBC, cockney, singlish, na’vi or Klingon,  for at least some of the phrases in a plugin or theme, it’s easy. (I’n not bunging it on, you Can la!)

Update on 2016 October 7th:  This is all much easier now with the use of a plugin like      Simply ensure that the language for which you are adding a new text / translation is one which is either the main wordpress language or selectable by your users.

Already have system translations in that language?

You may need to override existing translations

  • Drop the code at the bottom of the post into your plugin or theme’s functions.php.
  • Decide which locale code to use-  the default wordpress language for your site (for English it is en_US) or  a variation ? (en-GB, en_au ) .  If not using the default you will need to change your  wp-config.php file to tell your wordpress your preferred locale.
  • Create a translation file with just the texts that you want to translate.  For example using loco translate or code styling localisation plugin (old, still works for me)

    1. Select the theme or plugin,
    2. click add new language and enter the locale code.  It will appear in the list of language files for that plugin or theme or wordpress core
    3. click edit against the language
    4. Scroll to the texts you want to  change or “accentise”
    5. Enter your text as the translation, SAVE
    6. after you have entered your translations, most important – generate the .mo file
  • Put the .mo file into your wp-content/languages folder
Screen shot of language folder

the link to clickenter a translation

It’s a link text, and here it is

the translation in action

Don’t like the menu text ? translate it!

Change the menu text

Have some fun!

Just pick a few key phrases (they must be translateable) to make an impact.

Your website could talk like a pirate just for a day – drop the .mo file in on the day and delete it afterwards!

Danger of upgrades

An upgrade may overwrite your translations, so save it somewhere other than the main plugin language folder .  The amr-events plugins looks for language files with the plugin language text domain in the wp-content/languages folder before looking in the normal place.

The loco translate plugin offers you choices as to where to save your translation files.

Locating your language file for the amr-events plugins in the wp-contents/language should be safe from upgrades.

For other plugins you could write a quick filter function to point to your special file.  WordPress now has several filters that can be used.  The best for this purpose may be:

$mofile = apply_filters( 'load_textdomain_mofile',
                     $mofile, $domain );

Suggested Filter Function

if (!function_exists('amr_load_custom_text') ) { // for filter
	function amr_load_custom_text( $mofile, $domain='' ) {
	//only do for the plugins/themes you want
	if (!in_array($domain, array('amr-ical-events-list', 'amr-events')))
        return $mofile;

    $pathinfo = pathinfo($mofile);
	$custom_mofile = WP_CONTENT_DIR."/languages/" 
            . $pathinfo["basename"];
	if (file_exists($custom_mofile)) 			
			return ($custom_mofile); 
			return $mofile;
add_filter ('load_textdomain_mofile','amr_load_custom_text',10,2 );

Works a treat!

Want your website events to appear in facebook?

This icalendar to event facebook application looks like it would do the trick.  Use amr-events (or any such plugin) to generate a valid ics feed.  Add that to the application and there you should have it – integration from your wordpress events into facebook .

Note: reviews seem to be polarised (very good or very bad), and it does have a lot of users.  Note:   I have found facebook very SLOW to update either way and can imagine this may cause some of the dissatisfaction. That said I am not using this application myself, just thought it might be useful.

Reverse direction?

To go the other way, you need

  1. Activate the plugin
  2. Drop  [events ics=facebookicurl] or [iCal ics=facebookicurl]  into  a page.
  3. Publish!

amr-events v1.9.1 minor updates

Stupid Mistake was made
Part of photo by Sarah Derr

This is a minor update for those who  already upgraded to 3.9 – the free version) , or (in either amr-events 1.9 or amr-ical-events-list 3.9 ) use the ‘”lists for rows” with a grouping’ – ie like the widget default but with a grouping added in.

There may be another update along in a couple of weeks with some additional features that have been requested.  If you have a wished for feature, let me  know and i’ll see if I can add it in too.

Change log:

  • Fix: removed a debug statement that displayed in free version of amr-ical-events-list
  • Fix: default event url in list type settings should not be mandatory.
  • Fix: for list type using “lists” not table, and when one uses a grouping, the html validation failed due to a missing html tag.  This highlighted some minor things in the html that could be cleaned up – and so they have been (cleaned up)

Thanks to Barisko and Polyfade for identifying and letting me know.

Multi-day events and the calendar view

If one is listing multi day events such as an art exhibitions which show for a week say, please evaluate whether to create

  • a single multi day event or
  • a daily recurring event.

For example, consider whether you wish to show opening and closing times each day. This would allow someone to add the instance of the day that they wish to attend to their calendar, rather than adding the whole long exhibition to their calendar.

A recurring event is best for showing opening and closing times.

Recurring events

If you open up the “repeats” tab in the event creation, you will find you can specify in all sorts of weird and wonderful ways the recurence of you event:

eg: daily (m,t,w,th,fr only) or every 2nd day etc

Agenda or Calendar View

Also consider how the two options will appear in the agenda or calendar view.

In the Agenda view, a single multi day event, where it is only listed once on the day that it starts, may look best for each exhibition. (Note an event will be displayed if it is still ongoing even if the start date has passed.)

In the calendar view, if you wish to have the event appear on each day, at the moment, a recurring event is required.

The Plugin, Calendar View and Single Multi day events

Currently the plugin does not display an event on more than the day that it starts.  Doing otherwise requires some complex css to force the event to stretch across the day cells.  It would also require  the plugin to temporarily create some dummy events where the event goes across week rows.  Achieving consistency of appearance when there are other events on on that day would be quite tricky, particularly ensuring cross browser support.

This feature may be available at a later stage.

Custom wordpress feed issue (for ics feed)

For users of amr-events:

If you are:

  • using or offering your users the ics feed (to subscribe to whole calendar) and
  • you have more than 10 (or more accurately, more than your posts_per_rss feed parameter setting) active recent events, then please either
    1. In your wordpress settings> reading increase the “Syndication feeds show the most recent” (aka “post_per_rss”) setting to a number larger enough to cover all the events that you wish to include in the calendar subscription feed ( temporarily until the next larger upgrade – there should be one with additional features before Christmas).  This will also update the number of posts that show in your rss feed.       or
    2. upgrade to amr-events v 1.1.1 or
    3. manually apply the small code change below.

Code Change:

1. In file wp-edit-event.php, right near the bottom around line 604, find function ical_adjust_query. At the top of this function,before the other code  add:

//  if the query is doing the ics feed, then we need to make doubly sure that it will get all feeds, since wp overwrites the post_per_page parameter.

 if (isset ($query->query_vars['feed']) and ($query->query_vars['feed'] == 'ics'))
     add_filter('post_limits','amr_no_limits_for_feed'); // this filter will clear the  limits

2. Then above  function ical_adjust_query, add a new function:

function amr_no_limits_for_feed($limits) { //wordpress overwrites our 'unlimited posts_per_page' parameter if the query is n a feed and imposes the rss feed limit.  This will remove the limit. Only call if it is a ics feed
 return ('') ;


A user of amr-events (Shourin Sen , using the plugin for ip, entertainment and art law events) brought to my attention that the ics feed was not showing all events – it was behaving like an rss feed – only showing the last x events.

This was very puzzling since the ics feed code uses the same functions to get the event posts as the shortcodes and the widgets and they got all the data they needed.   It seemed like the “posts_per_page=-1” argument passed was being ignored when in the feed.

post_per_page = -1 is supposed to fetch all posts.

I dug down into the wordpress code and at line 1687  in wp-includes/query.php found that if the query was in a feed, then wordpress fetched the “posts_per_rss” option and overwrote (without checking) whatever value was in post_per_page.

Is this a wordpress bug?

Maybe? – there may be a case for ignoring the parameter in case plugin or theme developers forget that changes they make to the query may impact the feed to,  although all the other examples do suggest checking whether in a feed or not before applying changes to the query, so arguably the wp code should not just overwrite it.

Certainly the codex needs to highlight this to help developers.  Therefore I have updated the wordpress documentation  in a couple of places, but I have not logged it as a bug in the wp trac.

Feedburner plugins and ical feeds

If you are using feedburner and a ical plugin that generates feeds, then please use the, rather than the feedsmith plugin.

The FD plugin allows for the possibility of some other feed (like an ical feed naturally!) and so will not hijack your ics feed like the feedsmith one does.


  • a simple hack to the google feedsmith plugin to check the global $feed variable and bail if it = ‘ics’ would also do the trick!
  • or if you maintain good coding standards and don’t like editing external plugins (not a good idea generally!), then you could muck around with the wordpress action template_redirect and see if you can remove the feedburner redirect IF it is a ics feed.

How should one break long urls in event content? aka too wide tables

One uncontrollable part of allowing users to create events is that they may not be “good” about entering links.  If they enter a full url that is quite long, this could cause the calendar listing content to overflow.  How this appears visually depends on your theme’s css and your browser.   In IE it could be this:

Loooong Urls

The ical-events-list plugin automatically makes links ‘clickable’ if they are not already.  This is desirable most of the time, however if the link is really long, then we have the long url problem, which is how I came to look at this question.

There are a range of possible answers from getting the table to deal with it, the cell to deal with it and avoiding if by modifying the link text.

Modifying the link text

Possibly the most stable version in the long run with the downside that users cannot cut and paste the link text as url, they have to know to select the “shortcut” or link address.

For the plugin, this is probably the safest answer as I prefer to let the theme css work so that the styling is consistent with the theme as much as possible.  It will also not interfere if the link is not too wide, or is not a url.

Version 3.0.2 will trim the event hyperlinks:

Trimmed urls

Coping with a wide table

A suggestion from

Css3 options:

  • word-wrap: break-word has some browser support
  • word-break: (normal, break-all, keep-all) aimed at dealing with mixed character sets.  Random Break Point.


Need to know the possible combinations for repeating dates? – an Ical cheatsheet

The ical specification allows one to define some very interesting and complicated date recurrences.  This table (adapted from was very useful when I decided to rewrite the recurrence engine part of my plugins.

Sorry about the table width – got to get that theme css fixed!

Yearly Monthly Weekly Daily Hourly Minutely Secondly
BY MONTH (1 to 31,  -1 to -31) Expand Limit Limit Limit Limit Limit Limit
BY WEEK NO (1 to 53, -1 to 53) Expand invalid invalid invalid invalid invalid invalid
BY YEAR DAY (1  to 366, -1 to -366) Expand invalid invalid invalid Limit Limit Limit
BY MONTH DAY (1 to 31, -1 to -31) Expand Expand invalid Limit Limit Limit Limit
BY DAY (MO, TU , WE, TH, FR, SA, SU) Note 2 Note 1 Expand Limit Limit Limit Limit
BY HOUR (-23 to 0 to +23) Expand Expand Expand Expand Limit Limit Limit
BY MINUTE (-59 to 0 to 59) Expand Expand Expand Expand Expand Limit Limit
BY SECOND (-60 to 0 to 60) Expand Expand Expand Expand Expand Expand Limit
BY SET POS (-366 to -1,1 to 366) Limit Limit Limit Limit Limit Limit Limit

The “By”‘s are applied in the order indicated. Limit means that the possible repeat dates are limited by the “BY” specification.  Expand means that the possible repeat dates are expanded by the BY values.  The start date will fill in any missing year, month, day, hour, minute or second values.  See the RFC 5545 Specification for examples.

Note 1:

  • Limit the dates if BYMONTHDAY is present;
  • else special expand for monthly


  • Limit if BYYEARDAY or BYMONTHDAY is present; otherwise,
  • special expand for WEEKLY if BYWEEKNO present; otherwise,
  • special expand for MONTHLY if BYMONTH present; otherwise,
  • special expand for YEARLY

What every developer ought to know about timezones wrt calendar files

A timezone definition consists of

  • a ID
  • a name
  • a standard time definition with a gmt offset
  • daylight saving time definitions with a series of daylight saving transitions (as rules have changed over time

Ideally every system around the world should be using the same definition of timezones.  However not all systems are kept up to date when a government decides to change a transition time.  In addition not all systems use the same naming conventions, so while to the human it may be obvious which timezone is being referred to, a program has to do some deductions.

Most calendar applications appear to use the olson database or similar.  Windows PC take a slightly different approach, with a requested time change on the first reboot after daylight saving change.  Windows based application issue different timezone ID’s.

A calendar application can decide on it’s own timezone id’s. They have to include the definition (The VTIMEZONE) with the daylight saving changes in the file, however this can be their own version of the timezone definition

What if the issuing application has an outdated version of the daylight saving changes?  Would you not rather control it on your server than taking their definition?

Global Timezone Database

Php, WordPress, Google, Linux (Ubuntu), Apple

These all appear to use the timezone database aka Olson Database.  It has timezone identifiers like:


A few months ago, Issued no TZID, no VTIMEZONE, all dates local / floating and just this : X-WR-TIMEZONE;VALUE=TEXT:Europe/Oslo

Mozilla sometimes has great fun confusing people:


Recently I dealt with an ics file that had no TZID, no VTIMEZONE, all dates local / floating

Microsoft Windows PC, Microsoft Exchange

Setting TimeZone in Windows Vista

Microsoft exchange, Windows PC’s and by extension any application that runs on the PC that uses the windows timezones does the gmt offset thing

(GMT+10:00) Canberra, Melbourne, Sydney.

Now Sydney has daylight saving, so we are only GMT+10 for half the year.  The rest of the time we are GMT+11.  If we happen to choose the GMT+11 option for our setup thinking it was more correct we would be wrong…..

What windows does is technically not wrong.  They acknowledge the daylight saving and you can choose to have it automatically update… WHEN you REBOOT the PC, the times will update.

It is however potentially misleading, unnecessarily so.  Particularly around the actual daylight saving change, errors may occur, due

  • an ‘old’ ics file perhaps – the one issued before the times were updated ?, or
  • to applications not always handling the timezone  correctly – It would be very tempting as a programmer to grab that GMT+10 and use that.  Just google things like my meeting is one hour out etc to get a feeling for the problem.

What does this mean for developers using calendar files?

Well it depends a bit on the application issuing the ics file.  You could have to deal with any of these timezone values:


  • TZID:America/New_York
  • DTSTART;TZID=”America/New_York”:20080807T090000
  • X-WR-TIMEZONE:Europe/London
  • TZID:Europe/London
  • DTSTART;TZID=Europe/London:20060707T130000
  • TZID:Canberra\, Melbourne\, Sydney
  • DTSTART;TZID=”Canberra, Melbourne, Sydney”:20100831T210000
  • DTSTART;TZID=”(GMT+01.00) Amsterdam / Berlin / Bern / Rome / Stockholm / Vienna”:20100831T16000
  • TZID:(GMT+02.00) Harare/Pretoria
  • DTSTART;TZID=US/Central:20080726T190000
  • DTSTART;TZID=”(GMT) Greenwich Mean Time – Dublin / Edinburgh / Lisbon /
  • TZID:/

Windows – assessed using Windows Calendar

Windows Calendar Ics file

Windows calendar defines the TZID with a VTIMEZONE definition

TZID:Canberra\, Melbourne\, Sydney
TZNAME:AUS Eastern Standard Time...

and then uses it in the ics file

DTSTART;TZID="Canberra, Melbourne, Sydney":20100831T210000

This is correct according to the spec and not too hard to deal with.    The developer can grab each city and check for a matching timezone on their host system.

A minor gripe is that if you import this into Google and then share the resulting google calendar file, Google will decide to go with Melbourne, even if the rest of your calendars are Sydney.  This may offend some. ;-)


I’m told that Zimbra issues ics files with :

DTSTART;TZID="(GMT+01.00) Amsterdam / Berlin / Bern / Rome / Stockholm / Vienna":20100831T160000

I don’t know whether a VTIMEZONE was included or not.  AS noted before grabbing that GMT+01 may cause incorrect times when daylight saving is involved.

At the very least the reading application  has to deal with that somehow. Possibly by tossing the GMT parts away and looking for the cities again.  My events plugin will do this in the next upgrade

Mozilla / Thunderbird

Mozilla plays nicely (with php anyway!)

PRODID:-// Mozilla Calendar V1.1//EN

Reading the VTIMEZONE definition?

Somehow working with the timezone definition passed in the ics file – Is this an option ? – well maybe – I shudder to think how though. Imagine the confusion if some dates in your website knew about one set of daylight saving and others were obeying the possibly different definition in the ics file. PHP encourages us to use it’s timezone definitions. It has functions to do a variety of timezone functions, but uploading daylight saving changes into a timezone object is not one of them. (Probably a good idea too).

Parsing Timezone Ids

If you are developing an ical parser, I believe that the best approach (wrt correctness and usability) is

  1. attempt to determine the desired timezone from the TZ id (toss those GMT’s if you have too)
  2. match to a timezone identifier that is already in your system, and then use those consistent daylight saving changes
  3. and of course use the DateTime object class – do not mess around with unix time that breaks on old dates.
    Dates, Times, Timezones, daylight saving etc are so fraught with danger (see the best of dates, the worst of dates), that one must use pre-tested logic as much as possible, and there are some very useful functions there.

My amr-ical-events-list plugin

For the record, my plugin will attempt to cope with all of these variations (and more if anyone tells me about them).   If we can extract some city names, it should be easy to match it at least one to the php timezones:

  • explode the names out, stripping off all the quotes, slashes etc
  • If a timezone has been specified in the shortcode, and it matches the city name, then it will deduce that is the timezone
  • If the wordpress timezone  matches the city name, then it will deduce that that is the timezone
  • Else if will attempt to find a match in the php timezone names list (which it should unless something really weird is going on)
  • Else if all that fails, it will just use the wordpress timezone as the base timezone for the events.

Extract From

This property parameter specifies a text value that uniquely identifies the “VTIMEZONE” calendar component to be used when evaluating the time portion of the property. The value of the “TZID” property parameter will be equal to the value of the “TZID” property for the matching time zone definition. An individual “VTIMEZONE” calendar component MUST be specified for each unique “TZID” parameter value specified in the iCalendar object.

Failure to include and follow VTIMEZONE definitions in iCalendar objects may lead to inconsistent understanding of the local time at any given location

The presence of the SOLIDUS character “/” as a prefix, indicates that this “TZID” represents a unique ID in a globally defined time zone registry (when such registry is defined).

Note: This document does not define a naming convention for time zone identifiers. Implementers may want to use the naming conventions defined in existing time zone specifications such as the public-domain TZ database [TZDB]. The specification of globally unique time zone identifiers is not addressed by this document and is left for future study.

Do you need BYYEARDAY for your events?

Is BYYEARDAY useful enough ?

ByYearDay allows the user to enter days of the year to repeat separated by commas (1,2,…366,-366,-365…-1). Almost every real example can be represented in a more user friendly fashion using other ‘BY’s such as BYMONTH and BYMONTHDAY


Only leap years affect whether the 72nd day of the year is 31+28+13 = March 13 or 31+29+12 = March 12. It’s just not useful enough to schedule a meeting on “March 13, except March 12 if it’s a leap year” and that kind of use case can be worked around. (One special case might be to state that a RRULE that occured yearly on Feb 29 might automatically recur on Feb 28 if not a leap year). Without BYYEARDAY we’d see rules like “RRULE:FREQ=YEARLY; INTERVAL=1” and the date would be March 12 every year.

For this reason, at launch, the amr events plugin does not offer a BYYEARDAY entry option on the edit event screen. It will however read BYYEARDAY’s entered in ics files and apply the necessary recurrence rule and included in any calendar listing.

Does your group need BYYEARDAY ?

If your website needs to be able to offer entry of recurring dates using BYYEARDAY for it’s members, it will be easy to add.  It is beingexcluded to avoid cluttering the screen unnecessarily.