Popular Posts Sidebar Page

Crafting a Custom “Popular Posts” Widget

top ten blocksA client wanted to list the blog’s most popular posts in the sidebar. There are many plugins available that will provide a widget for this task. Most are based on comment count as this is the metric that WordPress stores with each post record in its database. Some of the more sophisticated plugins make API calls to other services, such as Twitter and Google, to gather ranking data.

But nothing worked quite right for this client who had become a proficient Google Analytics user as well as a ardent Twitter user. I couldn’t find a popular posts plugin that would reliably match her subjective sense of popularity. I finally sent an email saying: “You want your readers to see your best stuff, in that respect, the numbers can provide guidance but your own judgement is the best metric.” I promised to figure something out that would allow the management of a Top-Ten Posts lists.

Rather than write a new sidebar widget, I decided to write a shortcode which could be used in a sidebar text widget to display the content from a specific page. Then my client could simply edit a page containing an ordered list of permalinks to the most popular posts and it would appear in the sidebar widget. It could also be used in other posts or pages on the site.

How to Build a Sidebar Page Widget

To start, create a new static page with a title like, “Popular Posts”. Enter an ordered list of permalinks to other posts for testing.

You need to add a function to your theme’s function file, functions.php, that will output the contents of a page when called from the shortcode. Make sure you backup functions.php before you make any changes! WordPress has built-in functions for getting the contents of a page. Use get_page_by_title( ) to fetch the page by its title. Here’s the code for the function:
function my_show_page( $atts, $content = null ) {
extract(shortcode_atts(array( 'title'=>'' ), $atts));
if ($title != '') {
$page_data = get_page_by_title( $title );
return $page_data->post_content;
}
else {
return '';
}
}

The first two lines are the standard setup for a shortcode. The parameter, $atts, will contain the shortcode’s parameters. In our case there is only one parameter, the page’s title which is extracted by the second line of the code. Setting the variable $content to null allows us to place the simple shortcode:

[showpage title="Popular Posts"]

wherever we want to display the content of the page “Popular Posts” .

The body of the function is a simple if statement that makes sure a title is provided, then goes and gets the content of that page and returns it. The content is returned unfiltered. That is, it’s unaffected by any plugins (e.g: ShareThis) or other code that modifies content.

The shortcode must be registered to make it available for use. This is just a short command that also goes in the theme’s function file:

add_shortcode('showpage', 'my_show_page');

It can go either before or after the definition of the my_show_page function. I usually place it after the function along with comments to guide any future programmers who may work on my clients’ sites.

Shortcodes are not enabled by default in text widgets because of security concerns. Sidebar text widgets are places where people often embed code clipped from outside sources. The concern is that such embedded code might contain a shortcode that could cause a conflict. This is usually not a problem for smaller, personal blogs. Here’s the command to enable shortcodes in text widgets:

add_filter('widget_text', 'do_shortcode');

Add the above to your functions file, save it and test the blog in a separate browser window to be sure it’s still working. Errors in a theme’s functions file will usually crash the public portion of a WordPress blog, but will leave the admin dashboard in working order.

Lastly, add a text widget with the shortcode to your sidebar. Here’s a screenshot from my client’s site illustrating this.

Text Widget with a shortcode

For your convenience, here’s the entire block of commented code that I added to my client’s function file:
/**
* Create a shortcode to display a page's content */
//
// [showpage title="page_title"]
//
function my_show_page( $atts, $content = null ) {
extract(shortcode_atts(array( 'title'=>'' ), $atts));
if ($title != '') {
$page_data = get_page_by_title( $title );
return $page_data->post_content;
}
else {
return '';
}
}
// register the shortcode
add_shortcode('showpage', 'my_show_page');
//
// Enable the use of shortcodes in text widgets.
add_filter('widget_text', 'do_shortcode');

Now that we see how easy it is to get formatted content into a sidebar widget, perhaps you have some ideas on what can be done with custom shortcodes in sidebar widgets. If so, please share them by leaving a comment below. Thanks.