Developing Plugins With WordPress Boilerplates: Building a Plugin

In the first article of this series, we looked at how a boilerplate can improve your development efforts by providing a foundation off of which your project can be built.

Ideally, boilerplates should provide just enough of a framework to get started while letting you focus on the specific business logic, core need, or domain-specific code that you need to write.

Specifically, we took a look at the WordPress Widget Boilerplates and the WordPress Plugin Boilerplate. In this post, we're going to take advantage of the Plugin Boilerplate to write our own plugin in order to see how Boilerplates both lay the foundation for writing good code, and how we can use it as a starting place for our future work.


A Post Message Plugin

In this post, we're going to be building a post notification widget that allows the author to add a new post message before the content on their page. This will actually be based on a plugin that's already in the wild so you can have a point of reference once the project has been completed.

As with the rest of my tutorials, I like to plan out the project in advance so let's lay out everything that we're going to be doing:

  1. Download a copy of the WordPress Plugin Boilerplate
  2. Fill out the TODO's with the specific information for your own project
  3. Implement the code necessary to display and save information in a post meta box
  4. Check for the existence of post meta and then render it in the content
  5. Finish up the README and Localization

Overall, it's a relatively simple plugin but it should provide a solid example of how Boilerplates allow you to focus on your specific functionality all the while working within the context of WordPress best practices.


Building the Widget

1. Download the WordPress Plugin Boilerplate

In order to get started, you need to download a copy of the WordPress Plugin Boilerplate. You can do this by navigating to its GitHub page, then clicking on the 'zip' button that you see near the top of the page or by clicking here.

Next, extract the contents of the download into your plugins directory. It should initially write out a directory called plugin-boilerplate.

WordPress Plugin Boilerplate
Rename this to post-message. At this point, we're ready to begin working on the source code for the boilerplate.

2. Fill Out the TODO's in the Boilerplate

Next, open the post-message directory in your favorite IDE. The first thing that we want to do is open plugin.php and then locate all of the TODO's that exist in the code.

Out of the box, the code will look something like this:

Next, we need to make each TODO plugin-specific so we'll place all instances where needed with a variation of the name of the plugin.

For example:

  • Replace the name of the plugin with Post Message
  • Replace the URL of the plugin with your URL of choice
  • Populate the name, email address, and all personal information with what works
  • Name the class Post_Message
  • Name any locale-related strings, classnames, and ID's post-message

Next, we can also remove all of the JavaScript and stylesheet calls except the admin.css styles. We'll be using this file later. Also be sure to remove the following files from the Boilerplate:

  • views/display.php
  • css/plugin.css
  • js/admin.js
  • js/plugin.js

This should leave you with the following directory structure:

WordPress Plugin Boilerplate Directory Structure

Note that this is one thing about a Boilerplate: if anything, you should want to remove something from it. If you have to add something to it that helps you get off the ground - or that's more foundational - then it may be an opportunity to improve it.

Anyway, though we're not done yet, and though we will be adding to the plugin, the file should look something like this at this point:

Next, we need to actually begin working on our core business logic.

3. Implement the Code Necessary to Display and Save Information in a Post Meta Box

First, we need to identify exactly how this is going to work:

  1. We'll display a post meta box directly under the content editor
  2. It will include a text area that allows users to provide their own content
  3. When the post is updated, it needs to save the content of the text area

So the first thing we need to do is introduce a hook and a function in order to capture the data in the post meta box. In the constructor, let's add the following line:

add_action( 'add_meta_boxes', array( $this, 'add_notice_metabox' ) );

Next, we need to define the function add_notice_metabox so that we can actually render the meta box, so let's provide that function now:

After that, we need to write a function that's responsible for actually rendering the post content:

Above, notice that we've introduced a nonce field for security purposes. Notice also that we've given this textarea the ID of post-message so that we can easily style it using CSS, and we've given it the name post_message which will come in handy as we save the contents of the textarea to the specific post's meta data.

Finally, we've taken advantage of the esc_textarea function to make sure that we're properly encoding our data for rendering it in the textarea.

At this point, let's add some light styling using the admin.css file to give the post message a slightly different look and feel from the content:

This should result in something like the following:

Plugin Message Example

Of course, we still aren't done. We need to actually save and retrieve the data when the user clicks on the "Publish" or the "Update" button. To do this, we need to setup a call back for saving the post data.

So the last thing that we need to do is to introduce a save_notice function. First, we'll register this in the constructor with the following code:

add_action( 'save_post', array( $this, 'save_notice' ) );

Then, we'll define the following function:

We've discussed saving the contents of post meta data at length in previous articles, so I don't want to belabor the point here, but suffice it to say that the function does the following:

  • Verifies that the user has permission to save this information
  • Deletes any existing post meta data
  • Saves the data to the associated post meta data

At this point, we're ready to test the plugin so fill out the textarea, save the data, and when the page refreshes, make sure that the data also shows up in the textarea.

If so, we're ready to move on; otherwise, make sure your code looks like the code above.

4. Render the Post Notice

Next up, we're ready to render the post message in the content. The process for doing this will be as follows:

  • Register a function with the the_content filter
  • Check for the existence of post meta data
  • Render it above the content if it's present

So let's do just that. First, let's register a function with the_content filter:

add_filter( 'the_content', array( $this, 'prepend_post_message' ) );

After that, let's setup the actual function:

Notice that the post message is contained within its own p element with its own class name so that you can easily style it however you'd like, should you want to do so.

At this point, we should have everything that we need in order to see the post message, so let's test it out. Create a post message, publish it, then view the post in your browser.

Next, remove the post content and then verify that nothing appears.

Easy enough, isn't it?

5. Finish Up the README and Localization

Finally, we need to make sure that we clean up the README and properly localize the plugin.

First, the README should contain the usual information. This is largely subjective; however, I've provided an example README below:

And finally, localization should be a cinch: Simply open the `plugin.po` file in the `lang` directory in your IDE, make sure that you change up the name of the plugin and the author information, then open it in POEdit to register the localization files.

Localizing The Plugin

Save your work and you're ready to go!


Conclusion

In this series, we've examined exactly what's needed to take advantage of WordPress Boilerplates, how they can help impact our workflow, and help us to focus more on the core of our project rather than re-inventing the wheel and getting up and going by repeating a lot of what's already needed.

Additionally, we built a plugin that can be downloaded for further review.

Hopefully this series has provided a case for why you should be using boilerplate code when applicable, and has helped to show how they can ease the pain of re-writing a lot of the same code in each of your projects.

Tags:

Comments

Related Articles