templatepart

I See get_template_part in my WordPress Theme. What’s it For? How Do I Use It?

I have seen quite a few searches come through lately for get_template_part.  Seems like a lot of folks don’t know what it’s for, what it does, or how to use it in their WordPress theme.  When it was introduced with WordPress version 3.0 I wasn’t all that excited.  I didn’t see a need for it.  I was kind of set in my ways.  I liked how I did things.  But after looking into it for a while, I discovered it’s a powerful and useful tool.  Let’s take a look at what it does for you.

First off, what is it?  Simply put, get_template_part is just a way to include another file.  But it’s more powerful than a php include statement, because of its flexibility.  It’s amazingly useful, especially for anyone trying to build a child theme.  So let’s take a look at how it could work for you if you are trying to make a child theme for twentyten first.  If we look at index.php in twentyten, we see:

get_template_part( 'loop', 'index' );

What’s that do?  Well let’s take a look at the structure.  Get template part follows the format of:

get_template_part( $slug, $name );

Where the slug is the generic name of the template being called, and name is the specialized name of the template being called.  So there is an order that WordPress would use to try to find the template to use.  Properly named files in your child theme come first, then files in your parent theme are used.  So using the example above with the generic name ‘loop’ and the specialized name ‘index’ here is the order WordPress would look for files.

  1. wp-content/themes/twentytenchild/loop-index.php
  2. wp-content/themes/twentytenchild/loop.php
  3. wp-content/themes/twentyten/loop-index.php
  4. wp-content/themes/twentyten/loop.php

See how that works?  We look for the specialized template in your child theme.  Then the generic.  Then the specialized name in the parent template.  Finally the generic name in the parent theme.

Now sticking with the twentyten theme. We already know we have this in index.php:

get_template_part( 'loop', 'index' );

And we also can see we have this in archive.php:

get_template_part( 'loop', 'archive' );

So what does it all do?  Well, in a basic twentyten install, there are no specialized templates, nothing named loop-index.php or loop-archive.php, so WordPress simply uses loop.php.  But the power comes in here for you, the child themer!  You could overwrite the loop for the index page or the archive page by creating the specialized named file loop-index.php or loop-archive.php.  For instance, if you only made a loop-index.php, then your file would be used for the main index page.  But since you didn’t make a loop-archive.php, twentyten’s original loop.php file would be used.  You see, you can override either template, without affecting the other.  Now if you made a file called just loop.php in your child theme, with no specialized template, then your loop.php would override twentyten’s for both situations.

Hopefully now you can see the naming conventions. How it all works, and how you can override templates in themes which use get_template_part. It gives you a lot of power when making a child theme. But what if you are making your own theme? How can you use it? Well you could a couple of routes here. In all your files (index.php, archive.php, category.php, etc) You could make a call to get_template_part, and make an individual file for each loop. So index.php would have:

get_template_part( 'loop', 'index' );

And then you would make a file called loop-index.php with the loop in it. You could do that for each file. This now gives anyone trying to make a child theme for your theme a way to override your loops. Or you can do what I like. Use get template part in your theme, but just make a loop.php file and code it to account for everything. I have a giant loop.php which uses a variety of conditional statements to cover all my templates. It handles index, archive, my shop, pages, single view, custom post types, etc. I just built the file up as I added everything. So now I have one big loop, but have given users of my theme the ability to use their own loops with get_template_part.

You can also use get_template_part to call in things besides the loop. For instance I use:

get_template_part( 'icons', 'social' );

to call in a file called icons.php. It’s a big block of code that I use to display social icons under member profiles on my blog. Rather than repeat the code on various templates I just included it. This is nice for me as it allows me to reuse the block of code without actually typing it into each template. Keeps things neat and organized. But it also allows child themers to override it with their own code if they feel the need.

That’s it for this article. Hopefully it helped you understand what that bit of code is doing, and why get_template_part is so useful. Now get to building your own child theme, and have some fun with it!

