Using get_template_part() In Your Themes for Better File Organization

Developing WordPress themes take practice… not because it’s difficult, but because you have to find your groove.

I’m willing to bet the first five themes you build all differ in significant ways based on lessons you learn from each development process. That’s perfectly normal.

One of the patterns you’ll start to develop early on is file organization. It doesn’t take long to figure out your preferred file and directory structure.

That’s what this article is all about, WordPress’ awesome get_template_part() function that helps you organize your theme in a clean and extremely efficient manner.

Including and Requiring Files in PHP

WordPress is written mainly in PHP which comes with a host of functions you can use to build software the way you want it.

Two very common functions are include() and require(). In short, these two functions are the same except for the fact that require() produces a fatal error if it fails while include() only produces a warning.

The purpose of these functions is to “include” or “require” another file’s code in the file making the function call. Plain and simple… the function names say it all.

While these functions are great, they’re limited within the scope of WordPress. Considering how WordPress parent themes and child themes are structured, they may fall a little short based on the situation.

That’s where get_template_part() comes in.

Understanding get_template_part()

As discussed above, handling failure may vary from function to function. PHP’s way of handling these errors makes sense. Use the function correctly or it fails. Period.

In WordPress, though, we need a friendlier solution. It’s best that the functions do a little bit of thinking for us in special cases.

That’s how get_template_part() works in place of include() and require().

You tell the function specifically what files to look for. In the event something goes wrong, it goes through a number of steps to “fix” the mistake. In fact, sometimes it’s not even a mistake and get_template_part() is strategically used as a conditional.

Let’s take a look at how get_template_part() behaves in specific situations before we check out a code example.

Parent Themes and Child Themesget_template_part() understands the relationship between parent themes and child themes. When the function is used call a specific file, it will search for that file in an active child theme first. If it fails, it will then search for the same file in the parent theme.

If that fails, the function will return to the child theme and start searching for a “fix” (remember, it won’t create a warning or fatal error like include() and require()) by loading another file in place of the missing specified file. If that was to fail as well, the function goes back to the parent theme and starts looking for the same fix. Awesome.

Function Self-awareness – That’s a silly thing to say about a function. I know. But get_template_part() knows where it is in your file structure when it’s used. You don’t have to specify which directory the function works from with other WordPress functions like get_stylesheet_directory_uri(). get_template_part() does that for you.

Recognizing Post Formats – In true conditional fashion, get_template_part() can be set up to detect the post format being loaded and search for specific file names based on that post format. This means it also recognizes certain WordPress file naming conventions.

With all of this understood, let’s take a look at the function in more detail.

get_template_part() in Action

get_template_part() takes two parameters, though only one of them is required.

The first parameter is called the “slug.” This parameter is required and is used to start the initial “search” for the file being used. Typically, multiple files will share this slug.

The second parameter is called the “name.” This parameter is optional and is used to further specify which file to locate. The name parameter is usually what makes a file name unique within a given slug.

Here’s an example of how get_template_part() would be used in a theme.

<?php get_header(); ?>

<div id="content" class="content-column">

	<?php while ( have_posts() ) : the_post(); ?>

		<?php get_template_part( 'content', 'page' ); ?>

	<?php endwhile; // end of the loop. ?>

</div>

<?php get_sidebar(); ?>
<?php get_footer(); ?>

What you see here is a typical page.php template file for a theme. It’s responsible for displaying WordPress “Pages.”

Without getting into too much detail, all this file does is call the site’s header file, display an HTML container for Page content, call the site’s sidebar, and call the site’s footer.

The part we want to worry about now is the way get_template_part() is used inside of the WordPress loop – get_template_part( 'content', 'page' ).

Just like get_header() calls the header.php file, get_sidebar() calls the sidebar.php file, and get_footer() calls the footer.php file…

get_template_part( 'content', 'page' ) calls the content-page.php file.

Notice the way the function parameters are used to determine the file name to search for – {slug}-{name}.php.

content-page.php should then be full of code that is relevant to the exact location it’s being called from. In this case, the page content container element and its contents, like the title and entry content, should be in this file like so.

<article>
	<header class="entry-header">
		<h1 class="entry-title"><?php the_title(); ?></h1>
	</header>

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

The main purpose of get_template_part() is to grab code from another file. Therefore, you are correct in your assumption that instead of using the function, the code inside of the file being called could be pasted in its place.

get_template_part() is used for organization purposes and it also helps with efficiency if multiple template files can share the same remote file through the use of the function.

Here’s how WordPress will treat our get_template_part( 'content', 'page' ) example.

  1. search child theme for content-page.php
  2. search parent theme for content-page.php
  3. search child theme for content.php
  4. search parent theme for content.php

Pay close attention to that order as well as the significance of the slug parameter. Child themes take priority while parent themes back them up. Likewise, the slug parameter backs up the overall function in the event the slug/name combination is not found.

That’s get_template_part() in a nutshell. It allows you to easily call another file’s contents as well as better organize your theme files.

Additional Tips for Using get_template_part()

