Digging into WordPress » template http://digwp.com Take your WordPress skills to the next level. Thu, 09 Feb 2012 19:03:45 +0000 en hourly 1 http://wordpress.org/?v=3.3.1 WordPress Custom functions.php Template, Part 2 http://digwp.com/2010/04/wordpress-custom-functions-php-template-part-2/ http://digwp.com/2010/04/wordpress-custom-functions-php-template-part-2/#comments Wed, 07 Apr 2010 16:13:36 +0000 Jeff Starr http://digwp.com/?p=1811 In a recent post, we show you how to clean up and enhance the functionality of WordPress with a custom functions.php template. In that post, we explain how using a custom functions.php template can speed up development while optimizing many key aspects of WordPress. In this post, we deliver another prime collection of 15 custom functions to enhance your WordPress site. These functions provide all sorts of useful functionality, including stuff like:

  • Callback function for a custom comments loop
  • Automatic content insertion in posts and feeds
  • Spam and delete links for comments when logged in
  • Buffer period before new posts are added to your feeds
  • Including an Admin link to the “All-Settings” page
  • Removing the version and generator information from your site and feed

These new functions extend the functionality of our original functions.php template with 15 more useful functions. Not everything presented here is going to be necessary for all of your themes, so just grab what you need and add it your own custom functions.php file.

In this DiW article, we extend our original functions.php template with 15 more useful functions.

As before, we’ll first walk through each of the functions and then unify them into a working functions.php template. To use, just copy and paste the template code at the end of this article or grab a copy of the zipped functions.php file and enjoy a custom collection of functions that will help you optimize your development process while enhancing WordPress with some awesome new functionality.

Insert custom content after each post

If you look at the different things contained within a typical post, you will find many common and repetitive items, such as feed links, copyright information, and social-media bookmarks. While there’s nothing wrong with inserting this content into your single.php template, it is sometimes easier to manage things from the functions.php file. For example, at Perishable Press, I include a brief copyright statement at the end of each post. By including the following code in my functions.php template, it’s something that happens automatically:

// add custom post content
function add_post_content($content) {
	if(!is_feed() && !is_home()) {
		$content .= '<p>This article is copyright &copy; '.date('Y').'&nbsp;'.bloginfo('name').'</p>';
	}
	return $content;
}
add_filter('the_content', 'add_post_content');

The trick here is an old one, but it’s extremely useful. By changing the line beginning with “$content.”, you can add just about any content you like.

Insert custom content in your feeds

Just as with the previous method, this function makes it possible to automatically add any content to your feeds. Yes, I know there are plugins that will make your feed footers do backflips, but for a simple copyright message or other info, I think it is easier and more efficient to simply toss a few lines into your custom functions.php template:

// add custom feed content
function add_feed_content($content) {
	if(is_feed()) {
		$content .= '<p>This article is copyright &copy; '.date('Y').'&nbsp;'.bloginfo('name').'</p>';
	}
	return $content;
}
add_filter('the_excerpt_rss', 'add_feed_content');
add_filter('the_content', 'add_feed_content');

As before, you can change the added content to whatever you want by editing the “$content” variable. Once in place, this will append a dynamic copyright message to each post in your feed. Note: if you happen to be adding the same content to your web pages (using the previous method) and your feeds (using this method), you may combine the two functions like so:

// add custom content to feeds and posts
function add_custom_content($content) {
	if(!is_home()) {
		$content .= '<p>This article is copyright &copy; '.date('Y').'&nbsp;'.bloginfo('name').'</p>';
	}
	return $content;
}
add_filter('the_excerpt_rss', 'add_custom_content');
add_filter('the_content', 'add_custom_content');

Remember that if you use this combined function that you should remove or comment out both of the individual ones to avoid duplicate output. It will be included but commented out in the complete functions.php template file.

Completely remove the version number from pages and feeds

A commonly cited security measure for WordPress-powered sites involves removing the automatically generated version number from appearing in the <head> section of your pages’ source code. This type of security technique is referred to as “security through obscurity,” and aims at hiding potentially sensitive information from a would-be attacker. Here’s a function that does the job:

// remove version info from head and feeds
function complete_version_removal() {
	return '';
}
add_filter('the_generator', 'complete_version_removal');

This will remove your site’s version and generator information from all of your pages and feeds, making it a little bit harder for the bad guys and a little bit safer for you and your visitors.

Customize the admin footer message

Customization is what makes your online experience something special. For your own sites and for your clients’ sites, it is nice to customize the generic admin footer message with something a little more useful, informative, and inspiring. This little gem makes it easy:

// customize admin footer text
function custom_admin_footer() {
	echo '<a href="http://monzilla.biz/">Website Design by Monzilla Media</a>';
} 
add_filter('admin_footer_text', 'custom_admin_footer');

Here, for the sake of example, we are including a link to my web-design company, but you can customize the content with just about anything you wish. If this were something I had to do manually for each site, I probably wouldn’t do it. But by adding these few lines to my functions.php template, it all happens automatically, without me having to think about it. Nice ;)

Enable HTML markup in user profiles

When customizing their profiles, users may want to include a hyperlink, bold text, or some other HTML markup. By default, WordPress prevents this from happening, but you can easily enable it with this friendly little snippet:

// enable html markup in user profiles
remove_filter('pre_user_description', 'wp_filter_kses');

Note: as miqrogroove points out, enabling HTML may be best left to sites that have open user-registration disabled. Use with discretion.

Delay feed update after posting

As a chronic perfectionist, I hate it when I post something only to discover an error a few minutes later. By the time I notice, fix and update the post, it’s already been beamed out all over the freakin’ place. To prevent this, I like to take the advice of WPEngineer and give myself a little buffer period or “safety net” after publishing my posts.

// delay feed update
function publish_later_on_feed($where) {
	global $wpdb;

	if (is_feed()) {
		// timestamp in WP-format
		$now = gmdate('Y-m-d H:i:s');

		// value for wait; + device
		$wait = '5'; // integer

		// http://dev.mysql.com/doc/refman/5.0/en/date-and-time-functions.html#function_timestampdiff
		$device = 'MINUTE'; // MINUTE, HOUR, DAY, WEEK, MONTH, YEAR

		// add SQL-sytax to default $where
		$where .= " AND TIMESTAMPDIFF($device, $wpdb->posts.post_date_gmt, '$now') > $wait ";
	}
	return $where;
}
add_filter('posts_where', 'publish_later_on_feed');

This code quietly and automatically gives me an extra five minutes before my post is added to my feeds. If you need more or less than five minutes, just edit the “$wait” variable with the integer of your choice.

Add an Admin link to the WordPress “All-Settings” page

As we’ve explained before, WordPress makes it easy to view and edit your blog settings from the Admin area. Thanks to a file named “options.php”, WordPress will display all of your database settings and enable you to edit a majority of them. To view this page, you need to log in as Admin and enter this URL in your browser’s address bar:

http://domain.tld/wp-admin/options.php

Having access to your “All-Settings” page can be extremely helpful, so it’s nice to display a direct link for easy access. The following slice of code in your functions.php file is all that’s needed:

// admin link for all settings
function all_settings_link() {
	add_options_page(__('All Settings'), __('All Settings'), 'administrator', 'options.php');
}
add_action('admin_menu', 'all_settings_link');

Once in place, you will see a link to your “All Settings” page in the WordPress Admin. You can change the name of the link to whatever you prefer by editing the two instances of “All Settings”.

Remove all nofollow attributes from comments

There are a million ways to remove nofollow from your comments, but nothing is as easy as this method provided by code guru Thomas Scholz:

// remove nofollow from comments
function xwp_dofollow($str) {
	$str = preg_replace(
		'~<a ([^>]*)\s*(["|\']{1}\w*)\s*nofollow([^>]*)>~U',
		'<a ${1}${2}${3}>', $str);
	return str_replace(array(' rel=""', " rel=''"), '', $str);
}
remove_filter('pre_comment_content',     'wp_rel_nofollow');
add_filter   ('get_comment_author_link', 'xwp_dofollow');
add_filter   ('post_comments_link',      'xwp_dofollow');
add_filter   ('comment_reply_link',      'xwp_dofollow');
add_filter   ('comment_text',            'xwp_dofollow');

That code will remove all instances of the nefarious “nofollow” attribute from all comment items, including the author link and comment text. This is a great way to automatically remove nofollow with no plugins or hacking required.

Enable easy display of your post’s word count

This function enables you to display your post’s word count without cluttering up the WordPress loop. To display the word count of your posts, first place this in your functions.php file:

// count words in posts
function word_count() {
	global $post;
	echo str_word_count($post->post_content);
}

Then, simply place this anywhere in your loop where you would like the number to appear:

<?php word_count(); ?>

