Events List

The event list shortcode can be used to display a list of events. Using the attributes you can show events in particular categories, venues, date-range or a combination of both. You can also change the appearance and the content (i.e. what details are displayed). See the section Customising the look of the event list below.

Usage

 [eo_events att1="val1" att2="val2"]

Or when using template tags (see below)

 [eo_events att1="val1" att2="val3"] A custom template here [eo_events]

Attributes

The shortcode automatically inherits attributes supported by eo_get_events(). For example sorting by event start/end date, querying by taxonomy (Note: hyphens in event-venue, event-category, etc should replaced by underscores).

Because eo_get_events() inherits arguments from get_posts() – you can use the arguments for get_posts() (see codex) in both eo_get_events() and this shortcode.

Therefore, an incomplete list of supported attributes is the following:

  • venue – the venue slug (must be a string). Alternatively you can use “%this%” to set Venue to the Venue of the current event.

  • event_start_before – Events that start before date given as a string in YYYY-MM-DD format or relative format. There is no default value.

  • event_start_after – Events that start after date given as a string in YYYY-MM-DD format or relative format. There is no default value.

  • event_end_before – Events that end before date given as a string in YYYY-MM-DD format or relative format. There is no default value.

  • event_end_after – Events that end after date given as a string in YYYY-MM-DD format or relative format. There is no default value.

  • ondate – Events that start on this specific date given as a string in YYYY-MM-DD format or relative format. There is no default value.

  • showpastevents – True or False. If set to false, excludes events that have already started. Default value is set in Event Organiser settings page.

  • group_events_by – ‘series’ or ‘occurrences’. Defaults to ‘occurrences’ (effectively no grouping). If set to ‘series’, only the next occurrence of a recurring event is displayed.

  • event_category – The slug of an event category. Please note that this should be used instead of the parameter event-category used in eo_get_events.

  • numberposts – The number of events to display.

  • users_events – If true display only events for which the current user is attending

  • no_events – A message to display if they are no events matching the query.

Customising the look of the event list

There are two ways of customising the appearance of the event list and changing what details are displayed:

  • Wrapping the shortcode arround content which includes placeholder tags.
  • Using a template file in your theme, which gives you a greater degree of freedom. This is the preferred method, but you cannot use it when you are using placeholder tags.

Method 1: Template

This is the preferred method. It requires at least a familiarity with how php works, but offers complete control over the style and content of the event list (and indeed if it displays a list, or a table, or in any other format).

Simply copy shortcode-event-list.php from wp-content/event-organiser/templates/ into your theme and edit it there.

To display event details you use the various functions available to you. For example eo_get_the_start() and eo_get_venue(). Full documentation of available functions can be found at the codex.

If you use the shortcode with placeholder tags this template will be ignored

Method 2: Placeholder Tags

Content wrapped in the shortcode is used to display each event in the list. The plug-in supports numerous tags (some with options) that can be used as placeholders for event details. For example

[eo_events] <a href="%event_url%">%event_title%</a> on %start{jS M Y}{ g:i:a}%, at %event_venue% [/eo_events]

The following template tags are available

  • %event_title% – The event’s title

  • %event_title_attr% – Same as above but sanitises the title for use as an attribute.

  • %event_url% – Link to the event’s page

  • %start% or %start{date-format}{time-format}% – The event’s start date/time. The format of the date and time can be specified appropriately:

    //Format date in '18th February 2012' format. No time format.  
 $start{jS M Y}%

//Format date in '18th February 2012 at 1:30pm' format. 
 $start{jS M Y}{ at g:i:a}% 

//Format date-time in '1:30pm' (no date part) format. 
 $start{g:i:a}{}% 

//Format date-time as given in WordPress' general settings. 
 $start%

Please note the ‘time format’ option is only used for non-all day events, and date/time formats can be used in either option. The date-time formats are those accepted by PHP datetime.

  • %end% or %end{date-format}{time-format}% – The event’s end date/time. Similar to above.

  • %schedule_start% or %schedule_start{date-format}{time-format}%: The event’s series start date/time. Similar to above.

  • %schedule_end% or %schedule_end{date-format}{time-format}%: The event’s series last start date/time. Similar to above.

  • %event_duration{date-interval-format}% The duration of the occurrence. A date interval format must be supplied. Please see php’s DateInterval documentation for details on supported formats. Example: %event_duration{%d days %h hours %i minutes}%.

  • %event_cats% – Displays the list of the event’s categories with links to the category pages.

  • %event_tags% – Displays the list of the event’s tags with links to the tag pages.

  • %event_content% – Display’s the event’s content

  • %event_excerpt% – Display’s the event’s excerpt. Optionally set the the word limit: %event_excerpt{30}%

  • %event_thumbnail% – Displays event’s thumbnail. (Optional) the size of the thumbnail as a preregistered string keyword (thumbnail, medium, large, full etc). A second optional ‘attribute’ argument is passed as a string to to get_post_thumbnail().

  • %event_custom_field{key}% – Displays event’s custom field value for a given key.

  • %event_venue% – The name of the event’s venue

  • %event_venue_url% – Link to the event’s venue page

  • %event_venue_address% – Address of the event’s venue

  • %event_venue_postcode% – Postcode of the event’s venue

  • %event_venue_country% – Country of the event’s venue

  • %event_venue_map% or %event_venue_map{class}% – Google Map of the event’s venue. (Optional) specify as class for the map. This can be used to alter the size of the map.

  • %cat_color% – The colour of the event (according to the colour of its category(ies)).

Examples

Output a list of future events at the venue of the current event.

 //Future events at this venue: 
 [eo_events venue="%this%" showpastevents=false]