WordPress Widgets: Refactoring, Part 1

The last post included a lot of information on setting up code quality tools in your WordPress development environment, but they are necessary if we are going to be doing a lot of refactoring.

But as I mentioned at the start of this post, laying code quality tools first provides us with a foundation we can use as we refactor the boilerplate (which we clearly need to do given the amount of red shown by GrumPHP).

Honestly, I see these as necessary if you’re going to be doing any type of development hence the need to show how to set them up.

Regardless, the previous post shows just how much work we have cut out for us, right?

Screen Capture on 2018-11-20 at 12-50-27.gif

Now we’re going to start with refactoring the WordPress Widget Boilerplate.

This will not only improve the code quality but also walk us through some object-oriented principles that we can apply when building our widgets and we can apply in future WordPress development efforts.

The WordPress Widget Boilerplate: Refactoring, Part 1

Perhaps the most exciting thing for me is to bring this repository up to modern standards. If you look at the master branch in GitHub at the time of this post (or the history of the repository later), you’ll see that it’s six years old.

WordPress Widget Boilerplate
This thing is six years old (at the time of this post).

That’s a long time in Internet years, isn’t it?

Anyway, in our refactoring efforts, we’re going to be doing some things:

  • creating a branch off of which to work before merging it back into the master branch,
  • implementing a more cohesive way of organizing files,
  • updating the coding standards to follow what’s more in-line with PSR,
  • and more.

I lay this out now because we’re likely not going to get to all of it in this post, but we will cover a lot of ground. So with that said, let’s get started.

1. Creating a Development Branch

Assuming that you have a copy of the repository of on your local machine, which you should have after the last post, the first thing we need to do is to create a branch off of which to do our work.

It’s a best practice not to work on the master branch. Instead, the master should always be used to deploy the latest stable version of the code.

To that end, enter the following command in your terminal:

$ git checkout -b develop

This will create a new local branch. It’s not yet been pushed up to GitHub or your remote repository yet (wherever you may be keeping it).

Next, enter the following command:

$ git push --set-upstream origin develop

This will push the development branch up to the remote repository. Once it’s done, you should be able to see all of the changes that we implemented in the last post in your remote repository.

If you’re using GitHub, it should look something like this:

WordPress Widget Boilerplate: The Develop Branch

If you’re using another service, it should still look similar. That is, the directory structure should be the same, but the way it looks in the browser will vary.

A Note About the Branch

Remember, the purpose of this branch is for us to do all of our work. This way, we’re not interfering with the master branch from which many people will pull.

To be clear, maybe no one will pull from this. Maybe they will. Regardless, this practices introduced here are meant to show how to run a project using source control and code-quality tools so that you can build better projects for yourself, your company, and more.

2. Reorganizing Files

The first thing we should do is re-organize the files, so they mimic a more modern structure. I’ll do my best to justify the decisions that I’m making for the project as we do this; however, feel free to take liberties with how you want to do it.

The decisions I make are ultimately going to affect the primary Boilerplate. What you opt to do will affect how you may use it in your day-to-day work or how you opt to move forward with the project as a whole.

Updating Directories

One of the things I try to do is break down my directories, so they are as clear as possible. This means I try to do the following:

  • create an assets directory for JavaScript and stylesheets,
  • create a src directory for all PHP files,
  • create a language directory for internationalization files,
  • keep all other files in the root of the repository, so it’s easy for others to follow along with the provided README.

To do this, I’m going first to remove and move a few things. I’ve tried to organize this in a particular order:

  1. I am going to remove the README.txt file. This file is used as a standard README template if you’re going to submit code to the WordPress Plugin Repository, but it’s not necessary for what I want for the Boilerplate.
  2. I will rename plugin.php to Plugin.php to follow PSR conventions.
  3. I will also rename lang to languages.
  4. I’m going to create an assets directory and move and then move the css and js directories into that directory. I’ll create a dev subdirectory in each of these directories where we can work on Sass and unminified JavaScript files (both of which will come later in the series).
  5. After that, I’ll create a src directory and move the views stylesheet into that directory.
  6. I’ll also rename views to Views and will also uppercase the files contained with in it.
  7. Finally, I’ll move everything up to the root of the directory. This means widget-boilerplate will disappear and all files will reside in the root directory of the repository.

These are a lot of steps, but they are small. I like to lay them out first so it’s clear to what will happen throughout the remainder of this section.

Remove the README

To do this, simply enter the following command in your terminal from the root of the widget-boilerplate directory:

$ rm readme.txt

This will remove the file. If you enter the following command in your terminal:

$ git status

You should see something like this:

WordPress Widget Boilerplate: Removing Files

I’m a fan of making sure that the various changes that are pushed up are clear and concise so that it’s easier to roll them back one at a time. So let’s go ahead and commit and push this change.

