Plugin Authoring
From GregariusWiki
Contents |
[edit] Introduction
Plugins can be used to enhance certain aspects or add new features to your Gregarius installation in a quick and easy way.
End-users will install plugins by placing the plugin file(s) in their /plugin/ directory and activate them in the Config section of their Gregarius Administration interface.
Note that a good place to discuss plugin development is the gregarius-dev mailing list.
[edit] The Gregarius Plugin Architecture
Gregarius plugins follow the Wordpress Plugin Architecture quite closely and writing a plugin is fairly straightforward. At some key locations throughout the Gregarius source-code call-back hooks are defined. You can insert functionality at that location by having your plugin register for that hook.
Gregarius plugins can be categorized in two families:
- Filter plugins : Filter plugins will take a variable as input, which will vary depending on which hook they are working with, and must return the same variable, after it has been modified: they basically filter the content they are being passed
- Functional plugins : : Functional plugins receive the php null value as their input and are not required to return anything. This is usually the case when the plugin is used to inject HTML code at the hook’s location.
Gregarius plugins usually consist of a single php file, having the following key sections:
- Plugin meta-information : These provide information like the plugin name, provided features, and author.
- Plugin code : The actual code that provides the plugin’s features
- Plugin call-back hooks : These are just calls to rss_set_hook() which tell Gregarius when the plugin code should be executed.
[edit] Plugin Meta-information
Plugin meta-information provides key informations about the plugin. These entries are required and undergo strict syntax rules: plugin meta-information is composed out of a set of specially formatted php comments. Each entry starts with three consecutive slashes (///), followed by a space, the field name, a colon, a space, and finally the field content.
A sample plugin meta-info section looks like this:
/// Name: Sample Plugin /// Author: John Doe /// Description: This is the description of the “Sample Plugin” plugin /// Version: 1.0
Future versions of plugin will probably also support these additional fields:
- Plugin URL
The URL of the homepage, if any, for this plugin
- Author URL
The URL of the author’s website (http://…), or the author’s email address (mailto:email@address).
[edit] Hooks
Hooks are specific locations in the Gregarius source code where plugin functionalities can be inserted.
Each hook is identified by a unique identifier. Plugins which registered themselves against this identifier will be called when code execution reaches the given hook
Depending on where the hook is located, this will also pass a variable along to the plugin. Plugins that take a variable other than the PHP value null are required to return it after it has been modified.
A list of plugin hooks is also available.
[edit] Recommended API Calls
While your plugin is able to use any and all functions defined in the source of Gregarius, there is a limited subset of recommended calls. Using the functions in this list will provide consistent implementation and interoperability across multple plugins. It should also prevent your plugin from being broken with future updates to Gregarius.
In general, the safe API functions begin with the prefix rss_plugins_ and are defined in plugins.php. This wiki will also maintain an up-to-date list of recommended API calls where more detailed documentation will be given.
[edit] Providing Configuration Options
As of Gregarius version 0.5.3, each plugin has the option of storing its own configuration options. This data is stored in the database alongside the other configuration options. The configure plugin hook is fired when the user clicks the edit button beside your plugin on the plugins page.
The first step is to define a configuration hook for your plugin. Rather than the traditional method of calling rss_set_hook, a plugin configuration hook is defined inside the Meta-information section of your plugin. You must provide the name of your configuration function inside the Configuration field of the Meta-information. For example, Charilaos Skiadas's Auto-highlighter plugin contains the following:
/// Configuration: __yourplugin_config
When a user clicks the edit button beside the Auto-highlighter plugin on the plugins page, the function _autohighlighter_config will be invoked. This function will again be invoked when the user submits the resulting form. Most commonly, the configuration function is defined as follows.
function __yourplugin_config() {
if (rss_plugins_is_submit())
{
//call rss_plugins_add_option to save your information
}
// render a form for the user to edit your plugin's options.
// Gregarius will provide the <form> tag as well as a submit
// and cancel button. Use rss_plugins_get_option to retrieve
// the current values from the database.
}
Once your plugin has been configured, you can retrieve stored configuration options by calling rss_plugins_get_option and passing the name of your parameter. If you determine that the configuration data no longer needs to be stored, it can be removed by calling rss_plugins_delete_option.
[edit] Coding guidelines
Plugin authors should follow these coding guidelines:
- In order to minimize the risk of conflicts, php function names in plugins should start with a double underscore, followed by the plugin name, e.g. : function __sample_plugin_functionName($var) { …
- If needed, plugins should access the database through the database-wrapping functions provided by Gregarius. See: db.php
- Plugins shouldn’t store persistence data in the config database table. A plugin-specific way of saving and reading configuration entries will be provided in an upcoming version.
- Take extra care that your plugin files don’t contain any extra new-line or space characters before the opening “<?php” and after the closing “?>” elements.
- Remember never to use short open tags like "<?=" . Instead make sure that you are using “<?php echo”
[edit] Sample plugin
A sample plugin is probably the best way to understand how plugins work in Gregarius.
This (completely useless) plugin will be called against the content of every new item when you update your feeds, and will strip out HTML links from the content before it is inserted in the database.
<?php
/// Name: Link Remover
/// Author: Gregarius
/// Description: This sample plugin will filter out links from new items content.
/// Version: 1.0
/**
* This function will remove html links from the passed
* content, then return it.
*/
function __linkremover_removeLinks($content) {
$ret= preg_replace("/<a[^>]+>/im","",$content);
$ret= preg_replace("/<\/a>/im","",$ret);
return $ret;
}
// The plugin hook: link the ‘rss.plugins.import.description’
// hook to the removeLinks function:
rss_set_hook(
"rss.plugins.import.description",
"__linkremover_removeLinks"
);
?>
[edit] Help
If you need help writing a plugin or if your plugin requires a plugin hook that is not available, please post a message to the gregarius-dev mailing list. Many examples of plugins are available at the plugin repository.
[edit] Distribution
If you think your plugin would be useful to the user community, it would be really nice if you added them to the plugin repository.