So for example, you could display your post’s word count to your visitors with something like:

<p>This post contains a whopping <?php word_count(); ?> words.</p>

We can also easily display the word count of other items, such as the post title:

<?php echo str_word_count($post->post_title); ?>

Likewise, we can exclude the function from functions.php and get the word count with a single line of code in the loop:

<?php echo str_word_count($post->post_content); ?>

Just slap ‘em anywhere in your post loop to display your word count. Not always needed, but nice to have available ;)

Enable delete and spam links for comments

Managing your comments is easily done via the Admin, but geeks like me also like to see things from the outside, as they appear to the public. Browsing through comments as they appear on your site helps you catch things that may have eluded routine approvals in the Admin’s comment listings. To help facilitate this process, I like to include a backwards-compatible set of spam and delete links next to each comment. This makes it super-easy to cultivate comments live on the site.

// spam & delete links for all versions of wordpress
function delete_comment_link($id) {
	if (current_user_can('edit_post')) {
		echo '| <a href="'.get_bloginfo('wpurl').'/wp-admin/comment.php?action=cdc&c='.$id.'">del</a> ';
		echo '| <a href="'.get_bloginfo('wpurl').'/wp-admin/comment.php?action=cdc&dt=spam&c='.$id.'">spam</a>';
	}
}

Once this is included in your functions.php file, displaying the links is as easy as adding this to your comments loop:

<?php delete_comment_link(get_comment_ID()); ?>

Disable all WordPress feeds

Thanks to Frank from WPEngineer, it is easy to disable all feed functionality for your site. Here is the functions.php code:

Note: Only use this function if you want to disable your feeds! This function will be commented out of the complete functions.php file.

// disable all feeds
function fb_disable_feed() {
	wp_die(__('<h1>Feed not available, please visit our <a href="'.get_bloginfo('url').'">Home Page</a>!</h1>'));
}
add_action('do_feed',      'fb_disable_feed', 1);
add_action('do_feed_rdf',  'fb_disable_feed', 1);
add_action('do_feed_rss',  'fb_disable_feed', 1);
add_action('do_feed_rss2', 'fb_disable_feed', 1);
add_action('do_feed_atom', 'fb_disable_feed', 1);

This function will quietly and completely disable all of your site’s feeds, including all different formats. With this code in place, any request for your feed will return the following message in a nice, big set of <h1> tags:

Feed not available, please visit our Home Page!

This message is easily customized by editing the “wp_die” argument in the function.

Customize the default gravatars and add your own

Instead of suffering with the rather dull default gravatars, use this code to customize your own: 

// customize default gravatars
function custom_gravatars($avatar_defaults) {

	// change the default gravatar
	$customGravatar1 = get_bloginfo('template_directory').'/images/gravatar-01.png';
	$avatar_defaults[$customGravatar1] = 'Default';

	// add a custom user gravatar
	$customGravatar2 = get_bloginfo('template_directory').'/images/gravatar-02.png';
	$avatar_defaults[$customGravatar2] = 'Custom Gravatar';

	// add another custom gravatar
	$customGravatar3 = get_bloginfo('template_directory').'/images/gravatar-03.png';
	$avatar_defaults[$customGravatar3] = 'Custom gravatar';

	return $avatar_defaults;
}
add_filter('avatar_defaults', 'custom_gravatars');

Of course, you can manually choose a default gravatar by specifying its location via the “get_avatar” template tag, but this method makes it so much easier. Not only does it replace the default with multiple custom gravatars, but it also goes the extra mile by displaying them in the WordPress Admin area under Settings > Discussion. From there, you can select any of your custom gravatars by simply selecting it and clicking the “Update” button. Nothing could be easier.

A few notes about this function:

  • As is, it adds three new gravatars to choose as defaults.
  • Each gravatar should be located in your theme’s images directory.
  • You can add as many default gravatars as you would like by emulating the code pattern.
  • If you keep your custom gravatars someplace else, be sure and edit the image paths accordingly.

Disable automatic formatting in post content via shortcode

WPRecipes shows us how to prevent WordPress from automatically formatting chunks of post content by using a shortcode. This is very useful for posting code, poetry, or anything else that you would like to display in raw format. To do this, we add the following snippet to our functions.php file:

// disable auto formatting in posts
function my_formatter($content) {
	$new_content = '';
	$pattern_full = '{(\[raw\].*?\[/raw\])}is';
	$pattern_contents = '{\[raw\](.*?)\[/raw\]}is';
	$pieces = preg_split($pattern_full, $content, -1, PREG_SPLIT_DELIM_CAPTURE);

	foreach ($pieces as $piece) {
		if (preg_match($pattern_contents, $piece, $matches)) {
			$new_content .= $matches[1];
		} else {
			$new_content .= wptexturize(wpautop($piece));
		}
	}

	return $new_content;
}
remove_filter('the_content', 'wpautop');
remove_filter('the_content', 'wptexturize');
add_filter('the_content', 'my_formatter', 99);

With that code in place, you can insert unformatted code into your posts via the “[raw]” shortcode, for example:

[raw]Unformatted content[/raw]

Anything contained within those shortcodes will be left unformatted when displayed in your posts.

Escape HTML entities in comments

Kaspars Dambis shows us how to automatically escape encoded HTML entities in the comments that readers leave on your posts. This is especially useful for blogs that deal in heavy code exchanges on post threads. This enables your commentators to simply wrap their code in <code> tags and not have to worry about manually converting characters such as angled brackets (“<” & “>”) into their encoded equivalents (“&lt;” & “&gt;”).

