WordPress is the popular blog engine that is utilized by many organizations more for its Content Management System (CMS) functionality than for the task of blogging. What makes WordPress a stronger tool for web content management are the thousands of plugins that extend the capabilities, including over 25,000, such as those for creating widgets, admin functions, sidebars, twitter connections, print, Facebook, security, and other services with over 459 million downloads to date.
The WordPress Plugin Boilerplate built by Tom McFarlin gives you a way to create your own WordPress plugins and share them among the WordPress community. If you have always wanted to create a WordPress plugin but wanted to know how to get started, this piece will delve into the features of the plugin boilerplate, including downloading, installing and configuring it into a live WordPress implementation. I will describe some other resources for WordPress Settings API, and others for creating your own WordPress plugins.
The WordPress Plugin Boilerplate is a foundation for WordPress plugin development and its primary goal is to deliver a clear and concise guide for building WordPress plugins. The five main features of the plugin boilerplate include:
- Uses the WordPress Plugin Application Programming Interface Plugin API, which provides hooks, actions, and filters available to WordPress plugin developers, and describes how to use them.
- Code documentation uses PHPDoc for all conventions, which is an adaptation of Javadoc for the PHP programming language including object-oriented and procedural code.
- Example values are provided which gives you a way to see what can be changed to suit your needs and requirements.
- Uses a strict file organization scheme to ensure that all assets are maintained.
- Includes a “.pot” file as a starting translation file.
The new WordPress Plugin Boilerplate 2.0 download is available from the GitHub repository, and is available as a zip (489KB) file named “WordPress-Plugin-Boilerplate-master.zip”. The earlier download for version 1 is available as a tar.gz (484KB) or a zip (490KB) file from the plugin homepage and is delivered as the file name “tommcfarlin-WordPress-Plugin-Boilerplate-2.5.1-0-g08f0d9a” with the appropriate extension depending on what you select.
Included with the download are the following files in the root directory:
- .gitignore file
- ChangeLog.md file
- README.md file
- plugin-name directory
The plugin-name directory contains all the files required for the installation. If you are familiar with WordPress plugin installations, this is the directory to copy to your plugins directory. For those not familiar with WordPress plugin installations, the next section describes the details.
The four-step process is quite easy, and make sure you are logged into your WordPress instance and you are at the dashboard. The screen capture in Figure B from FileZilla shows the directory paths of the local site and remote site for copying the plugin-name directory into the plugins directory of the blog.
- Copy the plugin-name directory and its contents to the wp-content/plugins directory of your WordPress installation.
- In your WordPress dashboard navigate to the Plugins page.
- Locate the menu item TODO.
- Click Activate.
This activates the WordPress Boilerplate Plugin, but it has no real functionality and nothing will actually be added to your WordPress instance, but the plugin will demonstrate exactly how your plugin should behave while you are developing. Figure C below shows the screen capture from inside the WordPress dashboard where the plugin is activated.
I am not sure why the version 2.5.0 still shows as Version 1.0.0 in the Plugins directory of the WordPress dashboard. Once active, the plugin will appear in the Plugins dashboard as shown in Figure D below:
Editing the Plugin Boilerplate
Next you will want to familiarize yourself with the files that can be edited within the boilerplate. Clicking the Edit button just under the plugin name will take you to the Edit Plugins screen with the active editing file plugin-name/plugin-name.php open as shown in Figure E below.
This is where you can start to build your own WordPress plugin following the most common best practices and development strategies available for WordPress developers. The editable files located in the plugin-name directory for the boilerplate plugin include the following:
One of the first things you can do is create a new plugins admin page which will add a new menu item labeled “Menu Text” at the bottom of the Plugins section of the left sidebar by uncommenting Line 71 in the class-plugin-name.php class file which contains the following line of code:
add_action( 'admin_menu', array( $this, 'add_plugin_admin_menu' ) );
And the new menu item “Menu Text” is displayed as highlighted in the WordPress dashboard in Figure F below:
When clicked, the blank plugin admin page appears as shown in Figure G below:
According to Tom, the plugin Boilerplate does feature a basic example of how to include an options page; however, it doesn’t go into detail with the Settings API. Tom has covered two areas of interest for those who wish to delve deeper into WordPress Settings API with these two tutorials, WordPress Settings Sandbox: A Working Example of the Settings API, and The Complete Guide To The WordPress Settings API.
Other resources for WordPress Plugin creation
- WordPress.org Codex Writing a Plugin – WordPress organizations codex contains the instructions and standards for creating a WordPress plugin including topics such as names, files, locations, file headers, programming, hooks, tags, saving plugin data to the database, and administration panels
- Anatomy of a WordPress Plugin – Packt Publishing gives a deconstruction of the popular existing plugin “Hello Dolly”
- Top 10 Most Common Coding Mistakes in WordPress Plugins – Planetozh blog provides a list of the most common mistakes, errors, misunderstandings, bad habits, or wrong design decisions made while coding WordPress plugins
- How to create WordPress Plugin from a scratch – WordPress Development Magazine offers instructions for writing a very simple WordPress plugin.
- Building your first WordPress plugin – Web Designer Depot tutorial steps through what a plugin does, plugin names and files, plugin header, paths to files, plugin states, and best practices for building WordPress plugins.
- WordPress Essentials: How To Create A WordPress Plugin – Smashing Magazine’s article covers topics such as theme or plugin, creating your first plugin, structuring plugins, naming your plugin and its function, plugin safety, cleaning up, documentation and coding standards, putting the knowledge into practice, planning ahead, preparing the function, and more
- Create a Custom WordPress Plugin From Scratch – Net Tuts+ tutorial is on implementing a WordPress plugin from the ground up.
The WordPress Plugin Boilerplate will get you on your way to creating your own customized plugins using a PHP and WordPress coding standard from the template. If your plugin works really well, you might consider submitting the plugin and promoting it, and then getting it into world distribution.