Change the naming convention in theme hooks to match standard patterns

@SebCorbin - thanks much for your patch - started me on the road to solving the problem of how to deploy webforms to different servers which might have different nid, but the same path-alias. I'm including a patch that incorporates the above patch1 and also adds support for webform-mail--.
Also updated the webform-form and webform-mail templates documentation accordingly. The patch is against 7.x-4.x (git co 7.x-4.x && git apply -v patch-file).

Would appreciate any comments or suggestions for improvement. I'm planning on adding this support (ie --nid) to all the different theming hooks.

The problem with that change is that all templates must be renamed from webform-form-1.tpl.php to webform-form--1.tpl.php to agree with the convention.

For this reason, I don't think we can put this patch in the 3.x version of the module. It's an API change.

o it would be best to delete the pattern and work with template suggestions (as node.module does

I'm not sure imitating node module is the best solution. If you're using theme_hook_suggestions only, the theme must also override the original template in order for it's suggestions to work (if I recall correctly). The solution used by Webform is the same as used by Views, Panels, and other modules that have complex template names. Although I do think being consistent with other names would be a good thing, the only change that is strongly needed here is switching to two underscores instead of one.

This issue is also quite relevant here: #837594: Give a machine name to webform and use it for theming, exports, features, form IDs, etc., as if we added that functionality, the pattern name would be webform-form--[machine_name].tpl.php.

Stupid drupal question, but is it possible to support both the single and double hyphen syntax in some way?

It's certainly very convenient to be able to have theme_hook_suggestions to allow for templates that can be named consistently across server deployments, but I completely understand about the patch breaking backwards compatibility for existing users.

Thanks much for your work on this module, BTW!

Stupid drupal question, but is it possible to support both the single and double hyphen syntax in some way?

Yes, it is I think. When we make this call:

  $default_template = theme(array('webform_mail_' . $node->nid, 'webform_mail', 'webform_mail_message'), array('node' => $node, 'email' => $email));

We'd need to include two suggestions, one with a single underscore and one with two:

  $default_template = theme(array('webform_mail__' . $node->nid, 'webform_mail_' . $node->nid, 'webform_mail', 'webform_mail_message'), array('node' => $node, 'email' => $email));

Likewise, our pattern would need to stay in place, but be updated like this:

    'webform_form' => array(
      'render element' => 'form',
      'template' => 'templates/webform-form',
      'pattern' => 'webform_form_[_]?[0-9]+',
    ),

Basically making the underscore optional.

So we can maintain backwards compatibility if we desire by adjusting our pattern matching and calls if that's our primary goal.

I'm not entirely sure how @SebCorbin's description of "it will always be taken into account" is a problem. I may need an example use-case in which the current approach is causing a problem.

From what I've seen @SebCorbin's statement is not completely true (but again, I say this not knowing enough about Drupal). Retaining the pattern, but keeping it more like the webform-mail pattern (ie., (_[0-9])?, I think would solve all cases. I've just tested it with the pattern you provided above and things are looking positive in the case of -form and -mail.

On an aside, I don't really understand how "pattern" is used. If I remove it from webform-form, and add a suggestion (per @SebCorbin's patch) it works, but not if i remove it from webform-mail. Obviously the pattern is being tied to the template somewhere that I'm missing.

Finally, it would be cool if there was a way to implement some test scripts to ensure that nothing breaks in the implementation given all the existing users.

On an aside, I don't really understand how "pattern" is used.

So "pattern" used to be required as far as I remember, but now it's automatic whenever you have a pattern with double underscores. If you have a pattern that doesn't use double underscores, then you have to manually specify the pattern matching.

@quicksketch

Yeah, check out https://api.drupal.org/api/drupal/modules!system!system.api.php/function...

Also the example in webform.module is pretty good

/**
 * Implements hook_theme().
 */
function webform_theme() {
  $theme = array(
    // webform.module.
    'webform_view' => array(
      'render element' => 'webform',
    ),
    'webform_view_messages' => array(
      'variables' => array('node' => NULL, 'teaser' => NULL, 'page' => NULL, 'submission_count' => NULL, 'user_limit_exceeded' => NULL, 'total_limit_exceeded' => NULL, 'allowed_roles' => NULL, 'closed' => NULL, 'cached' => NULL),
    ),
    'webform_form' => array(
      'render element' => 'form',
      'template' => 'templates/webform-form',
      'pattern' => 'webform_form_[0-9]+',
    ),
... snip snip snip...

At this point in 7.x development, I don't see this as a viable change. There doesn't seem to be much payback for the effort, and there are lots of theme functions already defined. If there is relevancy to 8.x, please re-open with the issues there.

Hi Dan:

Wow, three years ago and this patch is helping me today. I'm having a difficult time using theme level preprocess at this level. So I had to reroll this patch.

This is re-roll for #2 patch against Webform 4.16.

This is re-roll for #2 patch against Webform 4.17.

This is re-roll for #2 patch against Webform 4.21.