Drupal 8, override template menu in custom module doesn't work, theme template is called instead

Question

I Want create a custom module with custom template for override a menu created from the back office administration. I don't want put my custom template in the theme, I want put this file in my custom module (in custommodule/templates/..)

1) I activated twig debug, I can see what is the suggested template menu name : (menu--main.html.twig)

2) I added in my custom .module file the hook theme :

function custommodule_menu_theme($existing, $type, $theme, $path)
{
  return array(
    'menu__main' => array(
      'base hook' => 'menu',
      // 'render element' => 'menu', // I tried this, nothing change
      // 'template' => 'menu--main', // I tried this, nothing change
    ),
  );
}

3) From my custommodule, I created a directory 'templates'. In this directory, I add the twig file menu--main.html.twig :

<h1> Hello ! <h1>

4) I cleared caches (drush cr)

5) I reloaded the page from my browser. I noticed my custom template isn't called. And if I look in the html structure page, I see :

Why this is the template from the global theme called ? and not my templates/main--menu.html.twig ? I don't understand..

UP

My new code :

function custommodule_theme($existing, $type, $theme, $path) {
  $theme=array();
  $theme['menu__main'] = array(
    'base hook' => 'menu',
    'render element' => 'menu',
      );
  return $theme;
}

But my custommodule/templates/menu--main.html.twig is still not called (I cleared caches). My page always uses the themes/boostrap/templates/menu/menu--main.html.twig in the

Answer 1

Your module function custommodule_menu_theme() is incorrectly named so hook_theme() isn't evoked and returning incomplete output; it needs, at least, the base hook & render element elements entered so that it knows what hook to target and the render array to supply to the template.

/**
 * Implements hook_theme().
 */
function custommodule_theme($existing, $type, $theme, $path) {
  $theme = array();
  $theme['menu__main'] = array(
    'base hook' => 'menu',
    'render element' => 'menu',
  );
  return $theme;
}

Answer 2

A theme will always win over a module when it comes to theming. So you need to either

• remove template from theme (so your module's template will be used.
• create a custom template suggestion for the main menu that only your module has using hook_theme_suggestions_HOOK_alter
• Modify the theme registry to let your module win using hook_theme_registry_alter

Of the 3 I would suggest going for option 2, as it is the most flexible one (themes could overwrite the module defined template if needed).

Also remember that the template suggestion can be anything, but your module needs to implement hook_theme to register the template.