Creative Coding

Developing Plugins With WordPress Boilerplates: Why Boilerplates Matter


Over the past five to ten years, building sites and applications for the web has become much more complex than much of the stuff that people were building in the 90's. Long gone are manually creating sites using uppercase HTML, table-based layouts, and ugly JavaScript to make some type of cute animation happen on a page.

Now we've got a variety of technologies, frameworks, and languages all of which work together to help us build full on software applications that run within a browser.

It's an awesome time to be a developer.

Because there are so many different technologies with which we can work, boilerplates are becoming more and more popular. For those who aren't familiar, boilerplates are basically foundational code that help developers jump start projects without having to write code or certain components that are common to all sites and/or applications.

Sure, they can be overdone to the point of being bulkier and more complicated than necessary, but all of the good ones are meant to lay a foundation - that is, to provide a sort of scaffolding - to help you focus on writing your core algorithms, code, and functions that are unique to your projects and needs.

Over a year ago, I started working on two projects - the WordPress Plugin Boilerplate and the WordPress Widget Boilerplate - each of which aim to provide a foundation off of which developers can build plugins using WordPress best practices. Thankfully, the projects have received a number of other contributions from the open source community to help make them as strong as possible.

One of the aspects of maintaining these projects is that I often receive questions of why I have laid things out the way that I have. So in this two part series, we're going to examine the Boilerplates, the reasons (and advantages) of organizing them the way that I have, and then we'll build a simple plugin using one of these Boilerplates to give an example of how to use them in your future projects.

File Organization

One of the key components of building any software application - regardless of how large or how small - is how the program is organized. This isn't just limited to how the classes and/or functions are related either (that's a topic of a whole other article), but how the files are organized as well.

Ideally, files should not be simply dumped into a directory and then left for other developers to sift through in order to maintain the project. Instead, they should be logically organized in coherent directories, clearly - not cleverly - named, and it should require any developer who is contributing to the project very little effort to understand where certain files are located and where to put his or her own additions.

One Does Not Simply Put Files Anywhere

It's like the old adage:

A place for everything and everything in its place.

In creating both the Boilerplates, I not only tried to follow this particular principle, but I also tried to follow inspiration from how Ruby on Rails models its layout. Specifically, they favor "convention over configuration."

Obviously, WordPress is not Rails, nor is it an MVC framework, nor am I trying to make it so. I'm simply trying to borrow good ideas from other developers in order to make our lives a bit easier within the context of our environment.

Core Plugin File

Regardless of how simple or how complex your plugin is, it must include at least a single PHP file. This file serves as the core plugin file where all of the code, logic, and functionality is contained that gives your plugin life.

If you look across the spectrum of plugins, you'll notice that developers have different practices:

  • Some include everything in a single file
  • Some break related functionality out into separate files and use the core plugin file to simply include each of them
  • Some separate some of the frontend code from the server side code

I'm not here to make a case for why any of these methods (even those mentioned) are better than the others; just why the Boilerplates are laid out in the way that they are and how it can work for you.

WordPress Plugin Repository
The plugin's homepage based on the README file.

In addition to a core plugin file, WordPress plugins require a README in order to provide the end user with some instruction on how to use the plugin as well as populate the page in the WordPress plugin repository.

At the most very basic level, this is all that's required of a WordPress plugin: a core plugin file and a README. You can get away with building some significantly complex plugins with just these two files; however, it can become incredibly difficult to maintain especially if other developers begin contributing which may ultimately result in unintended bugs.

As such, I'm a big fan of logically separating the components of the code.


Views is a word that I borrowed from the MVC pattern (as well as being inspired from Rails).

Views can be defined as the frontend markup that renders elements on the screen for both administrators and site visitors.

That's all. Easy, right?

Sure, because we're working in PHP there are bound to be minor PHP tags placed throughout the code, but the majority of a view file should be HTML with class and ID attributes.

Within the Boilerplates, there are two views:

  1. admin.php is the view that is used to render the elements for users in the administrative dashboard
  2. widget.php or plugin.php is the view that is used to render the elements for site visitors

Naturally, plugins may not have a view for the dashboard or for the site visitors. In that case, the views directory would be deleted and the code responsible for including them within the core plugin file would be removed.


This is a trivial component of the Boilerplates as anyone that does any kind of frontend development knows how to manage stylesheets and likely has their own approach to organizing them.

But to be consistent, it's worth mentioning that the css directory is where all of the stylesheets are kept. The files also follow the same naming convention as their associated views.


  1. admin.css is the view that is used to style the elements for users in the administrative dashboard
  2. widget.css or plugin.css is the view that is used to style the elements for site visitors

I've toyed with the idea of introducing a directory structure for LESS or SASS, but I think that's getting too opinionated for development and it's not the direction in which I want the Boilerplates to go. I'd rather developers pick their own flavor and incorporate it.

To that end, the way I normally organize my stylesheets in my own projects is to introduce a dev directory in the css directory and then introduce an admin.less and plugin.less file which is then compiled and minified into the root css directory.

This continues to follow suit of organizing the Boilerplates while also allowing me to include my LESS files.


Like stylesheets, the JavaScript files are a trivial component to the Boilerplates as most people who have worked with WordPress and developed a theme or plugins have used JavaScript.

Unfortunately, one of the most frustrating parts of using JavaScript in WordPress - as both a user and a developer - is that developers don't often follow best practices.

