get_theme_data()

The function that makes it possible is called get_theme_data(), and it simply returns an array of information about any of your theme files. Here is how it’s used in your theme template:

<?php get_theme_data( $theme_filename ); ?>

So $theme_filename is required and should be the path and filename of your theme’s style.css file. There is no default value for this, so you need to ensure a proper value.

So what information can you display with get_theme_data()? The function returns an array of values that basically comprises the different meta items in your stylesheet. Here is a list of possible return values (all strings):

• Name – theme name
• Title – either theme name or linked theme name
• URI – theme URI
• Description – wptexturized version of the theme name
• AuthorURI – theme author URI
• Template – theme parent template, if exists
• Version – theme version number
• Status – theme status (default: publish)
• Tags – theme tags
• Author – author name or linked author name

Note that these return values are case-sensitive and will not work if the first letter is not capitalized.

Examples

The Codex provides this example for getting and displaying the theme Name and Author:

<?php

    /*
     * Assign theme folder name that you want to get information.
     * make sure theme exist in wp-content/themes/ folder.
     */

    $theme_name = 'twentyeleven'; 

   /*
    * Do not use get_stylesheet_uri() as $theme_filename,
    * it will result in PHP fopen error if allow_url_fopen is set to Off in php.ini,
    * which is what most shared hosting does. You can use get_stylesheet_directory()
    * or get_template_directory() though, because they return local paths.
    */

    $theme_data = get_theme_data( get_theme_root() . '/' . $theme_name . '/style.css' );
    echo $theme_data['Title'];
    echo $theme_data['Author'];

?>

This should get you going.. just copy/paste into your theme template and indicate the theme name in that first line of code. Displaying other bits of theme data is matter of editing/replicating those last two lines.

Once you see how it works, you can do cool stuff with it, like display your theme’s version number sort of globally throughout your site. I’m using this technique to append version parameters to my stylesheet URLs, like so:

<link rel="stylesheet" href="<?php bloginfo('stylesheet_directory'); ?>/style.css<?php if(function_exists('theme_version')) theme_version(); ?>">

..and the output markup looks like this (notice the appended version parameter, ?v=1.3):

<link rel="stylesheet" href="http://example.com/wp-content/themes/xycss/style.css?v=1.3">

Because I am using multiple stylesheets, this method really saves a LOT of time trying to keep track of everything. Here is the theme_version() function that goes in your theme’s functions.php file:

// display version number
function theme_version() {
    $theme_name = 'xycss'; // customize with your theme name
    $theme_data = get_theme_data( get_theme_root() . '/' . $theme_name . '/style.css' );
    echo '?v=' . $theme_data['Version'];
}

And with a few modifications, you can also display your theme’s information in your posts and pages via shortcode:

// version number shortcode
function theme_version_shortcode() {
    $theme_name = 'xycss'; // customize with your theme name
    $theme_data = get_theme_data( get_theme_root() . '/' . $theme_name . '/style.css' );
    return $theme_data['Version'];
}
add_shortcode('theme_version', 'theme_version_shortcode');

With that second snippet in your functions.php file, displaying your theme info directly in pages is as easy as writing this:

[theme_version]

..and the output:

1.3

It’s pretty cool stuff, and I’m sure there’s tons more you can do with it too. If you know any tricks or tips, please share in the comments, Thanks :)

© 2011 Digging into WordPress | Permalink | 10 comments | Add to del.icio.us | Post tags: functions, Theme, tips, tricks

• wp_reset_postdata()
• wp_reset_query()
• rewind_posts()
• Quick Summary

wp_reset_postdata()

First up we have wp_reset_postdata, which restores the global $post variable to the current post in the main query. This is useful when using WP_Query to customize loops or create multiple loops on the same page. It looks like this:

<?php wp_reset_postdata(); ?>

This tag is nice and simple – it accepts no parameters and returns no values. It simply resets the post data after a custom query. So for example, let’s say we have a custom WP_Query loop in our theme’s header.php file, something like this:

$random_post = new WP_query(); 
$random_post->query('cat=3&showposts=1&orderby=rand'); 
while ($random_post->have_posts()) : $random_post->the_post(); 
<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($random_post->ID, 'featured', true); ?>">
</a>
endwhile;

This would display a random post in the header, but it will also change the main query object for any other loops on the page. Without the original query data available, the main posts loop contained in, say, index.php may produce unexpected results. Fortunately, we can use wp_reset_postdata to restore the query object to its original state.

