The early years

As I was growing up in smalltown Alabama, I always wanted to be a writer. From about the time I could hold a crayon, I was writing something. Writing on the walls. The kitchen table. Occasionally, on paper. From what my parents tell me, I could do this quite well at about the age of 3.

During my pre-teen years, I wanted to follow in my father’s footsteps and write songs, so music and lyrics were my first introduction to how beautiful language could be.

Eventually, I outgrew my songwriting phase. Be glad I did. The world certainly doesn’t need any more boy-band pop songs. I figured I could offer something of a little more substance to the world.

High school

In high school, I had the most wonderful English teacher. She was one of those teachers that understood that literacy is not just about basic reading and writing skills. Literature. Technology. Music. Film. Those are the things that matter. Don’t get me wrong. We still had to do the boring high school English class stuff. But, she opened my mind to the world outside of the small town I was living in.

At some point during my senior year I realized that I wanted to write. I mean really write. It was the first time I’d ever put “write a book” on my list of life goals.

College

I graduated from Auburn University in 2007 with a B.A. in English and a concentration in creative writing and journalism.

When I began college, I didn’t plan on having a degree in English. I was in software engineering. Then I was in hotel and restaurant management. Then I was in software engineering again. Like many other college students, I bounced around majors a few times. It was tough finding something that was both enjoyable and challenging.

Despite protests from friends and a few from my family, I decided to take the plunge and declare myself as an English major. What I found was something that I loved. How could anyone not love reading 20+ books a semester? I had the time of my life exploring ethnographic studies, novels, and even the Bible as literature.

Each professor impacted my life in some way. Each class allowed me to explore other cultures. Each friend I got to know, helped shape me.

By the time I graduated, I had narrowed my list of life goals down to a few things. At the top of that list: Write something that has an impact on someone’s life.

At some point during college, I also started learning HTML, CSS, PHP, and WordPress.

After college

Harsh realization that life is not all roses and peaches.

…Time spent wandering the globe…

I moved back to Alabama last year because I wanted to get back to my roots. I wanted to engulf myself in the white-trash, trailer-park, tobacco-chewing culture that I hadn’t been a part of in so long.

The plan: Observe the culture. Write.

I could give you at least 100 reasons why I haven’t finished a novel yet, but I won’t. There’s no point in trying to justify losing sight of my goal.

I also spent some more time playing around with WordPress during this phase of my life. I suppose that time could’ve been spent working on the great Southern American novel.

An opportunity

A few months ago, I received an email about collaborating on a WordPress plugin development book for Wrox, a company devoted to publishing books “by programmers for programmers.”

At first, I was a bit hesitant to take on any extra WordPress projects. It also meant that I wouldn’t be able to apply for teaching jobs this school year, which was one of my goals for 2010. And, it wasn’t quite what I had in mind when I put “write a book” on my list of life goals.

However, it was an opportunity to write about something I’m passionate about.

The book

We have a great team of WordPress minds melding for what will be an awesome WordPress plugin development book. Brad Williams, Ozh Richard, and I are the writers. We’ve also picked up Andrew Nacin as our WordPress technical editor.

As a sidenote to this: I’m convinced that Andrew is actually a super-advanced robot that has been programmed to do nothing other than write awesome WordPress code. And, I’m happy to have him on the team.

I don’t want to get into too many technical details about the book yet. I do want to say that it will be a great resource for professional plugin development. We will put everything we have into making this the best book on creating plugins available for WordPress.

For me, this book announcement is mostly about sharing my personal journey to this point. I am thankful that Wrox, Brad, and Ozh are giving me an opportunity to realize one of my lifelong dreams. And, I hope that all my readers will come along on this journey with me (and buy the book when it’s published in March).

Also, check out theses posts by Brad and Ozh:

• New Book: Professional WordPress Plugin Development
• Into Plugins? You Will Love This.

The question usually goes back to my original post on creating a movie database with taxonomies. In the tutorial, I explain how to make several taxonomies that represent people (actor, director, producer, and writer). Taxonomies give us a way to clearly label and organize what roles a person takes on within the production of a movie. The relationship between the given taxonomy and the movie post type usually stops there.

The question: How does one make an “actor” both a taxonomy term and a post of a specific post type?

That’s essentially what most of the questions boil down to. We want the clear organizational structure of taxonomies, but we also want each term in a taxonomy to behave as if it were a post/page with the ability to edit the content, upload media, have custom fields, and allow comments. So, we also need a “person” post type to handle this.

Creating taxonomies and post types is the easy part. Making the connection we want is the complex part of the question.

What we’re doing

In this tutorial, we’re trying to make connections between two post types and one taxonomy.

• Movie (post type).
• Person (post type).
• Actor (taxonomy).

In my movie database example, we’d be making the connection with several taxonomies. But, I want to keep this tutorial simple.

The goal is to create a “movie” and list its actors on the movie page. But, instead of going to an actor archive when clicking on one of the actor’s names, we want to visit a “person” page with custom content. This would allow you to write custom content, upload images, add videos, open up the commenting section, and do all the things you’d normally be able to do with posts.

On the movie database, when we see Tom Hanks listed as an actor, we’d want to visit a custom person page we set up for him.

Post type and taxonomy setup

The rest of this tutorial assumes a working knowledge of creating post types and taxonomies. The examples below will be limited and likely won’t be helpful unless you have an understanding of this process. Please read my previous tutorials on post types and taxonomies for a more in-depth review.

Open your theme’s functions.php file and add this PHP code to create the movie and person post types.

add_action( 'init', 'my_register_post_types' );

function my_register_post_types() {

	register_post_type(
		'movie',
		array(
			'public' => true,
			'labels' => array( 'name' => 'Movies', 'singular_name' => 'Movie' )
		)
	);

	register_post_type(
		'person',
		array(
			'public' => true,
			'labels' => array( 'name' => 'People', 'singular_name' => 'Person' )
		)
	);
}

Now, let’s add some code for our actor taxonomy.

add_action( 'init', 'my_register_taxonomies' );

function my_register_taxonomies() {

	register_taxonomy(
		'actor',
		array( 'movie' ),
		array(
			'public' => true,
			'labels' => array( 'name' => 'Actors', 'singular_name' => 'Actor' )
		)
	);
}

That should give us a simple setup to work with and base to build our new functionality on.

The biggest thing to note here is that we have to be careful with our actor and person slugs. When we create a new actor (term), we need to have the exact same slug as the person (post). For example, when creating the Tom Hanks “actor,” it needs to have the slug of tom-hanks. And, when we create the Tom Hanks “person,” it needs to have the slug of tom-hanks. Otherwise, the proposed solutions below won’t work.

Option #1: Changing term links to post permalinks

One option is to change the links to actor archives to a specific post. We’ll be working with term and post slugs in this step. I normally don’t recommend using slugs because IDs are usually best to work with. They don’t change and slugs can. Unfortunately, connecting the terms and posts via ID isn’t something we can do right now.

The code below will do this step automatically for you. What it does is filter term_link (link to actor archive page). It grabs the term slug (actor name) and searches for a post slug that matches the term slug and has a post type of “person.” If it finds the post, it switches the link for you. Otherwise, it does nothing.

If you’re listing a ton of terms on one page, this solution isn’t ideal unless you mix it in with a caching solution.

add_filter( 'term_link', 'my_term_to_type', 10, 3 );

function my_term_to_type( $link, $term, $taxonomy ) {

	if ( 'actor' == $taxonomy ) {
		$post_id = my_get_post_id_by_slug( $term->slug, 'person' );

		if ( !empty( $post_id ) )
			return get_permalink( $post_id );
	}

	return $link;
}

function my_get_post_id_by_slug( $slug, $post_type ) {
	global $wpdb;

	$slug = rawurlencode( urldecode( $slug ) );
	$slug = sanitize_title( basename( $slug ) );

	$post_id = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_name = %s AND post_type = %s", $slug, $post_type ) );

	if ( is_array( $post_id ) )
		return $post_id[0];
	elseif ( !empty( $post_id ) );
		return $post_id;

	return false;
}

Option #2: Redirect term archives to posts

In the above example, term archives are still publicly available. We’re not doing a redirect, so it’s possible for someone to still stumble upon the archive or for you to even make it available if you wanted to. But, if you’re looking for a way to redirect anyone that visits a term archive to the appropriate post, use the code below. This method is also a lot more efficient.

Use this code in your functions.php file.

add_action( 'template_redirect', 'my_redirect_term_to_post' );

