How to Use WordPress 3.0 Custom Post Types in Thesis

The custom post type addition in WordPress 3.0 truly pushes WordPress towards a complete CMS. With plenty of modifications to our custom_functions.php file, Thesis can take full advantage of the custom post types that WordPress offers in 3.0.

I will go ahead and forewarn you that I am in no way an expert at PHP. I know just enough to be dangerous (to myself and others). With that being said, making practical use of custom post types in Thesis does require a lot of tedious PHP work. You have been warned.
Now that I have cleared myself of all potential fault (probably not), let’s get cracking with our code. This post is long-winded, so grab a cup of coffee and some reading glasses. Here we go…

Giving Credit to Whom It Is Due

Before I can even begin to explain how this works, I need to give credit where credit is due. What I have done below is simply compiled lots of scattered information from different places and modified it to become a working example for Thesis. I encourage you to view each of these posts as they contain valuable, in-depth information related to custom post types.

• Justin Tadlock for his epic post on custom post types (this is a must read if you want to really learn about custom post types)
• Kristarella for adapting the custom post types code to Thesis (also a must read!)
• Chris Creed for his inspiration to make a portfolio using custom post types (I’ve adapted it to work for my own site)
• Berchman for his tutorial on custom templates for Thesis (love, love, love)
• Greg Rickaby for his tutorial on sub-loops in Thesis (the crux of making custom post types work in Thesis)
• Dave Wilkinson for telling me that I should make a post like this

I hope I haven’t left anybody out. If I have, let me know in the comments and I’ll be sure to add you in!

What is a Custom Post Type?

Custom post types are very simple to understand. They are simply a way to for you to handle and control information in the same way that you would, for example, a regular blog post. They have a specific function for your blog and/or website.

In the tutorial today, we will be creating a simple custom post type that displays a portfolio of client websites. This can easily be modified to fit your desired needs, such as a product category or a movie review category. If possible, I encourage to title your page the same as your custom post type. This helps keep continuity and order throughout the entire process of creating a custom post type. Let’s get started, shall we?

Creating A Page to House Our Custom Post Type

The first thing we need to do is to create a page that will be used specifically for our custom post type. In my case, I created a page and titled it ‘Folio’. You can title your page to whatever you choose.

Creating Our Custom Post Type

The second thing we need to do is actually create our custom post type. This requires that we add some code to our custom_functions.php file. Go ahead and open up your custom_functions.php file in your favorite text editor and paste the following code (I’ll explain what it means below):

 /* BEGIN Custom Post Type 'Folio' */
 function create_folio() {
 $folio_args = array(
 'label' => __('Folio'),
 'singular_label' => __('Folio'),
 'public' => true,
 'show_ui' => true,
 'capability_type' => 'post',
 'hierarchical' => false,
 'taxonomies' => array('post_tag', 'category'),
 'rewrite' => array( 'slug' => 'folio', 'with_front' => false ),
 'supports' => array('title', 'editor', 'thumbnail', 'custom-fields', 'comments', 'trackbacks', 'author')
 );
 register_post_type('folio', $folio_args);
 }
 add_action('init', 'create_folio');
 /* END Custom Post Type 'Folio' */

Basically we are creating a function called ‘create_folio’ and listing a slew of arguments for that function. I’ve labeled it ‘Folio’ because I’m using it for my own portfolio. This label will show up throughout your admin panel, so label it according to what kind of custom post type you are creating.

If you have custom taxonomies, you can add (or subtract) from those that I have listed.

The ‘rewrite’ argument allows you to make custom permalinks for your specific post type. For example, adding this above code to our custom post type allows all posts to have a permalink structure like this: yourwebsite.com/folio/the-rest-of-your-link. You should change the slug name (in this case it is ‘folio’) to match the title of your page. You will want to keep the ‘with_front’ argument false, unless you would like your custom post type URLs to be prefixed with your custom permalink structure that you altered in your Settings. If you remove this argument, you will have a permalink structure that looks something like this: yourwebsite.com/blog/folio/the-rest-of-your-link (‘blog’ could be ‘archives’ or your post date or whatever you set it to).

