So because frameworks have all these helper functions, they are targeted at people who don’t want to learn how to do all that stuff themselves, but still harness all that power. In other words, non-nerds. These helper functions are used by hand-altering theme files, which is inherently nerdy. So frameworks are for non-nerds, but the only people that know about them (and especially how to use them), are nerds.

Or am I full of crap?

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 66 comments | Add to Delicious
Categorized: Theme, Uncategorized | Tagged: discussion, frameworks

• 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 (“<” & “>”).

// 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!

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 17 comments | Add to Delicious
Categorized: Design, Theme | Tagged: functions, template, Theme

• 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');

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!

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 80 comments | Add to Delicious
Categorized: Design, Theme | Tagged: functions, template, Theme

<?php comments_template(); ?>

That line basically calls/includes your comments.php file. Within that, the line to output all comments is something really simple like this:

<ol class="commentlist">
   <?php wp_list_comments(); ?>
</ol>

But that doesn’t leave much by way of customizing the HTML that gets output, does it? Fortunately it’s fairly easy to specify your own formatting in a non-destructive non-core-altering way. Although personally, I’m having one little issue with it. Let’s take a look.

Why would you need this?

This is what you get as the defacto standard comment output:

This is from the new 2010 theme slated to come out with WordPress 3

But what if you wanted something more like this?

From a new client site I’ve been working on

The best way to get into that new skin is to get your hands on the HTML, as CSS alone isn’t quite going to get us there.

Custom output through a callback function

The trick is is that the wp_list_comments function accepts a parameter for a callback function. This function overrides what the output of each comment will be. Here is an example of that:

<ol class="commentlist">
    <?php wp_list_comments('type=comment&callback=format_comment'); ?>
</ol>

The above code will only output “comments” (and not trackbacks or pingbacks) and will call a custom function “format_comment” for formatting the comment. This function needs to be built in your functions.php file, and better be present before you call this function otherwise you’ll throw an error.

The callback function is completely in charge of the comment formatting. It could be something completely whacky like this:

<?php
    function format_comment() {  ?>
           <li>This is whack, yo.</li>
   <?php } 
?>

Which would return that ridiculous sentence for every single comment, instead of the actual comment. Of course you wouldn’t (probably) ever do that. What you probably want to do, is just adjust how the different standard comment-related data is output. To do that, first you pull in the comment globals, then you can use all the comment functions that return the stuff that you probably want:

• get_comment_link
• get_comment_author
• get_comment_date
• get_comment_time
• get_comment_text
• etc.

Here is a customized formatting function I recently used:

<?php

    function format_comment($comment, $args, $depth) {
    
       $GLOBALS['comment'] = $comment; ?>
       
        <li <?php comment_class(); ?> id="li-comment-<?php comment_ID() ?>">
                
            <div class="comment-intro">
                <em>commented on</em> 
                <a class="comment-permalink" href="<?php echo htmlspecialchars ( get_comment_link( $comment->comment_ID ) ) ?>"><?php printf(__('%1$s'), get_comment_date(), get_comment_time()) ?></a>
                <em>by</em> 
                <?php printf(__('%s'), get_comment_author_link()) ?>
            </div>
            
            <?php if ($comment->comment_approved == '0') : ?>
                <em><php _e('Your comment is awaiting moderation.') ?></em><br />
            <?php endif; ?>
            
            <?php comment_text(); ?>
            
            <div class="reply">
                <?php comment_reply_link(array_merge( $args, array('depth' => $depth, 'max_depth' => $args['max_depth']))) ?>
            </div>
        
<?php } ?>

When NOT to customize output

Remember that CSS is quite the handyman at whipping things into shape. Let’s say your goal was to get rid of the gravatars that the default comment formatting outputs. Well that’s as simple as:

.avatar { display: none; }

And with more powerful tools like absolute positioning, you can take the default output and really do a ton of customization. There are some times though, when you need to alter the HTML to do it right, and that’s when all this is useful.

My little problem

My custom output works really well, save for one little problem. That is nested replies. The WORK, it’s just the output is invalid, as nested lists sit directly within the list above it instead of being wrapped in a list item like they should be. See:

