I recently built an Event Manager theme for promoting an event, and on our Event Theme Settings page we had fields for event date and location, so these could be used throughout the site and pulled from a single source.

This code is pretty technical, but it is 100x easier than making admin pages without Genesis. See this 10 page tutorial by Chip Bennett for instructions on making them without Genesis’ help.

You should only use this method if you’re building a Genesis theme or a Genesis-specific plugin. If you build a plugin for public distribution, make sure you put some checks in place to ensure the user is running Genesis (take a look at the AgentPress plugin code as an example).

Here’s the steps:

1. Specify the page information. This includes the page’s name and default values for your fields.
2. Create the sanitization filters. These keep the page secure by ensuring the right type of data are entered.
3. Set up the help tab, a very useful feature that was improved in WordPress 3.3.
4. Add your metaboxes to the page.
5. Build your metaboxes.
6. Finally, add the new admin page to the backend.

For a complete example, see the child-theme-settings.php file in my base child theme.

Specify the page information

First, it’s best to keep all this code in its own file so your theme is easy to browse. I like to create a “lib” folder in my child theme where I store everything. In my example, I created /lib/admin/child-theme-settings.php, then added this to my functions.php to include it:

<?php

// Setup Theme Settings
include_once( CHILD_DIR . '/lib/admin/child-theme-settings.php');

Now inside your child-theme-settings.php file, place the following:

<?php
/**
 * Child Theme Settings
 * Requires Genesis 1.8 or later
 *
 * This file registers all of this child theme's specific Theme Settings, accessible from
 * Genesis > Child Theme Settings.
 *
 * @package     BE Genesis Child
 * @author      Bill Erickson <bill@billerickson.net>
 * @copyright   Copyright (c) 2011, Bill Erickson
 * @license     http://www.opensource.org/licenses/gpl-license.php GPL v2.0 (or later)
 * @link        https://github.com/billerickson/BE-Genesis-Child
 */ 
 
/**
 * Registers a new admin page, providing content and corresponding menu item
 * for the Child Theme Settings page.
 *
 * @package BE Genesis Child
 * @subpackage Admin
 *
 * @since 1.0.0
 */
class Child_Theme_Settings extends Genesis_Admin_Boxes {

	/**
	 * Create an admin menu item and settings page.
	 * 
	 * @since 1.0.0
	 */
	function __construct() {

		// Specify a unique page ID. 
		$page_id = 'child';

		// Set it as a child to genesis, and define the menu and page titles
		$menu_ops = array(
			'submenu' => array(
				'parent_slug' => 'genesis',
				'page_title'  => 'Genesis - Child Theme Settings',
				'menu_title'  => 'Child Theme Settings',
			)
		);

		// Set up page options. These are optional, so only uncomment if you want to change the defaults
		$page_ops = array(
		//	'screen_icon'       => 'options-general',
		//	'save_button_text'  => 'Save Settings',
		//	'reset_button_text' => 'Reset Settings',
		//	'save_notice_text'  => 'Settings saved.',
		//	'reset_notice_text' => 'Settings reset.',
		);		

		// Give it a unique settings field. 
		// You'll access them from genesis_get_option( 'option_name', 'child-settings' );
		$settings_field = 'child-settings';

		// Set the default values
		$default_settings = array(
			'phone'   => '',
			'address' => '',
		);

		// Create the Admin Page
		$this->create( $page_id, $menu_ops, $page_ops, $settings_field, $default_settings );

		// Initialize the Sanitization Filter
		add_action( 'genesis_settings_sanitizer_init', array( $this, 'sanitization_filters' ) );

	}

	function sanitization_filters() {

	}

}

This is a lot of code, so I’ll walk through it:

• I start out with some page-specific documentation that describes what this page is (always a good practice).
• Then there’s the documentation for our new class, Child_Theme_Settings
• We create our new class by extending the existing Genesis_Admin_Boxes class
• First thing in our new class is the __construct() method (functions inside of classes are called methods). This is what sets everything up.
• We create an unique page ID for this page. I’m calling mine ‘child’, but you could call yours whatever you’d like. I recommend naming it the same as your child theme since it will contain your child-theme-specific settings.
• Next we specify some information about the menu item. It’s a child of the ‘genesis’ page, we give it a page title and a menu title.
• Then we create the $page_ops variable which lets you customize some page settings. I’ve left the defaults in there and commented them out so you can see. Uncomment a line and then modify it to change the default.
• Then we define the settings field. All the settings on this page will be grouped together. If you create a field called address you can get to it like this: $address = genesis_get_option( 'option_name', 'child-settings' );
• Finally, we create the admin page by adding all the variables together in the create() method.
• I’ve also added the sanitation action (in __construct() method) and sanitization_filters() method to create the sanitization filters, which we’ll do in the next step.

Before we move on, a few quick notes about classes. Everything inside the class should use the __construct() method for hooking to appropriate actions/filters. Classes are their own namespace, so you can name the methods whatever you’d like. Unlike standard functions where you always need to prefix, you don’t have to worry about any other function having the same name. And finally, when hooking methods to actions make sure you use array( $this, 'method_name' ) instead of just 'method_name'.

