Difference between revisions of "Stats Function"
From GeeklogWiki
m (Fixed formatting) |
(Updated to explain the "new" stats handling (as of 1.4.0)) |
||
| Line 1: | Line 1: | ||
| − | + | The way this function works is very specific to how Geeklog shows its statistics. On <tt>stats.php</tt>, 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, <code>$showsitestats</code>, 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 "<code>else</code>", which makes extensions somewhat tricky. | ||
| + | |||
| + | Furthermore, due to the original templates for the site stats, it has become standard practice to hard-code a <code>table</code> in the plugins as the return value for <code>$showsitestats == 1</code>. 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, <code>plugin_statssummary_<plugin-name></code>, will receive a call to that function. It is expected to return the plugin's entry for the site stats in an array which <tt>stats.php</tt> will then format properly, alongside the entries for the built-in items. | ||
| + | * Plugins that provide the new <code>plugin_statssummary_<plugin-name></code> function will '''not''' receive a call to <code>plugin_showstats_<plugin-name>(1)</code>. | ||
| + | * Plugins that do '''not''' provide the <code>plugin_statssummary_<plugin-name></code> function '''will''' receive a call to <code>plugin_showstats_<plugin-name>(1)</code>. | ||
| + | * Both types of plugins will receive a call to <code>plugin_showstats_<plugin-name>(2)</code> for their plugin-specific stats. | ||
| + | |||
<table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center"> | <table cellpadding="2" cellspacing="2" border="1" width="90%" align="Center"> | ||
| − | <caption align="bottom">Table 5. Stats | + | <caption align="bottom">Table 5. Stats functions</caption> |
<tr> | <tr> | ||
<th valign="top">Function</th> | <th valign="top">Function</th> | ||
| Line 11: | Line 24: | ||
<td valign="top" class="codeheader">plugin_showstats_<plugin | <td valign="top" class="codeheader">plugin_showstats_<plugin | ||
name></td> | name></td> | ||
| − | <td valign="top" class="code">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 | + | <td valign="top" class="code">This function takes a <code>$showsitestats</code> 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).</td> | Top Ten Commented Stories).</td> | ||
| + | </tr> | ||
| + | <tr> | ||
| + | <td valign="top" class="codeheader">plugin_statssummary_<plugin-name></td> | ||
| + | <td valign="top" class="code">When implemented, this function is supposed to return an <code>array(item text, item count)</code> for use in the site-wide statistics block, e.g. <code>array("Forum posts", 42);</code></td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
Latest revision as of 18:41, 18 May 2009
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 toplugin_showstats_<plugin-name>(1). - Plugins that do not provide the
plugin_statssummary_<plugin-name>function will receive a call toplugin_showstats_<plugin-name>(1). - Both types of plugins will receive a call to
plugin_showstats_<plugin-name>(2)for their plugin-specific stats.
| 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); |
