Extending Site Statistics with your plugin - Revision history

Dirk: typos and such

2009-05-24T16:20:48Z

typos and such

Dirk: rewrite for the current Stats API

2009-05-24T15:59:19Z

rewrite for the current Stats API

Show changes

Dirk: Typo

2009-05-24T14:52:51Z

Typo

Dirk: formatting and minor corrections

2009-05-24T14:51:55Z

formatting and minor corrections

Dirk: added link to Plugin API

2009-05-23T19:39:37Z

added link to Plugin API

Dirk: Minor corrections and linkage

2009-05-22T13:35:03Z

Minor corrections and linkage

Dirk: added a link to updated Stats API description

2009-05-18T18:43:42Z

added a link to updated Stats API description

Dirk: fixed formatting of sample code

2009-05-05T08:37:32Z

fixed formatting of sample code

Dirk: Changed category

2008-05-10T20:16:53Z

Changed category

Tomw at 13:59, 1 July 2004

2004-07-01T13:59:07Z

@@ Line 1: / Line 1: @@
-This section will describe and document how to enable your plugin to return  statistics back to Geeklog when the site stats page is requested. There are two main sections to the site stats page. The first is a block at the top of the stats pages used for the site summary. The rest of the stats page is a more detailed report for each Geeklog component. Your plugin can be written to return results for both or just one of these sections.
+This section will describe and document how to enable your plugin to return  statistics back to Geeklog when the site stats page is requested. There are two main sections to the site stats page. The first is a block at the top of the stats page used for the site summary. The rest of the stats page is a more detailed report for each Geeklog component. Your plugin can be written to return results for both or just one of these sections.
 The site statistics summary block at the top may have one line for your plugin as an overall summary counter. This may be the number of contacts in your contact plugin, number of files in your file repository or some other overall counter for your plugin. This will be a straight forward database query to return the count and description.
@@ Line 5: / Line 5: @@
 The detailed stats section allows you to have a block on the stats page for your plugin in which you can report as many lines of detail as you want. For example: the [[Static Pages Plugin]] and [[File Management Plugin]] report, respectively, the top 10 pages and and top 10 files.
-There are two plugin functions that you need for your plugin to support reporting stats back to Geeklog. The example functions that are used for explanation in this section and included in the [[Universal Plugin ToolKit|kit]] should provide enough details. You can also review the plugins that are bundled with Geeklog, most of which have these functions implemented. For example, the [[Static Pages Plugin]] implements both the summary and the detailed list. The [[Spam-X Plugin]] also implements both, but makes the detailed list only available to Admin users.
+There are two plugin functions that you need for your plugin to support reporting stats back to Geeklog. The example functions that are used for explanation in this section should provide enough details. You can also review the plugins that are bundled with Geeklog, most of which have these functions implemented. For example, the [[Static Pages Plugin]] implements both the summary and the detailed list. The [[Spam-X Plugin]] also implements both, but makes the detailed list only available to Admin users.
 The following table summarizes the functions:
@@ Line 34: / Line 34: @@
 === Summary Stats ===
-For the summary stats, your <code>statssummary</code> only needs to return an array where the first item is the label for the summary (to be displayed on the stats page) and the second entry is the number. By convention, your plugin should format the number using the <code>COM_NumberFormat</code> function.
+For the summary stats, your <code>statssummary</code> function only needs to return an array where the first item is the label for the summary (to be displayed on the stats page) and the second entry is the number. By convention, your plugin should format the number using the <code>COM_NumberFormat</code> function.
 This function will typically be very short. Here's an example, taken from the [[Static Pages Plugin]]:
@@ Line 60: / Line 60: @@
 The detail level reporting is a bit more involved. For the [[File Management Plugin]] and the [[Static Pages Plugin]] as well, the detail reporting is for the top 10 accessed records. You may need to add logic to your plugin if it does not  already have the required data that you want to report on.
