[innerindex]The first thing we all have to agree on is that bsuite is the replacement for bstat. The name change reflects that fact that the plugin is doing a lot more than simply track page loads. The most exciting new feature is a module I can’t help but call bsuggestive. It uses the tags of the current post to suggest related posts to your readers. And when readers arrive at your site via a search engine, it not only highlights the search words they used, but offers a list of other posts matching their search criteria.
Why “b2″? I released b1 privately a while ago, and I’ve been running it here at MaisonBisson since September.
bsuite Features
- Tracks page loads (hits)
- Tracks search terms used by visitors ariving at your site via search engines
- Reports top-performing stories via a function that can be included in the sidebar
- Reports recent comments via a function that can be included in the sidebar
- Reports top search terms via a function that can be included in the sidebar
- Outputs a “pulse” graph of activity on your site or specific stories
- Highlights search words used by visitors ariving at your site via search engines NEW!
- Lists related posts at the bottom of the current post’s content NEW!
- Suggests posts that closely match the search criteria for visitors who arrive via search engines NEW!
- Integrates bsuite_speedcache NEW!
- Does some stuff with tags NEW!
Changes
This documentation supersedes any previous documentation.
I need to be honest, it’s been too long since the last public release for me to remember all the details. I haven’t really been keeping records on all this, so if you’ve been running the previous version and you discover a problem, please tell me about it.
The first change is that the plugin is now in a file named “bsuite.php”. As you install it you’ll need to deactivate the previous “bstat.php” version to avoid conflicts.
Another big change is that bsuite will now start tracking page loads as soon as it’s activated. You no longer need to put any code in your theme. But if you’re upgrading from a version where you already have that code in your theme, it also includes code to prevent it from double-counting any page loads.
The other functions from bstat b4 are all there, and I don’t believe there are any changes to the way they’re called.
The options submenu is almost entirely redesigned. It should be pretty self explanatory, but there’s documentation below.
Installation
Update: bugfix release b2v7 available.
- Download and unzip bsuite.zip
- Place bsuite.php in you wp-content/plugins directory
- Place spacer.gif in your wp-content directory
- Log in to your WordPress admin panel and activate the plugin, then visit the new bsuite submenu of the options tab. This will allow bsuite to create its database tables.
Stats collection will start automatically; you can see the results in the new bsuite Reports submenu of your Dashboard
- Once installed, be sure to enable the options and consider customizing the look by adding the bsuite CSS to your theme’s CSS (sample CSS here).
In order to view the stats reports reports on your public pages, you’ll need to add the display functions to your pages.
Upgrading
If you’re upgrading from bstat, be sure to delete or deactivate the old plugin before activating the new one. And don’t forget to visit the bsuite submenu of the options tab so that it can create its new db tables.
Options
The bstat submenu of the options tab has three configurable settings:
- Minimum userlevel to view bsuite reports
The options are restricted to users at userlevel 8 or above, but you can choose who can view the reports.
- Output default CSS
Some of the bsuite functions require CSS styles not found in the average style sheet. This will output default styles.
- Default pulse graph style
This sets how values are interpolated in drawing the pulse graph. Experiment with the options to see how they work.
- Suggest related entries in post
This will insert a block of links at the tail of each (tagged) post’s content with links to related posts at your site.
- Highlight search words and offer search help
The first part of this should be obvious, but the real trick here is using those search words to offer other related content from your site to visitors. It works (and looks) a lot like the option above, but the suggestions only appear when search words are detected.
- Filter incoming search terms using comment moderation and blacklist words.
Referrer spam is as much of a problem as trackback spam. There are a few tricks in bstat to prevent the problem, but here’s one you can configure. Selecting this option tells bstat to not display search terms that contain words in your moderation list or blacklist.
- Ignore hits from registered users at or above userlevel
No author wants to skew their stats just by poking around their own site.
- Ignore hits from these IP numbers.
Sites with low traffic may find that activity by authors severely skews the stats tracking. Enter an IP address here to ignore it.
Tag Support
Until WordPress adopts a standardized way to manage tags, we’ll have to deal with things like this.
bsuite recognizes tags in three forms:
- Any link with a rel=”tag” attribute
- Any number of single tags like this: <tag>tag name</tag>
- A block of comma-delimited tags like this: <tags>WordPress, WordPress Plugin</tags>
This appears to make it compatible with a number of existing tag management strategies now in use — including those used by Ecto and SimpleTags.
Tags in <tag> and <tags> tags are mapped to Technorati, but a future version will include an option to set other tag resolvers.
Using bsuite Functions
Though many bsuite features require no coding or modifications to theme files, there are a number of public functions available to display lists of top stories, recently commented stories, recent comments, recent incoming search terms, etc. Most of these functions take similar arguments and output their results in similar ways.
Today’s Stats
- bstat_todaypop
displays top stories for today only.
- bstat_todayrefs
displays top incoming search terms for today only.
The functions bstat_todaypop and bstat_todayrefs each take the same arguments.
Usage:
bstat_todaypop({count}, "{before}", "{after}");
count is the total number of results to output
before is a string to output before each result
after is a string to output after each result
Example:
<h2>Today's Most Popular</h2> <ul><?php bstat_todaypop(15, "<li>", "</li>\n"); ?></ul>
Recent Stats
- bstat_recentpop
displays top stories for the past x days. This function reveals more useful data on sites with low traffic, but is somewhat slower than bstat_todaypop.
- bstat_recentrefs
displays top incoming search terms for the past x days. This function reveals more useful data on sites with low traffic, but is somewhat slower than bstat_todayrefs.
The functions bstat_recentpop and bstat_recentrefs each take the same arguments.
Usage:
bstat_recentrefs({count}, "{days}", "{before}", "{after}");
count is the total number of results to output
days is the number of days back to look
before is a string to output before each result
after is a string to output after each result
Example:
<h2>Incoming Search Terms This Week</h2> <ul><?php bstat_recentrefs(15, 7, "<li>", "</li>\n"); ?></ul>
Recent Discussion
- bstat_discussionbypost
displays recently commented posts. Each post will appear only once.
- bstat_discussionbycomment
displays recent comments (and commenter). Better on sites with lots of community interaction.
The functions bstat_discussionbypost and bstat_discussionbycomment each take the same arguments.
Usage:
bstat_discussionbypost({count}, "{before}", "{after}");
count is the total number of results to output
before is a string to output before each result
after is a string to output after each result
Example:
<h2>Incoming Search Terms This Week</h2> <ul><?php bstat_discussionbypost(15, "<li>", "</li>\n"); ?></ul>
Special Functions
- bstat_pulse
displays the "pulse" graph of hits over time.
Usage:
bstat_pulse([{post_id}, [{max_width}, [{display_text}, [{display_credit}, [{graph_accurate}]]]]]);
post_id is the post_id for the story, usually provided by a WP variable
max_width is the maximum width the graph maw run
display_text (acceptable values: 0 or 1), switch to display stats for total views and average views per day
display_credit (acceptable values: 0 or 1), switch to display “powered by bstat” credit
graph_accurate (acceptable values: 0 or 1), make smooth, accurate graphs or fuzzy (but not inaccurate) graphs
Example:
<h3>Story pulse</h3><?php bstat_pulse($id, 525, 1, 1, 1); ?>
- bstat_hitit
The hamster on a wheel that makes it all work. It records hits for each page load, and hits for each incoming search term.
This function is no longer necessary, as it is executed automatically via a plugin hook that runs every time the footer is called. Still, it’s around if you have content that you want to track outside that scope.
Example:
<?php // this is how it used to work, but it's automated now...
global $id;
if (!is_single() && !is_page()) $id = 0;
bstat_hitit($id, "read");
?>
note: (be careful of any "curly quotes" that might have been accidentally/automagically inserted in code samples)
Known Bugs
The search word highlighting routine seems to still be buggy. Expect it to mis-recognize referrers, and one tester reported that it caused content not to display. Go ahead and enable it to see how cool it will be in b3, when it works, but I suggest disabling it for the moment.
Ryan Eby reminded me that I use a whole bunch of short PHP open tags (“<?” where I should have used “<?php”).
Zach pointed out that I’ve been sort of sloppy about using double-quotes where I should use single quotes and not single-quoting my array indices. All of this can add up to an unnecessary performance hit for high traffic sites (30,000 + daily page loads).