Skip to:
Content
Pages
Categories
Search
Top
Bottom

Creating a Plugin

This article goes through the steps you need to follow, and things to consider when creating a well-structured BuddyPress Plugin.

Plugin Name
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.

Plugin Files
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.

Another option is to split your Plugin into multiple files. Your BuddyPress Plugin must have at least one PHP file; it could also contain JavaScript files, CSS files, image files, language files, etc. If there are multiple files, pick a unique name for a file directory and for the main PHP file, such as fabfunc and fabfunc.php in this example, put all your Plugin’s files into that directory, and tell your Plugin users to install the whole directory under wp-content/plugins/. However, an installation can be configured for wp-content/plugins to be moved, so you must use plugin_dir_path() and plugins_url() for absolute paths and URLs. See: http://codex.BuddyPress.org/Determining_Plugin_and_Content_Directories for more details.

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.

Readme File
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.

Home Page
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.

File Headers
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:

<?php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Tags: buddypress
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.

License
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:

<?php
/* 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.

Template Tags
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 ?>.