To use wp_reset_postdata, just place after your custom loop(s). Here is our previous example with wp_reset_postdata to reset the loop:

$random_post = new WP_query(); 
$random_post->query('cat=3&showposts=1&orderby=rand'); 
while ($random_post->have_posts()) : $random_post->the_post(); 
<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($random_post->ID, 'featured', true); ?>">
</a>
endwhile;
wp_reset_postdata();

When to use: best used after custom or multiple loops created with WP_Query.

wp_reset_query()

Next up we have the wp_reset_query function, which resets the query used with custom loops. It’s a simple function that accepts no parameters and returns no values. It looks like this:

<?php wp_reset_query(); ?>

Specifically, this function was created to prevent issues with query_posts, as indicated for the function in the wp-includes/query.php file:

/**
 * Destroy the previous query and set up a new query.
 *
 * This should be used after {@link query_posts()} and before another {@link
 * query_posts()}. This will remove obscure bugs that occur when the previous
 * wp_query object is not destroyed properly before another is set up.
 *
 * @since 2.3.0
 * @uses $wp_query
 */

Looking at the wp_reset_query function in query.php, we see that it uses the adjacent wp_reset_postdata function to restore the global $post variable to the current post in the main query:

// destroy and reset the query
function wp_reset_query() {
	unset($GLOBALS['wp_query']);
	$GLOBALS['wp_query'] =& $GLOBALS['wp_the_query'];
	wp_reset_postdata(); // <-- RESET QUERY
}

// restore the query
function wp_reset_postdata() {
	global $wp_query;
	if ( !empty($wp_query->post) ) {
		$GLOBALS['post'] = $wp_query->post;
		setup_postdata($wp_query->post);
	}
}

So both wp_reset_query() and wp_reset_postdata() reset the query object by restoring the global $post variable, but wp_reset_query takes it a step further and actually destroys the previous query before doing so. This is important when using query_posts(), as seen in the following example:

<?php query_posts('posts_per_page=3');
if (have_posts()) : while (have_posts()) : the_post(); ?>

<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>

<?php endwhile; endif; ?>
<?php wp_reset_query(); ?>

When to use: best used after a query_posts loop to reset things after a custom query.

rewind_posts()

Last but not least, we have the rewind_posts function, which basically does what it says: rewinds the loop so you can re-use the same query. The function accepts no parameters, returns no values, and looks like this when used in your theme files:

<?php rewind_posts(); ?>

So to understand when to use rewind_posts(), let’s say we want to use the same query in two different locations on the page. We want to display post titles in the first loop and post content in the second loop. To re-use the same posts, we include rewind_posts after the first loop, like so:

if (have_posts()) : while (have_posts()) : the_post(); ?>
<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
<?php endwhile; endif; ?>

<?php rewind_posts(); ?>

<?php while (have_posts()) : the_post(); ?>
<?php the_content(); ?>
<?php endwhile; ?>

So, while wp_reset_query and wp_reset_postdata reset the entire query object, rewind_posts simply resets the post count, as seen for the function in the wp-includes/query.php file:

// rewind the posts and reset post index
function rewind_posts() {
	$this->current_post = -1;
	if ( $this->post_count > 0 ) {
		$this->post = $this->posts[0];
	}
}

When to use: best for re-using the same query on the same page.

5-second summary

Quick summary for future reference:

• wp_reset_postdata() -> best used after custom or multiple loops created with WP_Query
• wp_reset_query() -> best used after a query_posts loop to reset a custom query
• rewind_posts() -> best for re-using the same query on the same page

I hope this is a useful round-up of when & how to reset/rewind the WordPress loop. Note that the WP Codex information on these functions is kinda thin, so feel free to share any tips or examples in the comments.

© 2011 Digging into WordPress | Permalink | 11 comments | Add to del.icio.us | Post tags: loop, PHP, tips, tricks

• Default Loop
• Loop with query_posts()
• Loop with WP_Query()
• Loop with get_posts()

Each of these looping methods is useful in a variety of situations. They share a lot of the same underlying functionality, and the query parameters are essentially the same. Collectively, these four techniques enable simple loops, multiple loops, and custom loops in your WordPress theme template. A good place to find a default loop, for example, is in your theme’s index.php file. Its purpose is to loop through the posts stored in the database and echo their contents to the browser. Using WordPress’ template tags, it’s easy to display post titles, content, meta info, and much more. That said, let’s examine the four ways to loop with WordPress.

