Fun with template tags: comment_form

This time I’ll focus on the comment_form(). Neat, fun and with plenty of hooks and filters.

The code

Like usual we will look at the core code of the comment_form. There are approximately 230 lines of code that make up this template tag. Does sound like a lot, right? Yes, but when you look a little closer it is the inline documentation that makes up the brunt of it all.

Yes, documentation. I love it and is what I am doing to an extent with these posts. I am documenting their use with examples in hopes that somebody finds it useful. I know at least one person will.

Anyway, back to the point. The hooks and filters.

The filters

One of the first filters is comment_form_default_fields. Pretty neat one because you can add, remove, and even edit form fields. Let’s make a quick edit and remove the website field from the default, shall we?

add_filter( 'comment_form_default_fields', 'my_new_fields' );
function my_new_fields( $fields ){
	$fields['author'] = '<p class="author input"><label for="name"><span class="required">Your name:</span></label><input name="name" type="text" /></p>';
	
	unset( $fields['url'] );
	return $fields;
}

Pretty neat, right? The next one that we come across is the comment_form_defaults. This one is a little more fun in that it has the previous one included with it. I know you may be thinking what do I mean by that, so let’s look at the code:

$defaults = array(
	'fields' => $fields,
	'comment_field' => '<p class="comment-form-comment"><label for="comment">' . _x( 'Comment', 'noun' ) . '</label> <textarea id="comment" name="comment" cols="45" rows="8" aria-describedby="form-allowed-tags" aria-required="true" required="required"></textarea></p>'

That $fields variable is from the previous filter. It is the line before the $defaults array is set. So much like the previous filter we can edit and remove from the default comment_form.

add_filter( 'comment_form_defaults', 'my_custom_form' );
function my_custom_form( $array ){
	$array['class_submit'] ='submit blue input';
	$array['title_reply'] = __( 'Drop us a line', 'text-domain' );
	$array['title_reply_to'] = __( 'Argue with %s', 'text-domain' );
	$array['cancel_reply_link'] = __( 'nevermind!', 'text-domain' );
	
	return $array;
}

From the above example you can see we change the submit class to include blue and input. A few other things were changed and the best part is that you can use a child theme to remove that or even add your own. That’s cool if you wanted to make a lot of additions or deletions but what if you wanted to do it to just one? That’s where

echo apply_filters( "comment_form_field_{$name}", $field ) . "\n";

comes into play. Where $name is the input you wanted to edit. For example:

add_filter( 'comment_form_field_author', 'my_new_author_field' );
function my_new_author_field(){
	return '<label for="author">' . __( 'What is your name, yo?', 'text-domain' ) . '<span class="required">*</span></label><input id="author" name="author" type="text" size="30" />';
}

Pretty cool if you have to change a few thing in order to properly style your form elements.

The hooks

Cool! Those were some of the filters but we cannot just leave without a few action hooks, right? I mean why wouldn’t you like action hooks? Those are so cool because you can add things conditionally.

Let’s look at some of them shall we? There are nine in total. Yes, 9. Not nine thousand. Just nine. That’s quite a few that we can hook to. Good! Plenty of things to mess and tweak with. Some of the neater ones I like are:

do_action( 'comment_form_before' );
do_action( 'comment_form_top' );
do_action( 'comment_form_before_fields' );
do_action( 'comment_form_after_fields' );
do_action( 'comment_form', $post_id );
do_action( 'comment_form_after' );

The reason I like the fifth one is because it is a dynamic one. You can add to the form depending on the post’s ID. Let’s say you wanted to add a note to all posts published before a certain date. You could potentially go through every single one but that could be time consuming. What’s nice is that WordPress uses an incremental ID meaning that when a new post is added it uses the next highest number for the ID. You could use something like:

add_action( 'comment_form', 'my_form_notice' );
function my_form_notice( $id ){
	if ( $id < 1155 ){
		printf( '<span class="notice">%s</span>', __( 'This post may be outdated', 'text-domain' ) );
	}
}

Do keep in mind that some of the above mentioned methods could be used for both plugins as well as themes so use them wisely.

Fun with template tags: comments_template

On my last post I talked about dynamic_sidebar and some uses. It was a fun little experiment I wanted to do and share. Yes, I said experiment. That is how I learn. I read, do and then share. I know I’m not the only one that does that.

This time I dabbled with comments_template(). Yes, another one of the more common template tags. I wanted to dissect the function and see what really makes it unique. Okay, not really, I more or less wanted to look at the code and see how it gets the template file.

Core code

The code itself is about 90 lines. That is including the inline documentation. Without the inline documentation it is about 60 lines. Good to know. It means we don’t have to guess what is going on a lot. So let’s dive in shall we?

Okay, let’s break the function down, shall we?

The arguments

The first argument that is passed is the $file location. The second is whether or not to separate the comments. Simple. But what does that mean and how can we change this?

One way, of course is by passing some arguments ourselves. Let’s say we wanted to separate the comments, we would use:

<?php comments_template( '', true ); ?>

Or if we had our comment template in another location we would use:

<?php comments_tempate( '/inc/comments.php' );

That’s great if your comment template resided in the inc folder and was named comments.php. But what happens if you don’t have a comments.php file anywhere in your theme’s folder? Well, the nice part is that WordPress does account for that. The downside is that it creates a deprecated_file call. Yes, an error. If you read the following doc-block you can see why.

/**
 * @package WordPress
 * @subpackage Theme_Compat
 * @deprecated 3.0
 *
 * This file is here for Backwards compatibility with old themes and will be removed in a future version
 *
 */

I’m going to emphasize the part that really matters most:

and will be removed in a future version

Backwards compatibility is one thing that WordPress does really well; though this is one time I wish it would do it faster. At least for these files. There are a few other files but I’ll focus on this for now.

But why does it load that file if there is no comments.php file? Let’s look a little closer at what the function actually does. At least the parts that really make it load the needed file.

if ( empty($file) )
	$file = '/comments.php';

$theme_template = STYLESHEETPATH . $file;

$include = apply_filters( 'comments_template', $theme_template );
if ( file_exists( $include ) )
	require( $include );
elseif ( file_exists( TEMPLATEPATH . $file ) )
	require( TEMPLATEPATH . $file );
else // Backward compat code will be removed in a future release
	require( ABSPATH . WPINC . '/theme-compat/comments.php');

Not really much code, right? First it checks if the passed argument $file is empty and if it is it creates a simple string of '/comments.php'. Then, it creates a variable $theme_template with the constant TEMPLATEPATH and $file appended to it. Next we see a fairly familiar function apply_filters(). The filter name is comments_template.

We can then use a filter hook to change the location of our comments template. Granted we can do the same without even using the filter by simply passing it the location string to the function itself as we saw above, right?

It matters

Why am I bringing this up? I am bringing this up because the comments template file should be the place to be using wp_list_comments() as well as comment_form(). It doesn’t have to be comments.php that houses those template tags. It could be named anything you want, you just have to make sure you are loading the file properly.

Using a filter

One way is using a filter hook. As you noticed above the line:

$include = apply_filters( 'comments_template', $theme_template );

This what we can use. The code would look a little something like:

add_filter( 'comments_template', 'demo_path_to_comments_template' );
function demo_path_to_comments_template( ){
	if ( is_child_theme() && file_exists( get_stylesheet_directory() . '/inc/coms.php' ) ){
		return get_stylesheet_directory() . '/inc/coms.php';
	} else {
		return get_template_directory() . '/inc/coms.php';
	}	
}

Yes, quite a bit just for comments, right?

Using an argument

What’s super cool about using the core template tag and passing it the argument is that it will first look in the child theme ( if active ) and then the parent theme for the file you designate.

<?php comments_template( '/comments/pings.php', true ); ?>

In the above example it will first look for the pings.php file of the child theme ( if it is active ) and if that file does not exist it will load the parent file. Sort of what get_template_part() does. That is another neat little function for another post.

Seriously, it matters

I’m going to repeat this part because it bears repeating. The backwards compatibility file will one day be removed. Your users will thank you for not using the fallback file. It shouldn’t be a safety net for the theme. Besides, if you want the theme to be hosted in the repository it can’t have any errors.

Fun with template tags: dynamic_sidebar

The last couple of weeks I’ve been reading the core code more and more. I like it. Came to the conclusion I really don’t know every hook or filter. I don’t claim to though. I like knowing enough to make a functional theme or even a plugin. Yes, I’ve been recently dabbling with one but that’s for another post.

The reason for this post is to share some knowledge. Hopefully somebody finds this useful or helpful.

The function

For this post I will be using dynamic_sidebar(). It’s a fairly common template tag in themes. It gets a widgetized area and outputs them in a designated area. In order for that to happen you must first have a registered area. We do that by using register_sidebar(). For demonstrational purposes we will use:

register_sidebar( array(
	'name'          => __( 'Footer Area', 'dademo' ),
	'id'            => 'footer-area',
	'description'   => __( 'Add widgets here to appear in your sidebar.', 'dademo' ),
	'before_widget' => '<aside id="%1$s" class="widget %2$s">',
	'after_widget'  => '</aside>',
	'before_title'  => '<h2 class="widget-title">',
	'after_title'   => '</h2>',
) );

Great! So we created a widgetized area with an ID of footer-area. It can be anything we want but we will currently stick to simple naming conventions. Now, let us look at the core code, shall we?

The core code

The function itself is quite a few lines of code. Approximately 160 lines. I’m not going to post all of that code. The developer reference page has it and you can even view on trac. The ones that matter most for this post are two lines.

The first line:

do_action( 'dynamic_sidebar_before', $index, true );

The second line:

do_action( 'dynamic_sidebar_after', $index, true );

Notice something a little strange about it? I’m referring to the $index part of course. This is the neat part of it all. What does that little part mean?

Our hook

The cool part is that you can hook to specific widgetized areas if you want. I know you may be asking what I mean by this so I’ll demonstrate a little bit. Take our previous example of footer-area above and we will wrap it within a <section> element tag with a class of row.

add_action( 'dynamic_sidebar_before', 'demo_sidebar_before' );
function demo_sidebar_before( $index ){
	if ( $index == 'footer-area' ){
		echo '<section class="row">';
	}
}
add_action( 'dynamic_sidebar_after', 'demo_sidebar_after' );
function demo_sidebar_after( $index ){
	if ( $index == 'footer-area' ){
		echo '</section><!-- Widgetized footer area -->';
	}
}

From there it would render:

<section class="row">
	<aside id="recent-posts-4" class="widget widget_recent_entries">
	<h2 class="widget-title">Recent Posts</h2>
	<ul>
		<li>
		<a href="/2015/04/13/aesop-testing/">Aesop testing</a>
		/li>
		<li>
		<a href="/2015/04/13/sampling-some-code/">Sampling some code</a>
		</li>
		<li>
		<a href="/2015/04/08/another-gallery/">another gallery</a>
		</li>
		<li>
		<a href="/2015/04/08/gallery-7/">gallery 7</a>
		</li>
		<li>
		<a href="/2015/04/08/gallery-6/">gallery 6</a>
		</li>
	</ul>
	</aside>
</section><!-- Widgetized footer area -->

As you can see it created the section element and inside of it is a simple recent posts widget. Now, as I mentioned that is for specific widgetized areas. The thing to remember is to use the ID of the widgetized area to conditionally add or remove. It is that $index that is used to test. You can add things to every single dynamic_sidebar call by not even checking. Let’s say we have two widgetized areas. One in the footer and the other just above the content. We will call that section, “content-above.”

I know, very creative. I said it would be simplistic, didn’t I?

Okay, we wanted to add few things. Let’s say we wanted to add an image to both of those sections. We could edit two different files depending on how your theme is structured. Sounds a little painful, right? So, we will use our handy-dandy little hook:

add_action( 'dynamic_sidebar_before', 'demo_sidebar_before' );
function demo_sidebar_before( $index ){
	echo '<section class="row">';
	echo '<img src="' . get_template_directory_uri() . '/img/divider.png" />';
}
add_action( 'dynamic_sidebar_after', 'demo_sidebar_after' );
function demo_sidebar_after( $index ){
	echo '</section><!-- Widgetized area with image -->';
}

Pretty cool, right? What’s super cool is it will render like:

<section class="row">
<img src="path/to/img" />
<!-- widgets -->

</section><!-- Widgetized area with image -->
<section class="content row">
<!-- the_content -->
</section>

<section class="row">
<img src="path/to/img" />
<!-- widgets -->
</section><!-- Widgetized area with image -->

Yes, all that markup where ever you are using dynamic_sidebar().

Advanced fun

This part I’m writing as my left eye is twitching only because it deals with widgets in themes. Yes, I’ve never liked including them. This part deals with hooking to particular widgets in your theme.

Yes, you could simply edit the file that has the widget but where is the fun in that? This time we will use an action hook.

add_action( 'dynamic_sidebar', 'demo_sidebar' );
function demo_sidebar( $obj ){
	
	if ( $obj['callback'][0]->id_base == 'meta' ){
		printf( '<span>%s</span>', __( 'So much meta', 'dademo' ) );
	}
	// Alternatively
	// if ( preg_match( '/meta-/', $obj['id'] ) ){
	//	printf( '<span>%s</span>', __( 'So much meta', 'dademo' ) );
	// }
}

Does look a little complex, right? Let’s break it down a little.

First, we create the hook in line 1. Then we create our callback function in line 2. Doing good so far. Line 3 is where it does get a little odd. What does it mean? What does it mean?!

Okay, it may look a little complex to some but I’ll explain a little bit more.

When using dynamic_sidbar() it uses an array for the widgets. If there are no widgets then the function returns a false value. If there are it creates an associative array of the widget instance. That array is what we pass our callback function. In the example it is called $obj. In that array we have a key called callback. It, too, is an array.

We are looking for the first item on there because it holds the important part. The information about the widget object. The example is looking for the id_base of the widget. You know that little part you named when you registered the widget.

The alternative uses preg_match to match the ID of the widget’s instance. Yes, you can do specific instances as well.

Be friendly and filter your foot

HTML5 footer

A brief glimpse of my WordPress.com hosted blog’s footer. I’ve had that thing for nearly six years. Yep, six years. A little hard to believe that I only have about eighty posts but it’s true. Part of that reason being me branching off and trying on a self hosted site. I wish I could tell you all the things I’ve tried over the course of this branching but honestly don’t recall every little thing I’ve done.

I can honestly tell you I have learned a few things here and there from not only reading the WordPress codex  pages but from doing some theme reviews as well.

Be friendly

Yes, be friendly. What I mean by this is that you should think about who will be using your theme or plugin. True that not many people are capable of knowing how to code a site with PHP, HTML but that may not be your target, right? Odds are that you want to share your theme with the community.

That means that another developer will be looking at your code. Shock! Awe! You name the emotion, odds are that person will experience it at one point while looking at your code. The one you don’t want to bestow upon them is anger. Once that one hits their ability to trust you will dwindle.

How do you prevent it? Well, documenting is a great way. Another is by making things a little easier by adding hooks and filters to your theme.

Hooks and filters

Yes, hooks and filters. One simple solution to help everyone out. At least a good portion of people. You can’t really please everyone, unfortunately. One way of adding friendliness to your theme, or plugin, is by adding a simple action so that a child theme can easily hook to it. A quick sample would be just before the page of the theme.

< ?php do_action( 'page_prior' ); ?>
    

See? Simple, right? Then all a child theme, or even a plugin, has to do is hook to it. Now, that is a quick and painless way of making your theme a little easier to work with and a future developer will like it since they won’t have to change any files or create a separate file. But there is more! What’s even crazier to think about is that you can not only create minor changes that way but you can also make huge changes that way.

Suppose for a moment that you create a post structure that you feel would want to be changed down the road or by somebody else. Simple! You guessed it! Action hook. Now it is a little more work but you can do it with a few extra lines of code.

//somewhere in the index file
while ( have_posts() ) : the_post(); 
 do_action( 'theme_content' ); 
endwhile;

// in the functions file
add_action( 'theme_content', 'theme_content_cb' );
function theme_content_cb(){
    // inside the WordPress loop
}

Yeah it does look a little odd. But in the child theme’s function file all you would have to do is remove the action and add it again with your own callback function. So the child theme’s function would look a little like:

remove_action( 'theme_content', 'theme_content_cb' );
add_action( 'theme_content', 'child_theme_content' );
function child_theme_content(){
    // My child theme's content code
}

What is nice about that is you can easily alter an entire block of code without ever having to touch any parent theme files or having to create any duplicate files and modifying to your choosing. It is very convenient when you have to remove credits sometimes. One of the issues I see in the WordPress.org Themes and Templates forums.

Filtering

Filtering the output is key in this. Why? Because it makes things just that much easier for the developer that will be using the theme. Remember to keep your audience in mind when creating a theme, or plugin. A good portion of the time it will be a developer. Adding a filter is as easy as using

apply_filters

and you’re done.

function theme_footer_cb( $theme_footer ){
    $theme_footer =
    ';
    echo apply_filters( 'theme_footer_cb', $theme_footer );
}

With that any themer can filter the output of the theme’s footer by adding a filter in the child theme’s function file like so:

add_filter( 'theme_footer_cb', 'child_theme_footer' );
function child_theme_footer( $footer ){
    $footer = '
Created with LUV
'; return $footer; }

Not so hard, right? Now go out and make a developer happy by creating these simple little hooks and filters.

Creating a sticky post slider

Brief background

Creating a slider is simple. For some. In WordPress there are a lot of ways to creating a post slider, image slider, category slider and just about any type of slider you could possibly imagine. The one I wanted to share is creating one with sticky posts. You know the ones that you have to pick from the slightly hidden options.

Make post sticky

Yeah. That little guy. The way WordPress handles sticky post is by putting them on the front page and keeping them on top regardless of when it was posted. A good example is the quick image I created to help illustrate.

The requirements

WordPress has plenty functions and plenty of ways of getting the required posts. One way of getting posts is using get_posts() but that isn’t the method I’ll be using. I’ll be using the WP_Query and alter it just a little bit. No, not with query_posts because that will just cause the world to implode. Okay, not really but there are several other reasons not to use that function.

The steps

In order to have a good functional featured post slider we first need to layout the steps needed. What I did initially was make a quick list of the steps.

  1. Get the posts
  2. Check if there are any ‘sticky’ posts
  3. If there are then run our code
  4. Ignore sticky posts in regular feed
  5. Drink up

The code

Now that we have our logic we can get started.

The first thing we have to do is get all the posts that are set to be sticky. We create and array to hold these.

$stickies = get_option( 'sticky_posts' );

We need to count how many posts there are and we’ll store that as a variable so we can use it later on.

$count = count( $stickies );

Now that we have an array and the total we can start a new query for only those posts. The way we do this is by creating a new WP_Query and passing some arguments. So we’ll create these arguments and name our newly created object of posts $featured. It can be whatever you want it to be. If you are submitting to the WordPress repo then prefix it with your theme or equivalent.

$args = array(
	'post__in'       => $stickies,
	'posts_per_page' => 3,
	'post_type'      => 'post',
	'nopaging'       => true
	);
$featured = new WP_Query( $args );

Now that we have our new object filled with posts we can run our code with the newly created query. But wait! When WordPress is first installed there are no sticky posts so then how do we check for that? Simple. Remember that we stored the value into a variable called $count? We’ll use that. We’ll use an if statement to run our code. If there are no posts then we’ll begin the newly created WordPress loop.

if ( $count > 0 ) {
  // run WordPress loop using $featured
}

Sounds simple now that we have it all together, right? Now we can create the loop and fill it with all the goodies and information we want using template tags. Don’t forget to use wp_reset_postdata() to reset our post data. There is one last thing we must do to get it all working right and that is hooking to pre_get_posts.

What?!

One more thing?

Yes, one last thing. I know a bit of a curveball but this is what will prevent the doubling of sticky posts. What we have to do is add just a few lines of code to our functions file of our theme.

add_action( 'pre_get_posts', 'my_awesome_theme_pre_posts' );
function my_awesome_theme_pre_posts( $query ){
    if ( is_home() ){
        $query->set( 'post__not_in', get_option( 'sticky_posts' ) );
    }

    return $query;
}

Now that we have that done we have our final code snippet:

// Create array of all the sticky_posts
$stickies = get_option( 'sticky_posts' );

// Count how many there are, if any
$count = count( $stickies );

// Create a set of arguments to pass
$args = array(
	'post__in'       => $stickies,
	'posts_per_page' => 3,
	'post_type'      => 'post',
	'nopaging'       => true
	);

$featured = new WP_Query( $args );

// If there is one or more sticky post we create our new slider
if ( $count > 0 ) : ?>
<section class="featured" id="featured-slider">
    <?php while( $featured->have_posts() ) : $featured->the_post(); ?>
    <article <?php post_class( 'featured' ); ?> id="post-< ?php the_ID(); ?>">
        <h1 class="featured-title"><?php the_title(); ?></h1>
        <div class="content"><?php the_content(); ?></div>
        <div class="content"><?php wp_link_pages(); ?></div>
        <footer class="meta">Posted: <?php the_time( get_option( 'date_format' ) ); ?></footer>
    </article>
    <?php endwhile; wp_reset_postdata(); ?>
</section><!-- end of our featured article slider -->
<?php endif; // end the featured posts ?>

Enjoy

And done! For the most part since we need to add interaction but I’ll let you pick out what to use since there are plenty of jQuery slider plugins to help with that.