Working with the WordPress Customizer

Recently the Theme Review Team chose to make the customizer as the format of creating theme options. I love it! Yes, I was in favor of it. I have my reasons. I know there are some people that still don’t fully grasp the customizer and most likely won’t. All good! Some take a little more time than others; I know I do sometimes with certain things.

How it works

Okay. This little post will deal with customizer settings, controls, sections and panels. Yes. At the time of this writing the WordPress version is 4.2.1 with 4.3 just beginning. In the following I will make an attempt at giving you ( the reader ) a little more insight into how the WordPress customizer works and what is available within the customizer.

In order to understand the customizer a little more I dove into the core code. I asked myself a simple question, “when and where is it being created?”

Funnily enough it is done in one simple function. _wp_customize_include. It is a callback function that is hooked to plugins_loaded. Yes, I went ahead and looked up a lot of the code for you. What’s pretty cool is that in order for the customizer to work it needs five files. Yes, five. To a degree 7 but the other two are the customize.php and class-wp-customize-widgets.php files. For the purpose of this post I’ll only really dive into the five customizer ones.

Let’s look at the function:

function _wp_customize_include() {
	if ( ! ( ( isset( $_REQUEST['wp_customize'] ) && 'on' == $_REQUEST['wp_customize'] )
		|| ( is_admin() && 'customize.php' == basename( $_SERVER['PHP_SELF'] ) )
	) )
		return;

	require( ABSPATH . WPINC . '/class-wp-customize-manager.php' );
	// Init Customize class
	$GLOBALS['wp_customize'] = new WP_Customize_Manager;
}

The key thing to remember is when you are creating your options, you are passing an object. The $wp_customize global object to be a little more specific. As you can tell from the function above, you are creating an instance of the WP_Customize_Manager and setting that as the $wp_customize global variable that can be accessed by using:

global $wp_customize;

Looking at the __construct method, it loads the needed files and adds a few filters and hooks in order for the magic to happen. Totally awesomesauce!

Boom! We have our customizer! Great! But how do we add stuff?

Adding things

In order to add our theme options we have to hook to the right place. The codex has a great explanation on this, though currently it is missing a section on how to add panels. Yes, you can add panels in order to make your theme option logic make some sense for a user.

So, in order to add things we need to know how, right? Right! What’s pretty neat is that the customizer does this with built in methods. Yes, it is very object oriented. One of the other reasons I like it. There are four methods that will help in creating a great customizer experience.

$wp_customize->add_setting();
$wp_customize->add_control();
$wp_customize->add_section();
$wp_customize->add_panel();

I say customizer experience because as a developer you will have to think about the logic of your theme options. That’s great and all but what actually starts it all? The part that we hook to in order to start our theme options is the customize_register hook. This is done from within your theme by using:

add_action( 'customize_register', 'my_theme_customize_regiter' );
function my_theme_customize_register( $wp_customize ){
	// Theme settings/options code goes here
}
// or if using a class
add_action( 'customize_register', array( 'My_Class_customize_register', 'register' ) );
class My_Class_customize_register {
	public function register(){
		// Theme settings/options code goes here
	}
}

Got it? Cool! Let’s keep moving! Let’s break down each method a little more.

The methods

What’s super cool is that the customizer makes it super easy to create a theme option experience. It does this with four different methods. Let’s take a look at each one and what each one has to offer.

add_setting

The first one we will look at is the settings. In order to create a theme option in the customizer we use the $wp_customize->add_setting method. It takes two arguments. The first one is the ID of the setting and the second is an associative array. It looks a little like:

$wp_customize->add_setting( 'theme_option', array(
	'default' => '', // The default setting
	'type' => '', // can use 'theme_mod' or 'option'
	'capability' => '', // generally 'edit_theme_options'
	'transport' => '', // can use 'refresh' or 'postMessage'
	'theme_supports' => '', // internally used in customizer
	'sanitize_callback', // the callback before setting is saved to database
	'sanitize_js_callback' => '' // used for the JS value
	) );