The Default Loop

The default WordPress loop looks something like this:

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

	<div <?php post_class(); ?> id="post-<?php the_ID(); ?>">
		<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
		<?php the_content(); ?>
	</div>

<?php endwhile; ?>

	<div class="navigation">
		<div class="next-posts"><?php next_posts_link(); ?></div>
		<div class="prev-posts"><?php previous_posts_link(); ?></div>
	</div>

<?php else : ?>

	<div <?php post_class(); ?> id="post-<?php the_ID(); ?>">
		<h1>Not Found</h1>
	</div>

<?php endif; ?>

So what makes it “default”? Mostly because it uses the default query to loop through post content, making it the loop used like 99% of the time for most themes. It tells WordPress to loop through posts and display the information according to context, and as called by the various template tags (the_title, the_content, et al). There are tags available for just about any type of data stored in the database.

Based on the query that is sent, the default loop will display a certain number of posts from a certain category from a certain date, and so on. For example, the number of posts displayed in the first part of the loop is specified in the WP Admin. So if someone requests the second page of your “Awesome” category, that information is sent via the query, along with the number of posts, theme template file, and so on.

So the default loop is perfect if you’re happy with the query that is sent, but it is also possible to customize the query and generate an entirely different set of posts.

Loop with query_posts()

The query_posts function enables us to modify the query and display our desired results. We can either override the entire query or keep it around and just change a few parameters. Here’s an example where query_posts is called before the default loop to exclude a specific category:

<?php global $query_string; // required
$posts = query_posts($query_string.'&cat=-9'); // exclude category 9

<?php // DEFAULT LOOP GOES HERE ?>

<?php wp_reset_query(); // reset the query ?>

Say you have a default loop in your index.php theme template, but you want to change the number of posts, exclude two categories, and display the results in ascending order. Easy. Just add some query_posts action before the default loop and wp_reset_query immediately after, like this:

<?php global $query_string; // required
$posts = query_posts($query_string.'&posts_per_page=3&cat=-6,-9&order=ASC');

<?php // DEFAULT LOOP GOES HERE ?>

<?php wp_reset_query(); // reset the query ?>

Here we are keeping the original query around and just overriding a few parameters. There are many parameters available, so customizing any default loop is accomplished quite easily. If we wanted to completely override the original query, we would replace the second line with something like this:

$posts = query_posts('posts_per_page=3&cat=-6,-9&order=ASC');

Notice here that we’ve removed the $query_string from the query_posts parameters. This essentially erases the default query and replaces it with one that contains only those variables included in query_posts. This means no paging information will be available, so remove the original query only if you know what you’re doing.

When to use? Use query_posts to modify the type of posts that are returned for a single loop. It’s perfect for limiting the number of posts, excluding posts from a certain category or tag, and so on. If more than one loop is required, multiple query_posts loops could work, but there is a much better way to do it using WP_Query.

Loop with WP_Query()

For complete control over the customization of any number of loops, WP_Query is the way to go. When used to modify a default loop, it looks similar to query_posts. For example, let’s exclude a specific category using WP_Query:

<?php $custom_query = new WP_Query('cat=-9'); // exclude category 9
while($custom_query->have_posts()) : $custom_query->the_post(); ?>

	<div <?php post_class(); ?> id="post-<?php the_ID(); ?>">
		<h1><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h1>
		<?php the_content(); ?>
	</div>

<?php endwhile; ?>
<?php wp_reset_postdata(); // reset the query ?>

It also accepts the same parameters as query_posts, so modifying stuff like number of posts, included/excluded categories, and post order looks quite familiar. As seen in the following examples, WP_Query makes it easy to customize the loop by simply changing the parameter:

$custom_query = new WP_Query('cat=-7,-8,-9'); // exclude any categories
$custom_query = new WP_Query('posts_per_page=3'); // limit number of posts
$custom_query = new WP_Query('order=ASC'); // reverse the post order

As expected, we can combine parameters with WP_Query using the same syntax as both query_posts and get_posts. Here’s the equivalent of our query_posts example:

$custom_query = new WP_Query('posts_per_page=3&cat=-6,-9&order=ASC');

Notice, however, that with WP_Query, we don’t need the $query_string variable. In addition to using WP_Query to customize the default loop, we can also use it to create and customize multiple loops. Here is a basic example:

<?php // Loop 1
$first_query = new WP_Query('cat=-1'); // exclude category
while($first_query->have_posts()) : $first_query->the_post();
...
endwhile;
wp_reset_postdata();

// Loop 2
$second_query = new WP_Query('cat=-2'); // exclude category
while($second_query->have_posts()) : $second_query->the_post();
...
endwhile;
wp_reset_postdata();

// Loop 3
$third_query = new WP_Query('cat=-3'); // exclude category
while($third_query->have_posts()) : $third_query->the_post();
...
endwhile;
wp_reset_postdata();
?>

Each of these additional loops may be placed anywhere in your theme template – no need to line them up sequentially. For example, one loop may be placed in your sidebar, another in your footer, and so on. And with the output of each loop easily modified using any of the available parameters, any loop configuration is possible.

When to use? Use WP_Query for creating multiple, customized loops. By setting up additional instances of WP_Query in your theme, you can create any number of multiple loops, and customize the output of each.

Even so, we don’t always need to break out the big guns, sometimes we just need a few additional loops displayed around the page. So let’s put down the bazookas and gather in the garden for some get_posts tea ;)

Loop with get_posts()

The easiest, safest way to create multiple loops in your theme is to use get_posts(). Anywhere you need to display a quick, static set of posts, get_posts is the perfect choice. Think 10 recent posts in the sidebar, or 10 random posts in the footer. get_posts makes it easy. Here again is a query to exclude a specific category:

<?php global $post; // required
$args = array('category' => -9); // exclude category 9
$custom_posts = get_posts($args);
foreach($custom_posts as $post) : setup_postdata($post);
...
endforeach;
?>

This code creates a loop of all posts except those in the excluded category. Of course, excluding a category is just one way to customize your additional, static loops. By using any of the same parameters accepted by WP_Query and query_posts, it’s possible to create loops that display just about anything you want.

Notice, however, that get_posts requires the use of an array for the parameters. The format for multiple parameters looks like this (using our previous example):

$args = array('numberposts'=>3, 'category'=>-6,-9, 'order'=>'ASC');

Also notice that we’re using numberposts instead of posts_per_page to limit the number of posts. According to the WP Codex, posts_per_page should work with get_posts, but if it doesn’t just go with numberposts. There is also a showposts parameter that also seems to work fine with get_posts.

When to use? Use the get_posts() function to easily create additional, static loops anywhere in your theme. get_posts accepts the same parameters as query_posts, and is perfect for adding static, custom loops to your sidebar, footer, or anywhere else.

30-Second Summary

The bottom line for customizing default loops and creating multiple loops:

• To modify the default loop, use query_posts()
• To modify loops and/or create multiple loops, use WP_Query()
• To create static, additional loops, use get_posts()

If you’re working with WordPress loops and want to learn more about using them to customize your theme, we cover the topic extensively in our book, Digging into WordPress, which is current with WordPress 3.1 :)

© 2011 Digging into WordPress | Permalink | 31 comments | Add to del.icio.us | Post tags: loop, PHP, query_posts

• Default WordPress Login Page
• Moving the login/register/password form
• Custom WordPress template code
• Implement and Demo
• Customizing things
• Wrap up

Default WordPress Login Page

Out of the box, WordPress uses wp-login.php for logging into the Admin, retrieving lost passwords, and registering for site membership. Each of these activities are handled on the same page, commonly referred to as the WordPress Login Page.

Yep, it’s the WordPress Login Page

As seen here, the Login Page shows the log-in form by default. Beneath the form are two links, “Register” and “Lost your password?”, which enable users to (yep, you guessed it) register and recover their password.

The cool thing about the Login Page is that the page doesn’t reload when either of these links are clicked. Instead, the form instantly changes from login to register or password to whatever. All three forms are included on the wp-login.php page and hidden/revealed as-needed using JavaScript. This “same-page” functionality is key to setting up our own custom login/register/password form elsewhere in our theme.

Moving the login/register/password form

While it’s not a good idea to move the entire wp-login.php file, it is possible to display the login/register/password forms anywhere in your theme. For example, putting the forms in your sidebar.php make it super-easy for visitors to register and login from anywhere in your site (here is an example). You could even create a WordPress page for each event: login, registration, and password-recovery pages that are customized/optimized in some really unique, bad-ass way.

