Document change in template override logic: page--node--1.tpl.php overrides, not page--node-1.tpl.php, as in D6

Moving to proper component & demoting priority. At most, this is major. Perhaps this is the intended behavior, though, in which case the presentation is simply out-of-date. People who worked on the theme system for D7 will have to give feedback.

I think that this bug is probably "normal" priority, but want to wait for the relevant people to make that determination.

similar issues: #821446: Need tests for region-specific overrides of region.tpl.php

for me I always think it is a critical issue. I don't understand why Drupal sometimes ship a broken system to end user.(It's issue can be affect to ALL drupal 7 themes)

@droplet: Thanks for pointing to the other issue. As far as priority goes, please read Priority levels of issues, especially the definition of critical: "Critical bugs either render a system unusable...or expose security vulnerabilities."

This bug, by definition, does not render Drupal unusable as a whole; I don't even think it meets the criteria for a major bug, since it only affects the theme system, and it does so by changing the system's expected behavior, not by making it impossible to override templates at all. It could be fixed in a point release, if necessary; it doesn't need to block release of 7.0.

That said, I have tagged it as a regression, and with "needs themer review" in the hopes that will attract the right people to review it.

Page 82 of the presentation says:

Delimiters use two: "--"
Words still use one: "-"

@jucallme: I'm not sure which part of the presentation suggests anything else than the following sources. I don't see any examples in the presentation using the page hook, as in your post. Do you think there is a problem with http://api.drupal.org/api/function/theme_get_suggestions/7 ?

From the API Docs (http://api.drupal.org/api/function/theme/7):

This process is iterative, so if theme('links__contextual__node', ...) is called, theme() checks for the following implementations, and uses the first one that exists:

links__contextual__node
links__contextual
links

In #821446: Need tests for region-specific overrides of region.tpl.php Effulgentsia writes:

Wherever you see the double underscore, it means the thing is a variant of whatever comes before the double underscore, and in a few cases, you can even find multiple double underscores, like 'field__' . $element['#field_name'] . '__' . $element['#bundle'], which allows for a bundle-specific variant of 'field__' . $element['#field_name'], which itself is a field-specific variant of 'field'.

@Eric_A: So what is the difference between delimiters and words? This sounds to me like it is actually a documentation problem, where the documentation on changes from D6 should be made clearer.

The text from http://drupal.org/update/theme/6/7#template_files_double_hyphen might benefit from an example with multiple occurences of the double hyphen.

The system strips double hyphens until it finds a hook implementation. It strips at delimiters and checks, it does not at words.

From theme():

  // If there's no implementation, check for more generic fallbacks. If there's
  // still no implementation, log an error and return an empty string.
  if (!isset($hooks[$hook])) {
    // Iteratively strip everything after the last '__' delimiter, until an
    // implementation is found.
    while ($pos = strrpos($hook, '__')) {
      $hook = substr($hook, 0, $pos);
      if (isset($hooks[$hook])) {
        break;
      }
    }

Changing this to a documentation task, then. I am sure that I am not the only person who finds this confusing. An example with the double hyphen (probably with "node--long-content-type-name.tpl.php", to stick with the current example given) would be helpful.

If your comment is specific to the node and node/% router paths, then there may be more to it, because the "node/%" path is very different from the "node" path.

Consider these hooks:
page__node__1
page__node__1__html1

page__node_1
page__node_1__html1

They could mean different things. The integers would be just types in the first 3 hooks, not node ID's. In the last 3 hooks the integers could be node ID's.

It does not work that way right now, though, as far as I know. See template_preprocess_page() and theme_get_suggestions().

EDIT:
Since the __% pattern is the default way to work with numeric args in paths, it is in fact the other way around, i.e. one should consider/ register non default (non hyphens) overrides for the "node" router path.

EDIT2: Replaced wildcard with integers. It doesn't make sense otherwise.

@jucallme. Every theme hook has its own default suggestions, i.e. default suggestions for field are different from the default suggestions for page.

What are we saying needs documentation here, exactly?

@jhodgdon: The fact that the override of a page.tpl.php for node/17 is page--node--17.tpl.php (i.e., two occurrances of the double hyphen, rather than the 2nd one being a single hyphen).

Hmmm. Then we should probably put this onto the Theme Upgrade 6/7 page, as well as some theming page in the Handbook (not that the D7 theming guide really exists at this point)? Adding a tag for update doc accordingly.

A D7 theming guide would be an awesome place for this :) I so wish that I wasn't as busy with work this time of year....

This was long-ago documented:
http://drupal.org/update/themes/6/7#template_files_double_hyphen
I added a note specifically about page templates, since the examples in that section didn't have multiple levels of template overrides.