Create the sanitization filters

Sanitization is about ensuring the data collected is the type of data you expect. By limiting a checkbox to a 0 or 1, a title to no html… you’re able to prevent code you didn’t expect (whether malicious or not) from altering the way your theme/plugin works.

See my previous post on Genesis options for more details on sanitization filters.

I’m planning to have two fields on this page – phone and address – so I’ll register those as no_html. Update your sanitization_filters() method like this:

<?php


/** 
 * Set up Sanitization Filters
 *
 * See /lib/classes/sanitization.php for all available filters.
 *
 * @since 1.0.0
 */	
function sanitization_filters() {

	genesis_add_option_filter( 'no_html', $this->settings_field,
		array(
			'phone',
			'address',
		) );
}

Help Tab

While not required, it’s a good idea to put instructions and other useful information in the help tab. If you’d like to have a help tab, simply create a help() method in your class.

Here’s a screenshot of the help tab in my Event Theme. I don’t usually provide this much information, but the client plans to sell the theme so we wanted to provide as much information as possible.

To create a help tab, add this method inside your Child_Theme_Settings class ( so before the last } ).

<?php

/**
 * Set up Help Tab
 * Genesis automatically looks for a help() function, and if provided uses it for the help tabs
 * @link http://wpdevel.wordpress.com/2011/12/06/help-and-screen-api-changes-in-3-3/
 *
 * @since 1.0.0
 */
 function help() {
 	$screen = get_current_screen();

	$screen->add_help_tab( array(
		'id'      => 'sample-help', 
		'title'   => 'Sample Help',
		'content' => '<p>Help content goes here.</p>',
	) );
 }

Provide an unique ID for the tab, then give it a title (shown on the left) and HTML content (shown on the right). For multiple tabs, simply repeat the $screen->add_help_tab() method inside your help() method.

Add your metaboxes

We’ll now create a method inside our class called metaboxes(). For each metabox we’d like to add to our page, we’ll write a simple one line of code to add_meta_box().

<?php

/**
 * Register metaboxes on Child Theme Settings page
 *
 * @since 1.0.0
 *
 * @see Child_Theme_Settings::contact_information() Callback for contact information
 */
function metaboxes() {

	add_meta_box('contact-information', 'Contact Information', array( $this, 'contact_information' ), $this->pagehook, 'main', 'high');

}

I’ve added a single metabox with an ID of ‘contact-information’, a title of ‘Contact Information’, a callback function (where the actual metabox code is) of contact_information(), I’m putting it on the current page, it goes in the main column (not that there’s any other columns for it) and I want it positioned at the top. For more information on this function, see add_meta_box() in the Codex.

Build your metaboxes

In the previous method we referenced a callback function called contact_information(). Now it’s time to build this.

My metabox, Contact Information, will contain two fields. Phone will be a text field, and Address is a textarea. For examples of more fields, look at the actual Genesis admin pages (/lib/admin/…). And I’ve heard there might be a tool similar to our Custom Metabox Library for making Genesis admin fields (talk with NickTheGeek).

This method also goes inside your Child_Theme_Settings class.

<?php

/**
 * Callback for Contact Information metabox
 *
 * @since 1.0.0
 *
 * @see Child_Theme_Settings::metaboxes()
 */
function contact_information() {

	echo '<p>Phone:<br />';
	echo '<input type="text" name="' . $this->get_field_name( 'phone' ) . '" id="' . $this->get_field_id( 'phone' ) . '" value="' . esc_attr( $this->get_field_value( 'phone' ) ) . '" size="50" />';
	echo '</p>';

	echo '<p>Address</p>';
	echo '<p><textarea name="' . $this->get_field_name( 'address' ) . '" cols="78" rows="8">' . esc_textarea( $this->get_field_value( 'address' ) ) . '</textarea></p>';		
}

The important thing to note here is the handy methods that are built into the class (examples below are for the field ‘phone’ ).

• $this->get_field_name( 'phone' );
• $this->get_field_id( 'phone' );
• $this->get_field_value( 'phone' );

That’s It!

That’s all it takes to build custom admin pages in Genesis. The code definitely looks complicated, but once you get started it’s pretty easy to modify it to your needs. StudioPress has done all the hard (and repetitive) work for you, so you just have to specify the things that are unique to the page.

Here’s the completed code:

<?php
/**
 * Child Theme Settings
 * Requires Genesis 1.8 or later
 *
 * This file registers all of this child theme's specific Theme Settings, accessible from
 * Genesis > Child Theme Settings.
 *
 * @package     BE Genesis Child
 * @author      Bill Erickson <bill@billerickson.net>
 * @copyright   Copyright (c) 2011, Bill Erickson
 * @license     http://www.opensource.org/licenses/gpl-license.php GPL v2.0 (or later)
 * @link        https://github.com/billerickson/BE-Genesis-Child
 */ 
 
/**
 * Registers a new admin page, providing content and corresponding menu item
 * for the Child Theme Settings page.
 *
 * @package BE Genesis Child
 * @subpackage Admin
 *
 * @since 1.0.0
 */
class Child_Theme_Settings extends Genesis_Admin_Boxes {