The key to mobilizing the login forms is ensuring that they’ll work properly regardless of placement (before, after, or within the loop) in your theme template files. We also want to ensure that normal visitors who aren’t logged in see the forms, but logged-in users do not (or see alternate content).

Basically, it should work exactly like the default WordPress login functionality, but with one exception: instead of redirecting to the Admin Area (for log-ins) or to the Login Page (for registrations/password-recovery), we want the user to remain on the same page. This enables your guests to log-in, register, and reset passwords without leaving whatever page they happen to be visiting. Here’s the code to make it happen..

Custom WordPress template code

Here is the code to display the login/register/password form anywhere in your theme:

view as plain text

<div id="login-register-password">

	<?php global $user_ID, $user_identity; get_currentuserinfo(); if (!$user_ID) { ?>

	<ul class="tabs_login">
		<li class="active_login"><a href="#tab1_login">Login</a></li>
		<li><a href="#tab2_login">Register</a></li>
		<li><a href="#tab3_login">Forgot?</a></li>
	</ul>
	<div class="tab_container_login">
		<div id="tab1_login" class="tab_content_login">

			<?php $register = $_GET['register']; $reset = $_GET['reset']; if ($register == true) { ?>

			<h3>Success!</h3>
			<p>Check your email for the password and then return to log in.</p>

			<?php } elseif ($reset == true) { ?>

			<h3>Success!</h3>
			<p>Check your email to reset your password.</p>

			<?php } else { ?>

			<h3>Have an account?</h3>
			<p>Log in or sign up! It&rsquo;s fast &amp; <em>free!</em></p>

			<?php } ?>

			<form method="post" action="<?php bloginfo('url') ?>/wp-login.php" class="wp-user-form">
				<div class="username">
					<label for="user_login"><?php _e('Username'); ?>: </label>
					<input type="text" name="log" value="<?php echo esc_attr(stripslashes($user_login)); ?>" size="20" id="user_login" tabindex="11" />
				</div>
				<div class="password">
					<label for="user_pass"><?php _e('Password'); ?>: </label>
					<input type="password" name="pwd" value="" size="20" id="user_pass" tabindex="12" />
				</div>
				<div class="login_fields">
					<div class="rememberme">
						<label for="rememberme">
							<input type="checkbox" name="rememberme" value="forever" checked="checked" id="rememberme" tabindex="13" /> Remember me
						</label>
					</div>
					<?php do_action('login_form'); ?>
					<input type="submit" name="user-submit" value="<?php _e('Login'); ?>" tabindex="14" class="user-submit" />
					<input type="hidden" name="redirect_to" value="<?php echo $_SERVER['REQUEST_URI']; ?>" />
					<input type="hidden" name="user-cookie" value="1" />
				</div>
			</form>
		</div>
		<div id="tab2_login" class="tab_content_login" style="display:none;">
			<h3>Register for this site!</h3>
			<p>Sign up now for the good stuff.</p>
			<form method="post" action="<?php echo site_url('wp-login.php?action=register', 'login_post') ?>" class="wp-user-form">
				<div class="username">
					<label for="user_login"><?php _e('Username'); ?>: </label>
					<input type="text" name="user_login" value="<?php echo esc_attr(stripslashes($user_login)); ?>" size="20" id="user_login" tabindex="101" />
				</div>
				<div class="password">
					<label for="user_email"><?php _e('Your Email'); ?>: </label>
					<input type="text" name="user_email" value="<?php echo esc_attr(stripslashes($user_email)); ?>" size="25" id="user_email" tabindex="102" />
				</div>
				<div class="login_fields">
					<?php do_action('register_form'); ?>
					<input type="submit" name="user-submit" value="<?php _e('Sign up!'); ?>" class="user-submit" tabindex="103" />
					<?php $register = $_GET['register']; if($register == true) { echo '<p>Check your email for the password!</p>'; } ?>
					<input type="hidden" name="redirect_to" value="<?php echo $_SERVER['REQUEST_URI']; ?>?register=true" />
					<input type="hidden" name="user-cookie" value="1" />
				</div>
			</form>
		</div>
		<div id="tab3_login" class="tab_content_login" style="display:none;">
			<h3>Lose something?</h3>
			<p>Enter your username or email to reset your password.</p>
			<form method="post" action="<?php echo site_url('wp-login.php?action=lostpassword', 'login_post') ?>" class="wp-user-form">
				<div class="username">
					<label for="user_login" class="hide"><?php _e('Username or Email'); ?>: </label>
					<input type="text" name="user_login" value="" size="20" id="user_login" tabindex="1001" />
				</div>
				<div class="login_fields">
					<?php do_action('login_form', 'resetpass'); ?>
					<input type="submit" name="user-submit" value="<?php _e('Reset my password'); ?>" class="user-submit" tabindex="1002" />
					<?php $reset = $_GET['reset']; if($reset == true) { echo '<p>A message will be sent to your email address.</p>'; } ?>
					<input type="hidden" name="redirect_to" value="<?php echo $_SERVER['REQUEST_URI']; ?>?reset=true" />
					<input type="hidden" name="user-cookie" value="1" />
				</div>
			</form>
		</div>
	</div>

	<?php } else { // is logged in ?>

	<div class="sidebox">
		<h3>Welcome, <?php echo $user_identity; ?></h3>
		<div class="usericon">
			<?php global $userdata; get_currentuserinfo(); echo get_avatar($userdata->ID, 60); ?>

		</div>
		<div class="userinfo">
			<p>You&rsquo;re logged in as <strong><?php echo $user_identity; ?></strong></p>
			<p>
				<a href="<?php echo wp_logout_url('index.php'); ?>">Log out</a> | 
				<?php if (current_user_can('manage_options')) { 
					echo '<a href="' . admin_url() . '">' . __('Admin') . '</a>'; } else { 
					echo '<a href="' . admin_url() . 'profile.php">' . __('Profile') . '</a>'; } ?>

			</p>
		</div>
	</div>

	<?php } ?>

