Speed up Development Using the WordPress Plugin Boilerplate

A low learning curve into WordPress plugin development means that there is no one definitive way to build a plugin. A plugin can be as simple as a single file like Hello Dolly, or it can be structured as complex as needed to cater for various requirements and functionality. The WordPress Plugin Boilerplate aims to provide a standardized, high quality foundation to build your next awesome plugin.

In this first part of the series, we’ll take a deep look into the boilerplate, including how the files and folders are structured as well as code organization of the boilerplate.

Background

WordPress plugin boilerplate is originally an initiative by Tom McFarlin to provide a standardized, object-oriented approach to building WordPress plugins. Since the boilerplate is built on top of the Plugin API, and following the Coding Standards and Documentation Standards recommended by WordPress, you can be sure that you’re in safe hands.

Recent update of the boilerplate to version 3.0.0 brings major improvements to the boilerplate itself, in terms of code organisation, as well as further separation of concerns within your plugin. If you’re already familiar developing your plugin using the previous version of boilerplate (v2.6.2), you might need to take some time to relearn what’s new in the latest version, which includes new folder structure.

This boilerplate is no longer maintained by Tom McFarlin himself (at the time of writing), he’s passed the torch to Devin Vinson. The development is still continuing as usual, so if you have any issues, feel free to report one at the GitHub repository. Contributions are also definitely welcomed.

Getting Yourself a Copy

The simplest way to get a copy of WordPress plugin boilerplate is by cloning the git repository itself.

git clone https://github.com/DevinVinson/WordPress-Plugin-Boilerplate.git

Or you can always download a zip copy from the GitHub repository.

Since version 3.0.0 was released, the plugin cannot be simply copied into your wp-content/plugins directly. This is because the actual source code of the plugin is not contained in the root directory, but actually resides in the subdirectory called trunk. Don’t worry about this now, we’ll talk about the new folder structure later on in this article.

Full detailed instructions on how to install the boilerplate correctly is described in the README.md file. In a nutshell, you can either:

• Copy the trunk directory into the wp-content/plugins folder OR
• Copy the whole boilerplate directory, and then create a symbolic link for the trunk subdirectory to the wp-content/plugins/<plugin-name>/. Creating the symbolic link will depends on the operating system that you’re using.

Once you’ve done that, you should now find a plugin called WordPress Plugin Boilerplate in your plugin list in the admin dashboard, assuming you haven’t made any modifications to the boilerplate itself. Simply activate the plugin and you’re good to go!

Using the Online Generator to Customize the Plugin

Once activated, you’ll have a sort of vanilla plugin that doesn’t really do anything – that is, just yet. You’ll also need to run a search and replace to the whole boilerplate’s codebase, and this process can be very tedious and time consuming. Luckily, there is an unofficial generator built by Enrique Chavez that can automate the process. Simply head to http://wppb.me/ and complete the form located at the bottom of the page to generate a personalized copy of WordPress plugin boilerplate.

Folder Structures

Let’s take a closer look on how the WordPress plugin boilerplate version 3.0.0 is organised compared to the old one. As mentioned previously, the actual plugin code is contained in a subdirectory called trunk instead of in the root directory.

This is to follow the standards employed in the WordPress official plugin repository which contains three main directories which are assets, branches and trunk. The boilerplate already provides two of those, assets and trunk.

Here’s a complete directory and files contained in the boilerplate, at the time of writing:

|-- plugin-name/
|   |-- assets/
|   |   |-- banner-772x250.png
|   |   |-- icon-256x256.png
|   |   |-- screenshot-1.png
|   |
|   |-- trunk/
|       |-- admin/
|       |   |-- css/
|       |   |   |-- plugin-name-admin.css
|       |   |-- js/
|       |   |   |-- plugin-name-admin.js
|       |   |-- partials/
|       |   |   |-- plugin-name-admin-display.php
|       |   |
|       |   |-- class-plugin-name-admin.php
|       |   |-- index.php
|       |   
|       |-- includes/
|       |   |-- class-plugin-name-activator.php
|       |   |-- class-plugin-name-deactivator.php
|       |   |-- class-plugin-name-i18n.php
|       |   |-- class-plugin-name-loader.php
|       |   |-- class-plugin-name.php
|       |   |-- index.php
|       |   
|       |-- languages/
|       |   |-- plugin-name.pot
|       |
|       |--  public/
|       |   |-- css/
|       |   |   |-- plugin-name-public.css
|       |   |-- js/
|       |   |   |-- plugin-name-public.js
|       |   |-- partials/
|       |   |   |-- plugin-name-public-display.php
|       |   |
|       |   |-- class-plugin-name-public.php
|       |   |-- index.php
|       |
|       |-- LICENSE.txt
|       |-- README.txt
|       |-- index.php
|       |-- plugin-name.php
|       |-- uninstall.php
|
|-- .gitignore
|-- CHANGELOG.md
|-- README.md

