View source for Extending Site Statistics with your plugin

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 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:

  <table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#DDDDDD" width="67%" id="AutoNumber4" height="91">   <tr>     <td width="34%" height="19"><font size="2">Staticpages 1.2 </font></td>     <td width="66%" height="19"><font size="2">Reports summary and detail</font></td>   </tr>   <tr>     <td width="34%" height="16"><font size="2">FileMgmt v1.2&nbsp;&nbsp; </font>     </td>     <td width="66%" height="16"><font size="2">Reports summary and detail</font></td>   </tr>   <tr>     <td width="34%" height="16"><font size="2">Contact Manager v1.0</font></td>     <td width="66%" height="16"><font size="2">Reports summary only - Total      number of contacts</font></td>   </tr>   <tr>     <td width="34%" height="16"><font size="2">Chatterblock 3.0</font></td>     <td width="66%" height="16"><font size="2">Reports summary only - Total      number of chat records</font></td>   </tr> </table>The following table summarizes the function:

  <div align="center">   <center>   <table cellPadding="2" width="100%" border="1" style="border-collapse: collapse" bordercolor="#111111" cellspacing="0">     <tr>       <th vAlign="top" width="4%">&nbsp;</th>       <th vAlign="top" width="27%">Function</th>       <th vAlign="top" width="99%">Description of Function</th>     </tr>     <tr>       <td class="codeheader" width="4%" align="center">       <font size="2">1</font></td>       <td class="codeheader" width="27%"><font size="2">plugin_showstats_{plugin}</font></td>       <td class="code" vAlign="top" width="99%"><font size="2">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</font></td>     </tr>     </table>   </center> </div>  === 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><font size="2">$showsitestats</font></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.

You may decide to only return a result for one of the stats features.  Chatterblock for example only returns a summary stat result.


=== Plugin database changes ===