	/**
	 * Create an admin menu item and settings page.
	 * 
	 * @since 1.0.0
	 */
	function __construct() {

		// Specify a unique page ID. 
		$page_id = 'child';

		// Set it as a child to genesis, and define the menu and page titles
		$menu_ops = array(
			'submenu' => array(
				'parent_slug' => 'genesis',
				'page_title'  => 'Genesis - Child Theme Settings',
				'menu_title'  => 'Child Theme Settings',
			)
		);

		// Set up page options. These are optional, so only uncomment if you want to change the defaults
		$page_ops = array(
		//	'screen_icon'       => 'options-general',
		//	'save_button_text'  => 'Save Settings',
		//	'reset_button_text' => 'Reset Settings',
		//	'save_notice_text'  => 'Settings saved.',
		//	'reset_notice_text' => 'Settings reset.',
		);		

		// Give it a unique settings field. 
		// You'll access them from genesis_get_option( 'option_name', 'child-settings' );
		$settings_field = 'child-settings';

		// Set the default values
		$default_settings = array(
			'phone'   => '',
			'address' => '',
		);

		// Create the Admin Page
		$this->create( $page_id, $menu_ops, $page_ops, $settings_field, $default_settings );

		// Initialize the Sanitization Filter
		add_action( 'genesis_settings_sanitizer_init', array( $this, 'sanitization_filters' ) );

	}

	/** 
	 * Set up Sanitization Filters
	 *
	 * See /lib/classes/sanitization.php for all available filters.
	 *
	 * @since 1.0.0
	 */	
	function sanitization_filters() {

		genesis_add_option_filter( 'no_html', $this->settings_field,
			array(
				'phone',
				'address',
			) );
	}

	/**
	 * Set up Help Tab
	 * Genesis automatically looks for a help() function, and if provided uses it for the help tabs
	 * @link http://wpdevel.wordpress.com/2011/12/06/help-and-screen-api-changes-in-3-3/
	 *
	 * @since 1.0.0
	 */
	 function help() {
	 	$screen = get_current_screen();

		$screen->add_help_tab( array(
			'id'      => 'sample-help', 
			'title'   => 'Sample Help',
			'content' => '<p>Help content goes here.</p>',
		) );
	 }

	/**
	 * Register metaboxes on Child Theme Settings page
	 *
	 * @since 1.0.0
	 *
	 * @see Child_Theme_Settings::contact_information() Callback for contact information
	 */
	function metaboxes() {

		add_meta_box('contact-information', 'Contact Information', array( $this, 'contact_information' ), $this->pagehook, 'main', 'high');

	}

	/**
	 * Callback for Contact Information metabox
	 *
	 * @since 1.0.0
	 *
	 * @see Child_Theme_Settings::metaboxes()
	 */
	function contact_information() {

		echo '<p>Phone:<br />';
		echo '<input type="text" name="' . $this->get_field_name( 'phone' ) . '" id="' . $this->get_field_id( 'phone' ) . '" value="' . esc_attr( $this->get_field_value( 'phone' ) ) . '" size="50" />';
		echo '</p>';

		echo '<p>Address</p>';
		echo '<p><textarea name="' . $this->get_field_name( 'address' ) . '" cols="78" rows="8">' . esc_textarea( $this->get_field_value( 'address' ) ) . '</textarea></p>';		
	}


}


add_action( 'genesis_admin_menu', 'be_add_child_theme_settings' );
/**
 * Add the Theme Settings Page
 *
 * @since 1.0.0
 */
function be_add_child_theme_settings() {
	global $_child_theme_settings;
	$_child_theme_settings = new Child_Theme_Settings;	 	
}

And once you do have your custom admin page up-and-running, you’ll need to access that information. Just use genesis_get_option( [field-name], [settings-field] );.

So in the above example, to access the phone number use: $phone = genesis_get_option( 'phone', 'child-settings' );.

There’s three pieces of code we’ll add to our core functionality plugin ¹:

1. Register the connection. This adds the metaboxes for linking posts.
2. Pre-Loop code. This adds the related posts information to the $wp_query (better performance)
3. Display Related Posts.

Register the Connection

<?php

add_action( 'init', 'be_post_type_connections' );
/**
 * Related Post Connection
 * @author Bill Erickson
 * @link http://www.billerickson.net/manually-curated-related-posts/
 *
 * @uses Posts2Posts
 * @link https://github.com/scribu/wp-posts-to-posts/wiki
 */
function be_post_type_connections() {

	// Make Sure plugin is active
	if ( !function_exists( 'p2p_register_connection_type' ) )
		return;

	p2p_register_connection_type( array(
		'name' => 'related-articles', // unique name
		'from' => 'post',
		'to' => 'post',
		'title' => array( 'to' => 'All Connections', 'from' => 'Related Articles' )
	) );
}

I’m creating this connection from the post post type, to the post post type. So when you’re editing a post, you can select other posts to connect it to. This actually creates two metaboxes: a from metabox that you use to connect the current post to others, and a to metabox that shows what posts have already been connected to this one. I’ve labeled the from metabox “Related Articles” since this is what is displayed as related to the current post, and I labeled to “All Connections”.

