twd_events Technical Documentation

Index / Plugins

The plugins system is comprised of 2 required files to write a plugin.

toc.pl - A Table of Contents file. Contains general information about the plugin.
functions.pl - Contains procedures used by the plugin.
common functions - Common functions available to all plugins.

toc.pl

toc.pl contains the general header information about the plugin. toc.pl contains 2 hash elements that are used to display plugin information.

We need to register our plugin with the system via function &RegisterPlugin;

As you can see we are passing 2 different anon arrays. First array contains plugin data, 2nd contains author data.

&RegisterPlugin(["version", "plugin title", "plugin description"],

 ["author", "author\@email"]);

Note: It is VERY IMPORTANT to use the trailing backslash in the email address or PERL will mistake the @ sign as an array

function.pl

functions.pl contains the actual function code and event registration calls

Event Registration

Event registration is done via the &RegisterForEvent function

Syntax:
&RegisterForEvent([event], [procedureName]);

[event] - the event you are registering for. See Events Codes for list of events.
[procedureName] - the name of the subroutune to perform when your [event] occurs. DO NOT pass a reference to your subroutine, just pass it's name. To prevent any subrountine conflicts from occuring, I recomend that your subroutine name start with your plugin name or ID.

Example:


## Lets register for the calender.printout event. this will fire our "Header" procedure before printing out.

&RegisterForEvent("calender.printout", "DemoMode_Header");



## Here is our plugin procedure.

&DemoMode_Header {

	## We have a conditional arguement in our theme that allows us to not display the standard header.

	$StandardHead = 0;

	## We also have a variable $statusText in our theme where we can insert our "Demo Mode" header.

	$statusText = "Welcome to the Demo Mode!";

	
	## our plugin needs to report a success status back. If we encountered an error, we would want to 

	## return a 0 along with an error message.

	return 1, "Success!";

}

Common Functions

($success, $errmsg) = &QueryDB([sql statement]);

Used to execute sql statements on the database. if $success = 1, the sql statement has failed and the error returned by the database engine will be in $errmsg

(while $ref = &MySQLFetchHash) {

...

}

Used to fetch values from a SELECT sql statement after &QueryDB; Retrieve values via $ref->{'field name'}

&WriteSetting([key], [value]);

Used to write to hash %CONFIG which is stored in the database.

&RaiseEvent([event]);

Used to call event procedures that have registered for your [event]

&LoadTemplate("path/to/template");  ## Load a template file.

print &OutputTemplate; ## Print http headers and template contents.

exit;  ## Exit PERL!

Useful to output custom pages or errors