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: If the format attribute is not provided, 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. When providing a custom format value, format_header and format_footer will be blank if not also provided. 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: If the format attribute is not provided, 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. A limit higher than 0 is required for offsets to work.

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-separated fields (e.g. "event_start_date,event_name").

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

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.

page

Which page shall be shown. Requires pagination to be set to 1 and will override the offset value if also provided.

page_queryvar

The default parameter name used to figure out the page number to show is pno, provide a unique name if you want to display two lists on the same page with independent pagination.

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, slug or comma-separated ids or slugs (e.g. "1,categories-slug,3") to limit the search to events in any of these categories. You can also use negative numbers and slugs to exclude specific categories (e.g. -1,-exclude-categories,-3). If you mix inclusions and exclusions, all events with included categories AND without excluded categories will be shown. You can also use & to separate ids and slugs, in which case events must contain (or not contain) both categories to be shown.

event

Supply a single id or comma-separated 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.

near

Accepts a comma-separated coordinates (e.g. 1,1) value, which searches for events or locations located near this coordinate.

near_unit

The distance unit used when a near attribute is provided. Default Value: mi

Accepted Arguments : mi or km

near_distance

The radius distance when searching with the near attribute. near_unit will determine whether this is in miles or kilometers.

owner

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

post_id

Supply a single id or comma-separated 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

recurrences

Show only recurrences if set to 1 or non-recurrences if set to 0, shows all events if not used.

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 or recurrences if you want to filter event recurrences.

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 separated 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, week, this-week, month, this-month, next-month, 1-months, 2-months, 3-months, 6-months, 12-months, all

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

tag

Supply a single id, slug or comma-separated ids or slugs (e.g. "1,tags-slug,3") to limit the search to events in any of these tags. You can also use negative numbers and slugs to exclude specific tags (e.g. -1,-exclude-tags,-3). If you mix inclusions and exclusions, all events with included tags AND without excluded tags will be shown. You can also use & to separate ids and slugs, in which case events must contain (or not contain) both tags to be shown.

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.

has_location

When set to true, only events WITH an assigned location will be shown, has priority over no_location.

no_location

When set to true, only events WITHOUT an assigned location will be shown.

groupby

Show one event for each unique value of the provide field name, along with events contaning no defined value for that field. See our grouping documentation for more information.

Accepted Arguments : Database field name from the wp_em_events or wp_em_locations tables, e.g. event_name or location_name

groupby_orderby

When groupby is defined, the fields defined here will determine the sorting of events in each group. See our grouping documentation for more information. Default Value: event_start_date,event_start_time

Accepted Arguments : Database fields (comma-seperated) in the wp_em_events and wp_em_locations tables, e.g. event_start_date,event_start_time or location_name

groupby_order

Indicates the alphabeitcal/numerical/date order of the sorting in groupby_orderby. Choose between ASC (ascending) and DESC (descending), case insensitive. Default Value: ASC

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)

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, can be comma-separated e.g. US,GB,ES

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-separated ids (e.g. "1,2,3") to limit the search to locations with the location_id(s).

near

Accepts a comma-separated coordinates (e.g. 1,1) value, which searches for events or locations located near this coordinate.

near_unit

The distance unit used when a near attribute is provided. Default Value: mi

Accepted Arguments : mi or km

near_distance

The radius distance when searching with the near attribute. near_unit will determine whether this is in miles or kilometers.

owner

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

post_id

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

postcode

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

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

region

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

scope

Default Value: all

state

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

status

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

town

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

groupby

Show one location for each unique value of the provide field name, along with locations contaning no defined value for that field. See our grouping documentation for more information.

Accepted Arguments : Database field name from the wp_em_events or wp_em_locations tables, e.g. event_name or location_name

groupby_orderby

When groupby is defined, the fields defined here will determine the sorting of events in each group. See our grouping documentation for more information. Default Value: event_start_date,event_start_time

Accepted Arguments : Database fields (comma-seperated) in the wp_em_events and wp_em_locations tables, e.g. location_country,location_town or location_name

groupby_order

Indicates the alphabeitcal/numerical/date order of the sorting in groupby_orderby. Choose between ASC (ascending) and DESC (descending), case insensitive. Default Value: ASC

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));