You don’t have to use all of them. The ones that matter most are the default, option, transport, and sanitize_callback arguments. The reason option is one that matters is in the way it will save the options into the database. The sanitize_callback matters because it runs before the setting is saved to the database so you have to make sure to sanitize it. The transport value can be important if you want the page to do a full refresh or if it will be AJAXified.

add_control

The next one to look at is the $wp_customize->add_control. This is what the user will see. Much like the add_setting it, too, we have to pass two arguments. The first one being a unique ID, and the second being an associative array.

$wp_customize->add_control( 'option_control', array(
	'label => '', // label for the control
	'description' => '', // description of the control
	'settings' => '' // the setting 
	'section' => '', // core ones are: 'title_tagline', 'colors', 'header_image', 'background_image', 'nav', 'static_front_page'
	'type' => '', // core ones include: 'checkbox', 'radio', 'select', 'textarea', 'dropdown-pages', 'text'
	'choices' => array(), // associative array of 'value' => 'option user sees'
	'priority' => '', // the higher the number the lower it will appear from the top
	'input_attrs' => array(), // associative array of 'attr' => 'value'
	'active_callback' ='' // based on preview context
	) );

So, we have a few options with the controls. Cool, right? What’s even cooler is that there are few others to use. You can also use WP_Customize_Image_Control, WP_Customize_Upload_Control, WP_Customize_Color_Control, and WP_Customize_Media_Control. They just require a little extra code.

$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'media_control', array(
	'label' => 'Image selection',
	'description' => 'Choose an image',
	'settings' => 'default_value',
	'section' => 'random_slider'
) ) );

add_section

Great! Now that we know how to create a setting and a control, we can look at how to create a section to hold those settings. You’ll notice I’m using settings and options a little interchangeably. As stated earlier you can choose how to save things to the database. The theme_mods or option. How you do it is up to you. Now, let’s look at how to create a section, shall we? This too, like the previous two takes two arguments. A unique ID and an associative array.

$wp_customize->add_section( 'my_section', array(
	'title' => '', // the title of the section
	'description' => '', // description of the section
	'priority' => '', // the higher the number the lower in the customizer from the top
	'capability' => '', // default setting is 'edit_theme_options'
	'panel' => '', // if none it will show on main panel
	'active_callback' => '' // based on preview context
	) );

Simple and fairly straight-forward, right? What’s pretty cool too is that you can use the active_callback to your advantage. For example if you wanted to show a certain section only a widgetized area was being used. You could use a callback like:

// in the customizer
'active_callback' => 'widgetized_cb'
// later on in the code
function widgetized_cb(){
	return is_active_sidebar( 'primary' );
}

add_panel

Pretty awesome right? See where some of that logic can come into play? Great! Now you know how to add settings, controls, and sections. We can finally take a look at the final one: panels!

What’s super awesome is that this, too, uses two arguments. A unique ID and an associative array. Notice a pattern here? Let’s look at the available ones:

$wp_customize->add_panel( 'my_panel', array(
	'title' => '', // the title for the panel
	'description' => '', // short description of the panel
	'priority' = '', // the higher number, the lower from the top
	'active_callback' => '' // based on preview context
	) );

As you can see not a lot for the panels – yet. The customizer is constantly being worked on in core. There are a lot of things you can do to make it better if you want to help out.

Previewing

Okay, this is the part where things really come together because it deals with JavaScript. You remember in the add_setting there was an option for transport? If you want to create live previews without the entire page being refreshed, you set it to postMessage. In order for it to take place you will have to include a little JavaScript. I would highly recommend using a dedicated file for this. All you have to do is hook to the right place and enqueue it.

add_action( 'customize_preview_init', 'my_theme_preview' );
function my_theme_preview(){
	wp_enqueue_script( 'my-theme-js-preview-file', get_template_directory_uri() . '/js/my.customize.preview.js', array( 'customize-preview' ), '', true );
}

From there your JavaScript file would include something like:

wp.customize( 'setting_id', function( value ) {
	value.bind( function( newvalue ) {
		// do things
	} );
} );

Final thoughts

So there you have a slight crash course on how the customizer works and what options are available to create a good theme option user experience. There are a few little tricks and things you can also do, so go ahead and explore the core code and find out! You’ll be amazed at what you will find.

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.

