Event Organiser 3.0.0 (release candidate)

Event Organiser 3.0.0 is due to be released in January 2016, and is the biggest update to date.

While there are some fairly obscure breaking changes, mostly the API changes are backwards compatible. There is, however, a major revamp of the calendar shortcode – and in particular its appearance – as well as some minor tweaks to the default templates.

Download 3.0.0-rc-1

General

3.0.0 brings with it substantial improvements in performance, particularly for sites with long recurring events or a large number of venues.

There is also improved support for UTC-offset timezones, but it is nevertheless strongly recommended you chose a city. Support for UTC offset might be limited by your PHP versions.

Calendar shortcode

The calendar’s appearance

This is the biggest change to the plug-in. The old “jQuery UI” look as been removed, and replaced with something far more minimalistic, and more easily adjusted by the theme.

Responsive

The calendar is now responsive (by default), and collapses to a list view on mobile devices. You can disable this with the following:

[eo_fullcalendar responsive=false]

Compact view

You can also display the calendar more compactly by reducing events to one-line and truncates long titles. This helps improve the readability of the calendar when there are a lot of events. This can be enabled as follows:

[eo_fullcalendar compact=true]

Next-day threshold

Previously, late-night events which finished in the early hours of the next morning appeared on that date in the calendar. In such a context this can be produce a poor user experience: if an event is running from Friday 10pm until Saturday 3am, it would be confusing to see that event on the Saturday (as well as Friday).

The nextDayThreshold attribute allows you specify a time (Default ’06:00:00′, 6am) after which a multi-day event must finish in order to appear on that day. So the event in our earlier example would only appear on the Friday, whereas an event from Friday 10pm until Saturday 6:30am would appear on the Friday and Saturday.

To disable this:

 [eo_fullcalendar nextDayThreshold=00:00:00]

Additional attributes

You can now use the showDays attribute to specify which day(s) appear on fullCalendar shortcode (day & week views):

 [eo_fullcalendar showDays="MO,WE,TH,SU"]

The aspect ratio of the calendar can be set with the aspectratio parameter which can be used to set the height/width ratio (higher means larger height). By default the calendar automatically adjusts its height for the content.

 [eo_fullcalendar aspectratio=1.35]

The time duration of the ‘slots’ or ‘rows’ in agenda view can be configured via the slotDuration attribute (default: ’00:30:00′, 30 minutes)

 [eo_fullcalendar slotDuration=01:00:00]

The key attributes can now take the value ‘top’ or ‘bottom’, e.g. [eo_fullcalendar key="bottom"] to configure the location of the category colour key.

Formatting date titles/axis

Specifying a ‘range’ format is no longer supported, and the calendar will now automatically split date(time) ranges appropriately.

Templates

Improved theme compatibility

By default, new installs of Event Organiser will have theme compatibility mode enabled: the plug-in wil insert the events pages into your theme’s template for an actual page, and applies additional styling. This means, out of the box, the plug-in is likely to work better with a wider range of themes.

Existing installs are unaffected, and if your theme has an appropriately named template, that still take precedence. Additionally you can instruct Event Organiser to leave all template handling to the theme by adding:

 add_theme_support( 'event-organiser' );

to your theme’s functions.php

Site admins can also disable this in the plug-in settings.

Templates include end dates

With the introduction of date range formatting (see Formatting ranges below), the templates now include the event date as a range, for instance, 28th January 2:30pm – 3:30pm, for a single-day, part-day event.

Please note that single-day, all-day events shall display only the start date.

More template parts

Previously each of the default templates duplicated a lot of code (e.g. looping through events, or rendering an individual event). If you wanted to change the mark-up for an event on the event pages you would have to edit multiple templates.

The new improved templates adhere to the DRY principle (Don’t Repeat Yourself), each page template includes common ‘template parts’ for rendering page navigation, event loops and each event – so if you wish to edit how events appear, you only need to do it one place.

Added hooks

There are two new hooks relating to plug-in stylesheets. They allow you to either ‘map’ the stylesheet to another one, or change the location of a stylesheet: making it even easier for themes to replace, move or incorporate styling for Event Organiser into their themes.

