Creating a Plugin
This article goes through the steps you need to follow, and things to consider when creating a well-structured BuddyPress Plugin.
The first task in creating a BuddyPress Plugin is to think about what the Plugin will do, and make a (hopefully unique) name for your Plugin. Check out Plugins and the other repositories it refers to, to verify that your name is unique; you might also do a Google search on your proposed name. Most Plugin developers choose to use names that somewhat describe what the Plugin does; for instance, a weather-related Plugin would probably have the word “weather” in the name. The name can be multiple words.
The next step is to create a PHP file with a name derived from your chosen Plugin name. For instance, if your Plugin will be called “Fabulous Functionality”, you might call your PHP file fabfunc.php. Again, try to choose a unique name. People who install your Plugin will be putting this PHP file into the BuddyPress Plugin directory in their installation, wp-content/plugins/, so no two Plugins they are using can have the same PHP file name.
In the rest of this article, “the Plugin PHP file” refers to the main Plugin PHP file, whether in wp-content/plugins/ or a sub-directory.
If you want to host your Plugin on http://wordpress.org/extend/plugins/, you also need to create a readme.txt file in a standard format, and include it with your Plugin. See http://wordpress.org/extend/plugins/about/readme.txt for a description of the format.
Note that the WordPress plugin repository takes the “Requires” and “Tested up to” versions from the readme.txt in the stable tag.
It is also very useful to create a web page to act as the home page for your BuddyPress Plugin. This page should describe how to install the Plugin, what it does, what versions of BuddyPress it is compatible with, what has changed from version to version of your Plugin, and how to use the Plugin.
Now it’s time to put some information into your main Plugin PHP file.
Standard Plugin Information
The top of your Plugin’s main PHP file must contain a standard Plugin information header. This header lets BuddyPress recognize that your Plugin exists, add it to the Plugin management screen so it can be activated, load it, and run its functions; without the header, your Plugin will never be activated and will never run. Here is the header format:
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
License: A "Slug" license name e.g. GPL2
The minimum information BuddyPress needs to recognize your Plugin is the Plugin Name line. The rest of the information (if present) will be used to create the table of Plugins on the Plugin management screen. The order of the lines is not important.
So that the upgrade mechanism can correctly read the version of your plugin it is recommended that you pick a format for the version number and stick to it between the different releases. For example, x.x or x.x.x or xx.xx.xxx
The License slug should be a short common identifier for the license the plugin is under and is meant to be a simple way of being explicit about the license of the code.
Important: file must be in UTF-8 encoding.
It is customary to follow the standard header with information about licensing for the Plugin. Most Plugins use the GPL2 license used by BuddyPress or a license compatible with the GPL2. To indicate a GPL2 license, include the following lines in your Plugin:
/* Copyright YEAR PLUGIN_AUTHOR_NAME (email : PLUGIN AUTHOR EMAIL)
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
Programming Your Plugin
Now, it’s time to make your Plugin actually do something. This section contains some general ideas about Plugin development, and describes how to accomplish several tasks your Plugin will need to do.
BuddyPress Plugin Hooks
Many BuddyPress Plugins accomplish their goals by connecting to one or more BuddyPress Plugin “hooks”. The way Plugin hooks work is that at various times while BuddyPress is running, BuddyPress checks to see if any Plugins have registered functions to run at that time, and if so, the functions are run. These functions modify the default behavior of BuddyPress.
Another way for a BuddyPress Plugin to add functionality to BuddyPress is by creating custom Template Tags. Someone who wants to use your Plugin can add these “tags” to their theme, in the sidebar, post content section, or wherever it is appropriate. For instance, a Plugin that adds geographical tags to posts might define a template tag function called geotag_list_states() for the sidebar, which lists all the states posts are tagged with, with links to the state-based archive pages the Plugin enables.
To define a custom template tag, simply write a PHP function and document it for Plugin users on your Plugin’s home page and/or in the Plugin’s main PHP file. It’s a good idea when documenting the function to give an example of exactly what needs to be added to the theme file to use the function, including the <?php and ?>.