function my_redirect_term_to_post() {
	global $wp_query;

	if ( is_tax() ) {
		$term = $wp_query->get_queried_object();

		if ( 'actor' == $term->taxonomy ) {
			$post_id = my_get_post_id_by_slug( $term->slug, 'person' );

			if ( !empty( $post_id ) )
				wp_redirect( get_permalink( $post_id ), 301 );
		}
	}
}

function my_get_post_id_by_slug( $slug, $post_type ) {
	global $wpdb;

	$slug = rawurlencode( urldecode( $slug ) );
	$slug = sanitize_title( basename( $slug ) );

	$post_id = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_name = %s AND post_type = %s", $slug, $post_type ) );

	if ( is_array( $post_id ) )
		return $post_id[0];
	elseif ( !empty( $post_id ) );
		return $post_id;

	return false;
}

Asking for a term meta table

There has been some discussion in the WordPress community about adding a term meta table to the WordPress core. I can list a ton of reasons this would be a great idea, but let me just focus on how it would make the above solutions even better.

Right now (in the examples), we’re calling up the database to search for a post based on a slug. This isn’t something I really like to do on the front end, especially with the first example. For example, listing 50 actors on a page using the first option would cause us to search the database 50 times to see if a post slug matches the taxonomy term.

A term meta table would easily solve this problem. We could save the post ID as metadata for individual terms. We could even do the post lookup in the backend instead of doing it on-the-fly on the front end of the site. Or, even provide a nice interface for easily selecting the post/term we want to connect. Having term meta would allow us to do a quick check if there’s a post we want to redirect to.

Other solutions and thoughts

The above solutions are just something I was tinkering around with because of the enormous number of questions I get about this. I haven’t fully explored every possible option, so I can’t say that either is the best route to take. Think of it more as “Justin thinking out loud” than a definite solution.

I would love to hear your take on other solutions or even solutions that we could try to get rolled into core to better handle metadata and relationships between post types and taxonomies.

The idea of parent/child themes was created so that the parent theme could be updated while keeping customizations intact within a child theme. That system works great. The problems begin when a child theme is updated. Users tend to want to take advantage of the update, but they can’t upgrade because they’ve made customizations.

Essentially, we’ve just added another layer to the preexisting problem.

But, that’s not where the real problem is at. The problem is confusion over what frameworks, parent themes, and child themes are. Users aren’t to blame for this confusion. Theme developers are at fault here (even me), and I’m going to attempt to clear things up.

Advanced parent themes are not frameworks

I’m going to avoid calling any other “framework” themes out and tell you that my own Hybrid theme is not a framework, at least not in the traditional development framework sense. It’s an advanced parent theme. Admittedly, I’ve called it a “framework” before because I’ve just been following the crowd.

What should we call the Hybrid theme? Simple. It’s a parent theme.

One thing we should definitely not confuse are the terms “framework” and “parent theme.” These two are not interchangeable. That’s where a lot of the confusion stems from.

What is a theme framework?

This is the question I most wanted to answer because I’ll be releasing a framework for theme developers soon (see below). But, I can’t do that with all this confusion floating around the community.

A theme framework is a set of conventions to use for developing WordPress [parent] themes.

Yes, that’s a bit vague, but frameworks can exist for all kinds of different purposes. This can be something like an elegant template engine (Carrington Core is really good for this) or a set of helper functions for more quickly building a theme.

It is not a theme though. You can’t simply drop it in your WordPress themes directory and expect it to work.

Frameworks are for theme developers. They offer a set of standards (or whatever features) for theme developers to use in creating their own themes. They’re a set of functions/features created to aid development.

What is a parent theme?

Nearly all WordPress themes are parent themes. Only those called “child themes” are not parent themes.

Theme developers create parent themes for users to download and install on their sites. My Hybrid theme is, without a doubt, a parent theme. Parent themes should house the theme design, functionality, and the templates required for running the theme in WordPress.

You can use a framework to build a parent theme, but the framework is not a parent theme itself.

What is a child theme?

A child theme is something users should be creating so that they can customize the look and functionality of their site. The child theme inherits all of its functionality from a single parent theme.

When a theme developer creates a child theme, things become problematic because that child theme might eventually need an update. If you’re a theme developer and are building a child theme with a 20kb functions file and five or six custom templates, I can assure you that you’re doing it wrong. I’ve even had to tell myself this.

What you should really be creating is a parent theme. Child themes from theme developers should be nothing more than a stylesheet and a few functions. This idea of releasing advanced child themes just creates the same problem child themes were meant to solve: upgradability.

I’ve got over two years of experience at this point in dealing with parent/child themes if you need a reason to take my advice on this.

How frameworks work

Confused yet? Let me break this process down for you and explain how it should work.

• Frameworks come packaged within a single folder.
• Developers drop the framework folder into a new parent theme and load the framework.
• Users create a child theme based on the parent theme to house their customizations, allowing both the framework and parent theme to be updated.

Here’s a diagram for reference:

Users should only ever have to worry about creating a child theme. This will allow them to make modifications without losing them when the parent theme is updated. They shouldn’t have to worry about all the other stuff.

As you can see by now (I hope), the question of grandchild themes has been completely averted because theme developers shouldn’t be adding advanced functionality (that might need future updating) within child themes.

Doesn’t Hybrid break these rules?

The Hybrid parent theme doesn’t break the rules. A couple of the child themes? Definitely. If I could afford a time-traveling machine (and if they existed), I’d zip back a year or two and turn a couple of those child themes into parent themes instead. We all have to learn from our mistakes, and I can freely admit that I’ve taken the wrong route on occasion.

So, I’m going to give you a real-world example of everything I’ve been talking about and how it could’ve been avoided with one of my own themes.

Hybrid has a child theme called Hybrid News. This child theme has a few extra features that make it more advanced than its parent theme. One good example of a problem was when WordPress 3.0 launched with a new menu system (which I love). The Hybrid News child theme has an extra navigation menu that’s not present within its parent theme.

The problem: How do you upgrade the Hybrid News child theme to use the the new nav menu system for its extra menu?

You certainly can’t expect users to upgrade the child theme and lose all of their customizations. To solve this particular problem, I wrote a tutorial on making the switch to the new system. But, it was just a way to avoid the larger problem at hand.

The solution should’ve been: Make Hybrid News a parent theme. This would allow it to be upgraded and users to keep their customizations intact.

If you’re a theme developer with a lot of advanced child themes, you may be thinking that you’ve got this problem all figured out. You may have already come up with plenty of nifty solutions for avoiding these types of problems. But, no one can foresee what new things will come in later versions of WordPress to conflict with those solutions.

Introducing Hybrid Core: A theme framework

Last year, I mentioned that I’d release Hybrid Core to the public for download. Unfortunately, that release never came out. I wanted some more time to perfect it, which turned out to be around a year worth of extra time.

Hybrid Core will be a theme development framework for use by other theme developers. What this means is that any theme developer will be able to download this and build parent themes with an awesome framework behind them. Yes, I’m essentially giving you the keys to the Theme Hybrid kingdom.

Hybrid Core is currently packaged within my Hybrid parent theme. It is used to handle the “logic” behind how the theme runs. Theme developers will be able to load this framework and build themes using the set of conventions provided by the framework. All of the HTML, CSS, and extra functionality will be left up to you.

In the next month or two, I’ll be putting the finishing touches on this. I’m still moving some stuff around that’s specific to the Hybrid parent theme and getting it out of the way.

It’d be awesome to see many great themes built off this framework. It’s a project that I started building in June 2008, so a lot of work and testing have been put into it. The next theme I build will be a parent theme based off it, so you’ll have a good, working example of how to use the framework.

Just in case you were wondering if building a “grandchild” theme is actually possible, the answer is no, at least not by default. And, I hope to never see the day it happens.

But, I still wanted a way to easily allow readers to visit my archives. I also wanted to not just show monthly archives like the standard WordPress archives widget. The method I decided on has three major benefits:

• Allows readers to find archives by year, month, and day.
• Doesn’t take up any extra space on my blog.
• The code was already written in my Breadrumb Trail plugin, so there wasn’t much I had to do.

On this blog and many others, we have a thing called a byline or dateline, which is usually located before or after the post title. Traditionally, the date the post was written is shown. But, it doesn’t do much. It just sits there. Yes, it provides valuable information to the user but not anything more than that.

What we’re going to do is link the various parts of the date to archive pages. We’re going to give the post date more purpose.

Creating the post date link function

The first thing we need to do is create a function in our theme’s functions.php file. Actually, we’re going to create a function and a shortcode. Just drop this PHP code in the file:

<?php

add_shortcode( 'entry-link-published', 'my_entry_published_link' );

