I'm working in Drupal 7.

I'm trying to add a custom template file for a few pages I'm creating. I've done so in hook_preprocess_page in my template.php file.

This is the scenario:

I have four "Basic Page" pieces of content that will use the same template file. I've already coded page.tpl.php for other "Basic Page" content. The reason I want this template is because the look of these four basic pages is different from other pages. What I've done is added my suggestion to the theme_hook_suggestions array. It's ignoring what I'm adding. Just a note: after every step I'm clearing my caches. It isn't that.

I've tried this:

$variables['theme_hook_suggestions'][] = 'newbies';

This will add the 'newbies' suggestion to the array, but creating a 'newbies.tpl.php' file gets me nowhere. It's ignored. I've gone as far as doing this:

$variables['theme_hook_suggestions'] = array(0=>'newbies');

Which erases the suggestions array and adds only my suggestion, which I've verified with krumo. This also doesn't do anything and is ignored. My site doesn't even break when I do it.

From what I've read about theme_hook_suggestions, it would seem that Drupal only wants template suggestions for templates that it defines. For example, just creating an arbitrary template file (in this case 'newbies') instead of some system defined one like 'page--type--system--node......' etc.. will never work. I've decided to rule that out as being truth for now because I refuse to believe that a design flaw of that magnitude could be introduced into any software.

What am I missing?

2 Answers 2


You're missing how the framework is designed.

If you're doing anything with hook_preprocess_page() you are affecting the 'page'.

The default template for page is 'page.tpl.php'.

If you want to 'override' this template Drupal needs to understand what's going on so has some conventions.



"Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds"

See: http://drupal.org/node/1089656 and http://drupal.org/node/223440#custom-suggestions

In your case, your defining 'newbies.tpl.php' and expecting this to work but it's still going to use 'page.tpl.php' so to override this you want to do 'page--newbies.tpl.php' (same as 'page--node.tpl.php').

More to the point, you don't even need to set this with hook_preprocess_page() as Drupal will follow those conventions automatically.

  • Does it matter that 'newbies' isn't a content type? I just want an arbitrary template file.
    – Brandon
    Dec 7, 2012 at 16:33
  • What are 'newbies' then, in the Drupal sense?
    – Alex Gill
    Dec 7, 2012 at 16:37
  • They're 'Basic Page's. The reason that I'm not just using page.tpl.php is because they're laid out differently than every other basic page on the site.
    – Brandon
    Dec 7, 2012 at 17:26
  • So they are 'content types'?
    – Alex Gill
    Dec 7, 2012 at 17:30
  • 1
    @Brandon if you have a content that needs to be treated differently, you are supposed to make it different content type. That's how this framework is designed.
    – Mołot
    Jun 24, 2013 at 6:53

I've struggled with this on many occasions and it still confuses the hell out of me, but I think I got it figured out finally (or again...):

If you try to overwrite a page with hook_preprocess_page your tpl filename must start with 'page--'. The next pitfall is that all hyphens will get replaced by underlines.

So let's say you want to overwrite the page.tpl and your file is called:


Then your hook should look something like that:

mymodule_preprocess_page(&$vars) {
   if(something) {
      $vars['theme_hook_suggestions'][] = 'page__something_with_hyphens';

Same goes for html.tpl overwrites. Just they have to start with 'html--'.

And do not forget to clear caches if you make a change :-)


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.