Editing the README

In the previous post of this WordPress Plugin Boilerplate series, we created the WP Starter Plugin using the plugin generator. However, before we begin developing, there is at least one thing we need to edit: the README file.

The plugin generator barely touches the README file (remind me to file a bug report), leaving it incomplete. Since we want to learn to develop plugins properly as we go, we start by editing the README.

Examining the Parts

The README consists of several parts which are typical for most plugin README files:

  • Tags (at the top)
  • Description
  • Installation Instructions
  • Frequently Asked Questions
  • Screenshot List
  • Changelog
  • Upgrade Notices
  • Arbitrary Section

Tags

The tags populate much of the information you see in a plugin listing on the WordPress Plugin Directory.

For starters, correct the === Plugin Name === to your plugin’s name.

The contributors tag needs your wordpress.org username and any other developer’s usernames as well.

The Donate link should already be your Author URI. If you have a specific site where people can donate money for your plugin, use that instead.

Tags helps classify your plugin in the directory. Its similar to how news websites use categories like World, Sports, Entertainment, etc. If you need to use more than one, be sure to separate them with commas.

WordPress uses the Requires At Least and Tested Up To tags for compatibility checks. If a plugin requires a specific version of WordPress, then users below that version will not receive automatic updates.

Stable Tag is the current version of your plugin. Update this every time you create a new version. Since this is a new plugin, change this to 1.0.0.

License and License URI tags should remain “GPL-2.0” and the URL given. To remain compatible with the GPL 2 license, you can use a more permissive license, like the MIT license, but not a more restrictive one.

Description

There are actually two descriptions in the README file. There’s a short description above the === Description === header and a long description just below the header.

Limit the short description to 150 characters or less and do not use markup. Think of this as a tweet describing your plugin.

The long description explains the details of your plugin. This section uses Markdown formatting so you can dress it up with lists, links, headings, and even videos. It can be as long as you prefer and can include just about anything. Many developers use this section to convince users to choose this plugin, up-sell paid versions of this plugin, provide documentation for simpler plugins, and/or usage instructions.

As an example, the Yoast SEO plugin uses the long description to convince users to install the plugin, up-sell the paid version of the plugin, then detail the plugin features. Others simply provide a link to the plugin’s website where the details are provided.

I would advise using this space to add as much information as possible about your plugin. Give people reasons to use your plugin and list out the features. Then, provide more detailed documentation on your website or on a dedicated plugin site.

Installation Instructions

Give people the instructions what they need to get your plugin working. Some plugins only require installation and activation to work. Others need shortcodes placed into content. Some may require template tags. I saw one recently on github that required moving a folder into your theme.

Most of the time, the first two instructions in the example list are consistently the same. For the rest, give step-by-step details. Be sure to test this out on a new WordPress install to make sure you don’t miss anything.

Frequently Asked Questions

This is your chance to provide some basic documentation to users. If your plugin uses a shortcode, give the basic usage instructions in an FAQ. Same for template tags or any other major plugin feature. Try to anticipate what people may ask and answer it here first. Be sure to pay attention to the example’s formatting.

Screenshot List

Provide some screenshots of your plugin in action. These could be the settings pages or examples of the output. For example, if you provide 3 screenshots, name the image files screenshot-1.jpg, screenshot-2.jpg, and screenshot-3.jpg. Then the screenshot descriptions in this list match the corresponding file based on the list order. Since this is a new plugin, leave the examples alone. We’ll add screenshots later and edit these accordingly.

Changelog

The changelog provides details about the changes from one version to the next. I recommend providing as much as detail as you can. For example, if the next version has 10 commits, use the commit messages as list items in the changelog for this version. If you don’t use the commit messages, at least tell what major things changed in this new version. For a new plugin, there isn’t a changelog yet, so remove the examples and enter something like:

= 1.0.0 =
* New plugin.

Upgrade Notices

At first it seems like the upgrade notice is the same as the changelog entry. However, these notices are considerably shorter. I think of them like a mini-sales pitch for why a user should update to this new version. Keep them short, the limit is 300 characters. New plugins also don’t need an upgrade notice, so you can delete the examples here. The formatting is the same as the changelog, so we can look there for an example later.

Arbitrary Section

You can add additional sections to the README and they can be whatever you need. They use the same heading formatting as the other headings and also use Markdown formatting. I’ve seen just a handful of plugins that use another section. They are usually for something really outside the norm or where the plugin requires additional information outside not classified under the provided headings. In this case, remove the entire section.

Wrapping Up the README

