Filtering Events in Stager Event Calendars

5 min read
Posted in
  1. How do filters work in Stager event calendars?
  2. Filter fields (“taxonomies")
  3. Filter appearance and examples
  4. “Dropdown” filter appearance
  5. “Accordion” filter appearance
  6. Enabling filters in event calendars
  7. 1. Using the Stager Event Calendar block (Block Editor), or the Stager Event Calendar Elementor widget.
  8. 2. Using shortcodes
  9. 3. PHP (developers)
  10. Pre-filtering events before rendering a calendar
  11. Customising filter field labels
  12. Styling filters
  13. For developers: hooks and overrides
  14. 1. Filter taxonomy label
  15. 2. Filter taxonomy terms
  16. 3. Custom filter template

The WP Stager Integration plugin offers a filter functionality for its Event Calendars. Calendar filters let users narrow events in calendars. Filters can be enabled for any field present in Stager’s event data, including tags, event type, a location’s name or city, labels, ticket types, etc. When the user uses the filter, the filtered list of events displays instantly. A result count and “Clear filters” button are included. Filters work with any calendar view and are fully responsive.

Different filter appearances shown side by side.

💡 Looking for an integration partner who does the full integration for you? Every license comes with a Free Configuration Service, and we also offer a paid Full Integration Service!

How do filters work in Stager event calendars?

Filters allow the user to filter the events within a calendar. Only events that match the current filter selection will be highlighted. Optionally, events that don’t match the filter selection can be hidden completely. You can choose yourself which filter fields to enable (e.g. Tags, Labels, Location, Ticket types, etc). Any field present in the Stager data can be enabled as a field in the filter.

Filter fields (“taxonomies”)

You can enable a filter for any Stager event field that exists in your feed data (e.g. tags, type, status etc.). You can also filter on nested fields using dot notation (e.g. eventLabels.name, location.city, location.country, location.spaces.name etc.).

💡 Any field present in the Stager feed data can be used in the filter. See the Stager Feed documentation for more information on the available fields.

A few examples include:

FieldTypical use
tagsTags (split by delimiter set in plugin settings)
typeEvent type
statusEvent status
location.nameVenue name
location.cityVenue city
location.countryVenue country (contains ISO code → gets mapped to country name automatically)
location.spaces.nameVenue space name
eventLabels.nameEvent labels
customerInterests.nameCustomer interests
programItems.nameProgram items
ticketGroups.nameTicket types

All of the above fields will automatically get a label assigned (e.g. location.name is displayed as “Location”, location.city is displayed as “City”, etc). When filtering on another field, the label will fall back to the field key, but custom labels can be added through the plugin’s settings.

Filter appearance and examples

Filters can be displayed as either a dropdown, or an accordion menu. See examples of the different appearances below.

The dropdown filter appearance displays the filters as a dropdown menu above the calendar:

Loading calendar…

“Accordion” filter appearance

The accordion filter appearance displays the filters as a collapsible accordion menu next to the calendar:

Loading calendar…

Enabling filters in event calendars

How to enable the filter in your calendar depends on the method you use to render calendars. All different methods are discussed below.

1. Using the Stager Event Calendar block (Block Editor), or the Stager Event Calendar Elementor widget.

  1. Add the Stager Event Calendar block (in the block editor), or the Elementor widget (in the Elementor editor).
  2. In the block’s/widget’s sidebar settings, go to the the Filters section.
  3. Toggle Enable filters on, and add one or more filter fields: each row has a field and optional label. The fields can be chosen using a dropdown, or a custom value can be entered. The label is optional, is used to override the default label given to some fields.
  4. You can use the Filter appearance setting to modify the look of the filter.

💡 The filters will only display in the calendar if at least one field is added, and that field actually has values in your event data.

2. Using shortcodes

Use the wpstager_calendar shortcode and pass enabled_filters (comma-separated field names) and optionally filter_appearance. For example:

// Enable an 'accordion' filter for tags and event type
[wpstager_calendar enabled_filters="tags,type" filter_appearance="accordion"]

// Enable a 'dropdown' filter for event labels and cities
[wpstager_calendar enabled_filters="eventLabels.name,location.city" filter_appearance="dropdown"]
  • enabled_filters: A comma separated list of fields to enable the filter for.
  • filter_appearance: The appearance of the filter, which can be either accordion (default) or dropdown.
  • See the wpstager_calendar shortcode documentation for more information.

3. PHP (developers)

When calling a calendar rendering function like \WP_Stager_Integration\Calendar::render_all() (or render_month(), render_week(), etc.), you can use the enabled_filters, filter_appearance and filter_labels arguments. See the Calendar::render_calendar() documentation for more information.

For example:

// Render a calendar with an 'accordion' filter for tags, event type and cities, and a custom label for the 'location.city' field
\WP_Stager_Integration\Calendar::render_all( array(
    'enabled_filters'    => array( 'tags', 'type', 'location.city' ),
    'filter_appearance'  => 'accordion',
    'filter_labels'      => array( 'location.city' => 'Place' ),
) );

Pre-filtering events before rendering a calendar

You can show a calendar that is already filtered (e.g. only “concert” + “Premium” events).

  • Shortcodes: use the query attribute. Default format: field:value1|value2; use ; between fields. You can use other characters as delimiters for advanced querying. For more information, see the wpstager_calendar shortcode documentation
// Example: only events with tags “concert” or “theater” and label “Premium” or “VIP”:
[wpstager_calendar query="tags:concert|theater; eventLabels.name:Premium|VIP"]
  • Block Editor/Elementor: use the Event query panel in the block’s/widget’s settings to add fields + values to filter on.
  • PHP: pass the query argument as an array, for example:
// Render all events in Amsterdam with the "Workshop" label
\WP_Stager_Integration\Calendar::render_all( array(
    'query'            => array(
        'location.city'    => array( 'Amsterdam' ),
        'eventLabels.name' => array( 'Workshop' )
    ),
) );

Customising filter field labels

In WP Stager Integration → Settings → Calendar, under Custom filter labels, you can add custom labels for the fields in the filter:

  • Field name: The field as present in the Stager event data e.g. location.name, tags, eventLabels.name, etc. More info on the Stager fields above.
  • Custom label: The text/label shown in the filter (e.g. “Venue”, “Category”, “Label”, etc.).

These apply to all calendars that use that field. Custom labels added per calendar instance will override these values. You can also use the wpstagerintegration_calendar_filter_taxonomy_label filter hook (more info below).

Styling filters

The filter is wrapped in a container with BEM-style classes so you can target it without changing plugin files. Some useful classes include:

  • .wpstager-calendar-filter — filter wrapper
  • .wpstager-calendar-filter--appearance-* — appearance classes (dropdown or accordion)
  • .wpstager-calendar--has-filters-enabled — When filters are enabled
  • .wpstager-calendar--filter-appearance-* — Added to the calendar wrapper
  • .wpstager-filtered-hidden — Added to .wpstager-event-card when hidden in the filter

For developers: hooks and overrides

1. Filter taxonomy label

If you want to change the label for a filter field (on all calendars), you can use the

wpstagerintegration_calendar_filter_taxonomy_label filter hook.

2. Filter taxonomy terms

If you want to change or restrict the list of options to filter on (e.g. sort or add/remove terms), you can use the wpstagerintegration_calendar_filter_taxonomy_terms filter hook.

3. Custom filter template

You can use the wpstagerintegration_calendar_component_template filter hook to build a fully custom filter template. Replace the default filter markup by returning the path to your custom filter template:

add_filter( 'wpstagerintegration_calendar_component_template', function( $path, $component, $args ) {

    // Return a custom filter component path
    if ( $component === 'filter' ) {
        return get_stylesheet_directory() . '/template-parts/wpstager-calendar-filter.php';
    }

    return $path;
}, 10, 3 );

Your template receives $args including events, enabled_filters, filter_labels, filter_appearance, etc.

💡Please note: Some classes and data attributes are expected by the plugin’s JavaScript.

This is how you can easily setup filters in your Stager event calendars using the WP Stager Integration plugin!

Get WP Stager Integration

🎁 Limited offer: Use code WELCOME26 to get your first month for free!

Get started