Custom Plugins

Custom Plugins

Top Previous Next

What is a custom plugin?
A custom plugin is a subroutine, written in php code, that is not a part of the standard plugin set, that may be included into your program's output, by placing the appropriate HTML Tag into your template. This HTML tag MUST follow this format:

Where plugin_name is the name of a php subroutine and module (.inc) located in the "custom" subdirectory within the data directory of your installation. Custom plugins can be written offline, using your own development environment, and uploaded into this directory manually, via FTP (use ascii file transfer mode when uploading them), or by using the Plugin Editor from within your admin center.

You can optionally append parameters inside of parenthesis to your custom plugins, like this:

Let's write a simple custom plugin , to illustrate the specifics of developing a custom plugin. This sample plugin will read from a database table which contains a bunch of strange facts about nothing in particular.

The purpose of this plugin is to show a random fact to the visitor on each page that they visit.

In order to do that, we need to first have a source for these facts. So, assume that you have a database table, called "facts", that has one column, called "fact_string", with the following entries.

   Cleveland Rocks!
   Oh No, Mr Bill ....
   If I had a nickel for every time you said that
   Pain Hurts

Now, let's think about how this plugin will work. First, we have to connect to the database, run a query that picks a fact at random, and then send that back out to the browser. Easy enough, let's go.

Open a new text file, and call it "factoids.inc". Remember, the custom plugin that you're calling from inside the template is called PLUGIN:CUSTOM:factoids. Therefore, the program will be looking for a perl module called "factoids.inc", so make sure that you name the file with the same name as the plugin.

Now, create your subroutine. The code for this routine is below, and is well commented, so you can follow along easily.

<?php

### Plugin: factoids

## Note, the subroutine name is also the same

## name as the plugin module file!

function factoids {

Pull in any globally needed variables. Note that

in this plugin, we're not going to use some of them,

but for the sake of the example, this is how you'd do it

global $CGI; // Query String or Post paramaters

global $oSQL // OLAP Database Server Connection for lookups

global $language // Language definitions

global $config // Preferences settigns

global $templates // Internal Templates, all preloaded for you.

// First, let's construct an SQL Query to get one random fact.

$SQL = "SELECT * FROM facts LIMIT 1 ORDER BY RAND(NOW()) LIMIT 1;

           // Now, using the database connection that the program already
           // established, run it.  The command below will run the query
           // specified, and will return a single sting value back.  You could
           // also ask it to return a "hash" or a "set", which is an array
           // of associative arrays

           $factoid = $oSQL->search( array( "SQL"=>$SQL, "Return"=>"single" ) );

// Now, we have the fact, let's format it.

// For the sake of this example plugin, rather than just regurgitate

// it with some HTML around it, let's use an internal template called

// "factoid" that you would need to create under "Hyperseek" as a "LAYOUT"

// style template.

// Grab the template from the $templates hash (predefined)

$template_text = $templates['hs_admin']['default']['LAYOUT']['factoid'];

// Note that the template object expects an associative array for use in

// substituting <<variables>> with their actual value, so let's create one

// right now, with our fact text in it. Assume, that the template has

// <<factoid_text>> somewhere in it.

$values['factoid_text'] = $factoid;

// Create a new template object

$template = new SubTemplate( array( "front"=>"<<", "back"=>">>", "template_text"=>$template_text, "values"=>$values ) );

// Merge the values in the associative array from above into your template:

$output = $template->merge();

// Whatever we "return" here will be spit out into your template

return $output;

}

Save this file, upload it to your server (discussed in the installation chapter), and put the plugin tag into any of your program templates, and it'll show you a random line from the facts file on every page of your application.

Be sure, when writing your plugins, that you stick to the following:

Structure Guidelines

Plugin Names must be ascii only (no numbers, spaces, or characters other than an underscore (_)... if you use the online plugin editor, the name will be properly converted for you, should you enter something invalid.

All variables used by the function must be either one of our global variables (see the list below), or declared for use only by your subroutine.

DO NOT USE the echo or print commands anywhere inside your plugin.... custom plugins are run in queue during the parsing of your template, their output accumulates with the rest of the program's output. So, you should "collect" your plugin's output into a variable and return the output to the program

Your plugin is treated as a separate module by the system, so please make sure that is contained within <?php and ?> tags.

System Globals ...
To aid in writing your custom plugins, there are a few global variables that you'll be able to use, so that your plugin has access to the same environment that the main program has:

$CGI // Query String or Post parameters

$oSQL // OLAP Database Server Connection for searches/lookups

$iSQL // OLTP Database Server Connection for writes/deletes

$language // Language definitions

$config // Preferences settings

$templates // Internal Templates, all preloaded for you.

$searchengine // Search Engine Object for Hyperseek custom plugins, contains specific settings for Hyperseek. You can do a "print_r($searchengine) somewhere in your plugin to get the rundown of the data it contains.

$manager // Account Manager Object for jackhammer bid manager custom plugins, contains specific settings for Jackhammer Accounts. You can do a "print_r($manager) somewhere in your plugin to get the rundown of the data it contains.