I’m not quite sure how to fix that, although I imagine it can be done within the custom function somehow? If anyone knows, let me know.

Update

It was my mistake, although in my defense, the answer is a little weird. What you need to is OMIT the closing </li> tag in the callback function. WordPress will add that automatically for you.

In other news, if you find your callback function breaks the “Reply” button functionality, take a look at the add_below parameter:

<?php comment_reply_link(array_merge( $args, array('reply_text' => 'Reply', 'add_below' => $add_below, 'depth' => $depth, 'max_depth' => $args['max_depth']))); ?> 

That parameter takes a string, like “div-comment” for example, and then the reply links on each comment will be looking for the page element of “div-comment-XXXX” to jump the comment form up to (where XXXX is the ID of the comment). So your theme better have page elements with matching ID’s, or the reply link will “fail” and reload the page. I say “fail” in quotes because replying will still work, it just doesn’t do the cool jump-up technique which is the whole point of the comment-reply.js file that most themes load on single pages.

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 14 comments | Add to Delicious
Categorized: Theme | Tagged: comments, functions, PHP, Theme

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!

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 12 comments | Add to Delicious
Categorized: Theme | Tagged: template, Theme

I have a “blank” WordPress theme for myself, because I make a lot of WordPress themes. Starting from Kubrick, or any other pre-made theme, would be absurd. There is to much stuff there that would to be stripped out or fought against to be useful. So, I have my own. It’s been in a folder called BLANK-theme on my computer for a while, so I’m going to call it BLANK. And now I’m making it available for you. Read on to find out the scoop on it and you can decide if it would be of any use to you.

What is BLANK?

It is a WordPress theme with all the functionality of a typical WordPress theme but almost none of the styling. The idea is that when starting a new theme, it is far easier to use this as a base then a theme that is already finished and styled.

What are some of it’s “features”?

• Things are as semantically marked up as can be for a starter theme.
• It’s XHTML 1.0 STRICT and validates. Maybe it will go HTML5 soon. We’re at that point where there isn’t a whole ton of advantages to going to HTML5 yet, but there aren’t many downsides either and it’s definitely the future.
• The sidebar is widget-ready.
• Page titles are optimized for best SEO and readability/usability.
• Functions.php file does a number of things: Sets up RSS <link>’s in the head automatically, loads jQuery, removes the weird header links like rsd_link, wlw manifest, and generator info that I’ve never once needed, and registers the sidebar widget area.
• Has some starter CSS ready to go, more about that below.

Uses includes for some key things, like under-title meta data and forward/back navigation, that are very common places for redundant code in themes.

About the CSS

As you can see from the screenshot above, the CSS is pretty baron, but not entirely! Here are some things the CSS is set up for:

• Uses a basic star-selector reset.
• Includes a .group selector for the new clearfix
• Has basic toolbox and WordPress-standard CSS classes, including .screen-reader-text for hiding things.
• Standard typography-related sectors are there but generally without any attributes.
• CSS for threaded comments is in there, but light on actual styling.
• Both screen and print styles included in single stylesheet. Print styles optimized for generic nice printing.

Demo and Download

If you want to take a peak at it live, you can view it in our Theme Playground. You can also download it from there, or directly right here.

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 58 comments | Add to Delicious
Categorized: Theme | Tagged: CSS, free, Theme

Widgetize Your WordPress Theme: Step 1

Make a fist and howl at the monitor. Then place this code into your active theme’s functions.php file:

if (function_exists('register_sidebar')) {

	register_sidebar(array(
		'name' => 'Widgetized Area',
		'id'   => 'widgetized-area',
		'description'   => 'This is a widgetized area.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));

}

This is all that is needed for the first step. Once this widgetizing code is placed in your functions.php file, proceed to Step 2. The remainder of this section is explanation.

This code checks to make sure that the current version of WordPress supports widgets, and then declares an array of values that will be used to create the widgetized area in your theme. Here are the different values:

• name – the name of the widgetized area as displayed in the WP Admin
• id – a unique identifier for your widgetized area
• description – description of the widgetized area
• before_widget – the markup generated before any user-added widgets
• after_widget – the markup generated after any user-added widgets
• before_title – the markup generated before the title of any user-added widgets
• after_title – the markup generated after the title of any user-added widgets

So, given these parameters, our widgetizing code would result in the following output, say, if the built-in Search widget were added to our widgetized area:

<div id="search-3" class="widget widget_search">
	<h4>Search</h4>
	<form role="search" method="get" id="searchform" action="http://localhost/283/" >
		<div>
			<label class="screen-reader-text" for="s">Search for:</label>
			<input type="text" value="" name="s" id="s" />
			<input type="submit" id="searchsubmit" value="Search" />
		</div>
	</form>
</div>

Note the markup created for the opening <div>, which gets its attribute information based on the wild-card matching specified in our widgetizing array. To see this more clearly, examine the following side-by-side comparison of the sprintf directives and the resulting (X)HTML source code:

'before_widget' => '<div id="%1$s" class="widget %2$s">',
<div id="search-3" class="widget widget_search">

Hopefully the relationship is clear. This is a powerful way to ensure that all widgets have a similar class names and unique IDs, which are important for easy CSS styles.

Let’s continue with Step 2..

Widgetize Your WordPress Theme: Step 2

Finally, add the following code to the location in your theme’s template file(s) where you would like the widgetized area to appear:

<div id="widgetized-area">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('widgetized-area')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Area</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>

With both steps complete, your theme should now feature a widgetized area in the location of your choosing. Nothing else needs to be done at this point. If you get it, then get to it and continue developing your theme. For more information and some juicy tips and tricks, continue reading.

Let’s examine the code used in this second step. Everything located between the if/endif statements will be output to the browser when no widgets have been activated. This is a good place to inform the user that the area is widgetized and may be customized via the Widgets area in the WordPress Admin. I also include a “pre-widget” class to help style the pre-widget area. With multiple widgetized areas on a page, having a class name to hang styles on is super nice.

Also, note that we are using the id specified in the widgetizing array (refer to Step 1) as the parameter value for the specific dynamic_sidebar() check in the third line.

Multiple widgetized areas

So we now have a nice, widgetized sidebar. But why stop there? Implementing additional widgetized areas is as simple as replicating the code in Step 1 and Step 2. For example, let’s say we wanted to widgetize the header, sidebar, and footer areas of our theme. We would be put this in our functions.php file:

if (function_exists('register_sidebar')) {

	register_sidebar(array(
		'name' => 'Header',
		'id'   => 'header',
		'description'   => 'This is the widgetized header.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));
	register_sidebar(array(
		'name' => 'Sidebar',
		'id'   => 'sidebar',
		'description'   => 'This is the widgetized sidebar.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));
	register_sidebar(array(
		'name' => 'Footer',
		'id'   => 'footer',
		'description'   => 'This is the widgetized footer.',
		'before_widget' => '<div id="%1$s" class="widget %2$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));

}

..and then we would place the following code chunks into their respective locations within our theme template files:

<div id="widgetized-header">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('header')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Header</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>
<div id="widgetized-sidebar">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('sidebar')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Sidebar</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>
<div id="widgetized-footer">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('footer')) : else : ?>

	<div class="pre-widget">
		<p><strong>Widgetized Footer</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>

That’s all there is to it. Of course, you’ll probably want to tweak the details to suit your specific needs, but these two steps are all you need to widgetize your WordPress theme. Now let’s wrap things up with some juicy widgetizing tricks..

Some Juicy Widgetizing Tricks

Here are some sweet little tips for widgetizing your theme:

Streamline & organize custom widgets

The first thing that I do after widgetizing a new theme is to include a separate “widgets.php” that contains all of the custom widgets. A simple line of code is all that is required to acheive this functionality:

if ($wp_version >= 2.8) require_once(TEMPLATEPATH.'/widgets.php');

Place that code into your functions.php file and place all of your widgets into a file called widgets.php. Once in place, this method will ensure that your widgets are loaded and available for all supportive versions of WordPress. This is a great way to keep your theme files nice and organized.

Replace WordPress’ default widgets

Many of the default WordPress widgets leave something to be desired. Fortunately, it’s super-easy to override any of the default widgets with your own creations. For example, here is one way to replace the default Search Widget with your own version:

<?php function custom_search_widget() { ?>

<form action="http://localhost/283/index.php" method="get">
	<div>
		<label for="s">Site Search</label>
		<input id="s" name="s" alt="Search" type="text" />
	</div>
</form>

<?php } if (function_exists('register_sidebar_widget'))

register_sidebar_widget(__('Search'), 'custom_search_widget'); ?>

Hide unused widget areas

An empty widgetized area of your theme can look strange, especially when CSS styles are applied to the container element. To prevent this from happening, we can wrap each of our widgetized areas with the following code:

<?php if (function_exists('is_sidebar_active') && is_sidebar_active('sidebar')) { ?>

<!-- code from Step 2 or whatever you want -->

<?php } ?>

With this conditional code, widgetized areas will only be displayed if they contain at least one active widget. Nice :) Also note that this conditional technique works for displaying things other than widgets.

More..?

Hopefully this easy two-step widgetizing guide will be useful for you during your next round of theme development. As always, if you know of any other sweet widgetizing tricks, please share them in the comments!

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 24 comments | Add to Delicious
Categorized: PHP, Theme | Tagged: PHP, Theme, widgets

Our personal collection of useful ways to customize and format the WordPress more tag…

Everyone who has been using WordPress for any length of time should be familiar with the <!--more--> tag. When you are writing a post, inserting the <!--more--> tag within the post text will create an excerpt out of any text/markup that precedes it. The post will then show the default “more…” link that readers may click to view the entire post. When the more tag is used, the post’s excerpt will be displayed on all non-single views, such as category, tag, and archive views; the entire post content will only be displayed when the single-post view is displayed. Let’s look at a quick example..

A quick example of how to use the more tag

If you have the following post text:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio. 
Quisque volutpat mattis eros. Nullam malesuada erat ut turpis mattis.
Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.

<!-more->

Phasellus ultrices nulla quis nibh. Quisque a lectus. Donec consectetuer 
ligula vulputate sem tristique cursus. Nam nulla quam, gravida non dolor, 
commodo a semper suscipit, sodales sit amet, nisi adipiscing.

..your post will show this on all non-single post views:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio.
Quisque volutpat mattis eros. Nullam malesuada erat ut turpis mattis.
Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.

more…

..and this on all single-post views:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio.
Quisque volutpat mattis eros. Nullam malesuada erat ut turpis mattis.
Suspendisse urna nibh, viverra non, semper suscipit, posuere a, pede.

Phasellus ultrices nulla quis nibh. Quisque a lectus. Donec consectetuer
ligula vulputate sem tristique cursus. Nam nulla quam, gravida non dolor,
commodo a semper suscipit, sodales sit amet, nisi adipiscing.

..which basically shows the entire post without the more link.

Why do we use the more tag?

Well mostly because excerpts are cool, and you can display many of them on your home page to give visitors a good overview of your content without making them scroll forever to do so. If one of your excerpts catches the visitor’s eye, they will most likely want to read the entire post, and can do so by clicking on the link created by the more tag. To help encourage this behavior, there are several ways to customize the more link text, depending on your specific design goals. Let’s take a look..

Customize the more link text on a post-by-post basis

There are a couple of good ways to customize the output format of your more link text. By far, the easiest way is to simply include your custom text right there in the more tag within your post text. For example, if you wanted to change your more text from the default to “Keep reading this post”, you would replace the usual <!--more--> tag with this:

<!--more Keep reading this post-->

This way, WordPress makes it easy to customize any post’s more link with unique text. This is one of those sweet WordPress secrets that not many people know about, as evidenced by the popular alternative method for customizing per-post more text:

<?php $custom_more = get_post_meta($post->ID, "custom_more_text", true);
if(!$custom_more) { $custom_more = "Keep reading this post &raquo;"; }
the_content($custom_more); ?>

This code looks for a custom field named “custom_more_text” and displays its value as the post’s custom more text. But again, this is complete overkill thanks to the previous method.

Customize the more link text on a sitewide basis

Instead of customizing individual more text, we can also customize it for all posts on a sitewide basis. The first and easiest way to change the default more link text is to simply add your custom text to the_content() template tag:

<?php the_content('Keep reading this post'); ?>

You can even add markup to help format and style the output according to your needs:

<?php the_content("<span class="custom-more">Keep reading this post</span>"); ?>

I think most WordPress peeps are familiar with this method and use it frequently. But there is also a newer method for accomplishing the same thing from the functions.php file. As of WordPress 2.8, we now may filter sitewide more links using the new filter hook, the_content_more_link:

function my_more_link($more_link, $more_link_text) {
	return str_replace($more_link_text, 'Keep reading this post', $more_link);
}
add_filter('the_content_more_link', 'my_more_link', 10, 2);

That goes into your theme’s functions.php file. Simply edit the “Keep reading this post” string to whatever you would like to use for your custom more text. This is a good way to change your theme’s more text without modifying any theme template files — perfect for customization via child themes! Check out Justin Tadlock’s article for more information.

Automatically display the post title in more links

Another cool more-tag trick is to include the post title in the more link text. For example, we might want to setup something like this:

Lorem ipsum..

Continue reading “Lorem Ipsum Strikes Back”

Including the post title into your more links is a great way to personalize each excerpt with a little “more” (haha). Anyway, here is how the Codex suggests doing this:

<?php the_content("...continue reading the story called " . get_the_title('', '', false)); ?>

That’ll work, but we can clean it up a little like so:

<?php the_content(the_title('Continue reading &ldquo;','&rdquo;',false)); ?>

That’s a tight little snippet that will generate custom more links that include the title of the associated post. Nice.

Stop more link from jumping to middle of page

By default, clicking on the more link will take the reader to the single-post view at the location where the more tag is specified in the source code. Thus, if you are using default more-tag functionality, your visitors are being thrown halfway-down your post after clicking on the more link. At one time, this seemed like a good idea, but the convention is now to simply open the post-view without jumping to any particular point in the page.

All of that to say this: if you want the more link to open the post-view at the top of the page, slap this little gem into your active theme’s functions.php file:

function remove_more_jump_link($link) { 
	$offset = strpos($link, '#more-');
	if ($offset) {
		$end = strpos($link, '"',$offset);
	}
	if ($end) {
		$link = substr_replace($link, '', $offset, $end-$offset);
	}
	return $link;
}
add_filter('the_content_more_link', 'remove_more_jump_link');

This will kill the more “jump” and keep visitors from being thrown around the page unexpectedly. Note that this function is only for WordPress version 2.8 and better. For older versions, you’re gonna need to hack the core. See the Codex for more information.

Target custom pages with the more tag

The typical use of the more tag is such that its link opens the single-view of the associated post. This may be changed, however, should you ever need to target a different web page. To understand this a bit better, consider the parameters available to the_content() template tag:

<?php the_content($more_link_text, $strip_teaser, $more_file); ?>

Here, the $more_link_text parameter defines the text that will be used for the more link. The $strip_teaser parameter defines a boolean value determining whether or not to display the more link. The third parameter is the one we’re interested in here. The $more_file parameter specifies the URL that the more link should reference. By default, this URL points to the associated single-view post, but we could just as easily customize this like so:

<?php the_content('Order Now!', FALSE, 'http://amazing-product.com/order-page.html'); ?>

Or whatever. Obviously, the uses for this are limited, but it’s there if you ever need it.

Styling the more link

The easiest way to style the more tag is to take advantage of the built-in class attribute, more-link. By default, this class is automatically included on every WordPress more link in the entire world. Thus, you can apply styles directly, for example:

.more-link {
	border: thin solid black;
	letter-spacing: 1px;
	background: yellow;
	font-size: 24px;
	color: red;
	}

If you need additional control, you may also incorporate custom markup to your more link via the_content() template tag:

<?php the_content("<span class="custom-more">Keep reading <em>this</em> post</span>"); ?>

Which would output markup such that the following CSS could be applied:

.custom-more {
	font-weight: bolder;
	}
	.custom-more em {
		font-weight: normal;
		font-style: italic;
		}

Obviously, this is just a simple example to help illustrate the method. Just about anything is possible!

Adding an image to your more link

Last but not least, let’s wrap up the article with a couple of ways to add an image to your more link. The first way to do it is to simply include the image element directly in the_content() template tag:

<?php the_content('<img src="http://domain.tld/read-more.png" alt="Arrow" title="Read more" />'); ?>

This will spit out an image for your more tag instead of text. You could also add in some text, but if you don’t be sure to include the alt and title attributes for the <img> element. Either way, you can also style your “Read more” image using some CSS, or even bypass the <img> element completely and add an image using a few lines of CSS:

.more-link img {
	background:url(http://domain.tld/read-more.png) no-repeat left center;
	padding: 10px;
	height: 100px;
	width: 300px;
	}

Again, just an example demonstrating how it works. The possibilities here are virtually infinite.

“I give myself a B+”

It would have been an “A”, but I just know there are more cool things you can do with the WordPress more tag. This article shares all of the cool tricks that we know, but there’s just got to be more sweet tips! Hopefully you know of some more more tricks to share with the WordPress community ;) – Chime in!

Like the article? Get the book!

© 2010 Digging into WordPress | Permalink | 26 comments | Add to Delicious
Categorized: Theme | Tagged: more-tag, tips, tricks

• All visitors will see the current theme
• Only the designer will see the new theme
• All site plugins will work with the new theme
• Smooth transition between old and new theme at launch

These are the main concerns, but there are a few other details that need addressed to ensure smooth theme development on a live site. Let’s take a look at how to achieve these goals and effectively develop themes behind the scenes..

You need a plugin

The easiest way to develop a new theme behind the scenes is to install a good theme-switcher plugin. There are plenty available:

• Theme Switcher
• Theme Switcher Reloaded
• Alternative Theme Switcher
• Theme Preview
• Theme Test Drive
• NK Theme Switch

Any of these plugins will work fine for the purposes of working with multiple themes on your site. If you also plan on enabling your visitors to switch themes, I would have to recommend the newer NK Theme Switch plugin. NK Theme Switch does everything the other plugins can do, but with the added bonus that it redirects users back to the page from which they came after switching themes. The other two plugins switch themes, but the user is always redirected back to the home page after the theme switch.

Note that, for the different theme-switcher plugins, the URLs used when switching themes include different query-string parameters that are similar but not interchangeable. Once you implement a theme switcher, replacing it with a different plugin is going to be difficult.

In any case, once you have your theme-switcher plugin of choice activated, you’re going to need to know how to actually switch the themes..

Switching themes

Different plugins involve different methods of switching to a different theme. If you are using NK Theme Switch, you can select and activate your alternate (development) theme from within the WordPress Admin. This is the easiest way to do it. If you are using one of the other theme-switching plugins, activating the alternate theme for your browser is as easy as entering a specific URL into the address bar. These theme-switching URLs look similar for either of the first two plugins:

http://domain.tld/index.php?wptheme=ThemeName

For example, here is the URL used to switch to one of my favorite themes at Perishable Press:

http://perishablepress.com/press/index.php?wptheme=Perishable

The syntax here is straightforward — the only thing that needs to be changed is the theme name, which in this case is “Perishable”. When developing a new theme for Perishable Press, I simply jot down the theme-switch URL for both the new theme and the active default theme. This makes jumping back and forth very easy. Of course, the general format of these URLs will vary depending on the particular theme-switching plugin that you use.

Another option for switching between current and alternate themes is to actually include the theme-switching links and/or dropdown menu right there on the theme pages themselves. For example, including the theme-switch dropdown menu in the footer of all your themes is a great way to speed up and simplify the development process. But be advised, unless you explicitly exclude your new theme from the theme-switch menu, it will be available for all of your visitors to see and activate. The other method of just using the URL directly is a good way to ensure privacy.

Now that you are setup and easily switching between themes, there are a few other points to consider..

Your new theme is just another theme

This may sound strange, but there is nothing special about your new theme — it’s treated by WordPress as any other theme in your “themes” directory. All of the requirements of the default theme apply:

• Your new theme needs a properly configured style.css file
• Your new theme needs a working index.php file

Assuming your new theme meets these basic requirements, WordPress will recognize your theme as such and display it when activated (either through the Admin or via theme-switch plugin). Incidentally, the name of your theme is specified via the style.css file. The “Theme Name” that is listed here will be the same one used in your theme-switching URLs.

Once you get the basics of your new theme established, use your theme-switching plugin to activate it locally in your browser. Form there, you can rock the design however you want, exactly as you would do when starting from a fresh installation of WordPress. While you are working on your new theme, your visitors will still be seeing your default active theme, which is whatever you specify in the WordPress Admin. This is why the theme-switch development method works so well.

Pages, plugins, and custom functions

Here are a few more little things that will help you when developing your themes behind the scenes..

Plugins affect all themes

Even when your theme is not set as the current default, it will still be affected by all of the plugins installed on your site. This is one of the benefits of using plugins over custom functions..

Custom functions only affect the theme being used

In contrast to plugins, custom functions (i.e., functions placed in your theme’s functions.php file) only affect the current theme being viewed. If you seem to missing some functionality in your “behind-the-scenes” theme, make sure that you have properly transferred any required custom functions.

Page templates will confuse you

This happens to everyone: you are working behind the scenes on a new theme and you can’t seem to get a custom page template to appear in the WordPress Admin. This is because the page editor only shows the templates available to the current default active theme (i.e., the one that everyone sees). To work around this, you can either upload a copy of the custom page template to the active theme, or temporarily switch the default active theme to your behind-the-scenes theme. Personally, I use the former method and just delete the page template if it’s not needed in the default theme.

And last but not least..

Prepare for launch!

Once you have your new theme pimped out and ready to go, simply change your default active theme in the WordPress Admin to launch it for the world see. That’s all there is to it! :)

Like the article? Get the book!

© 2009 Digging into WordPress | Permalink | 27 comments | Add to Delicious
Categorized: Design, Theme | Tagged: plugin, theme-switch, tips

Here are the most important ones, when it comes to commenting, are these:

• $comment_author
• $comment_author_email
• $comment_author_url

Which you can safely output anywhere in the comments.php file like so:

<?php echo esc_attr($comment_author); ?>
<?php echo esc_attr($comment_author_email); ?>
<?php echo esc_attr($comment_author_url); ?>

In order to pre-fill the comment form with this information, the inputs for your comment form could be marked up like so:

<div>
  <label for="author">Name*</label>
  <input type="text" name="author" id="author" value="<?php echo esc_attr($comment_author); ?>" tabindex="1" />			
</div>	

<div>
  <label for="email">Email*</label>
  <input type="text" name="email" id="email" value="<?php echo esc_attr($comment_author_email); ?>" tabindex="2" />
</div>

<div>
  <label for="url">Website</label>
  <input type="text" name="url" id="url" value="<?php echo esc_attr($comment_author_url); ?>" tabindex="3" />
</div>

Getting the Gravatar

Gravatars are those little pictures that show up next to comments… “Globally Recognized Avatars”. Anybody can have one, get one here. What is cool about Gravatars is you have your own account that is associated with your email, so anywhere you comment that you use that email that supports Gravatars, that image will show up, and you can “globally” change that image at any time.

It is almost trivially easy to grab the URL source of someone’s Gravatar. The direct link to the image is:

http://www.gravatar.com/avatar/MD5-HASH-OF-EMAIL

So to spit out an <img> in your comments.php file, use a little PHP:

<?php if ($comment_author_email != "") { 

    $gravatar_link = 'http://www.gravatar.com/avatar/' . md5($comment_author_email) . '?s=32';
    echo '<img src="' . $gravatar_link . '" alt="" />';

} ?>

On CSS-Tricks, I use all of this to prefill previous commenter information, including a small Gravatar:

That’s all there is to it! I think the comment form in every single WordPress theme ever written should probably use at least the pre-fill stuff. The “default” and “classic” themes that come with WordPress have this, so it’s pretty standard, but I do see plenty of themes that don’t.

Like the article? Get the book!

© 2009 Digging into WordPress | Permalink | 9 comments | Add to Delicious
Categorized: Theme | Tagged: comments, PHP, Theme