Overriding Page Templates per Content Type in Drupal 7

Posted by Art Williams on January 11, 2012

Overriding a template file is relatively common task for a front-end developer, but depending on the base theme used it’s not always clear how to go about doing it.

Here at Digett we’ve begun to use AdaptiveTheme as our starting point for two Drupal 7 sites we are currently building, where previously we were using Fusion or Zen on Drupal 6. This caused us some heartache in overriding templates and brought to light the lack of clear documentation on the subject. There are a lot of opinions on Drupal.org but not much clear instruction.

Template Files

Most Drupal themes will come with a minimum of 3 default template files: html.tpl.php, page.tpl.php and node.tpl.php. Many other template files may be included that control the display of more specific elements such as comments or individual fields. Each of these files can be overridden for a specific condition simply by creating a new file in the theme folder with the correct name. These file names are called “Template Suggestions” and there is a standard set of these suggestions built into Drupal and listed in the documentation as Drupal 7 Template Suggestions.

Page Template Per Content Type

A common override that is not included in the default list is the page.tpl.php override based on the content type being displayed. There is a node.tpl.php override based on the same condition which leads to confusion as to where the page override exists. On top of that, themes like Zen add this type of override to the Template Suggestions, which leads those using Zen to believe that this is part of the default list. Check the theme documentation to see if this override has been added to the Template Suggestions by the theme. If it hasn’t, you need to add it manually.

The process is straightforward. We can create additional Template Suggestions simply by adding them to the ‘theme_hook_suggestions array in our template.php file.

  1. Open the template.php file in your theme for editing.
  2. Look for a function called yourthemename_preprocess_page (replace the yourthemename with your theme’s name).
  3. If this function already exists, you will need to add the if statement to the end of the function just before the closing bracket. Otherwise you’ll need to create a new function to look like this:

function yourthemename_preprocess_page(&$vars) {
  if (isset($vars['node']->type)) {
    $vars['theme_hook_suggestions'][] = 'page__' . $vars['node']->type;
  }
}

Now you can create a template file called page--content-type.tpl.php and all nodes with that type will use the new template file.

Filename Notes:

  • Use two dashes after the word ‘page’ in the filename.
  • If your content type is two or more words, replace the underscore ( _ ) with a short dash ( - ) in the content type machine name.

Image: Woody Thrower

Related Articles

MONTHLY MARKETING INSIGHTS.

Get thought-provoking and actionable insights to improve how your firm makes a connection with your customers.

LEAVE A COMMENT

The content of this field is kept private and will not be shown publicly.

Plain text

  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
Submitted by Patrick on Wed, 01/11/2012 - 11:58am

There's a typo in the second paragraph of the "Page Template Per Content Type" section: hook_suggestions not hood_suggestions.

Submitted by Art Williams on Wed, 01/11/2012 - 2:34pm

Thanks, Patrick. It has been corrected.

Submitted by Dionisis on Fri, 02/10/2012 - 4:31pm

Nice tip. Some times the design can be pretty unique and stuff like that are necessary !

Thanks

Submitted by Olivier on Sun, 03/11/2012 - 12:34pm

Thanks, Williams.

Submitted by Delaney on Fri, 03/23/2012 - 2:04pm

Hello,

I'm trying to do this on my site and have stripped the template down to only show title and content. (for simplicity's sake)

I created a new content type: homepage

I've named my template file in my templates directory: page--homepage.tpl.php

I added the preprocess_page function to my template.php file right above the process_page function. (I didn't have a preprocess function in my template.php file.)

Still, it doesn't seem to work.

Do I need to do anything else? Or have I done something wrong?

Submitted by Art Williams on Fri, 03/23/2012 - 4:03pm

@Delaney: Did you build the theme registry? (i.e. flush all cache)

Submitted by Doug on Wed, 03/28/2012 - 4:01pm

Can this be done for yourthemename_preprocess_html ?

Submitted by Martin on Wed, 05/16/2012 - 3:46am

I am developing a custom theme in D7 and sometimes finding good documentation on drupal.org can be confusing & complex.

Congratulations on this simple and effective article. It is awesome and got me making custom node type templates in minutes, something I had been struggling to understand for days.

Well done & thanks - drupal needs people like you definitely!

Submitted by kishore on Mon, 06/11/2012 - 11:46am

Hi
I have followed your steps for creating Page Templates per Content Type but it is not working please help me?

Submitted by kishore on Mon, 06/11/2012 - 11:52am

I am working drupal 7 bartik theme
My steps are
1.I have added below code in the theme template file like
function bartik_preprocess_page(&$vars) {
if (isset($vars['node']->type)) {
$vars['theme_hook_suggestions'][] = 'page__' . $vars['node']->type;
}
}
2.I have created a content type named as lawngarden (Machine name: lawn)
3.I have created a page template (page--lawn.tpl.php) under templates folder
4.I have clear the cache
5.Enter the browser url like http://localhost/appl/?q=lawn
6.The page shows like
The requested page "/appl/?q=lawn" could not be found.
7.please help me
8.Thanks for advance

Submitted by Delaney on Tue, 06/12/2012 - 2:53pm

Well, I thought I had... but it turns out that drush cc all doesn't actually clear all cache.

Submitted by chirag on Fri, 06/29/2012 - 1:08am

how to override page.tpl file for a specific menu?????

that menu is not for any content type.

Submitted by Quinten on Wed, 07/18/2012 - 5:07am

Thank you for this. it should be made a basic snippet for core!!

Submitted by Amy Peveto on Wed, 07/18/2012 - 12:40pm

Thanks! :)