At this point, your README should have an accurate set of tags and plugin name at the top, good plugin descriptions (long and short), good installation instructions, no FAQs, no screenshots, no upgrade notices, and one changelog entry. In the next post, we will begin creating the WP Starter Plugin and learning to build plugin parts in the boilerplate.

Using the Plugin Generator

In the previous post of the WordPress Plugin Boilerplate series, we explored the loader class and how to properly register hooks. In this post, we will begin developing the WP Starter Plugin by using the plugin generator.

Enrique Chávez, a full-stack WordPress developer from Valle de Bravo, Mexico, built the WordPress Plugin Boilerplate Generator. You can find the plugin generator at https://wppb.me/.

Generating A Plugin

WordPress Plugin Boilerplate Generator Homepage

The generator operates from a simple form. After hitting the Build Plugin button, the site returns a zip file of a boilerplate-based plugin. Let’s start by looking at the form.

Plugin Name

We start with the name of your plugin. Here’s what I entered for our example plugin: WP Starter Plugin.

Plugin Slug

The plugin slug becomes the translation string, the URL slug, and part of each class file name. Here’s what I entered for our example plugin: wp-starter-plugin.

Plugin URI

The plugin URI is the web address where people can find more information about your plugin. Here are some ideas for this URL:

  • the github repo page
  • a dedicated plugin website URL
  • a page on your site

I create a page on my site for each plugin I publish, so here’s what I entered for our example plugin: https://www.slushman.com/wp-starter-plugin.

Author Name

In this field, enter the name of the plugin developer. This should be your wordpress.org username, especially if you plan to publish your plugin. Otherwise, you could use your proper name (ie Chris Wilcoxson) For our example plugin, I entered my wordpress.org username: slushman.

Author Email

Enter a valid email address. If you plan to publish your plugin to the WordPress Plugin Directory, the directory admins will contact you through this email. Otherwise, people will most likely use this for support requests. For our example plugin, I entered my email.

Author URI

This is simply the author’s website. For our example plugin, I entered the URL of this website: https://www.slushman.com.

Build Plugin

Finally, click the Build Plugin button to build your plugin. The site should allow you to download the zip file of your new plugin.

Examine the Results

Open the zip file and check out the resulting plugin. You can see the plugin uses the boilerplate structure, except the classes now use your plugin slug. If you open some of the class files, you’ll notice the translation strings use your plugin slug as well.

I’m sure you can see the generator saves a good deal of time when starting a new plugin. Finding and replacing each string and filename isn’t overly difficult, but it can be time consuming, especially if you miss one and get errors.

Wrapping Up

In the next post, we’ll look at the final steps needed before actually beginning development. While the generator saved some time and manual labor, there are some parts of the plugin that require attention before moving on to development.

Understanding the Loader Class

In the previous post of the WordPress Plugin Boilerplate series, we walked through the structure. We also examined each file and what they do. The biggest feature of the version 3 rewrite is the new loader class.

The loader class loops through all the hook calls and registers them with WordPress all at once. The class consists of two class variables and four methods.

Class Variables

Each of the class variables are arrays containing the hooks and their corresponding functions.

$actions

An array of the all actions to register with WordPress.

$filters

An array of the all the filters to register with WordPress.

Methods

There are only four methods in the loader class, not counting the constructor.

Constructor

The class constructor simply assigns a blank array to each of those class variables.

add_action()

Adds the action passed to it to the $actions class variable using the add() method.

add_filter()

Adds the filter passed to it to the $filters class variable using the add() method.

add()

Takes the passed in hook and the other parameters and restructures everything into an array.

run()

Loops through the $actions and $filters class variables and registers each hook with WordPress.

Summary

The main plugin class calls add_action() and add_filter() with the hook parameters. Each method passes parameters to the add() method, which collects all the hooks into respective class variables. The main plugin class calls the run() method, loops through the class variables, then registers the hooks with WordPress.

How to Register Hooks

The most confusing part of using the new loader class is properly registering hooks. While the boilerplate has methods named add_action() and add_filter(), they work differently than the WordPress functions.

The boilerplate gathers all the hooks to register them with WordPress all at once. Let’s use the enqueue_styles declaration in define_admin_hooks() as an example.

First, we have to create an instance of the admin class and assign it as the variable $plugin_admin. We also pass the plugin_name and version using the get_plugin_name() and get_version() methods in this class.

$plugin_admin = new Plugin_Name_Admin( $this->get_plugin_name(), $this->get_version() );

Next, we use the add_action method in the Loader instance. Each hook registers separately with the loader class. In the load_dependencies() method, we assigned the instantiated loader class to the $loader class variable.

