Events List Widget Settings

We’re going to go over the Events List Widget in this tutorial, including how to configure it, things to expect from it, and perhaps some tips and tricks you can use at your next cocktail party. You’ll be the star of the show, for sure.

Adding the Widget to a Sidebar

The first thing to note is about the Events List widget is where to find it. The widget comes packaged with the core version of The Events Calendar. You’ll find it Appearance > Widgets from the WordPress dashboard. Drag that little guy into the sidebar area of your choice, and you’re off to the races!

Events Widget Settings

There are three settings that help customize the Events List widget experience. Let’s take a look at them:

• Title: This is the heading that sits above the widget. By default, this is “Upcoming Events” but it can be changed to anything you’d like.
• Show: This is the maximum number of events you want to display at any given time. Five is the default, but this can be any number between one and ten.
• Hide this widget if there are no upcoming events: Check the box for this option and the widget will automatically hide itself if there are no relevant events to list. Otherwise, it will display a handy notice saying there are no upcoming events at this time.
• Limit to featured events only: Check the box for this option and the widget will display featured events.
• Generate JSON-LD data: Enable this setting if you would like to enable structured data in the widget. Structured data is what search engines use to recognize calendar content on and display events in the search results if the data is there and processed by the search engine.

Block Option

When using the Block Editor, you can add the Events List as a block instead. Simply search for Events List under blocks and you’ll find all of the same available options.

Configuring the Pro Version

It’s important to bear in mind that the Events List widget in The Events Calendar Pro is the same widget that comes with the core version of The Events Calendar. If you have Pro, you’ll see the same Events List widget under Appearance > Widgets. In your frontend the Widget will have the same appearance, the only difference is that you have some more filtering options available to setup this.

As you can see, there are more configurable options when setting up the Pro widget. Add the widget to the sidebar the same way as described above, and now you’ll see more options. In addition to the same three options in the basic widget, Pro introduces these settings:

• Display: This is a set of checkboxes that allow you to toggle the display of different bits of information, including:
  • Venue
  • Organizer
  • Street
  • City
  • State (US) or Province (Int)
  • Postal Code
  • Country
  • Venue Phone
  • Price
• Filter: This is an advanced setting that allows you to filter the events that display in the widget by a number of variables, including Categories and Tags. You can add multiple filters, and also multiples instances of the widget- so if you wanted you could have different widgets for different Event categories

Please note that all that settings are responsible only for properly load events from your database, they don’t add or remove any visual information in the Widget!

Phew, that’s a lot of stuff! You really have a lot of options here to customize the widget’s content without touching a line of code and that’s awesome.

Theming the Widget

We actually have another tutorial that provides a specific example of how to customize the Events List widget, as well as an entire Themer’s Guide on how template overrides work in The Events Calendar. Still, it’s helpful to know what files to look for and what they do.

The template for the core Events List widget can be found at: /plugins/the-events-calendar/src/views/widgets/list-widget.php. This single file contains all the content and functionality for the widget. To override it, make a copy of it, then:

• Make a new folder in the theme directory called tribe-events
• Make a folder in that one called widgets
• Drop the list-widget.php copied file in that last folder

Now that the template is in the theme, you can modify it to your liking. For example, you can customize the notice for when there are no upcoming events by changing this line:

 <?php printf( __( 'There are no upcoming %s at this time.', 'tribe-events-calendar' ), strtolower( $events_label_plural ) ); ?>

…to something like:

 <p> No events here. Holla! </p>

The process for customizing the widget in Events Calendar Pro is very similar. The difference is how many files there are and where you find them. First off, you can find the primary template at: /plugins/events-calendar-pro/src/views/pro/widgets/list-widget.php.

Open that up and you’ll see that the template actually includes another template called single-event.php which can be found in the modules folder in the same directory as the template.

Making modifications to the Pro version of the widget entails the same process, though you place the files in a different location. Make a copy of the file, then:

• Make a new folder in the theme directory called tribe-events
• Make a folder in that one called pro
• Make a folder in that one called widgets
• Drop the list-widget.php copied file in that last folder
• Example: wp-content/themes/YOUR_THEME/tribe-events/pro/widgets/list-widget.php

If you were modifying the single-event.php template, you would create one last folder after widgets called modules and then drop the file in there instead (example: wp-content/themes/YOUR_THEME/tribe-events/pro/widgets/modules/single-event.php).

Wrapping Up

There we go! We covered a lot of ground in this tutorial. Hopefully, now you’ve got a better understanding of the Events List widget, how to configure it, how Pro extends it, and how to customize its templates. Still have some burning questions not covered here? Hit us up at our help desk and we’d be happy to help.