Events List

Your theme probably has at least a couple of ‘widgetised areas’. These are locations where you can add a widget, including the event list widget. The events widget displays a simple list of events. Using the options you can show events in particular categories or venue, 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 appearance of the event list below.

Adding the widget

  • Go to Appearance > Widgets.
  • Find the “Events” widget
  • Click the widget, select the widgetised area and click ‘Add widget’ or drag and drop the widget to the desired location

Widget Options

The widget comes with several options:

  • Title – The title of the widget
  • Number of events – The number of events to display
  • Event categories – A list of slugs, seperated by commas (and without spaces) to display only events in at least one of those listed categories. Leave blank for all.
  • Event venue – Select a venue to display only events at that venue
  • Order by – How to order events. One of ‘event start date’, ‘title’ and ‘publication date’
  • Interval – A setting which allows you to show events within a specific time period. E.g.
    • All events
    • Future events (events start in the future)
    • Running events (events which are currently in progress)
    • Past event (events which have already finished)
    • Future & running events (events which have not started or finished yet)
    • Events on today (Events which a running at some point today).
      You can register custom intervals (see Registering custom intervals below).
  • Group occurrences – Check to show only one date from a recurring event. The date shown is the first date in the list. If you are not showing past events this will be the next date of the event.
  • Template – Provide a string with placeholder tags to use for the event list. Alternatively you can leave this blank and provide a template file in your theme. See the Customising the appearance of the event list
  • No events’ message – A message to display when no events are being displayed

Customising the appearance of the event list

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

  • Using the Template widget setting
  • 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 the Template setting.

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 widget-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 widget with the “template” setting this template file will be ignored

Method 2: Placeholder Tags

You can use the ‘Template’ setting with placeholders to determine what is displayed for 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

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

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_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()][4].

  • %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)).

Registering custom intervals

The event list widget allows you to only show events which fall within a certain period. You can choose from a number of pre-defined periods, but if none fit the bill, you can register your own using the eventorganiser_query_scope hook.

This hook filters an array of intervals. Each interval is defined by any number of the following properties:

  • event_start_after (include only events which start on or after this date)
  • event_start_before (include only events which start on or before this date)
  • event_end_after (include only events which end on or after this date)
  • event_end_before (include only events which end on or before this date)

While you can give these absolute datetimes (e.g. '2016-02-17 14:30:00'), you will most likely need to make use of relative statements such as 'this monday', or 'tomorrow', '+2 hours'. You can find out more about relative date formats here: http://docs.wp-event-organiser.com/querying-events/relative-date-formats/.

So, for example, to register an interval which shows events running this month (‘running’ means active any point during this month, so we want events which start on or before the last of month and finish after or on the first of the month).

 add_filter( 'eventorganiser_query_scope', function( $intervals ) {
     $intervals['this_month'] = array(
          'label' => 'Events on this month', //a human readable description
          'query'   => array(
                'event_start_before' => 'last day of this month',
                'event_end_after'    => 'first day of this month',
          ),
     )
     return $interval;s
 } );