# Gossamer Links Help

Table of Contents

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:

1. The user does a search for the word 'alpha'.
2. 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.
3. 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.
4. The main code is run.
5. 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.
6. 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.

Table of Contents