function my_entry_published_link() {

	/* Get the year, month, and day of the current post. */
	$year = get_the_time( 'Y' );
	$month = get_the_time( 'm' );
	$day = get_the_time( 'd' );
	$out = '';

	/* Add a link to the monthly archive. */
	$out .= '<a href="' . get_month_link( $year, $month ) . '" title="Archive for ' . esc_attr( get_the_time( 'F Y' ) ) . '">' . get_the_time( 'F' ) . '</a>';

	/* Add a link to the daily archive. */
	$out .= ' <a href="' . get_day_link( $year, $month, $day ) . '" title="Archive for ' . esc_attr( get_the_time( 'F d, Y' ) ) . '">' . $day . '</a>';

	/* Add a link to the yearly archive. */
	$out .= ', <a href="' . get_year_link( $year ) . '" title="Archive for ' . esc_attr( $year ) . '">' . $year . '</a>';

	return $out;
}

?>

For non-American users, you might want to switch the dates around as I’m using the “Month Day, Year” format. The WordPress Codex also has a helpful guide on formatting date and time if you want to mix things up a bit.

Note to theme authors: Please don’t implement this function as is into your themes. There are tons of variations on the date/time format and we have to respect what the user chooses unless the design can’t be accomplished without a specific format. If you come up with a way to handle all scenarios, then by all means, go for it.

Using the published link in your theme

We’ve added the function to run this to our theme’s functions.php file. Now, we have to use the function in our theme. All themes are going to be a little different, so I can’t tell you exactly where to put the code. You’ll just have to look in your theme templates or ask your theme author how to do it. I can tell you that this code should go within The Loop.

This is the code you add to the template:

<?php echo my_entry_published_link(); ?>

That’s all the code you have to deal with.

If you’re using a super-intelligent theme like Hybrid, you can use the [entry-link-published] shortcode and not worry about adding the PHP function.

Or, if you’re not using Hybrid and just want to know how to run a shortcode in a theme template, try this out:

<?php echo do_shortcode( '[entry-link-published]' ); ?>

What are the benefits of doing this?

I count two main benefits:

• Providing an easy way for readers to visit your archives. It never hurts to implement more methods of keeping people on your site.
• It’s just something fun to do. Maybe spruce up your blog a little.

Maybe it’ll even help search engines crawl your site easier. I don’t know. I quit trying to figure them out a long time ago.

I hope you enjoy this little snippet of code. If you want to see it in action, I’m using it on my blog now. Just look at my post byline and you’ll see the date linked to three different archives.

I’ve been promising a real-world example of what’s possible with custom post types for a while. But, I didn’t want to put together yet-another-long-technically-detailed post. I wanted to give you something that would open your mind to the possibilities.

And, there’s loads of possibilities.

I’ve been tinkering around with the idea of building a forum plugin, so I decided to get behind the project completely and make it happen. What started out as a simple project quickly turned into something that a lot of people have been wanting — a forum plugin that fully integrates itself within WordPress.

Post types for the plugin

The plugin uses three post types for handling the structure:

• Forums: This is your top level, which holds everything else.
• Topics: Children of forums and use the topic tags taxonomy.
• Replies: These are the individual posts made within a topic.

I had originally taken a different route of using a forum taxonomy, topic post type, and reply comment type. However, using that structure had major limitations.

The benefits of using three post types are numerous. Here are some examples:

• Forums can have metadata (custom fields) and media attachments added to them to allow a lot of cool stuff (forum thumbnails, for example).
• You get pretty permalinks using a reply post type (forums/topic-name/page/2).
• Replies can also have their own media attachments (user-uploaded images).
• Capabilities/permissions are handled a lot better with post types.
• Can set up custom post statuses such as “closed” and use the current statuses like “private.”
• Works well with plugins that allow you to edit from the front end of the site.

This is not to say there aren’t issues with this method. There’s a lot of custom work work that needed to be done, which isn’t surprising considering I’m using custom post types.

I can’t take all the credit for this idea of using three post types. John James Jacoby convinced me this was the best route to go.

Taxonomies for the plugin

The only taxonomy used by default is the topic tag taxonomy. It allows users to assign tags to specific topics.

The great thing about the plugin though is that you can build custom taxonomies on top of it. You can give forums, topics, and replies their own taxonomies if you wanted. Since we’re using custom post types for those things, the possibilities are endless.

Integration with WordPress

Obviously, we want our forum plugin to work well with WordPress. Some of the current problems users of other forum software are facing when integrating are:

• Separate user login pages (and separate user database tables in some cases).
• Separate roles and permissions setups.
• Using multiple themes to get the same design across the site.
• Not being able to use WordPress plugins within the forum.
• Having to figure out how “deep integration” works just to use things like menus and widgets.

My plugin seeks to solve those issues and use the tools available in WordPress.

Lightweight

I’m not a fan of adding every fancy gizmo and gadget in the world to a forum. I like to keep things simple and extend it with other plugins when I need a new feature. I also don’t want 20 theme templates when I can use a handful.

The biggest goal I have is to keep this thing as lightweight as possible. There are over 10,000 plugins for WordPress that will allow this plugin to be extended.

What about the bbPress plugin?

While this is outside the scope of what I’d planned on writing about, I know questions about bbPress will crop up. I’ll try to address those.

It’s true that bbPress will be becoming a plugin in the future and work has already started on it. I’m happy that there’s at least something happening. I love bbPress and have been using it for years, but I can’t wait around six or seven months again to see where the project is headed. I’m not saying bbPress isn’t going anywhere, but I had to make the decision to move forward on my own after the last disappointment.

I’d love to be involved in the bbPress plugin project at some point, but my priorities right now don’t mesh well with it. It’d also be great if the ideas used in my plugin or any of its code gets used in the bbPress plugin.

One thing I will promise to plugin users is that I’ll try to make it as easy as possible to switch between either plugin if that’s what they choose to do.

Demo and testing

The plugin isn’t ready for a public release right now. There’s tons of work still ahead. But, testing does need to be done on a large enough scale for me to make this a solid plugin.

I’ve put the plugin on one of my own sites for live testing. If you have any interest in this plugin at all or just want to help test, please register for my forums at Pop Critics.

At first, I was a bit disappointed that this wasn’t taken care of because this would be a major blow to my plugin. However, I soon learned this could be considered a great feature rather than a bug.

Andrew Nacin mentioned that we’d need to “roll our own handling” for capabilities using the map_meta_cap hook. This hook gives you control over the meta capabilities as well as the power to step outside of the WordPress way of doing things. The more I play around with it, the more I’d rather WordPress not automatically map these.

Before reading on, please note that this is only an issue/feature if you’re using custom capabilities for your post types. If not, this might not interest you much.

What are meta capabilities?

Meta capabilities are capabilities a user is granted on a per-post basis. The three we’re dealing with here are:

• edit_post
• delete_post
• read_post

For regular blog posts, WordPress “maps” these to specific capabilities granted to user roles. For example, a user might be given the edit_post capability for post 100 if they are the post author or have the edit_others_posts capability.

When using custom post types, this mapping doesn’t happen automatically if you’re setting up custom capabilities. We have to come up with our own solution.

In this tutorial, I’ll be using the movie post type, so the above three meta capabilities for our purposes will be:

• edit_movie
• delete_movie
• read_movie

Setting up your custom post type

At this point, I’ll assume you’re familiar with creating custom post types. If not, you’ll want to read through my detailed tutorial on them. The code presented below will be an abridged version of what you might use.

We’re going to focus on two arguments, capability_type and capabilities. These control the permissions for what a user with a specific role can do with the post type.

As mentioned earlier, the post type we’re going with is movie. So, let’s set up that post type:

add_action( 'init', 'create_my_post_types' );

function create_my_post_types() {
	register_post_type(
		'movie',
		array(
			'public' => true,
			'capability_type' => 'movie',
			'capabilities' => array(
				'publish_posts' => 'publish_movies',
				'edit_posts' => 'edit_movies',
				'edit_others_posts' => 'edit_others_movies',
				'delete_posts' => 'delete_movies',
				'delete_others_posts' => 'delete_others_movies',
				'read_private_posts' => 'read_private_movies',
				'edit_post' => 'edit_movie',
				'delete_post' => 'delete_movie',
				'read_post' => 'read_movie',
			),
		)
	);
}

I’ve also added in a couple of extra capabilities that were not shown in my previous tutorial on post types: delete_posts and delete_others_posts. We’re going to use these to give people the ability to delete posts (movies).

Assigning capabilities to roles

To assign specific capabilities to roles, you’re going to need a role management plugin. A good one to use is my Members plugin. You could code this if you wanted, but it’s a bit outside the scope of this tutorial.

