Gregarius - Devlog

This document is a developer’s guideline on writing Gregarius plugins

Table of Contents

1. Introduction

2. The Gregarius Plugin Architecture

3. Plugin Meta-information

4. Hooks

5. Coding guidelines

6. Sample plugin

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.

↑ Back to the Table of Contents

The Gregarius Plugin Architecture

Gregarius plugins follow the Wordpress Plugin Architecture quite closely. The basic gist is the following:

• On some key locations throughout the Gregarius source-code call-back “hooks” are defined.

• Plugin authors can “inject” functionalities at these locations by having their plugins “register” for that task.

Although they work strictly in the same way, 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:

1. Plugin meta-information

   These provide information like the plugin name, provided features, and author.

   See also: Plugin Meta-information.

2. Plugin code

   The actual code that provides the plugin’s features

3. Plugin call-back hook

   This usually consist of a single line of code calling the rss_set_hook() function, which will instruct Gregarius on when the plugin code should be called.

   See also: Hooks.

↑ Back to the Table of Contents

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:

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).

↑ Back to the Table of Contents

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.

At the time of writing the following hooks are provided:

Additional hooks can be added to the Gregarius code quite easily. Please contact me if your plugin requires a new hook.

↑ Back to the Table of Contents

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.

↑ Back to the Table of Contents

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"
 );
?>

↑ Back to the Table of Contents