// escape html entities in comments
function encode_code_in_comment($source) {
	$encoded = preg_replace_callback('/<code>(.*?)<\/code>/ims',
	create_function('$matches', '$matches[1] = preg_replace(array("/^[\r|\n]+/i", "/[\r|\n]+$/i"), "", $matches[1]); 
	return "<code>" . htmlentities($matches[1]) . "</"."code>";'), $source);
	if ($encoded)
		return $encoded;
	else
		return $source;
}
add_filter('pre_comment_content', 'encode_code_in_comment');

Once in place in your functions.php file, simply tell your commentators to wrap their code snippets in <code> tags. In other words, any content wrapped in <code> tags will be encoded automatically. Plus, in order to prevent unwanted <br /> tags, this function also automatically removes line breaks after the opening <code> tag and before the closing <code> tag.

Custom comments display callback function

When designing your theme’s comments.php file, you can use either WordPress’ default code or create your own for full control over your comments display. If you’re rolling your own, it is often easiest to grab a solid comments-display template and customize it to suit your needs. After many iterations and much refining, here is the comments callback function that I usually begin with:

// custom comments callback function
function custom_comments_callback($comment, $args, $depth) {
	$GLOBALS['comment'] = $comment; ?>

	<li <?php comment_class(); ?> id="comment-<?php comment_ID(); ?>">
		<div class="comment-wrap">
			<?php echo get_avatar(get_comment_author_email(), $size = '50', $default = bloginfo('stylesheet_directory').'/images/gravatar.png'); ?>

			<div class="comment-intro">
            			<?php printf(__('%s'), get_comment_author_link()); ?> &ndash; <a class="comment-permalink" href="<?php echo htmlspecialchars(get_comment_link($comment->comment_ID)); ?>"><?php comment_date('F j, Y'); ?> @ <?php comment_time(); ?></a><?php edit_comment_link('Edit', ' &ndash; ', ''); ?>
			</div>
			<?php if ($comment->comment_approved == '0') : ?>

			<p class="comment-moderation"><?php _e('Your comment is awaiting moderation.'); ?></p>
			<?php endif; ?>

			<div class="comment-text"><?php comment_text(); ?></div>

			<div class="reply" id="comment-reply-<?php comment_ID(); ?>">
				<?php comment_reply_link(array_merge($args, array('reply_text'=>'Reply', 'login_text'=>'Log in to Reply', 'add_below'=>'comment-reply', 'depth'=>$depth, 'max_depth'=>$args['max_depth']))); ?> 

			</div>
		</div>

<?php } // WP adds the closing </li>

There’s a lot going on here, so let’s highlight the important stuff:

  • Do not add the closing </li> element – WordPress does this for you.
  • This function calls for a default gravatar in your theme’s “images” directory. Either ensure you’ve got the required image in place or edit the code to reflect your site’s reality.
  • Once this function is included in your functions.php file, you can display it by using the following comments loop in your comments.php file:
<?php if (have_comments()) : ?>
<ol class="commentlist">
	<?php wp_list_comments('type=comment&style=ol&callback=custom_comments_callback'); ?>
</ol>
<?php else : ?>

Notice the third parameter for the wp_list_comments template tag? that’s what makes it go. Also important is the “style=ol” parameter, which tells WordPress that we are using an ordered list for comments and that it should automatically close the markup with a </li> element.

Putting it all together..

As promised, here is the full-meal deal – the entire collection neatly organized into a single chunk of code:

<?php // custom functions.php template @ digwp.com

// add custom post content
function add_post_content($content) {
	if(!is_feed() && !is_home()) {
		$content .= '<p>This article is copyright &copy; '.date('Y').'&nbsp;'.bloginfo('name').'</p>';
	}
	return $content;
}
add_filter('the_content', 'add_post_content');


// add custom feed content
function add_feed_content($content) {
	if(is_feed()) {
		$content .= '<p>This article is copyright &copy; '.date('Y').'&nbsp;'.bloginfo('name').'</p>';
	}
	return $content;
}
add_filter('the_excerpt_rss', 'add_feed_content');
add_filter('the_content', 'add_feed_content');


/* add custom content to feeds and posts
function add_custom_content($content) {
	if(!is_home()) {
		$content .= '<p>This article is copyright &copy; '.date('Y').'&nbsp;'.bloginfo('name').'</p>';
	}
	return $content;
}
add_filter('the_excerpt_rss', 'add_custom_content');
add_filter('the_content', 'add_custom_content'); */


// remove version info from head and feeds
function complete_version_removal() {
	return '';
}
add_filter('the_generator', 'complete_version_removal');


// customize admin footer text
function custom_admin_footer() {
	echo '<a href="http://monzilla.biz/">Website Design by Monzilla Media</a>';
} 
add_filter('admin_footer_text', 'custom_admin_footer');


// enable html markup in user profiles
remove_filter('pre_user_description', 'wp_filter_kses');


// delay feed update
function publish_later_on_feed($where) {
	global $wpdb;

	if (is_feed()) {
		// timestamp in WP-format
		$now = gmdate('Y-m-d H:i:s');

		// value for wait; + device
		$wait = '5'; // integer

		// http://dev.mysql.com/doc/refman/5.0/en/date-and-time-functions.html#function_timestampdiff
		$device = 'MINUTE'; // MINUTE, HOUR, DAY, WEEK, MONTH, YEAR

		// add SQL-sytax to default $where
		$where .= " AND TIMESTAMPDIFF($device, $wpdb->posts.post_date_gmt, '$now') > $wait ";
	}
	return $where;
}
add_filter('posts_where', 'publish_later_on_feed');


// admin link for all settings
function all_settings_link() {
	add_options_page(__('All Settings'), __('All Settings'), 'administrator', 'options.php');
}
add_action('admin_menu', 'all_settings_link');


// remove nofollow from comments
function xwp_dofollow($str) {
	$str = preg_replace(
		'~<a ([^>]*)\s*(["|\']{1}\w*)\s*nofollow([^>]*)>~U',
		'<a ${1}${2}${3}>', $str);
	return str_replace(array(' rel=""', " rel=''"), '', $str);
}
remove_filter('pre_comment_content',     'wp_rel_nofollow');
add_filter   ('get_comment_author_link', 'xwp_dofollow');
add_filter   ('post_comments_link',      'xwp_dofollow');
add_filter   ('comment_reply_link',      'xwp_dofollow');
add_filter   ('comment_text',            'xwp_dofollow');


// count words in posts
function word_count() {
	global $post;
	echo str_word_count($post->post_content);
}


// spam & delete links for all versions of wordpress
function delete_comment_link($id) {
	if (current_user_can('edit_post')) {
		echo '| <a href="'.get_bloginfo('wpurl').'/wp-admin/comment.php?action=cdc&c='.$id.'">del</a> ';
		echo '| <a href="'.get_bloginfo('wpurl').'/wp-admin/comment.php?action=cdc&dt=spam&c='.$id.'">spam</a>';
	}
}


/* disable all feeds
function fb_disable_feed() {
	wp_die(__('<h1>Feed not available, please visit our <a href="'.get_bloginfo('url').'">Home Page</a>!</h1>'));
}
add_action('do_feed',      'fb_disable_feed', 1);
add_action('do_feed_rdf',  'fb_disable_feed', 1);
add_action('do_feed_rss',  'fb_disable_feed', 1);
add_action('do_feed_rss2', 'fb_disable_feed', 1);
add_action('do_feed_atom', 'fb_disable_feed', 1); */


// customize default gravatars
function custom_gravatars($avatar_defaults) {

	// change the default gravatar
	$customGravatar1 = get_bloginfo('template_directory').'/images/gravatar-01.png';
	$avatar_defaults[$customGravatar1] = 'Default';

	// add a custom user gravatar
	$customGravatar2 = get_bloginfo('template_directory').'/images/gravatar-02.png';
	$avatar_defaults[$customGravatar2] = 'Custom Gravatar';

	// add another custom gravatar
	$customGravatar3 = get_bloginfo('template_directory').'/images/gravatar-03.png';
	$avatar_defaults[$customGravatar3] = 'Custom gravatar';

	return $avatar_defaults;
}
add_filter('avatar_defaults', 'custom_gravatars');


// disable auto formatting in posts
function my_formatter($content) {
	$new_content = '';
	$pattern_full = '{(\[raw\].*?\[/raw\])}is';
	$pattern_contents = '{\[raw\](.*?)\[/raw\]}is';
	$pieces = preg_split($pattern_full, $content, -1, PREG_SPLIT_DELIM_CAPTURE);

	foreach ($pieces as $piece) {
		if (preg_match($pattern_contents, $piece, $matches)) {
			$new_content .= $matches[1];
		} else {
			$new_content .= wptexturize(wpautop($piece));
		}
	}

	return $new_content;
}
remove_filter('the_content', 'wpautop');
remove_filter('the_content', 'wptexturize');
add_filter('the_content', 'my_formatter', 99);


// escape html entities in comments
function encode_code_in_comment($source) {
	$encoded = preg_replace_callback('/<code>(.*?)<\/code>/ims',
	create_function('$matches', '$matches[1] = preg_replace(array("/^[\r|\n]+/i", "/[\r|\n]+$/i"), "", $matches[1]); 
	return "<code>" . htmlentities($matches[1]) . "</"."code>";'), $source);
	if ($encoded)
		return $encoded;
	else
		return $source;
}
add_filter('pre_comment_content', 'encode_code_in_comment');


// custom comments callback function
function custom_comments_callback($comment, $args, $depth) {
	$GLOBALS['comment'] = $comment; ?>

	<li <?php comment_class(); ?> id="comment-<?php comment_ID(); ?>">
		<div class="comment-wrap">
			<?php echo get_avatar(get_comment_author_email(), $size = '50', $default = bloginfo('stylesheet_directory').'/images/gravatar.png'); ?>

			<div class="comment-intro">
            			<?php printf(__('%s'), get_comment_author_link()); ?> &ndash; <a class="comment-permalink" href="<?php echo htmlspecialchars(get_comment_link($comment->comment_ID)); ?>"><?php comment_date('F j, Y'); ?> @ <?php comment_time(); ?></a><?php edit_comment_link('Edit', ' &ndash; ', ''); ?>
			</div>
			<?php if ($comment->comment_approved == '0') : ?>

			<p class="comment-moderation"><?php _e('Your comment is awaiting moderation.'); ?></p>
			<?php endif; ?>

			<div class="comment-text"><?php comment_text(); ?></div>

			<div class="reply" id="comment-reply-<?php comment_ID(); ?>">
				<?php comment_reply_link(array_merge($args, array('reply_text'=>'Reply', 'login_text'=>'Log in to Reply', 'add_below'=>'comment-reply', 'depth'=>$depth, 'max_depth'=>$args['max_depth']))); ?> 

			</div>
		</div>

<?php } // WP adds the closing </li>

?>

Download the custom functions.php template file

If you prefer, you can download this code in a ready-to-go functions.php file in zipped format:

Download zipped functions.php Template File

Also..

If this post is useful to DiW readers, I’ll be writing up yet another article (part 3!) with even more useful custom functions. If that happens, the third set of functions will include some slightly more advanced techniques. Stay tuned!

© 2010 Digging into WordPress | Permalink | 17 comments | Add to del.icio.us | Post tags: , ,

]]> http://digwp.com/2010/04/wordpress-custom-functions-php-template-part-2/feed/ 17 WordPress functions.php Template with 15 Essential Custom Functions http://digwp.com/2010/03/wordpress-functions-php-template-custom-functions/ http://digwp.com/2010/03/wordpress-functions-php-template-custom-functions/#comments Mon, 22 Mar 2010 06:25:58 +0000 Jeff Starr http://digwp.com/?p=1699 When designing WordPress themes, I always add a common set of custom functions to the theme’s functions.php file. This speeds up development time because I don’t have to hunt for and individually copy the same slew of functions for every theme. I just drop in a copy of my functions.php template and build up from there. This takes care of all those little things that always need to be done:

  • Include jQuery
  • Enable threaded comments
  • Add feed links to the header
  • Disable unused widget areas
  • Adding Google Analytics to the footer
  • Stop the “Read More” link from jumping to the middle of the next page ;)

One of the things that I like about these functions is that they’re all so concise, simple, and effective. The functions.php template file currently contains 15 different functions and is a continual work in progress. Not everyone is going to need or use everything in the file, but the idea is to modify this template into something that works for you. It’s a starting point with some really useful functions.

In this DiW article, we first provide an explanation of each of the 15 functions and then bring them all together into the working functions.php template. Just copy and paste the template code at the end of this article or grab a copy of the zipped functions.php file and enjoy a custom collection of functions that will help you optimize your development process while enhancing WordPress with essential functionality.

Add feed links to header

Since version 2.8, WordPress can add all relevant feed links (main, comments, categories, et al) to your <head> area. It doesn’t happen by default, however, because you have to add the following snippet to make it work:

// add feed links to header
if (function_exists('automatic_feed_links')) {
	automatic_feed_links();
} else {
	return;
}

This will check to see if you’re using a version of WordPress that is compatible, and then enable the automatic feed links. A couple of notes: first, this method assumes that you are not manually including any feed links in your <head>. Also, I read a recent Trac ticket that looked like this functionality was being integrated with add_theme_support, so keep your eyes open for that.

Automatic jQuery inclusion

We’ve discussed how to include jQuery the right way by placing a little snippet in your document head, but here is a way to do it from your theme’s functions.php file:

// smart jquery inclusion
if (!is_admin()) {
	wp_deregister_script('jquery');
	wp_register_script('jquery', ("http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"), false);
	wp_enqueue_script('jquery');
}

This code ensures that only one copy of jQuery is included, and calls it from Google’s servers to save bandwidth and take advantage of any primed caches that happen to be visiting. Note that this function needs to be located before the threaded-comments function in order for it to work.

Enable threaded comments

As we explain in the book, enabling threaded comments requires adding a snippet of code into your <head> area just before the wp_head tag. After a little experimenting, I discovered that you can include this snippet from the functions.php file:

// enable threaded comments
function enable_threaded_comments(){
	if (!is_admin()) {
		if (is_singular() AND comments_open() AND (get_option('thread_comments') == 1))
			wp_enqueue_script('comment-reply');
		}
}
add_action('get_header', 'enable_threaded_comments');

This helps keep your document <head> a little cleaner. Note that this function needs to be located after the jQuery-inclusion function in order for it to work.

Thanks to Peter Wilson for this awesome technique!

Remove unwanted crap from the head section

As we’ve mentioned before, WordPress spits out a ton of crap in the document <head> – stuff like the version number and WLW, RSD, and index links. To clean things up, we add this nice little snippet into the functions.php template:

// remove junk from head
remove_action('wp_head', 'rsd_link');
remove_action('wp_head', 'wp_generator');
remove_action('wp_head', 'feed_links', 2);
remove_action('wp_head', 'index_rel_link');
remove_action('wp_head', 'wlwmanifest_link');
remove_action('wp_head', 'feed_links_extra', 3);
remove_action('wp_head', 'start_post_rel_link', 10, 0);
remove_action('wp_head', 'parent_post_rel_link', 10, 0);
remove_action('wp_head', 'adjacent_posts_rel_link', 10, 0);

Add Google Analytics to the footer

Another annoying task that has to be done for all of the sites I create is adding Google Analytics code to the footer.php file. Recently it occurred to me to just add the code to my functions.php and never worry about it again:

// add google analytics to footer
function add_google_analytics() {
	echo '<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script>';
	echo '<script type="text/javascript">';
	echo 'var pageTracker = _gat._getTracker("UA-XXXXX-X");';
	echo 'pageTracker._trackPageview();';
	echo '</script>';
}
add_action('wp_footer', 'add_google_analytics');

A couple of notes here: first, obviously you want to replace the “UA-123456-1” with your actual GA code. Second, you may want to check out the three currently available Analytics options and modify the code accordingly. Currently, this function is using the newer “ga.js” tracking code, but that is easily changed to either of the other methods.

Custom excerpt length

Instead of using the default 55-word limit, this function enables you to specify any length for your excerpts.

// custom excerpt length
function custom_excerpt_length($length) {
	return 20;
}
add_filter('excerpt_length', 'custom_excerpt_length');

Just set your preferred number of words by editing the “20” to whatever you wish.

Custom excerpt “continue” string

Or whatever they call that funky bracketed ellipses thing “[...]” that is appended to your post excerpts by default. I like to remove the brackets, but with this functions.php snippet you can change it to anything:

// custom excerpt ellipses for 2.9+
function custom_excerpt_more($more) {
	return '...';
}
add_filter('excerpt_more', 'custom_excerpt_more');

/* custom excerpt ellipses for 2.8-
function custom_excerpt_more($excerpt) {
	return str_replace('[...]', '...', $excerpt);
}
add_filter('wp_trim_excerpt', 'custom_excerpt_more'); 
*/

As you can see, there are two different versions of this code, depending on your version of WordPress. We like to stay current, so we commented out the older method but left it there in case you need it. For either version of this technique, just replace the “...” with “pants on the ground” or whatever happens to suit your needs.

No “more” jumping for the “read more” link

One of the weirdest things that WordPress does is “jump” the reader to the location of the “<!--more-->” tag on the single-post-view when the “read more” link is clicked. It’s just awkward — if the jump was on the same page, it would make sense, but to load a new page and then take the reader halfway down without explaining anything is just wrong. In any case, here is a nice little function that will stop the jumping once and for all:

// no more jumping for read more link
function no_more_jumping($post) {
	return '<a href="'.get_permalink($post->ID).'" class="read-more">'.'Continue Reading'.'</a>';
}
add_filter('excerpt_more', 'no_more_jumping');
add_filter('the_content_more_link', 'remove_more_jump_link');

Nothing else needs to be done for this to work – just plug it in and enjoy your new “jumpless” functionality. Note that this is also a convenient place to customize the “read more” link with whatever attributes or custom text you wish.

Add a favicon to your blog

You just gotsta have a favicon for your blog, and this code makes it super easy to do. Just create your image and upload to site’s root directory. The following code in your functions.php file makes it so by adding the required line to your <head> area:

// add a favicon to your 
function blog_favicon() {
	echo '<link rel="Shortcut Icon" type="image/x-icon" href="'.get_bloginfo('wpurl').'/favicon.ico" />';
}
add_action('wp_head', 'blog_favicon');

Feel free to change the directory to whatever you desire. Also make sure that the wp_head is present within your theme’s header.php file.

Add a different favicon for your blog’s Admin area

While we’re here, let’s add a unique favicon to our Admin pages, so that they are easier to recognize when bookmarked or working with tabs. Just create a favicon and upload to your theme’s /images/ directory. This code takes care of the rest:

// add a favicon for your admin
function admin_favicon() {
	echo '<link rel="Shortcut Icon" type="image/x-icon" href="'.get_bloginfo('stylesheet_directory').'/images/favicon.png" />';
}
add_action('admin_head', 'admin_favicon');

As before, feel free to change the directory to whatever you desire. It might be best to keep your admin favicon in a separate directory than your blog favicon. Just sayin’.

Custom Admin Login logo

You know that snazzy blue WordPress logo that is branding your various login pages? Yeh, you can change that to whatever you want. Just create your custom login image, name it “custom-login-logo.png”, and upload it to your theme’s /images/ directory. This code will take care of the rest:

// custom admin login logo
function custom_login_logo() {
	echo '<style type="text/css">
	h1 a { background-image: url('.get_bloginfo('template_directory').'/images/custom-login-logo.png) !important; }
	</style>';
}
add_action('login_head', 'custom_login_logo');

The key here is to make sure that the path and image names match that of your setup. Also, when creating your image, you may want to keep in mind the properties of the original: 30px length, 31px height, transparent GIF format, and header background color of #464646 (for the image matte).

Disable unused widget areas

Justin Tadlock shares this handy function for removing unwanted widget areas from our theme – a must for customizing existing themes:

// disable all widget areas
function disable_all_widgets($sidebars_widgets) {
	//if (is_home())
		$sidebars_widgets = array(false);
	return $sidebars_widgets;
}
add_filter('sidebars_widgets', 'disable_all_widgets');

This code is plug-&-play – no other modifications need to be made. Note: if you only want to disable widgets on your Home page, then remove the two comment slashes (“//”) from the third line.

Kill the WordPress update nag

This is one of my favorites, but I know it’s not for everyone. In any case, you know that “Please update now..” message that appears on every page in the WordPress Admin when new versions are available? This sweet little function kills it dead (or disables it, actually):

// kill the admin nag
if (!current_user_can('edit_users')) {
	add_action('init', create_function('$a', "remove_action('init', 'wp_version_check');"), 2);
	add_filter('pre_option_update_core', create_function('$a', "return null;"));
}

Feel free to comment this one out or remove it if you rely on the Admin nag to keep you informed of changes.

Include category ID in body_class and post_class

By default, WordPress body_class and post_class do not include the ID of the category of the current post. This custom function changes all that:

// category id in body and post class
function category_id_class($classes) {
	global $post;
	foreach((get_the_category($post->ID)) as $category)
		$classes [] = 'cat-' . $category->cat_ID . '-id';
		return $classes;
}
add_filter('post_class', 'category_id_class');
add_filter('body_class', 'category_id_class');

Even if you aren’t using it, it’s a nice function to have around, which is why it’s included here for this custom functions.php template of essential functions. Keywords in the house because we can.

Get the first category ID

Another useful function when working with different categories is the ability to get the first category ID of the current post. This function makes it happen:

// get the first category id
function get_first_category_ID() {
	$category = get_the_category();
	return $category[0]->cat_ID;
}

Strictly plug-&-play: just use <?php get_first_category_ID(); ?> in your theme template file to access the data.

Putting it all together..

As promised, here is the full-meal deal – the entire collection neatly organized into a single chunk of code:

<?php // custom functions.php template @ digwp.com

// add feed links to header
if (function_exists('automatic_feed_links')) {
	automatic_feed_links();
} else {
	return;
}


// smart jquery inclusion
if (!is_admin()) {
	wp_deregister_script('jquery');
	wp_register_script('jquery', ("http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"), false, '1.3.2');
	wp_enqueue_script('jquery');
}


// enable threaded comments
function enable_threaded_comments(){
	if (!is_admin()) {
		if (is_singular() AND comments_open() AND (get_option('thread_comments') == 1))
			wp_enqueue_script('comment-reply');
		}
}
add_action('get_header', 'enable_threaded_comments');


// remove junk from head
remove_action('wp_head', 'rsd_link');
remove_action('wp_head', 'wp_generator');
remove_action('wp_head', 'feed_links', 2);
remove_action('wp_head', 'index_rel_link');
remove_action('wp_head', 'wlwmanifest_link');
remove_action('wp_head', 'feed_links_extra', 3);
remove_action('wp_head', 'start_post_rel_link', 10, 0);
remove_action('wp_head', 'parent_post_rel_link', 10, 0);
remove_action('wp_head', 'adjacent_posts_rel_link', 10, 0);


// add google analytics to footer
function add_google_analytics() {
	echo '<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script>';
	echo '<script type="text/javascript">';
	echo 'var pageTracker = _gat._getTracker("UA-XXXXX-X");';
	echo 'pageTracker._trackPageview();';
	echo '</script>';
}
add_action('wp_footer', 'add_google_analytics');


// custom excerpt length
function custom_excerpt_length($length) {
	return 20;
}
add_filter('excerpt_length', 'custom_excerpt_length');


// custom excerpt ellipses for 2.9+
function custom_excerpt_more($more) {
	return '...';
}
add_filter('excerpt_more', 'custom_excerpt_more');

/* custom excerpt ellipses for 2.8-
function custom_excerpt_more($excerpt) {
	return str_replace('[...]', '...', $excerpt);
}
add_filter('wp_trim_excerpt', 'custom_excerpt_more'); 
*/


// no more jumping for read more link
function no_more_jumping($post) {
	return '<a href="'.get_permalink($post->ID).'" class="read-more">'.'Continue Reading'.'</a>';
}
add_filter('excerpt_more', 'no_more_jumping');


// add a favicon to your 
function blog_favicon() {
	echo '<link rel="Shortcut Icon" type="image/x-icon" href="'.get_bloginfo('wpurl').'/favicon.ico" />';
}
add_action('wp_head', 'blog_favicon');


// add a favicon for your admin
function admin_favicon() {
	echo '<link rel="Shortcut Icon" type="image/x-icon" href="'.get_bloginfo('stylesheet_directory').'/images/favicon.png" />';
}
add_action('admin_head', 'admin_favicon');


// custom admin login logo
function custom_login_logo() {
	echo '<style type="text/css">
	h1 a { background-image: url('.get_bloginfo('template_directory').'/images/custom-login-logo.png) !important; }
	</style>';
}
add_action('login_head', 'custom_login_logo');


// disable all widget areas
function disable_all_widgets($sidebars_widgets) {
	//if (is_home())
		$sidebars_widgets = array(false);
	return $sidebars_widgets;
}
add_filter('sidebars_widgets', 'disable_all_widgets');


// kill the admin nag
if (!current_user_can('edit_users')) {
	add_action('init', create_function('$a', "remove_action('init', 'wp_version_check');"), 2);
	add_filter('pre_option_update_core', create_function('$a', "return null;"));
}


// category id in body and post class
function category_id_class($classes) {
	global $post;
	foreach((get_the_category($post->ID)) as $category)
		$classes [] = 'cat-' . $category->cat_ID . '-id';
		return $classes;
}
add_filter('post_class', 'category_id_class');
add_filter('body_class', 'category_id_class');


// get the first category id
function get_first_category_ID() {
	$category = get_the_category();
	return $category[0]->cat_ID;
}

?>

Download the custom functions.php template file

If you prefer, you can download this code in a ready-to-go functions.php file in zipped format:

Download zipped functions.php Template File

Also..

If this post is useful to DiW readers, I’ll be writing up another article (part 2) with even more useful custom functions. If that happens, the second set of functions will include some slightly more advanced techniques as opposed to these “must-have” template functions. Stay tuned! Update: Custom functions.php Part 2 is here!

© 2010 Digging into WordPress | Permalink | 80 comments | Add to del.icio.us | Post tags: , ,

]]> http://digwp.com/2010/03/wordpress-functions-php-template-custom-functions/feed/ 80 Which Template File does WordPress Use to Render Different Pages? http://digwp.com/2010/02/template-heirarchy-chart/ http://digwp.com/2010/02/template-heirarchy-chart/#comments Fri, 19 Feb 2010 14:34:51 +0000 Chris Coyier http://digwp.com/?p=1431 This page in the codex has a particularly interesting infographic that shows a flowchart of how WordPress chooses which template file it is going to use to render the page. For example, did you know if you have a published page with “contact” as the slug, it will look for and use page-contact.php automatically?

