Basic shortcode

[ecs-list-events]

Shortcode Options

limit

Total number of events to show. Default is 5.

[ecs-list-events limit='3']

offset pro only

Skip a certain number of events from the beginning. Useful for splitting into columns or using multiple copies of the shortcode on the same page.

[ecs-list-events offset='2']

category

Shows events in a single event category. Use commas when you want multiple categories

[ecs-list-events cat='festival']

[ecs-list-events cat='festival, workshops']

Pro only: if you want to only include events in both the festival AND the workshops categories, you'll need to use the tag_cat_operator option, ie.

[ecs-list-events cat='festival, workshops' tag_cat_operator='AND']

exclude category or categories pro only

Include events that are not in the specified categories. Useful for excluding any community submitted events.

[ecs-list-events exclude_cat='community']

[ecs-list-events exclude_cat='meeting, gala']

If you want to only include events that are both in the community category but also NOT in the meeting category, you'll need to use the tag_cat_operator option, ie.

[ecs-list-events cat='community' exclude_cat='meeting' tag_cat_operator='AND']

tag pro only

Show events in a single event tag. Use commas when you want multiple tags.

[ecs-list-events tag='special']

[ecs-list-events tag='special, meeting']

exclude tag or tags pro only

Include events that are not in the specified tags.

[ecs-list-events exclude_tag='large-event']

[ecs-list-events exclude_tag='large-event, regular-event']

If you want to only include events that both have the large-event tag but also do NOT have the regular-event tag, you'll need to use the tag_cat_operator option, ie.

[ecs-list-events tag='large-event' exclude_tag='regular-event' tag_cat_operator='AND']

tag/category operator pro only

Instead of showing events that are in at least one of the categories or tags you specify, switch to only show events in all of those categories.

[ecs-list-events tag="meeting, board" tag_cat_operator="AND"]

[ecs-list-events cat="gala, special" tag_cat_operator="AND"]

days pro only

Specifies the number of days from today to fetch events. If specified, overrides the month option

For example to get events for the next week:

[ecs-list-events days='7']

Or to get events for the next day:

[ecs-list-events days='1']

day pro only

Get events from a specific day.  If specified, overrides the month option

[ecs-list-events day='2017-04-15']

[ecs-list-events day='current']

or a relative date:

[ecs-list-events day='+1 day']

[ecs-list-events day='+7 days']

or for the current day but in future only:

[ecs-list-events day='current' futureonly='true']

[ecs-list-events day='current' key='start date' hide_finished='true']

Show only events marked as "featured"

[ecs-list-events featured_only='true']

Show events that are not marked as a "featured" event

[ecs-list-events exclude_featured='true']

hide_soldout pro only

Hide any events that are sold out (used with the Event Tickets or Event Tickets Plus addon by Modern Tribe)

[ecs-list-events hide_soldout='true']

Note that due to the complexity of this option, it may decrease the number of events displayed. You can use the limit option to show more events if needed.

hiderecurring pro only

Option to only show the first event from a recurring event (The Events Calendar PRO).

[ecs-list-events hiderecurring='true']

id pro only

Show a single event using that event's ID

[ecs-list-events id='123']

You can find the id by going to the event you want while logged into your WordPress site, then clicking Edit Event at the top:

then in the top you can see the ID beside post=

In this case the ID is 599

exclude_id pro only

Hide an event from the listing. Useful if showing related events using the shortcode on an event page, but you want to exclude the current event. Use "current" to hide the ID of the current event or specify one or more IDs (see the id option above on how to find the post IDs you need to exclude).

[ecs-list-events exclude_id='current']

[ecs-list-events exclude_id='123']

[ecs-list-events exclude_id='123, 534']

order

Order of the events to be shown. Value can be 'ASC' or 'DESC'. Default is 'ASC'. Order is based on event date.

[ecs-list-events order='DESC']

date

To show or hide date. Value can be 'true' or 'false'. Default is true.

[ecs-list-events eventdetails='false']

timeonly pro only

To show the start time only on most designs. Value can be 'true' or 'false'. Default is false.

[ecs-list-events timeonly='true']

venue

To show or hide the venue. Value can be 'true' or 'false'. Default is false.

[ecs-list-events venue='true']

excerpt

To show or hide the excerpt and set excerpt length. Default is false.

