/ Extending ActiveStat Application / How to Extend?

Extending ActiveStat Application

How to Extend?

Storing Custom Parameters

Let's assume you have some forms to get software development quotes from your customers. And you'd like to get statistic reports on these quotes (which quotes, how often, which companies, manufacturers, etc.) Here are the steps to be taken to extend ActiveStat so you can get this kind of statistics:

Define a new parameter type in ui.cfg.php

define ("PT_QUOTE", PT_PREDEF_MAX+1);	// our new parameters will belong to this type
$statParamTypes[PT_QUOTE] = "Quote";	//our parameter type has been named 'Quote'

Define parameters (in "Parameters" of the administration part) belonging to the type.

Then you should write some code in your form processing scripts to store information on the defined parameters in the ActiveStat database. Let's consider an example with commentaries:

......

include ($stat_root_dir . "sss_main.php");

//include statistics script in the page to be tracked.
//The script contains the $stst object.
//It provides you with a number of functions to store
//parameters.

$tag = $stst->incTag("QUOTE");

//get the current tag and increment its value stored in the session

//prepare an array of parameters to be stored

$aParams = array("Q_FIRST_NAME" => addslashes($firstname),
	"Q_LAST_NAME"	=> addslashes($lastname),
	"Q_COMPANY"	=> addslashes($company),
	"Q_EMAIL"	=> addslashes($email),
	"Q_PHONE"	=> addslashes($phonenumber),
	"Q_URL"	=> addslashes($websiteurl),
	"Q_ DESCRIPTION"	=> addslashes($describeproject),
	"Q_QTYPE"	=> "Short quote");

$stst->getParamsIDs(array_keys($aParams));

//get IDs of the parameter to be stored/updated in the internal array

$stst->storeParams($aParams, $tag);

//store parameters

$stst->close();

//close database connection

......

incTag("QUOTE") - increment a tag index for a parameter group to distinguish between different parameter groups of the same type. Looking at our example, if a user makes more than one quote, we should be able to distinguish between them. This is achieved by assigning a unique tag for a parameter group. The function returns a current tag value and increments it for further use (a current tag value gets registered in the session variables).

If you fill a form made as a wizard, you should use another scheme. Here is an example of one of the wizard's mid-steps:

$tag = $stst->getTag("QUOTE");

//get the current tag for the specified parameter type name from the session

//create parameter array to be stored

$aParams = array("Q_PROJECT_TYPE" => intval($iProjType),
	"Q_WORKING_MODEL"	=> addslashes($sWorkModel),
	"Q_GETSTARTED"	=> intval($iGetStarted),
	"Q_DEADLINE"	=> addslashes($sDeadline),
	"Q_BUDGET_SIZE"	=> intval($iBudget));

$stst->getParams(array_keys($aParams), $tag);

//get parameter values currently stored

//values are taken from the DB and stored in the $stst object internal array

if ($action=="update") {		//if we have to update - do it
	$stst->getParamsIDs(array_keys($aParams));	//get IDs of the parameter to be stored/updated in internal array
	$stst->updateParams($aParams, $tag);	//update parameters in the DB
	$stst->close();	//close database connection
}

Edit the $statUDReports array in ui.cfg.php to define which parameters we want to view in reports:

$statUDReports = array(
	PT_QUOTE	=> array("Q_QTYPE", "Q_EMAIL", "Q_COMPANY")
);	//we want to get reports on 3 PT_QUOTE type parameters

After the above actions, the "QUOTE" menu item will be added to your reports menu and will have the following submenus: "QUOTE TYPE", "E-MAIL" and "COMPANY". I.e. you'll further be able to get standard reports on these parameters: