An Important Update: WordPress 3.0 Post Types And Taxonomies

I remember posting about this important update that was made to the way custom post types and custom taxonomies could and should be created in order to properly set them up for full customization. I wrote about it the day after the update was pushed to the WordPress SVN in one of the beta versions.

I don't think this change got enough exposure. At the very least I didn't expect to be the only one to explain it as I did here as the only other article explaining it besides what the Codex says on it. Because of this and Antonio mentioning to me yesterday after he noticed that out of all his bookmarks for post types, no one has explained this, I decided to post a complete how-to, in setting up custom post types and taxonomies the RIGHT way. If I had known this would've been so highly overlooked down the line, I would've written a post like this instead of the less in-depth explanation I did when the change was first made.

Quick Jump Menu:

• Custom Post Types Done Right
• Working With Post Types: Functions You Should Know

• Custom Taxonomies The Right Way
• Working With Taxonomies: More Useful Functions For You!

Use the links listed above to jump down to the part of this post you're interested in.

Using Labels For Post Types

The use of labels for custom post types and taxonomies is important for the fact that it helps differentiate your custom stuff from the other things in WordPress that already exist. When you go to add a new post, page, category or tag, at the top of the page it says Add New _Thing_, depending on what it is your adding. If you don't use labels to change this to read whatever the custom thing you create is, then it will default to Post for post types, and Category or Tags for taxonomies that are either hierarchical or not, respectively.

Here's what you see without using labels:

This is collage of different places post type labels are used in the dashboard, like when you add new, search or edit posts, tags categories, etc. It's also what you will see if you create custom post types or taxonomies the way everyone else has said to create them besides me, without the use of labels.

Setting up labels to show the custom post type

As I mentioned in my first post on labels, the WordPress Codex has documented this as well, if you hadn't noticed. Here's a quick review using the example they provide.

// The register_post_type() function is not to be used before the 'init'.
add_action( 'init', 'my_custom_init' );

/* Here's how to create your customized labels */
function my_custom_init() {
	$labels = array(
		'name' => _x( 'Books', 'post type general name' ), // Tip: _x('') is used for localization
		'singular_name' => _x( 'Book', 'post type singular name' ),
		'add_new' => _x( 'Add New', 'book' ),
		'add_new_item' => __( 'Add New Book' ),
		'edit_item' => __( 'Edit Book' ),
		'new_item' => __( 'New Book' ),
		'view_item' => __( 'View Book' ),
		'search_items' => __( 'Search Books' ),
		'not_found' =>  __( 'No books found' ),
		'not_found_in_trash' => __( 'No books found in Trash' ), 
		'parent_item_colon' => ''
	);
	
	// Create an array for the $args
	$args = array( 'labels' => $labels, /* NOTICE: the $labels variable is used here... */
		'public' => true,
		'publicly_queryable' => true,
		'show_ui' => true, 
		'query_var' => true,
		'rewrite' => true,
		'capability_type' => 'post',
		'hierarchical' => false,
		'menu_position' => null,
		'supports' => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' )
	); 

	register_post_type( 'book', $args ); /* Register it and move on */
}

It is obviously more coding this way compared to every other article you've probably read on this, but it is how you can make your post types more custom, since they are custom post types after all. It only takes 2 seconds more to do this anyways.

Now you will see the correct post type as shown here.

You get the idea I hope now, right? See how much better that looks, to you, your clients, or any other users of the site who will see the complete customization of your post types. They will think you are some kind of god, or something....

Additional Post Type Functions You Should Know About

The following are functions you can use for various things related to post types. The function name is linked to the line in /wp-includes/post.php where it is created for those that would like to check out the source code which makes them work. I've also added a short description for each that is used in the source to describe them.

Post Type Functions:

• post_type_exists() - Checks if a post type is registered.

• is_post_type_hierarchical( $post_type ) - Whether the post type is hierarchical. A false return value might also mean that the post type does not exist.

• get_post_type( $post ) - Retrieve the post type of the current post or of a given post.

• get_post_type_object( $post_type ) - Retrieve a post type object by name.

• get_post_types( $post ) - Get a list of all registered post type objects.
  • $args - An array of key => value arguments to match against the post type objects.
  • $output - The type of output to return, either post type 'names' or 'objects'. 'names' is the default.
  • $operator - The logical operation to perform. 'or' means only one element from the array needs to match; 'and' means all elements must match. The default is 'and'.
  • Returns an array listing post type names or objects.

• register_post_type() - Register a post type. Do not use before init.
  • A simple function for creating or modifying a post type based on the parameters given.
  • The function will accept an array (second optional parameter), along with a string for the post type name.