[ecs-list-events excerpt='true']

[ecs-list-events excerpt='300']

raw_excerpt pro only

Uses the raw excerpt rather than stripping any HTML from it or modifying the result in any way.

[ecs-list-events excerpt="true" raw_excerpt="true"]

description pro only

Use the full description for the excerpt rather than the WordPress excerpt or short description. Can also use raw_description with it to avoid removing any formatting and links.

[ecs-list-events excerpt="true" description="true"]

[ecs-list-events excerpt="100" description="true"]

[ecs-list-events excerpt="true" description="true" raw_description="true"]

thumb

To show or hide thumbnail/featured image. Default is false.

[ecs-list-events thumb='true']

Specify the size using thumbsize (defaults to medium)

[ecs-list-events thumb='true' thumbsize='large']

You can also use thumbwidth and thumbheight to customize the thumbnail size

[ecs-list-events thumb='true' thumbwidth='150' thumbheight='150']

message

Message to show when there are no events. Defaults to 'There are no upcoming events at this time.'

cost pro only

Add the cost to the event listing in the default design:

[ecs-list-events cost='yes']

viewall

Determines whether to show 'View all events' or not. Values can be 'true' or 'false'. Default to 'true'

[ecs-list-events cat='festival' limit='3' order='DESC' viewall='false']

contentorder

Manage the order of content with commas. Default to title, thumbnail, excerpt, date, venue.

[ecs-list-events cat='festival' limit='3' order='DESC' viewall='false' contentorder='title, thumbnail, excerpt, date, venue']

month

Show only specific Month. Type 'current' for displaying current month only or 'next' for the next, ie:

[ecs-list-events cat='festival' month='2015-06']

[ecs-list-events cat='festival' month='current']

With the pro version you can also specify futureonly="true" to only display upcoming events or hide_finished="true" if using key="start date" (to get events based on the start date).

year pro only

Show only a specific year.  Type 'current' for displaying current year only or futureonly='true' for future events only, ie.

[ecs=list-events year='2016']

[ecs-list-events year='current']

[ecs-list-events year='2016' futureonly='true']

[ecs-list-events year='current' key='start date' hide_finished='true']

fromdate pro only

todate pro only

Show events between a certain date range.

[ecs-list-events fromdate='2017-05-31' todate='2017-06-15']

or with relative dates:

[ecs-list-events fromdate='today' todate='+7 days']

[ecs-list-events fromdate='+7 days' todate='+14 days']

or you can specify either the from or the to date, and optionally add futureonly to only show future events:

[ecs-list-events fromdate='2017-07-25']

[ecs-list-events todate='2017-08-20']

[ecs-list-events futureonly='true' todate='2017-07-25']

or use hide_finished='true' if getting events by the start date and you want to hide any that have finished:

[ecs-list-events fromdate='-30 days' todate='today' key='start date' hide_finished='true']

Note the default limit of 5 can be changed using the limit option if needed:

[ecs-list-events fromdate='2017-05-31' todate='2017-06-15' limit='100']

include in progress

For use with fromdate/todate, days, day and year to also include events that are "in progress" (ie. start before and end after the current day).

[ecs-list-events day="current" include_in_progress="true"]

[ecs-list-events year="current" include_in_progress="true"]

[ecs-list-events days="7" include_in_progress="true"]

[ecs-list-events fromdate="2018-01-31" todate="2018-02-28" include_in_progress="true"]

past

Show outdated events (ie. events that have already happened)

[ecs-list-events cat='festival' past='yes']

city pro only

state pro only

country pro only

Filter events by a location city, state or province, or country. Use a comma to separate more than one. Use -- instead of a comma if the city, province or country name has one.

[ecs-list-events city='Chicago']

[ecs-list-events state='IL']

[ecs-list-events country='United States, Canada']

[ecs-list-events country='Korea-- Republic of']

venue_id pro only

Filter events by one or more venue ids

[ecs-list-events venue_id='52']

[ecs-list-events venue_id='52, 56']

You can find the venue ID by going to Events then Venues in the WordPress administration area:

Then find your venue, click Edit, and the venue ID is at the top beside post_id:

In this case the venue ID would be 1277

organizer_id pro only

Filter events by one or more organizer ids

[ecs-list-events organizer_id='73']