$this->loader

Since enqueue_styles is an action hook, we use the add_action() method from the loader class.

$this->loader->add_action

This first parameter of the boilerplate’s add_action method is the name of the hook. In this case, admin_enqueue_scripts.

$this->loader->add_action( 'admin_enqueue_scripts',

The second parameter of the add_action method is the class instance of our action.

$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin,

Finally, we put the name of the method in the class where WordPress can find our action. In this case, the name of the method is enqueue_styles.

$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin, 'enqueue_styles' );

Additional Loader Method Parameters

The loader class accepts two additional parameters: the hook priority and the accepted arguments. Both are optional and in this case, we’re not using either. However, a complete example would be:

$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin, 'enqueue_styles', 10, 1 );

Finally, in the admin class, the enqueue_styles() method contains:

wp_enqueue_style( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'css/plugin-name-admin.css', array(), $this->version, 'all' );

This is the standard way to enqueue a CSS file into the WordPress admin through the plugin boilerplate methods.

Summary

We have seen how the loader class works and the proper way to register a hook.

In future posts, we will learn how to create various plugin features using the boilerplate. Let’s start by creating the WP Starter Plugin by using the plugin generator.

The Structure of the WordPress Plugin Boilerplate

In the previous post of the WordPress Plugin Boilerplate series, we looked at why one would use the boilerplate. This post will explore the organized structure in more detail.

The structure makes plugin development more predictable and easier to maintain in the future. The boilerplate organizes files into four main folders:

Plugin Folder

WordPress Plugin Boilerplate Main FolderThe main plugin folder contains basic files for creating a WordPress plugin.

Main Plugin File

This file contains the comments describing what it does, who authored it, the current version, etc. The boilerplate also uses the PHPDoc versions of those same properties.

This file also registers the activation and deactivation hooks, then runs the main plugin file.

readme.txt file

A required file for any WordPress plugin. It describes what the plugin does, who authored it, as well as a changelog and versioning information.

GPL 2.0 license

The boilerplate uses the GPL 2.0 license which is the same license as WordPress. A copy of the license is a wise thing to include in your plugin.

index.php file

The index.php file is internationally blank. Some developers have questioned the necessity of including this file. However, many experienced developers have explained a file like this helps with security concerns.

uninstall.php file

Plugins usually remove settings and other database-related features in the uninstall file.

Languages

WordPress Plugin Boilerplate Languages FolderThe languages folder contains all the files needed for translations. The boilerplate includes an empty .pot file for translations. You can optionally include additional .pot files containing the translated strings.

Admin & Public

WordPress Plugin Boilerplate Public Folder
WordPress Plugin Boilerplate Admin Folder
Since both the admin and public folders have the same structures, I’ll explain both at once. The admin and public classes have the same structure and methods, but keep the different concerns separated.

class-plugin-name-admin.php & class-plugin-name-public.php

This is the main class. Most of the plugin code will reside in one or both of these files.

partials

WordPress Plugin Boilerplate Admin Partials FolderThe partials subfolder contains PHP files with the output HTML code. For example, displaying a settings page in the admin requires using two files. The WordPRess API code resides in the admin class, but the HTML output would be in a partial file.

JS

WordPress Plugin Boilerplate Admin JS FolderThis folder contains all the Javascript files for the plugin.

CSS

WordPress Plugin Boilerplate Admin CSS FolderThis folder contains all the CSS files for the plugin.

Includes

WordPress Plugin Boilerplate Includes FolderThe includes folder is Tom’s answer for where to put code that isn’t exclusive to the admin or public. A common question prior to version three was where to put code for features that are both public and admin, like widgets.

class-plugin-name.php

This is the main plugin file. All the plugin’s WordPress hooks register through the Loader class here. All the class files become available throughout the plugin in this file as well.

The constructor sets the class variables. plugin_name is for naming things, like enqueueing stylesheets, and version is for caching busting scripts and stylesheets. Then these four methods run:

  • load_dependencies(): includes each of the classes used in the plugin. Instantiates the loader class.
  • set_locale(): contains the hooks for translation using methods in the i18n class.
  • define_admin_hooks(): contains the hooks for the plugin admin using methods in the admin class.
  • define_public_hooks(): contains the hooks for the public-facing parts of the plugin using methods in the public class.

class-plugin-name-activator.php

Contains any code that runs during plugin activation.

class-plugin-name-deactivator.php

Contains any code that runs during plugin deactivation.

class-plugin-name-i18n.php

Loads and defines the internationalization files for this plugin so all the strings are ready for translation.

