Category Archives: amr ical events list

Posts related to Version Releases of amr ical events list

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

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

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

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

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

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.

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.

list showing recurrence-id and sequence
list showing recurrence-id and sequence

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

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.

Complete multi-lingual event website

To achieve a complete multi-lingual website using amr-events and amr-ical-events-list, the following are required:

the wordpress language files

These are required for the day, month etc event time localisations.  See this post for instructions and links.

your theme language files

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.

custom_language_file

 

Translation tools:

Finally a Language switcher and/or a multi-lingual language plugin. Some plugins that may help:

  • WPML (paid, used to be free)
  • Xili

Demonstration

lang.icalevents.com

Finding the Facebook events ics feed for subscribing or syncing

I’m not a fan of facebook…..however I get asked the questions, so have had to develop some familiarity, so here’s a quick reference until facebook changes things again.

Before you get too stuck in to facebook for your events,  look at oreilly.com’s advice on perhap not using facebook as the home for your public events.

Finding that public events ics feed in facebook

From a facebook ‘page’

They really do not make it easy do they ?  There is no obvious ‘Export all’ as there is in the personal page.  So…Pretend you’re only exporting one event from your page.

Example fb page
Example Facebook page – events page

Click the event

The facebook events lists, click export.

Click export.

Choose subscribe to all events, or right click and copy the link address

Copy that webcal ics address and use it wherever you need to subscribe to that set of events.

From a personal homepage

After logging in look for the export events option, not just for one event but ALL upcoming events.

Go to your all events page:   https://www.facebook.com/events/list.

Click "Export"In the top right corner, see the little gear icon, click it and click the export option.

 

You should get a popup window.

export facebook ics
export facebook ics

If you just want the url to subscribe to it from another application, right click and ‘copy the link address’. Paste it in to your calendars subscribe url option.

Alternatively if you just click on it, your calendar application should open up and hanlde the subscription process for you.

Use it in the ical events plugin?

facebook in shortcode
facebook in shortcode

Bear in mind that the plugin caches the url’s, so you may need to force a refresh (add ?refresh) to the calendar page url and refresh the page in your browser.

eg:

 

Other possibly useful references:

External ics files timing out?

Slow server? Ics refresh problems too frequent?

In version 4.0.24 of amr-ical-events-list, the default http timeout in wordpress can be extended for ics fetches.  5 is the wp default.

Note: using a large number may mean that your calendar page will be slow when it is time to refresh the ics files.  Consider the cache frequency too.

See also

Advanced admin settingfor timeouts

How to tell if necessary?

If you occasionally see a little exclamation mark on your calendar page – this is an attempt to warn you that  a cached version of the ics file is being used and events may be out of date.  Hover over it to see the message.

Want more info ?

If you are a logged in admin user, add ?debug&refresh to the url and hit refresh.  A debug listing will be produced while it tries to refresh. Scroll down to see the result.

Debug message for logged in admin users
Ics file does not exist

Problem with Dates/Time – Off by 1 Hour?

If you are using amr-events or amr-ical-events-list you will not have this problem!

Every time a zone somewhere in the world kicks on to daylight saving or off for that matter, I see a bunch of support questions popping up about their event times being off by an hour.    (I monitor wordpress support, stackexchange and wpquestions, and maybe a few more…..)

From a favourite cartoon source - thanks http://xkcd.com/673/

Imagine the confusion this can cause where clients may have subscribed to calendar feeds and have the wrong times.

PHP datetime objects and functions

If people are very lucky, the plugin that they are using has some good coding and is using php DateTime objects with timezone support, and the only problem is that their wordpress timezone is set as a GMT offset, not as a timezone.

That is easily fixed! (goto wordpress general settings)

However all too often the plugin developer has failed to appreciate

  • the complexities of times around the world,
  • timezones,
  • daylight saving and
  • most importance of managing recurring events in one timezone for a display in another where one zone changes daylight saving.  Very easy to generate the wrong times for a recurring event without realising it!
  • even worse governments sometimes change the date/time of the switchover (ok not that often, but it does happen, and then you hope your php installation gets updated with the timezone definitions)

Fixes:

If it is not a simple wordpress timezone setting, then these things are NOT easy to fix and will involve changes to code:

  1. Change to use php DateTime Classes for all date logic .If they are using unix time and not  php datetime objects, it is almost impossible to get it right.  It’s a fairly major rewrite to change all date logic to use the DateTime objects and functions.
  2. If already using, it maybe that the intricacies of recurring event logic have won out.  See below for logic help.

Developers and event website managers should read:

 

 

Horizontal Weekly Calendar

A horizontal weekly calendar is now possible (in a few hours anyway).

It was requested a while back by autrice. Then I saw the sydney 2011 film festival schedule and I thought…

… hmmmm we could do that.

Sydney Film Festival Schedule Styling
Sydney Film Festival Schedule Styling - possible with amr-events

From amr-ical-events-list version 4.0.5 onwards use shortcode [weekscalendar]. You will need the new list type 11.  It is not exactly  the same as above.  If you really want the sff.org style, only show the summary and the event date and times.  Set all other columns to 0.

Don’t panic if you do not want to reset your list types to get the new defaults. Simply use your local test server (You do have one don’t you? you don’t do everything live …. no of course not, I didn’t really think so.)

In your test server, reset the list types, then copy list type 11 over to your main server (after suitable testing etc.)

Colour it with some category, tag or taxonomy styling.

Version 4.0.5 also offers css classes by id,  – so that you can change the category slug with breaking your styling.  All id’s will be prefaced with ‘t’ (for term,tag, or taxonomy or caTegory :) )

Maybe add some css like:

#events_wrap .eventscat,
#events_wrap table tr.eventscat td.amrcol1 {     
 border-left: solid 5px green;
}
#events_wrap table tr.t1 td.amrcol1 { 
 border-left: solid 5px red;
}

Have fun…

Oh, by the way, you always could do a weekly vertical agenda too, I’ve added a sample listtype for that too (no 12).