[ecs-list-events organizer_id='73, 77']

key

Used to hide events when the start date has past rather than the end date.

[ecs-list-events cat='festival' key='start date']

orderby

Override the ordering. Useful when you have multi-day events or you don't want to hide the event until the full event time has passed.

[ecs-list-events orderby='start date']

You can also sort by the title if you wish:

[ecs-list-events orderby='title']

Additional Fields pro only

If you use Advanced Custom Fields or The Events Calendar Pro with Additional Fields, you can filter by those values when listing events.

Advanced Custom Fields

First, find the name of the field you want to filter by going to Custom Fields and editing the field group:

Finding the Field name from Advanced Custom Fields

In this case the field name is addl_series

So to only show events with the value "Test Series" in this additional field, you can use:

[ecs-list-events addl_series="Test Series"]

Additional Fields (The Events Calendar Pro)

Finding the name is a little more complex with Advanced Fields. When editing an event, find the field you want to filter by and right-click on it to show a menu. Pick Inspect to show additional details on the field:

Additional Fields with The Events Calendar Shortcode

Here the saved name of this field is _ecp_custom_2 so to only show events with "Test Series" in this field you can use:

[ecs-list-events _ecp_custom_2="Test Series"]

Toolset Types

Similarly with Toolset Types, if you have a field with slug my-field you can filter for events with value “Test” for this field with:

[ecs-list-events my-field="Test"]

Styling/Design

By default the plugin shows a listing of events in a style similar to The Events Calendar's list view.

You can see screenshots and examples of the designs below, or view some examples on the demo site.

Standard Design

If you would like to use the styling/html from the free version, just add design="standard" to the shortcode:

[ecs-list-events design="standard"]

Compact Design pro only

If you would like to use a more compact view, just add design="compact" to the shortcode:

[ecs-list-events design="compact"]

You can customize the colors using fgthumb (text color of the date) and bgthumb (background color), for example:

[ecs-list-events design="compact" fgthumb="#efefef" bgthumb="#000000"]

[ecs-list-events design="compact" fgthumb="black" bgthumb="red"]

View some more examples on the demo site.

Calendar Design pro only

Easily display a monthly calendar view of your events.  Visitors can switch between months and click on an event to view the full details.

[ecs-list-events design="calendar"]

You can customize the colors of the event items with eventbg (background color) eventfg (foreground color) and eventborder (border color)

[ecs-list-events design="calendar" eventbg="white" eventfg="black" eventborder="#efefef"]

You can change the initial month that is displayed by specifying a default date. For example to set the default to December 15th 2017 (and show December 2017) use:

[ecs-list-events design="calendar" startdate="2018-12-15"]

You can also change the first day of the week, where 0 is Sunday, 1 is Monday and so on:

[ecs-list-events design="calendar" first_day_of_week="1"]

Last but not least you can add a filter bar to the top with:

[ecs-list-events design="calendar" filterbar="true"]

View more examples of the calendar design on the demo site.

Columns/Horizontal/Photo or Table Design pro only

Column listing of events

Split events into columns so they’re easy to read and visually appealing. Looks great when events have photos (featured images) but works either way. Use design="columns" for a pinterest-style layout where the rows flow into each other, or design="table" to have the tops of each row line up with each other.

View examples of the Columns/Horizontal/Photo design or the Table design on the demo site.

Grouped Design pro only

This design is great for lots of events, to show the date of the event with just the time, title and venue of each event underneath.

If you would like to group the events by day with just the time under each date, just add design="grouped" to the shortcode:

[ecs-list-events design="grouped"]

You can also optionally include the venue with:

[ecs-list-events design="grouped" venue="true"]

View examples on the demo site.

Additional Options

You can also customize the output of certain designs with things like:

  • titlesize to customize the size of the title, ie. titlesize="18px"
  • thumb="true" to show the event thumbnail image (if any)
  • excerpt="true" to show the event summary description under the title
  • venue="true" to show the venue name under the title
  • timeonly="true" to show only the start time
  • button="View Details" to show a button with a link to the event (change "view details" to whatever you want)
  • buttonlink="website" to use the event website URL instead of the regular link for the button
  • buttonbg and buttonfg to customize button color

The demo site has a number of examples of the designs, but if you can't find what you're looking for let us know!

Custom Design pro only

