Sometimes it is handy to be able to query for and list events outside of existing views or in someplace where our existing widgets and shortcodes are unsuitable.
Thankfully, because events are a custom post type, the usual WordPress paradigms many of you will already be familiar with apply here — you can, for instance, make use of WP_Query to fetch a set of events.
If you’re not familiar with querying via WP_Query, however, fear not — this tutorial should be sufficient to get you on the road to building event queries like a rock star.
Introducing tribe_get_events()
While using WP_Query is completely possible, we also supply a convenient function called tribe_get_events() which returns any events which might be found in an array.
Note that we can use tribe_get_events() where we provide no arguments whatsoever.
Generally speaking, of course, we will wish to specify various arguments in order to narrow down the result field. For the most part any event-specific arguments can also be used if you prefer to work with WP_Query.
Dates
WordPress is built around the idea of posts, which contain various fields including the publication date and last-modified date.
When it comes to events those fields can also be useful but, most of the time, we are more interested in the actual event dates. So, when querying for events, two special arguments can be provided: start_date and end_date.
The format I have chosen to use is the “machine-friendly” yyyy-mm-dd hh:mm style or, to describe the same format PHP date()-style: Y-m-d H:i.
Actually a wider range of formats than this are accepted, but sticking to the above is safe and provides for consistency with The Events Calendar itself.
Display types
Another event-specific query argument is eventDisplay> — this is used to shape the actual query in a way that makes sense for the particular event view that has been requested, such as month if the visitor has tried to open month view.
Depending on the nature of the query you are building, this may not need to be explicitly set. However, unless you are sure you want the same behavior as (for example) Month View, it is often best to set it to custom if you wish to stop The Events Calendar or Events Calendar Pro from making assumptions about the nature of your query.
Advanced usage
While it’s beyond the scope of this tutorial to cover taxonomy queries and other advanced topics, suffice to say that you can restrict your query to specific categories and tags or hunt for events marked with some piece of meta data you are interested in.
To learn more about this and the actual syntax to use in these more advanced scenarios, please refer to the Codex’s WP_Query documentation.