-In most cases, you will have the data in the plugin records. In this example, the SQL statement does most of the work, returning the top 10 accessed records. The logic then checks for a search result &gt; 0 records. If no records are found, we return a simple message (wrapped between <code>COM_startBlock</code> and <code>COM_endBlock</code> stating that.
+In most cases, you will have the data in the plugin records. In this example, the SQL statement does most of the work, returning the top 10 accessed records. The logic then checks for a search result &gt; 0 records. If no records are found, we return a simple message (wrapped between <code>COM_startBlock</code> and <code>COM_endBlock</code>) stating just that.
 If there are results, we loop over them, format them, and store the formatted date in an array (<code>$data_array</code>) that is then passed on to an <code>ADMIN_simpleList</code> which formats it for display on the stats page. Doing it this way ensures a consistent display of all detailed lists on the stats page without the need of having to deal with templates.

@@ Line 3: / Line 3: @@
 The site statistics summary block at the top may have one line for your plugin as an overall summary counter. This may be the number of contacts in your contact plugin, number of files in your file repository or some other overall counter for your plugin. This will be a straight forward database query to return the count and description.
-The detailed stats section allows you to have a block on the stats page for your plugin in which you can report as many lines of detail as you want. For example: the [[Static Pages Plugin] and [[File Management Plugin]] report, respectively, the top 10 pages and and top 10 files.
+The detailed stats section allows you to have a block on the stats page for your plugin in which you can report as many lines of detail as you want. For example: the [[Static Pages Plugin]] and [[File Management Plugin]] report, respectively, the top 10 pages and and top 10 files.
 There is just one plugin function (actually, there are [[Stats Function|two]]) that you need for your plugin to support reporting stats back to Geeklog. The example function that is used for explanation in this section and included in the [[Universal Plugin ToolKit|kit]] should provide enough details. You can also  review the following plugins which have this function implemented:

@@ Line 1: / Line 1: @@
-This section will describe and document how to enable your plugin to return  statistics back to  Geeklog when the site stats page is requested. There are two main sections to  the site stats page. The first is a block at the top of the stats pages used for  the site summary. The rest of the stats page is a more detailed report for each  Geeklog component. Your plugin can be written to return results for both or just  one of these sections.
+This section will describe and document how to enable your plugin to return  statistics back to Geeklog when the site stats page is requested. There are two main sections to the site stats page. The first is a block at the top of the stats pages used for the site summary. The rest of the stats page is a more detailed report for each Geeklog component. Your plugin can be written to return results for both or just one of these sections.
-The site statistics summary block at the top may have one line for  your plugin as an overall summary counter. This may be the number of contacts in  your contact plugin, number of files in your FileMgmt or some other overall  event counter for your plugin. This will be a straight forward database query to  return the count and description.
+The site statistics summary block at the top may have one line for your plugin as an overall summary counter. This may be the number of contacts in your contact plugin, number of files in your file repository or some other overall counter for your plugin. This will be a straight forward database query to return the count and description.
-The detail stats section allows you to have a block on the stats page for  your plugin in which you can report as many lines of detail you want. For example: the  staticpage plugin and filemgmt plugin report respectfully, the top 10 pages and  files.
+The detailed stats section allows you to have a block on the stats page for your plugin in which you can report as many lines of detail as you want. For example: the [[Static Pages Plugin] and [[File Management Plugin]] report, respectively, the top 10 pages and and top 10 files.
-There is just one plugin function (actually, there are [[Stats Function|two]]) that you need for your plugin project to  support reporting stats back to Geeklog. The example function that is used for explanation in this  section and included in this kit should be provide enough details. You can also  review the following plugins which have this function implemented:
+There is just one plugin function (actually, there are [[Stats Function|two]]) that you need for your plugin to support reporting stats back to Geeklog. The example function that is used for explanation in this section and included in the [[Universal Plugin ToolKit|kit]] should provide enough details. You can also  review the following plugins which have this function implemented:
-<table border="1" cellpadding="3" cellspacing="0"><tr>
+<table border="1" cellpadding="3" cellspacing="0">
-<td width="34%">Staticpages 1.2</td><td>Reports summary and detail</td></tr>
+<tr><td width="34%">[[Calendar Plugin]]</td><td>Reports summary and detail</td></tr>
-<tr><td width="34%">FileMgmt v1.2</td><td>Reports summary and detail</td></tr>
+<tr><td width="34%">[[Links Plugin]]</td><td>Reports summary and detail</td></tr>
 <tr><td width="34%">Contact Manager v1.0</td><td>Reports summary only - Total number of contacts</td></tr>
-<tr><td width="34%">Chatterblock 3.0</td><td>Reports summary only - Total      number of chat records</td></tr></table>
+<tr><td width="34%">[[Chatterblock Plugin]]</td><td>Reports summary only - Total      number of chat records</td></tr></table>
 The following table summarizes the function:
@@ Line 23: / Line 27: @@
 === How to call the Stats Function ===
-You only need to include the completed <i>showstats</i> function in your  plugin functions.inc file. Ensure that you.use the standard function naming  convention. It will automatically be called by the Geeklog stats.php program when  the site stats pages is being created. The function has one <i>int </i>paramater <b>$showsitestats</b> which is either = 1 for summary or =  2 for detail.
+You only need to include the completed <i>showstats</i> function in your plugin <tt>functions.inc</tt> file. Ensure that you use the standard function naming  convention. It will automatically be called by the Geeklog <tt>stats.php</tt> program when the site stats pages is being created. The function has one <i>int </i> parameter <b>$showsitestats</b> which is either = 1 for summary or = 2 for detail.
 The [[Plugin API]] call <code>PLG_getPluginStats()</code> is called twice in <tt>stats.php</tt> and with each call, all the enabled plugins will return their statistics which are then formatted into the final page.
@@ Line 32: / Line 36: @@
 === Plugin database changes ===
-There are no required database changes or plugin table requirements for this  API.
+There are no required database changes or plugin table requirements for this API.
 === Function details and examples ===
-This example function is from the [[File Management Plugin]] 1.2 release. It uses the Geeklog template class to return  the properly formatted output to stats.php.
+This example function is from the [[File Management Plugin]] 1.2 release. It uses the Geeklog template class to return the properly formatted output to <tt>stats.php</tt>.
 If the passed int parameter is (1) then it returns a summary level metric. In  this case and in most plugins, this would be the total number of main records in  your plugin. You should use language variables for all displayed text.
@@ Line 42: / Line 46: @@
 If there are no stats for this plugin at this time to report - then return an  empty result &quot;&quot;.
-The detail level reporting is a bit more involved. For the filemgmt plugin  and the staticpage plugin as well, the detail reporting is for the top 10  accessed records. You may need to add logic to your plugin if it does not  already have the required data that you want to report on.
+The detail level reporting is a bit more involved. For the [[File Management Plugin]] and the [[Static Pages Plugin]] as well, the detail reporting is for the top 10 accessed records. You may need to add logic to your plugin if it does not  already have the required data that you want to report on.
-In most cases, you will have the data in the plugin records. In this example,  the SQL statement does most of the work, returning the top 10 accessed records.  The logic then checks for a search result &gt; 0 records and executes a loop to  format each line for the final returned output.
+In most cases, you will have the data in the plugin records. In this example, the SQL statement does most of the work, returning the top 10 accessed records. The logic then checks for a search result &gt; 0 records and executes a loop to  format each line for the final returned output.
-The stats template has a number of defined variables like <i>item_label,  stat_name, item_url, item_text, item_stat</i> that are being set with the  results of each record - in this case the top 10 accessed files. The two  templates used are under &lt;theme_dir&gt;/stats and are itemstatistics.thtml and  singlestat.thtml.
+The stats template has a number of defined variables like <i>item_label,  stat_name, item_url, item_text, item_stat</i> that are being set with the results of each record - in this case the top 10 accessed files. The two templates used are under &lt;theme_dir&gt;/stats and are <tt>itemstatistics.thtml</tt> and  <tt>singlestat.thtml</tt>.
-The detail stats section is setup to provide a link <i>item_url</i> for each  item in the result. This allows the user to immediately access the item from the  stats report page. The template <i>item_url</i> variable is set to the plugin  program URL to view the item.
+The detail stats section is setup to provide a link <i>item_url</i> for each item in the result. This allows the user to immediately access the item from the stats report page. The template <i>item_url</i> variable is set to the plugin program URL to view the item.
 <pre>

@@ Line 25: / Line 25: @@
 You only need to include the completed <i>showstats</i> function in your  plugin functions.inc file. Ensure that you.use the standard function naming  convention. It will automatically be called by the Geeklog stats.php program when  the site stats pages is being created. The function has one <i>int </i>paramater <b>$showsitestats</b> which is either = 1 for summary or =  2 for detail.
-The Plugin API call PLG_getPluginStats() is called twice in stats.php and  with each call, all the enabled plugins will return their statistics which are  then formatted into the final page.
+The [[Plugin API]] call <code>PLG_getPluginStats()</code> is called twice in <tt>stats.php</tt> and with each call, all the enabled plugins will return their statistics which are then formatted into the final page.
 You may decide to only return a result for one of the stats features.  [[Chatterblock Plugin|Chatterblock]] for example only returns a summary stat result.

@@ Line 5: / Line 5: @@
 The detail stats section allows you to have a block on the stats page for  your plugin in which you can report as many lines of detail you want. For example: the  staticpage plugin and filemgmt plugin report respectfully, the top 10 pages and  files.
-There is just one (1) plugin function that you need for your plugin project to  support reporting stats back to Geeklog. The example function that is used for explanation in this  section and included in this kit should be provide enough details. You can also  review the following plugins which have this function implemented:
+There is just one plugin function (actually, there are [[Stats Function|two]]) that you need for your plugin project to  support reporting stats back to Geeklog. The example function that is used for explanation in this  section and included in this kit should be provide enough details. You can also  review the following plugins which have this function implemented:
 <table border="1" cellpadding="3" cellspacing="0"><tr>
@@ Line 19: / Line 19: @@
 <th>Description of Function</th></tr>
 <tr><td width="4%" align="center">1</td><td width="27%">plugin_showstats_{plugin}</td><td>This function expands the site stats reporting and is called with a parameter to indicate to get the plugin summary or detail stats. You can return a blank ' ' if there is nothing to report</td></tr></table>
 === How to call the Stats Function ===
@@ Line 26: / Line 27: @@
 The Plugin API call PLG_getPluginStats() is called twice in stats.php and  with each call, all the enabled plugins will return their statistics which are  then formatted into the final page.
-You may decide to only return a result for one of the stats features.  Chatterblock for example only returns a summary stat result.
+You may decide to only return a result for one of the stats features.  [[Chatterblock Plugin|Chatterblock]] for example only returns a summary stat result.
@@ Line 35: / Line 36: @@
 === Function details and examples ===
-This example function is from the filemgmt plugin 1.2 release and is similar  to the staticpage search function. It uses the Geeklog template class to return  the properly formatted&nbsp; output to stats.php.
+This example function is from the [[File Management Plugin]] 1.2 release. It uses the Geeklog template class to return  the properly formatted output to stats.php.
 If the passed int parameter is (1) then it returns a summary level metric. In  this case and in most plugins, this would be the total number of main records in  your plugin. You should use language variables for all displayed text.

@@ Line 88: / Line 88: @@
+}
 </pre>
 [[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

@@ Line 50: / Line 50: @@
 <pre>
-function plugin_showstats_filemgmt($showsitestats) {
+function plugin_showstats_filemgmt($showsitestats)
-global $LANG_FILEMGMT, $_FM_TABLES, $_CONF;
-$stat_templates = new Template($_CONF['path_layout'] . 'stats');
+    global $_CONF, $LANG_FILEMGMT, $_FM_TABLES;
 $stat_templates->set_file(array('itemstats'=>'itemstatistics.thtml', 'statrow'=>'singlestat.thtml'));
-if ($showsitestats == 1) {
+    $retval = '';
-$total_pages=DB_count($_FM_TABLES['filemgmt_filedetail']);
+    $stat_templates = new Template($_CONF['path_layout'] . 'stats');
-$total_downloads=DB_getItem($_FM_TABLES['filemgmt_filedetail'], 'SUM(hits)',"");
+    $stat_templates->set_file(array('itemstats'=>'itemstatistics.thtml', 'statrow'=>'singlestat.thtml'));
-$retval  = "<table border = '0' width='100%' cellspacing='0' cellpadding='0'>";
+    if ($showsitestats == 1) {
-$retval .= "<tr><td>" . $LANG_FILEMGMT['nofiles'] . "</td>";
+        $total_pages=DB_count($_FM_TABLES['filemgmt_filedetail']);
-$retval .= "<td align='right'>" . $total_pages . " (" .$total_downloads .")
+        $total_downloads=DB_getItem($_FM_TABLES['filemgmt_filedetail'], 'SUM(hits)',"");
-} else {
+        $retval  = "<table border = '0' width='100%' cellspacing='0' cellpadding='0'>";
-$result = DB_query("SELECT lid, title, hits from {$_FM_TABLES['filemgmt_filedetail']} WHERE hits > 0 ORDER BY hits desc LIMIT 10");
+        $retval .= "<tr><td>" . $LANG_FILEMGMT['nofiles'] . "</td>";
-$nrows = DB_numRows($result);
+        $retval .= "<td align='right'>" . $total_pages . " (" .$total_downloads .")
-$retval .= COM_startBlock($LANG_FILEMGMT['StatsMsg1']);
+    } else {
-if ($nrows > 0) {
+        $result = DB_query("SELECT lid, title, hits FROM {$_FM_TABLES['filemgmt_filedetail']} WHERE hits > 0 ORDER BY hits desc LIMIT 10");
-$stat_templates->set_var('item_label',"Page Title");
+        $nrows = DB_numRows($result);
-$stat_templates->set_var('stat_name',"Hits");
+        $retval .= COM_startBlock($LANG_FILEMGMT['StatsMsg1']);
-for ($i = 0; $i < $nrows && $i < 10; $i++) {
+        if ($nrows > 0) {
-list ($lid, $title,$hits) = DB_fetchARRAY($result);
+            $stat_templates->set_var('item_label',"Page Title");
-$stat_templates->set_var('item_url', $_CONF[site_url]. "/filemgmt/singlefile.php?lid=".$lid);
+            $stat_templates->set_var('stat_name',"Hits");
-$stat_templates->set_var('item_text', $title);
+            for ($i = 0; $i < $nrows && $i < 10; $i++) {
-$stat_templates->set_var('item_stat', $hits);
+                list ($lid, $title,$hits) = DB_fetchARRAY($result);
-$stat_templates->parse('stat_row','statrow',true);
+                $stat_templates->set_var('item_url', $_CONF[site_url]. "/filemgmt/singlefile.php?lid=".$lid);
+                $stat_templates->set_var('item_text', $title);
-$stat_templates->parse('output','itemstats');
+                $stat_templates->set_var('item_stat', $hits);
-$retval .= $stat_templates->finish($stat_templates->get_var('output'));
+                $stat_templates->parse('stat_row','statrow',true);
 } else {
-$retval .= $LANG_FILEMGMT['StatsMsg2'];
+            $stat_templates->parse('output','itemstats');
+            $retval .= $stat_templates->finish($stat_templates->get_var('output'));
-$retval .= COM_endBlock();
+        } else {
+            $retval .= $LANG_FILEMGMT['StatsMsg2'];
 return $retval;
+}
 </pre>
 [[Category:Plugin Development]]

← Older revision		Revision as of 20:16, 10 May 2008
Line 85:		Line 85:
	</pre>		</pre>

−	[[Category:~~Plugin_Developers_Handbook~~]]	+	[[Category:Plugin Development]]

← Older revision		Revision as of 13:59, 1 July 2004
Line 84:		Line 84:
	}		}
	</pre>		</pre>
		+
		+	[[Category:Plugin_Developers_Handbook]]