If you'd like to completely customize the output you can create a folder called tecshortcode in your theme directory, and in it create a file called custom.php

Then add your shortcode with "custom" as the design name (which matches custom.php):

[ecs-list-events design="custom"]

You can rename custom.php to another name and even create multiple design templates to use elsewhere on your site. Note that you should place this folder within a child theme so any updates to your main theme do not override your templates.

Available Variables in a Custom Design Template

The Events Calendar Shortcode Pro will pass you several variables you can use in the implementation of your design:

  • $post (WP_Post) of the current event
  • $posts (WP_Post[]) array of all the events
  • $post_index (int) index of the current event, starting at zero. So $post_index == 0 is the first event, and count( $posts ) - 1 == $post_index is the last one
  • $atts (array) the attributes/options of the current shortcode
  • $event_output (string) HTML of the output that will be overridden by your template

You can use the functions provided by The Event Calendar (by Modern Tribe) along with other WordPress functions on a post.

Customizing the Default Design

You can copy the-events-calendar-shortcode-pro/templates/default_tpl.php to wp-content/themes/your-theme/tecshortcode/default.php then edit the default.php file as needed.

Note that you need to keep it named default.php in order to have the default options and styling come though.  The template version is also slightly different than the non-template version, but has the majority of the features and functionality as an example for you to customize.

Customizing the Compact Design

Want to customize the Compact design?  You can copy the-events-calendar-shortcode-pro/templates/compact_tpl.php to wp-content/themes/your-theme/tecshortcode/compact.php then edit the compact.php file as needed.

Note that you need to keep it named compact.php in order to have the default options and styling come though.  The template version is also slightly different than the non-template version, but has the majority of the features and functionality for you to customize.

Customizing the Grouped Design

You can copy the-events-calendar-shortcode-pro/templates/grouped.php to wp-content/themes/your-theme/tecshortcode/grouped.php then edit the grouped.php file as needed.

Note that you need to keep it named grouped.php in order to have the default options and styling come though.

Customizing the Columns/Horizontal/Photos Design

You can copy the-events-calendar-shortcode-pro/templates/columns.php to wp-content/themes/your-theme/tecshortcode/columns.php then edit the columns.php file as needed.

Note that you need to keep it named columns.php in order to have the default options and styling come though.

Customizing the Table Design

You can copy the-events-calendar-shortcode-pro/templates/table.php to wp-content/themes/your-theme/tecshortcode/table.php then edit the table.php file as needed.

Note that you need to keep it named table.php in order to have the default options and styling come though.

 

Access Event Data

When your template is loaded, the data for the event is the current post.  You can use any tribe_ functions like tribe_get_event_link() and tribe_get_cost()

A good place to look for example templates is in The Events Calendar itself, ie.

wp-content/plugins/the-events-calendar/src/views/day/single-event.php

Accessing Shortcode Attributes

You can use the variable:

$atts

 

to access any shortcode options or attributes within the custom template.  For example if you had the shortcode:

[ecs-list-events design="custom" cost="true"]

You could use the following template in custom.php to use the cost attribute along with showing the event meta:

<?php do_action( 'tribe_events_single_event_before_the_meta' ) ?>
<?php tribe_get_template_part( 'modules/meta' ); ?>
<?php if ( Events_Calendar_Shortcode::isValid( $atts['cost'] ) ): ?>
   <?php tribe_get_cost( null, true ); ?>
<?php endif; ?>    
<?php do_action( 'tribe_events_single_event_after_the_meta' ) ?>

If you want to add your own attributes you'll need to define their default value using the ecs_shortcode_atts filter. For example to add an attribute "new":

function add_my_attributes( $default_atts ) {
   $default_atts['new'] = '';
   return $default_atts;
}
add_filter( 'ecs_shortcode_atts', 'add_my_attributes' );

 

You might want to take a look at the templates in The Events Calendar for ideas on what you could use as a custom shortcode template.

or see it in action.

Absolutely ZERO risk.  30 day full refund policy, no questions asked.

This plugin is not developed by or affiliated with The Events Calendar or Modern Tribe in any way.

A plugin to display the events from The Events Calendar (by Modern Tribe) anywhere on your site

Can't find the option you're looking for? Ask us or check out some common examples!

Index

View Pricing

or see it in action

Special Offer: Get 20% off for: