In the previous post, we created our first plugin and also create a GitHub repo for it. So far so good, but now we need to take it a step further. In this lesson we will cover the following topics:
- Create a readme.txt file.
- Create a readme.md for GitHub.
- Refactor code into different files.
Readme.txt
Why even bother creating this file? Very simply : the WordPress.org plugin repository uses it to generate your plugin’s landing page. And this page can make all the difference when people are deciding if they want to download your plugin or not.
I seldom download and install a plugin that doesn’t have a list of features or a link to an online demo. I also really like seeing screenshots of the plugin in action. Something we’ve learned here on FooPlugins is that coding the plugin is only half the battle. Marketing your plugin is just as important.
The readme.txt file format uses a custom form of Markdown. Markdown allows the file to be human readable, while at the same time being translatable into a nice looking HTML equivalent.
Create a readme.txt file in your plugin folder and add something similar to the following:
=== FooDocs === Contributors: bradvin,webdevmattcrom Donate link: https://fooplugins.comdonate Tags: documentation, hierarchy, custom post type, syntax highlighting Requires at least: 3.5.1 Tested up to: 3.6 Stable tag: 1.0.0 License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Organized documentation for your digital products == Description == Easily create and manage documentation for your digital products in a central location. = Plugin Features = * Manage all your documentation using a custom post type. * Include documentation on any page using a simple shortcode. * Include a table of contents in your sidebar with a handy widget. * Built-in syntax highlighting. == Installation == 1. Upload your plugin folder to the '/wp-content/plugins' directory. 2. Activate the plugin through the 'Plugins' menu in WordPress. == Frequently Asked Questions == There are no FAQ just yet. == Changelog == = 1.0.0 = * First release == Upgrade Notice == There is no need to upgrade just yet. == Screenshots == There are no screenshots yet.
A great example readme.txt can be found here. Once you have created your readme.txt, you need to validate it, using the readme.txt validator on WordPress.org.
How To Improve Your WordPress Plugin’s Readme.txt is a great article which covers the readme.txt file in great detail and highly recommended it!
[note color=”#69BC3C”]Please note : we will be adding to the readme.txt file as our plugin progresses throughout the series.[/note]
Now Make GitHub Happy
The nice thing about GitHub is that when visitors view your repository, it will automatically load and display the readme.txt file to them. The problem is that GitHub will not render the markdown from readme.txt into HTML, so we have to create another file named readme.md so it will be shown correctly on GitHub.
However, we can’t just copy the readme.txt to readme.md, as WordPress uses it’s own variation of markdown. Luckily Ben Balter wrote some code to do this conversion for us. You can find the code itself on Github, or use the hosted version where you can simple upload your readme.txt and get a nice GitHub-friendly readme.md back.
I used this online tool to generate the readme.md you now see at the FooDocs repository. I also use the Markdown Live Preview site to preview what my markdown will look like when it is converted to HTML.
Time For A Refactor!
Before we write too much actual plugin functionality, I want to make sure we are following best practices.
Our friend Tom McFarlin is a great developer and often talks about things like design patterns within WordPress. He is also the author of the terrific WordPress Plugin Boilerplate. For those that don’t know, the plugin boilerplate is a great starting point for any WordPress plugin. I have started using this boilerplate code in a lot of recent plugins I have written, and we are also going to follow the guidelines of the boilerplate with our FooDocs plugin.
Separate Class Into It’s Own File
One antipattern that I see in a lot of WordPress plugins, is writing all your code into a single .PHP file. Why do this? I have no idea why developers think it is cool to lump all the code into a single monolithic file. There is no benefit that I know of for doing this. All it does is make your code extremely hard to maintain in the future.
Not only do I want my plugin’s user interface to be as user-friendly as possible, I want my code to be as user friendly as possible! This means I want to separate logical groupings of code into their own files. One thing that the boilerplate does is separate the plugin class into it’s own file. I love this idea and I have started doing it in all my plugins now. The reason I like doing this is there is a clear separation of logic. My main plugin file is also very small and only contains the code to create a new instance of my class.
Follow these steps to get it done:
- Create a new file called class-{plugin name}.php – in my example it is class-foodocs.php
- In the new file, open your PHP tag and create a sensible header comment:
<?php /** * FooDocs class * * @package foodocs * @author Brad Vincent */
- Then cut the whole class definition (including the class_exists check) into the new file.
At this point, your original plugin file is pretty useless. Mine currently contains this:
<?php /* Plugin Name: FooDocs Plugin URI: https://github.com/fooplugins/foodocs Description: Organized documentation for your digital products Author: FooPlugins Author URI: https://fooplugins.com Version: 0.2-alpha */ $GLOBALS['FooDocs'] = new FooDocs();
If you ran the plugin at this point it would give you an error that the class can not be found. This is because we have not included our new file. To do this, we need to add the following code before we instantiate our plugin class:
require_once( 'class-foodocs.php' ); $GLOBALS['FooDocs'] = new FooDocs();
Our plugin now works again as it used to. Now let’s go an play with our class code a bit.
Add Class Variables
There are a few bits of info, about the plugin, that we will use throughout our class. And it makes sense to make these into variables and that we define them at the top of our class up front.
We do this so that if we ever want to change these values down the line, we only need to change it in a single place. The info we care about for now is:
- plugin unique name or slug
- plugin version number
Create 2 protected variables and give them values:
protected $version = '0.2.0'; protected $plugin_slug = 'foodocs';
The reason we set the visibility of the variables to be protected, is so that we can only access and modify them inside our class.
What’s Next?
In the next article we will add the ability to translate our plugin.
Matt’s Response Post
Check out Matt’s response post where he raises some great questions about why WordPress does the things the way they do in the readme.txt file, and also about whether or not the plugin structure has the potential to affect performance. There is some great insight there for fellow learners.
Questions, Suggestions and Comments
Please ask a question that you are unsure about – others will probably have the same question.
What can I do better? Please make suggestions.
Did you enjoy the post? Please comment or share on your social networks.
Comments are closed.