Once you add this code to your site, you should see metaboxes like this when editing a post:

Pre-Loop Code

<?php

/**
 * Related Posts Before Loop
 * Adds connection data to $wp_query. Run before the loop.
 *
 * @author Bill Erickson
 * @link http://www.billerickson.net/manually-curated-related-posts/
 */
function be_related_posts_pre_loop() {
 	// Make Sure plugin is active
 	if ( !function_exists( 'p2p_register_connection_type' ) )
		return;

	global $wp_query;
	p2p_type( 'related-articles' )->each_connected( $wp_query );	
}

As described in the Posts 2 Posts wiki, when dealing with archive pages its much better to add the connected posts to the $wp_query before you run the loop.

Display Related Posts

<?php

/**
 * Display Related Posts
 * @author Bill Erickson
 * @link http://www.billerickson.net/manually-curated-related-posts/
 */
function be_related_posts() {
 	// Make Sure plugin is active
 	if ( !function_exists( 'p2p_register_connection_type' ) )
		return;

	global $post;
	if( isset( $post->connected ) && !empty( $post->connected ) ):
		echo '<div class="related-posts">';
		$count = 1;
		foreach( $post->connected as $related ):
			if( $count < 6 ) {	
				echo '<div class="related-post">';
				echo '<a class="image" href="' . get_permalink( $related->ID ) . '">';
				$cat = wp_get_object_terms( $related->ID, 'category', array( 'count' => 1 ) );
				echo '<span class="category">' . $cat[0]->name . '</span>';
				echo get_the_post_thumbnail( $related->ID, 'be_home_small' );
				echo '</a>';
				echo '<a class="title" href="' . get_permalink( $related->ID ) . '">' . $related->post_title . '</a>';
				echo '</div>';
				$count++;
			}
		endforeach;
		echo '</div>';
	endif;
}

You can of course display the related posts however you’d like. For my specific implementation, I wanted to limit it to 5, display the post image at a specific size, float the category name on top of the post image, and then display the title below the image.

The important thing to note is that $post->connected is an array of post objects, so use the foreach() to loop through them and then display the post data however you’d like.

Integrating it with your theme

Once you’ve added this code to your core functionality plugin, you have to actually call it in your theme. Just place be_related_posts_pre_loop() before you call the loop, and be_related_posts() somewhere inside the loop. If you’re using Genesis, it has hooks throughout the theme, so you just need to add the following two lines to your theme’s functions.php file (alter the second line to change the positioning of the related posts):

<?php

// Related Posts (see mu-plugins/lib/functions/related-posts.php
add_action( 'genesis_before_loop', 'be_related_posts_pre_loop' );
add_action( 'genesis_after_post_content', 'be_related_posts', 15 );

I’d love to hear any thoughts you have about this, especially if you have experience with Posts 2 Posts.

1. Core Functionality Plugin
   While you could put all this code in your theme’s functions.php file, a core functionality plugin is better for things like this because if you change your theme in the future, you’ll want to easily move this functionality to your new theme. If it’s in a plugin, all you have to do is add two lines to your theme (call the pre-loop code and then the display code). If all the code is in your old theme, you have to dig through all your files, figuring out how you built your related posts section so you can duplicate it in your new theme. In my core functionality plugin, I created /lib/functions/related-posts.php so that all the code was on one location.

There’s two different ways I set up client sites to use this:

• Adding Editor Styles
• Div Shortcode Plugin

Adding Editor Styles

If the client is somewhat comfortable with HTML – she’s not afraid to click the “HTML” tab in the editor – then I’ll add the column classes to the editor’s stylesheet. This will make it so the columns are visible in the editor and the client can easily see where the content she’s writing will show up. I also recommend using the fullscreen editor when using this because the inline one is a bit too small.

In your theme, create a file called editor-style.css and add the column class CSS styles to it. You can also add any other styles you’d like reflected in the editor (I often add the headlines styles so the client can visually see how her h2′s and h3′s will look from the editor).

Then, add this to your functions.php file: add_editor_style( 'editor-style.css' );.

That’s it! Now when editing a post, switch to HTML view and add this:

<div class="one-half first">

Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet.

</div>

<div class="one-half">

Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet.

</div>

When you switch back to Visual view, your editor should look like this:

Div Shortcode Plugin

For those who get completely lost in the HTML tab, I have a plugin that let’s them use [div] shortcodes. Once Div Shortcode Plugin is activated, they just have to write something like this in the Visual Editor:

[div class="one-half first"]

This is the left column

[end-div]

[div class="one-half"]

This is the right column

[end-div]

The benefit here is that they can see exactly where in the Visual editor one column is ending and another is beginning. They’re able to control div’s without ever switching to the HTML view (where they might get lost).

Other Notes

When building out a site, I’ll often create two sample pages using each technique so the client can choose which is best for her.

If every page will have the same number of columns, you might consider pre-populating the content area with default text. This way they never have to switch to HTML mode to create the columns – they are there already.

It looks like a future version of Genesis might include icons in the TinyMCE Editor for creating the columns, which will give you one more way for doing this.

But when you’re building websites with complex content structures, you’ll often need to build a very specific template hierarchy of your own, or else duplicate a lot of code.

