Better Includes and Excludes for wp_list_pages

The wp_list_pages() template tag forms the navigation core of most WordPress-powered websites, but it has a few issues:

1. The exclude_tree parameter doesn’t work. If you include a list of page ID numbers after “exclude_tree=” in your wp_list_pages() tag, all of those pages (and all of their child pages) are supposed to be excluded from the page list. However, only the first page ID actually works this way; the others are ignored.
2. There’s no such thing as an include_tree parameter.

That second one really became a pain working on a non-profit site recently. After I turn the site over, I want the director to be able to add and move pages whenever he wants without it breaking the nice drop-down menus I worked so hard styling for him.

The Function

That’s where this handy little function comes in. It adds an include_tree parameter and solves the exclude_tree problem by taking the list of page IDs in your exclude- and include_tree parameters, finding all of the child pages (to the depth you specify), then adding those parent and child IDs to your exclude and include parameters before passing everything on to the wp_list_pages function.

function md_list_pages( $args ) {

	$defaults = array(
		'depth' => 0, 'show_date' => '',
		'child_of' => 0, 'exclude' => '',
		'title_li' => __('Pages'), 'echo' => 1,
		'authors' => '', 'sort_column' => 'menu_order, post_title',
		'link_before' => '', 'link_after' => '',
		'include' => '', 'include_tree' => '',
		'exclude_tree' => '',
	);

	$r = wp_parse_args( $args, $defaults );

	$exclude = list_pages_tree( $r[ 'exclude' ], $r[ 'exclude_tree' ],
			$r[ 'depth' ] );
	$include = list_pages_tree( $r[ 'include' ], $r[ 'include_tree' ],
			$r[ 'depth' ] );

	$pages = wp_list_pages( 'depth=' . $r[ 'depth' ] . '&show_date='
			. $r[ 'show_date' ] . '&child_of=' . $r[ 'child_of' ]
			. '&exclude=' . $exclude . '&title_li='
			. $r[ 'title_li' ] . '&echo=0&authors=' 
            . $r[ 'authors' ] . '&sort_column=' 
            . $r[ 'sort_column' ] . '&link_before=' 
            . $r[ 'link_before' ] . '&link_after=' 
            . $r[ 'link_after' ] . '&include=' . $include );
            
	if($r['echo']){
    	echo $pages;
	} else {
    	return $pages;
	}

}

function list_pages_tree( $param, $tree, $depth ) {

	// get the parent pages of the tree
	$parent_pages = get_pages( 'include=' . $tree );

	foreach ( $parent_pages as $parent ) {
		if (!empty( $param ) ) {
			$param .= ",";
		}

		$param .= $parent->ID;

		// get the child pages of the tree
		$child_pages = get_pages ( 'child_of=' . $parent->ID
			. '&depth=' . $depth );

		foreach ( $child_pages as $child ) {
			$param .= "," . $child->ID;
		}
	}

	return $param;
}

How to Use It

Copy and paste the above functions into your functions.php file. Then replace all instances of wp_list_pages() in your template with md_list_pages(). The parameters are the same as the wp_list_pages parameters, with the addition of the include_tree parameter.

For example, I replaced this call on the non-profit site:

<?php wp_list_pages( 'depth=2&sort_column=menu_order&title_li=
			&include=5,9,11,14,2,16' ); ?>

…which only returns the included pages, with this call:

<?php md_list_pages( 'depth=2&sort_column=menu_order&title_li=
			&include_tree=5,9,11,14,2,16' ); ?>

…which returns the included pages and all of their child pages (for the drop-down menu on the site).

I realize that this method results in the template tag parameters being parsed twice, but I decided to keep wp_list_pages in the mix rather than bypass it completely because some plugins (including some on the aforementioned non-profit site) function by adding or removing actions to that template tag.

Hope this is helpful to someone else out there — I’ll be using it myself more in the future (unless WP3.0 eliminates my need for a workaround).

Update: Wow, over 350 pingbacks, and all of them spam. Thank goodness for Akismet…

Update 23 July 2011: I thought the new menu system in WordPress 3.0 pretty much killed the need for this workaround, but I guess there are still reasons to use wp_list_pages(). I’d love to hear how people are still using the function (wp_list_pages(), not my md_list_pages()) and whether they prefer it to wp_nav_menu() or not. Depending on response, I may have to rework my solution a bit to reduce the processing overhead and to weed out the bugs.

WordPress Wednesday: How to Use paginate_comments_links Only When You Really Mean It

I was pretty happy when WordPress added paginate_comments_links because now I didn’t have to write a custom function to break blog comments into separate pages and give them a nice navigation (instead of just “next” and “previous”). However, I like to put my navigation in a div, and I like to style that div…and it can look pretty bad when my styled div shows up with no navigation (depending on my design).

The solution is pretty simple (as most of my solutions are): I wrote a simple function that only echoes my div and pagination links if the comments are paginated:

function comment_pagination() {
	//read the page links but do not echo
	$comment_page = paginate_comments_links('echo=0');

	//if there are page links, echo the navigation div and the page links
	if (!empty($comment_page)) {
		echo "<div class=\"navigation\">\n";
		echo $comment_page;
		echo "\n</div>\n";
		}
}

All that’s left at this point is styling the pagination links.  The above code will give you a markup along these lines:

<div class="navigation">
	<a class='prev page-numbers'>&laquo; Previous</a>
	<a class='page-numbers'>1</a>
	<span class='page-numbers current'>2</span>
	<a class='page-numbers'>3</a>
	<a class='next page-numbers'>Next &raquo;</a>
</div>

Hopefully I’ll learn more about paginate_comments_links in the future and be able to better customize the output. We’ll see.

WordPress Wednesday: Turn Any Shortcode into a Template Tag

I previously discussed WordPress’s shortcode API, which allows you to turn any function into a shortcode that you can embed in the content of your pages or posts. Though the example I gave was for a function I wrote, you can use this API for WordPress template tags. The easiest way is to get the Template Tag Shortcodes plugin by Justin Tadlock, although you can also write your own by adding the following line to your functions.php file:

add_shortcode('shortcode_name', 'template_tag');

But what about the other way around? The solution is just as simple with the do_shortcode function.

You may remember that my previous shortcode allowed a client to enter [link pagename='example'] into the content of any page, and the function would insert the named page’s permalink into the content for him. If I wanted to call that shortcode as a template tag, the tag would look like this:

<?php echo do_shortcode("[link pagename='example']"); ?>

All you have to do to turn any shortcode into a template tag is substitute your shortcode (with the desired parameters defined) between the double quotes (“) and you’re good to go. This is especially helpful when plugins come with shortcodes included but not template tags (like NextGen Gallery).

What will you use the do_shortcode function for?

Update: Thanks to Holling for pointing out that I forgot to include the echo statement. Fixed now.

Survivor: Twitter – 3 Guidelines for Managing Who You Follow and Who Follows You

A few weeks ago was a first for me: I stopped following someone on Twitter.

The person in question is a webcomic artist who is well known for the drama that swirls around him. I started following him for the chance to pick his brain on becoming successful with my own webcomic. Instead of insight into the world of webcomics, however, I got insight into a very angry individual. I got to see frequent, vulgar complaints about inconsequential things. One day he picked a fight about social views (not the first time), starting off by insulting those who hold my personal views.

I decided it was time to stop following. Then I decided that it was time I started managing who I follow and who follows me.

You Are Who You Hang Out With

The way I see it, your social network associations say as much about you as your real-life associations. We all tend to associate with those who we are like, whose views we share or whose company we enjoy. I had stopped enjoying this person’s company a long time ago but for some reason kept associating with him. When I realized that my association could be considered a tacit approval of or agreement with the views he was airing so rudely, I knew I had to end the association.

The same holds true people following me. If you’ve used Twitter with any frequency at all, you’ve probably noticed that you will suddenly have an increase in followers anytime you’re actively tweeting, but that half of them are spambots — and at least half of those are porn spambots. I try to block those as soon as I find them, because I don’t want the association.

Managing Your Twitter Followers Can Be Like a Reality TV Show

Inspired by one of Sid Raisch’s tweets, I’m proposing an UN-Follow Friday — but I want to make it fun and establish some guidelines for who gets unfollowed or blocked.

Think of the people and companies you’re following or who follow you as contestants on Survivor. Each week at Tribal Council you have a chance to vote them off your island. Each Twitterer is judged based on three criteria:

1. Tweet Content
2. Tweet Frequency
3. Relationship

No one person or company needs to satisfy all three guidelines to stay on the island, but anyone who doesn’t satisfy at least one is getting voted off.

Tweet Content

The first guideline is the most obvious: what does the person tweet about? Are the tweets relevant, interesting and/or humorous? In short, why am I following them and what am I getting from the association? You can follow people just because it’s fun (like @CobraCommander or @pagecrusher) or because they’re a celebrity you like (like @wilw), but have some reason why you’re following their tweets. If you never read the person’s tweets (or if their content insults you, like my example), it’s time to cut them loose.

The guideline gets a little relaxed for people following you. Generally, I suggest that as long as they’re not an obvious spammer or particularly offensive they can stay.

Tweet Frequency

One of the people I follow tweets at least 10 times each hour. There is no way I can keep up with all the content that he is pointing to, and sometimes I see the same tweet more than once each day (which may fall under tweet content above). I haven’t stopped following him yet because he does tweet some useful articles, but I’m seriously thinking about it.

Relationship

I follow a few people just because they’re friends of mine, and I don’t see anything wrong with that. In fact, it’s sometimes a good way for us to keep tabs on each other, and occasionally we’ll use Twitter as a way to point each other to content we know the other will like. Additionally, I’ve started to make some friends on Twitter (using some of techniques I discussed in a previous post) who I only know through Twitter. I’m not likely to drop anyone I have a relationship with (real or virtual) unless their tweets become too much of a problem under the first two guidelines.

Wrap-Up

So there are my Twitter follow/follower management guidelines. As before, I plan to follow my own advice. Not sure which day I’ll pick to be my Tribal Council day, but it will probably be Friday or Saturday since I usually have fewer pressing deadlines on those days.

What will your Tribal Council day be?

WordPress Wednesday: How to Transfer Your Plugin Data Using phpMyAdmin

I often use Stray Random Quotes for clients who want to display random testimonials (or quotes, natch) on their WordPress sites. Of course, I build their sites completely on my webspace to test them before installing on the client domain. While WordPress has export and import functions for pages, posts and media, my quotes don’t transfer over so easily. Fortunately, the built-in functions of phpMyAdmin can pick up the slack.

The following assumes that you already have WordPress installed on both your test domain and the live domain. I’m using the specific example of Stray Random Quotes but you can do the same with any plugin that creates tables in your WordPress database.

First, make sure you have Stray Random Quotes (or whichever plugin you’re transferring data for) installed on the live site. This is important because the plugin will create the necessary tables for you (saves you a few steps and a lot of headache).

Second, open your WordPress database using phpMyAdmin on your test site. In the left-hand column, click on the database name to expand it, then click on the wp_stray_quotes table.

Click on the “Export” tab in the  main window. Make sure your export format is set for “SQL” and your export type is “INSERT,” then click “Go.”

You should see a text representation of the database export. Copy only the text rows that start with “INSERT INTO.” Paste these into a text file using Notepad and save as a .txt file.

Next, open the WordPress database on your live site using phpMyAdmin. Click on the database name to expand and then on wp_stray_quotes.

Click the “Import” tab, then the “Browse” button. Locate the text file you created previously and click “Open,” then click “Go.”

Your quotes should be imported into the live database.