Submitted by Paul on Thu, 07/26/2012 - 3:44pm

Thanks, this was really helpful. It took me a minute to figure out that the $vars used here is the same thing as the $variables used by Zen, that in fact it doesn't matter what you call the input argument to this function. I learn something new everyday with Drupal. :)

Submitted by Amy Peveto on Thu, 07/26/2012 - 3:57pm

That's the downside—or maybe the upside?—of using such a complex platform: you're never done learning!

Submitted by martina on Thu, 08/23/2012 - 1:50pm

Thank you so Much! this was very helpful!

Submitted by Amy Peveto on Thu, 08/23/2012 - 2:23pm

Glad it helped you, Martina!

Submitted by Jonathan on Sun, 09/02/2012 - 8:56pm

Thanks, I've been trying to work this one out!

Submitted by Amy Peveto on Tue, 09/04/2012 - 9:52am

Glad it helped, Jonathan!

Submitted by John on Sun, 09/09/2012 - 4:38pm

Thank you so much for this info, it was extremely helpful!

Submitted by Amy Peveto on Mon, 09/10/2012 - 9:09am

Glad you found it helpful, John!

Submitted by John on Mon, 09/10/2012 - 9:29am

In the excitement of getting this to work via your excellent tutorial, I didn't realized that it made my header block disappear. I'm using Zen. Any idea what might be causing this?

Thanks!
-JP

Submitted by Paul on Mon, 09/10/2012 - 10:43am

If you look in Zen's page.template.php file, you'll find lines that generate various sections of of a generic web page. Copy the lines you need into your new file.

Submitted by John on Tue, 09/11/2012 - 8:46am

Yup, that that did it! Thanks so much.

Submitted by Craig Sander on Mon, 09/24/2012 - 12:16pm

This is a great article and really helps explain the process, but I'm still not seeing results.

I've added the if statement to the Zen template.php file and I've created a template for my content type, but I'm still not seeing the override.

I have cleared caches and I've substituted the underscore with a short dash.

Do you know if there's a specific technique you must use with the Zen theme structure. (I'm not using sub-theme, just overriding Zen files.)

Thanks,
Craig

Submitted by Mahesh on Wed, 10/10/2012 - 10:07am

Thanks for the information ... It helped ....

Submitted by Amy Peveto on Wed, 10/10/2012 - 10:09am

You're welcome!

Submitted by Cocoonfxmedia on Fri, 11/23/2012 - 1:54am

I am using a copy bartik theme in DP7

I have tried everything and this doesn't work. I have used page--node--1.tpl.php or page--node--73.tpl.php and this works.

Losing the will to live as it seems it is the hardest CMS system to work with.

Any suggestions would be welcomed

Submitted by JD Collier on Mon, 11/26/2012 - 8:53am

@Cocoonfxmedia: I'm sorry, I don't personally like Bartik for front end theming. I prefer Adaptive, Zen or my new favorite is Bootstrap. Bartik had too much stuff to undo for my taste. I prefer to start with less and add my own. I did a google search and couldn't find anything to help you.

PS: While I am a fan of Wordpress and can do anything with it ... I still favor Drupal. Once learned, it can do ANYTHING :)

Submitted by Jice from Pres… on Sat, 01/12/2013 - 10:35am

Thanks for the post. Very clear.

I was struggling with drupal, trying to force the page customization, until I found your article.

Hope the 'automatic' overriding is there with drupal8.

Submitted by Drupal | Annotary on Thu, 01/17/2013 - 9:38pm

[...] More from Nick Lewis: Javascript Miscellaneous Programming Agile Sort Share www.digett.com       2 days [...]

Submitted by Chris Bloomfield on Thu, 07/18/2013 - 3:40am

Thanks, really helpful. I've been trying to figure this out for a while.

Submitted by Amy Peveto on Thu, 07/18/2013 - 7:55am

Glad to hear it, Chris!