Estimated Reading Time Plugin : Sharpening the stick (technical tuesday)

(Reading time: 6 – 10 minutes)

Tim Ferriss has a lot to say about blogging. In fact, he can talk for an hour straight about it, as I found out last year at WordCamp 2009 in San Francisco.

I learned about Tim’s strategy, and he gave us a few of his tactics and techniques. One of Tim’s really interesting tactics for treating readers with respect was providing an estimate of how much time it might take them to read an article. For those unacquainted with Tim’s writing, sometimes it’s long, 3000 words or more long.

These days, I’m starting to see a lot more blogs with an estimated reading time displayed. Back last June, a whole year ago, there weren’t very many. There are surely several ways to implement an estimated reading time; being WordPress, there is a plugin.

And so, once again, a Technical Tuesday, where we break down one of Website In A Weekend’s most popular plugins: Estimated Reading Time.

But…

Before we get started, (IMPORTANT →) You Do Not Need To Read The Code To Get The Point.

You do, however, need to scan over the code. Take it in as a “block.” Notice it’s not very long.

The Estimated Reading Time plugin

The Estimated Reading Time plugin is pretty short, just a couple of dozen lines. If this hurts your eyeballs, by all means jump right over the code.

Otherwise, check it out in all it’s PHP glory:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

if (!function_exists('est_read_time')):
function est_read_time( $return = false) {
	$wordcount = round(str_word_count(get_the_content()), -2);
	$minutes_fast = ceil($wordcount / 250);
	$minutes_slow = ceil($wordcount / 150);
 
	if ($wordcount <= 150) {
		$output = __("Reading time: < 1 minute");
	} else {
		$output = sprintf(__("Reading time: %s - %s minutes"), $minutes_fast, $minutes_slow);
	}
	if ($return) {
		return '<p class="estread">' . $output . '</p>';
	} else {
		echo '<p class="estread">' . $output . '</p>';
	}
}
endif;
 
if (!function_exists('est_the_content')):
function est_the_content( $orig ) {
	// Prepend the reading time to the post content
	return est_read_time(true) . "\n\n" . $orig;
}
endif;
 
if (function_exists('add_filter')):
   // Set this to priority 9 so it's called before wptextuarize/wpautop/etc
   add_filter('the_content', 'est_the_content', 9); 
endif;

That’s not bad, 30 lines of pure D elegance.

Just for fun, let’s break it down… (no? Go for the goodies?)

The break down

1
2

if (!function_exists('est_read_time')):
function est_read_time( $return = false) {

Let’s check to see if this function for estimated reading time already exists in WordPress, perhaps in another plugin. If so, skip over it.

If not, do some computation.

3
4
5

	$wordcount = round(str_word_count(get_the_content()), -2);
	$minutes_fast = ceil($wordcount / 250);
	$minutes_slow = ceil($wordcount / 150);

These simple computations are the heart of the plugin, and if you’ve noticed the “2-2″ bug, this computation is where that occurs. Here’s how it works:

1. After counting the words with str_word_count, the PHP round function with argument -2 multiplies the result by 100.
2. Then, dividing by 250 and 150, respectively, gives a range, and the ceil function returns the next highest integer from the division.

Not hard, right?

Let’s figure out what to show the reader:

7
8
9
10
11

	if ($wordcount <= 150) {
		$output = __("Reading time: < 1 minute");
	} else {
		$output = sprintf(__("Reading time: %s - %s minutes"), $minutes_fast, $minutes_slow);
	}

Here’s the other half of the “2-2 minutes” bug. Fixing it won’t be hard, will just take a little time examining how round and ceil work, or kludging in a fix by checking to see if $minutes_fast equals $minutes_slow.

Once we know what we want to display…

12
13
14
15
16
17
18

	if ($return) {
		return '<p class="estread">' . $output . '</p>';
	} else {
		echo '<p class="estread">' . $output . '</p>';
	}
}
endif;

This means that when the function is called from some other part of WordPress, it will return a string to wherever it’s wanted. Else, it prints the estimated reading time string straight to your screen.

Note that “estread” class is added automatically. This CSS currently has to be added manually to your style sheet. (custom.css if you use Thesis) In the near future, the plugin will have it’s own style sheet.

Here’s where we set up for the hook…

12
13
14
15
16
17

if (!function_exists('est_the_content')):
function est_the_content( $orig ) {
	// Prepend the reading time to the post content
	return est_read_time(true) . "\n\n" . $orig;
}
endif;

Calling est_reading_time with true. We want the string back because…

12
13
14
15

if (function_exists('add_filter')):
   // Set this to priority 9 so it's called before wptextuarize/wpautop/etc
   add_filter('the_content', 'est_the_content', 9); 
endif;

…we’re adding the string with the reading time directly to the content.

Easy, right?

“But why,” you might ask, “should I bother myself with these tedious details?”

That’s an excellent question, and you, Website In A Weekend reader, deserve an answer.

Ripping back the (plugin) veil

Long time readers (bofem) recall that I’ve published similar code and plugin breakdowns in the past. Just last week, we tore into the SEO Slugs plugin. A month or two past, we had the world’s shortest plugin.

Stay with me here…

If you think I might demonstrating something (more than just showing off even though I am sort of showing off, at least a little bit), you might be right.

I’m setting the stage for a nice big twist of Blogistan’s collective nose. Remember this old saw “Too many plugins is bad and makes your blog slow.”?

Who says so? Why do they say it? How do they know, who granted their authority and why should I believe what J. Random Blogger says about plugins, loading speed, or any other damn thing about blogging?

More important, why should you believe it?

Rule of thumb: If it didn’t come directly from a WordPress core developer, or plugin author with years of experience, or a professional webmaster, take it with a grain of salt. Maybe a big lump of salt.

Worse yet, even if you get your information straight from the horse’s mouth (so to speak), it may be suspect. I’ll go deeper into “why” in the future.

Let’s wrap this up.

Do you need estimated reading time?

This plugin is pretty small, and it’s not going to put much of a load on your WordPress installation (almost none, really), so using it won’t cost much more than installing it. But before you “just install it,” note that my primary reason for using it is because the length of my articles varies wildly between roughly 1 minute reading time to over 20 minutes reading time.

Further, the topics that I write on vary between highly accessible to highly technical.

Because of this wide range of length and topical difficulty in my blog posts, letting the reader know what’s in store just seems polite. And it works. Readers have commented that having some notion of their commitment ahead of time is very helpful.

Seeing a short post (1 – 2 minutes) may bring a reader in who might otherwise pass. Seeing a long post, a reader might choose to go get a cup of coffee before starting to read (I say this because this is what I’ve been told by a reader in the past.)

Displaying an estimated reading may or may not be useful for you. If you write articles of uniform length, your readers always know what to expect, reading time is superfluous. Likewise, if your articles are fairly well-focused and written in a uniform voice, your articles can be any length, from 100 to 3000 words, and your readers will be there for you regardless of article length.

Also. Remember why I do this stuff: Talent is Overrated, I write to learn, and deliberate practice is the only sure path to mastery.