The first: eventorganiser_stylesheet_src_{handle} filters the stylesheet’s location. This allows for themes to map the plug-in’s stylesheets to its own stylesheets.

add_filter( 'eventorganiser_stylesheet_src_eo_front', function( $src ) {
     //This will load the front end stylesheet from themes/your-theme/event-organiser.css
     //rather than use the stylesheet in plugins/event-organiser/css/eventorganiser-front-end.css
     return get_stylesheet_directory_uri() . 'event-organiser.css';
} );

The second: eventorganiser_stylesheet_handle_{handle} allows themes/plugins to map a CSS file to a different one.

add_filter( 'eventorganiser_stylesheet_handle_eo_front', function( $handle ) {
     //Whenever eo_front is enqueued by eo_enqueue_script() it will instead
     //enqueue the script 'my-theme'
     return 'my-theme';
} );

Event API changes

Getting/printing an event’s start and end date

There is a breaking API change. Specifically there is a change to the parameters that are given to eo_get_the_start() and eo_the_start() functions (and eo_get_the_end()/eo_the_end()).

Currently, the documentation states that you should use this function as follows:

 eo_get_the_start( $format, $event_id, null, $occurrence_id );

and that will still work. But why the null value? That third argument had once-upon-a-time been used to accept the ordinal number of the occurrence (1 for the first, 2 for the second occurrence etc.) which was used to identify the occurrence instead of its ID.

That use of the third argument was never publicly documented and has been deprecated since 1.5.6 (September 2012), it is now being resurrected to take the occurrence ID instead. So now you should do the following:

 eo_get_the_start( $format, $event_id, $occurrence_id );

Formatting ranges

The event API also has a useful addition in the form of eo_format_event_occurrence(). This function will format the start and end date(time) of the specified occurrence, according to the given format – displaying it as a range where appropriate.

So for example:

echo eo_format_event_occurrence( get_the_ID(), eo_get_the_occurrence_id(), 'jS F', 'g:ia', ' - ', false );
//prints 28th January 2:30pm - 3:30pm for a single-day, part-day event
//28th-29th January for a two-day (and all-day) event
//28th January for a single-day, all-day event

The resulting date depends on the date/time format options, and whether the event is multi-day and whether is all-day.

Additionally you can set the sixth argument to true (actually, its default value) to include microdata:

echo eo_format_event_occurrence( get_the_ID(), eo_get_the_occurrence_id(), 'F j, Y', false, ' - ', true );
//prints <time itemprop="startDate" datetime="2016-01-28">January 28, 2016</time>

Rendering taxonomy dropdowns

Other changes include deprecating eo_event_venue_dropdown() in favour of eo_taxonomy_dropdown() (although the former will still work).

//Instead of
eo_event_venue_dropdown( array(
   ...
) );

//Use
eo_taxonomy_dropdown( array(
   'taxonomy' => 'event-venue',
   'class'    => 'postform event-organiser event-venue-dropdown event-dropdown', //optional!
   ...
) );

Widgets

The agenda widget ‘day’ mode now behaves consistently with the week/month mode and displays only one day at a time.

The event list widget now allows you to list events in certain scopes (e.g. past events, future events, running events, events on today).

Additional ‘scopes’ can be registered with the eventorganiser_query_scope filter:

 add_filter( 'eventorganiser_query_scope', function( $scopes ) {
      $scopes['coming-week'] = array(
           'label' => __( 'Events starting this week', 'eventorganiser' ),
           'query'  => array(
                'event_start_after'  => 'now', //future events
                'event_start_before' => 'next Monday', //which end before next Monday
           ),
      );
      return $scopes;
 } );

Improved iCal feed

The iCal importer is more forgiving when importing incorrectly formatted iCal feeds. It also supports the DURATION attribute is now supported.

For calendar clients subscribing to your site’s feed a long-standing bug with recurring events across a timezone has also been addressed.

Accessibility

This is an ongoing process, and any bug reports, feature suggestions and pull requests are welcome in this respect.

The admin (and frontend) calendar is key navigable by keyboard shorts. On the admin calendar you can view the keyboard shortcuts by pressing shift + ?.

There have been a whole host of other improvements, but this is still an ongoing process.