Trivial theme example -- now working.

Example code demonstrates the problem in both d6 and d7. Steps to reproduce:

1. Install module on example.com.
2. Visit http://example.com/a
3. Page content says "a". It should say "b".

EDIT: now working, thanks to effulgentsia!

D7 version:

a.info

name = A
core = 7.x

a.module

function a_menu() {
  return array(
    'a' => array(
      'title' => 'A',
      'page callback' => 'a',
      'access callback' => TRUE,
      'type' => MENU_CALLBACK,
    ),
  );
}

function a_theme() {
  return array(
    'a' => array(
      'render_element' => 'elements',
      'template' => 'a',
    ),
    'a__b' => array(
      'render_element' => 'elements',
      'template' => 'a--b',
    ),
  );
}

function a() {
  return theme('a');
}

function template_preprocess_a(array &$v) {
  $v['theme_hook_suggestions'][] = 'a__b';
}

a.tpl.php

a

a--b.tpl.php

b

EDIT: now working, thanks to effulgentsia!

D6 version:

a.info

name = A
core = 6.x

a.module

function a_menu() {
  return array(
    'a' => array(
      'title' => 'A',
      'page callback' => 'a',
      'access callback' => TRUE,
      'type' => MENU_CALLBACK,
    ),
  );
}

function a_theme() {
  return array(
    'a' => array(
      'render_element' => 'elements',
      'template' => 'a',
    ),
    'a_b' => array(
      'render_element' => 'elements',
      'template' => 'a-b',
    ),
  );
}

function a() {
  return theme('a');
}

function template_preprocess_a(array &$v) {
  $v['template_files'][] = 'a_b';
}

a.tpl.php

a

a-b.tpl.php

b

@Ralt -- Sorry. In the d6 version I should have had template_files instead of theme_hook_suggestions. Will re-edit above to correct. (Testing... corrected, but the problem persists; sigh.)

From the d6 theme() docs:

There are two special variables that these hooks can set: 'template_file' and 'template_files'. These will be merged together to form a list of 'suggested' alternate template files to use, in reverse order of priority. template_file will always be a higher priority than items in template_files. theme() will then look for these files, one at a time, and use the first one that exists.

From the d7 theme() docs:

There are two special variables that these preprocess and process functions can set: 'theme_hook_suggestion' and 'theme_hook_suggestions'. These will be merged together to form a list of 'suggested' alternate theme hooks to use, in reverse order of priority. theme_hook_suggestion will always be a higher priority than items in theme_hook_suggestions. theme() will use the highest priority implementation that exists. If none exists, theme() will use the implementation for the theme hook it was called with. These suggestions are similar to and are used for similar reasons as calling theme() with an array as the $hook parameter (see below). The difference is whether the suggestions are determined by the code that calls theme() or by a preprocess or process function.

You are suggesting that I should:

• (d6) declare template_preprocess_a_b() instead of adding 'a_b' to template_files.
• (d7) declare template_preprocess_a__b() instead of adding 'a__b' to template_files.

If that were so, then the d6 node.module would need to declare every possible template_preprocess_node_$nid() in order for node-specific templates like node-1.tpl.php to be invoked.

updated example code. Corrected "theme_template_suggestions" to "template files" in the d6 version but the problem persists.

@meba -- When an example as trivial as this doesn't work despite exactly following the instructions in the docs, that's a bug. Dunno if it's a docs bug or a core bug. Do you?

Thanks.

So the mechanism that makes node--1.tpl.php work doesn't have anything to do with the code in template_preprocess_node()? Or does it need to be supported in both theme and module in order to work?

Okay; I've got a working example I can build from now; thanks.

Soon as I've solved the immediate problem I'll work on building a docs page.

In my particular case, I want to add a htmlmail--simplenews.tpl.php suggestion template to HTML Mail in order to demonstrate how to customize Simplenews messages. My first attempt failed, and after a couple of hours of reading docs and re-writing code, I created a minimal problem demonstration module, and posted it here.