A metabox for your layout options

It’s no surprise I can be vocal when I am reviewing a theme. Many know that I’ll spurt out what I end up seeing in a lot of themes. There is one thing that really does drive me crazy though and that is when people copy and paste code to their theme without actually knowing how the code actually works.

One file that has really been rather popular is using a metabox in order to choose the layout of the post or page. That’s great. I love that ability but then again who doesn’t love having that control? I think what drives me bonkers is that this code is super predictable before the file is opened. The file adds two actions. One to add_meta_boxes and the second to the save_post hooks. Great! Very super simplistic and hard to mess up, right?

I created a gist with the name of the theme changed. The code is the same that I’ve seen in many other themes though. From authors who have several themes in the repo to new authors to the repo.

One of the first things that you may notice is the use of two globals.

global $post, $deargodwhy_sidebar_layout;

First there should be no reason for that and second those hooks pass the $post object. We’ll look at the first one: add_meta_boxes

Using the developer resources as a guide we see that the hook for adding metaboxes uses two arguments. The post type and the post.

do_action( 'add_meta_boxes', string $post_type, WP_Post $post )

The first one being the string of the current post type and the second being the WordPress post object. Now, what’s super cool about that is that we can now register a metabox in any post type we want and it does on every post type if we don’t pay attention to what we are doing. There is also one more hook we could potentially use in order to use a metabox in only one specified post type. That hook is add_meta_boxes_{$post_type} and the developer docs does explain it a little better. For example, if you wanted to add a metabox to only your EDD downloads, you could do something like:

add_action( 'add_meta_boxes_download', 'jmc_download_extra_metaboxes', 10 );
function jmc_download_extra_metaboxes( $post ) {
	// Do our magic here.
}

In order to now add our metabox we do need to use the function add_meta_box() so let’s take a look at how that function is used.

add_meta_box( $id, $title, $callback, $screen = null, $context = 'advanced', $priority = 'default', $callback_args = null )

Now, if you want to take a closer look at what each one of those parameters actually does then I suggest you take a look over the developer docs. It is well worth your time if you really want to understand how to create a better user experience and understand how WordPress creates those.

Another thing I wanted to look over was the save_post callback being used. The biggest issue is the use of the foreach() loop.

foreach( $deargodwhy_sidebar_layout as $field ){  
        //Execute this saving function
        $old = get_post_meta( $post_id, 'deargodwhy_sidebar_layout', true ); 
        $new = sanitize_text_field( $_POST['deargodwhy_sidebar_layout'] );
        if ( $new && $new != $old ) {  
            update_post_meta($post_id, 'deargodwhy_sidebar_layout', $new );  
        } elseif ('' == $new && $old ) {  
            delete_post_meta( $post_id,'deargodwhy_sidebar_layout',  $old );  
        } 
     }

The reason is it is creating an unnecessary loop. The only thing that needs to be checked is the value being input and to make sure that it is a valid option. A quick change to the code and we have:

if ( ! empty( $_POST['deargodwhy_sidebar_layout'] )
	&& in_array( $_POST['deargodwhy_sidebar_layout'], array( 'right-sidebar', 'no-sidebar' ), true )
	) {
	update_post_meta( $post_id, 'deargodwhy_sidebar_layout', $_POST['deargodwhy_sidebar_layout'] );
}

Knowing those things we could make changes to the file and not only will we have a better understanding of how WordPress creates metaboxes but we have a file that doesn’t pollute the $GLOBALS with info that we only use in one place. If you look at what those changes were in the diff, you will see that not a lot was changed. It only looks that way since I removed a lot of the linting errors.

My tour of creating a PHPCodeSniffer Standard

It’s no surprise I like to learn new things. I also like to read things when I can. Okay, a lot of the time I skim through things but I make an effort to learn from it.

The last couple of weeks I’ve looked at working with the PHPCodeSniffer. I installed it and never really played with it. Not until last week did I realize my version was out of date. Easy fix but something to keep in mind. The current version at the time of this writing is 2.7.1 and that’s what I am currently running on my Windows machine as well as my MBP.

So, here are some of the things I learned from attempting to create a standard and a sniff.

Lessons Learned

  • Read the docs
  • Carefully read the docs
  • Experiment

One of the first things to understand is that you need to know where your PHPCS standards reside.  There you will see a series of folders and files. The one that we will focus on is the Standards folder. This is where our newly created Standards will live.

The steps

We will outline the steps needed to create both a standard as well as a sniff. They are:

  1. Create the directories
  2. Create the XML file
  3. Create the sniff or sniffs if you want more

Sounds super simple right?

So let’s move on!

The first thing we will do is create the directories. The first one is the name of our standard. The second directory will be Sniffs and this is where all of our sniffs will reside. For example, WordPress standards looks like the following image:

Inside of the folder we will then create the ruleset.xml file with the needed information for our standard. It will look something like the following image:

Now, we can finally create our sniffs. But wait there is one thing you should know before making this and that is that you need to have a category folder.

Why?

It makes it easier to organize and know what we are looking for as well. For the sake of this post, I created an Example folder and inside of that I created a ListSniff.php file. Pay close attention to that detail as it will matter down the line. I learned this one because of errors I kept getting.

So, our new folder structure should look a little like:

codesniffer\standards\
codesniffer\standards\YourStandard
codesniffer\standards\YourStandard\ruleset.xml
codesniffer\standards\YourStandard\Sniffs
codesniffer\standards\YourStandard\Sniffs\Example
codesniffer\standards\YourStandard\Sniffs\Example\ListSniff.php

Now we can create our sniff!

This is where the fun really begins for some.

The important thing here is both the file and the class inside of the file must end with Sniff. For my example I named it ListSniff.php so the class would look like:

<?php
/** Example class created for demonstration purposes only **/
class YourStandard_Sniffs_Example_ListSniff implements PHP_CodeSniffer_Sniff {

	public function register() {
		return array();
	} // end register()

	public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {

		// Tokenize the file, right?
		$tokens = $phpcsFile->getTokens();

		// We need this in order show what the error actually is.
		$phpcsFile->addError( $error, $stackPtr, $code = '', $data = array(), $severity = 0, $fixable = false );

		// We can even add a warning if we want.
		$phpcsFile->addWarning( $warning, $stackPtr, $code = '', $data = array(), $severity = 0, $fixable = false );
	} //end process()
}

You will see two very interesting things here. The first one being the naming of the class. It needs to be:

class {Folder of the standard name}_{the Sniffs folder}_{subfolder of Sniffs}_{your sniff}Sniff

And the second being the implements PHP_CodeSniffer_Sniff. This is straight from their documentation:

Each sniff must implement the PHP_CodeSniffer_Sniff interface so that PHP_CodeSniffer knows that it should instantiate the sniff once it’s invoked.

The reason is because the PHP_CodeSniffer_Sniff interface has two methods that need to be utilized. The register() and process() methods.

The methods

The first one – register – simply does that. You register what tokens you want the CodeSniffer to catch. PHP.net does provide a super handy list with all the available tokens.

Now, let us take a look at how the addError and addWarning sort of work so you can get an idea of what you can do.

First the addError:

/**
@param string  $error    The error message.
@param int     $line     The line on which the error occurred.
@param int     $column   The column at which the error occurred.
@param string  $code     A violation code unique to the sniff message.
@param array   $data     Replacements for the error message.
@param int     $severity The severity level for this error. A value of 0
                         will be converted into the default severity level.
@param boolean $fixable  Can the error be fixed by the sniff?
*/

What’s really nice is that the addWarning does nearly the same:

/**
@param string  $warning  The error message.
@param int     $line     The line on which the warning occurred.
@param int     $column   The column at which the warning occurred.
@param string  $code     A violation code unique to the sniff message.
@param array   $data     Replacements for the warning message.
@param int     $severity The severity level for this warning. A value of 0
                         will be converted into the default severity level.
@param boolean $fixable  Can the warning be fixed by the sniff?
*/

With that I created a random test sniff. It turned out a little like:

class Examplee_Sniffs_Example_FunctionSniff implements PHP_CodeSniffer_Sniff {

	public function register() {
		return array( T_FUNCTION );
	} // end register()

	public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {

		// Tokenize it!
		$tokens = $phpcsFile->getTokens();

		// We want to check.
		if ( $tokens[ $stackPtr ]['content'] ) {

			// build up our message to show on the report.
			$warn = 'Make sure %s is prefixed';

			// build up the array of data we want to pass
			$data = array( trim( $phpcsFile->getDeclarationName( $stackPtr ) ) );

			// finally we add our warning. Could use addError().
			$phpcsFile->addWarning( $warn, $stackPtr, 'found', $data );
		}
	} //end process()
}

I did try it out on Twenty Seventeen functions file and got the following:

FOUND 0 ERRORS AND 14 WARNINGS AFFECTING 14 LINES
----------------------------------------------------------------------
  27 | WARNING | Make sure twentyseventeen_setup is prefixed
 200 | WARNING | Make sure twentyseventeen_content_width is prefixed
 222 | WARNING | Make sure twentyseventeen_fonts_url is prefixed
 257 | WARNING | Make sure twentyseventeen_resource_hints is prefixed
 274 | WARNING | Make sure twentyseventeen_widgets_init is prefixed
 315 | WARNING | Make sure twentyseventeen_excerpt_more is prefixed
 336 | WARNING | Make sure twentyseventeen_javascript_detection is
     |         | prefixed
 344 | WARNING | Make sure twentyseventeen_pingback_header is
     |         | prefixed
 354 | WARNING | Make sure twentyseventeen_colors_css_wrap is
     |         | prefixed
 371 | WARNING | Make sure twentyseventeen_scripts is prefixed
 433 | WARNING | Make sure twentyseventeen_content_image_sizes_attr
     |         | is prefixed
 460 | WARNING | Make sure twentyseventeen_header_image_tag is
     |         | prefixed
 479 | WARNING | Make sure twentyseventeen_post_thumbnail_sizes_attr
     |         | is prefixed
 499 | WARNING | Make sure twentyseventeen_front_page_template is
     |         | prefixed
----------------------------------------------------------------------

So you can see some versatility when using the PHPCodeSniffer. If you really want to help out the Theme Review team then I highly recommend heading over to the github repo and helping out.

As for me, I’ll be digging more into how to create random tests because I like dabbling and breaking those things.

Creating a diff file

The other day I made a quick video on how to create PHPCS reports. Later on during the day I was asked about creating a patch to meta. Of course I’m going to make another video to help somebody else out.

In the video I go over on how to create a diff file using SVN and atom. With that file you can submit patches to core and meta.

There are two places to look for. If you are submitting a new ticket, you will see a checkbox that will take you to an upload screen.

Or if you are contributing to an already existing ticket you will see a field where you can upload files.

Hope this helps some of you out!

Creating sample PHPCS reports

I created a quick video in hopes to help some people understand the great thing that is using the PHP_CodeSniffer and how good it can be for not only developing plugins but WordPress themes as well.

In the video I create two sample reports. The first one a source report and the second just a summary report. The documentation does provide some useful information to help along the way in creating those reports.

Hope this helps some people out!

Getting WordPress Custom Post Types in the customizer

It’s no surprise I love a good theme. I love it even more when I get a choice of what can go where – extra cookie points if I don’t have to input that information. A while back I wrote out a post about presenting content within themes.