What you need to do at this point is assign capabilities to the roles that should have them. Just be careful not to give too much power to the wrong roles.

• publish_movies: This allows a user to publish a movie.
• edit_movies: Allows editing of the user’s own movies but does not grant publishing permission.
• edit_others_movies: Allows the user to edit everyone else’s movies but not publish.
• delete_movies: Grants the ability to delete movies written by that user but not others’ movies.
• delete_others_movies: Capability to edit movies written by other users.
• read_private_movies: Allows users to read private movies.
• edit_movie: Meta capability assigned by WordPress. Do not give to any role.
• delete_movie: Meta capability assigned by WordPress. Do not give to any role.
• read_movie: Meta capability assigned by WordPress. Do not give to any role.

Just to say it again: it is important that you don’t assign those last three capabilities to any role. These are our meta capabilities that we’ll be mapping in the next section.

Mapping the meta capabilities

This part is completely customizable. What we’re doing here is filtering the map_meta_cap hook so we can do our own mapping. What this means is that users will be granted meta capabilities on a per-post basis so they can do things like edit their own posts.

I’m going to keep it extremely simple and follow my notes from the previous section. If you wanted, you could do all kinds of crazy things here.

You can simply drop the below in your plugin or theme’s functions.php (whichever you’re using) and be done with it. It’ll follow the rules I set forth above.

add_filter( 'map_meta_cap', 'my_map_meta_cap', 10, 4 );

function my_map_meta_cap( $caps, $cap, $user_id, $args ) {

	/* If editing, deleting, or reading a movie, get the post and post type object. */
	if ( 'edit_movie' == $cap || 'delete_movie' == $cap || 'read_movie' == $cap ) {
		$post = get_post( $args[0] );
		$post_type = get_post_type_object( $post->post_type );

		/* Set an empty array for the caps. */
		$caps = array();
	}

	/* If editing a movie, assign the required capability. */
	if ( 'edit_movie' == $cap ) {
		if ( $user_id == $post->post_author )
			$caps[] = $post_type->cap->edit_posts;
		else
			$caps[] = $post_type->cap->edit_others_posts;
	}

	/* If deleting a movie, assign the required capability. */
	elseif ( 'delete_movie' == $cap ) {
		if ( $user_id == $post->post_author )
			$caps[] = $post_type->cap->delete_posts;
		else
			$caps[] = $post_type->cap->delete_others_posts;
	}

	/* If reading a private movie, assign the required capability. */
	elseif ( 'read_movie' == $cap ) {

		if ( 'private' != $post->post_status )
			$caps[] = 'read';
		elseif ( $user_id == $post->post_author )
			$caps[] = 'read';
		else
			$caps[] = $post_type->cap->read_private_posts;
	}

	/* Return the capabilities required by the user. */
	return $caps;
}

Now taking questions

I realize there’s still quite a few things that I might not have covered in my tutorials on post types so far. Some people have probably figured these out by now, but others of you may be stuck.

Feel free to ask any questions you have about post types, and I’ll see about answering them or writing more tutorials based on your suggestions.

The issue: Before WordPress 3.0 was released, a small piece of code was added to the WordPress core that changes all instances of “Wordpress” (notice the lowercase “p”) to “WordPress” in areas where content is shown on the site. We’ll get to the details in a bit.

I tried hard to stay out this debate because I’m fairly certain I made a vow to myself to stay out of these types of arguments. But, I’ve got a few opinions on this one that I can’t just keep to myself. And, as someone that is considered a leader within the WordPress community, I feel responsible for communicating with that community on this issue.

It’s spelled “WordPress”

WPCamelCase.com says so, and I’d never question an entire site dedicated to the proper spelling of a single word.

On a more serious note, these are not proper:

• Wordpress
• wordPress
• wordpress
• Word Press
• word press
• wordress
• WoRdPrEsS

Coming from an English and journalism (especially journalism) background, I feel a strong need to hack into the site of anyone that misspells WordPress and correct it for them. Fortunately, I don’t know how to hack people’s sites, have just a smidgen of self control, and respect the rights of others.

Why is there an issue?

Matt Mullenweg wrote a filter function called capital_P_dangit() that correctly capitalizes the “P” in misspellings of WordPress where the “p” is lowercase. It may seem like a minor thing, but there are several issues at hand.

• The code literally breaks things like URLs on some sites. For example, suppose you installed WordPress in a /Wordpress directory. That would cause all kinds of trouble with things like images.
• This function is effectively changing what people write, and WordPress should not have editorial control over the content of anyone’s blog.
• The code was committed to WordPress without a Trac ticket, so it wasn’t left open to community discussion beforehand.
• Matt’s responses seem to dismiss the very community of people that help make WordPress what it is.

Following the discussion

I cannot accurately represent all of the discussion that has happened to this point. I highly recommend that you read the discussions provided by the below links if you want all the details.

• “Wordpress” being turned into CamelCase “WordPress” breaks URLs
• Putting the P in WordPress: WP Hackers
• Automatically Correcting the WordPress Mistake
• Wordpress -> WordPress in core?
• MattPress Egomania
• “Wordpress” to “WordPress” filter
• A Fuss About Nothing
• CapitalP.org

Breaking URLs

If nothing else, this issue must be addressed. In fact, this bug was brought up in a bug report before WordPress 3.0 was released. Yes, before.

The resolution set for this bug: wontfix.

A new ticket is now open for discussion and resolutions. Mark Jaquith has at least created a patch that should fix this issue.

Don’t change my content

The real issue is not the bug; it’s the display of content that people didn’t write. Sure, the cases where people actually intend to misspell WordPress are rare, but that’s besides the point.

The point is that the content is yours, and you should be able to write anything any way you see fit, including “WordPress.”

If you want to debate that last statement in any way, I suppose you can try all you want, but I can’t think of a single reason why a piece of software should be able to control the output of my words without consent.

We’re talking about principles here, and changing what people write in this manner goes against everything I believe in. I simply refuse to allow this on my site.

One of the reasons I use WordPress is because of its philosophy on community, openness, and freedom, which fits along nicely with my own personal philosophy about most things in life. The idea that a piece of software could infringe upon those values is what bothers people.

What about emoticons and auto-paragraphs?

What about apples and oranges?

This line of reasoning keeps getting brought up in the debate.

If you think the forced spelling of a word and the opt-in process of converting smileys and basic word-processing are one in the same, there’s no convincing you there’s an issue. You may as well stop reading now.

Why don’t you build a plugin?

According to Matt Mullenweg, a plugin should be built:

As I said before, you are in /complete control/ of your site. It’s a single line to remove a filter. If you don’t like the filter, vote with your feet or with a plugin.

Vote with your feet? This type of remark represents one of the biggest issues in the WordPress community. Attitudes like this can bring down entire empires.

I completely agree with the plugin idea though. Building plugins to gauge community interest in certain features and making the decision to include these plugins in core code based on statistics is a great idea.

As pointed out by Jeff Chander, it just so happens that someone made a plugin nearly three years ago that does the same job as capital_P_dangit(). It’s called Ozh’ Correctly Spell WordPress.

At the time of writing, this plugin has received a grand total of…wait for it…338 downloads!

As flawed as that argument is, a new plugin has been created called Remove Wordpress to WordPress Filter that disables the capital_P_dangit() functionality. Funnily enough, its number of downloads will likely surpass the other plugin within a week or two given its current rate of adoption.

But, since we’re voting with plugins, there’ll be 16 other plugins that will disable this filter soon enough. All of my plugins will have this bug fix added to them in their next updates.

There’s two things that will make me reconsider this decision and remove this from my plugins:

• The capital_P_dangit() function is removed from the default filters or made to be opt-in.
• An outcry of arguments from my plugin users to remove it. Some of us listen to our users, even when we disagree with them.

Since some folks have missed the point of this last argument, which I thought was clever (though I’m a bit biased), I must inject a note here to interrupt the flow of this article. No, I don’t actually intend to update all 16 of my plugins to try and prove a point. The entire point is to show how irrational such an action would be.

How to remove the capital_P_dangit() filter

You can either install the Remove Wordpress to WordPress Filter plugin or add the below code to your theme’s functions.php file.

remove_filter( 'the_content', 'capital_P_dangit' );
remove_filter( 'the_title', 'capital_P_dangit' );
remove_filter( 'comment_text', 'capital_P_dangit' );

Listen to your community

I’ve only seen a handful of people that agree this function should be in WordPress. It has been met with harsh opposition. The people arguing to remove this function are people we need in the community. They’re plugin developers, theme developers, contributors to core code, and evangelists for the WordPress platform. These are the people that continue making WordPress better.

