Event Search Attributes

Since version 3.0, we’ve made a consistent set of accepted search attributes which you can pass to various shortcodes, template tags and core functions that search objects like events and locations. For example, when dealing with locations, you should be able to use most attributes which are also available when dealing with events. Below is a description of specific attributes and general attributes.

General Attributes

These attributes are shared across all shortcodes and template tags that accept attributes. Some default values have different defaults when used in different functions and shortcodes (e.g. for locations), which are explained further down. Also, note that in some contexts these attributes will not make a different to the returned results.

array

If you supply this as an argument, the returned data will be in an array, not an object (only useful wen using PHP, not shortcodes)

format_header

If you are displaying lists (e.g. listing events), you can supply the header html and placeholders here. Default Value: The relevant default format will be taken from the settings page.

format

If you are displaying some information with the shortcode or function (e.g. listing events), you can supply the html and placeholders here. Default Value: The relevant default format will be taken from the settings page.

format_footer

If you are displaying lists (e.g. listing events), you can supply the footer html and placeholders here. Default Value: The relevant default format will be taken from the settings page.

limit

Limits the amount of values returned to this number. Default Value: 0 (no limit)

offset

For example, if you have ten results, if you set this to 5, only the last 5 results will be returned. Useful for pagination.

order

Indicates the alphabeitcal/numerical order of the lists. Choose between ASC (ascending) and DESC (descending). Default Value: ASC

orderby

Choose what fields to order your results by. You can supply a single field or multiple comma-seperated fields (e.g. "event_start_date,event_name").

Accepted Arguments : Database table fields, e.g. event_name or location_name

owner

Limits returned results to a specific owner, identified by their user id (e.g. list events or locations owned by user)

pagination

When using a function or shortcode that outputs items (e.g. [events_list] for events, [locations_list] for locations), if the number of items supercede the limit of items to show, setting this to 1 will show page links under the list.

Event Attributes

Along with these attributes, you can also use the general attributes and location attributes for filtering by location. This applies to all event related functions and shortcodes, e.g. em_events(), [events_list], EM_Events::get()

blog

Limit search to events created in a specific blog id (MultiSite only)

bookings

Include only events with bookings enabled. Use 'user' to show events a logged in user has booked.1 = yes, 0 = no

category

Supply a single id or comma-seperated ids (e.g. "1,2,3") to limit the search to events in these categories. You can also use negative numbers to exclude specific categories (e.g. -1,-2,-3).

tag

Supply a single id or comma-seperated ids (e.g. "music,theatre,sport") to limit the search to events in these tags.

event

Supply a single id or comma-seperated ids (e.g. "1,2,3") to limit the search to events with the event_id(s).

group

Limit search to events belonging to a specific group id (BuddyPress only). Using 'my' will show events belonging to groups the logged in user is a member of.

post_id

Supply a single id or comma-seperated ids (e.g. "1,2,3") to limit the search to events with the post_id(s).

private

Display private events within your list? Default Value: If user can view private events, 1, otherwise 0.

Accepted Arguments : 1 = yes, 0 = no

private_only

Display only private events ?

Accepted Arguments : 1 = yes, 0 = no

recurrence

If set to the event id of the recurring event, this will show only events this event recurrences.

recurring

If set to 1, will only show recurring event templates. Only useful if you know what you're doing, use recurrence if you want events that are recurrences.

search

Do a search for this string within event name, details and location address.

status

Limit search to events with a spefic status (1 is active, 0 is pending approval) Default Value: 1

scope

Choose the time frame of events to show. Additionally you can supply dates (in format of YYYY-MM-DD), either single for events on a specific date or two dates seperated by a comma (e.g. 2010-12-25,2010-12-31) for events ocurring between these dates. Default Value: future

Accepted Arguments : future, past, today, tomorrow, month, next-month, 1-months, 2-months, 3-months, 6-months, 12-months, all

year

If set to a year (e.g. 2010) only events that start or end during this year/month will be returned. Does not work as intended if used with scope.

Location Attributes

Along with these attributes, you can also use the general attributes and event attributes for filtering locations according to events. This applies to all location related functions and shortcodes, e.g. em_locations(), [locations_map], EM_Locations::get()

blog

Limit search to locations created in a specific blog id (MultiSite only)

eventful

If set to 1 will only show locations that have at least one event occurring during the scope.

eventless

If set to 1 will only show locations that have no events occurring during the scope.

location

Supply a single id or comma-seperated ids (e.g. "1,2,3") to limit the search to locations with the location_id(s).

post_id

Supply a single id or comma-seperated ids (e.g. "1,2,3") to limit the search to locations with the post_id(s).

private

Display private locations within your list? Default Value: If user can view private locations, 1, otherwise 0.

Accepted Arguments : 1 = yes, 0 = no

private_only

Display only private locations ?

Accepted Arguments : 1 = yes, 0 = no

scope

Default Value: all

status

Limit search to locations with a spefic status (1 is active, 0 is pending approval) Default Value: 1

country

Search for locations in this Country (no partial matches, case sensitive). Default Value: none

Accepted Arguments : Use two-character country codes as defined in countrycode.org, e.g. US,GB,ES

region

Search for locations in this Region (no partial matches, case sensitive). Default Value: none

state

Search for locations in this State (no partial matches, case sensitive). Default Value: none

town

Search for locations in this Town (no partial matches, case sensitive). Default Value: none

postcode

Search for locations in this Postcode (no partial matches, case sensitive). Default Value: none

Category Attributes

Aside from general attributes for lists, See the WordPress get_terms() Codex for a list of possible search attributes/arguments.

Calendar Attributes

Along with these attributes, you can also use the general, event and location attributes. This applies to all calendar related functions and shortcodes, e.g. em_calendar(), [events_calendar], EM_Calendar::output()

full

If set to 1 it will display a full calendar that shows event names.

long_events

If set to 1, will show events that last longer than a day.

Examples

This is a shortcode showing a paged list of 10 events that occur tomorrow:

[events_list scope='tomorrow' limit=10 pagination=1 ][/events_list]

This the equivalent using PHP:

echo EM_Events::output(array('scope'=>'tomorrow', 'limit'=>10, 'pagination'=>1));

This is a list of locations that have events located in the US tomorrow:

[locations_list scope='tomorrow' limit=10 pagination=1 eventful=1 country='US'][/locations_list]

This the equivalent using PHP:

echo EM_Locations::output(array('scope'=>'tomorrow', 'limit'=>10, 'pagination'=>1, 'country'=>'US', 'eventful'=>1));