*Note that I rewrote my link to reflect the page that I created for my custom post type. I suggest you do the same to keep continuity throughout your site.*

The ‘supports’ argument tells WordPress what it should show on the Edit Post page. For our tutorial, I’ve included most of the standard arguments that you would see when you make regular posts. You could add other support arguments if you would like, such as ‘revisions’ and ‘page-attributes’.

Within the register_post_type line, the first variable is what you would like your custom post type to be referred to, and the second variable defines the arguments for that specific custom post type.

Now save your custom_functions.php file and scroll to the top of your screen. You should see an admin label to your left entitled ‘Folio’ (or whatever you decided to call it) like the one to the left. Congrats! You’ve just created your first custom post type! Now let’s get to making it work. But wait…

Getting Thesis SEO Boxes to Work with Custom Post Types

You will notice that if you click on the “Add New” option in your new Folio menu, the format will look nearly the same as the Post format. But you are missing one crucial element: your Thesis SEO and meta boxes!

Thesis 1.8 (the version I am using) apparently does not add SEO and meta boxes to custom post types by default, but we can add some code into our custom_functions.php file in order to get them to appear.

*Special thanks to Dimas for this bit of code*

 /* BEGIN Adding Thesis Meta Boxes to 'Folio' */
 add_action('admin_menu','my_admin_menu');
 function my_admin_menu() {
 $post_options = new thesis_post_options;
 $post_options->meta_boxes();
 foreach ($post_options->meta_boxes as $meta_name => $meta_box)
 {
 add_meta_box($meta_box['id'], $meta_box['title'], array('thesis_post_options', 'output_' . $meta_name . '_box'), 'folio', 'normal', 'high'); #wp
 }
 add_action('save_post', array('thesis_post_options', 'save_meta')); #wp
 }
 /* END Adding Thesis Meta Boxes to 'Folio' */

Now save your custom_functions.php file and go add a new post to your custom post type. You will notice that the Thesis SEO and meta boxes are now present! We can continue forward with our tutorial.

Custom Titles for Your Custom Post Type Admin Panel

Now that we have created our custom post type, we need to label it in our admin area. Paste the following code into your custom_functions.php file:

/* BEGIN Custom Columns for 'Folio' */
 function folio_edit_columns($folio_columns){
 $folio_columns = array(
 "cb" => "<input type="checkbox" />",
 "title" => "Project Title",
 "description" => "Description",
 );
 return $folio_columns;
 }
 function folio_columns_display($folio_columns){
 switch ($folio_columns)
 {
 case "description":
 the_excerpt();
 break;
 }
 }
 add_filter('manage_edit-folio_columns', 'folio_edit_columns');
 add_action('manage_posts_custom_column', 'folio_columns_display');
 /* END Custom Columns for 'Folio' */

Basically this code allow us to define our columns in our custom post type admin menu. In this case, we have created the labels “Project Title” and “Description”. You may change the titles to whatever you wish. Within the “Description” column, we have told WordPress to present an excerpt of a specific custom post.

Now save your custom_functions.php file and go create a test post within your new custom post type area (we need to do this to see the edit we just made). After you have created and published this test post type, go back to the main admin menu for the custom post type and notice the column titles and descriptions.

Getting the Custom Post Type to Appear on Our Site

*Update*

Thanks to some help and tips from Kristarella, I’ve updated this post to include the option of using the Thesis Custom Loop API for your custom post type. It will be listed under Option #2.

Option #1: Using the Normal WordPress Loop Query

Up until now, we have done nothing but back-end groundwork in order to prepare our custom post type for our site. Now we get to actually build our loop query and custom page template in order to display our custom post type.