I’m building a site right now with four custom post types, and each post type has 2-4 taxonomies. Take a look at the screenshot above. The ‘recipe’ post type has two taxonomies: ‘name-range’ which allows the client to break down the list of recipes by name (ex: A-D, E-G…), and ‘base’ (dropdown says category), which is a shared taxonomy with another post type that specifies the alcoholic base of the cocktail.

I want a single template file that is used in all of these situations:

• Recipe post type archive
• Name Range taxonomy archive
• Base taxonomy archive (if post type is also ‘recipe’)

For this, I’ll use the template_include filter. This filter runs right after WordPress determines what template it thinks it should use, but before that template is actually loaded. This is where you can hop in and specify your own template hierarchy.

Without this technique, I’d need to put the same code in archive-recipe.php, taxononomy-name-range.php, and taxonomy-base.php (with some extra code in here to check for the current post type).

<?php

/**
 * Template Chooser
 * Use CPT archive templates for taxonomies
 * @author Bill Erickson
 * @link http://www.billerickson.net/code/use-same-template-for-taxonomy-and-cpt-archive/
 *
 * @param string, default template path
 * @return string, modified template path
 *
 */
function be_template_chooser( $template ) {

	if( is_post_type_archive( 'recipe' ) || is_tax( 'name-range' ) || ( is_tax( 'base' ) && 'recipe' == get_post_type() ) )
		$template = get_query_template( 'archive-recipe' );
	return $template;
}
add_filter( 'template_include', 'be_template_chooser' );

The code above says “if this is the post type archive for ‘recipe’, the taxonomy archive ‘name-range’, or the taxonomy archive ‘base’ AND post type ‘recipe’, then use the template file archive-recipe.php.”

I also like to generalize this section checker into its own function so I can use it elsewhere. You might want to add a body class called ‘section-recipe’ if any of these templates are in use. Here’s how:

<?php

/**
 * Return Archive Section
 * @author Bill Erickson
 * @link http://www.billerickson.net/code/helper-function-for-template-include-and-body-class/
 * 
 * @param null
 * @return string
 */
function be_return_archive_section() {
	if( is_post_type_archive( 'lifestyle' ) || is_tax( 'lifestyle-section' ) || is_tax( 'lifestyle-type' ) || is_tax( 'lifestyle-series' ) )
		return 'lifestyle';

	if( is_post_type_archive( 'recipe' ) || is_tax( 'name-range' ) || ( is_tax( 'base' ) && 'recipe' == get_post_type() ) )
		return 'recipe';		

	if( is_post_type_archive( 'brand' ) || ( is_tax( 'base' ) && 'brand' == get_post_type() ) )
		return 'brand';

	if( is_post_type_archive( 'experience' ) )
		return 'experience';

	return false;
}

add_filter( 'template_include', 'be_template_chooser' );
/**
 * Template Chooser
 * Use CPT archive templates for taxonomies
 * @author Bill Erickson
 * @link http://www.billerickson.net/code/use-same-template-for-taxonomy-and-cpt-archive/
 *
 * @param string, default template path
 * @return string, modified template path
 *
 */
function be_template_chooser( $template ) {
	if ( be_return_archive_section() ) 
		$template = get_query_template( 'archive-' . be_return_archive_section() );	

	return $template;
}

add_filter( 'body_class', 'be_section_body_classes' );
/**
 * Section Body Classes
 * @author Bill Erickson
 * 
 * @param array $classes
 * @return array
 */
function be_section_body_classes( $classes ) {
	if( be_return_archive_section() )
		$classes[] = 'section-' . be_return_archive_section();

	return $classes;
}

First I’m creating a function that returns the current section if there’s a match, and ‘false’ if there isn’t.

Then I have my template redirect function. If the current page is in a section, it loads the template ‘archive-$section’ (ex: archive-recipe.php).

Then I have my body class filter. If the current page is in a section, it adds the body class ‘section-$section’ (ex: ‘section-recipe’ ).

If you add a new taxonomy, just edit the be_return_archive_section() function to specify the section it belongs in, and it will automatically use the correct template file and have the body class.

It’s been about six months since my original Custom Metaboxes post announcing the release of this code library for easily creating metaboxes. If you haven’t had a look at it since then, I highly recommend you hop on Github and look at the latest version and the wiki.

Some of the features:

• The ability to create metaboxes with a simple array rather than a ton of code. Compare this tutorial (without our library) to these examples (with our library).
• Choose from 20 included field types, or add your own field types
• You can limit the metabox to specific post types, page template, page IDs, or create your own filter for where it should show up
• This can be used by both themes and plugins. And as long as you initialize it correctly (see bottom of example-functions.php), it can be used by a theme and as many plugins as you like at the same time.

My favorite field types:

