Sidebar Pages In WordPress
Feb 16th, 2011
Creating a custom “Popular Posts” widget
I have a blogging client who has a love-hate relationship with computing. This client publishes daily and has become quite adept at the mechanics of doing so, successfully building traffic and a solid following. But when it comes to handling the blog’s administrative tasks, my client balks, refusing to look at any of the admin level menus. “I don’t like being a person who knows just enough to be dangerous,” my client has said.
The latest request from this client was to list the blog’s most popular posts in the sidedbar. It’s a WordPress site and 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 my client’s own 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 selection and ranking of posts although I didn’t have a clue how.
One of the joys of computer programming comes from those moments when you recognize that the particular little problem you’re working on is just a special case of a larger, more interesting and easier to solve problem. In this case, the larger problem was how to enable a WordPress author to publish formatted content to a sidebar widget. If I could solve that problem then my client could simply edit a page containing an ordered list of titles linked to the most popular posts. These could easily be copied from other pages in the WordPress dashboard. The client wouldn’t need any admin level privileges. All I had to do was setup a text widget with code that pulled in the content of a designated page — A sidebar page.
How to build a WordPress sidebar page widget
Rather than write a dedicated sidebar widget, which is kind of complicated even though the WordPress codex has several examples to copy and paste from, I decided to write a WordPress shortcode which could be used in a sidebar text widget. This shortcode could also be used in other posts or pages on the site — going again for the more general and easier solution.
To start with, I created a new static page with the title, “Popular Posts”. Before you do this and publish the new page, check to see if it will automattically appear in your navigation menus. If you’re using the Menu Manager (included in WordPress 3.0+,) you’re probably okay since there’s a setting for this that’s off by default. If your theme does not use the Menu Manager, you might want to make the new page a child of some other page to exclude it from your navigation.
Next, we have to write a function that will output the contents of a page. This is easy. WordPress provides a built-in function just for that purpose called, get_page( ). We are going to use a variant of that function, get_page_by_title( ), and pass the title of the page (instead of the ID) as a shortcode parameter. 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 this is the page’s title which is then extracted by the second line of the code. If no title is passed, it’s given an empty string value. 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. Note that the content is returned unfiltered. That is, it’s unaffected by any plugins (e.g: ShareThis) or other code that modifies content.
The function code goes into your theme’s function file, functions.php. Make sure you backup this file before you make any changes!! The function code can go anywhere in the file (except, of course, inside of another function) provided that it’s inside a set of php tags.
The next step is to register the shortcode so that it’s 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 function. I usually place it after the function along with comments to guide any future programmers who may work on my clients’ sites.
Next, we have to enable shortcodes in text widgets. This is not enabled by default in WordPress because of security concerns. Sidebar text widgets are places where people often embed code from outside sources. The concern is that such embeded code might contain a shortcode that could conflict with something else on your blog or otherwise do nasty stuff. This is usually not a problem for smaller, personal blogs, however, I’ll emphasize again the importance of backing up your theme’s functions file before making any changes. 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.
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.