Once again, we are going to need to edit our custom_functions.php file in order to make this thing come to life. Copy and paste this code into your custom_functions.php file, and then we will discuss it below.

 /* BEGIN 'Folio' Post Queries */
 function custom_page_type_folio() {
 if (is_page('156', 'Folio')) { ?>
 <?php
 $loop = new WP_Query(array('post_type' => 'folio', 'posts_per_page' => 5));
 ?>
 <div id="sidebars">
 <?php thesis_build_sidebars(); ?>
 </div>
 <?php while ( $loop->have_posts() ) : $loop->the_post(); ?>
 <div id="content" class="hfeed">
 <div class="post_box top">
 <div class="headline_area">
 <h2 class="entry-title"><a href="<?php the_permalink() ?>" rel="bookmark" title="<?php _e('Permanent link to'); ?>"><?php the_title(); ?></a></h2>
 </div>
 <div class="format_text entry-content">
 <?php $post_image = thesis_post_image_info('image'); ?>
 <a href="<?php the_permalink() ?>"><?php echo $post_image['output']; ?></a>
 <?php the_excerpt(); ?>
 </div>
 </div>
 </div>
 <?php endwhile; ?>
 <?php }
 }
 remove_action('thesis_hook_custom_template', 'thesis_custom_template_sample');
 add_action('thesis_hook_custom_template', 'custom_page_type_folio');
 /* END 'Folio' Post Queries */1
 Let's begin to break down this bit of code.

In this code, we are creating a function that utilizes a custom loop and page template that we specify within the function. We also use a conditional tag in order to target our specific page that we created for our custom post type.
<div class="alert">In the line <code>if (is_page('156', 'Folio'))</code>, you need to replace the number with your specific page number and the word with the Title of your page. In order to learn the custom ID number for your page, go to Pages > Edit (your specific page) > Look at the right section of the URL in your address bar. You page number is right after the <code>post=</code> part of the URL.</div>
The next part of the code creates our custom loop that will query posts from our specific custom post type. Once again, it you have chosen to name your custom post type something other than 'folio', you need to change it here. You can also alter the variable number at the end to change the number of posts that WordPress will display the page.
1 <div id="sidebars">
 <?php thesis_build_sidebars(); ?>
 </div>

This tells WordPress to build any sidebars that we have in our normal layout. If you don’t have any sidebars in your layout OR you would like to leave out sidebars for this page, you can simply take out this piece of code.

 have_posts() ) : $loop->the_post(); ?>

This sets up our loop to query posts from our custom post type.

Now, the next section of code is formulated to act just like your normal blog feed would. You can change this to whatever you would like and style it however you would like. Simply create your own specific HTML structure and style it accordingly in your custom.css file. Mine is structured so that it has a title, calls WordPress to use the Post Image that is set in the Thesis meta box, and uses the_excerpt to show part of my custom post to my readers. Like I said before, this is where you can style and make it happen for your custom post type.

Once you have styled your new custom post type according to your liking, be sure to save your custom_functions.php file.

Check out the before and after images below:

Before adding the loop:

After adding the loop:

Option #2: Using the Thesis Custom Loop API

If you are using Thesis 1.8 (which I highly encourage that you upgrade to 1.8 for its features and benefits), you have the ability to take advantage of the new custom loop that Thesis offers. This makes loop-making much more simple because Thesis 1.8 has built-in loop functions ready to go. With one simple call, your loop is instantiated and running on all cylinders.

If you opt to use the custom loops provided by Thesis, paste the following code into your custom_functions.php file:

 /* BEGIN 'Folio' Post Queries */
 function custom_page_type_folio() {
 if (is_page('156', 'Folio')) { ?>
 <div id="sidebars">
 <?php thesis_build_sidebars(); ?>
 </div>
 <div id="content" class="hfeed">
 <?php
 query_posts(array('post_type' => 'folio', 'posts_per_page' => 5));
 thesis_loop::home();
 ?>
 </div>
 <?php }
 }
 remove_action('thesis_hook_custom_template', 'thesis_custom_template_sample');
 add_action('thesis_hook_custom_template', 'custom_page_type_folio');
 /* END 'Folio' Post Queries */

Let’s examine what’s happening in this little bit of code.

We begin this bit of code the same way that we would for our normal WordPress loop query, but if you will notice, using the Custom Loop API does not require us to build a new loop to query. Since Thesis already has the loop built into its framework, all we need to do is run a query_posts() call in order to grab our custom post type (which is in this case our ‘folio’ post type) and then tell Thesis to run the loop.