• WYSIWYG. If you’re using WordPress 3.3, this will automatically use the new wp_editor which gives you a ton of flexibility.
• Taxonomy field types (select, radio, multicheck). If you’re dealing with a lot of taxonomies, the default metabox provided by WordPress takes up a lot of screen real estate. Include taxonomies in your custom metabox instead. Using select or radio is also a great way to force users to only select one taxonomy term.
• File upload. Use the built-in media uploader to allow the user to upload any file they want. You can also store the attachment ID in case you want to retrieve other image sizes.
• Title. If your metabox has a lot of fields in it, use the title field type to create subheadings and instructions.
• Text (standard, medium, and small). This is as simple as it comes, but also the one you’ll use most often.
• text_date_timestamp. This one uses a date picker to let the user select a date, and then saves it as a UNIX timestamp. This is great for event metaboxes because you can then query based on the date.

The contributors of this code library, in no particular order, include: Andrew Norcross, Jared Atchison, Travis Smith, Randy Hoyt, Jeremy Pry, Andrew Ryno, Patrick Forringer, Chris Olbekson, Stefan Crain  …and me.

Please use this code, and consider contributing any improvements you make. If you create any field types or show_on filters, post them on the wiki. If you find any bugs, post them in issues (and even better, post the fix!).

To make it easier for my clients, I’ve written a simple plugin called Gallery Metabox. This adds a metabox below the post editor that displays all the attached images. It also has a lot of filters in place for a developer to customize it specifically to the project (see the plugin page for more information).

For instance, if you’re adding a custom field to the uploader to specify which images are in a rotator, you can make the metabox only show these images.

I just built a site for a client that has a photo gallery.

I created a page template called “Photos” which replaces the content area with a photo rotator. But if you edit the page, the edit screen was pretty useless. There’s a big empty wysiwyg, and to get to the actual images in the gallery you have to click a small icon, then go to the Gallery tab.

I’ve added the plugin, along with some code that limits the metabox to this page template. I’ve also added the following code to the theme’s functions.php file to remove the post editor on this page template:

<?php

/**
 * Hide Editor on Specific Template Page
 *
 */
function be_hide_editor() {
	// Get the Post ID
	if( isset( $_GET['post'] ) ) $post_id = $_GET['post'];
	elseif( isset( $_POST['post_ID'] ) ) $post_id = $_POST['post_ID'];
	if( !isset( $post_id ) ) return;

	// Get the Page Template
	$template_file = get_post_meta($post_id, '_wp_page_template', TRUE);
    
    if( 'template-photos.php' == $template_file )
    	echo '<style>#postdivrich{display: none;}</style>';
}

add_action( 'admin_init', 'be_hide_editor' );

So now this is what they see when editing that page:

This is by far a much easier user interface for this specific page template. And even if your page isn’t solely a gallery, I think this is a useful plugin for quickly seeing which images you have attached to the page or displaying in a gallery/rotator.

A good rule-of-thumb is that anything a user would expect to keep after changing themes belongs in a plugin. This includes custom post types, taxonomies, metaboxes, and shortcodes.

For specific functionality that’s reusable and/or the client might want to selectively disable, it’s best to build as its own plugin. Many times I’ll turn these into public plugins.

For everything else that’s project-specific but should be theme-independent, I put in a plugin called Core Functionality. That’s the base plugin I now use. Of course you’ll want to delete everything that’s not relevant – I have the code for post types, taxonomies, and metaboxes in there because they are used most often.

My base child theme used to have all these in the theme. Over the past few months I’ve been moving them to a core functionality plugin on each project, but it’s about time I finally update the base child theme and pull the functionality out into its own plugin.

If you want to collect additional information on a post you typically use a metabox. For images, you can add your custom fields directly to the media uploader.

There’s two filters we’ll use: attachment_fields_to_edit and attachment_fields_to_save.

I’m going to provide two examples that I use often: adding a “Photo credit” section, and adding an “Include in Rotator” selection.

Adding Photo Credit

You’ll often need to provide attribution to the source of images you use on your website. Rather than sticking it at the top or bottom of the post, we can add that information as photo metadata and then include it in the theme.

I’m going to add two text fields, Photographer Name and Photographer URL.

<?php

/**
 * Add Photographer Name and URL fields to media uploader
 *
 * @param $form_fields array, fields to include in attachment form
 * @param $post object, attachment record in database
 * @return $form_fields, modified form fields
 */
 
function be_attachment_field_credit( $form_fields, $post ) {
	$form_fields['be-photographer-name'] = array(
		'label' => 'Photographer Name',
		'input' => 'text',
		'value' => get_post_meta( $post->ID, 'be_photographer_name', true ),
		'helps' => 'If provided, photo credit will be displayed',
	);

	$form_fields['be-photographer-url'] = array(
		'label' => 'Photographer URL',
		'input' => 'text',
		'value' => get_post_meta( $post->ID, 'be_photographer_url', true ),
		'helps' => 'If provided, photographer name will link here',
	);

	return $form_fields;
}

add_filter( 'attachment_fields_to_edit', 'be_attachment_field_credit', 10, 2 );

/**
 * Save values of Photographer Name and URL in media uploader
 *
 * @param $post array, the post data for database
 * @param $attachment array, attachment fields from $_POST form
 * @return $post array, modified post data
 */

function be_attachment_field_credit_save( $post, $attachment ) {
	if( isset( $attachment['be-photographer-name'] ) )
		update_post_meta( $post['ID'], 'be_photographer_name', $attachment['be-photographer-name'] );

	if( isset( $attachment['be-photographer-url'] ) )
		update_post_meta( $post['ID'], 'be_photographer_url', $attachment['be-photographer-url'] );

	return $post;
}