Using the_post_thumbnail

For some time I’ve noticed one thing that many people like doing. Recreating core functions. One being the_post_thumbnail(). The reason it drives me crazy is because it means maintaining more code in your theme. Why would you do that to yourself? One of the common things is to wrap it in a conditional check and then use the function if there is a thumbnail. Great! Looks like:

if ( has_post_thumbnail() ){
	the_post_thumbnail();
} else {
	custom_post_thumbnail();
}

The problem

Rewriting a core template tag to suit the theme’s design. Yes, it drives me insane when I know that there is a filter or a hook that can be applied to core functions. Yes. Core has a lot of hook and filters to modify. I’m not saying learn them all but merely suggesting look at the core code when you want to see what and how things are done.

Core file

In order to create our little function let us look at the actual core code, shall we? All the workings are actually placed in the wp-includes/post-thumbnail-template.php file. A little crazy, right? Let’s take a look at the code:

function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
	echo get_the_post_thumbnail( null, $size, $attr );
}

There it is. So what does it do? It creates a default size ( post-thumbnail ) and passes a null argument to get_the_post_thumbnail. A little weird but makes sense, right? So let’s look at the actual function that gets us the image, yeah?

function get_the_post_thumbnail( $post_id = null, $size = 'post-thumbnail', $attr = '' ) {
	$post_id = ( null === $post_id ) ? get_the_ID() : $post_id;
	$post_thumbnail_id = get_post_thumbnail_id( $post_id );

	$size = apply_filters( 'post_thumbnail_size', $size );

	if ( $post_thumbnail_id ) {

		do_action( 'begin_fetch_post_thumbnail_html', $post_id, $post_thumbnail_id, $size );
		if ( in_the_loop() )
			update_post_thumbnail_cache();
		$html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );

		do_action( 'end_fetch_post_thumbnail_html', $post_id, $post_thumbnail_id, $size );

	} else {
		$html = '';
	}

	return apply_filters( 'post_thumbnail_html', $html, $post_id, $post_thumbnail_id, $size, $attr );
}

As you can see it looks like quite a bit. So we will break it down a little bit more. Go down the lines and explain a little more.

Breakdown: the arguments

The first thing you will see is that it asks for a $post_id, then an image size and an attribute. Cool. Still with me? Good. Now let’s move on to the next line of code:

$post_id = ( null === $post_id ) ? get_the_ID() : $post_id;

It tests if the $post_id is identical to null and if it is, we get the post’s ID by using get_the_ID(). Pretty neat if you ask me.

Next, it passes that ID to get_post_thumbnail_id in order to get the image’s attachment ID. You read it right.

The next line is where we come across our first filter. Yay! And it is post_thumbnail_size. What this means is that if you wanted to use

the_post_thumbnail( 'my-theme-image' );

You can add a filter and make it a conditional setting as well. You can use:

add_filter( 'post_thumbnail_size', 'my_new_sizes' );
function my_new_sizes( $size ){
	if ( is_front_page() || is_home() ){
		return 'my-large-front-image';
	}
	return 'my-theme-image';
}

Awesome, right? I like to think so. The next several lines are what create the actual code.

First it checks if it is a true value and if it is we can continue with our code. Then we see an interesting line:

do_action( 'begin_fetch_post_thumbnail_html', $post_id, $post_thumbnail_id, $size );

Kind of a neat little hook. You can print things just before the image tag. From there it updates the thumbnail cache, and then finally it gets the image’s markup by using wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr ). Cool, right? Right. But we are not done just yet.

We have another hook:

do_action( 'end_fetch_post_thumbnail_html', $post_id, $post_thumbnail_id, $size );

With this particular one you can also print things out before the image’s markup. For example:

add_action( 'end_fetch_post_thumbnail_html', 'demo_before_image' );
function demo_before_image(){
	_e( 'I appear before the image', 'textdomain' );
}

The end result will be:

I appear before the image<img width="522" height="270" src="http://sample.dev/wp-content/uploads/2013/03/featured-image-horizontal.jpg">;