• get_post_type_capabilities() - Builds an object with all post type capabilities out of a post type object.
• Accepted keys of the capabilities array in the post type object:
  • edit_post - The meta capability that controls editing a particular object of this post type. Defaults to "edit_ . $capability_type" (edit_post).
  • edit_posts - The capability that controls editing objects of this post type as a class. Defaults to "edit_ . $capability_type . s" (edit_posts).
  • edit_others_posts - The capability that controls editing objects of this post type that are owned by other users. Defaults to "edit_others_ . $capability_type . s" (edit_others_posts).
  • publish_posts - The capability that controls publishing objects of this post type. Defaults to "publish_ . $capability_type . s" (publish_posts).
  • read_post - The meta capability that controls reading a particular object of this post type. Defaults to "read_ . $capability_type" (read_post).
  • read_private_posts - The capability that controls reading private posts. Defaults to "read_private . $capability_type . s" (read_private_posts).
  • delete_post - The meta capability that controls deleting a particular object of this post type. Defaults to "delete_ . $capability_type" (delete_post).

• get_post_type_labels( $post_type_object ) - Builds an object with all post type labels out of a post type object.
• Accepted keys of the label array in the post type object:
  • name - general name for the post type, usually plural. The same and overriden by $post_type_object->label. Default is Posts/Pages
  • singular_name - name for one object of this post type. Default is Post/Page
  • add_new - Default is Add New for both hierarchical and non-hierarchical types.
  • add_new_item - Default is Add New Post/Add New Page
  • edit_item - Default is Edit Post/Edit Page
  • new_item - Default is New Post/New Page
  • view_item - Default is View Post/View Page
  • search_items - Default is Search Posts/Search Pages
  • not_found - Default is No posts found/No pages found
  • not_found_in_trash - Default is No posts found in Trash/No pages found in Trash
  • parent_item_colon - This string isn't used on non-hierarchical types. (In hierarchical ones the default is Parent Page)

• _get_custom_object_labels() - Builds an object with custom-something object (post type, taxonomy) labels out of a custom-something object

• add_post_type_support( $post_type, $feature ) - Register support of certain features for a post type.
• All features are directly associated with a functional area of the edit screen, such as the editor or a meta box:
  • 'title',
  • 'editor',
  • 'comments',
  • 'revisions',
  • 'trackbacks'
  • 'author',
  • 'excerpt',
  • 'page-attributes',
  • 'thumbnail',
  • 'custom-fields'

  Additionally, the 'revisions' feature dictates whether the post type will store revisions, and the 'comments' feature dicates whether the comments count will show on the edit screen.

• remove_post_type_support( $post_type ) - Remove support for a feature from a post type.

• post_type_supports( $post_type, $feature ) - Checks a post type's support for a given feature.

• set_post_type( $post_id = 0, $post_type = 'post' ) - Updates the post type for the post ID.
  • $post_id Post ID to change post type. Not actually optional.
  • $post_type Optional, default is post. Supported values are 'post' or 'page' to name a few.
  • Return int Amount of rows changed. Should be 1 for success and 0 for failure.

• get_posts() - Retrieve list of latest posts or posts matching criteria.
• The defaults are:
• 'numberposts' - Default is 5. Total number of posts to retrieve.
• 'offset' - Default is 0. See { WP_Query::query() } for more.
• 'category' - What category to pull the posts from.
• 'orderby' - Default is 'post_date'. How to order the posts.
• 'order' - Default is 'DESC'. The order to retrieve the posts.
• 'include' - See { WP_Query::query() } for more.
• 'exclude' - See { WP_Query::query() } for more.
• 'meta_key' - See { WP_Query::query() } for more.
• 'meta_value' - See { WP_Query::query() } for more.
• 'post_type' - Default is 'post'. Can be 'page', or 'attachment' to name a few.
• 'post_parent' - The parent of the post or post type.
• 'post_status' - Default is 'published'. Post status to retrieve.

Alternatively to using get_posts(), you should also learn about the difference between WP_Query() and query_posts() for retrieving post information.

I plan to cover get_posts() more in a future post.

Using Labels For Taxonomies

Also mentioned in my previous post was using labels when creating custom taxonomies. This is also documented in the WordPress Codex just so you know. I will cover it a little more in-depth though.

Here's the example used in the Codex:

First snippet is hierarchical. The same thing as WordPress 'category' taxonomy.

// hook into the init action and call create_book_taxonomies() when it fires
add_action( 'init', 'create_book_taxonomies', 0 );

