If you are creating a custom events website for which RSVPMaker is the foundation but you want to add your own flourishes, you should be aware of several utilities functions.
I created these for my own selfish purposes. As someone who customizes events for specific purposes, I have gradually gotten to the point where I don’t want to deal with the internal complexities of my own plugin. And from studying the APIs of other software I’ve had occasion to modify or extend, I’ve started to figure out what that ought to look like for RSVPMaker.
Here are a few basic functions that are useful if you are trying to get events data out of the system and display it in some custom manner, for example in a widget or a shortcode different from the ones RSVPMaker includes.
To get a listing of future events use get_future_events:
$events = get_future_events();
The variable $events will be an array of objects, each of which represents an event post. The event post objects include all the usual blog post fields such as post_title, post_author, post_content, with the additional fields datetime (the SQL timestamp for the date and time of the event) and date (date formatted as Month Day, Year as in July 6, 2017). You can add where and limit parameters to the query. You then loop through the results like in this example using a shortcode.
function rsvpmaker_utilities_test () {
$output = '';
$events = get_future_events('post_author=1',10);
foreach($events as $event)
{
$output .= sprintf('%s %s',get_permalink($event->ID), $event->post_title,$event->date);
} return $output;
}
add_shortcode('rsvpmaker_utilities_test','rsvpmaker_utilities_test');
The full function signature is
get_future_events ($where = '', $limit='', $output = OBJECT, $offset_hours = 0)
Changing the $output parameter from OBJECT, the default, to ARRAY_A, would give you an associative array for each event. The fourth parameter, $offset_hours is used to prevent events from expiring off the list the moment their start time is past. I’ve come across a number of situations where it’s preferable to have an event displayed several hours past the start time, for example so people who are arriving late or are in the middle of the meeting can still look up details such as the agenda or location.
There is also get_past_events function, which works almost the same way (no $offset_hours parameter) but lists past events starting with the most recent and counting backwards.
Here’s an example that would pull in all the past events since the start of 2017.
$events = get_past_events("datetime > '2017-01-01' ");
You can retrieve a single event using get_rsvp_event. It accepts 2 parameters, $where and $output (defaults to OBJECT)
$event = get_rsvp_event('datetime > CURDATE');
or
$event = get_rsvp_event('ID=3');
Here are a few others that might come in handy.
Use get_events_by_template to retrieve all the events associated with a specific template, in ascending date order by default and as row objects by default.
//showing defaults get_events_by_template($template_id, $order = 'ASC', $output = OBJECT); //example $template_31_events = get_events_by_template(31);
Count of future events (no parameters)
$count = count_future_events ();
Get the date associated with an event, based on ID, with get_rsvp_date. SQL date will be returned. To format, you might use strtotime as in this example.
global $post;
$timestamp = get_rsvp_date($post->ID);
$t = strtotime($timestamp);
echo date('F jS, Y',$t);
Because a single event can span multiple dates, there is also a get_rsvp_dates function that returns an array of timestamps. This is also the version you would have to use if you also want to retrieve the event duration. Look at the rsvp_date_block function in rsvpmaker-pluggable.php for an example of how RSVPMaker uses this internally to display the date or dates at the top of an event post.
To test whether an event is in the future, use:
is_rsvpmaker_future($event_id, $offset_hours)
The $event_id is the post ID, while $offset_hours (default = 0) is the number of hours past the start time where this will return true. For example, you wouldn’t necessarily want it to evaluate to false for an all-day event.
To retrieve the same values you would get from the rsvpmaker_upcoming shortcode (or the comparable Gutenberg block), you can use:
rsvpmaker_upcoming_data($atts)
This returns an array of rows that you can feed into your own display function.
$atts is an array of the same attributes you would use with the shortcode. Examples: $atts[‘posts_per_page’] (default: 10) or $atts[‘days’] (days worth of results to include (default: 365). The stricter of the two limits will be applied.
To check whether an event is based on a template, this function will return either the ID of the template or false if there is none.
has_template($post_id)
Can I Help?
If you would like help creating custom events websites, I am available as a consultant. Drop me a note at david@rsvpmaker.com. Some of the customizations I’ve worked on over the past couple of years include:
- Signups for volunteer roles at a rifle range, with a reporting back end to show which roles are filled versus open for each shift.
- A network of membership-based event websites for a nonprofit organization (Toastmasters), set up as subdomains using WordPress multisite. Chapter officers can sign up to get a free site, using a custom user and site registration process. They can then manage their own events and create accounts for their own members. They can collect event registrations via RSVPMaker but also sign members up to fill specific roles using the WordPress for Toastmasters extensions.
- In a couple of cases, I’ve made signing up for MailChimp a prerequisite for creating a user account. The MailChimp confirmation message directs people back to a website page with a coded url that includes their email address. Before the signup form will display, their subscription must be verified via the MailChimp API.
Toward a Proper API
Going back to 2010, RSVPMaker has included a mechanism for developers to override pluggable functions with their own versions. The functions documented above represent the beginnings of a cleaner API.