Unfortunately this graphic wasn’t very pretty and for some reason has a giant “Page 1″ text awkward sitting over it. We have an outdated version of this in the book, and since we are updating it right now, I thought I would take the opportunity to re-create this chart.

CLICK FOR FULL SIZE VERSION

This will also be used in the book, which should be back available for order in around a week or so! Stay tuned!

© 2010 Digging into WordPress | Permalink | 12 comments | Add to del.icio.us | Post tags: ,

]]> http://digwp.com/2010/02/template-heirarchy-chart/feed/ 12 Two Ways to Limit the Number of Posts without a Plugin http://digwp.com/2009/12/limit-posts-without-plugin/ http://digwp.com/2009/12/limit-posts-without-plugin/#comments Thu, 10 Dec 2009 13:27:10 +0000 Jeff Starr http://digwp.com/?p=1046 Let’s say your blog is set to display ten posts per page, as specified via the WordPress Admin under Settings > Reading. Once set, ten posts will appear on your home page, archive pages, search results, and so on. In other words, if it isn’t a single-view page or an actual “page” page, you’re gonna get ten posts per page. It’s a global setting.

But what if you want to display different numbers of posts for different types of page views? For example, instead of showing just ten posts on your search-results pages, you may want to show a whole bunch, like maybe fifty or something. Perhaps you would also like to limit the number of posts displayed on your category archives to only five. Of course, many of us know the easy way to do this: install Custom Query String or Custom Post Limits, tweak a few settings, and call it good. But.. this does require commitment to yet another plugin, which is a good reason for doing things the “hard” way..