Don’t alienate them.

Are these people only a vocal minority of WordPress users? Certainly. However, these people speak for a larger amount of users. For users without the knowledge of mailing lists. For users without the understanding of how Trac works. They are the people that interact with the majority every day. They are the voice of the majority.

Don’t let their voices go unheard.

However, with WordPress 3.0 around the corner and the introduction of custom post types, the usefulness of custom taxonomies will increase greatly.

Post types are your forms of content. Taxonomies are the glue that holds that content together, linking it in all kinds of neat ways.

As I delve deeper into the subject of post types and taxonomies in this series of posts, I’ll give more examples of how these two things are related and how they can be used to create any type of site you want with WordPress.

First, we need a primer on taxonomies.

In WordPress 3.0, taxonomies will be super-charged. While I do encourage you to go back and read my original post on custom taxonomies and my followup on how I created a movie database to gain a better understanding of taxonomies, I’ll try to cover the important details in this post.

A refresher on what taxonomies are

Taxonomies are a method for grouping content. They’re a way of intelligently creating an organizational system for data. Some examples include:

• Finding actors (taxonomy) that have played in specific movies (content).
• Listing musicians (taxonomy) that have performed on various albums (content).
• Locating restaurants (content) that serve specific types of food (taxonomy).
• Getting recipes (content) that use certain ingredients (taxonomy).
• Searching for jobs (content) in different fields (taxonomy).
• Visiting a forum (taxonomy) that lists forum topics (content).
• Scanning for books (content) written by your favorite author (taxonomy).

Grouping content in this way simply isn’t possible with standard tags and categories. To understand the benefits of taxonomies, you have to open your mind to possibilities beyond a standard blog.

What’s new with taxonomies in 3.0?

Some things have changed since the major overhaul in WordPress 2.8 of taxonomies. Don’t worry; your previously-created taxonomies will still work fine. But, now you have much more control.

The biggest changes are:

• Ability to create taxonomies for any post type (not just posts).
• Hierarchical taxonomies now get admin screens just like non-hierarchical ones.
• Control over the capabilities for editing, creating, deleting, and assigning terms.
• Control over admin text for making the UI not seem so weird.

The register_taxonomy function

To register a taxonomy, we must use the register_taxonomy() WordPress function. It takes in three parameters.

register_taxonomy( $taxonomy, $objects, $arguments )

$taxonomy

The $taxonomy parameter should be a unique name for your taxonomy that’s not used by any other taxonomy.

register_taxonomy( 'division', $objects, $arguments )

$objects

The $objects parameter can be a string (single object type) or an array (multiple object types). This represents the post types that you want to register your taxonomy for.

register_taxonomy( $taxonomy, array( 'post', 'page' ), $arguments )

$arguments

The $arguments parameter is an array of arguments that help define how your taxonomy should function. I’ll cover these in more depth later.

register_taxonomy( $taxonomy, $objects, array() )

Creating a custom taxonomy

We’re going to keep everything pretty basic for this tutorial. Let’s create a taxonomy called division for your blog posts. The easiest way to do this is to add this code to your theme’s functions.php file or a plugin file.

add_action( 'init', 'register_my_taxonomies', 0 );

function register_my_taxonomies() {

	register_taxonomy(
		'division',
		array( 'post' ),
		array(
			'public' => true,
			'labels' => array(
				'name' => __( 'Divisions' ),
				'singular_name' => __( 'Division' )
			),
		)
	);
}

This will create a new item called “Divisions” for you under your “Posts” menu item in the admin.

Controlling your taxonomy

The arguments array (third parameter) of register_taxonomy() is the parameter that gives you fine-grain control over how your taxonomy functions in WordPress. It allows for about 10 arguments, which I’ll cover in detail here. In each section, I’ll give a basic code example of how each is used.

public

The public argument is sort of a catchall argument that controls whether your taxonomy is publicly used on the site or if works behind the scenes. Depending on whether it’s set to true or false, it’ll automatically set other arguments if they aren’t defined.

• show_ui: Whether the taxonomy should be shown in the administration interface.
• show_tagcloud: Whether to allow the taxonomy to be chosen in the tag cloud widget.
• show_in_nav_menus: Whether to allow terms from the taxonomy in navigation menus.

'public' => true,
'show_ui' => true,
'show_tagcloud' => true,
'show_in_nav_menus' => true,

hierarchical

The hierarchical argument decides if your taxonomy’s terms are in a non-hierarchical (flat) or hierarchical format. By default, this is set to false, so the taxonomy will behave like the post tag taxonomy. Hierarchical taxonomies will behave like the category taxonomy.

'hierarchical' => false,

capabilities

New in WordPress 3.0 is the ability to change the capabilities for who can use the taxonomy in the admin. By default, users of roles with the manage_categories capability can manage, edit, and delete terms, and those of roles with the edit_posts capability can assign terms to a “post.”

• manage_terms: Ability to view terms in the administration. I don’t see any other use for this.
• edit_terms: Grants the ability to edit and create terms.
• delete_terms: Gives permission to delete terms from the taxonomy.
• assign_terms: Capability for assigning terms in the new/edit post screen.

If you’re using a role management plugin like Members, you can assign which users have control over your terms. If not, I suggest not changing these capabilities.

'capabilities' => array(
	'manage_terms' => 'manage_divisions',
	'edit_terms' => 'edit_divisions',
	'delete_terms' => 'delete_divisions',
	'assign_terms' => 'assign_divisions'
),

labels

The labels array is a set of text strings that control how your taxonomy is viewed in the admin. If your taxonomy is non-hierarchical, this defaults to the post tag wording. If it is hierarchical, it defaults to the category terminology.

• name: The plural name that represents your taxonomy.
• singular_name: The singular name for your taxonomy.
• search_items: Text for the search button when searching the taxonomy terms.
• popular_items: Header for the popular cloud of terms (not used with hierarchical taxonomies).
• all_items: Text to display all of the terms of the taxonomy.
• parent_item: Text for displaying the parent term (not used with non-hierarchical taxonomies).
• parent_item_colon: Text for displaying the parent term followed by a colon (not used with non-hierarchical taxonomies).
• edit_item: Represents the text when editing a term.
• update_item: Displayed when updating a term.
• add_new_item: Text to display for adding a new term.
• new_item_name: Text to display for adding a new term name.

'labels' => array(
	'name' => __( 'Divisions' ),
	'singular_name' => __( 'Division' ),
	'search_items' => __( 'Search Divisions' ),
	'popular_items' => __( 'Popular Divisions' ),
	'all_items' => __( 'All Divisions' ),
	'parent_item' => __( 'Parent Division' ),
	'parent_item_colon' => __( 'Parent Division:' ),
	'edit_item' => __( 'Edit Divison' ),
	'update_item' => __( 'Update Division' ),
	'add_new_item' => __( 'Add New Division' ),
	'new_item_name' => __( 'New Division Name' ),
),

query_var

The query_var argument allows you to get posts based on particular terms of the taxonomy through a query string in the browser URL bar or through a WordPress function like query_posts() or class like WP_Query. This will default to the name of your taxonomy, but you can also set it to false to prevent queries.

'query_var' => 'division',

rewrite

The rewrite argument gives you control over the permalink structure of your taxonomy’s term archives. You may want a structure like yoursite.com/divisions/blue-group, and this argument will give you control over that. It can be set to true, false, or an array of values. The values of the array are:

• slug: The slug you want to prefix your term archives with.
• with_front: Whether your term archives should use the front base from your permalinks settings.

'rewrite' => array( 'slug' => 'divisions', 'with_front' => false ),

update_count_callback

update_count_callback allows you to write a custom function that will be called when the term count is updated. Most users shouldn’t need this and shouldn’t bother setting this.

'update_count_callback' => 'my_custom_count_callback',

To answer the 18 billion questions from the last year

Since I first published an article on taxonomies last year, I’ve gotten numerous questions on using them. The two questions that crop up the most:

• Can I create a hierarchical taxonomy like categories?
• Can I use my taxonomy with pages (or other post types)?

It’s been a long time coming, but I can finally say, “Yes! And. Yes!”

I didn’t want to overwhelm everyone with too much information in this tutorial. I mostly wanted to give a refresher on taxonomies and cover some of the new features. I encourage you to read my previous posts on the subject for a deeper understanding of taxonomies.

The problem I see now is that there’s one more question that needs answering — how to merge taxonomies and post types. I’ve touched on this a bit in this post, but you can expect a real-world example from me in the near future.

The trouble is that a large majority of users want custom menus and no two menus are the same. There are tons of plugins that fix this problem in their own way. Even some theme developers have integrated menus systems into their themes.