thesis_loop::home(); – here is where we call the specific loop that we would like Thesis to use. By default, Thesis has numerous types of loops that we can run. To see a full list of the loops, please visit the Custom Loop API page. In order to keep in line with this post, I decided to use the thesis_loop::home(); call. This will query and display our ‘folio’ posts exactly like our regular posts page. For instance, if you have it set in your Thesis options menu to display 2 featured posts and the rest teasers for your normal posts, the same thing will occur when using the thesis_loop::home(); for your ‘folio’ posts! Pretty awesome, right?!

Regular Home Page:

Custom Post Type Page Using thesis_loop::home();:

In this sense, using the Thesis Custom Loop API gives you more control over exactly how your custom post types are displayed because of the number of loops you can choose from.

And there you have it, folks! You’ve just created your own custom post type using Thesis! For a live example of this, you can view my own Portfolio page.

Optional Styling of WordPress Excerpts

If you looked at my portfolio page, you will notice that my excerpts are styled. I also wanted to make the ellipses hyperlink to the post. I also wanted to remove the Tweet button from my Portfolio page so that it only displays on my Posts page. Here is the code I added to my custom_functions.php file:

 /* BEGIN Custom Excerpt for 'Folio' Page */
 function improved_trim_excerpt($text) {
 global $folio, $post;
 if ( '' == $text ) {
 $text = get_the_content('');
 $text = apply_filters('the_content', $text);
 $text = preg_replace('@<script[^>]*?>.*?</script>@si', '', $text);
 $text = preg_replace('|[(.+?)](.+?[/\1])?|s', '', $text);
 $text = strip_tags($text, '<p>, <div>, <a>, <strong>');
 $excerpt_length = 80;
 $words = explode(' ', $text, $excerpt_length + 1);
 if (count($words)> $excerpt_length) {
 array_pop($words);
 array_push($words, '[...]');
 $text = implode(' ', $words);
 }
 }
 return $text;
 }
 remove_filter('get_the_excerpt', 'wp_trim_excerpt');
 add_filter('get_the_excerpt', 'improved_trim_excerpt');
 /* END Custom Excerpt for 'Folio' Page */

/* BEGIN Adding Hyperlink to Excerpt */
 function excerpt_hyperlink($text) {
 return str_replace('[...]', '<a href="'. get_permalink($post->ID) . '">' . '[&hellip;]' . '</a>', $text);
 }
 add_filter('the_excerpt', 'excerpt_hyperlink');
 /* END Adding Hyperlink to Excerpt */

In order to have my excerpts retain the original styling of the post, I added a few exceptions to the strip_tags argument, as noted above.

I also wanted to lengthen my exceprts. I have set my excerpt length to be 80 words. The default WordPress excerpt length is 55 words.

I also ran into the issue with my Tweet button wanting to show up on my individual portfolio items. That doesn’t look professional to me, so I wanted to change that. I chose the option “use shortcode” for my Topsy retweet button. This allows me to manually add the Tweet button to my posts. This caused the shortcode to appear in my excerpts, so I had to add this line into the above function:

 $text = preg_replace('|[(.+?)](.+?[/\1])?|s', '', $text);

This removes shortcode from excerpts.

I also wanted to make my ellipses hyperlink to my posts, so I added in the second function in order to make that happen.

Final Thoughts

Phew…I am exhausted from putting together this tutorial. I hope you have found it beneficial and useful. It took me a full Saturday to figure out how all this worked together, but I believe it is a sound solution for custom post types in Thesis.

Like I said before, I only know enough PHP to be dangerous. I am not an expert by any means, and there are probably some faults in my coding. If you notice anything that doesn’t look quite right, be sure to let me know so that I can change it.

I will do my best to answer any of your questions you may have related to making your own custom post types in Thesis. I’m sure some will be over my head, so I’m hoping the Thesis community will pitch in where I need help.

Thanks again for reading! If you don’t already own Thesis, why don’t you buy a copy today!