Here’s a little explanation of what each file and folder does:

• .gitignore

  Provides a sane default .gitignore to most of the stuff that should not exist in your git repository.

• CHANGELOG.md

  Standard changelog of changes to the boilerplate with date of change.

• README.md

  A useful starting guide that lists the installation instructions, among other few other sections such as tools recommendations and credits.

• assets

  This directory contains the recommended resources that you need to provide whenever you decide to publish your plugin to the WordPress plugin repository. All of the images contained in this directory is the recommended resolution for publishing.

• trunk

  This is the actual plugin that you are going to develop. There are a few folders that separate the codebase between admin and public facing functionality. We’ll go through in details of what each subdirectory represents.

  • admin

    There are three directories contained within the admin directory, namely css, js and partials. As its name suggests, all admin facing functionality should be placed here. By default, the plugin-name-admin.js and plugin-name-admin.css is enqueued to your wp-admin. class-plugin-name-admin.php will provide generic functionality where you can define your admin specific hooks.

  • public

    This directory is pretty much similar to what the admin directory has to offer, the only difference is that the public directory should be used to store all of your public facing functionality codebase.

  • languages

    A starting .pot file where you can provide translation functionality with your plugin.

  • includes

    This is probably where pretty much all the magic happens. There are five starting classes included by default, which we will discuss later in the next section.

  • LICENSE.txt

    A copy of GPL v2 license is included by default.

  • README.txt

    A starting point for your plugin README file. This file pretty covers all of the sections that you can further fill in to provide a good plugin page on WordPress plugin repository.

  • plugin-name.php

    The point of entry for your plugin. In here, a general plugin file header is included that you can modify to your own liking. The register_activation_hook and register_deactivation_hook are also registered in this file if you ever need to include some sort of functionality on plugin activation and/or deactivation.

Included Classes

As mentioned before, there are five default classes provided inside the trunk/includes directory. Let’s see what each of these do:

• class-plugin-name-activator.php

  This class is instantiated during the plugin activation. It only has one static method, activate() which is registered to the register_activation_hook. Use this class whenever you find yourself in need to do something on plugin activation such as creating custom tables or saving default options.

• class-plugin-name-deactivator.php

  The counterpart for class-plugin-name-deactivator.php. It also only contains one static method, deactivate() which can be used to run any functionality during plugin deactivation.

• class-plugin-name-i18n.php

  A starting point for i18n functionality of your plugin. It has one property, $domain which stores your plugin text domain. This property can be set using the public method set_domain(). Finally, the method load_plugin_textdomain() in this class will be called whenever the plugin is loaded.

• class-plugin-name-loader.php

  Probably the most important class in the boilerplate. It contains two properties, $actions and $filters where all the hooks registered in the plugin will be stored. It provides two simple wrapper functions, add_action() and add_filter that are used to add actions or filters into the $actions and $filters properties. This should not be confused with the WordPress default add_action() and add_filter() function as this class does not actually register them directly. All of the hooks will only be registered during another method called run().

• class-plugin-name.php

  The class that glues all the pieces together. It holds important information about the plugin such as the plugin name and version. Plus, it will load the dependencies using the method load_dependencies() which will include all the above four classes and plugin text domain will be set using set_locale() method. All admin and public hooks that were previously registered can also be defined here.

  This class also provides simple get methods, such as get_plugin_name() to return the plugin name, get_version() to return the current plugin version and get_loader() that keeps an instance of class-plugin-name-loader.php.

Conclusion

In short, the WordPress plugin boilerplate provides a terrific starting point for plugin developers. It follows the recommended WordPress coding standards as well as WordPress documentation standards so you know you’re starting off on the right foot. Besides, publishing to the WordPress plugin repository is made easier since the boilerplate already provides much of what you’ll need.

Once we’re familiar with the code organisation and folder structure, we’ll explore how to develop an actual plugin using the WordPress plugin boilerplate in the second part of the series.