Plugin Specification

[Documentation Index]
Writing a plugin report should be a fairly simple task if you understand perl. A plug-in report is just a file with a special name and format, put into the right directory. A template file is included to make sure the file is in the right format in the plugins/ directory. The following points should help you in creating plug-in reports:

1. Create the file
the 'report.template' file is where you should start when writing a plug-in report. It has the basic format you need to keep inside of the file. All plug-in reports must have a filename like 'sub.report_name' to be recognized and executed. The report_name is the name of the subroutine that MKStats should call once it has 'required' your file. So, if you created a subroutine called 'my_report' then your filename must be 'sub.my_report'.

2. Edit the file
Here is a description of the blank template file and what you should put where. Anything in <bold> should be added by you.
# ======================================================================
# <A short description of what this does>
# ======================================================================
sub <routine_name> {

$NAME="<The title of your report, such as 'visitor summary'>";
$DESC="<A short description of this report>";
$CATEGORY="<One of: SUMMARY,WHO,WHAT,WHEN,REFERER,BROWSER,ERROR,MISC>";
$LINK="<The filename of your report, such as 'my_report.html' or 'my_report.txt'>";

&AddToIndex($NAME,$DESC,$CATEGORY,$LINK);
# ----------------------------------------------------------------------
# Local Settings:
<Put any local variables used here, so they can be configured>
# ----------------------------------------------------------------------

open(OUT,"> ${REPORT_DIR}$LINK");

<Your routine goes here>

}
1;

3. Use the correct variables
MKStats compiles a lot of statistics and places them into variables that you should use inside of your plug-in reports. You are free to modify these values if you wish, but it is not recommended because it may interfere with the accuracy. There are no restrictions places on how you use these variables so that you have as much control as possible. This does, however, open up some possible problems which are up to you to avoid. A list of all variables and what they contain is located here.

4. Submit your plug-in report
I would like to have a growing collection of plug-ini reports that users create so others can benefit from them as well. Please go to the MKStats site to find out how to submit your report. I will make sure it does not have any bugs, does what it intends, and does not conflict with any other part of the program, and then make it available. I cannot guarantee that all reports will be made available to everyone, and of course you do not need to submit your report if you do not wish to do so.

This documentation will hopefully get you started on creating plug-in reports. I will write some more detailed information when I get a chance.