In the course of reviewing so many themes, I noticed one thing in common with many themes. They love trying to control my content, and that is great, as that is what they are meant to do; but when they start creating some content this is where my headache begins. Yes, there is some trivial content like a small span of text but that is very dismissable. What I’m talking about is when I see a theme using textarea when they register a theme setting. This concerns me. This worries me.

Why worry?

This worries me because I can insert a novel in that option. An entire novel if I wanted to. Okay, perhaps not an entire novel but about 4,294,967,295 characters in that theme option. Granted I’m never going to be doing that inside of an option but why would you even give me that option? What happens if I have a recipe that I would like to display? Would I have to copy and paste it or find a hackish way of doing it? I mean you could potentially use shortcodes but then you get an even bigger headache.

As a theme reviewer I try to think about different types of content a user could have. It makes it easy to know what to look for rather than having to rely on having the user ( me in this case ) input all that content or info all over again. Portability. It’s a great thing.

Using the customizer to get a live preview is what drove me to actually writing out this post. Earlier in the day I was trying out a different theme because I’m looking for a grid style. Not for the entire site but only some parts. Sort of a e-commerce if you will. I have the content, I have what I need. I am only looking to display it but when I’m asked to input what I already have over and over I just gave up.

Getting content

One of the things I would love to see more is a dropdown of my content. The customize menu component that was added to core is a great example of this. It gives you a list of all your pages, posts and even other post types that you have registered.

The other day I was talking to a few other theme reviewers and shared a snippet of code. I’ll post a simplified version first and then break it down and expand upon it as we progress.

add_action( 'customize_register', 'jmc_customize' );
function jmc_customize( $wp_customize ) {
	// get list of post types
	// Check if we have any
	// create an associative array for later use
	// register our setting
	// register our control
}

What’s super neat about that little snippet is that it will create a dropdown of post types that are registered. The second part of the snippet would be:

// get our setting and make sure it's not empty
if ( get_theme_mod( 'section-one-type' ) ) {
	// create a new WP_Query
	// create a new loop
	// make sure we wp_reset_postdata()
}

That little snippet would be in the template file of your choosing. What do you say we break it down a little to get an idea of what the code is actually doing, yeah?

What are we doing?

The first thing we do is hook to the customize_register hook and create our function callback. Inside of that function a lot of our logic will reside. We get all the available post types by using get_post_types() and create a variable to contain them if there are any.

// We create a variable to house our post types
$post_types = get_post_types( array(
	'public'   => true,
	'_builtin' => false
), 'object' );

Then we check to see if there are any and if there are we will create our setting and create our control.