Generally speaking, developers should always do the following:

  1. Use the version of jQuery that's bundled with WordPress
  2. Avoid conflicts with the jQuery '$' function by gaining access to it with an anonymous function
  3. Don't deregister jQuery as other plugins and the theme may be using it

With that said, the Boilerplates - like stylesheets and views - are organized in the following manner:

  1. admin.js is the JavaScript that is used to manage the behavior of the elements for users in the administrative dashboard
  2. widget.js or plugin.js is the JavaScript that is used to manage the behavior of the elements for visitors

As with stylesheets, developers may also opt to lint and/or minify their JavaScript prior to releasing their plugin. To avoid being too opinionated with respect to how JavaScript files are managed, there are no subdirectories included in the Boilerplate, but I often create a dev directory in the js directory in order to manage my pre-linted, pre-minified JavaScript.


One aspect of building plugins is making sure that they are accessible and translated by those who speak other languages. To make that as easy as possible, the Boilerplates also include a lang directory and a skeleton plugin.po file.

This file is meant to be used in conjunction with POEdit so that once you've completed development, you can process all of the localized strings easily.

What About Images and Other Assets?

Other than stylesheets and JavaScript files, the Boilerplates do not provide any directories or conventions for managing other assets such as images.

Again, it's a balance of trying to avoid being too opinionated while also providing just enough scaffolding to get developers started with focusing on their core functionality. Although not every plugin will include administrative CSS, JavaScript, or views, they are far more common than including images and other assets.

Still, the convention that's been supplied would dictate that you can create an assets directory, an images directory, an icons directory, or whatever other type of file with which you'll be working.

Why Bother?

WordPress Widget Boilerplate
The WordPress Widget Boilerplate

So what's the point of all of this? Wouldn't it be just as easy to open a single file and begin writing all the code? Definitely. But remember, the bulk of development comes after a product is released, and if you take plugin development seriously, then you're in the business of building products.

As such, you need to begin with the end in mind. Using a consistent scheme for organizing your files, naming your files, and so on:

  • Eases development in the long term such that you and contributing developers know how to manage the files, where to place new files, and where to look for dependencies should they need them
  • Makes maintenance easier by providing a common organization and pattern off of which the plugin can be enhanced
  • Improves the ability to scale the project beyond the first version without needing to do a significant amount of refactoring once the codebase gets unwieldy

Above all else, the scaffolding should provide developers the ability to easily begin working on the core business logic of their product without getting in their way.


In this article, we reviewed the "Why" of the organization of the Boilerplates, but we've not actually reviewed the "How" of the Boilerplates, so in the next article we'll take a look at just that.

Specifically, we'll work step-by-step through building a plugin using one of the Boilerplates so that we can identify the typical steps that are needed to grab a copy of the Boilerplate and begin development.

Related Posts
  • Code
    Theme Development
    Creating a WordPress Theme From Static HTML: Releasing Your ThemeCreating wordpress theme from html 400
    If you've been following this series you now have a working WordPress theme. Your theme has a number of template files, including a page template and an archive template, and also has featured image support.Read More…
  • Code
    Web Development
    Build Your Own Yeoman GeneratorYeoman wide retina preview
    Take a look at some of the more interesting features of Yeoman by learning how to build your own Yeoman generator.Read More…
  • Code
    JavaScript & AJAX
    Connect 4 With Socket.ioSocket io wide retina preview
    Today we'll see how we can use Node.js and to create a multiplayer Connect 4 style game.Read More…
  • Code
    Creative Coding
    Creating a TextMate Bundle to Easily Package Your WordPress ProjectTextmate bundle 400
    If you've developed a WordPress theme or plugin, then you know how fast your codebase can grow in just a short amount of time. You start off with just a few PHP, JavaScript and CSS files. Then you find yourself creating image assets and adding them to your codebase together with their Photoshop file counterparts. After a while you'll be including other third-party PHP libraries as well. Then when you're finally ready to ship your WordPress project, you'll end up having a web of multiple file types like *.php, *.css, *.scss, *.js, *.min.js, *.png and *.psd, maybe you'll have some hidden files like .DS_Store. You would eventually need to clean your codebase up before zipping them all up for your users. Normally, this just means that you duplicate your files, then scan each and every directory deleting all the unwanted files. You'd then archive your project then perhaps use a third party app to remove the hidden files. This article will teach you on how to automate this packaging process by building a TextMate Bundle that would do everything for us with a single shortcut key. [tip]This article teaches about some tips regarding TextMate, an awesome code editor for Macs. You can find more information on TextMate from MacroMate's website[/tip]Read More…
  • Code
    WordPress Initialization Hooks: Benefits and Common MistakesHooks
    In programming, initialization of data is important as it's where we setup the prerequisites for the application such as its attributes, its required files and data, its connection to the database, and so on. WordPress itself has a well-defined initialization procedure. Through the page life cycle, WordPress fires a number of actions many of which we've covered in previous articles. To that end, it provides a set of initialization hooks which are naturally used to initialize the application before executing its primary functionality. As plugin and theme developers, it's important to understand the use cases and common mistakes of these initialization hooks, in order to build quality applications. In this article, we are going to take a look at the importance of WordPress initialization hooks and how they are used in various scenarios.Read More…
  • Code
    Creative Coding
    Developing Plugins With WordPress Boilerplates: Building a PluginDeveloping 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.Read More…