Deploying a React App to Netlify

As part of the creating a headless React-based frontend for my WordPress site, I decided to try hosting my files on Netlify. They tout being super fast when serving a non-database site; a natural fit for a React project. Wes Bos’s React for Beginners course shows how to deploy to Netlify using the netlify-cli npm package. However, since completing that course, I updated to Node 10, which is not compatible with netlify-cli and Netlify recently deprecated it. In this post, I’ll detail how to deploy a site from the command line using their new command line tool: netlifyctl.

Sign Up for Netlify

If you don’t already have an account, head over to Netlify.com and sign up for an account. You shouldn’t need to create a paid account yet, so don’t worry about adding payment options.

Install

First off, you’ll need to install the new tool on your computer. On OS X, it’s available through Homebrew and on Windows, it’s available through Scoop.

OS X

If you don’t already have Homebrew installed, open Terminal and enter this command, then follow the prompts:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

With Homebrew installed, point to the netlifyctl tap:

brew tap netlify/netlifyctl

Next, install it:

brew install netlifyctl

Windows

If you don’t already have Scoop installed, make sure you have PowerShell 3 or higher installed, open it, then install Scoop using:

iex (new-object net.webclient).downloadstring('https://get.scoop.sh')

With Scoop installed, add the netlifyctl bucket:

scoop bucket add netlifyctl https://github.com/netlify/scoop-netlifyctl

Then install it:

scoop install netlifyctl

Deploying a React App

In this case, I’m specifically talking about a project created with create-react-app. If you aren’t using create-react-app, you will need to change some paths to match your project.

With netlifyctl installed, change directories into your project:

cd /myreactapp

Permissions

Start by giving your app permission to access your Netlify account.

netlifyctl login

This will openyour Netlify account in a web browser and ask if you want to give the CLI permission to access your account.

Netlify grant permissions prompt

Click the Authorize button. Once it confirms the CLI has permission to access your account, you can close the browser tab/window.

Build

If you haven’t already, run the build process for your app. For create-reat-app, that’s:

npm run build

Deploy

Next, use this command to start the deploy process to Netlify:

netlify deploy

It begins by asking if this is a new site. Entering “no” allows you to search by name for the existing site. Entering “yes” creates a new site.

Either way, it then asks for the path you’d like deployed. For a create-react-app project, it is:

./build

This uploads your build directory to Netlify and prompts you with the URL for your deployed app, which you can alt+click to view.

Last Things

That’s it! Your site should be visible on Netlify! A few last things: you’ll notice there’s now a netlify.toml file in your project. This file contains the settings you selected while deploying your app. Commit that file to your git repo to avoid answering those prompt again in the future.

Help!

If you forget how all this works, you can use:

netlifyctl --help

This lists out the commands available and how to use them. You can also use it with a specific command like:

netlifyctl deploy --help

Bonus Material

If you need to make changes to your app – say you’re like me and you forgot to run “npm run build” first so you deployed the default create-react-app build folder – and you need to re-deploy the project. Fortunately, it’s very simple:

netlify deploy

However, each time, the script prompts for the build path. This”feature” grows tiresome when you forget another thing, then another thing, then another thing and perform several deployments in a row (not that I would know from experience…). To avoid this, edit the netlify.toml file and add the build path. The default file includes your Netlify site ID and:

[Build]
  Publish = ""
  Functions = ""

Add your build path in the Publish value between the double quotes:

[Build]
  Publish = "./build"

Now, the deployment script uploads the files from the build folder and doesn’t stop for prompts each time.

Troubleshooting WordPress AJAX

I was working with some AJAX functionality a while back and started writing down the problems and solutions I ran across so they were all in one place. Basically, this post is for my future self. I hope you find it useful as well. 🙂

Specific Problems

Function Always Returns 0

If you’re getting a “0” as the response from an AJAX call in the admin, it’s most likely one of three things:

  • WordPress can’t find the function you’ve hooked.
  • You don’t have a wp_die() at the end of the PHP function.
  • The action isn’t in the data you’re sending to the PHP function.

403 Forbidden Error

Check the Nonce. You probably copied it from another function and it’s checking the wrong one.

Helpful Tip

The PHP function that processes the AJAX request has to echo something and should end with a wp_die() statement. You can use wp_die() to return something you want to see, like what data was passed to the function.

wp_die( print_r( $some_array ) ) is useful to check an array.

Code Sample Styling

I’m starting the process of redesigning this site. One of the components I have found most difficult to style are the code samples. Unfortunately, finding examples of what other people have done is not simple since googling words like code, HTML, CSS, styling, “code sample”, and/or pre result in all kinds of randomness. So I thought it would be helpful to publish what I’ve found so far in case anyone else wants inspiration or to explore possibilities.

Examples from Known Libraries

I believe there’s wisdom in listening to experts first, since (hopefully) they have already figured out all the things. In this case, I wanted to see the designs created by popular CSS libraries. Specifically, I wanted to see how these libraries style pre and code elements out-of-the-box.

NOTE: I’m combining the styling for both the pre and code elements here since I want to display a code sample (which uses both elements). I did not use any reset tools on these examples.

Library Gallery

Here’s the CodePen Collection of all the designs I explored, including some of the ones below.

No Styling / No Design

While exploring these libraries, I found many either didn’t include any specific design at all. I’m not posting screenshots of these since they would be really boring, but here’s the list:

Results for Libraries

Frankly, I had hoped for some amazing design I just copy/paste and move on. But it appears none of them offer a great option. I don’t judge too harshly since these libraries are probably great at solving other problems – just not this particular one.

From these options, I would choose Bulma or UIKit. Even those are still pretty basic, so it would still require some polishing to make it look “designed”. Next, let’s see some examples of how others are styling code samples on their websites.