Super cool, right?

The next and final steps in the function is the setting of $html. You’ll see that if the $post_thumbnail_id isn’t set then it returns an empty string. From there the last line of code is:

return apply_filters( 'post_thumbnail_html', $html, $post_id, $post_thumbnail_id, $size, $attr );

So, it returns the HTML. Great. As you can see you can filter this.

New filter

Yes, we will use a filter because that is what all good developers like to use and should use.

add_filter( 'post_thumbnail_html', 'theme_slug_post_thumbnail', 10, 2 );
function theme_slug_post_thumbnail( $html, $size ) {
	// get featured image based on $post->ID
	$post_thumbnail_id = get_post_thumbnail_id( get_the_ID() );

	// set size
	$size = (string) apply_filters( 'post_thumbnail_size', 'my-theme-image' );

	//do your magic here
	if ( $post_thumbnail_id ) {
		if ( in_the_loop() ) {
			update_post_thumbnail_cache();
		}
		$html = wp_get_attachment_image( $post_thumbnail_id, $size );
	} else {
		$html = '<img class="featured-image" src="' . get_template_directory_uri() . '/img/custom-thumb.jpg" alt="Image">';
	}

	return '<div class="feature-image-wrapper">' . $html . '</div>';
}

As you can see it is a simplified filter because we aren’t changing every variable the function has to offer. You can, of course, explore more and create your own version. You will see that the one filter I kept was the post_thumbnail_size and that is because if a child theme is created, the child theme can change that with a simple filter.

Child theme friendly post-formats

It’s no surprise I will always preach the making of child themes. Part of the reason is because you can make modifications without losing all that when it comes time to update the parent theme. I mean nothing more exciting than having to recall what files you changed, what code you added, deleted to brighten your day. Troubleshooting. It’s amazing.

The dilemma

Currently the biggest issue I’ve really seen is post formats. It’s not really easy to add to the parent theme. I mean yes and no. Adding to the list is not entirely possible without some parent theme editing and that is what I actually did. I created a quick function that checks and adds to the list of post formats.

The code

function get_theme_post_formats(){
    // $core_formats = array( 'link', 'chat', 'quote', 'gallery', 'status', 'image', 'aside', 'audio', 'video' );
    // base support for the theme
    $formats = array();
    // child if it wants to add
    $child_formats = apply_filters( 'theme_post_formats', array() );
    foreach( $child_formats as $key => $format ){
        if( ! array_key_exists( $format, $formats ) ){
            $formats["$key"] = $format;
        }
    }
    return $formats;
}
add_theme_support( 'post-formats', get_theme_post_formats() );

How it actually works is pretty nifty. What those fourteen little lines of code does is create a filter for child themes to use. That filter is: theme_post_formats. What you would do in the child theme’s function file is something like:

add_filter( 'theme_post_formats', 'child_formats' );
function child_formats(){
    return array( 'link', 'status', 'gallery' );
}

What that will do is add to the list of post formats of the parent theme. The way WordPress core makes you do it is by re-declaring the formats. What I mean by that is you have to call the function add_theme_support and list the already supported formats and add. Seems like a little too much work for some. At least how I feel about it; some may or may not agree with that.

To show you what I mean:

