Event Organiser 3.0.0 changes the way the plug-in looks and, to a lesser degree, behaves on the front-end of your site, replaces some legacy API and increases the minimum WordPress version required.
While these changes are intended to be improvements to the plug-in, and most can be easily reversed, because they may impact the front-end of your site we are jumping from the 2.*.* branch to the 3.*.* branch.
Most changes relate to template and widget mark-up, which should never break a site, but may nevertheless change how your site looks – sometimes subtly. (If you have custom templates, you’ll be unaffected).
This post is a summary of such changes, and does not include other features or bugfixes included in 3.0.0 which won’t impact your site after upgrading.
First and foremost, Event Organiser now requires WordPress 3.8.0+ or better. The remaining ‘breaking’ changes can be summarised as follows
- A – Default Template changes – which can be reverted by copying the pre-3.0.0 templates into your theme. These existing templates will continue to work without any problem. Furthermore if your theme (or child theme) have custom templates, you will not be affected by these changes.
- B – Update of the fullCalendar – including stylseheet improvements
- C – Dropping support for legacy API – ‘legacy API’ here means refers to a part of the API that was deprecated in 1.6.0 or earlier (September 2012). This will only affect users with custom code using this API. No documentation or forum posts on wp-event-organiser.com uses, or has ever used, this legacy API.
- D – Agenda widget – this has been completely rewritten
A – Default Templates / Stylesheets
A1 – Stylesheets
Front-end stylesheets have been updated to remove the very dated jQuery UI look with a more minimal “theme”. This largely affects the fullCalendar shortcode and the date-picker for those selling tickets via Event Organiser Pro, or taking event submissions via Event Organiser FES.
There are several reasonse for this update:
- Replace an old looking UI
- Reduce the size of the default stylesheets
- Make advanced theme integration easier by releasing easily-themed LESS stylesheets for the plug-in (in progress).
- The new stylesheets use namespaced classes to help avoid ‘collisions’ with themes.
A2 – Templates
- Templates now include the end date/time as part of a range (the end date/time does not appear for all-day single-day events).
- There are some minor mark-up changes
- Events pages now display the start and end date as a range (unless the event is all day, and starts and ends on the same day). You can revert this behaviour by copying the
taxonomy-event-*.phpandevent-meta-single-event.phptemplates fromevent-organiser/templates(in version 2.13.7) into your theme. - Template ‘parts’ have been added, and the new default templates use this. However this is a non-breaking change: old templates will still function, and the theme will still take precedence.
- The class
entry-metahas been removed from theevent-meta-event-single.phptemplate, leaving just the classeventorganiser-event-meta.
B – fullCalendar
The fullCalendar jQuery plug-in used by Event Organiser has be updated from 1.6.1 to 2.2.6. The affects the calendar in the following ways:
B1 – Stylesheet
See A1 above
B2 – Responsive fullCalendar
On small screens, the fullCalendar switches to a list view. This behaviour can be disabled as follows:
[eo_fullcalendar responsive=false]
B3 – fullCalendar dateformats
This is ‘soft-breaking’: the options below no longer accept a ‘range’ format as the plug-in renders the format of date range based on the provided ‘single date’ format. The default values have been appropriately changed, so unless you have specified a format for these options you do not need to do anything.
Even if you have specified a range format, the plug-in attempts to ‘clean up’ any range format given to it, but such formats should be considered deprecated. As such while replacing the range format with a single date fromat is not essential, it is recommended. (See http://fullcalendar.io/docs1/utilities/formatDates/ for previously accepted ‘range’ formatting).
The affected options are:
- timeformat
- axisformat
- titleformatday
- titleformatweek
- titleformatmonth,
- columnformatmonth,
- columnformatweek
- columnformatday
B4 – day thresholds introduced
Previously, on the fullCalendar, if an event ran into the early hours of a morning it would appear as running on that day. For example an event that ran from 17th October 11pm to 18th 2am would appear, on the calendar, on both the 17th and 18th October. This can be confusing as we wouldn’t typically consider such an event to running on the 18th even though it technicaly is.
As of 3.0.0 such events will not display on the end date if the end time is before 6am. This affects only long events. This threshold is configurable, and to return the calendar to is previous behaviour you can do:
[eo_fullcalendar nextDayThreshold="00:00:00"]
C1 – Event start/end date API
Please note that all extensions are currently compatable with these changes. You should only be affected if you are running custom code using the API, and that this was added before 1.5.6 (September 2012)
These changes affect the following functions:
eo_get_the_start()eo_get_the_end()eo_the_start()eo_the_end()
Prior to 1.5.6 these functions accepted three arguments:
- The format in which to print/return the date
- The event ID (optional)
- The occurrence ordinal ( 1 = first occurrence, 2 = second occurrnece, 3 = third etc)
In 1.5.6 the third argument was deprecated, and the recommended method was to pass an occurrence ID as the fourth argument, and null as the third, e.g:
$start = eo_get_the_start( 'jS F Y', $event_id, null, $occurrence_id );
You can still do this, but from 3.0.0 it is recommened that you do the following instead:
$start = eo_get_the_start( 'jS F Y', $event_id, $occurrence_id );
From 3.0.0 any valued other than null passed as the third argument shall be assumed to be the occurrence ID. Such a value take precedence over the four argument which in such as case would be ignored.
Use of a fourth argument is now deprecated.
C2 – Deprecated eo_php2xdate()
This function converted a PHP datetime format into an XDate format. This function is no longer used by Event Organiser, and is deprecated pending removal.
D -Agenda Widget
D1 – Agenda Widget markup
A completely rewrite of the agenda widget has taken place. Although it looks and behaves largely the same, there have been mark-up changes.
D2 – Agenda Widget behaviour
The agenda widget ‘day mode’ behaviour has changed. It no longer shows multiple days at once, but only one day at a time. This brings it in line with ‘week’ and ‘month’.