Templates Directory – When I build custom WordPress themes, I like to keep my theme root as clean as possible and organize files with logical directories. Simple stuff.

Considering the page.php and content-page.php example above is a real-world example that also applies to other template files like single.php, index.php, and archive.php along with their counterparts, I create a directory in my theme root called templates and place all of my content-{name}.php files in that directory.

With this setup, my theme root stays clean and WordPress can still find the top level template files it expects to see in the root.

As you may have guessed, get_template_part() needs to be informed of my decision to place my content files inside of a directory. It’s so easy to do. Simply add the directory name with a trailing slash directly before the slug parameter like so.

<?php get_template_part( 'templates/content', 'page' ); ?>

get_template_part() has the ability to search one directory deep. In this case, it’ll find the templates directory and then search its root for content-page.php just like before.

Using get_template_part() with post Formats – Another common situation in basic WordPress themes is the blog home using the index.php template file to format the blog post listing. Just like in our Page example, index.php will also use get_template_part() to include a more general template file usually called content.php.

The difference here is that the blog home may also have to honor a mix of Post Formats in the blog post listing. Obviously, it has no way of telling which post will be which post format. That’s where this handy functionality comes in.

<?php get_template_part( 'content', get_post_format() ); ?>

What happens here is WordPress will now search for more specified file names using the format content-{post_format_name}.php and select files based on which kind of post format is being displayed in the blog post listing.

If your theme supports “image” post formats, it will search for content-image.php and use that template instead of the default content.php. However, if content-image.php doesn’t exist, again, get_template_part() will simply fall back to content.php.

That means you can use the get_post_format() function for the name parameter in get_template_part() even if your theme doesn’t support post formats. Why? Because if a child theme is ever installed that does support post formats, you’re already good to go.

Happy organizing and coding! 🙂