Method 1

Fortunately, we can account for the latter scenario without relying on a plugin. Normally, the loop controls the number of posts displayed via the while(have_posts()) condition, as shown in this extremely boring example of a typical loop:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

	<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
	<p>?php the_time(); ?></p>
	<?php the_content(); ?>
	<p><?php the_tags(); ?></p>

<?php endwhile;?>

	<p><?php next_posts_link(); ?></p>
	<p><?php previous_posts_link(); ?></p>

<?php else : ?>

	<h1>Not Found</h1>
	<p>Silly monkey.</p>

<?php endif; ?>

What’s happening here is that we are running the loop only if we have posts, and only while the number of posts is less than or equal to the amount specified in the Admin area. Thus, limiting the number of posts is simply a matter of replacing “while(have_posts())” with something more restrictive.

There are probably a zillion ways of doing this, but the easiest that I have found is to simply setup a counter variable to keep track of each iteration of the loop. Once the counter variable reaches the specified value, the loop stops. Here’s the previous example loop showing the required modifications:

<?php $i = 1; while (have_posts() && $i < 6) : the_post(); ?>

	<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
	<p>?php the_time(); ?></p>
	<?php the_content(); ?>
	<p><?php the_tags(); ?></p>

<?php $i++; endwhile; ?>

	<p><?php next_posts_link(); ?></p>
	<p><?php previous_posts_link(); ?></p>

