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.

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.

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

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.

Stylesheets

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.

Specifically:

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.

JavaScript

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.

Languages

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?

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.

Conclusion

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.