Documentation Level: 

Normally template files (*.tpl.php) reside in a theme. But sometimes modules may need to override template files provided by Backdrop or another contrib project. Here's how a module can override a template file...

First, copy the template file you wish to override into your module directory. Putting it into a dedicated 'templates' sub-folder is recommended. For example:


The next step is to tell the theme system to look there. Copy the following function into your *.module file, editing as necessary:

* Implements hook_theme_registry_alter().
function my_module_theme_registry_alter(&$theme_registry) {
  // Defined path to the current module's 'templates' directory.
  $module_path = backdrop_get_path('module', 'my_module') . '/templates';

  // Find all *.tpl.php files in this module's 'templates' folder recursively.
  $template_file_objects = backdrop_find_theme_templates($theme_registry, '.tpl.php', $module_path);

  // Iterate through all found template file objects.
  foreach ($template_file_objects as $key => $template_file_object) {
    // If the template has not already been overridden by a theme...
    if (!isset($theme_registry[$key]['theme path']) || !preg_match('#/themes/#', $theme_registry[$key]['theme path'])) {
      // Alter the theme path and template elements.
      $theme_registry[$key]['theme path'] = $module_path;
      $theme_registry[$key] = array_merge($theme_registry[$key], $template_file_object);
      $theme_registry[$key]['type'] = 'module';