Unfortunately, all of these solutions are different. We haven’t had a standard to go by, at least until now. WordPress 3.0 will introduce a new navigation menu system. Sure, there are some limitations with this system. However, with a set standard, new plugins will likely emerge to fill in the gaps.

In this tutorial, I’ll walk you through the features of the new system and how to build this into your theme if you’re a developer.

What the menu system offers

In WordPress 3.0, you’ll gain another admin screen under your Appearance menu called Menus. In the screenshot below, I’ve highlighted four key elements of the page.

• Theme Locations: If your theme supports nav menus, it’ll register new locations for you to add your custom-created menus.
• Individual Menus: This is where the names of your menus will appear after you’ve created them. (Note that the “+” sign will create a new menu.)
• Add Menu Items: There’ll be several meta boxes containing pages, other post types, categories, other taxonomies, and custom links to your menus.
• Menu Items: Once you’ve added menu items to your menu, they will appear under the menu for your configuration.

Each menu item can has its own configuration section too. Once the item has been added to the menu, you can open it and edit its attributes, which are standard things you might want to change about any menu.

• URL
• Navigation Label
• Title Attribute
• CSS Classes
• Link Relationship (XFN)
• Description
• Link Target (Please note that a kitten dies every time a link is opened in a new window/tab.)

Registering a menu for a theme (theme location)

To associate specific menus with locations within our themes, we need to register these locations. Otherwise, we won’t know which menu goes where. There are two functions we can use for this:

• register_nav_menu(): Registers a single theme location.
• register_nav_menus(): An array of locations we want to register.

In this example, we’ll register a single menu called Primary Menu from our theme’s functions.php file.

add_action( 'init', 'register_my_menu' );

function register_my_menu() {
	register_nav_menu( 'primary-menu', __( 'Primary Menu' ) );
}

primary-menu is the slug we’ll use to identify the menu in code. Primary Menu is the label we’ll use to identify the menu in the admin.

Building off that example, we’ll create multiple menus, which is not much different than registering a single menu.

add_action( 'init', 'register_my_menus' );

function register_my_menus() {
	register_nav_menus(
		array(
			'primary-menu' => __( 'Primary Menu' ),
			'secondary-menu' => __( 'Secondary Menu' ),
			'tertiary-menu' => __( 'Tertiary Menu' )
		)
	);
}

Displaying a nav menu

There are two ways to display a nav menu. One is by calling wp_nav_menu() within a theme template file. The other is by using the Navigation Menu widget.

Displaying a menu within a theme template

Most themes will call a menu from their header.php template, but menus can be placed anywhere. The simplest form of calling a nav menu in a theme will look like this:

<?php wp_nav_menu(); ?>

That will load the first menu the user created or fall back on a standard page list if no menus exist.

We want to have a bit more control than that though. Let’s call our menu from the previous section (Primary Menu).

<?php wp_nav_menu( array( 'theme_location' => 'primary-menu' ) ); ?>

You’re allowed even more control. wp_nav_menu() has several parameters you can use when displaying a menu.

• theme_location: The menu to call that is associated with the specific theme location.
• menu: Call a specific menu ID, slug, or name.
• container: The element that wraps around the list. The default is div but can be changed to nav if you’ve moved on to HTML 5.
• container_class: The CSS class of the container.
• menu_class: The CSS class given to the unordered list. This defaults to menu.
• fallback_cb: A function to call in the event that no menu items have been given. By default, wp_list_pages() will be called.
• before: Text that is displayed before the link text but within the link.
• after: Text that is displayed after the link text but within the link.
• link_before: Text that is displayed before the link.
• link_after: Text that is displayed after the link.
• depth: How many levels the menu should display, which is useful for things like drop-down menus. This is set to 0 (any level) by default.
• walker: Allows a custom walker PHP class to be defined to create the menu.
• echo: Whether to display the menu or return it for use in PHP. This defaults to true and displays the menu.

Displaying a menu using the Navigation Menu widget

By default, WordPress will give you a simple menu widget that will allow you to select any of your custom menus to display. All you need is a widget-ready theme.

Since using widgets is fairly self-explanatory and the new widget is simple, I’m going to use this opportunity for a little shameless self promotion.

For those of you that use my Hybrid theme, you know you have the coolest widgets ever because they give you complete control. Version 0.8 will have a much more advanced Navigation Menu widget that overwrites the WordPress default. Here’s a look at what controls you’ll have.

Styling nav menus

I won’t be covering how to style menus here. That’s a tutorial in and of itself, and there are tons of different ways to style menus. I do have a couple of tips though.

Use the current-menu-item class to style a menu item whose page is currently being viewed. This will allow you to highlight the item so the reader will know which page they’re on. Here’s an example from one of my style.css files:

#primary-menu li.current-menu-item a {
	background: #fff url(images/primary-menu-active.png) repeat-x 0 0;
	border-top: none;
	border-bottom: 2px solid #fff;
	}

A solid base to start with is the Superfish jQuery plugin. It allows some subtle, but cool, JavaScript functionality and fixes drop-downs in Internet Explorer 6 without having to resort to hacks.

Here’s a screenshot of a menu I’ve been working on for a new theme.

At this point, you should know everything you need to know about handling menus in WordPress. But, if you continue reading, I have a few more tips that you can use.

Collapsible menus

Let’s suppose you only want a menu to appear when a user has added menu items. This can allow for a variety of layouts. In the screenshot below, I’m using two menus. But, this allows for up to four different layouts.

The trick here is to make sure there’s no fallback called. Let’s return to our original menu (Primary Menu) and the code for it.

<?php wp_nav_menu( array( 'theme_location' => 'primary-menu', 'fallback_cb' => '' ) ); ?>

What I’ve done is simply tell WordPress that I don’t want my menu to fall back to another menu if the user hasn’t given the menu any items.

Checking if a theme location has a menu

Update: Props to Andrew Nacin for adding the has_nav_menu() function after reading this section of the article.

WordPress currently has no conditional tag to check if a menu has been set to a specific theme location. WordPress has a conditional tag called has_nav_menu() to check if a menu has been set to a specific theme location. Let’s suppose we’re creating a container with a menu and a search form. But, if no menu is set for the theme location, we don’t want either to appear.

In the screenshot, you can see that neither appear in one scenario and both appear in the other.

When you call your menu by theme location, you can first check to see if a menu is associated with the location. Note that we’re checking the theme location slug and not a menu name or ID.

<?php if ( has_nav_menu( 'primary-menu' ) ) { ?>

	<div class="nav-container">
		<?php wp_nav_menu( array( 'theme_location' => 'primary-menu' ) ); ?>
		<?php get_search_form(); ?>
	</div>

} ?>

Allowing more menu containers

The menu system will only allow for <div> and <nav> as a menu container by default. This is likely all you’ll ever need. If for some reason your menu needs to be wrapped by something else, you can allow for new containers.

add_filter( 'wp_nav_menu_container_allowedtags', 'my_menu_allowed_tags' );

function my_menu_allowed_tags( $tags ) {
	$tags[] = 'p';
	return $tags;
}

Note the the <p> tag isn’t something I’d recommend using to wrap a list. It’s just an example.

Getting a list of all theme locations

If you need to list your theme’s menu locations, use the code below. It will return an array of the locations.

$locations = get_nav_menu_locations();

Creating a menu

Most theme authors shouldn’t have a need to use this function, but there may be cases when it’s needed. In most situations, you should use the theme location feature (register_nav_menu()) rather than this. But, if you need to programmatically create a menu, do so using the wp_create_nav_menu() function.

wp_create_nav_menu( 'Menu Name', array( 'slug' => 'menu-slug' ) );

Checking if a specific menu exists

This is another function not likely needed by theme developers but may come in handy. It allows you to check if a menu exists by ID, name, or slug.

if ( is_nav_menu( 'menu-slug' ) )
	/* Do something if the menu exists. */
else
	/* Do something if the menu doesn't exist. */

Have fun with your menus

While there are certainly other features I love about WordPress 3.0 more, the new menu system is the feature that’ll help me the most as a theme developer. There’s also a ton of stuff you can do with menus that I couldn’t possibly cover in this tutorial. I’m going to leave that up to your imagination.

I do have one request from any plugin developer that’s up for a challenge: a “menu logic” plugin akin to Alan Trewartha’s awesome Widget Logic plugin.

In WordPress 3.0, we’ll have the capability to easily create and manage content via custom post types. Not only that, but you won’t have to rely on a plugin to do this for you. It can be done via your theme’s functions.php file with a few lines of code.

