Teardown Of A WordPress Multisite Events & Membership Site (Video/Slides/Code)

These are the slides from a WordPress meetup presentation that covered the code behind RSVPMaker, the RSVPMaker for Toastmasters extension, and a WordPress multisite instance where I offer free club websites as subdomains of toastmost.org.

The audience was at a mix of experience levels in terms of technical knowledge, with some people being more designers or business users of WordPress as opposed to programmers. I tried to frame it so those with more WordPress programming experience would have a chance of learning something new, and the others would at least get a glimpse of what is possible when WordPress is used as the basis for a community website.

To make this more useful, in addition to the slides and the video I’m sharing some of the relevant code snippets and pointers to some tutorials with more info on specific aspects.

Meetup-Tear-Down.pptx

How to create a plugin

Create a PHP file with a header like this and upload it into a subdirectory of wp-content/plugins

Actually, for a one-off hack for your own site that you don’t intend to publish, it could be as simple as

Once this is uploaded, you should see the name of your plugin on the Plugins screen of the WordPress administration dashboard inviting you to activate it.

Making your plugin do something

The point of a plugin is to add to or modify the default behavior of WordPress. You do this by connecting with the plugin and filter hooks WordPress makes available. You can modify almost everything about how WordPress functions, which means you as a developer can do either wonderful or horrible things to a website. You can change the display of content, modify the database queries used to retrieve content, or alter security parameters for who should be able to access what.

The two major families of hooks are:

  • Actions triggered as WordPress loads a page like
    • ‘init’ – means the system has been initialized, but the process of running the page lookup query and outputting content has not yet begun)
    • ‘admin_init’ – same thing on the administration back end of WordPress
    • ‘wp_footer’ – fired by the wp_footer() function call that occurs in the footer of a properly coded theme. Often used to output a snippet of JavaScript or other code at the bottom of every public page or post.
  • Filters that allow you to modify some content or data
    • ‘the_content’ – change the content of a post
    • ‘the_title’ – change the title of the post
    • ‘query_where’ – change the WHERE clause in the SQL query used by the WordPress loop for retrieving a list of posts

Here’s an example of an action on ‘init’ used to set up the rsvpmaker post type. Without that, the system would not recognize urls pointing to rsvpmaker content.

Here are a couple of filters.

I’ve abbreviated the code of some of these plugins for simplicity, but the point is that the filter on the_content

  • Checks whether the content is associated with the post type rsvpmaker, and if not returns the content unchanged
  • Looks up the date or dates (stored as post metadata) and adds it to the top of the content.
  • Checks whether RSVPs (registrations) should be collected and if so displays the RSVP form at the bottom of the post.

The filter on wp_title changes what should be output in the HTML title tag in the page header. Again, it checks if the content is rsvpmaker content and if so adds the date.

Adding AJAX

In the Toastmasters application, when a meeting organizer is assigning other people to roles, the user ID of the chosen member is sent to the server via a JavaScript AJAX method so that it’s saved even if the meeting organizer doesn’t make it down to the bottom of the form and click Save.

This is accomplished with some JQuery Javascript

and the PHP code that will accept this input and process it

The JavaScript detects when a select form field with the class .editor_assign has changed, gets the current value of that field and submits it to the server. The data is posted to a global variable ajaxurl (set automatically by WordPress) that points to a PHP file used specifically to process ajax requests. The submission must also include an ‘action’ attribute, in this case ‘editor_assign’ that WordPress will use to figure out what function to call.

The PHP code starts with an add_action call including that action string prefixed by wp_ajax_. This is the version that works for a logged in user — for an unauthenticated website visitor, it would be wp_ajax_nopriv_ or in this case wp_ajax_nopriv_editor_assign.

The add_action command identifies the function that will process the input, record it as post metadata, and send back a confirmation message to be displayed by the JavaScript routine.

Metadata for posts and users

My plugins make extensive use of custom metadata associated with posts and with users. The date of an event is stored as post metadata, and so is the 1 or 0 indicating whether the registration form should be displayed. The Toastmasters application modifies user profiles so they can contain data like home_phone and mobile_phone and Toastmasters ID # in addition to default fields like name and email address.

The pattern for getting and setting metadata is.

In both cases, when getting metadata you must specify the third parameters as true if you are trying to retrieve a single value. By default, you will get back an array, which what be what you want if your application stores multiple items such as the log messages in this example under a single lookup key.

Here is what the corresponding database structure looks like for the wp_postmeta table, with metadata for an RSVPMaker post.

Post metadata

Modifying the Editor

When we create an RSVPMaker post, we need to add form fields to the standard WordPress editor and also functions for saving the data entered into that form as post metadata.

Here’s the WordPress editor, with the additional RSVPMaker fields showing under the editor.

RSVPMaker editor

Code to add the additional “metabox” on the form (simplified).

The action ‘admin_menu’ triggers a function that registers our meta box, gives it a name, associates it with the function draw_eventdates, and says what kind of content it is associated with, in this case rsvpmaker posts.

The draw_eventdates pulls in all the metadata associated with the event so far and displays the form for setting event dates and other attributes.

Because there is a long list of options associated with setting up a registration form, those are hidden by default until the Collect RSVPs checkbox is checked. The code for displaying that section of the form looks like this.

When an RSVPMaker post is saved, the post title and content are saved just the way that they normally are. In the process, WordPress triggers the action post_save, which RSVPMaker uses to detect and save the additional data submitted from its additions to the editor form.