add_filter( 'attachment_fields_to_save', 'be_attachment_field_credit_save', 10, 2 );

In the first function we used a simple array to specify the field’s Label, input type, value, and help text. In the second function, we check to see if a value has been set for those fields, and if so we update the post metadata.

To access this information in our theme, we simply have to get the post meta for the thumbnail. Assuming we want it for the featured image, we’d do something like this: get_post_meta( get_post_thumbnail_id(), 'be_photographer_name', true );

Include in Rotator

Adding text fields is rather easy. What if you want something more custom? If you use the ‘html’ input type, you can output whatever HTML you’d like.

I love using the built-in Gallery feature in WordPress for managing image rotators on specific posts or pages. The problem is that all images are included in the gallery. So I add an “Include in Rotator” option when editing the image, and then I can query for all attached images that were marked “Yes”.

For more examples of creating html inputs for the media gallery, look in /wp-admin/includes/media.php.

<?php


/**
 * Add "Include in Rotator" option to media uploader
 * Limited to Home page
 *
 * @param $form_fields array, fields to include in attachment form
 * @param $post object, attachment record in database
 * @return $form_fields, modified form fields
 */
 
function be_attachment_field_rotator( $form_fields, $post ) {

	// Only show on the in-page media uploader
	$screen = get_current_screen();
	if( 'media-upload' !== $screen->base )
		return $form_fields;

	// Only show on front page
	if( get_option( 'page_on_front' ) !== $post->post_parent )
		return $form_fields;

	// Set up options
	$options = array( '1' => 'Yes', '0' => 'No' );

	// Get currently selected value
	$selected = get_post_meta( $post->ID, 'be_rotator_include', true );

	// If no selected value, default to 'No'
	if( !isset( $selected ) ) 
		$selected = '0';

	// Display each option	
	foreach ( $options as $value => $label ) {
		$checked = '';
		$css_id = 'rotator-include-option-' . $value;

		if ( $selected == $value ) {
			$checked = " checked='checked'";
		}

		$html = "<div class='rotator-include-option'><input type='radio' name='attachments[$post->ID][be-rotator-include]' id='{$css_id}' value='{$value}'$checked />";

		$html .= "<label for='{$css_id}'>$label</label>";

		$html .= '</div>';

		$out[] = $html;
	}

	// Construct the form field
	$form_fields['be-include-rotator'] = array(
		'label' => 'Include in Rotator',
		'input' => 'html',
		'html'  => join("\n", $out),
	);

	// Return all form fields
	return $form_fields;
}

add_filter( 'attachment_fields_to_edit', 'be_attachment_field_rotator', 10, 2 );


/**
 * Save value of "Include in Rotator" selection in media uploader
 *
 * @param $post array, the post data for database
 * @param $attachment array, attachment fields from $_POST form
 * @return $post array, modified post data
 */
 
function be_attachment_field_rotator_save( $post, $attachment ) {
	if( isset( $attachment['be-rotator-include'] ) ) 
		update_post_meta( $post['ID'], 'be_rotator_include', $attachment['be-rotator-include'] );

	return $post;
}

add_filter( 'attachment_fields_to_save', 'be_attachment_field_rotator_save', 10, 2 );

Then when I want to get all the attached images that are going in the rotator, I run something like this:

<?php

// Get all images attached to post that have "Include in Rotator" marked as "Yes"
global $post;
$args = array( 
	'post_parent' => $post->ID,
	'post_type' => 'attachment',
	'post_mime_type' => 'image',
	'post_status' => 'inherit',
	'posts_per_page' => '-1',
	'order' => 'ASC',
	'orderby' => 'menu_order',
	'meta_query' => array(
		array(
			'key' => 'be_rotator_include',
			'value' => '1'
		)
	)
);

$images = new WP_Query( $args );
if( !$images->have_posts() )
	return;
while( $images->have_posts() ): $images->the_post(); global $post;

	// Echo image url
	$image = wp_get_attachment_image_src( $post->ID, 'be_featured' );
	echo $image[0] . '<br />';

endwhile; wp_reset_query();

• Don’t display posts from Category X on the homepage
• Increase or decrease the number of posts displayed per page for a specific post type
• Determine which posts are shown and their order based on postmeta
• Inside your page, do a separate query for different content

Andrew Nacin recently gave a great talk on using the query, which you can look at for some more technical information on what’s happening behind the scenes. I’m going to focus this tutorial on common uses.

First, what not to do. Don’t use query_posts(). As you can see from the Codex page, there’s a lot of caveats to it. I really can’t think of an instance where this function is advisable.

There’s two approaches you should take depending on your needs.

Create a new query to run inside your page or template.

This is best when the content you’re displaying is being loaded in addition to your current page’s content. For instance, if you had a page about Spain and wanted to show your 5 most recent blog posts about Spain at the bottom.

For this you’ll use the WP_Query class. For more information, see my post on Custom WordPress Queries. Also take a look at my Display Posts Shortcode plugin, which might save you from having to write any code.

Customize the Main Query