// Parent theme declaration
add_theme_support( 'post-formats', array( 'link', 'gallery', 'quote' );

// Child theme declaration
add_theme_support( 'post-formats', array( 'link', 'gallery', 'quote', 'status', 'chat' );

As you can see both can work. What it boils down to is how you want people to extend to your theme.

Getting the image count in WordPress

A long time ago I had a bit of an issue on how to get the image count from a post. At the time there wasn’t a way that I could think of to properly getting all the needed information; but then again I didn’t know as much as I do now.

I wanted to revisit this because I know it will help out at least one person if not more.

Since the last time I brought up the topic of multiple galleries in one post a lot has changed and a few new functions were added to help solve the dilemma. The key one that helped is: get_post_galleries

It was a simple idea but for some reason at the time it kept only giving my brain a beating. The reason was because it wouldn’t give the correct image count.

New solution

Up until now I was a little confused how I would solve my issue. I knew I needed to get all the galleries and then I needed to get all the images in those galleries. So, here is what I did:

// Get all the galleries in the current post
$galleries = get_post_galleries( get_the_ID(), false );
// Count all the galleries
$total_gal = count( $galleries );
/**
 * count all the images
 * @param array $array The array needed
 * @return int returns the number of images in the post
 */
function _get_total_images( $array ){
    $key = 0;
    $src = 0;
    while ( $key < count( $array ) ){
        $src += count( $array[$key]['src'] );
        $key++;
    }
    return intval( $src );
}

echo _get_total_images( $galleries );

As you can see it really isn’t much code. Part of that reason I wanted to keep the code as simple as possible. Feel free to extend it. In fact, I encourage you to do it.

How it works

What’s nice about the way I went about it is that it will require at least WordPress 3.6 and higher or else you will get an error. Nobody wants those, right?

The first thing we did was create a holder for all the galleries with the get_post_galleries function. We then count how many galleries there are and store that in another variable. That way we can use that later on to output the number if we want. Some people like that sort of thing.

Line 10 is where it goes a little different. I know you’re wondering why I’m declaring a function and then echoing that function in the last line. Part of that reason is because I wanted the ability for child themes to easily filter the text that I would use. Yes, I am aware I didn’t include any text strings. I’m pretty sure you can guess what it would say though, right?

Now, with that little tidbit in your arsenal go and read some code from the includes folder. You won’t be let down.

Using a post as a menu item

Truly a neat little find for many people. I know when I saw this for the first I was beyond astounded.

It does seem a little odd to use one but there are some random cases when it can be useful. Rather than having to use a page you can use a post. Granted it will show up with all the other posts but it is a cool thing to know.

There are a few steps required:

  1. Create the post.
  2. Create a menu
  3. Create the menu item

The first thing is, of course, to create the post. Could be anything you want about whatever you want. A cat, a dog or even a random turtle you saw the other day.

Next, you want to create a menu. In order to do so you want to go to the Appearance section and select Menus. That will bring up the Menus screen. If you don’t already have a menu created, name it whatever you want and press the create button.

Finally, we create the menu item. This is where it can be a little tricky. Why, you ask? Well, by default WordPress shows three options. You can actually have more. You just have to look in the right place.

screen-options

When you click on the Screen Options tab you get a nice little selection of things that you can now edit. As you can see from the following image you now can choose tags, categories and even posts as menu items.

new-options
Options galore!

From there you will choose what you want. In our case we will check off all the options because we like to live dangerously and love options.

Now we see that have a few more things in our roster of options.

new-menu-options

From there we can now choose posts as menu items. Awesome, right?

Vary all the vagrants

It’s no secret that creating a proper web hosting environment can be a pain. Main reason being that there are many things that you have to take into consideration. Processor, storage, memory and sometimes if the motherboard can support it all. And I’m getting far ahead of myself again.

When it comes to creating WordPress themes and plugins finding the right environment can be tricky. Even more so when you use a Windows operating system.

Vagrant

What is it? Vagrant is an amazing tool and an amazing thing to get to know. I’m still in the process of learning and I love it. It does deal a lot with the command line so I have to familiarize myself with that once more. It has been years since I’ve used it.

Virtual Box

Yes. A box. A virtual one at that. VirtualBox is another great tool when it comes to creating a working environment. The main reason I love it is because you can have several machines on one system. Meaning you can have Linux, Windows and possibly OSX running on any machine you want. Keep in mind it is a virtual instance and not the real thing so some errors may occur.

Learning as you go

A few weeks ago I saw more and more posts being shared about VVV. I was super impressed and fell in love with it. So I did a little more research and came across a few other posts about how to work with VVV. I figured I’d share with you a few of those:

Those are just some of the links I wanted to share. There are more but didn’t want to create a giant list of links. I mean after all that’s what a search engine is for, right?

Playing nice with plugins

Yep, you read that right. Playing nice. With plugins. I know what you’re thinking and are probably wondering what I mean by that.

Don’t lie

You know you want to ask. What do you mean by that?

What I mean is that as a themer you shouldn’t be adding frivolous things to your theme. What I mean by this is things that add content or completely alter, and manipulate, content. Things like sharing buttons, meta boxes or things that a user may end up losing once the choose a different theme. That is what I mean.

Background

What really brought this up is a change in guidelines to the theme review. It has been around but up until recently has been more enforced than before. At least from what I’ve noticed.

jetpack-sharing

Recently, I did a review where the developer used plugin functionality in the theme. Mainly the sharing buttons. I know, I know. Everybody loves to share their content. But the thing is when I switch a theme I want those buttons to stay where they are and not move around on me. A good portion of the time they reside towards the bottom of the post. As noted by the quick screenshot. That is using the Jetpack plugin’s sharing module, for demonstration purposes of course.

social-sharingJetpack is a great plugin and does the job for me and a few others. But what about those that append their sharing options to the content. It can look a little funky. A great example is the image on the left because it shows simple content but it showcases the issue I’m more concerned about fixing.

What is the issue?

The issue is that when you have content that is paginated the sharing icons get right in the middle of it all. As you can see the real content of the post ends with “Post Page 1” but can continue to page 2 and then three. It creates a separation that can ruin almost any design.

Now, I know what you’re probably going to say. But Jose, that’s a plugin. My theme handles it better. Of course it does. The theme developer chose the placing of the elements and how to display it. But what if you are a new user and are using a plugin? Looking at the second image you can see what can happen. To me it does look a little odd having sharing icons in between.

A better example is the default theme Twenty Fourteen. I wanted to use it because I do like the way it looks but when it came to displaying the post pagination it didn’t look right to me.

default-sharing

As you can see it almost feels like the content gets cut off. Yeah, I know it does seem a little picky but when you want to share a theme with many people you have to think about who the end-user really will be. It reminds me of a talk Nikolay did in WordCamp SF. Made me think about who will really be looking at the code.

How to solve it

What’s really funny about how I managed to resolve this issue, at least for me, was by thinking about when that social bar gets added. Now, do keep in mind I do use Jetpack on this site and try to test with it on a local setup. This is where the playing nice with plugins comes into play.

Notice I install the plugin and add styling and functionality to it rather than create my own? That is the way any theme developer should be creating any and all themes. Whether personal, for fun or commercial.

Currently I’m trying to redesign my site, of course, and have at least one post that is split up into more than one page. While that is sort of an edge case it does represent a bit of an issue that I would like to discuss.

The first thing I did of course was turn to the code. The first file I looked at was the Jetpack PHP file to see what things were being loaded. I noticed that Jetpack uses modules so I went ahead and skipped straight to the sharedaddy module. Started looking at the sharedaddy PHP file and it led me to the sharing file. Then the sharing service file.

You’re sort of wondering where this is going right? Thankfully that was the last file I really needed to see because towards the end of the file there was a line of code that was music to my eyes.

add_filter( 'the_content', 'sharing_display', 19 );

What that meant was that I could add a filter to the content and add a priority greater than 19.

Enter the code

So in order to add to the content I needed to filter the content and add to it. What is nice is that we can easily do that with a simple call. By using

add_filter( 'filter_name', 'function_callback' );

I managed to get the result I wanted and was so desperately looking for. The code I used is actually quite simple. I think that is part of the reason I’m shocked it worked the way it did.

// Append linked_pages if any are available
add_filter( 'the_content', 'my_theme_add_pages' );
function my_theme_add_pages( $content ){
    // Get the markup
    $linked = wp_link_pages(
        array(
            'before' => '<div class="page-links">Pages: ',
            'after' => '</div>',
            'echo' => false,
            ) );
    // If there is any markup append it
    if ( $linked ){
        $content .= $linked;
    } // otherwise we just return the regular content
    return $content;
}

Simple right? What really makes this work is the last key in the array. The echo key and setting it to false so that it won’t output any code and stores it to the $linked variable. Then a quick check to see if there is anything and if there is concactinate to the $content. The next step is styling it to give it some room.

personal-adjustment

As you can tell I still have some styling to do but now my post/page navigation links don’t appear after my sharing icons.