26 thoughts on “I See get_template_part in my WordPress Theme. What’s it For? How Do I Use It?”

  1. Thanks for good explanation. It would be helpful to show some examples of loop.php functions for archives for custom post types….

    1. I’m happy to give some loop examples. What sort of things are you looking for? Since CPTs are pretty specialized to each person. I use mine for listing members of my music label, and for displaying hockey RSS feeds, and for products in my shop. I use my loop.php to cover most of those, with a bunch of conditionals and whatnot. But my usage is specialized to my particular needs. I’ll write up an article soon with a variety of my usages for examples. Were you looking for anything specific, or just some examples?

    1. I’m glad you found this article useful! get_template_part is really cool, it provides a great way to reuse code throughout the theme, and a great way to allow child themers a way to override specific things.

  2. I would like to register a new sidebar (widget) that i will place on top of the content area just below the navigation bar for a banner ad. Can anyone please help me with this?
    Thanks in advance.

  3. Hello there!
    I just want to thank you for your clearly understandable explanation.
    I spent two hours searching till got to your site and with what you have written here now I can say I am able to use this function.
    By the way I am from Iran,
    I hope you don’t mind as some people do, That is the government not people.
    anyway I always owe you for what you taught me.

    Wish you Bests from Iran

    1. I am very happy you found my site, and that this info was helpful for you to learn from! If you come across other issues in the future, I hope you’ll remember this site! If the info isn’t here, just ask in a comment or on the forum. I normally quite busy, but I do try my hardest to provide answers, or to find them if I don’t know! I definitely don’t mind that you are from Iran!! I don’t care where anyone is from!! I’m here to to have fun with WordPress, and to help anyone else I possibly can!

      1. Thanks buddy I’ve already bookmarked your site.
        I believe there are a lot more here to learn.
        WordPress is not the thing I get here I am also learning how to be as generous as you to give people free info.

        Bests from Iran

  4. Great post, but for godsake please do something with your fonts. The text is rendered horribly in both firefox and chrome, almost illegible (and i’m not talking about the title style).

    1. I’m not sure what you mean about the fonts? I’ve checked them out on Chrome and Firefox, and even on mobile. I don’t see any issues with the font rendering? Everything looks good on any browser I use – except the titles, and those are just for silly sake really…. I had planned to change those up with the release of the 2012 theme, and that just never happened with WP 3.4.

  5. Hi Rav,
    I want to remove things like date, category and comments count under each post in my category page. I looked the archive.php file where i cound not understand the following line of the code:
    get_template_part( ‘post’ , ‘entry’)
    If I want to grab only the post title on category page, how to change this code?
    I am using ‘Complete’ theme.
    I searched over the internet but could not find an answer.
    thanks in advance

  6. I Use WP 2.9 twentyten based theme since a while and see it simple and powerful enough to all my needs .
    It was surprise to see all this files done what one file do .
    twentyten basically have fewer file like
    header.php index.php sidebar.php single.php page.php footer.php archive.php archives.php functions.php
    that all you need to edit to make wordpress theme
    Why They Make this more complex in every update
    By the way I make alot of changes on my theme using PHP include function . Which I see more simple from this extra codes .
    sorry If my English was bad that’s was best what I can explain .

    1. Well first off, WP 2.9 is old. Every release of WP has security fixes, and bug fixes. By using such an old version of WP, you are risking having your website hacked due to running old software versions with known security problems. It is quite important to keep WP up to date. The reason WP uses get_template_part is that it is quite powerful. Using it, we can have one main template, such as index.php. But we can call out to many different files for there for different pieces, like the loop – the part that displays your posts. But we can have many different files possibly used, depending on content. So within index.php, depending if it’s a blog page, a page, a custom post type, a post format, etc, that one line of code can call out to many different files. So it’s power and options. Plus, it makes child themes easier to create. I can make a child theme of 2010, and easily override various displays with my own template parts. So, while it may seem more complicated, once you understand how get_template_part works, you can see it’s all about options.

  7. Trying to use this convention with single.php and it doesn’t seem to work if I use:

    I have a related question which is that my image on my single page is showing above my post instead of the post wrapping around it. As the image is 250×250, that’s not ideal. I’m using twentyeleven and have created a child theme. If I have to fiddle with css I will, but this seems like something that should probably right out of the box. Loop in single.php is:
    single-img’, ‘alt’ => ‘Title’ ) ); the_post(); ?>

    Thanks for all your site tips.

    1. ON my comment form, right at the bottom, you can see instruction for how to paste code here on VoodooPress, it just needs to be wrapped in language tags in square brackets. I can’t get your pastebin to load right now (probably something wrong on my end, work computers are old and wonky), as soon as it loads for me, I’ll give it a look!

      1. Yeah, I just modified that Codex article because the order was wrong there too :) look at how get_template_part works internally. When given “loop” and “index” as the two arguments, it form the following array: array( ‘loop-index.php’, ‘loop.php’ );

        Which is then passed on to locate_template, which loops through that array and checks for the file in the child theme first, then in the parent theme. If the file is found it breaks the loop and includes what is found. Since loop-index.php is first in the array, it will look for loop-index.php in the child theme, then the parent theme and break if it’s found in the parent theme, so the foreach loop will never even reach loop.php :)

        Ref: http://core.trac.wordpress.org/browser/tags/3.5/wp-includes/template.php#L353

        1. Just got back from a business trip and trying to get caught up! so.. no shit?
          The order is:
          child/specific
          parent/specific
          child/generic
          parent/generic
          then?
          Good to know!!! That doesn’t affect my theme writing philosophy too much, but very impportant to know! Thanks!!!

  8. Thanks for the great explanation! I looked all over the place trying to find the difference between an include and get_template_part, and this sums things up perfectly.

Leave a Reply