// create two taxonomies, genres and writers for the post type "book"
function create_book_taxonomies() {

	// Add new taxonomy, make it hierarchical (like categories)
	$labels = array(
		'name' => _x( 'Genres', 'taxonomy general name' ),
		'singular_name' => _x( 'Genre', 'taxonomy singular name' ),
		'search_items' =>  __( 'Search Genres' ),
		'all_items' => __( 'All Genres' ),
		'parent_item' => __( 'Parent Genre' ),
		'parent_item_colon' => __( 'Parent Genre:' ),
		'edit_item' => __( 'Edit Genre' ), 
		'update_item' => __( 'Update Genre' ),
		'add_new_item' => __( 'Add New Genre' ),
		'new_item_name' => __( 'New Genre Name' ),
	); 	

	register_taxonomy( 'genre', array( 'book' ), array(
		'hierarchical' => true,
		'labels' => $labels, /* NOTICE: Here is where the $labels variable is used */
		'show_ui' => true,
		'query_var' => true,
		'rewrite' => array( 'slug' => 'genre' ),
	));

The next snippet is for creating non-hierarchical taxonomies such as Tags in WordPress

	// Add new taxonomy, NOT hierarchical (like tags)
	$labels = array(
		'name' => _x( 'Writers', 'taxonomy general name' ),
		'singular_name' => _x( 'Writer', 'taxonomy singular name' ),
		'search_items' =>  __( 'Search Writers' ),
		'popular_items' => __( 'Popular Writers' ),
		'all_items' => __( 'All Writers' ),
		'parent_item' => null,
		'parent_item_colon' => null,
		'edit_item' => __( 'Edit Writer' ), 
		'update_item' => __( 'Update Writer' ),
		'add_new_item' => __( 'Add New Writer' ),
		'new_item_name' => __( 'New Writer Name' ),
		'separate_items_with_commas' => __( 'Separate writers with commas' ),
		'add_or_remove_items' => __( 'Add or remove writers' ),
		'choose_from_most_used' => __( 'Choose from the most used writers' )
	); 
	register_taxonomy( 'writer', 'book', array(
		'hierarchical' => false,
		'labels' => $labels, /* NOTICE: the $labels variable here */
		'show_ui' => true,
		'query_var' => true,
		'rewrite' => array( 'slug' => 'writer' ),
	));
} // End of create_book_taxonomies() function.

You may have noticed that this is very similar to how labels are used for creating post types. That's because they are almost identical! You can choose to do either method, using the $args variable to set up the arguments as shown in the post types snippet, or you can just do it as shown above in the taxonomies snippets. It's up to you, however you want to organize your code.

Here's how taxonomies with labels now looks.

I'm going to assume you get the point and I don't need to take screenshots of how the non-hierarchical taxonomy will look. It's the same deal different word.

Functions For Taxonomies You Should Know About

The following are functions which you can use when working with taxonomies. I'm not going to link to the line of each function or include descriptions of each since the file which contains them is way smaller than posts.php where the post type functions are, so if you're interested in viewing the source of these you should've have a hard time finding the line they are on.

The functions which make up taxonomies are located in /wp-includes/taxonomy.php of the WordPress source.

• get_taxonomies() - Get a list of registered taxonomy objects.
• get_object_taxonomies() - Return all of the taxonomy names that are of $object_type.
• get_taxonomy() - Retrieves the taxonomy object of $taxonomy.
• taxonomy_exists() - Checks that the taxonomy name exists.
• is_taxonomy_hierarchical() - Whether the taxonomy object is hierarchical.
• register_taxonomy - Create or modify a taxonomy object. Do not use before init.
• get_taxonomy_labels() - Builds an object with all taxonomy labels out of a taxonomy object
• register_taxonomy_for_object_type() - Add an already registered taxonomy to an object type.
• get_objects_in_term() - Retrieve object_ids of valid taxonomy and term.
• &get_term() - Get all Term data from database by Term ID.
• get_term_by() - Get all Term data from database by Term field and data.
• get_terms() - Retrieve the terms in a given taxonomy or list of taxonomies.
• is_term() - Returns the index of a defined term, or 0 (false) if the term doesn't exist.
• sanitize_term() - Sanitize Term all fields.
• wp_count_terms() - Count how many terms are in Taxonomy.
• Default $args is 'hide_empty' which can be 'hide_empty=true' or array( 'hide_empty' => true ).
• wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term.
• wp_set_object_terms() - Create Term and Taxonomy Relationships.
• &_get_term_children() - Get the subset of $terms that are descendants of $term_id.
• get_term_link() - Generates a permalink for a taxonomy term archive.
• the_taxonomies() - Display the taxonomies of a post with available options.
• get_the_taxonomies() - Retrieve all taxonomies associated with a post.
• get_post_taxonomies() - Retrieve all taxonomies of a post with just the names.

I don't think I can squeeze anymore about custom post types or taxonomies into this post without copying and pasting the complete source code from the taxonomy.php and post.php files in WordPress. That's just not going to happen, you got enough of the source already I'm sure.

Let me know what you think, and if you have comments...