</div>

Okay, so here are the functional highlights for this hefty chunk of code:

• Everything is wrapped with <div id="login-register-password"></div>
• If the user is not logged in, the three forms are included in the markup
• If the user is logged in, a simple welcome message is displayed
• Success messages are displayed after both password recovery and registration
• Each form submission sets a generic user-cookie
• After login or registration, the script redirects the user to the same page
• Only one form is shown at a time; JavaScript is used to show and hide forms

So if you just throw this thing into your sidebar.php file, you’ll see the login form and three links: login, register, and recover-password. The other two forms are included in the markup, but are hidden with CSS (display:none;). As-is, the three links won’t do anything because they require JavaScript to work. Once we sprinkle in some jQuery, the links will toggle the three different forms.

Implement and Demo

First let’s walk through using this code in your theme, and then we’ll check out a demo.

1. Place the custom login code in your sidebar.php file, or some other location
2. Grab the jQuery code (no-conflict mode) and include it in your footer.php file
3. Include the CSS code in your theme’s style.css file, or wherever your styles are located

..and done. Once these three items are in place, upload everything to your server and check it out. Here is a demo showing this code used on a custom page within the loop.

Note that we have registration disabled here at DigWP.com, so the forms won’t be of much use other than to show how the tabs work and how the forms are styled. Here are some screenshots showing the “success” messages, and also the “logged-in” display.

Message displayed on successful registration

Message displayed on successful password-recovery

Content displayed when user is logged into the site

Here again is the demo and here are the three resource files:

• Custom Template Code
• jQuery Code
• CSS Code

Customizing things

One of the main reasons why we like working with actual code instead of widgets or plugins is the ability to easily customize anything we want exactly how we want it. With this implementation, there are basically three things to customize: the jQuery, the custom login code, and the CSS. As with any code, there are countless ways to modify appearance and functionality, so hopefully you have something specific in mind, and are familiar enough with design to jump in and customize things. If not, no worries – here are some ideas to help get you started.

Customizing the login forms

As-is, the custom login forms redirect to the current page. To get any/all of the forms to redirect to a different page, locate and edit the following line of code:

<input type="hidden" name="redirect_to" value="<?php echo $_SERVER['REQUEST_URI']; ?>" />

There are three instances of this hidden input field, which WordPress uses to perform the redirect. The value returns the current URL, so that’s what needs changed for each form to redirect elsewhere.

Another useful modification involves customizing what the logged-in users see. Showing the gravatar and username is kind of neat, but there are tons of cool tricks to help ensure smooth user experience.

Customizing the jQuery

The jQuery used to show/hide the different login panels is actually pretty basic and is only used for toggling display states. I suppose there is a way to customize this, but it already handles additional menu items, so maybe you want to change the class names or optimize the script or something.

