Improve documentation on the order of precedence of theme suggestions.

You'll need to remove the extra template from both the htmlmail module directory and your theme directory, if you're using an email theme.

Then you'll need to visit admin/config/development/performance and clear your cache.

If this doesn't work, then let me know, because something is broken and I need to fix it.

I should document this better.

If you have a file called htmlmail-user--password_reset.tpl.php in your e-mail theme directory, and it isn't getting used for password reset emails, then I want to hear about it.

The order of precedence should be:

1. $theme_directory/htmlmail--$module--$key.tpl.php
2. $module_directory/htmlmail--$module--$key.tpl.php
3. $theme_directory/htmlmail--$module.tpl.php
4. $module_directory/htmlmail--$module.tpl.php
5. $theme_directory/htmlmail.tpl.php
6. $module_directory/htmlmail.tpl.php

If that order is not being followed, please tell me and I'll try to fix the problem.

Isn't it a better idea to remove the htmlmail--user--password_reset.tpl.php file from the module entirely? This just serves as an example and places an additional burden on the users of the module.

I suspect the most common use case is to *not* have a customized user password email. To make this use case work as expected there are two options now:

1. Remove the template file from the module folder. This is an additional step to take when installing the module, and as it needs to be redone on every module update it adds maintenance complexity.
2. Maintain a separate template file in the theme folder, which adds unneeded extra work whenever changes are done to the email template.

I would not throw away this file, as it is useful as an example. But a better home for it would be inside a documentation page, and not in the module folder.

Or maybe an examples folder.

Isn't it just weird that templates in the module folder get preferred over the template folder? It shouldn't be necessary to change the module folder. Now I need to remove all template files from there to use a htmlmail.tpl.php in my theme folder.

Why not only search the module folder after all tries in the theme folder have failed? That would be a lot more logical and more in line with other systems.

The Module folder shouldn't be edited.

I completely agree with #8. Hacking a contrib module should not be necessary to achieve obvious functionality. Can you imagine if core shipped with a node--article.tpl.php that overrode node.tpl.php in a custom theme, and the SOP was to hack core to delete that template? It would never happen, because of https://www.drupal.org/best-practices/do-not-hack-core.

Hacking contrib is a very small step down from hacking core - many of the same reasons from that link apply:

Doing so will make it complicated, difficult or near impossible to apply site updates such as Security and bug fixes.

You will make it difficult for those that come after to maintain the site.

You could possibly leave your site vulnerable to exploits.

Contrib modules are supposed to allow their functionality to be modified with strategic use of hooks and templates, not "well, just delete this file".

To that end, here's a patch that removes all templates other than htmlmail.tpl.php from the htmlmail module.

Setting to needs review.

I agree with #6 and #7:

I would not throw away this file, as it is useful as an example. But a better home for it would be inside a documentation page, and not in the module folder.

Or maybe an examples folder.

I also agree with the reasoning in #9, but...

1. diff --git a/htmlmail--htmlmail.tpl.php b/htmlmail--htmlmail.tpl.php
   deleted file mode 100644
   

2. diff --git a/htmlmail--simplenews.tpl.php b/htmlmail--simplenews.tpl.php
   deleted file mode 100644
   

3. diff --git a/htmlmail--user--password_reset.tpl.php b/htmlmail--user--password_reset.tpl.php
   deleted file mode 100644
   

I disagree with throwing away these files.

Will Drupal still find the templates recursively under the module folder, say, if they're in an 'example-templates' folder? If yes, then we could rename them by appending '.example' to the file names.

HOWEVER: We have a major problem which is that some sites may have come to rely on these templates, and we must not break them inadvertently. I acknowledge that this is an issue for you, but simply shifting the burden to someone else is not the solution.

I see one way out of the dilemma: write a hook_update_NNN() function to check the theme registry to find out whether any of these templates are being used, and if they are, then alert the user that they've been moved/renamed and tell them what they need to do to restore the theming that they had before.

I think it will recursively find the files, yes, but appending .example should stop it from finding them.

I think your idea of implementing hook_update_N is a good one. I think many users would still miss it and complain, though. This just isn't a great situation to be in.

Maybe this needs to wait for a version jump, to 7.x-3.x perhaps?