<?php else : ?>

	<h1>Not Found</h1>
	<p>Silly monkey.</p>

<?php endif; ?>

Notice that in the first line we are initiating the counter variable “$i” and then setting its limit at “6”. We also add “$i++;” before the “endwhile” statement to increase the count by one for each iteration of the loop. The result of these modifications is that the loop will now run only five times (as specified in the first line) instead of ten times (as specified in the WordPress Admin).

Just keep in mind that this trick only works when you want to limit the total number of posts displayed on a particular page. Even so, it is still possible to avoid a plugin by setting your default post display to something high, like 20 or 30. Then, your blog displays the highest number of posts where you want them, and everything less is customized by limiting this default number with a couple lines of code. This technique could also be useful for designing themes that required a specific number of posts displayed in certain areas of the blog.

Method 2

Or, you could just use query_posts to create a custom query and specify the showposts parameter with a value of “5” (or whatever number you wish). Here is what our original loop example looks like using the query_posts function:

<?php query_posts('showposts=5'); if (have_posts()) : while (have_posts()) : the_post(); ?>

	<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
	<p>?php the_time(); ?></p>
	<?php the_content(); ?>
	<p><?php the_tags(); ?></p>

<?php endwhile;?>

	<p><?php next_posts_link(); ?></p>
	<p><?php previous_posts_link(); ?></p>

<?php else : ?>

	<h1>Not Found</h1>
	<p>Silly monkey.</p>

<?php endif; wp_reset_query(); ?>

Notice the two additions to the original loop: in the first line, we added the query_posts function with the required posts_per_page parameter set to 5. Then, in the last line, we invoke the mystical powers of wp_reset_query to reset the original posts query. Resetting the query ensures that it’s available elsewhere in the template and is just good practice in general when using query_posts.

The pros of using query_posts to modify the number of posts is that you can go either way — you can either decrease or increase the total number of posts displayed on any page — no plugins necessary.

The cons of using the query_posts method mainly involve the disruption of the original wp_query object normally used to communicate parameters involving page, category, search, and other properties to the SQL query*. Avoiding this drama is one of the reasons why using a simple counter variable (as described in the first half of the post) is often the preferred method (multiple loops, anyone?).

*Note: It is possible to include this default information in the query_posts query, but doing so is a bit beyond the scope of this article.

© 2009 Digging into WordPress | Permalink | 18 comments | Add to del.icio.us | Post tags: , , , ,

]]> http://digwp.com/2009/12/limit-posts-without-plugin/feed/ 18 The Difference Between is_singular() and is_single() http://digwp.com/2009/10/difference-between-is_singular-and-is_single/ http://digwp.com/2009/10/difference-between-is_singular-and-is_single/#comments Mon, 26 Oct 2009 06:56:58 +0000 Jeff Starr http://digwp.com/?p=836 You know that you can target single-view pages with the conditional tag, is_single():

<?php
if(is_single()) {

	// do something

} else {

	// do something else

}
?>

This is a great way to conditionally apply styles, scripts, and markup to single-view pages.

But did you know about the conditional tag, is_singular()? The is_singular() tag enables you to target single-view pages, regular page pages, and attachment pages all in one fell swoop.

So, instead of writing something like this:

<?php
if(is_single() || is_page() || is_attachment()) {

	// do something

} else {

	// do something else

}
?>

We can write this instead:

<?php
if(is_singular()) {

	// do something

} else {

	// do something else

}
?>

The is_singular() tag is what’s known as a “boolean” function, meaning that it returns one of two values, either TRUE or FALSE. No parameters are associated with this tag.

Now you know :)

© 2009 Digging into WordPress | Permalink | 3 comments | Add to del.icio.us | Post tags: , ,

]]> http://digwp.com/2009/10/difference-between-is_singular-and-is_single/feed/ 3 Look Ma, Editable Text Regions http://digwp.com/2009/09/look-ma-editable-text-regions/ http://digwp.com/2009/09/look-ma-editable-text-regions/#comments Thu, 03 Sep 2009 15:06:53 +0000 Chris Coyier http://digwp.com/?p=622 WordPress is a CMS. The whole idea being to manage content and make websites editable without having to wrangle code. Any theme can handle Posts and Pages, but what about those “smaller” areas. Little chunks of text placed around a design like a small “about” section, or the copy in the footer of a website. A lot of times this text is hard-baked right into the theme, which isn’t a very friendly way to do things, as it can’t be updated by average Joe user.

Widgetize!

If you are looking to add text to your sidebar, and your sidebar is already widgetized, this becomes trivially easy. In your Admin, go to Appearance > Widgets and drag the “text” widget into the your sidebar area on the right. You can then open up that widget and give it a title and text and save it.

Adding Multiple Regions

There is a good chance that if your theme is widgetized, the only widgetable area is the sidebar. But you are by no means limited to having only one widgetized area. In order to add another, open your functions.php file and add another chunk of code like this:

if ( function_exists('register_sidebar') ) {
   register_sidebar(array(
       'name'=>'Footer Widgets',
       'before_widget' => '<div id="%1$s" class="widget %2$s">',
       'after_widget' => '</div>',
       'before_title' => '<h4 class="widgettitle">',
       'after_title' => '</h4>',
   ));
}

The ‘name’ part is important, because we’ll be referencing that in a sec when we drop in the widgetization code. Most of the rest of this should be pretty self-explanatory. You provide the HTML code for what wraps the text you provide for a title and body of the widget. Those weird characters as part of the ID and class actually provide some nice useful hooks for each widget. The ID is literally a unique ID for the widget, and the classes designate the type of widget being used. The end result markup for a simple text widget will be something like this:

<div class="widget widget_text" id="text-4">
   <div class="textwidget">
       <p>©2009 Digging into WordPress</p>
   </div>
</div>

As you may have gathered, we are making an editable region in our footer to house the copyright information. In our footer.php file, we’ll drop in this code in an appropriate place to widgetize the area:

<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Footer Widgets') ) : ?>
<?php endif; ?>

All goes well, we now have a new widget area showing up in our Admin, in which to drag in widgets. Drag in a text widget, and you should be all set. It should be noted that while text widgets have a title and text area, you don’t have to use both, you can use one or the other if you want.

Fairly basic stuff, but this is great stuff for allowing users to be in more complete command of their sites!

© 2009 Digging into WordPress | Permalink | 21 comments | Add to del.icio.us | Post tags: , , , ,

]]> http://digwp.com/2009/09/look-ma-editable-text-regions/feed/ 21 Getting More Fine-Grained with Includes http://digwp.com/2009/07/getting-more-fine-grained-with-includes/ http://digwp.com/2009/07/getting-more-fine-grained-with-includes/#comments Tue, 28 Jul 2009 11:56:15 +0000 Chris Coyier http://diggingintowordpress.com/?p=364 I was recently putting together a site where I found it very useful to have a number of small areas of the site as separate chunks of code I could include in templates at will. The site wasn’t unusual at all, it just never occurred to me to get this fine-grained with includes before, but I’m starting to do it now and I like it.

In my theme folder, I created a directory for “includes” which has a number of these little chunks of code:

blogtitlearea.php

On this particular site, WordPress is used to power the entire site including a blog area that exists as a sub page (i.e. /blog/). Template files that specifically had to do with the blog area needed a special header area for the blog, whereas other page templates did not. This could have been solved with some elaborate if/then logic in the header.php file, but I found it more intuitive to create a special file with this “Blog Title Area” and include it on the template files that needed it.

For example, the index.php, archive.php and single.php files include the lovely blog title area:

<?php include( TEMPLATEPATH . '/includes/blogtitlearea.php' ); ?>

Whereas the search.php, 404.php, and page templates do not.

metabar.php

Underneath the Post tiles on this site was a red bar with information about the post. The data posted, the author, the categories, the number of comments. Otherwise known as “meta” information about the post.

This same exact “metabar” is present on a number of the different template files. For example, the blog home (index.php), the category views (archive.php), and the individual Post pages (single.php). The bit of code that was creating this bar was beginning to grow rather complex. For example, on one particular category I didn’t want to show it, and there are just a lot of PHP functions needed to gather all that data. 

