Stats Function

From GeeklogWiki
Jump to: navigation, search

The way this function works is very specific to how Geeklog shows its statistics. On stats.php, there is the top box which gives overall statistics for Geeklog and then there are blocks below it that give more specific statistics for various components of Geeklog.

This plugin API function suffers from a variety of bugs and bad design decisions for which we have to provide backward compatibility, so please bear with us ...

The only parameter to this function, $showsitestats, was originall documented as being 1 for the site stats and 0 for the plugin-specific stats. However, the latter was always called with a value of 2 (and not 0), so plugins only did a check for 1 and "else", which makes extensions somewhat tricky.

Furthermore, due to the original templates for the site stats, it has become standard practice to hard-code a table in the plugins as the return value for $showsitestats == 1. This table, however, didn't align properly with the built-in site stats entries.

Because of all this, a new mode, 3, was introduced which is used internally by Geeklog to solve this problem:

  • Plugins that provide a new plugin API function, plugin_statssummary_<plugin-name>, will receive a call to that function. It is expected to return the plugin's entry for the site stats in an array which stats.php will then format properly, alongside the entries for the built-in items.
  • Plugins that provide the new plugin_statssummary_<plugin-name> function will not receive a call to plugin_showstats_<plugin-name>(1).
  • Plugins that do not provide the plugin_statssummary_<plugin-name> function will receive a call to plugin_showstats_<plugin-name>(1).
  • Both types of plugins will receive a call to plugin_showstats_<plugin-name>(2) for their plugin-specific stats.

Table 5. Stats functions
Function Description of Function
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).
plugin_statssummary_<plugin-name> When implemented, this function is supposed to return an array(item text, item count) for use in the site-wide statistics block, e.g. array("Forum posts", 42);