theme_hook_suggestions is ignoring my suggestions

Question

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?

Answer 1

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.

page--[front|internal/path].tpl.php

page--node--edit.tpl.php
page--node--1.tpl.php
page--node.tpl.php
page.tpl.php

"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.

Answer 2

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:

page--something-with-hyphens.tpl.php

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 :-)