Blurbette Plugin: The Blueprint

The rough concept: create a plugin that provides “Blurbettes,” which are small content clippings that can be included anywhere in a blog. Change a Blurbette, and the change is reflected anywhere it’s included.

A Blurbette might be a copyright statement, author signature, important update notice, pull quote, just about anything. The Table of Contents in this series is a Blurbette, included within each post.

Let’s start with a couple of basics:

• This clearly looks like it should be a custom post type. WordPress automatically creates the edit and listing panels, and provides easily-configurable options for supporting certain features.
• To include a Blurbette in a post or elsewhere, a shortcode seems pretty standard. Something like
  [blurbette identifier="something"]

So we already have two tasks — I’ll keep a running list, starting with these two items:

• Custom post type.
• Shortcode that identifies a particular Blurbette and outputs it.

Now let’s brainstorm.

• Shortcodes can be cumbersome for non-technical people to type; a single typo will screw it up. What about a button within the post content editor window (TinyMCE)?
• How can the user include our Blurbette in a sidebar? S/he could use a Text Widget and type a shortcode, but again, that’s non-intuitive and frustrating for non-technical types. How about a separate widget for outputting any Blurbette?
• Both these options are great, but what if the user doesn’t want one or the other? How about a Settings panel which turns these options on or off?

I’ll add these ideas to our task list:

• Custom post type.
• Shortcode that identifies a particular Blurbette and outputs it.
• TinyMCE button that outputs a shortcode for the user.
• Blurbette Widget.
• Settings control panel

We can dig a little deeper, and refine our idea even more.

• User may decide a particular post would make a good Blurbette. How about enabling a special Copy button within the post editor that turns the current post into a Blurbette?
• If the user defines lots of Blurbettes, s/he may intend certain ones to be available within posts, and others to be available within sidebars, and so on. How about a control in the Blurbette editor that specifies which areas the Blurbette can appear in?

Both the above ideas are well-suited for metaboxes. Need a primer? Read WordPress’ documentation on the subject. I’ll add these to our task list:

• Custom post type.
• Shortcode that identifies a particular Blurbette and outputs it.
• TinyMCE button that outputs a shortcode for the user.
• Blurbette Widget.
• Settings control panel
• Post “copy” metabox
• Blurbette options metabox

Designing the classes

If you’re thinking procedurally, you might already have some idea of the number of functions required to accomplish these tasks. Furthermore, everything is inter-connected so all the functions will require careful tuning and re-editing as we go along. This is a pretty complex job.

So, let’s not think procedurally. Let’s devise a number of classes, and do our best to make each class autonomous — no need to keep tweaking all of them, every time we add a new method or feature.

• Right off the bat, it’s clear we need some way to organize all our classes. This calls for a coding pattern known as a registry: one master class that does all the business of instantiating, storing and referencing the rest of the classes.
• There are lots of one-off data that must be declared, just to define the particulars of a Blurbette. For instance, the standard post type data that labels the page / menu names in the admin areas. These labels don’t change.

I propose two classes. Again, I’ll keep a running list:

1. A registry class (manages all the other classes)
2. A definition class (defines all the one-off data and particulars of a Blurbette post type)

Naturally, the registry will have to evolve as we define more classes. And the definition class may have to expand a bit depending on the needs of the other classes. But let’s see if we can turn the remaining task list items into autonomous classes:

• Shortcode: A class that provides the shortcode functionality; the registry can add_shortcode referencing its main method.
• TinyMCE Button: A class that registers the proper hooks and enqueues the CSS and javascript.
• Widget: A class that extends the standard WordPress Widget class.
• Settings Control Panel: A class that presents the HTML form, and interacts with the options database.

As you’ll see, each task fits neatly into a distinct class, and all business related to each task can be contained therein, with maybe one or two small exceptions.

As for the last two task items, the metaboxes, I want to point something out: All the hooks and methods which define a metabox are pretty repetitive. This is a good opportunity to create an abstract class (one that must be extended, and completed, before creating an object instance). As you’ll see, this will make the task of creating any metabox quite simple, requiring only a handful of arguments, and one to three method definitions.

So I’ll propose three more classes:

• An abstract metabox class which automates the repetitive setup business of any metabox.
• The Post “copy” metabox which extends this abstract class.
• The Blurbette options metabox which extends this abstract class.

Now we have our final list of classes to define. In the following chapters I’ll discuss each item in detail.

1. A registry class (manages all the other classes)
2. A definition class (defines all the one-off data and particulars of a Blurbette post type)
3. Shortcode class
4. Tiny MCE button class
5. Widget class
6. Settings control panel class
7. Abstract metabox class
8. Post “copy” metabox class
9. Blurbette options metabox class