Difference between revisions of "Extending Site Statistics with your plugin"

Latest revision as of 16:20, 24 May 2009

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.

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

How to call the Stats Function

Please note that this API changed slightly in Geeklog 1.4.0. We will only describe the current implementation here. If you are interested in the details of the old API, see Stats Function.

Both functions should be implemented in your plugin's functions.inc file, as usual. Ensure that you use the standard function naming convention for both. They will automatically be called by the Geeklog stats.php program when the site stats page is being created.

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

Summary Stats

For the summary stats, your statssummary 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 COM_NumberFormat function.

This function will typically be very short. Here's an example, taken from the Static Pages Plugin:

function plugin_statssummary_staticpages()
{
    global $LANG_STATIC;

    $total_pages = SP_countVisiblePages();

    return array($LANG_STATIC['staticpages'], COM_numberFormat($total_pages));
}

Detailed Stats

For the detailed stats list, your showstats function will be called with an int parameter of 2 (for historical reasons - see the note above). In this case, your plugin should return a completely formatted Geeklog block with the contents of your list.

Traditionally, plugins used the template files from the current theme's stats directory for this list. For new plugins, however, we recommend that you use an Admin List instead, e.g. a ADMIN_simpleList. Sample code can again be found in the plugins that ship with Geeklog but is also shown below.

Function details and examples

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 > 0 records. If no records are found, we return a simple message (wrapped between COM_startBlock and COM_endBlock) stating just that.

If there are results, we loop over them, format them, and store the formatted date in an array ($data_array) that is then passed on to an ADMIN_simpleList 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.

The detail stats section is setup to provide a link for each item in the result. This allows the user to immediately access the item from the stats report page.

function plugin_showstats_staticpages($showsitestats)
{
    global $_CONF, $_TABLES, $LANG_STATIC;

    $retval = '';

    $perms = SP_getPerms();
    if (!empty($perms)) {
        $perms = ' AND ' . $perms;
    }
    $result = DB_query("SELECT sp_id,sp_title,sp_hits FROM {$_TABLES['staticpage']} "
            . "WHERE sp_hits > 0" . $perms . ' ORDER BY sp_hits DESC LIMIT 10');
    $nrows  = DB_numRows($result);
    if ($nrows > 0) {
        require_once $_CONF['path_system'] . 'lib-admin.php';

        $header_arr = array(
            array('text'         => $LANG_STATIC['stats_page_title'],
                  'field'        => 'sid',
                  'header_class' => 'stats-header-title'),
            array('text'         => $LANG_STATIC['stats_hits'],
                  'field'        => 'sp_hits',
                  'header_class' => 'stats-header-count',
                  'field_class'  => 'stats-list-count'),
        );
        $data_arr = array();
        $text_arr = array('has_menu' => false,
                          'title'    => $LANG_STATIC['stats_headline']
        );
        for ($i = 0; $i < $nrows; $i++) {
            $A = DB_fetchArray($result);
            $A['sp_title'] = stripslashes($A['sp_title']);
            $A['sid'] = COM_createLink($A['sp_title'],
                            COM_buildUrl($_CONF['site_url']
                                . "/staticpages/index.php?page={$A['sp_id']}"));
            $A['sp_hits'] = COM_NumberFormat($A['sp_hits']);
            $data_arr[$i] = $A;
        }
        $retval .= ADMIN_simpleList("", $header_arr, $text_arr, $data_arr);
    } else {
        $retval .= COM_startBlock($LANG_STATIC['stats_headline']);
        $retval .= $LANG_STATIC['stats_no_hits'];
        $retval .= COM_endBlock();
    }

    return $retval;
}

Please note that most of the code in this function is to prepare the use of the Admin List - only the SQL request and the for loop actually prepare the detailed stats data.