24 Comments:
  1. Here’s what I am trying to do.
    I have a parent and custom child theme installed on my website with jetpack plugin.
    I am using the portfolio functionality of the same.
    What I intend to do is, show the items of the portfolio content type in my very own desired manner. How do I do this?

    • I’m guessing the portfolio functionality is part of the parent theme and you’re wanting to customize how it looks through your child theme?

  2. I am trying to create a page in wordpress, and I am using the page template to help me do that, that is its code:
    ****************************************************


    ****************************************************

    Thats what I need:
    ****************************************************

    I write my code here!!!


    ****************************************************
    unfortunately, that moves the white area that the content suppose to be on!!! What should I do?

    take a look http://postimg.org/image/c485t1exp/

    Thank you 🙂

  3. A nicely written article! Helped me grasp the basics of the `get_template_part()` function in under 15 minutes. The official documentation had me confused to be honest, and this article was a life saver. Thanks!

  4. I was looking for way to include files from sub-directories. You did a wonderful job explaining ‘get_template_part()’. Thank you very much. You saved my time.

  5. Hello Sean.

    First of all I want to say GREAT JOB! Very good explanation of get_template_part using.
    Unfortunately I am still a bit confused. I wanna put a image slider on my front page so all what I need to do is just get some images from wordpress and make it work by means of css and js. Here is my code:

    ‘attachment’,
    ‘numberposts’ => -1,
    ‘post_status’ => null,
    ‘post_parent’ => $post->ID
    );

    $attachments = get_posts( $args );
    if ( $attachments ) {
    foreach ( $attachments as $attachment ) {
    echo ”;
    echo wp_get_attachment_image( $attachment->ID, ‘full’ );
    echo ”;
    echo apply_filters( ‘the_title’, $attachment->post_title );
    echo ”;
    }
    }

    endwhile; endif; ?>

    The question is: would it be a good practise if I saved it into my get_template_part file?

    • I’m sorry for the really slow reply here.

      I wouldn’t say it’s either good or bad practice. I do this sometimes when I want to separate a chunk of code and I do it for various reasons. I’ve used get_template_part() just to keep things clean in a particular template file and I’ve also done it to separate a chunk of code that I expect my users to want to override and edit from a child theme (because most of the themes I build are for mass distribution).

      So it’s really just about how you want to organize things. Are you distributing the theme? If you leave the code in its original template, does that expose users to code that you do not want edited if they override from a child theme? Answering questions like that will tell you which way to turn. No rules!

      Thanks for reading.

  6. Hello,
    I cannot get my child theme files to work. The parent theme files take precedence which I can’t figure out.

    single.php (Parent theme)

    If I create an “includes” folder in the child theme, and copy content-single.php into the folder and make edits, the parent theme content-single.php takes precedence. If I rename the parent theme content-single.php file to something else to check and see if it will find the file in my child theme folder, I get an internal 500 server error. Any help will be appreciated.

    • Hi there. Sorry for the delay.

      If you have not figured this out already, the first thing to do would be to copy your parent theme structure from your child theme. So take this for example:

      Your parent theme may have a single.php file, which WordPress will use to serve single posts and other post types that fall back to that template. What is in that template, though? Is it ALL of the markup or does it include a get_template_part() call to content-single.php? If it calls to another partial template, is that template in the root of your parent theme or its own subfolder?

      Let’s say it calls to content-single.php and that file sits in a folder called “partials.” What you would want to do from your child theme is create a folder called “partials” in the root and then copy the content-single.php from your parent theme into your new child theme “partials” folder. You need to copy the parent theme’s structure when you bring files into your child theme.

      So a child theme content-single.php will NOT override a parent theme single.php file, they are not the same thing.

      Does that make sense? Again, I apologize for the delay!

      • The content-single.php is located in the “includes” folder in the parent theme. I created an “includes” folder in the child theme and copied content-single.php into that folder.

        Here is a screenshot of the code for the single.php file.

        https://db.tt/A5y7P8Cc

        • Okay that is correct. WordPress will know to use your child theme’s partial template. If you are positive that you have content-single.php inside of the includes folder in the root of your child theme, and you are positive that your child theme is the activated theme, there is a separate issue.

          Temporarily deactivate all plugins to make sure you are not using anything that disrupts the behavior of WordPress template files. If no luck still, what kind of page are you trying to look at on your site? Is it a single blog post?

          • Actually, the single blog post is working. I’m trying to remove the author name from the blog page which I believe is the index page.

            Blog page screen shot:
            https://db.tt/nHpnRycq

            Here’s a link to the index page I’ve edited.
            https://db.tt/Q4z4Y5BM

            Line 85 starts the filter drop downs which are in the screen shot of the blog page. Line 138 starts the blog which I don’t know how to edit. People’s usernames are printing out in the post meta which I know can be changed but I have people maintaining their own websites with little WordPress training and I flip out when I happen to stumble upon someone posting a blog with their username showing. The author’s username is also printing out as a class name in each post. I don’t know if this is standard for WordPress themes??

            Thank you for your help.

        • I think we’ve gotten a little off track here. It sounds like get_template_part() is working properly for you. Did you have any other questions about that function that I can help with?

          I will not be able to assist you in customizing your theme.

          • Oops you’re right. I’m got off topic. Thanks again for your help.

  7. Sorry the code from the single.php file is not showing but it is pretty much what you have posted under the example of how get_template_part() would be used in a theme.

  8. Hi there! Im trying to figure out if what I am doing is a good practice for sectioning out some content in my templates. I have a hero image w gradient/text overlay on the homepage and on the interior pages I have a smaller hero images with gradient/text overlay. They will be different hero images for each page.

    Usually I like to section out my html like this. Header, Sub-Header, Content, Footer. Where in my subheader file I have my conditionals and I include that into the header. I have been using the typical include()

    So my question is can I create individual ‘subheader’ templates and call them within the header with this get_template_part? Or should I just use include the file with the standard include like i have been doing?

    I’ve seen where you can create different header files and just call them get_header(‘my-page’) per page but I feel like that is just too much loading of the same header code when really all i want to do is swap the subheader.

    Im just trying to figure out if what I have been doing is a good practice. thanks!!! sorry for the confusing post! 🙂

    • Hi Lance,

      Great question! So first, in response to the idea of using get_header() over and over again, I agree with you 100%. It’s too much, for the most part. And there is some pretty important data that flows through the header like everything using the wp_head() hook. So it’s definitely best to not repeat that code all over your theme if possible.

      I love the subheader idea. I’ve actually taken a similar approach in once of my themes. Here’s a portion of its header.php template: http://glui.me/?i=b68zg646el1m0h7/2016-07-09_at_11.29_AM.png/ You can see at the bottom I’ve used get_template_part() to call a feature box file which is essentially the same as your hero.

      Then once you get into the file you call, you can have a conditional using WordPress’ conditional tags. Or you can even build a conditional into the header.php file using the same conditional tags and then have multiple get_template_part() calls based on the condition. It really just comes down to what you like.

      To answer your overall question, though, it’s definitely safe and in my opinion, smart to use get_template_part(). I say go for it. 🙂

      • Thanks for your response Sean! I really appreciate it! I’m basically a ‘one-man’ band so its great to get some advice/feedback to see if Im on the right track or totally out in left field 🙂

        I’m glad I found your site. Lots of great stuff here! thanks so much! 🙂

  9. Really good details. It caters my needs indeed. thanks for explaining this function in detail. I want to show php file with mysql database connectivity code with default theme format ( as i am interested in using theme from wordpress , becaulse i am not good designer).

    hope i can solve my problem now.
    thanks once again.

  10. Hey there,

    Love the article. Like many others stated, it’s simple and easy to understand. Good job!

    One question though, I like how you said you create a “templates” folder to keep everything organized. So I decided, hey good idea, gonna try it. So I created a templates folder and added all of my content-{name}.php files to it and updates all of my to

    However, the main blog page, archive pages, search pages and so on will not show any posts.

    This has me perplexed…lol. Any idea of what may be the cause? Any insight is greatly appreciated.

    Thanks again for the article. It really is very helpful

Leave a Reply

Your email address will not be published. Required fields are marked *

*