// check to make sure we have any and if we don't we won't even register anything
if ( ! empty( $post_types ) ) { // register setting and control }

Now that we have our post types we need to create an associative array to pass our control. These are the options our users will see.

// create empty array to house types and names.
$types = array();
// we loop and assign.
foreach ( $post_types as $type ) {
	// name is the registered name and label is what the user sees.
	$types[ $type->name ] = $type->label;
}

We then register our setting.

// We register our setting.
$wp_customize->add_setting( 'section-one-type',
array(
	// we set a default just in case.
	'default' => key( $post_types ),
	// make sure we validate/sanitize our setting.
	'sanitize_callback' => 'jmc_post_type_validate',
) );

You will notice that I’m using a custom function in order to validate the setting. I called it jmc_post_type_validate and it looks like:

/**
 * Validate that we really are using a registered post type otherwise we return a default set
 * by the registered setting.
 *
 * @param  [type] $value   Value that is passed by customizer.
 * @param  [type] $setting The setting object.
 * @return [type] Return a validated value.
 */
function jmc_post_type_validate( $value, $setting ) {
	// Get a list of available post types.
	$post_types = get_post_types( array(
		'public'   => true,
		'_builtin' => false,
	), 'object' );

	// Check if what the user selected is valid.
	if ( array_key_exists( $value, $post_types ) ) {
		// If it is we return it.
		return $value;
	} else {
		// Otherwise return a default setting.
		return $setting->default;
	}
}

Finally, we create our control.

// register our control.
$wp_customize->add_control( 'section-one-type',
	// we pass our array.
	array(
		// The label for the markup.
		'label'       => __( 'The post type for section one', 'jmc' ),
		// A helpful description that display in the customizer.
		'description' => __( 'Choose what post type you would like to show', 'jmc' ),
		// What setting this control is attached to.
		'settings'    => 'section-one-type',
		// The type of control we want to display.
		'type'        => 'select',
		// We pass our $types associative array we made earlier.
		'choices'     => $types,
		// The section we want this to show on.
		'section'     => 'static_front_page',
	)
);

Super cool, right?

That is great and all but now what about displaying that on the front end? Enter get_metadata() and WP_Query. Yes, a new loop. Even better is that we can now use metadata within post types. How amazing is that?

Take the following for example:

if ( ! get_theme_mod( 'section-one-type' ) === false ) {
	// create a new WP_Query.
	$type = new WP_Query(
		array(
			// use the post type passed in the setting.
			'post_type'      => get_theme_mod( 'section-one-type' ),
			// depending on how many columns we want set it accordingly.
			'posts_per_page' => 3,
		)
	);

	// create our custom loop.
	if ( $type->have_posts() ) {
		while ( $type->have_posts() ) {
			$type->the_post();
			the_title( '<h3>', '</h3>' );
		}
	}
	// because we are nice, we reset the post data not the query.
	wp_reset_postdata();
}

This can be expanded of course but you sort of get the idea. I’ll post the snippet that does include a little more inline documentation in hopes it does help somebody out.

add_action( 'customize_register', 'jmc_customize' );
/**
 * Register our customizer settings for the theme.
 *
 * @method jmc_customize
 * @param  [type] $wp_customize The customizer object.
 */
function jmc_customize( $wp_customize ) {
	// get list of post types.
	$post_types = get_post_types( array(
		'public'   => true,
		'_builtin' => false,
	), 'object' );

	// check if there are types that can be used.
	if ( ! empty( $post_types ) ) {
		// create empty array.
		$types = array();

		// loop over post types.
		foreach ( $post_types as $type ) {
			// name is the registered type and label is what user sees.
			$types[ $type->name ] = $type->label;
		}

		// We register our setting.
		$wp_customize->add_setting( 'section-one-type',
			array(
				// we set a default just in case.
				'default'           => key( $post_types ),
				// make sure we validate/sanitize our setting.
				'sanitize_callback' => 'jmc_post_type_validate',
			)
		);

		// register our control.
		$wp_customize->add_control( 'section-one-type',
			// we pass our array.
			array(
				// The label for the markup.
				'label'       => __( 'The post type for section one', 'jmc' ),
				// A helpful description that display in the customizer.
				'description' => __( 'Choose what post type you would like to show', 'jmc' ),
				// What setting this control is attached to.
				'settings'    => 'section-one-type',
				// The type of control we want to display.
				'type'        => 'select',
				// We pass our $types associative array we made earlier.
				'choices'     => $types,
				// The section we want this to show on.
				'section'     => 'static_front_page',
			)
		);
	}
}

/**
 * Validate that we really are using a registered post type otherwise we return a default set
 * by the registered setting.
 *
 * @param  [type] $value   Value that is passed by customizer.
 * @param  [type] $setting The setting object.
 * @return [type] Return a validated value.
 */
function jmc_post_type_validate( $value, $setting ) {
	// Get a list of available post types.
	$post_types = get_post_types( array( 'public' => true, '_builtin' => false ), 'object' );
	// Check if what the user selected is valid.
	if ( array_key_exists( $value, $post_types ) ) {
		// If it is we return it.
		return $value;
	} else {
		// Otherwise return a default setting.
		return $setting->default;
	}
}

Oh, if you do want to use get_post_meta() you can use it a little something like:

get_post_meta( get_the_ID(), 'subtitle', true );

Presenting WordPress content with themes

There are a lot of ways of getting user content in WordPress. Plugins are ideal for creating that content and provide that functionality. Themes are better at presenting that content.

One of the many things we often see in theme reviews is what are known as pseudo post types. I love Justin’s post in regards to content and post types so do give a read to understand a little more. The following paragraphs will focus more on code and methods of not only getting content from the WordPress database but also on how to make use of that data for use in the customizer and on the front-end of a site.

The content

First we need to think about what we want to show on the page, right? For this example will focus on a single post. What’s super cool is that this can be applied to custom post types as well and not just the standard post. The function we will use for this is get_post_meta() and the developer documentation is a good starting point: https://developer.wordpress.org/reference/functions/get_post_meta/

What matters here is the returning value from that function:

(mixed) Will be an array if $single is false. Will be value of meta data field if $single is true.

That’s great, but what does it mean, right? Let’s say what we add a custom field to a post. Perhaps a subtitle. Depending on what you set your custom field to, you would use:

if ( $subtitle = get_post_meta( get_the_ID(), 'subtitle', true ) ) {
	printf( '<span class="subtitle">%s</span>', $subtitle );
}

That’s much easier than creating a custom meta box that would be lost when the theme is changed, right? I know you may be asking, but what about other post types? Well, we can use get_metadata() for that. The developer docs help here as well. All we do is change a small thing and we can use it in an archive style.

if ( $subtitle = get_metadata( get_post_type(), get_the_ID(), 'subtitle', true ) ) {
	printf( '<span class="subtitle">%s</span>', $subtitle );
}

Great!

Other types

So, with that you have a basic starting point of core’s built-in capabilities. Metadata is super useful and easy to get. Best part is that if that value doesn’t exist, we don’t output anything! No extra markup or code to worry about.

Now, there are tons of plugins out there that create all sorts of data and content for users. Let’s take a quick look at one that is pretty popular: testimonials.

What’s super cool is that by using a few function_exists() we can check if a plugin is active or not. The registration method may differ from plugin to plugin but the basic thing is to use the right function to check. There are a few functions we can use:

  • function_exists()
  • method_exists()
  • class_exists()
  • interface_exists()

That’s super cool and even core has one that can be useful as well:

  • post_type_exists()

Phenomenal if you want to check for a testimonial post type, or a portfolio, or a form, event, you name it. For this example I’ll use the Easy Testimonials plugin to test.

if ( class_exists( 'easyTestimonials' ) && post_type_exists( 'testimonial' ) ) {
	$testimonials = new WP_Query( array( 'post_type' => 'testimonial', 'posts_per_page' => 3 ) );
	if ( $testimonials->have_posts() ) {
		while ( $testimonials->have_posts() ) {
			$testimonials->the_post();
			the_title( '<h3 class="testimonial-title">', '</h3>' );
		}
	}
	wp_reset_postdata();
}

Super quick example. You can see what it is doing at the beginning. We are checking to see if the class easyTestimonials exists as well as the post type. If the functions return true then we can run our query. What’s nice is that now we are in control of how to present that content however we desire.

But what about the customizer?

I mentioned this a little earlier and we can use this as callback for a control. Yes, conditionally show a control based on what is active and available. Super awesome, right?

In this example we will use the custom fields suite plugin for a page customizer control. This is going to be a unique example in that we are going to check if the plugin is active and if a field is populated on a page. Now, it may not be the best example but it will give you an idea of how it works.

add_action( 'customize_register', function( $wp_customize ) {
	$wp_customize->add_setting( 'hero-location',
		array(
			'default' => 'above',
			'sanitize_callback' => 'jmc_sani_location'
		) );
	$wp_customize->add_control( 'hero-location-control',
		array(
			'settings'        => 'hero-location',
			'label'           => __( 'Hero Image Location', 'text-domain' ),
			'description'     => __( 'Where will the hero image show? Above or below the secondary menu location', 'text-domain'),
			'section'         => 'layout',
			'type'            => 'select',
			'active_callback' => 'jmc_check_field',
			'choices' => array(
				'above' => __( 'Above', 'text-domain' ),
				'below' => __( 'Below', 'text-domain' )
			)
		) );
}, 10 );
function jmc_check_field(){
	// bail if it's not a page
	if ( !is_page() ) {
		return false;
	}

	// check for the function and value
	if ( function_exists( 'CFS' ) && CFS()->get( 'hero-image' ) ) {
		return true;
	}

	// if nothing we won't show the control
	return false;
}

Let’s break it down a little bit. The part that really matters is:

'active_callback' => 'jmc_check_field'

This callback is what will handle our logic. This ultimately determines if that control will show or not. We want to begin with the assumption that it will not show so we always return false at the end. What’s super cool is that this can be done with sections as well. This next example is nice because we check for the available post types and can use a new WP_Query on the theme to get the content.

add_action( 'customize_register', 'jmc_customize' );
function jmc_customize( $wp_customize ) {
	// get list of post types
	$post_types = get_post_types( array( 'public' => true, '_builtin' => false ), 'object' );

	if ( ! empty( $post_types ) ) {
		$types = array();
		foreach( $post_types as $type ) {
			$types[$type->name] = $type->label;
		}

		$wp_customize->add_section( 'section-one',
			array(
				'title'           => __( 'Front Page sections', 'text-domain' ),
				'description'     => __( 'Choose what else shows on the front', 'text-domain' ),
				'active_callback' => 'jmc_haz_post_types'
			) );

		$wp_customize->add_setting( 'section-one-type',
			array(
				'default'           => '',
				'sanitize_callback' => 'jmc_post_validate',
				)
		);

		$wp_customize->add_control( 'section-one-control',
			array(
				'label'       => __( 'The post type for section one', 'text-domain' ),
				'description' => __( 'Choose what post type you would like to show', 'text-domain' ),
				'settings'    => 'section-one-type',
				'type'        => 'select',
				'choices'     => $types,
				'section'     => 'section-one'
			)
		);
	}
}

function jmc_haz_post_types() {
	$types = get_post_types( array( 'public' => true, '_builtin' => false ), 'object' )
	return empty( $types );
}

function jmc_post_validate( $value, $setting ){
	$post_types = get_post_types( array( 'public' => true, '_builtin' => false ), 'object' );
	if ( array_key_exists( $value, $post_types ) ){
		return $value;
	} else {
		return $setting->default;
	}
}

Then on the front-end we could do something like:

if ( ! get_theme_mod( 'section-one-type' ) === false ) {
	$type = new WP_Query(
	array( 'post_type' => get_theme_mod( 'section-one-type' ),
		'posts_per_page' => 3
		)
	);

	if ( $type->have_posts() ):
		while( $type->have_posts() ): $type->the_post();
		the_title( '<h3>', '</h3>' );
		endwhile;
	endif;
	wp_reset_postdata();
}

The thing to remember is that content should remain when the theme is switched. There should be no reason for a user to have to input the same thing over and over again on every theme switch – after all they are after the design and not the content of the theme. A good practice to keep in mind when creating your options is:

Do I give them decision A or decision B?

Working with paginate_links

It is no secret that I try to advocate the use of core functions when possible. The idea of maintaining less code is a great one for any developer. It’s the old set it and forget mentality.

What I do see a lot of is the use of my_theme_pagination that uses get_pagenum_link in order to get all the page links. Yes it does use a core function but it uses it several times. Why not just use a core function that has been available since 2.1? Talk about way back, right? The best part is that you are given a few options when you use paginate_links.

The core code

Let us take a look at the core code. The function is found in the general-template.php file of the wp-includes folder. There are approximately 142 lines that make up this function. As you can see there is quite a bit of logic behind it to work. We will look at the key things. The first one being the array we can pass as an argument, and the second being the type key in that array.

You can use the function without passing anything to it and it will work. There is a reason for that. The $args parameter that can be passed gets merged with a few defaults. What are those, you ask? Here they are:

$defaults = array(
	'base' => $pagenum_link, // http://example.com/all_posts.php%_% : %_% is replaced by format (below)
	'format' => $format, // ?page=%#% : %#% is replaced by the page number
	'total' => $total,
	'current' => $current,
	'show_all' => false,
	'prev_next' => true,
	'prev_text' => __('&laquo; Previous'),
	'next_text' => __('Next &raquo;'),
	'end_size' => 1,
	'mid_size' => 2,
	'type' => 'plain',
	'add_args' => array(), // array of query args to add
	'add_fragment' => '',
	'before_page_number' => '',
	'after_page_number' => ''
);

$args = wp_parse_args( $args, $defaults );

Quite a few options available to use. For the sake of this post we will focus on mostly on the type. There are three possible return types. They are array,list, and an empty value. We can see those towards the end of the function:

switch ( $args['type'] ) {
	case 'array' :
		return $page_links;

	case 'list' :
		$r .= "<ul class='page-numbers'>\n\t<li>";
		$r .= join("</li>\n\t<li>", $page_links);
		$r .= "</li>\n</ul>\n";
		break;

	default :
		$r = join("\n", $page_links);
		break;
}

It uses a switch statement to set the $r value that is ultimately returned. Yes, paginate_links returns and does not output any content. This is where we can actually take advantage of that.

Usage

Now with that in mind let us create some example usage, yeah? This is the part that gets fun! So we will take a look at using all three options and how they can be expanded or altered to suit your theme’s needs.

Array

Returning the array is one of the neater ways of using the function. The reason is that it returns an array of links. The amount of links is the amount of keys available for us to manipulate. Yes, we can style to our choosing. Let’s look at a sample return:

Array
(
    [0] => <span class='page-numbers current'>1</span>
    [1] => <a class='page-numbers' href='http://localhost/page/2/'>2</a>
    [2] => <a class='page-numbers' href='http://localhost/page/3/'>3</a>
    [3] => <span class="page-numbers dots">&hellip;</span>
    [4] => <a class='page-numbers' href='http://localhost/page/10/'>10</a>
    [5] => <a class="next page-numbers" href="http://localhost/page/2/">Next &raquo;</a>
)

What’s cool about that is you can see that by default you have the CSS classes page-number, current, and dots that you can use for some styling. Pretty awesome if you ask me. You can now expand upon that markup. A good way is by using the foreach to loop over and create your HTML markup. A quick example is:

$links = paginate_links( array( 'type' => 'array' ) );

echo '<div class="pagination col-6">';
foreach( $links as $link ){
	echo $link;
}
echo '</div>';

Yes, that is a super quick way of doing things but you get the idea. You can expand upon that to your heart’s content and add your needed classes or markup.

List

Another way is returning the list. An already HTML markup of our links in an unordered list. The returning text looks a little like:

<ul class='page-numbers'>
	<li><span class='page-numbers current'>1</span></li>
	<li><a class='page-numbers' href='http://locahost/page/2/'>2</a></li>
	<li><a class='page-numbers' href='http://localhost/page/3/'>3</a></li>
	<li><span class="page-numbers dots">&hellip;</span></li>
	<li><a class='page-numbers' href='http://localhost/page/10/'>10</a></li>
	<li><a class="next page-numbers" href="http://localhost/page/2/">Next &raquo;</a></li>
</ul>

What is super awesome about it is you can use just one line of code:

echo paginate_links( array( 'type' => 'list' ) );

Super awesome, right? The reason I love that is you can just leave that code and style it all. No special markup to worry about as it is already taken care of. You can use something like:

ul.page-numbers {
  clear: both;
  font-size: 1.4em;
  color: #deaf01;
}

ul.page-numbers li {
  display: inline-block;
}

It doesn’t have to be super crazy but you get the idea.

Empty value

Now for the simplest way of using the function.

echo paginate_links();

A lot of work, right? Super, super simple and you don’t have to worry about creating any extra markup. That is if you don’t want to. It returns a string of all the links and you can go about your business. If you really like super simple HTML markup then please use that.

User changes

Yes, we can have a user change a few of the things too if we want. Let’s take a quick look at how we can change the amount of links to show around the current page.

function jc_pagination(){
	echo paginate_links( 
		array(
		'show_all' => get_theme_mod( 'all-links', false ),
		'type' => 'list',
		'mid_size' => get_theme_mod( 'mid-links', 3 )
		)
	)
}

Pretty cool, right? With that get_theme_mod you can now have the user decide how many links will show before and after the current page. Yes, it is a minor touch but it can go a long way with some users.

Three sliders, one option, and a few tears later

Yes, sliders have a special place in my heart. Granted a super tiny place in my theme reviewer’s heart. Now, I’ve created a few tutorials, guides, resources, links, what you will on this site in order to share some of my insights into WordPress theme development and perhaps some WordPress theme reviews along the way.

There are a lot of things I have learned and a lot of things I had to learn. I think the biggest takeaway from this post will be that integrating a slider plugin to a theme is fairly easy to do but a pain in the butt to fully integrate.

So, let’s get the show on the road!

First steps

Okay, we need to figure out first what slider we would like to play nice with, right? I chose sort of at random three different plugins that all create sliders.

I was going to use Meta Slider but they actually have a fairly extensive documentation section on theme integration. So major kudos for them on providing those code snippets!

As you can see we have our three sliders to choose from and now we need to determine if they are active or not. I know some will want to use is_plugin_active() but I will tell you not to. The reason for not doing so is so that you don’t load an extra file. So instead we will use some basic PHP functions to check.

function jc_get_sliders(){
	$sliders = array();
	
	if ( class_exists( 'Soliloquy_Lite' ) ){
		$sliders['soliloquy'] = 'Soliloquy';
	}
	
	if ( function_exists( 'huge_it_slider_activate' ) ){
		$sliders['huge_it_slider'] = 'Huge IT Slider';
	}
	
	if ( function_exists( 'wd_slider' ) ){
		$sliders['wds'] = 'Slider WD';
	}
	
	return $sliders;
}

I know some of you are wondering why I chose to use the class and functions I chose to check for. Those are the classes and functions those respective plugins use when they are activated. If those plugins are not active they will not exist.

Now that we have our options for plugins we can create our theme customizer options.

add_action( 'customize_register', function( $wp_customize ){
	// Set up the section
	$wp_customize->add_section( 'slider-section',
		array(
		'title' => __( 'Select a slider', 'jc-domain' ),
		'priority' => 30,
		) );
	// register the setting
	$wp_customize->add_setting( 'slider-type',
		array(
		'default' => '',
		'sanitize_callback' => 'jc_valid_slider',
		) );
	// register the setting's control but only output if those sliders exist
	$wp_customize->add_control( 'slider-type-input',
		array(
		'label' => __( 'Select the slider to use', 'jc-domain' ),
		'settings' => 'slider-type',
		'section' => 'slider-section',
		'type' => 'select',
		'choices' => jc_get_sliders(),
		'active_callback' => 'jc_sliders_exist'
		) );
	// register the setting
	$wp_customize->add_setting( 'slider-id',
		array(
		'default' => '',
		'sanitize_callback' => 'absint',
		) );
	// register the setting's control but only output if those sliders exist
	$wp_customize->add_control( 'slider-id-input',
		array(
		'label' => __( 'Input the ID of the slider you would like to use', 'jc-domain' ),
		'settings' => 'slider-id',
		'section' => 'slider-section',
		'type' => 'number',
		'active_callback' => 'jc_sliders_exist'
		) );
	
});

Great! Now you can see that I am using an active_callback for the controls. This is so that the section will not show if there are no active plugins to choose from. That means we have to create that callback. Fairly simple:

function jc_sliders_exist(){
	if ( !empty( jc_get_sliders() ) )
		return true;
	return false;
}

As you see we can utilize the first function we created that gets the sliders to our advantage. If the array is not empty we return true, otherwise we return false. Straight-forward. Now, you may notice one function we may need to create and that is jc_valid_slider. This is what will check if the option is a valid option and return it. So, let’s create that shall we:

function jc_valid_slider( $value, $control ){
	return ( array_key_exists( $value, jc_get_sliders() ) ) ? $value : $control->default;
}

Yes, you can see we are still using jc_get_sliders() to get our values. No need to create another wheel when we already have one, right?

The output

I know you are now wondering, “But Jose, how will you display the slider?” Well, let me show you how! We use get_theme_mod() and do_shortcode() with a quick check to output our slider.

add_action( 'jc_slider_area', 'jc_create_slider' );
function jc_create_slider(){
	// get the setting for the type of slider
	$type = get_theme_mod( 'slider-type' );
	// get the setting for the ID of the slider to use
	$id = get_theme_mod( 'slider-id' );
	
	// Check if we have chosen a slider
	if( !$type ){
		return;
	}
	
	echo do_shortcode( "[$type id='$id']" );
}

Great! But I know you are probably wondering why I’m using an action hook rather than creating a function and calling it. What’s super cool about using a hook is that this can be extended or removed with a child theme or functionality plugin. Super great way of making your theme extendable and child theme friendly. So, in the last step all we need to do is create that action hook.

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

By adding that to where you want the slider to show, you can create a great hook for any theme developer to utilize.

Minor note

If you hadn’t noticed, I registered the customizer settings using an anonymous function. This will work on PHP versions 5.3 and higher so please make sure you are aware of what your environment you are developing for. So go, explore and try to break things along the way!

Two or three column section

A while back I wrote a quick and dirty tutorial on how to display more than one page. This can be done in a number of different ways. You can read about them in other tutorials and guides because this time I’ll go over another method using the WP_Query method. The codex page some really great ways and examples of using it to your advantage, I highly recommend you give it a skim and return to this.

So, on to the code!

What I’ll be using is a switch statement, an active callback, and of course the customizer API.

First we will create the settings and controls:

$wp_customize->add_section( 'demo-front-sections',
				 array(
					 'title' => __( 'Front page sections', 'text-domain' ),
					 'description' => __( 'Choose what pages to show on the front page panels', 'text-domain' ),
					 'priority' => 1,
					 'active_callback' => 'is_front_page'
				 ) );
$wp_customize->add_setting( 'col-count',
				 array(
					'default' => 2,
					'sanitize_callback' => 'absint'
				 ) );
$wp_customize->add_control( 'panel-count',
				 array(
					'settings' => 'col-count',
					'label' => __( 'How many panels on this section', 'text-domain' ),
					'type' => 'radio',
					'choices' => array( '2' => 2, '3' => 3 ),
					'section' => 'demo-front-sections',

				 ) );

// Register the page settings to get the IDs
$wp_customize->add_setting( 'page-1',
				 array(
					'default' => 0,
					'sanitize_callback' => 'absint'
				 ) );
$wp_customize->add_setting( 'page-2',
				 array(
					'default' => 0,
					'sanitize_callback' => 'absint'
				 ) );
$wp_customize->add_setting( 'page-3',
				 array(
					'default' => 0,
					'sanitize_callback' => 'absint'
				 ) );

// Set the controls
$wp_customize->add_control( 'panel-1',
				 array(
					 'settings' => 'page-1',
					 'label' => __( 'Pick what page you would like to showcase', 'text-domain' ),
					 'type' => 'dropdown-pages',
					 'section' => 'demo-front-sections'
				 ) );
$wp_customize->add_control( 'panel-2',
				 array(
					 'settings' => 'page-2',
					 'label' => __( 'Pick what page you would like to showcase', 'text-domain' ),
					 'type' => 'dropdown-pages',
					 'section' => 'demo-front-sections'
				 ) );
$wp_customize->add_control( 'panel-3',
				 array(
					 'settings' => 'page-3',
					 'label' => __( 'Pick what page you would like to showcase', 'text-domain' ),
					 'type' => 'dropdown-pages',
					 'section' => 'demo-front-sections',
					 'active_callback' => 'panel_countcheck'
				 ) );

You’ll notice I used a basic active callback for the section so that the section will only show up on the front page. You may also notice that I’ve added a callback to the third control. We haven’t created that callback so let’s do it:

function panel_countcheck( $value ){
	if ( get_theme_mod( 'col-count' ) > 2 ){
		return true;
	}
	return false;
}

Great! Now what does it do? Let’s break it down a little. So, if the first value ( col-count ) is greater than 2, then let’s show this control, otherwise we won’t. Pretty self-explanatory, right?

Great now we just need to display this on a page template, or the front page ( in our case ). We use get_theme_mod to get the values and the code will look a little like:

// get setting for how many
$count = intval( get_theme_mod( 'col-count', 2 ) );
// create an array for the new query
$ids= array();
// get the pages
$ids[] = intval( get_theme_mod( 'page-1', 0 ) );
$ids[] = intval( get_theme_mod( 'page-2', 0 ) );
if ( $count > 2 ){
	$ids[] = intval( get_theme_mod( 'page-3', 0 ) );
}

$query = new WP_Query( array( 'post_type' => 'page', 'post__in' => $ids, 'orderby' => 'post__in' ) );

switch( $count ){
	case 2:
		while( $query->have_posts() ): $query->the_post();
			echo '<div class="col-2">';
				the_title( '<h2>', '</h2>'); the_content();
			echo '</div>';
		endwhile;
	wp_reset_postdata();
	break;
	case 3:
		while( $query->have_posts() ): $query->the_post();
			echo '<div class="col-3">';
				the_title( '<h2>', '</h2>'); the_content();
			echo '</div>';
		endwhile;
	wp_reset_postdata();
	break;
}

Yeah, it is a little messy but we will break it down and explain what does what.

The first setting we get is the column count. You’ll see that I am using intval because we want to make sure that we are setting an integer. The value being passed from the customizer setting is an ID number that corresponds to a page ID, so we make sure that it really is an integer.

$count = intval( get_theme_mod( 'col-count', 2 ) );

Next up, we get our pages and build up the array that we will pass our new WP_Query. As you can see, we first get the first two pages and conditionally add the third if the $count is greater than 2. Remember this is the setting that the user picks.

$ids[] = intval( get_theme_mod( 'page-1', 0 ) );
$ids[] = intval( get_theme_mod( 'page-2', 0 ) );
if ( $count > 2 ){
	$ids[] = intval( get_theme_mod( 'page-3', 0 ) );
}

From there, we build up the new query. Pretty simple. We make sure that the post type is a page, and the order is maintained by what we pass it.

$query = new WP_Query( array( 'post_type' => 'page', 'post__in' => $ids, 'orderby' => 'post__in' ) );

Now we get to the switch statement! This is where the fun sort of begins.

switch( $count ){
	case 2:
		while( $query->have_posts() ): $query->the_post();
			echo '<div class="col-2">';
				the_title( '<h2>', '</h2>'); the_content();
			echo '</div>';
		endwhile;
	wp_reset_postdata();
	break;
	case 3:
		while( $query->have_posts() ): $query->the_post();
			echo '<div class="col-3">';
				the_title( '<h2>', '</h2>'); the_content();
			echo '</div>';
		endwhile;
	wp_reset_postdata();
	break;
}

Okay. Let’s look over the lines a bit. As you can see we pass it the $count variable we first created, which houses the option of whether to show 2 pages or 3. We create a case for each one and as you can see the only real difference here is the class. For showing two pages it is 2-col and for the 3 it is 3-col. You can create a quick wrapper for that if you want so it can be extended by a child theme like:

function jc_classes(){
	$classes = array();
	$classes[] = 'span';
	$cols = get_theme_mod( 'col-count', 2 );
	switch( $cols ){
		case 2:
		$classes[] = 'col-2';
		break;
		case 3:
		$classes[] = 'col-2';
		break;
	}
	
	return 'class="' . esc_attr( implode( ' ', apply_filters( 'jc_custom_classes', $classes ) ) ) . '"';
}

From there we can lose the switch statement and use:

$query = new WP_Query( array( 'post_type' => 'page', 'post__in' => $ids, 'orderby' => 'post__in' ) );
while( $query->have_posts() ): $query->the_post();
	echo '<div ' . jc_classes() .'>';
		the_title( '<h2>', '</h2>'); the_content();
	echo '</div>';
endwhile;
wp_reset_postdata();

What’s really nice is you can use basic CSS to style it. A quick snippet:

.col-2 {
	float: left;
	width: 50%;
}

.col-3 {
	float: left;
	width: 33%;
}

So, go on, experiment, and fiddle around with the code a bit. Do remember I used basic things, so be sure to add the proper settings, text, and values for your needs.

Customizer: dropdown category selection

This is just a quick code snippet that may help at least one person. I know it will. Earlier today I was looking over a theme and it was driving me crazy to see them re-inventing the wheel. A simple dropdown that core uses in order to display the categories. The way core uses choices is an associative array. The array key is the $value and the array value is used for the label. What does this mean?

It means that often times you have to flip things around because core can get certain values in a different manner. A great example is the get_page_templates function. The following is one way of creating this array.

// we get all the available templates
$templates = array_flip( get_page_templates() );

// new array is
$templates = 
	array (
	'templates/home.php' => 'home',
	'templates/featured.php' => 'featured posts',
	'templates/widgetized.php' => 'Widgetized Page'
	)

Do keep in mind that is just for that particular function. There are several other functions that return either arrays or objects, so it is in your best interest to learn how and what each function returns data. I say this because the above code uses a basic PHP function in order to re-create the array. The function itself returns things the other way around. The codex page does a good job of explaining it.

In this post we will go over the get_categories function. It returns an array but not the way we want in order to use in the customizer. In order to do so we have to get a little creative in building the array.

// create an empty array
$cats = array();

// we loop over the categories and set the names and
// labels we need
foreach ( get_categories() as $categories => $category ){
	$cats[$category->term_id] = $category->name;
}

// we register our new setting
$wp_customize->add_setting( 'cats_elect', array(
	'default' => 1,
	'sanitize_callback' => 'absint'
) );

// we create our control for the setting
$wp_customize->add_control( 'cat_contlr', array(
	'settings' => 'cats_elect',
	'type' => 'select',
	'choices' => $cats,
	'section' => 'my_section',  // depending on where you want it to be
) );

This will return an integer for the category. Hence the absint sanitation callback. From there all we would have to do to get our setting is use:

$cat_id = intval( get_theme_mod( 'cats_elect', 1 ) );

You’ll notice I’ve used intval around the get_theme_mod function, that is so we make sure that we are getting an integer from our saved setting just in case. You can never be too careful, right?

So, there you have it! Just a few lines of code and we have a dropdown of our categories.