Custom Event Queries
With ternCal you can use PHP within your WordPress ™ templates to query for events. It’s easy. If any events are found you’ll be returned an array of events just as you would by using WordPress ™’ get_posts function. The event array returned works perfectly with the WordPress ™ loop.
First, let’s take a look at a standard ternCal event query.
<?php $events = $ternCal->events(array( 'view' => 'month', 'upcoming' => true )); ?>
This is a very simple version of how to query ternCal. This query will give you all the upcoming events for whatever the current month is. So, if it’s December 21st, 2012. You’ll receive a WordPress ™ post list of all the events in December that occur on or after the 21st. Does that make sense?
There are many ways to query ternCal. Let’s talk about all the parameters available to you.
view
This parameter tells ternCal whether you wish to receive a month, week or day at-a-glance.
Accepted values include:
- month
- week
- day
Default value: month
NOTE: When the “view” parameter is set to “month” you’ll get events only for the month specified. When the “view” parameter is set to “week” you’ll get events only for the week specified. When the “view” parameter is set to “day” you’ll get events only for the day specified.
month
The “month” parameter tells ternCal what month of the year you’d like to query in. So, if you want the events returned by your query to start in July, set this value to the integer 7. Your query might look like this and will return all the events in July for the current year:
<?php $events = $ternCal->events(array( 'view' => 'month', 'month' => 7 )); ?>
The same would apply if your “view” parameter was set to “week” or “day”.
Accepted values include:
- Integers 1 – 12
Default value: The number of the current month.
day
The “day” parameter tells ternCal what day of the of the month you’d like to query by. This parameter’s use changes depending on what you’ve set for the “view” parameter.
If your “view” parameter is set to “month”:
The “day” parameter specifies the day of the month you’d like to search after. So if you’re looking for upcoming events in July and you’ve set the “day” parameter to the integer 14, you will only get events that occur on or after July 14th.
This example would look like this:
<?php $events = $ternCal->events(array( 'view' => 'month', 'upcoming' => true, 'month' => 7, 'day' => 14 )); ?>
If your “view” parameter is set to “week”:
The “day” parameter is assessed for what week of the year it falls in. If the day falls within the 28th week of the year that week will be queried beginning at the first day of that week. So if you set the “day” parameter to 14, the “month” parameter to 7 and the “year” parameter to 2011, you’ll get all the events falling within the week starting Sunday, July 10th, 2011.
This example would look like this:
<?php $events = $ternCal->events(array( 'view' => 'week', 'month' => 7, 'day' => 14, 'year' => 2011 )); ?>
If your “view” parameter is set to “day”:
This parameter specifies the day for which you’d like to get events. So if you set the “day” parameter to 14, the “month” parameter to 7 and the “year” parameter to 2011, you’ll get all the events that transpire on July 14th, 2011.
This example would look like this:
<?php $events = $ternCal->events(array( 'view' => 'day', 'month' => 7, 'day' => 14, 'year' => 2011 )); ?>
Accepted values include:
- Integers 1 – 31 depending on the number of days set by the month parameter.
Default value: The number of the current day of the month.
year
This parameter tells ternCal the year in which you’d like your queries to take place.
Accepted values include:
- Any four digit year between 1970 and 2037
Default value: The current year.
stamp
The stamp parameter allows you to skip setting the “month”, “day” and “year” parameters by feeding the query a UNIX timestamp. Read about UNIX timestamps here. ternCal can then take the timestamp and determine the month, day and year parameters.
So if you wanted to get all events for July 14th, 2011 your query might look like this:
<?php $events = $ternCal->events(array( 'view' => 'day', 'stamp' => 1310601600 )); ?>
Or if you wanted to get all the events in July after July 14th, 2011 your query would look like this:
<?php $events = $ternCal->events(array( 'view' => 'month', 'upcoming' => true, 'stamp' => 1310601600 )); ?>
to_month
This parameter tells ternCal what month you’d like the query to stop searching for events. So in the event you wanted to query for events starting on July 14, 2011 and ending in September of the same year you’d have a query like the following:
<?php $events = $ternCal->events(array( 'view' => 'month', 'month' => 7, 'day' => 14, 'year' => 2011, 'to_month' => 9 )); ?>
This query would give you all events that occur on or after July 14, 2011 but no later than September 30th, 2011.
Accepted values include:
- Integers 1 – 12
Default value: false
to_year
This parameter tells ternCal what year you’d like the query to stop searching for events and it works in conjunction with the “to_month” parameter.
So in the event you wanted to query for events starting on July 14, 2011 and ending in January of 2012 you’d have a query like the following:
<?php $events = $ternCal->events(array( 'view' => 'month', 'month' => 7, 'day' => 14, 'year' => 2011, 'to_month' => 9, 'to_year' => 12 )); ?>
This query would give you all events that occur on or after July 14, 2011 but no later than January 31st, 2012.
Accepted values include:
- Any four digit year between 1970 and 2037
Default value: false
upcoming
When querying for events, dependent on the query you could receive events that have already transpired or you can receive just the events that are either happening or upcoming. This parameter when set to “true” tells ternCal to find only events that are either happening or upcoming and to ignore any events that have already happened.
An example would be:
<?php $events = $ternCal->events(array( 'view' => 'month', 'upcoming' => true )); ?>
This query returns all the upcoming events for the current month and ignores all the events that have already happened.
num
This parameter tells ternCal the number of events you’d like to find. So for instance if you only wanted the next 10 upcoming events you’d use this parameter.
Your query might look like this:
<?php $events = $ternCal->events(array( 'view' => 'month', 'upcoming' => true, 'num' => 10 )); ?>
Accepted values include:
- Any integer (numer) greater than zero
Default value: false
to_first
This is an interesting parameter. In essence when you query by month you will only get results in the month your querying. If you leave the “month” parameter blank you’ll get events only in the current month. If you set the “month” parameter to 8 you’ll get events only in August. This is the same for week and day queries. So, what if we wanted to query the month of August but if there are no events left in August to find, we want to find the first 10 events?
This query would look like this:
<?php $events = $ternCal->events(array( 'view' => 'month', 'month' => 8, 'upcoming' => true, 'num' => 10, 'to_first' => true )); ?>
This query will first search August. If no upcoming events are found in August, then September will be searched. With this query ternCal will continue to move through months searching for events until either 10 events are found or there are no remaining upcoming events.
Accepted values include:
- true
- false
Default value: false
mag
This is a parameter you probably won’t use much. We’ll explain it anyway. Think of an actual calendar; one you might hang on your wall. Think of the calendar as a grid. Seven columns across. Maybe four or five rows. More often than not the month you’re viewing in the calendar will not start on the first cell in the grid. Nor will it end on the last cell of the grid.
This is what we mean:
Notice how the 30th and 31st of October are displayed before the November dates in the grid and the 1st, 2nd and 3rd of December are displayed at the end of the grid. This is a true Month-at-a-glance view. The name of this parameter “mag” stands for “month-at-a-glance”.
This parameter determines if when the “view” parameter is set to month, the dates before and after the month being queried that fall within the month-at-a-glance view are also found.
So if we had a query like this:
<?php $events = $ternCal->events(array( 'view' => 'month', 'month' => 11, 'mag' => true )); ?>
With this query events will be found that start on or after October 30th and start no later than December 3rd.
Hope that makes sense.
Accepted values include:
- true
- false
Default value: false
calendars
This parameter tells ternCal which of these ternCal calendars you’d like to query.
So for instance if you wanted to query all the events for the current month in the “Cooking Classes” calendar:
<?php $events = $ternCal->events(array( 'view' => 'month', 'calendars' => array(‘Cooking Classes') )); ?>
Or if you wanted to query both the “Cooking Classes” and “Bethlehem Events” calendars to find cooking classes and events happening in Bethlehem:
<?php $events = $ternCal->events(array( 'view' => 'month', 'calendars' => array(‘Cooking Classes','Bethlehem Events') )); ?>
Accepted values include:
- Array of ternCal calendars. Read about adding calendars here.
Default value: empty array
NOTE: If you’re attempting to find events that are categorized in all the categories you specify you need to set the “all_cats” parameter to true. Read about the “all_cats” parameter here.
all_cals
When specifying calendars you want to query by using the “calendars” parameter, the “all_cals” parameter when set to true will make sure ternCal only returns events that are found to be in all the calendars you specify.
For instance:
<?php $events = $ternCal->events(array( 'view' => 'month', 'calendars' => array(‘Cooking Classes','Bethlehem Events') )); ?>
The above query will find all the events that are in the category “Cooking Classes” and all the events that are in “Bethlehem Events”. However let’s say for instance you wanted to find Bethlehem cooking classes. This means you want to find events that are in both the “Cooking Classes” and “Bethlehem Events” calendars. You are no longer looking for events that appear in only one of the categories you’ve specified.
To do this your query would look like this:
<?php $events = $ternCal->events(array( 'view' => 'month', 'calendars' => array(‘Cooking Classes','Bethlehem Events'), 'all_cals' => true )); ?>
Previous document → Creating Custom Post Lists of EventsNext document → Events and the WordPress "Loop"
Home » Documentation » Creating Custom Post Lists of Events » Custom Event Queries