Override module's template in theme

Question

Suppose i have this hook_theme() in my module, choosing a template inside the module:

/**
 * Implements hook_theme().
 */
 function module_theme($existing, $type, $theme, $path) {
   return array(
     'module-output' => array(
       'template'  => 'output-template',
       'variables' => array(),
   ),
 }

If i put the same output-template.tpl.php inside my active theme, Drupal picks up the module's template.

Is there a way to make Drupal understand that if a template with the same filename exists somewhere in the theme, to pick the theme's template and not the module's (like an override)?

Answer 1

You can override tpl files defined in modules inside your active theme (under the templates directory). But Drupal will look for a file name using the defined theme key name and not the defined template file.

In your case, you should create a module-output.tpl.php file within your theme. Maybe a good practice to name your template file the same as your theme definition.

Answer 2

Just to mention here that you can even change the template file name also if you implement template_preprocess_page() for your theme.

So, you can add a new theme suggestion like this:

/**
 * Implements template_preprocess_page().
 */
function YOURTHEMENAME_preprocess_page(&$variables) {
  // Let's assume your tpl file is page--home.tpl.php.
  $variables['theme_hook_suggestions'][] = 'page__home';
}

Also you can re-order the priority of these theme suggestion as per your needs.

But you should think to write a semantic code as you can.

I usually add new theme suggestion when the client asks to use the front page.tpl for all static page content type like this way:

// Check if this page has defined node object or not.
if(isset($vars['node']) && isset($vars['node']->type) && ($vars['node']->type == 'page')){
  // Make all page nodes wear page--home.tpl.php.
  $vars['theme_hook_suggestions'][] = 'page__home';
}

Good luck!