Writing Maintainable WordPress Widgets: Part 1 of 2

Best of Wptuts 2011: Every week through January, we're going to revisit some of our favorite posts from 2011. Plugin development can often feel like the wild west if you're creating something from scratch without a boilerplate or a similar plugin to work from - Tom's 2 part series on Maintainable WordPress Widgets/Plugins offers some practical guidelines that should keep you on the tracks!

When it comes to software development, frameworks and libraries are popular because they're helpful, right? They provide a consistent way to write and organize code in hopes of making development and maintenance as easy as possible.


The thing is, these very same principles that apply to larger, enterprise level systems are just as applicable to smaller projects - such as WordPress plugins - developed by a small teams. And just as larger systems are full of moving parts, such is the case with WordPress plugins.

For example: you've got the core code that is responsible for communicating with WordPress (via filters, actions, and hooks), administration dashboards, client-side views, JavaScript files, style sheets, localization files, and so on all of which are achieved using at least four different programming languages.

During my time spent in WordPress Development, I've created a few boilerplates that I use to begin each of my projects. This tutorial will take a look at my WordPress Widget Boilerplate code, how to leverage it in new projects, and an example application in hopes of helping you get your next WordPress project off to a solid start.


A Widget Boilerplate

Organization

When it comes to development, I typically try to keep things as simple as possible by planning only for the necessary features; however, this is one case in which I aim to be exhaustive. It's almost always easier to begin planning a boilerplate when you know all of the components that may go into the system.

A plugin can ultimately consist of the following:

  • Core plugin code
  • Style sheets
  • Java Scripts
  • Localization files
  • Markup
  • Images

Taking all of the above into consideration, the widget boilerplate directory is laid out like this:

We'll take a look at each directory in detail later in the article.

The Skeleton

In addition to file organization, I also like to stub out the code used to drive the widget. The WordPress Codex[1] has a detailed explanation of the Widget API[2] and because there is a suggest way to craft them, I try to follow it.

Additionally, I'm a fan of writing my code in an object-oriented manner along with code comments to help explain what's going on in each area of the code. As such, the initial widget code looks like this:

Notice there are a number of TODO's throughout the code. These are useful especially in the context of writing your code on top of the boilerplate.

Note that there are three primary sections of code, as well:

  1. Constructor. This function is responsible for initializing the widget, importing localizing files, and including JavaScript sources and style sheets.
  2. API Functions. These functions are the three functions required for administering, displaying, and updating the widget.
  3. Helper Functions. These are private functions that I use to help with often repetitive or required tasks.

The three most important functions above, the API functions are required for developing your plugin.

  1. widget() extracts the stored values and rendering the public view
  2. update() is responsible for updating the previously saved values with the values provided by the user
  3. form() renders the administration form and provides functionality necessary for storing new values.

Because plugins are often divided between the administration functionality and the client-facing functionality, I divide my JavaScript source, style sheets, and HTML accordingly. I name these files accordingly and stub them out appropriately:

JavaScript Sources:

admin.js:

widget.js:

Style Sheets:

admin.css:

widget.css:

Views:

Easy, right? You can view (and fork!) this entire boilerplate including the localization files and the README on GitHub.

There's now a place for everything and when it comes time to ship, you just exclude certain files from the final build..


A Working Example With Your Social Networks

When it comes to programming, practice helps in learning a new language or tip so here's a quick example of how to use the above boilerplate to create a simple widget for making it easy to share your Twitter, Facebook, and Google+ links.

First, we'll list out the requirements:

  • An administration view for entering values. This includes markup and styles.
  • A public facing view for displaying links to social networks. This also includes markup and styles.
  • Options for storing a Twitter username, Facebook username, and Google+ ID

Secondly, let's open up the boilerplate and begin stubbing out the necessary parts.

First, we define out plugin name, slug, and locale values. These are used repeatedly throughout the code so it's nice to store them as constants for easily retrieving them. Locate the init_plugin_constants() function and make sure that your code looks like this:

After that, we need to prepare the constructor:

And stub out the API functions:

The final version of the plugin should look like this:

Next, let's add some styles to the administration form. Locate /css/admin.css and add the following code:

And let's write the markup that will render the view of the administration form:

Finally, we need to write some markup to render the public-facing view of the widget when it's live on the actual blog:

Done and done. Not bad, huh? A fair amount of work and functionality done relatively quickly.

You can download the working source code (including an associated README) for this widget on GitHub or right here at Wptuts.

Ultimately, maintaining a software projects amounts to trying to organize complexity. Although the above boilerplate is not *the* way the organize or manage code, it's an *effective* way to organize code and I've found is extremely helpful in many of my projects and hopefully it helps you with your future work.

Remember, you can grab a copy of both the boilerplate and the example project from their respective GitHub repositories. I also highly recommend bookmarking the WordPress Codex[1]. It's a tremendous resource for anyone seeking to do advanced WordPress development.

  1. http://codex.wordpress.org
  2. http://codex.wordpress.org/Widgets_API

Moving on to Part Two...

Check out the second part of this tutorial series where we'll be digging deeper into creating maintainable plugins! We'll be looking at how to use hooks within WordPress - and then we'll actually put our boilerplate to use to create another useful plugin. Ready for Part Two?

Tags:

Comments

Related Articles