My inc.functions.php – Part 3 : Nicer Summaries with reworkSummary()

Imagine you have a site that has a sidebar containing auto-generated summaries of (news)items, as seen on Jonathan Snook’s blog for example

(I could have referred to some other sites, yet Jonathan’s blog is perfect to highlight the why of this function)

If you take a closer look at the summaries you’ll see that they all are cut at about the 200th character:

I had a few things I wanted to mention and separate posts about each didn’t seem warranted so here it is: 3 days left! The SXSW 2007 Interactive Pass Contest was off to a strong start with a bunch …

Above that the summary is a flat version of the actual post: in the full news/blogpost of the item quoted above you’ll see that 3 days left! is a heading for example.

Before getting to reworkSummary(), a function to create a summary is needed. This is actually plain simple:

• Enforce the string to be HTML (thus the opposite of htmlentities())
• Strip out the HTML (that’s why the string had to be enforced to be HTML)
• Cut at the 200th character

The order of these steps are important, since otherwise one would be able to cut right in between an xhtml tag…

The PHP code for this is even more easy.

// All your code are belong to bram.us
	function makeSummary($text, $length, $hellip = "…") {

		// enforce html text (maybe it was encoded somewhere)
		$htmlText	= html_entity_decode($text);

		// strip out the tags
		$flatText	= strip_tags($htmlText);

		// text is not longer than length, return flatText
		if (strlen($flatText) <= $length) {
			return $flatText;
		// text is longer than length, create the summary and add hellips
		} else {
			$summary	= substr($flatText, 0, $length);
			return $summary.$hellip;
		}
	}

With the addition of the horizontal ellipsis at the end (to indicate that there's more to read) we're done, right?

Wrong! In the example quote way at the top, you'll see that the summary was cut just after a word, yet some other summaries are cut right in the middle or a word, for example:

This seems to bite me in the ass more often than not but any time you add a new model or adjust your associations, be sure to delete the cached ones from the /app/tmp/ folder. I'll get inexplicable er...

Not that nice indeed.

Now I must say that I myself hadn't noticed this, it was only until a client of ours made me aware of it whilst developing their site that I saw it. And boy I must say, she sure was right: it does look pretty nasty when a word is cut in half and the horizontal ellipsis is placed right after that. *Yoink*

Solution for this problem actually is "as easy as killing babies with axes": just cut off the summary on the last space and you're done (there would a problem if no space occurs, yet that won't occur on a regular news-/blogpost). So next to the makeSummary() function we'll create a reworkSummary() function to take the appropriate actions.

The resulting PHP code for this is:

// All your code are belong to bram.us
	function reworkSummary($summary) {

		// find last space
		$pos = strrpos($summary, " ");

		// a space was found: return substring from 0 till found position
		if ($pos !== false) {
			return substr($summary, 0, $pos);
		// no space was found: return the created summary
		} else {
			return $summary;
		}
	}

Now all you have to do is adjust makeSummary() so that it calls the reworkSummary() function. Please note that the default horizontal ellipsis now is preceded with a space, to make it look even nicer:

// All your code are belong to bram.us
	function makeSummary($text, $length, $hellip = " …") {

		// enforce html text (maybe it was encoded somewhere)
		$htmlText	= html_entity_decode($text);

		// strip out the tags
		$flatText	= strip_tags($htmlText);

		// text is not longer than length, return flatText
		if (strlen($flatText) <= $length) {
			return $flatText;
		// text is longer than length, create the summary and add hellips
		} else {
			$summary	= substr($flatText, 0, $length);
			return reworkSummary($summary).$hellip;
		}

	}

The following code ...

echo makeSummary("Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.", 200);
echo makeSummary("Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.", 200, " (continued)");
echo makeSummary("Lorem Ipsum is simply dummy text of the printing and typesetting industry.", 200, " (continued)");

... will output:

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type …
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type (continued)
Lorem Ipsum is simply dummy text of the printing and typesetting industry.

Happy summarizing!

B!