There are other 3.0 features such as menu management and multi-site, but this is the most promising feature coming. In this tutorial, I’ll walk you through the creation of custom post types and how they can be used for your blog.

Note that I’ll use “post” and “posts” a lot to refer to custom post types in this tutorial. I’ll try to separate this from what you likely know as a post by calling it a “blog post.”

What are custom post types?

Don’t be confused by the term “post” in the name. It is actually an extremely generic term and should not be considered the same thing as a blog post. If you prefer, you can replace it with “content” instead.

Custom post types don’t have any strict rules that define what they are. They can represent any type of content you want. For example, WordPress ships with several default post types.

• Blog Posts
• Pages
• Attachments
• Revisions
• Nav Menus (WordPress 3.0)

You should think of them as a way to create, edit, and store information in the same way as blog posts but with much more creative control.

One thing I would warn against is trying to separate your blog posts in this way. You have categories, tags, and custom taxonomies at your disposal if you’re just looking for a way to label them.

Ideas for custom post types

While WordPress ships with some good default post types that are great for most sites, some of us need alternatives. I’ll list some things below that I think would be useful and link to examples if I can.

• Real estate listings.
• Event calendar (I know a lot of folks are interested in this).
• Movie Database
• Book Database
• A forum without a lot of integration problems.
• A ticket system like the WordPress Trac.
• Design gallery/showcase.

Don’t let your imagination be limited by my list of examples. Also, look for some information on the forum and ticket system ideas from me in the future. Those two are projects I’ve been building and would love to get some feedback on.

Custom post types in the admin

Once you create a custom post type, WordPress can handle all of the admin stuff for you. By default, the administration interface will be the same as what you get with blog posts and pages. Of course, you’re welcome to get more advanced with it and change it into whatever you like.

In this tutorial, I’m creating a post type called Super Duper. With the minimum post type settings, the admin will look like the screenshot below (click image for more detailed view):

Creating custom post types (basics)

WordPress 2.9 introduced the register_post_type() function. It didn’t do a lot at the time, but WordPress 3.0 will make this a powerful tool.

To get the basic functionality of a custom post type working, we hardly have any code to input. Before you start, you at least need a few things: a name, two labels, and whether your post type will be public (you’ll likely want this).

You can either create a plugin file or use your theme’s functions.php file to add the code. I will assume at this point of the tutorial that you know how to work with at least one of those two things.

Let’s set up our Super Duper post type.

add_action( 'init', 'create_my_post_types' );

function create_my_post_types() {
	register_post_type( 'super_duper',
		array(
			'labels' => array(
				'name' => __( 'Super Dupers' ),
				'singular_name' => __( 'Super Duper' )
			),
			'public' => true,
		)
	);
}

You’ll notice that there’s not a lot going on there. We added two parameters: a post type name and an array of arguments. All of the possible arguments are detailed in the next section.

If all you’ll ever want to do is something as basic as having a title field and content textarea, you can skip over the next portion of this tutorial.

Creating custom post types (in detail)

In the basic section above, we used two arguments to create our custom post type. However, the register_post_type() function has well over 20 arguments you can use. It gives you a lot of control over the specifics of your post type without a lot of hassle. You can mix and match these in all sorts of ways that I can’t even come close to covering in this tutorial.

Below, I’ll describe each of the arguments available for use. Each section will have an example of how to add the argument to the arguments array.

labels

The labels argument is an array of strings that represents your post type in the admin. Each string is a bit of text shown for particular function in the admin. By default, non-hierarchical post types will have text with “post” in them and hierarchical post types will have text with “page” in them.

It is particularly important that you make these strings translatable if you’re creating a plugin for public use.

This list is a set of general examples of when each string is used. However, each may be used in multiple places in the admin.

• name: The plural form of the name of your post type.
• singular_name: The singular form of the name of your post type.
• add_new: The menu item for adding a new post.
• add_new_item: The header shown when creating a new post.
• edit: The menu item for editing posts.
• edit_item: The header shown when editing a post.
• new_item: Shown in the favorites menu in the admin header.
• view: Used as text in a link to view the post.
• view_item: Shown alongside the permalink on the edit post screen.
• search_items: Button text for the search box on the edit posts screen.
• not_found: Text to display when no posts are found through search in the admin.
• not_found_in_trash: Text to display when no posts are in the trash.
• parent: Used as a label for a parent post on the edit posts screen. Only useful for hierarchical post types.

'labels' => array(
	'name' => __( 'Super Dupers' ),
	'singular_name' => __( 'Super Duper' ),
	'add_new' => __( 'Add New' ),
	'add_new_item' => __( 'Add New Super Duper' ),
	'edit' => __( 'Edit' ),
	'edit_item' => __( 'Edit Super Duper' ),
	'new_item' => __( 'New Super Duper' ),
	'view' => __( 'View Super Duper' ),
	'view_item' => __( 'View Super Duper' ),
	'search_items' => __( 'Search Super Dupers' ),
	'not_found' => __( 'No super dupers found' ),
	'not_found_in_trash' => __( 'No super dupers found in Trash' ),
	'parent' => __( 'Parent Super Duper' ),
),

description

The description argument allows you to write a text string of your post type. Thus far, I haven’t seen this used anywhere in the WordPress admin, but I’m sure custom post type plugins could take advantage of this.

'description' => __( 'A super duper is a type of content that is the most wonderful content in the world. There are no alternatives that match how insanely creative and beautiful it is.' ),

public

The public argument is a kind of catchall argument for several other arguments and defaults to false. Depending on whether it’s set to true or false, it’ll automatically decide what other arguments should be unless they’re specifically defined. If you’re looking for finer control over the public arguments, there are three specific arguments you may set:

• show_ui: Whether to show the administration screens.
• publicly_queryable: Whether queries for this post type can be performed from the front end.
• exclude_from_search: Whether the posts should appear in search results.

'public' => true,
'show_ui' => true,
'publicly_queryable' => true,
'exclude_from_search' => false,

menu_position

By default, a new post type is added after the Comments menu item in the admin. But, you have to ability to move it to a position more suitable for you. Default WordPress menu items are set apart by integrals of 5. For example, using 20 will add your menu item after Pages.

'menu_position' => 20,

menu_icon

New post types will default to the Posts menu icon, but if you want to mix it up a bit or give your post type some separation from other elements, you can define a custom icon. You only have to input a a custom URL to an image file.

'menu_icon' => get_stylesheet_directory_uri() . '/images/super-duper.png',

hierarchical

The hierarchical argument allows you to choose whether you want your post type to be hierarchical. It defaults to false. If you set it to true, your posts will behave like pages in WordPress.

'hierarchical' => true,

query_var

The query_var argument allows you to control the query variable used to get posts of this type. For example, you could use it with the query_posts() function or WP_Query class. This will default to the name of your taxonomy.

'query_var' => true,

capability_type / capabilities

The capability_type argument is another catchall argument for several more specific arguments and defaults to post. It allows you to define a custom set of capabilities, which are permissions to edit, create, and read your custom post type. If you’re unfamiliar with capabilities, I highly recommend reading my guide on users, roles, and capabilities.

If you just want to keep the same permissions you have with blog posts, leave this at the default. Otherwise, you can either set capability_type to something custom or define each specific capability in the capabilities array.

• edit_post: Whether someone can create and edit a specific post of this post type.
• edit_posts: Capability that allows editing posts of this post type.
• edit_others_posts: Capability that allows editing of others posts.
• publish_posts: Capability to grant publishing of these types of posts.
• read_post: Capability that controls reading of a specific post of this post type.
• read_private_posts: Capability to allow reading of private posts.
• delete_post: Capability that grants the privelege of deleting posts.

For most people that need control over these things, it’s easier to just change capability_type to something like super_duper. WordPress will automatically switch the other caps to follow this pattern. For example, the edit_post capability would become edit_super_duper.

Of course, capability control means nothing without being able to choose who has the capabilities. That’s what my Members plugin was created for. It’s ideal for this scenario.

/* Global control over capabilities. */
'capability_type' => 'super_duper',

/* Specific control over capabilities. */
'capabilities' => array(
	'edit_post' => 'edit_super_duper',
	'edit_posts' => 'edit_super_dupers',
	'edit_others_posts' => 'edit_others_super_dupers',
	'publish_posts' => 'publish_super_dupers',
	'read_post' => 'read_super_duper',
	'read_private_posts' => 'read_private_super_dupers',
	'delete_post' => 'delete_super_duper',
),

supports

The supports argument allows you to define what meta boxes and other fields will appear on the screen when editing or creating a new post. This defaults to title and editor. There are several available options:

