Attending to the Basics

In this chapter, you discover how to use a plugin template to deal with some of the programming you will use repeatedly as a plugin developer. You must also include some basic information within your plugin so that the users of your plugin identify the plugin easily. Standard practices also exist for the elements that should be included in your plugin if you intend to submit it to the official WordPress Plugin Directory at http://wordpress.org/extend/plugins. Plugins submitted to the directory are reviewed and vetted by WordPress developers to make sure that your plugin has all the necessary elements, is formatted correctly, and meets the standards of practice for all plugins.

Among these necessary elements — the basics — is a short snippet of code at the top of your plugin file that identifies seven important identifying characteristics of your plugin:

• Plugin Name: The identifying name of your plugin. Obviously, giving your plugin a unique and appropriate name is a good start so that it's easily identifiable in the WordPress Plugin Directory and the list of plugins available on a user's Dashboard. Because people who use WordPress will most likely install several plugins in their installation of WordPress, you want to make sure that your plugin has a unique name, and preferably a name that describes, in just a few words, what your plugin is.

  For example, say you're writing a plugin that allows people to connect their blog to the Twitter service. Would naming your plugin My Great Plugin make sense? On the other hand, is giving the plugin a name like WordPress Twitter Connect more helpful? The first name may go far to serve your ego but is utterly useless from a user's standpoint. Create plugin titles that make sense to the user and make the function of the plugin easily identifiable.

• Plugin URI: The Web address of the Web page that displays a full description of your plugin (and, perhaps, support forums and a history of the plugin, including a change log and instructions on how to use it).
• Description: A brief description of what the plugin does. This plugin description also displays in the WordPress Dashboard (to the right of the plugin name) and gives users a brief description of what the plugin does and why they should use it.

  If you intend to submit your plugin to the WordPress Plugin Directory, the words you use in the description and title will identify your plugin in search results there. Therefore, when writing the description of your plugin, use terms that will help users find your plugin easily. When people search for a particular term in the directory, all the plugins with that term in either the title or description will appear.

  Figure 6-1 displays the WordPress Plugin Directory search results page for the term Twitter; the titles and descriptions all contain Twitter and help identify the plugin in the search results.

• Version: The plugin's unique version number (that is, 1.0, 2.0, and so on). Most likely, the first time you release your plugin, you'll identify it as version 1.0. Each time you release an update to the plugin, you change the version; and the extent of the changes determines the version number you use. Small changes to the plugin, such as styling improvements or the correction of a small bug, necessitate a point release, such as 1.2. However, if your new release includes many features that greatly extend the functions of the original release, you would probably consider it a major release and version it 2.0.

  In Book I, Chapter 3, we discuss the WordPress development and release cycle as it pertains to the WordPress software. Within that chapter, you find information about the various versions of WordPress, how and why different version numbers exist, and point releases versus major releases.

  The version numbers are up to you, of course; this is simply a standard practice by many developers who release software in order to keep their versions organized.

  Figure 6-1: The WordPress Plugins Directory search results for Twitter.

  

• Author: Your name and the names of any developers who helped you create this plugin.
• Author URI: The Web address of the plugin author's Web site.
• License: The name of the license under which your plugin is released. (The accepted license here is GPLv2, which is the license under which WordPress is released. For more information on GPL licensing, including how it pertains to your plugin development practices, see Book I, Chapter 2).

The necessary code to include these seven items looks like this:

<?php
/*
Plugin Name: Your Plugin Name
Plugin URI: Web Address of your Plugin
Description: A brief description of the Plugin.
Version: Version Number
Author: Name(s) of the plugin Author(s)
Author URI: Web Address of the plugin author(s) Web site
License: License name (ie: GPL2)
*/
?>

<?php
/* Copyright 2011 WordPress Twitter Connect Lisa Sabin-Wilson

  This program is free software; you can redistribute it and/or modify it under
   the terms of the GNU General Public License, version 2, as published by the
   Free Software Foundation.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
?>

Figure 6-2 shows the Plugins page, displaying plugin names and descriptions.

Figure 6-2: The WordPress Plugins page on the Dashboard.