Existing Ideas

NOTE: many of these screenshots also include syntax highlighting, which colorizes the code samples. At this point, I’m not talking about coloring the code within the samples, I’m just looking at the pre and code element styling.

The most common two styles are the background color only and the borders and background color. Most of the blogs and documentation sites I visited used one of these two options.

Since these two were so popular, I wondered if this was the default browser styling and the site/theme developers didn’t bother changing it. So I put together a code sample on my local development server and here’s the result:

Code sample with no styling
Code sample with no styling

As you can see, in Chrome the only styling appears to be a monospaced font and a 1 em margin on top and bottom. So, while Borders and Background Color and Background Color Only do require adding some styling, they are still rather plain. That said, code samples aren’t common for most websites, so it’s understandable that designers and developers focus their time and talents on other elements.

Here’s a CodePen showing the basic styling for each of these examples (except the line numbers):

Results for Existing Ideas

I think Background Color Only is a little too plain. The Borders with Background Color is a bit better as it feels like someone actually worked on it to make it look that way. Dashed Lines Top and Bottom has a classy feel without adding too much. Border Left and Border Right feel understated, but not lazy or forgotten. All that said, I have to explain the Header With Label option since it’s the most involved to do.

Header With Label

The HTML is just like any other: a code element wrapped in a pre element. However, the pre element also has a rel attribute that contains the type of the code. In the screenshot below, the “JSX” label text is in the rel attribute on the pre element.

Code sample from CSS Tricks block

This label text appears using a CSS property I hadn’t heard of yet: attr(). The attr() CSS function takes the content of the rel attribute and makes that the content of the pseudo element its applied to.

content: attr(rel);

The content CSS property only works with pseudo elements. In this case, the :before pseudo element of any pre element that has a rel attribute:

pre[rel]::before {
    content: attr(rel);
}

From here, the additional styling makes the label readable and positions it at the top of the pre element.

However, that’s not all. The background color of the header changes for each language on the CSS Tricks blog. Purple is the color for JavaScript, jQuery, and JSX code samples, assigned using an attribute selector:

pre[rel="jQuery"]::before, pre[rel="JavaScript"]::before, pre[rel="JSX"]::before {
    background: #9c27b0;
}

Now, only those pre elements with the proper rel attribute values will get the purple backgrounds.

While I think this is one of the coolest code sample styles out there, it feels heavy for my site. I could probably do this with a different color scheme. However, since I use WordPress, this would require either a custom plugin or hand-coding each code sample to add the rel attribute.

Summary

I’m still haven’t chosen an option yet. The out-of-the-box approach is just out; there’s just not enough “designy-ness” that’s worth stealing/borrowing/copying. I like most of the examples on other people’s sites, with the exception of Line Numbers. If you need that, it’s possible to do with just code, but I prefer to keep it simple.

PHPUnit tests and WP-CLI

I recently discovered an easy way to add unit tests to my plugins. I’ve been using WP-CLI for years now to set up new local installs of WordPress and found out it has a command specifically for setting up PHPUnit for plugins. This post is partially for my future self so I can remember how to do all this. FYI, I’m on a Mac, so all the commands will be OS X-specific.

Install and Configure PHPUnit

Start by installing PHPUnit using Homebrew:

brew install phpunit

That installs the latest version of PHPUnit and makes it ready to use with the global keyword “phpunit”.

Next, use WP-CLI to setup the test suites and such needed for PHPUnit. I recommend running this command from the plugin’s directory.

wp scaffold plugin-tests my-plugin

Replace the “my-plugin” part with your plugin name.

If you aren’t already in your plugin directory, change to that now. Then you’ll run the installation bash script.

bin/install-wp-tests.sh wordpress_test root '' localhost latest

Notes about this command:

  • ‘wordpress_test’ is the MySQL database created by this script and used for testing
  • ‘root’ is your local MySQL user
  • ” is where your local MySQL user password goes
  • ‘localhost’ is where you MySQL server is located
  • ‘latest’ changes the version of WordPress to use for testing.

Once you’ve run this script, you’re ready to start writing tests and running them using the ‘phpunit’ command. Here’s the rub though: the script installs WordPress and the testing suite in the /tmp directory. Why is that a  problem? On my computer, at least, the /tmp directory removes anything installed there upon reboot. Which means I need to re-run the tests bash script every time I reboot the computer.

Since we developers prefer not repeating ourselves, here’s how to configure things for a more permanent solution.

Solution

What I’m advising here is to move the stuff installed in /tmp to somewhere else, then fix all the references so they still work. So, run all of the above, then navigate to your /tmp folder. Move the /wordpress and /wordpress-tests-lib folders to another location outside the /tmp folder. I moved mine into a directory called unittests in my Dropbox folder.

Go to your Home folder and either open or create the .bash_profile file. You’ll probably need to tell Finder to show Hidden files first. In your .bash_profile file, add the following line, using your new directory location:

export WP_TESTS_DIR="/Your/New/Folder/Location/unittests/wordpress-tests-lib"

This line tells the PHPUnit bootstrap.php file where to find the test WordPress install and test suite files.

Now, go to the wordpress-tests-lib directory and open the wp-tests-config.php file. Edit the ABSPATH constant to the ‘/wordpress’ directory you copied over from /tmp earlier. Something like:

define( 'ABSPATH', '/Your/New/Folder/Location/unittests/wordpress//' );

Save the file and reboot your computer. Now, the tests setup by WP-CLI know where the testing WordPress is located, it doesn’t disappear when you install updates or reboot, and you can create and run PHPUnit tests for your plugins!

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 official documentation, I hope these posts serve as some unofficial documentation. 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