How to Create Template File for Parent Page of Custom Post Type

Question

After creating a custom post type I made a custom template file for the post (single-customposttypename.php). So the URL structure would be: example.com/page/postname, and postname would be the post that renders single-custompostype.php (this works fine).

But what I'm trying to get is example.com/PAGE to loop all the posts generated from that custom post type on one page...which it does, but it's unstyled. I tried creating a custom template called page-customposttypename.php but that didn't seem to work.

Seems like this should be really simple but I can't seem to figure it out. Can anyone point me in the right direction?

Answer 1

There are two different ways to implement what you want to do, and both are perfectly valid, depending on your needs:

1. Post-type archive index page
2. Custom page template

Post-type archive index page

This implementation uses the WordPress template hierarchy to output the archive index page for your custom post type. For custom post type archive index pages, the template hierarchy is:

1. archive-{posttype}.php
2. archive.php
3. index.php

So, if you want a custom layout/markup for the archive index page for your custom post type, create archive-{posttype}.php.

The advantage with this implementation is that you don't have to make any changes to the default query. You simply output a normal loop, and have all normal $post variables, conditionals, and tags available to you, out-of-the-box.

To view the archive index page for your custom post type, if you have pretty permalinks enabled, use: home_url() . '/{posttype}/, e.g. www.example.com/{posttype}/.

Custom Page Template

This implementation uses WordPress custom page templates to output a custom-query loop of posts for your custom post type.

This implementation will allow you to display your custom post types on a specific page, e.g. www.example.com/pagename, but has several drawbacks:

1. It is more difficult to implement.

   Where archive-{posttype}.php is used/displayed automatically by WordPress, to use a custom page template, you have to create a static page, then assign your custom page template to the page, then publish the page.

2. It is more difficult to develop.

   Unlike archive-{posttype}.php, a custom query loop in a custom page template does not use the default query, and does not have all of the normal $post variables, conditionals, and tags available.

   You will have to define a secondary query, via WP_Query()

   You will have to use a custom loop-instantiation markup.

   You will have to use a workaround if you want to use pagination.

That said, here is a quick-and-dirty custom page template:

/**
 * Template name: Custom Post Type Display
 */

get_header();

$cpt_query_args = array(
    'post_type' => 'foobar',
    'posts_per_page' => '10'
)
$cpt_query = new WP_Query( $cpt_query_args );

if ( $cpt_query->have_posts() ) : while ( $cpt_query->have_posts() ) : $cpt_query->the_post();
    // Loop output here
    // You CAN use normal post tags here,
    // such as the_title(), the_content(), etc.
endwhile; endif;

// Reset postdata
wp_reset_postdata();

get_footer();

(For more detailed answers about using custom page templates to display custom loop queries, and especially for custom query loop pagination, just search WPSE for related questions/answers.)

Answer 2

From the codex: If the custom post type were 'product', WordPress would look for archive-product.php to display the archive of posts.