class-plugin-name-loader.php

This is the big new feature of version three. The loader class takes all the hooks defined in the main plugin file and registers them with WordPress.

In the next post, we’ll examine the loader class in detail and how it differs from writing normal WordPress hooks.

Why Use the Boilerplate?

In the first post of the WordPress Plugin Boilerplate series, we covered the history of the project. In this post, we’re going to address a common question. The first question both new and experienced developers ask about the boilerplate is: why should I use this? The boilerplate describes itself as “a standardized, organized, object-oriented foundation for building high-quality WordPress plugins.” Here are at least five different ways the boilerplate helps when building plugins.

Organized

WordPress plugins don’t have a required structure. Many plugins are literally just one file. However, as a plugin gets more complex, better organization keeps it maintainable. The Boilerplate has an existing folder structure for keeping all the parts organized. While you’re able to customize everything, the pre-existing structure offers a predictable format can make building plugins easier.

Object-Oriented

Each class in the boilerplate separates the responsibilities of the methods and functionality. The included classes start with one public-facing object, one admin-facing object, and several classes used in either. You can see included examples to continue the good OOP practices in your custom classes.

WordPress Coding Standards

The boilerplate uses the WordPress Coding Standards. Seeing good examples can only help the code quality of plugins, especially for ones submitted to the plugin directory.

WordPress Documentation Standards

One of the best things you can do while building a plugin is document your code. The boilerplate uses the WordPress Documentation Standards and gives you plenty of really good examples of properly documenting code. I write my documentation to explain to my future self how the code works and why I wrote the code this particular way.

WordPress APIs

Of course, the boilerplate uses standard WordPress APIs so the examples you find in the Codex and every WordPress code blog are still usable.Codex examples would require some minor alterations to work within the boilerplate. We’ll go over those in detail as we build the WP Starter Plugin.

Translatable

The boilerplate includes a blank .pot file so you can add your translatable string easily. As WordPress becomes more popular outside the English-speaking community, making your plugin translatable increases the potential reach of your plugin.

Plugin Generator

The WordPress Plugin Boilerplate has a companion project – a plugin generator. The generator replaces the various strings and file names with your plugin’s information so you don’t have to do all this manually. Its a major head start. You can find the generator at https://wppb.me/.

Coming Next

I hope you see the boilerplate can be a useful tool for building plugins. In the next post, we’ll examine the files and folder structure.

A Guide to Using the WordPress Plugin Boilerplate

For several years now, I’ve been building plugins using the WordPress Plugin Boilerplate project. In 2015, I gave a WordCamp talk about how to use it. Over the past few years, I’ve answered questions about how to build plugins with the boilerplate. Since there is no formal documentation, I hope these posts serve that purpose unofficially. I covered most of this introductory material in my WordCamp talk. However, I’m planning more detailed posts, additional code examples, and topics I didn’t cover in the presentation. I’ll also offer some shortcuts and potential improvements, in case you want to fork the boilerplate.

When I first began writing plugins, I did what most beginning developers do – copy and paste code samples from the Codex and/or another developer’s blog. Each plugin eventually worked, but I still cringe when I look at that code. Many of those first plugins were giant, one-file plugins. Over time, I learned better methods for writing code and eventually discovered the WordPress Plugin Boilerplate. Since then, I’ve used either the boilerplate or my own fork for even the simplest plugins.

What Is The WordPress Plugin Boilerplate?

A good starting place is understanding what the boilerplate is and the history behind it. The boilerplate is a standardized, organized, object-oriented foundation for building high-quality WordPress plugins. There are some simple examples of how the parts work together as examples for building your plugin. In addition, the boilerplate includes easily overlooked plugin features like inline documentation and translation files.

Tom McFarlin, a well-respected developer from Atlanta, GA, developed the boilerplate. He wanted to prevent needlessly writing the same code each time he began a new plugin. The boilerplate is currently on version 3, which included a major restructuring. In March of 2015, the boilerplate project passed to Devin Vinson of Tampa Bay, FL.

How Do We Use The Boilerplate?

Since there is so much information to cover, we’ll cover each subject in a separate post. This introductory post will serve as a table of contents for the series. Throughout this series, we’ll build an example plugin titled “WP Starter Plugin”. It will include typical plugin parts like settings pages, widgets, metaboxes, etc. This gives you a major head start when creating plugins in the future.

Posts In This Series

  • Why Use the Boilerplate?
  • The Structure of the WordPress Plugin Boilerplate
  • Understanding the Loader Class
  • Using the Plugin Generator
  • Editing the README