Event Embed

One of the most powerful shortcodes provided by Event Rocket is [event_embed] which makes it easy to query for and list events in a range of neat and powerful ways.

Developers! Please note that you can also use the embed API and access the engine behind this shortcode directly, providing you with a powerful and flexible means of querying events that can be a handy alternative to the options provided by The Events Calendar itself.

In its simplest form, all you need to do to use the shortcode is drop it into a page or post. It will then list a number of upcoming events within your post (how many depends on your WP posts per page setting).

The shortcode accepts the following parameters:

  • event (or events)
  • venue (or venues)
  • organizer (or organizers)
  • category (or categories)
  • tag (or tags)
  • logic
  • from
  • to
  • limit
  • template
  • nothing_found_text
  • nothing_found_template
  • cache
  • where
  • blog

It’s a flexible and adapatable system that can even be used to effectively build up new “event views” with minimal effort.

Specifying events, categories and tags

The event, category and tag parameters accept both post (or term) IDs and slugs. So for example this will work:

[event_embed event="10"]

And so will this:

[event_embed event="my-test-event"]

You can also combine multiple different IDs or slugs – all of these examples are valid:

[event_embed event="5,10,15"]
[event_embed event="test-event-1,test-event-2"]
[event_embed event="6,9,test-event,10"]

Of course if you are specifying multiple events it may make more sense to use an events parameter (ie, plural not singular) – and that’s completely possible:

[event_embed events="7,8,9,some-event-or-other,20"]

And the same thing is essentially true of categories and tags – please see these examples:

[event_embed tag="5, 9, my-tag"]
[event_embed categories="78,90,category-slug,51"]

Last but not least, it is possible to identify events, categories or tags for exclusion – simply by using the – symbol:

[event_embed category="20" event="-10"]

This would include events from whichever category has an ID of 20 but exclude event 10, if it otherwise happened to be a part of the result set. This also works with slugs:

[event_embed tags="fresh,music" events="-one-off-event,-weekly-staff-meeting"]

It is also possible to whittle the result set down to only include events at a specific venue (or arranged by a specific organizer):

[event_embed venue="the-plaza" organizer="2505"]

Like the above parameters, slugs and IDs can be used interchangeably. Also like the above, it is possible to apply a negative operator in order to exclude results where there is a link with a particular organizer or venue:

[event_embed organizers="-billy-the-fish,-6011"]

In that example we ignore any events organized by Billy the Fish or whomever has been assigned post ID 6011.

More complicated category queries

This is all well and good, but what if you want to retrieve events that are categorized with both “family-friendly” and “dolphin-related”?

[event_embed categories="family-friendly, dolphin-related"]

The above will retrieve upcoming events that are categorized as either “family-friendly”, or “dolphin-related”, or both. If you want to tighten this up and only retrieve events categorized with both those terms you can use the + operator:

[event_embed categories="family-friendly + dolphin-related"]

You can extend this with additional “or” clauses, for instance:

[event_embed categories="family-friendly + dolphin-related, dance-music"]

This will look for any events that:

  • Have “family-friendly” and “dolphin-related” applied to them
  • Or, those events that live in the “dance-music” category

You can as before mix and match slugs and IDs – and you can have multiple, separate joins:

[event_embed categories="action + horror, horror + female-lead, -1"]

In the above example we’re looking out for events categorized in:

  • “action” and “horror”
  • Or, “horror” and “female-lead”
  • Or, those events not in category 1

Last but not least – and possibly most useful if you use a negative operator – you can set the overall logic to “AND”. This means the query will try to apply all the category (and tag) terms, positive or negative, that you apply:

[event_embed category="western" slug="weepy" logic="and"]

Above, we are telling the system to query for events categorized in “western” that also are tagged with “weepy” (not either/or).

Caution! When you start combining positive terms, negative terms, and “and” + operators a complex stew begins to form … use at your own risk (or, at least, think hard about whether or not it is really necessary – and if the results are not as you expect, again, please think hard before posting for help in case it’s actually doing what you’ve asked it to do).

How are events displayed?

The plugin provides a very basic template which is used by default. However, it is also possible to specify a template with the template parameter:

[event_embed category="hot-events" template="single-event"]

This would attempt to use a template named single-event.php and would use any such template that lives in the child theme – if there is a child theme – or else the parent/regular theme or else it will look and see if The Events Calendar itself contains such a template.

Sometimes you may want to do something more exotic. An absolute filepath can be passed to accommodate this:

[event_embed tag="fresh" template="/var/www/custom-stuff/some-template.php"]

It is also possible to define inline templates in this style:

[event_embed tag="featured" category="-private"]
    {title} on {start_date}
[/event_embed]

This approach is less flexible than using an actual PHP template but may also be much more convenient.

What if there are no events?

If [event_embed] queries for events and none are returned then, by default, it will display nothing. It might be nice to add some text, though, and this can be done via the nothing_found_text parameter:

[event_embed tag="special" nothing_found_text="Sorry, there are no upcoming special events"]

If you need to take things a step further you can specify an actual template:

[event_embed tag="special" nothing_found_template="event-embed-404"]

In the above case, it will hunt for a file called event-embed-404.php within your theme’s tribe-events subdirectory. If you prefer, you can pass in an absolute filepath to some location outside of your theme.

Caching

If you have a situation where you are using [event_embed] multiple times in a single page, or with a complex set of category and tag parameters, or you are simply seeking to reduce the overall footprint, you can do so with caching.

This is convenient where you have a page with dynamic elements that can’t easily be cached at a higher level, yet where you can make savings along the way (such as by caching the output of each [event_embed] shortcode).

[event_embed cache="auto"]

In the above example (it would also work to use cache=”on”) the output of the shortcode will be cached for the default period – 2hrs. When that period expires, it will query afresh.

If you want to specify some other time limit you can do so:

[event_embed cache="3600"]

If you provide a number, it is interpreted as the number of seconds for which the output should be cached.

It may seem obvious to many, but do bear in mind that until the cache is invalidated (ie, until the hour/two hour/whatever the caching period is expires) the output of the shortcode will stay the same. So, if you are using caching and you then add events that you expect will show up in the shortcode output but don’t see them … that is probably why 😉

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s