This is the seventh article in our plugin development tutorial series. In the last segment, we covered debugging basics, cross-browser testing, and WordPress version testing. You can access the linked table of contents for the entire series below.
Today, we'll discuss additional files that you should include in your plugin's folder.
Table of Contents for this Tutorial
The license.txt File
In order to be listed in the WordPress Plugins Repository, your plugin is required to adhere to a GPL2 compatible license. As we discussed in part 2 of this tutorial series, it is recommended that you include the license description just below the header block in your primary plug-in file.
Further, it's a good idea to also include a more detailed license.txt file in your plug-in's root folder. Generally, a plain text version of the GPL2 license will suffice.
Click this link to view a typical example. Right-click “Save As” to download it.
Although WordPress does require a license disclosure in order to be included in their repository, I've found many failures to do so. It seems to me that about 10% of the plugins have an actual license.txt and about 60% have the license description in the primary file's header. However, you can bet that their standards will be enforced at some point, so why not do it right from the start.
The index.html File
Most servers prevent directory file listing by default. If you have a LAMP installation, you can enforce this security measure by including the following command in your .htaccess file.
Conversely, you can allow directory listing for a specific folder by putting an .htaccess file in that particular folder with the following content:
Since we don't have control over the security features of the site on which our plug-in is installed, it's a good idea to simply include a blank file named index.html in your plug-in's root folder. This way, if someone tries to view the files from a browser (using the address bar, for example), they'll just get a blank white page.
Moreover, you could modify this technique slightly to have a warning message in a short index.html file. Click this link to view a simple example. Right-click “Save As” to download it.
The uninstall.php file
WordPress includes the register_uninstall_hook() function which can handle the final cleanup, if your plug-in is deleted by the user. This is chiefly for removing any database tables that were created or options that were stored after activation.
The recommended method of achieving that final cleanup step, however, is to simply include an uninstall.php file in your plug-in's root folder. Personally, even if my plug-in's don't make any database changes, I like to include a blank uninstall file just to let the savvy user know that deletion will be a complete removal.
Again, either the function or the file is implemented ONLY if the user chooses to delete the plug-in through the dashboard. Normal deactivation does NOT invoke this procedure.
Here's an example of an uninstall.php.
1 2 3 4 5 6 7 8 9 10 11
<?php // delete a NEW table that was created global $wpdb; $table_xyz = $wpdb->prefix . 'wcs_xyz'; $wpdb->query("DROP TABLE IF EXISTS $table_xyz"); // delete various options that were added to the OPTIONS table delete_option('wcs_set_01'); delete_option('wcs_set_02'); delete_option('wcs_set_03'); ?>
More robost plug-in's sometimes need to create their own database table. Lines 2 – 5 demonstrate how to remove such a table. Typically, though, only options are added to the OPTIONS table. Lines 7 – 10 demonstrate how to remove these. It is worth noting that delete_option() removes both single-value options and serialized, multi-value options.
Of course, each of the items listed here are fictitious names. You would use your own appropriate names.
Creating Screenshot Images
The WordPress plugin repository processes a special section of the readme.txt file specifically for screenshots. You don't have to use this feature. However, before someone downloads your plug-in, it's a good idea to provide at least one image for them to view.
If your plug-in presents a visual interface for dashboard options or provides a display for the end-user (blog visitor), you should capture these images for use with this capability. There's no real limit to the number you can use, but typical plug-in's include 1 to 5 screenshots. Also, your image width should not be greater than 500 pixels.
These files can be PNG format (the most common), JPG, or GIF. And, their names should be numbered … this is important for the readme.txt file … screenshot-1.png, screenshot-2.png, screenshot-3.png, and so on.
Several graphics programs (GIMP and PaintShop Pro, for example) offer a screen capture facility which is activated by clicking a pre-defined hotkey. TechSmith also has the stand-alone SnagIt utility.
With the Windows OS, you can capture the entire screen by pressing the PRINT SCREEN key. And, you can capture the active window by pressing the ALT+PRINT SCREEN combination. Then, just open your favorite graphics program, choose paste as new image, clip the portion you want for your screenshot file, and save it in your plug-in's root folder. Repeat these steps for each screenshot.
With the Mac OS, you can capture the entire desktop by pressing COMMAND+SHIFT+3. The screenshot will automatically be saved as a numbered PNG file on your desktop. And, you can copy the entire desktop by pressing COMMAND+CONTROL+SHIFT+3. The screenshot will be placed on your clipboard for you to paste into your favorite graphics program for clipping and saving.
My personal preference is a free FireFox plug-in named ScreenGrab. With this handy utility, you simply right-click on the web page and open the ScreenGrab submenu. From there you can choose to SAVE or COPY one of three options: the complete page, the visible portion, or a selection (by dragging the mouse). Then, you can use your favorite graphics program for fine-tuning and saving.
An Overview of the readme.txt File
Rather than using HTML, WordPress readme.txt files utilize a lightweight markup language called Markdown. It's basic purpose is a syntax structure for easy text-to-HTML conversion. WordPress also uses it to segment sections of the readme.txt file for tabbed presentation at the repository. You can read about it from one of its creator's here or at Wikipedia.
There is a bit of a learning curve with Markdown. So … let's look at four tools that make it easier.
- WordPress offers an example that you can use as a template for creating your readme.txt files.
- They also have a readme.txt validator that you can use to view a rough example of what your file will look like at the repository. It is strongly recommended that you test your readme.txt file with this utility before submitting your plug-in. Oddly though, the validator does not use the same stylesheet as the repository.
- Sudar Muthu has a cool online Plugin Readme File Generator that may save you some time and effort in creating your basic file. Just complete the text fields on his form and hit the Generate button.
- Similarly, David Artiss has a WP README Parser plug-in which lets you display formatted readme.txt files in a post or page using shortcodes.
Markdown Language Basics
A paragraph is defined as one or more lines of text, separated by at least one empty line. There is no other equivalent of <br/> or <p>.
The following are examples of the more common uses of Markdown in readme.txt files. These styles are very similar to those that are used at the repository.
*for italicized text* for italicized text
`for highlighted text` for highlighted text
= for large boldfaced text = for large boldfaced text
[WP Code Snippets](http://wpcodesnippets.info "Visit Our Site")
* that and
* the other thing
The readme.txt File Structure
Now, let's look at a skeleton of a basic readme.txt file:
=== Your Plugin Name Here === Contributors: (plug-in contributors separated by commas -- preferably use WP forum sign-in names) Plugin URI: (your plug-in's landing page on your web site) Tags: (search terms for the plug-in -- separated by commas) Author URI: (plug-in author's site -- typically your web site's home page) Author: (the plug-in's author) Donate link: (a URI for donating -- appears in the sidebar under FYI as 'Donate to this plugin') Requires at least: (minimum required WP version, eg, 2.9.0) Tested up to: (tested with WP up to version, eg, 3.1.3 -- UPDATE AS NEEDED) Stable tag: (plug-in's stable version, eg, 1.0 -- should be the latest version in the trunk folder -- UPDATE AS NEEDED) Put a short description here (max 150 characters). No markdown code! This will appear above the tabs and below the title. == Description == Put your long description markdown here. == Installation == Put your installation and usage instructions markdown here. == Screenshots == 1. This markdown description will appear underneath screenshot-1.png. Number is required, ie, '1. '. 2. This markdown description will appear underneath screenshot-2.png. Number is required, ie, '2. '. 3. This markdown description will appear underneath screenshot-3.png. Number is required, ie, '3. '. == Changelog == Put notes about your update history here as markdown. == Upgrade Notice == This section is outdated. However, it's required by the online validator. == Frequently Asked Questions == The markdown you put here will appear under the FAQ tab. == Additional Information == The markdown you put here will appear under the OTHER NOTES tab. Use your own section header name. == More Information == The markdown you put here will appear under the OTHER NOTES tab. Use your own section header name. == Donations == The markdown you put here will also appear under the OTHER NOTES tab. This is a pre-defined name.
Replace the parenthetical descriptions in the header block with your specific information. Also, you can arrange the sequence of these header items to your preference.
Section headers (Description, Installation, etc.) are tagged with double-equals-signs. You can omit the ones that you are not using. Put your markdown text just beneath the appropriate section headers. And, you can arrange the sequence of these sections to your preference.
It's not publicized, but you can include YouTube and Vimeo videos in your sections. This also works with the validator. For example, these two will display the actual videos.
Use like this:
or like this:
In our next article, we'll explore Submitting Your Plug-in to WordPress.
In our last article, we discussed Plug-in Testing Techniques .