Listing events on your web pages: the shortcode explained
As mentioned in our August newsletter, our existing Event List Content Block has become unreliable, and we have discontinued its use.
The new method of listing events uses a text “shortcode” — instructions for the website you can add in the page editor that will trigger features in the published pages. We have used these shortcodes for features such as buttons, status bars and link lists, and existing shortcodes are documented in our user guide.
Because this new method of listing events relies on specific syntax, we are happy to help set up your event lists. If you are interested in learning how this feature works, read on.
UMS Post Picker
This feature is utilized to pull posts from one site and display them within another site using shortcodes, taxonomy criteria and other options. The feature was developed and is maintained by the UMS Web Development Team, and the specific templates created for displaying information are developed and maintained by the UMS Web Technologies Team. The main uses for this feature are to display news, events, and other types of content across our websites to avoid duplicating content, in much the same way as our article and event list content blocks.
A useful example: embed the Academic Calendar events
To illustrate this feature, here is the shortcode needed to display the next five upcoming events in the academic calendar:
[ums-post-picker site_id="15" post_type="tribe_events" taxonomy_terms="tribe_events_cat:academic-calendar" order_by="meta_value" meta_key="_EventEndDate" template="ums_event_summary_list" omit_past_posts=true order="ASC" limit="5" options="no_excerpt;showDate:1"]
The details are explained below:
site_id: The sub-site ID to pull content from. If omitted, the post picker will pull content from your site. The ID of calendar.umaine.edu (where the Academic Calendar events are published) is 15.
post_type: The type of WordPress post to search. The post type for events is tribe_events.
taxonomy_terms: A list of taxonomies and terms to match. The format is taxonomy_terms=”taxonomy_name:term_slug”. For event calendar categories the taxonomy name is tribe_events_cat, and the Academic Calendar category term slug is academic-calendar.
order_by: The post field to order posts by. While the default for this is the post publish date, event calendar items have a special “meta” value to identify when a future event begins. For this reason, the order_by value for event calendar items is meta_value.
meta_key: This attribute is used in conjunction with the above meta_value to set the order of posts when the default publish date isn’t helpful. For event calendar items, this meta_key is _EventEndDate. NOTE: because this sorts by the event’s end date, events that span multiple days may appear to be out-of-order in your event list (which lists the event’s start date). Our recommended best practice is to list multi-day events as sequential single-day events.
template: This sets the template to use for the content. Templates can be specific to custom post types such as events, or generic and applicable to all post types. For calendar listings, the template is ums_event_summary_list.
omit_past_posts: This is an on/off (true/false) setting that controls whether the list should exclude posts earlier than the current date. If left out, the list will include past posts, but for event calendar items this is set to true in order to only display events that are upcoming.
order: The sort order, which can be either ascending (ASC) or descending (DESC). For a list of upcoming events, this is set to ASC.
limit: Shows at most this many posts. If left out the default is 50 posts. For this Academic Calendar example, setting this to 5 will show the next five upcoming events.
options: This is used in conjunction with the earlier template attribute to include options that are not otherwise included in the shortcode parameters. In the case of the event summary list template, the option no_excerpt will exclude any excerpt text from the listings, and showDate:1 will display the date to the left in bold.
Here is what the above shortcode displays:
That was a lot to take in, is there more?
There are still more options that can be used for event listings that we will document in our user guide over time. Displaying event image thumbnails, displaying the events in a horizontal row, and combining multiple categories of events together are all possible. If you want to explore what is possible with listing events on your site, contact us at um.weboffice@maine.edu.