<?php if ((!is_category("5")) and (!in_category("5"))) { ?>
        <div class="metaBar">
		    <p class="time"><span>Posted on</span> <?php the_time('F jS, Y') ?> <span>by</span> <?php the_author(); ?> <span>in</span> <?php the_category(' '); ?></p>
		    <p class="numComments"><?php comments_popup_link('Add Comment &#187;', '1 Comment &#187;', '% Comments &#187;'); ?></p>
	</div>
<? } ?>

If I wanted to change anything, I would need to maintain it in many different places even though it is the same code. Instead of repeating myself, I just used an include:

<?php include( TEMPLATEPATH . '/includes/metabar.php' ); ?>

prevnextlinks.php

I bet you guys know what these are! Those links that show up on all kinds of different template pages to allow for going back and forward in time showing Posts.

<ul class="prev-next-links">
	<li><?php next_posts_link('&laquo; Older Entries') ?></li>
	<li><?php previous_posts_link('Newer Entries &raquo;') ?></li>
</ul>

These are commonly found on the blog home page, search pages, archive pages, and even sometimes individual post pages. If they are exactly the same on each, why not include them from one central file?

<?php include( TEMPLATEPATH . '/includes/prevnextlinks.php' ); ?>

Other ideas?

On the particular site I was working on, some of my page templates were specifically related to a “store” area of the site, so those needed to use my special “storenav.php” include. Do you guys ever use this technique? Are there other things you can think of to use this fine-grained include approach on?

© 2009 Digging into WordPress | Permalink | 25 comments | Add to del.icio.us | Post tags: ,

]]> http://digwp.com/2009/07/getting-more-fine-grained-with-includes/feed/ 25 Delicious Recipes for WordPress Page Menus and Page Listings http://digwp.com/2009/07/delicious-recipes-wordpress-page-menus/ http://digwp.com/2009/07/delicious-recipes-wordpress-page-menus/#comments Mon, 13 Jul 2009 15:01:50 +0000 Jeff Starr http://diggingintowordpress.com/?p=248 There are so many awesome ways to display your WordPress pages. Out of the box, WordPress provides two different template tags for displaying lists of your site’s pages. The first, most-commonly used tag is wp_list_pages(), and the second, lesser-known tag is wp_page_menu(). First we’ll explore the highly flexible wp_list_pages() template tag, and then we’ll dig into the new wp_page_menu() tag. Along the way, we’ll check out some delicious recipes, tips and tricks for creating the perfect WordPress Page Menu.

Digging into the wp_list_pages() template tag

Almost everyone is familiar with the wp_list_pages() template tag, and it has served us well since WordPress version 1.5. Using this tag is easy, just add the following code to your sidebar or other choice location:

<?php wp_list_pages(); ?>

And then you can customize that in many ways using the fine menu of arguments provided at its Codex Reference Page. Some of the highlights include:

Extreme Sorting Power

You can sort your pages by the descriptor of any field in the wp_post table of the WordPress database. By default, you get alphabetical by page title, but there are some other great options as well. Here are some delicious copy-&-paste recipes for your next project:

<?php wp_list_pages('sort_column=menu_order'); // sort by admin-specified order ?>
<?php wp_list_pages('sort_column=post_date'); // sort by time of page creation ?>
<?php wp_list_pages('sort_column=post_name'); // sort by name of the page slug ?>
<?php wp_list_pages('sort_column=id&sort_order=asc'); // page id in ascending order ?>
<?php wp_list_pages('sort_column=id&sort_order=desc'); // page id in descending order ?>

That first one there is a little wonky, but can prove very helpful for getting your pages to display in any order imaginable. To configure custom Page order to display via the menu_order parameter, you simply assign each Page a numerical value in its Write/Edit Admin screen. You can see a full list of available descriptors here.

Include and Exclude Anything

WordPress makes it easy to include and exclude any pages to create the perfect page menu. By default, the wp_list_pages displays all pages, but this is easily customized with three useful arguments:

<?php wp_list_pages('exclude=1,2,3'); // exclude only these three page ids ?>
<?php wp_list_pages('include=1,2,3'); // include only these three page ids ?>
<?php wp_list_pages('exclude_tree=1,2,3'); // exclude these parent pages and all children ?>

The exclude_tree parameter is new as of WordPress version 2.7. It makes it super-easy to omit an entire branch of pages (the parent page and all descendant pages) from your page listings.

Control the Depth of Pages

There are two parameters designed to control the depth of pages displayed by the wp_list_pages() tag. The first is the depth parameter, which by default displays all subpages, regardless of depth. There is also the child_of parameter, which defaults to a value of 0 to display all pages and subpages. Here are some recipes to customize these default values:

<?php wp_list_pages('depth=0'); // display all pages and subpages via indented lists ?>
<?php wp_list_pages('depth=-1'); // display all pages and subpages without indentation ?>
<?php wp_list_pages('depth=1'); // display only top-level pages ?>
<?php wp_list_pages('depth=2'); // display all pages and first level subpages ?>
<?php wp_list_pages('depth=n'); // display all pages and subpages to the nth level ?>

<?php wp_list_pages('child_of=0'); // displays all pages and subpages ?>
<?php wp_list_pages('child_of=3'); // displays all subpages of page with id 3 ?>

The child_of parameter is a great way to display sub-menus of specific pages, for example for implementation of drop-down menus and so forth. Note that multiple instances of wp_list_pages() may be used on any given web page.

Use with Custom Fields

Here is an extremely powerful way to customize your page menus using custom-field values. Using meta_key and meta_value parameters, you can tell WordPress to display only those pages that contain specific custom-field key/value pairs. Here are some examples:

<?php wp_list_pages('meta_key=menu&meta_value=page'); // display pages with menu/page custom field ?>
<?php wp_list_pages('meta_key=icon&meta_value=true'); // display pages with icon/true custom field ?>

This parameter also gives you the flexibility of modifying page listings without having to touch any source code. Great for clients and family members who may not feel comfortable “digging in” ;)

Even more functionality (new in WordPress 2.7 & 2.8)

WordPress recently rolled out some new tricks for the wp_list_pages() tag. Namely, we now have the ability to wrap the anchor text of our page listings with any HTML or text. Other new features include the number of pages to display as well the number of pages to pass over when displaying page listings. Let’s have a look:

<?php wp_list_pages('link_before=<span>&link_after=</span>'); // wrap anchor text with a span tag ?>
<?php wp_list_pages('number=7'); // display only the first seven pages ?>
<?php wp_list_pages('offset=7'); // skip the first seven pages ?>

A complete copy/paste recipe for wp_list_pages()

There are several more useful parameters for the wp_list_pages() tag, but rather than explaining each one, I will refer you to the Codex for all the boring details. So now, before digging into the juicy stuff, here is a “super-delicious” tag recipe equipped with every possible parameter, especially designed for easy customization:

<?php wp_list_pages('sort_column=post_title&sort_order=asc&exclude=0&exclude_tree=0&include=0&depth=0&child_of=0&show_date=&date_format=&title_li=&echo=1&meta_key=menu&meta_value=page&link_before=<span>&link_after=</span>&authors=0&number=0&offset=0'); // contains all parameters as of version 2.8 ?>

Alright, enough of the basics, let’s explore some truly delicious page-listing recipes.

List all subpages of current page

Here is a way to simplify your sidebars and overall page designs. Instead of listing every subpage on all of your site’s web pages, you can dynamically display subpages only when the visitor is viewing the parent page. So for example, your homepage sidebar would list all of your parent pages, and then each of the parent pages would display a list containing all of its subpages. Here’s one way to do it, as demonstrated in the Codex:

<?php 
$children = wp_list_pages('title_li=&child_of='.$post->ID.'&echo=0');
if ($children) { ?>
	<ul>
		<?php echo $children; ?>
	</ul>
<?php } ?>

Placed in your theme template file, this code will generate a list of all subpages for the current parent page. If there are no subpages, nothing will be displayed.

As is, this method will only display the subpages when visiting the parent page, but we can modify the code so that all subpages are displayed when visiting either the parent page or any of the subpages:

<?php
if($post->post_parent)
	$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");
else
	$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
if ($children) { ?>
	<ul>
		<?php echo $children; ?>
	</ul>
<?php } ?>

And you can do even better than that. With this next method, your page listings will be displayed as follows:

  • When visiting main page, all top level pages are listed in the sidebar.
  • When visiting a top level page with no children, all top level pages are listed.
  • When visiting a top level page with children, just the children pages, and descendant pages, are listed.
  • When visiting a child page, just the children, and descendant pages, of that parent, are listed.
