Gossamer Links Help


Table of Contents

Gossamer Links Developers Guide : The Install File

Each plugin must contain an Install.pm file. This file contains install and uninstall code that the plugin requires. The plugin wizard will create a useable Install.pm file for you, but if you need to do anything special like creating SQL tables, extracting files, or adding templates you will need to edit the Install.pm file. The install file must contain four subroutines:

sub pre_install {}
The pre install function displays a message to the user before the plugin is installed. It should return a string containing HTML that will be displayed. You can output an HTML form with form fields asking the user any information you will need in the actual install.

sub install { my ($mgr, $tar) = @_; }
This function does the actual install of the plug in. Passed in are two arguments, the first is a GT::Plugins::Installer object which you can use to setup hooks, menu  options or user options (see the Plugin Wizard for a sample). The second argument is a GT::Tar object that has all the files in your current tar. You do not need to extract the install.pm or Yourpluginname.pm file, that is done automatically.

Your function should return an HTML message of the plugin results. If you want to abort the install, you should return undef and have an error message stored in $Plugins::Yourpluginname::error. You should always return a useful  error message if there was a problem with the install.

sub pre_uninstall {}
The pre uninstall function is the same as the pre_install function described above. 

sub uninstall { my $mgr = shift; }
The uninstall function takes one argument, a GT::Plugins::Installer object. You should be sure to clean up any columns you created, and drop any tables you created.

Examples
1. Your install needs to add a custom column named 'Review' to the Links Table to do this we will need a GT::SQL::Editor object. However, we should first check to make sure the column doesn't already exist (as they may be upgrading the plugin):

unless (exists $DB->table('Links')->cols->{'Review'}) {
    my $editor = $DB->table ('Links');
    unless ($editor->add_col ( 'Review', { type => 'TEXT' }) {
        $Plugins::Pluginname::error = "Unable to add column to Links: $GT::SQL::error";
        return;
    }
}

2. Your install needs to create a new table called Reviews that has a username column that relates to the Users table, and an ID column that relates to the Links table. For this we will need a GT::SQL::Creator object.

my $creator = $DB->creatore ('Reviews');
$creator->cols ( {
                   LinkID => { pos => 1, type => 'INT', not_null => 1 },
                   ReviewedBy => { pos => 2, type => 'CHAR', size => 25, not_null => 1 },
                   Review => { pos => 3, type => 'TEXT' },
                   ReviewDate => { pos => 4, type => 'DATE' }
                });
unless ($creator->create) {
   $Plugins::Pluginname::error = "Unable to add Reviews table: $GT::SQL::error";
   return;
}

3. Your install needs to extract a user cgi script into the users cgi directory. For this we will use the GT::Tar object.

# Get the file from the tar file, $tar was passed into install.
my $file = $tar->get_file ('newscript.cgi');
# Get the entire code as a string.
my $code = $file->body_as_string;
# Replace the path to perl with the users perl.
$code =~ s/^#!(.*)/$CFG->{path_to_perl}/;
# Replace the use lib with the users admin directory.
$code =~ s/use lib '[^']+'/use lib '$CFG->{admin_root_path}'/;
$file->body ($code);
# Set the name of the file
$file->name ($CFG->{admin_root_path} . '/../newscript.cgi');
# Save it.
unless ($file->write) {
   $Plugins::Pluginname::error = "Unable to extract newscript.cgi file. Reason: $GT::Tar::error";
   return;
}
# Set permissions
chmod (0755, $file->name);

Note: We have to make sure to set the path to perl, chmod the file, and add a use lib to the admin directory. All this information is available in the Gossamer Links configuration: $CFG.

Table of Contents