glFusion Wiki

Site Tools


glfusion:development:pluginapi:stats

Stats Functions

This section will describe how to enable your plugin to return statistics back to glFusion 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 glFusion 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 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 as you desire. For example, the Static Page plugin and Filemgmt plugin report the top 10 pages and files.

There is just one plugin function that you need for your plugin project to support reporting stats back to glFusion. The example function that is used for explanation in this section and included in this kit should provide enough details. You can also review the following plugins which have this function implemented:

  • Static Pages - Reports summary and detail.
  • FileMgmt - Reports summary and detail.

How to call the Stats Function

You only need to include the completed showstats function in your plugin functions.inc file. Ensure that you use the standard function naming convention. It will automatically be called by the glFusion public_html/stats.php program when the site stats pages is being created. The function has one int paramater $showsitestats 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.

Plugin Database Changes

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

plugin_showstats_<plugin name>

This function takes a showsitestats flag. If set to 1, this function shows the overall stats for your plugin in the site statistics box. If it is set to 2 it shows the statistic blocks for you plugin (similar to Top Ten Viewed Stories and Top Ten Commented Stories).

Arguments

($showsitestats)

Code Example

This example function is from the Filemgmt plugin v1.2 release and is similar to the Static Page search function. It uses the glFusion 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.

If there are no stats for this plugin to report at this time, then return an empty result “”.

The detail level reporting is a bit more involved. For the Filemgmt plugin and the Static Page 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 > 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 item_label, stat_name, item_url, item_text, and item_stat that are being set with the results of each record (in this case the top 10 accessed files). The two templates used are under public_html/layout/nouveau/stats and are itemstatistics.thtml and singlestat.thtml.

The detail stats section is setup to provide an item_url link for each item in the result. This allows the user to immediately access the item from the stats report page. The template item_url variable is set to the plugin program URL to view the item.

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

Page Tools