Introducing: We The People WordPress Plugin

This weekend we released the We The People WordPress plugin from the grounds of the White House in Washington, D.C. The plugin enables WordPress site owners to easily embed petitions from We The People using shortcodes and widgets. It’s targeted towards activists, interest groups, and campaigns but made to be simple enough for any user who cares about an issue to embed that content in a WordPress site.

When developing the plugin we had three main goals:

Make it as easy as possible for site owners to embed petitions
Provide reasonable defaults but make them easy for developers to override
Reduce impact on site performance

When deciding on whether or not a feature should be implemented (at least in version 1.0), it needed to meet at least one of these goals or be put off until a time where it was more reasonable to include. There were a few features, including embedded themes, which we decided to put off until version 1.1 for the sake of time, but will likely be available within the next few weeks.

If there are features you’d like to see, please create issues on the plugin’s Github page.

Goal #1: Make it as easy as possible for site owners to embed petitions

WordPress shortcodes are admittedly one of those things that sound great on paper but can be difficult for clients to remember without having it written down somewhere (in fact, client-specific shortcodes were one of the main reasons I wrote WP Client Reference). Petition IDs are also difficult to extract from the We The People site, so simplifying the combination of a hard-to-remember syntax with hard-to-retrieve information was an obvious first step. To make it as easy as possible for the end-user we created a TinyMCE plugin (the term used by TinyMCE to describe buttons in the WYSIWYG editor) that lets the user search We The People by title to find the desired petition. Once the user clicks “Insert Petition,” a shortcode that looks like [wtp-petition id="123"] will be inserted into the post.

For more long-term display of petitions we also created a WordPress widget that can easily be added to any dynamic sidebar in a WordPress theme. The widget functions very similarly (at least in terms of user experience) to the TinyMCE plugin but these petitions can live anywhere in the theme that users can place widgets. This flexibility makes it perfect for important petitions without risking them getting lost in the shuffle (especially if the user runs a very active blog).

Goal #2: Provide reasonable defaults but make them easy for developers to override

Out of the box, We The People petitions inherit almost all of their styles from the parent WordPress theme. This was a very intentional move as far too many plugins load default styles that conflict with user themes, resulting in third-party content sticking out like a sore thumb. We The People takes the opposite approach; it relies on themes for most of its styles and the styles it does load can be disabled using the typical WordPress enqueue/dequeue workflow. Future versions of the plugin will introduce some out-of-the-box themes that can be toggled by users who don’t want to (or can’t) edit their themes (see “The future of the plugin” below).

One of the beautiful things about WordPress is its template hierarchy model. If I wanted my “About Us” page, located at http://example.com/about, to use a unique page template, I could create that template in page-about.php and WordPress will load that instead of the default page.php for that single page (if you’re re-using these custom templates it would be best to use named templates to prevent duplication). We wanted similar functionality within our We The People plugin – if a petition template is defined in the active theme then it should take precedence over the built-in templates.

The order of precedence for petitions embedded via shortcodes is as follows:

wtp-petition-{id}.php (child theme)
wtp-petition.php (child theme)
wtp-petition-{id}.php (parent theme)
wtp-petition.php (parent theme)
templates/wtp-petition.php (plugin)

Since widgets often have less space to work within, there are separate templates for We The People widget instances:

wtp-petition-widget-{id}.php (child theme)
wtp-petition-widget.php (child theme)
wtp-petition-widget-{id}.php (parent theme)
wtp-petition-widget.php (parent theme)
templates/wtp-petition-widget.php (plugin)

Goal #3: Reduce impact on site performance

One of the quickest ways to slow down your site is to run a bunch of requests for third-party services. Those requests put you at the mercy of a server you don’t control and if the server hangs when sending you a response it can severely impact your page load times. To mitigate this risk, the We The People plugin uses three levels of caching.

The first is a simple javascript object cache in the TinyMCE plugin and WordPress widget (save the Ajax results to a JS object in case the user hits backspace). The second and third layers use the WordPress Transients API which enables us to save API responses in the database for short amounts of time. Right now all API calls are being stored for 60 seconds, meaning if a site is getting hit with lots of traffic it’s making only one call per minute to the API, reducing load time significantly. The third layer of caching is a long-term transient, saving that 60 second call for up to 24 hours. This protects your WordPress site from breaking if the We The People site disappears or starts returning errors, which happened to me several times during the development of this plugin.

The future of the plugin

Embedding petitions is nice, but the part I’m most excited about is the future of the plugin when the White House introduces its write API for We The People. Once implemented visitors will be able to sign petitions directly from the embedded petition without having to link off to the We The People site. I look forward to a day when an author can write a post about why he or she supports a petition, there can be a spirited discussion in the comments, and readers can sign the petition without having to leave the post.

Planning for and work on version 1.1 of the plugin has already begun, too. This version will focus on making it even easier for users to find and embed petitions and will introduce some pre-built petition themes to help spruce up the otherwise-unstyled output (again, great for theme developers but perhaps less-so for the casual user). Version 1.1 will also introduce all sorts of CSS class hooks to make it easier to style petitions based on the content within them (for example, a gun-related petition may look different than a gay marriage petition).

You can follow the progress of and contribute to the plugin’s development on Github.