I do love to look at a nice slice of well-formatted jQuery, however, so I’ll further indulge myself by including the entire code snippet right here:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>
<script type="text/javascript">
	$(document).ready(function() {
		$(".tab_content_login").hide();
		$("ul.tabs_login li:first").addClass("active_login").show();
		$(".tab_content_login:first").show();
		$("ul.tabs_login li").click(function() {
			$("ul.tabs_login li").removeClass("active_login");
			$(this).addClass("active_login");
			$(".tab_content_login").hide();
			var activeTab = $(this).find("a").attr("href");
			if ($.browser.msie) {$(activeTab).show();}
			else {$(activeTab).show();}
			return false;
		});
	});
</script>

A bit heavy-handed perhaps, but works great with no editing required ;)

Customizing the CSS

To get that fancy tabbed form menu looking all clean and rounded, much CSS is used. So instead of posting endless gobs of CSS, here is the code in plain text. As with any CSS, the best way to customize things is to open Firebug and start tweaking.

Just the links

One last trick: use this code to display links to the default WordPress login/registration page:

<ul>
	<?php wp_register(); ?>
	<li><?php wp_loginout(); ?></li>
	<?php wp_meta(); ?>
</ul>

Nothing to golf about, but I figured it was worth mentioning.

Wrap up

Using the code and techniques in this article, you can provide your readers with a login form anywhere on your site. This makes it easy for your users and visitors to login/logout, register for your site, and recover passwords without leaving their current page. The login code works great as-is or is easily transformed into a snazzily tabbed login menu using a sprinkle of CSS and a dash of jQuery.

Finally, one of the great things about WordPress is that there is always more than one way to set things up. So if you see a way to improve the code, please share with the community by leaving a comment. Thank you!

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

It always worked, but it has undergone an update to be much mo’ better. Shout out to Stewart Heckenberg for contributing to this, this new version is a combo effort of his work and mine. Here is what is now better:

• Scripts properly loaded in the footer
• Back button works, which users will expect it to
• Hash-tag URL structure enforced when entering via a “deep link”
• Detection of internal links smarter

It may not seem like much, but it kinda is. Most importantly, it’s just a better user experience all around. Please note the site works perfectly fine with JavaScript disabled as well.

View Demo

Why?

The idea is to give a simple framework in case you wanted to do this same kind of thing in your own custom WordPress theme. I feel like this is a fairly easy theme to start from, with it’s über basic design. The original idea was based on a client request where there was a music player in the sidebar. They wanted it so a user could play a song in the music player, and have it not stop as they clicked around other links.

How to get it

We have a brand new downloading system here for the book and it’s related materials. Everyone who has previously purchased the book has access to it. Read the instructions here.

*The page still reloads for the submission of a comment.

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

The Basic Setup

Sign up for the (free) Google Custom Search Engine.

The default code that Google gives you is the pure-JavaScript version. It works fine, but it doesn’t allow you to separate the search form and the results. I find that kind of ridiculous, as it’s far more common to want to host the search form on all pages (like in the header or sidebar) and have that take you to a dedicated results page.

To get the code that is the separate search form and results, go to the Look and Feel section after creating your CSE. Choose the iframe method, then click the Get Code button.

Fill out the URL of your search results page (this will be a page you’ll create and publish later). Then take the top bit of code and place it were you want the search form to be. Likely in your sidebar.php file or header.php file, wherever your site design dictates would be good to have a search form.

On this site, we put it in the sidebar, and applied our simple button class to match other buttons on the site. Don’t be afraid to alter the HTML of the provided code as long as it’s simple alterations like adding a class name to an input.

Now create a page in your WordPress admin called “Search Results”, in the content, paste in the second bit of code. Make sure the slug you give the page matches the URL you gave the CSE for the location of the results page. If they don’t match, you can easily change the <form>‘s action attribute in the HTML.

You’re all set! Now you can enter search terms on any page of your site, and be taken to a dedicated search results page where the results will be displayed. These results will of course be real Google search results, but limited only to your domain. So that He-Man article? It will almost certainly be on top, because Google’s importance algorithmic will put it there.

Using Multiple CSE’s for Subsections of your Site

On CSS-Tricks, I have a search area that looks like this:

Notice the little options beneath the search box which indicate in what area you would like to search. It might seem like this is some fancy custom development, but it’s really not. In reality, it’s just four different Google Custom Search Engines. Only one of them displays at a time though, depending on which search option is active.

