Gossamer Links Developers Guide
: Understanding Plugins
Plugins are a powerful new
feature of Gossamer Links that allows you to easily create, distribute and
install addons to Gossamer Links. Using the Plugin API you can easily override
any aspect of the program..
At it's heart, a plugin is
simply a tar file with at least two files: Install.pm and Yourpluginname.pm.
The install file manages installation and removal code, and the other file
contains your main code. All plugin code must be under the name space
Plugins::Yourpluginname for them to work correctly. You can use the Plugin
Wizard to create a template file for you to start with.
There are three main ways a
plugin interfaces with Gossamer Links:
1. Plugin Hooks:
A hook is simply a label for a section of code in Gossamer Links. For example
the user_add_link hook is when a user adds a link to the database. There are
a number of predefined hooks that are available for you to add code to, or
replace existing code. Your plugin can register some code to run before or
after a specific hook and optionally cancel the main code that would have
run.
It works as follows. We'll
use the search_results hook as an example:
- The user does a search
for the word 'alpha'.
- Gossamer Links figures out the
user is searching for something, and recognizes this is a plugin hook
spot. It loads the plugin config file, and checks to see if any plugins
are registered for the hook 'search_results'. If it doesn't find any, it
just runs the regular search and continues on.
- If it finds a plugin that
has registered a subroutine to run before the hook, it will run that
subroutine and capture the output. The subroutine must call GT::Plugins->action ( STOP )
or GT::Plugins->action ( CONTINUE ); If it calls STOP, the main Gossamer Links code is
skipped, and we go to step 5. If it calls CONTINUE, any other plugins
are similarly processed.
- The main code is run.
- Gossamer Links now looks for a
plugin that has registered a subroutine to be run after the hook. It
runs all post subroutine hooks. If a subroutine calls STOP, then no
more hooks are run.
- Code continues as normal.
As you can see, there are a
lot of possibilities. If you want your search results to search AltaVista
automatically, you simply set up a POST search_results plugin that only runs
if the Gossamer Links code found no matches. If you want to setup a search cache,
you setup a PRE search_results hook that checks to see if it knows the
results that the user is looking for, and if so return immediately, don't
run any other plugins.
2. Admin Menu Options:
Your plugin can create menu options in the Admin. When the install is
run, you can add any number of menu options that a user can click on.
3. User Options:
The plugin interface includes a simple get/set interface to store user
options.
For more information on
creating plugins, be sure to read the rest of the guide, and walk through
the examples.
|