|
This document is intended to describe the rules and guidelines to follow for creating custom gStats reports. It is not, however, a
document explaining the database structure of gStats or the logic
required to create a custom report.
- Reports must be contained within a single file.*
- The report file must contain at least one class, which name exactly matches the name of the file. For example, the file MyCustomReport.php must contain the class MyCustomReport.
- The class which matches the name of the file must follow the template defined below**.
- All database access must be made through ADOdb. A connection will be pre-established and available through the variable $CONFIG[‘dbCon’] (for each method using the $CONFIG variable
you will need to include a "global $CONFIG;" statement). Also, instead of using direct table names,
tables should be reference via $CONFIG[‘tableTABLENAME’]
(see database structure).
- The completed report file will be placed into the directory [gStats]/includes/reports/ and gStats will automatically recognize and incorporate the new report.
* The file containing your report can contain other classes that are used by your report. However, there may be only one report per file.
** PHP does not include (as of the creation of gStates) an interface mechanism such as that offered by Java or C#. For the purposes of creating custom reports, simply create a class that,
at a minimum, implements the methods defined below. The reports were not implemented using the inheritance mechanism offered by PHP simply because the defined interface offers no functionality and PHP offers no means of creating abstract classes.
class ReportName
{
//constructor
function ReportName($startDate=-1, $endDate=-1, $numRows=-1, $startTime=0, $endTime=SECONDS_IN_DAY)
{
...
}
//returns name of report class
function getClassName()
{
return "ReportName";
}
//returns title of report
function getTitle()
{
return "Title of Report";
}
//gets more detailed description of report
function getInfo()
{
return "Detailed Description of report.";
}
//shows the report
function showReport()
{
...
}
}
Your report class must contain a constructor that matches this signature (replacing ReportName with the class name of your report).
If your report class is instantiated with $startDate=-1 or $endDate=-1 then your constructor must do nothing . This is usually done when your report is being created for the purpose of retrieving its title or description. The method showReport() will not be called if the class was instantiated in this manner. However, getClassName(), getTitle(), and getInfo() may be called.
Generally the database access and statistics generation are done within the constructor. However, this is not a requirement and may not be practical depending on the type of report.
The start date of the time range that the report must cover. In the format YYYY-MM-DD.
The end date of the time range that the report must cover. In the format YYYY-MM-DD.
The maximum number of rows that this report should display (not including headers and totals). The report can show less than this number of rows but should only do so if it is logical. If numRows is equal to -1, the report should display the default number of rows, $CONFIG["defaultNumRows"].
The start time of the time range that the report must cover. This time is in number of seconds from 12am on $startDate (this is not a UNIX timestamp).
The end time of the time range that the report must cover. This time is in number of seconds from 12am on $endDate (this is not a UNIX timestamp).
Returns a string containing the exact class name of this class, which will also be the name of the report file (minus the .php).
Returns a string containing a short title for the report. It is ideal to keep the title short but meaningful since it will be displayed with many other reports in tables and menus.
Returns a string containing a detailed description of this report, including a description of each column shown. HTML is permissible in this string, however, opening/closing HTML and BODY tags are not necessary.
Shows the report based on the criteria passed into the constructor. No return values are required nor is any indication of success or failure. While there are no steadfast guidelines, it is recommended that reports be structured and displayed similar to the reports included with gStats.
The easiest way to write a suitable showReport() method is to modify one included with the gStats reports. Conforming to this format will create a more uniform feel and allow style sheet updates to work universally. Also, take a look at [gStats]/includes/importConfig.php for all of the configuration values available to your report.
|
gStats
