eo_get_events

Description

Retrieve list of events matching criteria.

This function is a wrapper for get_posts(). As such you can also use get_posts() or WP_Query instead to retrieve events.
All the arguments listed below can be used with them.
Arguments from get_posts() and WP_Query can also be used. Their default values are as indicated by the relevant codex page.

The $args array can include the following.

  • event_start_before – default: null
  • event_end_before – default: null
  • event_start_after – default: null
  • event_end_after – default: null. This argument, and those above can take a date in ‘Y-m-d’ format or relative dates.
  • numberposts – default is – 1 (all events)
  • orderby – default is ‘eventstart’
  • showpastevents – default is true (it’s recommended to use event_start_after=today or event_end_after=today instead)

If you use get_posts() or WP_Query instead then you should ensure the following:

  • post_type – is set to ‘event’
  • suppress_filters – is set to false

Example

$events = eo_get_events(array( 
       'numberposts'=>5, 
       'event_start_after'=>'today', 
       'showpastevents'=>true,//Will be deprecated, but set it to true to play it safe. 
  ));

<?php if($events): 
   echo '<ul>'; 
   foreach ($events as $event): 
           //Check if all day, set format accordingly 
           $format = ( eo_is_all_day($event->ID) ? get_option('date_format') : get_option('date_format').' '.get_option('time_format') ); 
           printf('<li><a href="%s"> %s </a> on %s </li>', 
                              get_permalink($event->ID), 
                              get_the_title($event->ID), 
                              eo_get_the_start($format, $event->ID,null,$event->occurrence_id) 
                          ); 
   endforeach; 
    echo '</ul>'; 
endif; ?>

Usage

     <?php eo_get_events( $args ); ?>

Parameters

  • args (array) – Event query arguments (optional|array())

Return Values

  • (array) – An array of event (post) objects. Like get_posts. In case of failure it returns null.

Change Log

Since: 1.0

See

Resources

Location

This function can be found in event-organiser/includes/event-organiser-event-functions.php (line: 63)

Default Usage

The function uses the same defaults as get_posts, with the exception of some parameters. By default, 'numberposts' is set to -1 (all events), 'orderby' is set to 'eventstart' and 'showpastevents' is set according to the Event Organiser settings.

The function ignores the parameters post_type and suppress_filters (these are set to 'event' and false).

 <?php $args = array( 
           'numberposts' => -1, 
           'offset' => 0, 
           'event-category' => , 
           'orderby' => 'eventstart', 
           'order' => 'DESC', 
           'showpastevents' => false, 
           'event_start_before' => ,
           'event_start_after' => ,
           'event_end_before' => ,
           'event_end_after' => ,
           'include' => , 
           'exclude' => , 
           'meta_key' => , 
           'meta_value' => , 
           'post_status' => 'publish' 
           ); ?>

Parameters

On top of the usual parameters accepted by get_posts, the following parameters are also available:

  • venue - The venue slug (must be a string) or venue id (must be an integer).
  • event_start_before - Events that start before date given as a string in YYYY-MM-DD format or [relative format][1]. There is no default value.
  • event_start_after - Events that start after a date given as a string in YYYY-MM-DD format or [relative format][1]. 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][1]. 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][1]. 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][1]. 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.
  • event-category - the slug of an event category.

Additional values are also permitted for 'orderby' parameter

  • eventstart - Order by event start date.
  • eventend - Order by event end date.

Note that in calling get_posts, the function sets 'post_type' to 'event' and 'suppress_filters' to false.

Examples

As previously noted, function uses WordPress' built-in get_posts and all arguments available to get_posts are available to this function. This allows for potentially complex queries.

For instance, to get the next 5 events which aren't in the category with slug 'comedy':

$events = eo_get_events(array(
                     'numberposts'=>3,
                     'tax_query'=>array( array(
                          'taxonomy'=>'event-category',
                          'operator' => 'NOT IN',
                          'field'=>'slug',
                          'terms'=>array('comedy')
                          ))

You can then loop through the results and display them:

<?php if($events):
              $return= '<ul class="eo-events eo-events-shortcode">'; 

              foreach ($events as $event):
                   //Check if all day, set format accordingly
                   if( eo_is_all_day($event->ID) ){
                        $format = get_option('date_format'); 

                   }else{
                        $format = get_option('date_format').' '.get_option('time_format');
                   }
                   $return .= '<li><a title="'.$event->post_title.'" href="'.get_permalink($event->ID).'">'.$event->post_title.'</a> on '.eo_format_date($event->StartDate.' '.$event->StartTime, $format).'</li>';
              endforeach; 

              $return.='</ul>'; 

              echo $return;
     endif; ?>