<div id="search-area">

	<form action="/search-results/" id="search-all" class="header-search-form default-search">
	    ...
	</form>

	<form method="get" action="/" id="search-articles" class="header-search-form">
	    ...
	</form>

	<form action="/forums/index.php" id="search-forums" class="header-search-form">
	    ...
	</form>

	<form action="/snippets/search/" id="search-snippets" class="header-search-form">
	    ...
	</form>

	<div id="search-by">Search: 
		<a href="#search-all" class="cur-search">All</a> 
		<a href="#search-articles">Articles</a> 
		<a href="#search-forums">Forums</a> 
		<a href="#search-snippets">Snippets</a>

		<p id="browse-archives">Or... <a href="/archives/">browse the archives</a></p>
	</div>

</div> <!-- END search-area -->

Notice the class names on the very first <form> includes “default-search”. All these forms are hidden by default, and only that class name reveals it. So while there are four forms here, only one displays. Also note the second form actually submits to “/” and uses the GET method. This is for “articles only” search and uses the default WordPress search.

The other areas (Snippets, Forums, and All) use Google Custom Search Engines. So for those three, I used what is described above in the basic setup. For the Snippets area, I told the CSE to use the domain http://css-tricks.com/snippets/ – so the results that it returns are limited to that subdirectory.

I use a bit of jQuery to allow the search option links to be clickable to change which area is to be searched. When a new option is selected, hide all forms, show the correct corresponding form, flip around classes to indicate the new option is selected. Easy cheesy.

var $searchByLinks = $("#search-by > a");

$searchByLinks.click(function() {
    var $el = $(this)
    $(".header-search-form").hide();
    $($el.attr("href")).show();
    $searchByLinks.removeClass("cur-search");
    $el.addClass("cur-search");
    return false;
});

Then to keep what users type in all search inputs in sync at all times, another quick bit:

$(".header-search-input").keyup(function() {
    $(".header-search-input").val($(this).val());
});

Now we’re all set! Users can now search subsections of the site if they choose, and all we had to do was use multiple Google CSE’s. The user likely doesn’t even notice and no custom development was needed.

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

The idea is that WordPress will look for files in a theme to use to render the current page in a specific order. For example, let say you have a page for showing posts from a certain category like this. On this site, all our category pages are currently the same and use “archive.php” template. This file is pretty far down the hierarchy, and is shared with other types of views, for example, tag pages.

If we wanted to differentiate our category pages from our tag pages, we could create a file in our theme called “category.php” and our site would instantly start using that template for these pages, without us having to do anything else. We could get even more specific, have theme files that are unique to the categories themselves! To make a page specific to our security category, we could make a file called “category-security.php” and our site would use that file when viewing that category page.

You could really get fancy with customized pages by having a good understanding of the template hierarchy! Do take care not to get too overly repetitive with your templates though. If you have 10 categories and want to have a different header on each, you may be better off using a single category.php file with conditional tags rather than 10 separate files.

SEE THE FULL SIZE IMAGE

This was based on this hierarchy list that was sent to me by Ptah Dunbar. Thanks Ptah!

• 404
  1. 404.php
  2. index.php
• Search
  1. search.php
  2. index.php
• Tax
  1. taxonomy-{tax}-{term}.php
  2. taxonomy-{tax}.php
  3. taxonomy.php
  4. archive.php
  5. index.php
• Home
  1. home.php
  2. index.php
• Attachment
  1. mime.php
  2. type.php
  3. mime_type.php
  4. attachment.php
  5. single.php
  6. index.php
• Single
  1. single-{post-type}.php
  2. single.php
  3. index.php
• Page
  1. custom_template.php
  2. page-{slug}.php
  3. page-{id}.php
  4. page.php
  5. index.php
• Category
  1. category-{slug}.php
  2. category-{id}.php
  3. category.php
  4. archive.php
  5. index.php
• Tag
  1. tag-{slug}.php
  2. tag-{id}.php
  3. tag.php
  4. archive.php
  5. index.php
• Author
  1. author-{author-nicename}.php
  2. author-{author-id}.php
  3. author.php
  4. archive.php
  5. index.php
• Date
  1. date.php
  2. archive.php
  3. index.php
• Archive
  1. archive.php
  2. index.php

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

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?

© 2010 Digging into WordPress | Permalink | 66 comments | Add to del.icio.us | Post tags: 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!

© 2010 Digging into WordPress | Permalink | 17 comments | Add to del.icio.us | Post tags: 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');
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: functions, template, Theme