If you want to alter which content is returned on a page, you most likely will be modifying the main query. The first three examples above all require altering the main query.

WordPress has a very handy hook called pre_get_posts. It fires once all the query settings are ready but right before the actual query takes place. This is where we’ll jump in and modify the query settings if needed.

All our functions are going to have a similar structure. First we’re going to make sure we’re accessing the main query. If we don’t check this first our code will affect everything from nav menus to recent comments widgets. We’ll do this by checking $query->is_main_query(). This was added in WordPress 3.3. For earlier versions, compare $query to the global $wp_the_query variable, as shown below in the 3.2 code below.

Then we’ll check to make sure the conditions are right for our modification. If you only want it on the homepage, we’ll make sure the query is for home ( $query->is_home() ).

Finally, we’ll make our modification by using the $query->set( 'key', 'value' ) method. To see all possible modifications you can make to the query, review the WP_Query Codex page.

Exclude Category from Blog

<?php

add_action( 'pre_get_posts', 'be_exclude_category_from_blog' );
/**
 * Exclude Category from Blog
 * 
 * @author Bill Erickson
 * @link http://www.billerickson.net/customize-the-wordpress-query/
 * @param object $query data
 *
 */
function be_exclude_category_from_blog( $query ) {

	if( $query->is_main_query() && $query->is_home() ) {
		$query->set( 'cat', '-4' );
	}

}

We’re checking to make sure the $query is the main query, and we’re making sure we’re on the blog homepage using is_home(). When those are true, we set ‘cat’ equal to ‘-4′, which tells WordPress to exclude this category.

If we were using WordPress 3.2 or earlier, the code could look like this:

<?php

add_action( 'pre_get_posts', 'be_exclude_category_from_blog' );
/**
 * Exclude Category from Blog
 * 
 * @author Bill Erickson
 * @link http://www.billerickson.net/customize-the-wordpress-query/
 * @param object $query data
 *
 */
function be_exclude_category_from_blog( $query ) {

	global $wp_the_query;
	if( $wp_the_query === $query && $query->is_home() ) {
		$query->set( 'cat', '-4' );
	}

}

Change Posts Per Page

Let’s say you have a custom post type called Event. You’re displaying events in three columns, so instead of the default 10 posts per page you want 18. If you go to Settings > Reading and change the posts per page, it will affect your blog posts as well as your events.

We’ll use pre_get_posts to modify the posts_per_page only when the following conditions are met:

• On the main query
• Not in the admin area (we only want this affecting the frontend display)
• On the events post type archive page

<?php

add_action( 'pre_get_posts', 'be_change_event_posts_per_page' );
/**
 * Change Posts Per Page for Event Archive
 * 
 * @author Bill Erickson
 * @link http://www.billerickson.net/customize-the-wordpress-query/
 * @param object $query data
 *
 */
function be_change_event_posts_per_page( $query ) {

	if( $query->is_main_query() && !is_admin() && is_post_type_archive( 'event' ) ) {
		$query->set( 'posts_per_page', '18' );
	}

}

Modify Query based on Post Meta

This example is a little more complex. We want to make some more changes to our Event post type. In addition to changing the posts_per_page, we want to only show upcoming or active events (so not ones that have ended), and sort them by start date with the soonest first.

I’m storing Start Date and End Date in postmeta as UNIX timestamps. With UNIX timestamps, tomorrow will always be a larger number than today, so in our query we can simply make sure the end date is greater than right now.

Creating the metabox and the fields within it are beyond the scope of this tutorial, but take a look at my post on Custom Metaboxes and this Events Plugin if you you want more informaton.

If all the conditions are met, here’s the modifications we’ll do to the query:

• Do a meta query to ensure the end date is greater than today
• Order by meta_value_num (the value of a meta field)
• Set the ‘meta_key’ to the start date, so that’s the meta field that posts are sorted by
• Put it in ascending order, so events starting sooner are before the later ones

<?php

/**
 * Customize Event Query using Post Meta
 * 
 * @author Bill Erickson
 * @link http://www.billerickson.net/customize-the-wordpress-query/
 * @param object $query data
 *
 */
function be_event_query( $query ) {

	if( $query->is_main_query() && !is_admin() && is_post_type_archive( 'event' ) ) {
		$meta_query = array(
			array(
				'key' => 'be_events_manager_end_date',
				'value' => time(),
				'compare' => '>'
			)
		);
		$query->set( 'meta_query', $meta_query );
		$query->set( 'orderby', 'meta_value_num' );
		$query->set( 'meta_key', 'be_events_manager_start_date' );
		$query->set( 'order', 'ASC' );
		$query->set( 'posts_per_page', '4' );
	}

}

add_action( 'pre_get_posts', 'be_event_query' );

It’s a question I’m asked often and I think it’s a tutorial that’s been missing.

Here’s my general process:

1. Create a subdirectory on my site for this project
2. Install WordPress and Genesis
3. Build all the site’s functionality into a child theme
4. Use CSS to make the outputted markup match the provided design
5. Send it to the client for review

The tutorial covers creating the child theme that has all the site’s functionality (step #3). Please take a look and let me know what you think in the comments over there.