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.
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 difference 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 alphabetical/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
orlocation_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.
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 occurring 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 specific 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.
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 containing 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
orlocation_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-separated) in the wp_em_events and wp_em_locations tables, e.g.
event_start_date,event_start_time
orlocation_name
groupby_order
Indicates the alphabetical/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 specific 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 containing 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
orlocation_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-separated) in the wp_em_events and wp_em_locations tables, e.g.
location_country,location_town
orlocation_name
groupby_order
Indicates the alphabetical/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));