Blog Stats Extension Docs

Blog Stats is an extension that can be used to place entry, comment, and trackback statistics throughout your PivotX blog. It can be used to count all entries, comments, and trackbacks across all categories in your PivotX or across selected categories (or by omitting select categories), and show the counts per category. It is based off of the PivotLog extension Total Posts by Bram Nijmeijer (formerly known as Tenshi).

Usage

Setup and Configuration

Setup is as simple as putting a checkmark next to Blog Stats under the Extensions tab of your PivotX control panel.

Snippet Syntax (since version 1.4)

The minimal usage is:

[[ blogstats cat_format="some html" ]]

[[ blogstats user_format="some html" ]]

"Some html" would be replaced by a line of html depicting how the ouput is to be formated. See below for more details.

The snippet takes two required parameters—cat_format or user_format—but only one is required at a time. If either of these parameters is not set, there will be no output. Both of these parameters can be used at the same time.

• cat_format - html format for the output, counting entries and comments in categories. The cat_format line is repeated for each category that is included (via cat_include), not ignored (via cat_ignore), or every non-hidden category (if cat_include and cat_ignore are not used). In cat_format, the following items are parsed:
  • %category% - display name of the category.
  • %cat-link% - simply a link to the category (snippet does not build the anchor tag).
  • %entries% - number of entries in the category.
  • %comments% - number of comments in the category.
  • %trackbacks% - number of trackbacks in the category.
  • %isactive% - snippet of html code inserted for a category that is active.
  cat_format is not required if totalonly is turned on.
• user_format - html format for the output, counting entries (and comments in those entries) per user. The user_format line is repeated for each user that is included (via user_include), not ignored (via user_ignore), or every user (if user_include and user_ignore are not used). In user_format, the following items are parsed:
  • %user% - display name of the user.
  • %user-link% - simply a link to the user's entries (snippet does NOT the anchor tag).
  • %entries% - number of entries authored by user.
  • %comments% - number of comments in the entries authored by user.
  • %trackbacks% - number of trackbacks in the entries authored by user.
  cat_format and user_format are not required if totalonly is turned on.

Additionally, the snippet takes nine optional parameters:

• prefix / postfix - html format for the first / last line(s) of the output. The format can display the total number of entries and comments, either for the specified categories/users or across all categories/users (depending on the setting of fulltotal). In the format, the following items are parsed:
  • %entries% - sum total number of entries in the specified categories or across all categories (depending on the setting of fulltotal).
  • %comments% - sum total number of comments in the specified categories or across all categories (depending on the setting of fulltotal).
  • %trackbacks% - sum total number of trackbacks in the specified categories or across all categories (depending on the setting of fulltotal).
• cat_prefix / cat_postfix - html format for the first / last line(s) of the output specifically for category output (before / after cat_format).
• cat_include - comma separated list of categories to be included in the stats gathering. Use the PivotX internal category names, not the display names. If you use cat_include, the order in which you list the categories is the order in which they will be displayed in the output, unless you specify an order using sort.
• cat_ignore - comma separated list of categories to be ignored in the stats gathering. It may be easier to list a couple of categories to ignore than several categories to include. The order of the displayed categories is determined by the parameter sort (defaulted to pivotx).
  • NOTE: hidden categories are automatically ignored.
  • NOTE: cat_ignore overrides cat_include.
• user_prefix / user_postfix - html format for the first / last line(s) of the output specifically for user output (before / after user_format).
• user_include - comma separated list of users to be included in the stats gathering. Use the PivotX internal user names, not the display names. If you use user_include, the order in which you list the categories is the order in which they will be displayed in the output.
• user_ignore - comma separated list of users to be ignored in the stats gathering. It may be easier to list a couple of users to ignore than several users to include. The order of the displayed users is determined by the order in which they are encountered internally by the extension.
  • NOTE: if a user has no entries in the included categories (cat_include), the non-ignored categories (cat_ignore), or the non-hidden categories, there will be no data output for them.
  • NOTE: user_ignore overrides user_include.
• year - limits the counting of entries and comments to the specified year (use four-digit year).
• month - further limits the counting of entries and comments to the specified month (use two-digit month; e.g., 02 = February).
  • NOTE: the parameter year is required for use with month.
• sort - order in which you would like the list of categories displayed. These are the choices:
  • pivotx or pivotx-rev - ordered as found in the PivotX configuration, either the same or in reverse.
  • alpha-asc or alpha-desc - ordered alphabetically by name, either ascending or descending.
  • entries-asc or entries-desc - ordered according to the number of entries each category has, either ascending or descending.
  • comments-asc or comments-desc - ordered according to the number of comments each category has, either ascending or descending.
  • tracks-asc or tracks-desc - ordered according to the number of trackbacks each category has, either ascending or descending.
  The default ordering method is pivotx, unless the parameter include is used. If the parameter include is used, the display order can still be specified using sort.
• fulltotal - determines whether or not the total number of entries and/or comments across all categories will be displayed regardless of the categories included or ignored. The default is not to use fulltotal. fulltotal=1 turns it on.
• totalonly - if you only want to display the total number of entries and/or comments, turn this on. cat_format and user_format are no longer required with this parameter on, but either prefix or postfix are. The default is not to use totalonly. totalonly=1 turns it on.
• usersfirst - if you display information for both categories and users, by default, the output for categories is displayed first. If you want the output for users displayed first, turn this parameter on. usersfirst=1 turns it on.

Example

Here is an example:

[[ blogstats
        prefix="Total Entries: <b>%entries%</b> || Total Comments: <b>%comments%</b><br />"
        cat_prefix="<br />Entries and Comments Per Category:<br />"
        cat_format='Entries in <a href="%cat-link%">%category%</a>: <b>%entries%</b> | Comments: <b>%comments%</b><br />'
	cat_include="my-ramblings, ubuntu, links"
        user_prefix="<br />Entries and Comments Per User:<br />"
        user_format='Entries by <a href="%user-link%">%user%</a>: <b>%entries%</b> | Comments: <b>%comments%</b><br />'
        user_include="geoffrey, andrew"
        sort="pivotx"
        fulltotal=1
]]

The example's output would look something like:

For more information, update notices, changelogs, etc., visit http://pivotx.mobius-design.net/?p=blog-stats.