Hostinicon
GET HOSTING FROM $3.95/MO PLUS A FREE YEAR ON TUTS+ (RRP $180). HURRY OFFER LIMITED. Check it out
Advertisement

Object-Oriented Programming in WordPress: Document The Plugin II

by
Gift

Get a free year on Tuts+ this month when you purchase a Siteground hosting plan from $3.95/mo

This post is part of a series called Object-Oriented Programming in WordPress.
Object-Oriented Programming in WordPress: Document the Plugin I
Object-Oriented Programming in WordPress: Inheritance I

At this point in the series, we're ready to move forward with rounding out our plugin by documenting our files, classes, functions, variables, and more.

Though this is the last step that we actually have to completing the plugin, it's not the last post in the series as we'll continue to look at a few advanced topics in object-oriented programming.

But before we do that, let's bring our plugin up to version 1.0 by putting into practice everything we learned in the previous article.

Of course, as with all previous articles, I recommend catching up on everything that we've covered thus far so you're completely up to speed not only with the work that we've done in the last article, but with how we actually got to the final points we're discussing in this article.

  1. An Introduction
  2. Classes
  3. Types
  4. Control Structures: Conditional Statements
  5. Control Structures: Loops
  6. Functions and Attributes
  7. Scope
  8. Building the Plugin I
  9. Building the Plugin II
  10. Document the Plugin I

With all of those covered and reviewed, let's get started with documenting each of our files.

Documenting the Plugin

There are a number of different ways that we can go about documenting this plugin:

  • We could document all of the file headers first, then we could come back and document the classes, then we could come back and document the variables, then we could document the functions.
  • We could document each file at a time and have a short discussion over everything that's included on a per file basis.

Obviously, the option will yield more documentation per section, but should result in a much less tedious article and a much easier understanding the flow of control for the entire plugin.

To that end, we're going to work through the plugin, file-by-file, introducing documentation for each piece of code that we have and then we'll discuss any points of interest following the code.

Finally, we'll make sure we refer to the final version of the plugin at the end of the article. With that said, let's get started.

The Single Post Meta Manager

Recall that the main file for starting the plugin is the single-post-meta-manager.php file located in the root of the directory of the plugin.

Here's what the fully documented version of the file looks like. Read each comment closely paying attention not only to the format that it follows, but the content that it provides.

In the above code, notice that we've defined a file header as per the conventions that we outlined that in the previous article. We also maintained the required plugin header tags in order for WordPress to proper read them.

Note that, in this case, we've included them under a custom @wordpress-plugin tag. This isn't required but helps to separate the file header comments from the required the plugin comments.

Finally, note that we've bumped the version of this plugin up to 1.0, and we've also given this plugin the @package value of SPMM which is short of Single Post Meta Manager. We'll be using this throughout the plugin.

The includes Directory

Next, let's turn our attention to all of the files that are located in the includes directory. 

Since these files are required before anything in the admin directory, it makes sense to look at each of these files individually, and then round out our discussion with the remaining files in the admin directory.

The Single Post Meta Manager

Clearly, there are a lot of new comments that have been introduced into this particular file; however, it should be very self-explanatory as to what each class property, the constructor, and the internal functions are doing.

The key thing to notice - aside from how the information is coordinated through out the plugin - is how we've adhered to the standards defined in the previous article. 

Notice, however, that we have taken the liberty if not using certain tags and/or features of the documentation when they aren't relevant. This is something that we'll continue doing throughout the rest of the article.

The Single Post Meta Manager Loader

Notice that this class is more of less a core component of the plugin in that it coordinates all of the actions and the filters used throughout the plugin. This plugin centralizes all of the registration and coordination of the hooks that are used throughout the plugin.

Finally, when run is called, all of the hooks are registered with WordPress so as the plugin fires, it will call each of the registered actions and filters.

The admin Directory

At this point, we're ready to turn our attention to the files located in the admin directory of the plugin. 

Though the file consists of a couple of PHP files, it also consists of a CSS file. For the purpose of this article, we are not going to be documenting the the CSS files; however, the WordPress Codex does define documentation for this.

For now, though, let's continue documenting the classes and files that exist in the admin directory.

Single Post Meta Manager Admin

The Single Post Meta Manager Admin class has a single responsibility: define the functionality to render the meta box and its styles for the dashboard.

Notice that the class above has very few functional details. Primarily, the class maintains a reference to the version of the plugin, the style sheet used to style the meta box, and the function required to actually render the meta box.

Recall that all of this is setup within the core plugin file and the loader. This helps de-couple the logic that exists within the plugin so each class can focus on what its primary purpose.

Of course, the final piece of the plugin relies on the actual partial file that contains the markup necessary to display the meta box.

Single Post Meta Manager Partial

This should be relatively self-explanatory; however, to be complete, note that this file takes the current post ID (through the use of the get_the_ID() function), reads the post meta data, and then iterates through it building a table that displays the keys and the values.

Finalizing The Plugin

At this point, we've completed the implementation of our plugin. From putting the object-oriented programming programming practices into place, to documenting the code.

You can grab the final version of the plugin on GitHub; however, we will be continuing our object-oriented discussion over a few more posts so that we can explore a few more advanced topics such as inheritance, abstraction, and other topics.

In the meantime, if you have questions or comments about the plugin, don't hesitate to leave them in the comments!

Advertisement