Shortcodes and Visual Representations of Shortcodes

WordPress shortcodes are placeholders for content to be inserted into the body of a post based on the output of a function.

Shortcodes are how this in the editor …

rsvpmaker_upcoming shortcode in the editor (Text view)

… turns into this on the website.

RSVPMaker event listing with calendar

A shortcode begins and ends with square brackets. The name of the shortcode is the first string of text after the opening bracket, and the shortcode can also include attributes like calendar="1" — which will be passed to the function to indicate the calendar should be displayed at the top of the event listings.

Here’s a simplified version of the rsvpmaker_upcoming shortcode

The excerpt shown here covers how RSVPMaker changes the standard WordPress query to look up a series of posts ordered by the date of the event rather than displaying them in blog post order of publication date. The $atts parameter is an array containing any shortcode attributes such as calendar="1" or past="1" (to display past instead of future dates).

If the shortcode uses a close tag like this

[my_shortcode]content here[/my_shortcode]

In that case, the shortcode function will also be passed a $content variable you can work with. Something like this:

To make shortcodes easier to use by non-techies, you can instead display an placeholder image in the body of the post, with a popup dialog box as a user interface for setting the shortcode attributes. You also want to add a new button in the visual editor for adding a new instance of your shortcode. What I present below is based on an excellent tutorial, Take your shortcodes to the ultimate level.

Popup editor for rsvpmaker_upcoming shortcode

Here’s an excerpt from the JavaScript code loaded as a plugin to the TinyMCE editor used by WordPress.

This script identifies shortcodes using the same regular expression (pattern matching) formula WordPress uses in PHP on the server side when rendering a post. It parses out the attributes and creates an HTML image tag that embeds those same parameters, so the data is logically associated with the image in the JavaScript object model. The src attribute of the img tag points to a url that has some of that data encoded in it, such as

Instead of referencing an image file, the img tag points to a url the plugin will use to generate an image.

Registered to execute on the admin action, before any content has been queried or output, this function first checks for the presence of a query string like ?rsvpmaker_placeholder=1 and returns if it is not found.

If that query string is present, the function loads a blank background image for the placeholder from the plugins directory, adds text based on the query parameters, and outputs the modified image. Finally, it exits before WordPress can output any other content.

Custom Administration Screens

Because RSVPMaker collects event registrations, we also need to add a screen on the administrative back end where those registrations can be viewed.

RSVP Report screen
Custom Dashboard

The default WordPress dashboard shows updates on plugins and upcoming WordPress meetups. My Toastmasters community is more concerned about managing the agenda for upcoming events, so we present them with a custom dashboard.

Toastmasters dashboard

For a more detailed tutorial, see this from WP Explorer. Here’s a quick summary.

Custom user registration and metadata

User records can also be customized to include metadata for your purposes. For Toastmasters club members, I want to record information such as phone numbers and Toastmasters ID #. Club officers are presented with an Add Member screen that asks for that additional information and records it as part of their user account, along with the required fields like user_login and user_pass (password).

We can test for whether a user is logged in, a member of a specific blog (site within a multisite install), or possesses a specific capability under the WordPress security scheme.

Add Roles and Capabilities

WordPress security revolves around user roles and capabilities. Each of the predefined roles (subscriber, contributor, author, editor, administrator) has a set of default capabilities. That list of capabilities can also be manipulated by plugins. I like the plugin User Roles Editor as a general purpose utility or this purpose. I wrote my own routines to define plugin-specific capabilities and roles.

In this example, I add a Manager role (one level up from editor, not quite an administrator) and add a capability to the default administrator role.

Making a WordPress Installation Multisite

See Create a Network in the WordPress Codex documentation for detailed instructions on configuring a single installation of the software to host a network of sites.

You start the process by modifying your wp-config.php file to include this statement:

When you return to the admin screens, you essentially get a wizard that guides you through the process of determining what settings to change wp-config.php as well as your .htaccess file.

For the subdomain configuration I used, where sites have URLs like op.toastmost.org and demo.toastmost.org, I also had to change the DNS settings to recognize “wildcard” subdomains. Just as the path to a blog post represents a logical naming convention for content in the database, WordPress can then treat subdomains as aliases for sites within the database table.

When you make these changes, WordPress modifies the database for your site to include separate tables for each site. For example, instead of single wp_posts table, you get a whole series of posts tables named according to the subdomain site ID.

Multisite tables for posts

Similarly, your uploads directory gets divided up by site ID to keep those files separate.

Multisite directories.

Finally, I use a custom site registration process that gathers information specific to my application, such as the name of the Toastmasters club and the timezone (important for calendar functions) and adds default content and settings.

The process is:

  • Club website owner first must register for an account. Custom user account registration flow requires that they first register for a MailChimp mailing list. I use the MailChimp API to verify their email address is on the list before accepting their registration.
  • User fills out the form with the requested subdomain and other data.
  • The script below creates the site.
We now have a custom-built website, with some starter content specific to its purpose as a Toastmasters website.

Questions? Drop me a line: david@rsvmpaker.com

The plugins discussed here are in the WordPress repository

You can also look them up (and contribute improvements!) on GitHub

github.com/davidfcarr

Developer Functions for Extending RSVPMaker

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:

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.

The full function signature is

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.

You can retrieve a single event using get_rsvp_event. It accepts 2 parameters, $where and $output (defaults to OBJECT)

or

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.

Count of future events (no parameters)

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.

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.

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.