Enter the following:

$ git rm README.txt
$ git add .
$ git commit -n -m "Removing the original README.txt template."
$ git push

This will tell Git to remove the file, add the single change to the change set, commit it without running any code quality tools (because we don’t need to do that right now; otherwise, it will fail), and will push it to the remote repository’s develop branch.

Now that we have that done let’s go ahead and rename some files.

Renaming Files

While we’re at it, we’re not only going to rename the plugin.php file but the other PHP files, as well. These are files that can be logically grouped in the same changeset, so it makes sense to go ahead and do that.

So from your terminal, enter the following commands:

$ mv plugin.php Plugin.php
$ mv views/admin.php views/Admin.php
$ mv views/widget.php views/Widget.php

In doing this, we haven’t made any changes to files yet, so there’s nothing to commit. Let’s move forward with renaming directories.

Create Directories; Rename Directories

Just as we did with the files, let’s go ahead and create a new assets directory. In your terminal, enter the following command:

$ mkdir assets

Next, we want to move the css and js directories into that directory so enter the following in the terminal, as well:

$ mv css assets
$ mv js assets

And let’s rename the lang directory to Languages by entering the following command:

$ mv lang Languages

Finally, let’s rename view to Views:

$ mv views Views

At this point, we’ve done all we can with the files currently in the main directory. We still need to prepare subdirectories for our preprocessed assets, though.

Before doing that, though, it’s a good habit to run a quick git status check to see what exists that can be added to a changeset. If your repository is like mine, then you’re likely to see something like the following:

WordPress Widget Boilerplate: Renamed Directories

In this case, I think it’s okay to add everything into a single changeset with a comment indicating that we’ve renamed and moved files.

You may differ and if so, that’s completely fine. Your commands will differ a bit from mine but here’s what I have for my commit:

$ git add .
$ git commit -n -m "Creating new directories; Renaming files."
$ git push

Now, on to the subdirectories for our preprocessed files.

Create Subdirectories

In the CSS directory, create a subdirectory called dev and create an empty file called admin.scss and widget.scss as we’ll be working with these files later in the series.

Next, add a dev directory to the JavaScript directory and add empty admin.js file and widget.js files to these files. If you feel so inclined, you can move the pre-existing files into the dev directories as these are the files that we will be using as the foundation for our development files.

That’s an optional step; however, I’ve gone ahead and done that because that’s how I prefer to work. Here’s the set of commands that I’ve run.

From the css directory…

$ mkdir dev
$ mv admin.css admin.scss && mv widget.css widget.scss
$ mv *.scss dev

Above, I’ve created the dev directory for my stylesheets, renamed them to Sass files, and moved them into the dev directory.

Before moving ahead, let now is a good time to do a git status check and commit changes related to the stylesheets:

$ git add .
$ git commit -n -m "Renaming and moving stylesheets into a dev directory."
$ git push

Now, from the js directory…

$ mkdir dev
$ mv *.js dev

Since we don’t have to change the file type of the associated files, we can simply move them into the new directory.

Finally, let’s do the same thing and see if there are any changes that we can push up through a quick git status check (which there should be). Here’s a list of the commands I ran to commit and push my changes:

$ git add .
$ git commit -n -m "Adding a JavaScript dev directory and moving the development files."
$ git push

We’re almost done. All that’s left to do is to move certain directories into the root of the repository and rename the core directory to src. So let’s do that now.

Move Directories into the Root

Essentially, we need to move everything except the plugin file and the Views directory out of the widget-boilerplate directory, and we need to rename widget-boilerplate to src.

Sounds simple, right? It’s pretty straightforward. From within the widget-boilerplate directory:

$ mv assets .. && mv languages ..
$ cd ..
$ mv widget-boilerplate src

Then I’ll commit the change to GitHub using the following:

$ git add .
$ git commit -n -m "Reorganizing the directory structure."
$ git push

Now we have a much more modern directory structure set up. You can see it here in my development branch.

A Word About OOP

And now that we have all of this in place, we can get into writing code. But don’t be mistaken: A portion of object-oriented programming is also object-oriented analysis and object-oriented design.

What we’ve done in this post is essentially apply an object-oriented architectural design based on the analysis of how the plugin fits together.

The next part, though, is updating the code to get rid of all the red we’ve seen when sniffing our code.

In the Next Post

The primary goal of the next post is to continue with updating the coding standards so that we have resolved all of the problems thrown by our IDE or through the code quality tools we’re running at the command-line.

We should also have a much cleaner, more-organized repository, and be in a position to where we’re ready to merge our work back into the master branch.

For now, though, make sure that you’ve got a good handle on everything above before proceeding as it’s necessary to understand for the remainder of the work we have ahead of us.