Override custom module template

Question

I created a custom module with its own template file to display the content with the following code.

function mymodule_theme($existing, $type, $theme, $path) {
  return [
    'theme_mymodule_list' => [
      'template' => 'templates/list_mymodule',
      // name of the template file, minus the '.tpl.php'

      // these are the template variables that will available to your template
      'variables' => [
        'myvar1' => NULL,
      ],
    ],

  ];
}

With the code above I'm able to get the template from the module directory (sites/all/modules/mymodule/templates/list_mymodule.tpl.php), but now I decided to make a theme for the site, and I want to override the custom module template file with the usual approach of copying-pasting the file into the theme and clear the cache.

How do I override the template used from a custom module from a theme?

Answer 1

What you describe is something that Drupal core already does. Take as example the Node module; it defines its own template file (node.tpl.php) that is then overridden from themes, such as the Bartik theme, with their own template file (in the case of the Bartik theme, with templates/node.tpl.php).

What is wrong in your implementation of hook_theme() is the name you give to the template file. Despite what it could seem, the template key doesn't allow to give the template name an arbitrary name; the name must match the theme name you are using, in your case mymodule_list. You can replace the underscores in the theme name with hyphens, but that is the only change you could do.

See Override template files based on template filename as well as hook name, where the user suggesting the change says:

Turns out the template file name needs to exactly match the array key used in hook_theme() (with the exception of dashes and underscores). In the case of my example, the template value would need to be my_abc_index and the file name my-abc-index.tpl.php. Failure to do so will result in an un-overridable template.

(I slightly changed formatting, and the spelling of a word.)

Also, as you see in the code used from Drupal core, the theme_ prefix in the the theme name is not necessary.

function node_theme() {
  return array(
    'node' => array(
      'render element' => 'elements',
      'template' => 'node',
    ),
    'node_search_admin' => array(
      'render element' => 'form',
    ),
    'node_add_list' => array(
      'variables' => array('content' => NULL),
      'file' => 'node.pages.inc',
    ),
    'node_preview' => array(
      'variables' => array('node' => NULL),
      'file' => 'node.pages.inc',
    ),
    'node_admin_overview' => array(
      'variables' => array('name' => NULL, 'type' => NULL),
      'file' => 'content_types.inc',
    ),
    'node_recent_block' => array(
      'variables' => array('nodes' => NULL),
    ),
    'node_recent_content' => array(
      'variables' => array('node' => NULL),
    ),
  );
}

Answer 2

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 theme_mymodule_list.tpl.php file within your theme. Maybe a good practice to name your template file the same as your theme definition.