<?php
$output = wp_list_pages('echo=0&depth=1&title_li=<h2>Top Level Pages</h2>' );
if (is_page( )) {
	$page = $post->ID;
	if ($post->post_parent) {
		$page = $post->post_parent;
	}
	$children=wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=' );
	if ($children) {
		$output = wp_list_pages ('echo=0&child_of=' . $page . '&title_li=<h2>Child Pages</h2>');
	}
}
echo $output;
?>

All this is great, but it’s also helpful to know how to style the markup generated by the wp_list_pages() template tag. Let’s look at that next..

Styling wp_list_pages() markup

Here is the default markup generated by the wp_list_pages() template tag (assuming a total of five pages with the current page having an ID of “1”):

<li class="pagenav">Pages
	<ul>
		<li class="page-item-1 page_item current_page_item">Page ID 1</li>
		<li class="page-item-2 page_item">Page ID 2</li>
		<li class="page-item-3 page_item">Page ID 3</li>
		<li class="page-item-4 page_item">Page ID 4</li>
		<li class="page-item-5 page_item">Page ID 5</li>
	</ul>
</li>

You can strip the outer <li class="pagenav"> and the enclosing <ul></ul> tags by including “title_li=” (empty string) as a parameter in the wp_list_pages() template tag. You may also keep these outer tags and customize the “Pages” text with whatever markup and/or text you need. Instead of an empty string, use something like “title_li=<h2>Pages</h2>” instead. Note also that specific class attributes will be applied to both parents and ancestors of the current page (see next section).

Styling page menus generated by wp_list_pages()

Here is a list of the selectors available for styling your page menus:

.pagenav {}               /* li tag containing page menu */
.page_item {}             /* inlcuded on every page item */
.page-item-n {}           /* specifies page with id of n */
.current_page_item {}     /* specifies the current page */
.current_page_parent {}   /* any parent of current page */
.current_page_ancestor {} /* any child of current page */

Now, ready for some new stuff? Brace yourself..

Digging into the wp_page_menu() template tag

So what about this new wp_page_menu() template tag? With all of the flexibility of wp_list_pages(), why is it necessary? In a nutshell, wp_page_menu() is a simplified version of wp_list_pages(). In addition to accepting a few of the same parameters, this new tag brings one new trick to the table: it provides the ability to add your site’s Home page to the list of Pages displayed. This tag was introduced in WordPress version 2.7, and, in my opinion, should have been integrated into the existing Page-listing template tag. In any case, for those looking for an easy way to include your Home page into the list of Pages, here you go:

<?php wp_page_menu(); ?>

As mentioned, most of the parameters are the same as before. Here is a list of common parameters:

  • sort_column
  • include
  • echo
  • link_before
  • link_after

And — drum roll please — here are the new parameters: menu_class and show_home! Let’s check ‘em out..

menu_class

This is a no-brainer. It simply specifies the class attribute for the surrounding <div>. Yes, the list is wrapped in a division. Any string may be used, here is an example:

<?php wp_page_menu('menu_class=pages'); // wrap list in div with class="pages" ?>

show_home

Ahh, the long-awaited “include-the-home-page” functionality. Now, instead of hacking your client’s functions.php file to include the Home Page in the main menu, you can simply do this instead:

<?php wp_page_menu('show_home=1'); // include the home page in the list ?>
<?php wp_page_menu('show_home=0'); // exclude the home page in the list ?>

By default, this parameter returns false and no Home Page is displayed. When set to true, the Home Page will be displayed as the first item in the page list. The URL for the Home Page is taken from the value for your site’s “Blog address”, as specified in the WordPress Admin under Settings > General.

When the Home Page is displayed, the default anchor text is simply “Home”, but you can customize that to whatever you want by specifying such for the parameter value:

<?php wp_page_menu('show_home=Digging%20into%20WordPress'); // include the home page ?>
<?php wp_page_menu(array('show_home'=>'Digging into WordPress', 'sort_column'=>'menu_order')); // include the home page ?>

For more information on this new tag, check it out at the WordPress Codex

Take-home message

WordPress provides two different ways to list your pages: wp_page_menu() and wp_list_pages(). The wp_list_pages() tag is powerful, flexible and fully functional. So, unless you need to include your Home Page, your best bet is always wp_list_pages(). For page menus that include the Home Page, you will need to use wp_page_menu() instead. Beyond listing your Home Page, the wp_page_menu() can do a few things, but nothing that wp_list_pages() can’t already handle.

My question for the day is: Why wasn’t the home-page functionality integrated into the existing tag? Why complicate things with an otherwise redundant tag? Share your thoughts!

© 2009 Digging into WordPress | Permalink | 59 comments | Add to del.icio.us | Post tags: , ,

]]> http://digwp.com/2009/07/delicious-recipes-wordpress-page-menus/feed/ 59 Free HTML 5 WordPress Theme http://digwp.com/2009/07/free-html-5-wordpress-theme/ http://digwp.com/2009/07/free-html-5-wordpress-theme/#comments Wed, 01 Jul 2009 07:19:43 +0000 Jeff Starr http://diggingintowordpress.com/?p=215 In an effort to inspire more WordPress theme designers to embrace HTML 5, I am releasing the “H5” Theme Template. The H5 Theme Template is a bare-bones WordPress theme built entirely with HTML 5 and styled with CSS 2.1. As you may know, HTML 5 provides greater flexibility and interoperability than previous markup languages, and enables us to build well-structured themes that are more flexible, interactive, and semantically precise.

About the ‘H5’ WordPress Theme Template

The H5 Theme Template provides everything you need to create beautiful themes with HTML 5 right now. H5 contains a complete set of theme files and folders, and each file has been meticulously crafted with all of the latest and greatest WordPress functionality. As a template theme, H5 is designed with easy customization and personalization in mind, serving as a solid starting point for your next HTML-5-based theme.

Unlike other frameworks, H5 works great as a basic theme right out of the box. Of course, this is a template theme we’re talking about here, so you will inevitably feel “inspired” to begin tweaking and styling its minimalistic appearance to get the design looking exactly how you want it. And that is entirely the point: H5 makes it quick and easy to begin designing themes with HTML 5. And best of all, H5 is completely free. Sound good? Great, let’s dig into the specifics..

‘H5’ Specifications

First, thanks for your interest in the H5 Theme Template. I am very excited to be sharing this theme with the WordPress community and hope that you will put it to good use. Next, three important points that I would like to emphasize:

  • H5 is completely free and licensed under GPL
  • H5 is a template used to build HTML-5 themes
  • H5 is built entirely with WordPress, HTML 5, and CSS 2.1

About the markup

  • Uses as few tags and attributes as possible
  • Contains no <div>s, <span>s, classes, or ids!
  • Built with semantically sound and fully valid HTML 5
  • Outputs clean, well-formatted source-code (although WordPress botches most of it)

About the CSS

  • Just enough CSS to target key elements, provide some structure, and make it “look” like a basic theme
  • Built with well-formatted and fully valid CSS 2.1 (current spec)
  • Uses child, adjacent, and attribute selectors to target elements without ids or classes

About the JavaScript

  • Uses only unobtrusive JavaScript
  • Uses createElement() to specify block elements for Internet Explorer
  • Includes WordPress’ jQuery script the right way

About the design

  • Includes minimal markup and styles for easy customization
  • Features a full set of theme template files and common folders
  • Very minimal, meant to do just the basics and serve as a starting point
  • Uses default and/or standard WordPress template tags, loops, and other functions
  • Looks and works great out of the box in (almost) all modern browsers (see next section)
  • Designed to be as lightweight and fast as possible — only essential tags are included

Browser compatibility

H5 looks and works great in the following browsers (and most likely others as well):

  • Firefox 3
  • Opera 8*
  • Opera 9
  • Chrome 1 & 2
  • Safari 2, 3, & 4
  • Internet Explorer 7*
  • Internet Explorer 8

* Denotes slight inconsistencies in these browsers.

For Firefox 2, Camino 1.6, and IE 6, the HTML seems to work great, it’s just some of the “advanced” CSS selectors that some browsers don’t understand. This is easily handled by simply adding a few choice id or class attributes to key elements (none are used by default).

Download and Demo

For a “live” demo of the H5 Template Theme, check out our newly revamped DiW Theme Playground, where we will be hosting any themes that we release here at Digging into WordPress.

At the DiW Theme Playground you will find a dropdown menu at the top of the browser window that enables you to preview any of our themes, as well as a download link for whichever theme happens to be active (Chris’ excellent WP Typo is the default active theme).

© 2009 Digging into WordPress | Permalink | 40 comments | Add to del.icio.us | Post tags: , , ,

]]> http://digwp.com/2009/07/free-html-5-wordpress-theme/feed/ 40