• title: Text input field to create a post title.
• editor: Content input box for writing.
• comments: Ability to turn comments on/off.
• trackbacks: Ability to turn trackbacks and pingbacks on/off.
• revisions: Allows revisions to be made of your post.
• author: Displays a select box for changing the post author.
• excerpt: A textarea for writing a custom excerpt.
• thumbnail: The thumbnail (featured image in 3.0) uploading box.
• custom-fields: Custom fields input area.
• page-attributes: The attributes box shown for pages. This is important for hierarchical post types, so you can select the parent post.

'supports' => array( 'title', 'editor', 'excerpt', 'custom-fields', 'thumbnail' ),

rewrite

The rewrite argument allows you to define the permalink structure of your posts when viewing the single post. For example, you may want to have a structure like yoursite.com/cool/post-name. WordPress will set up a default structure based on your taxonomy name. The rewrite argument can be set to true, false, or an array of values. It takes two arguments:

• slug: The slug you’d like to prefix your posts with.
• with_front: Whether your post type should use the front base from your permalink settings (for example, if you prefixed your structure with /blog or /archives).

'rewrite' => array( 'slug' => 'cool', 'with_front' => false ),

taxonomies

If you have some preexisting taxonomies, you can allow posts of this type to also use those taxonomies. You just have to set an array of taxonomy names that you’d like for it to use. WordPress will handle all the administration features for you.

Note that I’ll be covering the integration of post types and taxonomies in more depth in a future tutorial.

'taxonomies' => array( 'post_tag', 'category '),

can_export

You can use the can_export argument to decide whether posts of your post type can be exportable via the WordPress export tool. By default, this is set to true.

'can_export' => true,

register_meta_box_cb

This feature will likely only be useful to developers. You can create a custom callback function that is called when the meta boxes for the post form are set up.

'register_meta_box_cb' => 'your_callback_function_name',

permalink_epmask

I won’t pretend to know much about permalink endpoint masks. I just know you can define a custom one for your post type. Most of you won’t need this. For the purposes of this tutorial, I’ll leave this at the default.

'permalink_epmask' => EP_PERMALINK,

Viewing a custom post type

WordPress will show the singular view of your custom post types without any extra work. Once you create a new post, you’ll be able to view it by clicking on the View Post link.

If your WordPress theme has a single.php template, this will be used to display your custom post type. If not, it will fall back to the index.php template. Since this is a “custom” post type, I’ll assume you want to customize how it’s output. To overwrite the default, you can create a custom template. Our template will be called single-super_duper.php.

You can go as crazy as you like with this template. All of the standard WordPress template tags will work just fine here as well. I could give you endless pages of examples of how to customize this, but I won’t. I’d rather allow you to get creative on your own.

If you’re using a smart theme like Hybrid, this template will be super_duper.php. Hybrid has long supported custom post types and uses a different template hierarchy, which is detailed in its tutorials. WordPress 3.0 will be a fun time to use this theme because of the ultimate control it gives you over templates like this.

Showing multiple posts from our custom post type

Let’s suppose I wanted to show the 10 latest “super dupers” I’ve published. We’ll use the standard WordPress loop for this and customize it however we like. Here’s a basic example:

<?php $loop = new WP_Query( array( 'post_type' => 'super_duper', 'posts_per_page' => 10 ) ); ?>

<?php while ( $loop->have_posts() ) : $loop->the_post(); ?>

	<?php the_title( '<h2 class="entry-title"><a href="' . get_permalink() . '" title="' . the_title_attribute( 'echo=0' ) . '" rel="bookmark">', '</a></h2>' ); ?>

	<div class="entry-content">
		<?php the_content(); ?>
	</div>
<?php endwhile; ?>

Obviously, this is an extremely simple example. Understanding what you can do with the loop is outside the scope of this tutorial. The most important part is giving the post_type argument the name of our post type.

Getting the post type of a post

An old, yet useful, function in WordPress is get_post_type(). It allows you to check the current (if no post object or ID input) or a specific post’s post type. It will return the name of the post type for the post as a string.

$post_type = get_post_type( $post_id );

Checking if a post type exists

WordPress 3.0 will introduce a conditional tag called is_post_type() whose purpose is twofold. Its first purpose is to check whether a post type or types exist. In order to use it, you can input a custom post type name or array of names into the function call.

if ( is_post_type( 'super-duper' ) )
	echo 'Super Dupers are working!';
else
	echo 'Super Dupers are not working!';

Checking if a post is of specified post type

The second purpose of the is_post_type() function allows you to check a specific post against a specific post type(s). Let’s assume we want to check if one of our posts has the super_duper post type.

if ( is_post_type( 'super_duper', $post_id ) )
	echo 'This is a not a blog post.  It is a super duper!';
else
	echo 'This is not a super duper. [insert sad face]';

Checking if a post type is hierarchical

You may want to treat hierarchical post types differently than other post types. To figure out if a post type is hierarchical, you can use the is_post_type_hierarchical() conditional tag. It will take in a post type name, post ID, or post object as its single parameter.

For example, let’s check if our super duper post type is hierarchical:

if ( is_post_type_hierarchical( 'super_duper' ) )
	'Super Dupers should not be hierarchical!';
else
	'Super Dupers are definitely not hierarchical! We stick it to the man!';

Getting a post type object

In some scenarios, you may want to get the arguments (all those things we went over earlier) for a specific post type. It is extremely important for plugin/theme authors to respect these arguments when creating plugins/themes that interact with custom post types.

Let’s suppose we want to call a specific function if the super duper post type has set show_ui to true.

$post_type = get_post_type_object( 'super_duper' );

if ( $post_type->show_ui )
	custom_function_name();

Adding and removing support for post type features

The add_post_type_supprt() function is no different than using the supports argument when first creating your post type. This is likely more useful if you’re using a plugin/theme that has defined a custom post type.

So, let’s suppose you’re using a plugin that creates a new post type for you. Your post type doesn’t have support for thumbnails, but you think this feature would work well on your site.

add_post_type_support( 'post_type', 'thumbnail' );

The opposite of this function is remove_post_type_support(). So, let’s further suppose that your plugin author added support for excerpts, but you don’t want to use this feature.

remove_post_type_support( 'post_type', 'excerpt' );

Checking if a post type supports a specific feature

As a plugin/theme author, this will likely be useful. You wouldn’t want to try and display stuff that doesn’t exist for a custom post type. For example, your theme may wrap post content with a <div> or something of that sort. This is fairly common. But, you may want to remove it if the post type doesn’t have written content.

<?php if ( post_type_supports( 'super_duper', 'editor' ) ) { ?>

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

<?php } ?>

Be careful with this though. A post type may have other means of defining something like the content, and this should only be taken as an example of how to use the post_type_supports() function.

Getting registered post types for use in PHP

As a plugin/theme developer, you may need to get all the registered post types for use in a function of your plugin/theme. You’d use the get_post_types() function for this.

In the below example, I’ll output a list of post types by singular label that are shown in search results.

<?php $types = get_post_types( array( 'exclude_from_search' => false ), 'objects' ); ?>

<ul>
	<?php foreach ( $types as $type )
		echo '<li>' . $type->singular_label . '</li>';
	?>
</ul>

Help! I’m getting a 404!

If you’re getting a 404 message when trying to view a post, don’t worry. This is supposed to happen when setting up new post types. The easiest way to fix this is to simply visit your Settings > Permalinks page. You don’t have to save your permalinks but just visit the page. This will flush your rewrite rules.

If you’re a plugin author, you can save yourself some support questions by flushing the rewrite rules on activation of your plugin.

Is this a theme or plugin feature?

I’ve had a hard time trying to decide which to call it, and have ultimately decided that it’s both. It’s a marriage of the two because both need to be in sync to fully enjoy the benefits of custom post types.

More than likely, you’ll see post types registerd from within a plugin. But, they have to be displayed by your theme. If you’re creating this all yourself, you can simply drop it all in your theme.

If you’re a theme author, you should be aware that plugins may add new post types. Do yourself and your users a favor by not assuming too much. Keep your code flexible enough to give a default view for custom post types and easy enough to handle when creating custom templates for those post types.

The tip of the iceberg

I haven’t even scratched the surface of what’s possible with custom post types. Even the new navigation menus feature of WordPress 3.0 will be built with them. While I know some people in the community don’t agree with this decision, I wanted to point it out because it’s a unique example of what’s possible.

Of my list of about 1,000 things I wanted to share in this tutorial, I might have covered about 20 of them. Given enough free time, I could write a book on using custom post types. Some stuff should be left open to exploration though, and I encourage you to try everything I’ve written about and move beyond this tutorial to creating something unique for your site.