There are no required database changes or plugin table requirements for this  API. 

  === Function details and examples ===

   <table border="0" cellpadding="0" cellspacing="10" style="border-collapse: collapse; float: right; position: relative; left: 0" width="62%" id="AutoNumber1" align="right" height="98">     <tr>       <td width="100%" height="98" bgcolor="#DDDDDD" style="border-style: solid; border-width: 1; padding-left: 4; padding-right: 4; padding-top: 1; padding-bottom: 1" bordercolor="#C0C0C0">       <font SIZE="1"><b>       <p style="margin-top: 0; margin-bottom: 4">function</b>        plugin_showstats_filemgmt(</font><font SIZE="1" COLOR="#800000">$showsitestats</font><font size="1">)        {

       <b>       <p style="margin-top: 0; margin-bottom: 4">global</b> </font>       <font SIZE="1" COLOR="#800000">$LANG_FILEMGMT</font><font SIZE="1">,       </font><font SIZE="1" COLOR="#800000">$_FM_TABLES</font><font SIZE="1">,       </font><font SIZE="1" COLOR="#800000">$_CONF</font><font size="1">;

       </font>       <p style="margin-top: 0; margin-bottom: 4"><font SIZE="1" COLOR="#800000">       $stat_templates</font><font SIZE="1"> = <b>new</b> Template(</font><font SIZE="1" COLOR="#800000">$_CONF</font><font SIZE="1">[</font><font COLOR="#0000f0" size="1">'path_layout'</font><font SIZE="1">]        . </font><font SIZE="1" COLOR="#0000f0">'stats'</font><font size="1">);

       </font>       <p style="margin-top: 0; margin-bottom: 4"><font SIZE="1" COLOR="#800000">       $stat_templates</font><font SIZE="1"><b>-&gt;</b>set_file(array(</font><font COLOR="#0000f0" size="1">'itemstats'</font><font SIZE="1">=&gt;</font><font SIZE="1" COLOR="#0000f0">'itemstatistics.thtml'</font><font size="1">,</font><font SIZE="1" COLOR="#0000f0">        'statrow'</font><font SIZE="1">=&gt;</font><font SIZE="1" COLOR="#0000f0">'singlestat.thtml'</font><font size="1">));

       <p style="margin-top: 0; margin-bottom: 4"><b>if</b> (</font><font SIZE="1" COLOR="#800000">$showsitestats</font><font SIZE="1">        == </font><font SIZE="1" COLOR="#ff0000">1</font><font size="1">) {

       </font>       <blockquote>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$total_pages</font><font SIZE="1">=DB_count(</font><font SIZE="1" COLOR="#800000">$_FM_TABLES</font><font SIZE="1">[</font><font COLOR="#0000f0" size="1">'filemgmt_filedetail'</font><font size="1">]);

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$total_downloads</font><font SIZE="1">=DB_getItem(</font><font SIZE="1" COLOR="#800000">$_FM_TABLES</font><font SIZE="1">[</font><font COLOR="#0000f0" size="1">'filemgmt_filedetail'</font><font SIZE="1">],         </font><font SIZE="1" COLOR="#0000f0">'SUM(hits)'</font><font SIZE="1">,</font><font SIZE="1" COLOR="#0000f0">&quot;&quot;</font><font size="1">);

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$retval</font><font SIZE="1">&nbsp; =         </font><font SIZE="1" COLOR="#0000f0">&quot;&lt;table border = '0' width='100%'          cellspacing='0' cellpadding='0'&gt;&quot;</font><font size="1">;

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$retval</font><font SIZE="1"> .= </font>         <font SIZE="1" COLOR="#0000f0">&quot;&lt;tr&gt;&lt;td&gt;&quot;</font><font SIZE="1"> . </font>         <font SIZE="1" COLOR="#800000">$LANG_FILEMGMT</font><font SIZE="1">[</font><font COLOR="#0000f0" size="1">'nofiles'</font><font SIZE="1">]          . </font><font SIZE="1" COLOR="#0000f0">&quot;&lt;/td&gt;&quot;</font><font size="1">;

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$retval</font><font SIZE="1"> .= </font>         <font SIZE="1" COLOR="#0000f0">&quot;&lt;td align='right'&gt;&quot;</font><font SIZE="1">          . </font><font SIZE="1" COLOR="#800000">$total_pages</font><font SIZE="1">          . </font><font SIZE="1" COLOR="#0000f0">&quot; (&quot;</font><font SIZE="1"> .</font><font SIZE="1" COLOR="#800000">$total_downloads</font><font SIZE="1">         </font>

         <p style="margin-top: 0; margin-bottom: 4"><font size="1">&nbsp;&nbsp;&nbsp;&nbsp;          .</font><font SIZE="1" COLOR="#0000f0">&quot;)&amp;nbsp;&amp;nbsp;&amp;nbsp;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&quot;</font><font size="1">;

       </blockquote>       <p style="margin-top: 0; margin-bottom: 4">} <b>else</b> {

       </font>       <blockquote>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$result</font><font SIZE="1"> = DB_query(</font><font COLOR="#0000f0" size="1">&quot;SELECT          lid, title, hits from {</font><font SIZE="1"><b>$_FM_TABLES</b></font><font COLOR="#0000f0" size="1">['filemgmt_filedetail']}          WHERE hits &gt; 0 ORDER BY hits desc LIMIT 10&quot;</font><font size="1">);

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$nrows</font><font SIZE="1"> =          DB_numRows(</font><font SIZE="1" COLOR="#800000">$result</font><font size="1">);

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$retval</font><font SIZE="1"> .=          COM_startBlock(</font><font SIZE="1" COLOR="#800000">$LANG_FILEMGMT</font><font SIZE="1">[</font><font SIZE="1" COLOR="#0000f0">'StatsMsg1'</font><font size="1">]);

         <p style="margin-top: 0; margin-bottom: 4"><b>if</b> (</font><font SIZE="1" COLOR="#800000">$nrows</font><font SIZE="1">          &gt; </font><font SIZE="1" COLOR="#ff0000">0</font><font size="1">) {

         </font>         <blockquote>           <p style="margin-top: 0; margin-bottom: 4">           <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>set_var(</font><font SIZE="1" COLOR="#0000f0">'item_label'</font><font SIZE="1">,</font><font COLOR="#0000f0" size="1">&quot;Page            Title&quot;</font><font size="1">);

           </font>           <p style="margin-top: 0; margin-bottom: 4">           <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>set_var(</font><font SIZE="1" COLOR="#0000f0">'stat_name'</font><font SIZE="1">,</font><font COLOR="#0000f0" size="1">&quot;Hits&quot;</font><font size="1">);

           <p style="margin-top: 0; margin-bottom: 4"><b>for</b> (</font><font SIZE="1" COLOR="#800000">$i</font><font SIZE="1">            = </font><font SIZE="1" COLOR="#ff0000">0</font><font SIZE="1">;           </font><font SIZE="1" COLOR="#800000">$i</font><font SIZE="1"> &lt;           </font><font SIZE="1" COLOR="#800000">$nrows</font><font SIZE="1"> &amp;&amp;           </font><font SIZE="1" COLOR="#800000">$i</font><font SIZE="1"> &lt;           </font><font SIZE="1" COLOR="#ff0000">10</font><font SIZE="1">; </font>           <font SIZE="1" COLOR="#800000">$i</font><font size="1">++) {

           <blockquote>             <p style="margin-top: 0; margin-bottom: 4">list (</font><font SIZE="1" COLOR="#800000">$lid</font><font SIZE="1">,             </font><font SIZE="1" COLOR="#800000">$title</font><font SIZE="1">,</font><font SIZE="1" COLOR="#800000">$hits</font><font SIZE="1">)              = DB_fetchARRAY(</font><font SIZE="1" COLOR="#800000">$result</font><font size="1">);

             </font>             <p style="margin-top: 0; margin-bottom: 4">             <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>set_var(</font><font COLOR="#0000f0" size="1">'item_url'</font><font SIZE="1">,             </font><font SIZE="1" COLOR="#800000">$_CONF</font><font size="1">[site_url].             </font><font SIZE="1" COLOR="#0000f0">&quot;/filemgmt/singlefile.php?lid=&quot;</font><font SIZE="1">.</font><font SIZE="1" COLOR="#800000">$lid</font><font size="1">);

             </font>             <p style="margin-top: 0; margin-bottom: 4">             <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>set_var(</font><font COLOR="#0000f0" size="1">'item_text'</font><font SIZE="1">,             </font><font SIZE="1" COLOR="#800000">$title</font><font size="1">);

             </font>             <p style="margin-top: 0; margin-bottom: 4">             <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>set_var(</font><font COLOR="#0000f0" size="1">'item_stat'</font><font SIZE="1">,             </font><font SIZE="1" COLOR="#800000">$hits</font><font size="1">);

             </font>             <p style="margin-top: 0; margin-bottom: 4">             <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>parse(</font><font SIZE="1" COLOR="#0000f0">'stat_row'</font><font SIZE="1">,</font><font SIZE="1" COLOR="#0000f0">'statrow'</font><font SIZE="1">,</font><font SIZE="1" COLOR="#800000"><b>true</b></font><font size="1">);             

           </blockquote>           <p style="margin-top: 0; margin-bottom: 4">}

           </font>           <p style="margin-top: 0; margin-bottom: 4">           <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>parse(</font><font SIZE="1" COLOR="#0000f0">'output'</font><font SIZE="1">,</font><font COLOR="#0000f0" size="1">'itemstats'</font><font size="1">);

           </font>           <p style="margin-top: 0; margin-bottom: 4">           <font SIZE="1" COLOR="#800000">$retval</font><font SIZE="1"> .= </font>           <font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>finish(</font><font SIZE="1" COLOR="#800000">$stat_templates</font><font SIZE="1"><b>-&gt;</b>get_var(</font><font COLOR="#0000f0" size="1">'output'</font><font size="1">));

         </blockquote>         <p style="margin-top: 0; margin-bottom: 4">} <b>else</b> {

         </font>         <blockquote>           <p style="margin-top: 0; margin-bottom: 4">           <font SIZE="1" COLOR="#800000">$retval</font><font SIZE="1"> .= </font>           <font SIZE="1" COLOR="#800000">$LANG_FILEMGMT</font><font SIZE="1">[</font><font SIZE="1" COLOR="#0000f0">'StatsMsg2'</font><font size="1">];

         </blockquote>         <p style="margin-top: 0; margin-bottom: 4">} 

         </font>         <p style="margin-top: 0; margin-bottom: 4">         <font SIZE="1" COLOR="#800000">$retval</font><font size="1"> .=          COM_endBlock();

       </blockquote>       <p style="margin-top: 0; margin-bottom: 4">}

       <p style="margin-top: 0; margin-bottom: 4"><b>return</b> </font>       <font SIZE="1" COLOR="#800000">$retval</font><font size="1">;

       <p style="margin-top: 0; margin-bottom: 4">}</font></td>     </tr>   </table>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.

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.

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.

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 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.