Drupal 7 and using custom templates with theme()

Question

I have a list of items in the default main-menu. I am trying to override the template so I may iterate over each item and custom template/theme the entire menu.

echo theme('links', array('links' => menu_navigation_links('main-menu', 0)));

main-menu is the default menu ID drupal provides. The first param to theme is telling it to use the default "links" template - this much I understand. How do I tell it to use MY mainmenu.tpl.php that resides in mytheme directory?

I have tried creating a file named mainmenu.tpl.php and calling it with

theme('links__mainmenu.tpl.php')

So as to provide a fallback to default links in case mainmenu.tpl.php should every disappear. I am naming the files wrong or something and I cannot for the life of me figure it out. Help :)

Cheers, Alex

Courtney Christensen Courtney Christensen · Accepted Answer · 2011-01-20T18:14:30

A module's default theme is defined in the hook_theme method. This function allows you to declare theme files (.tpl.php) and the variables passed to them. To declare the default theme file, use the template field.

function hook_theme($existing, $type, $theme, $path) {
  return array(
    'mymodule_display' => array(        /* displayable name */
      'template' => 'mymodule_display', /* template file, leave off .tpl.php */
      'variable' => array(...),         /* associative array of vars used */
    )
  );
}

This link contains a more in depth example.

To invoke the module's default theme, use the theme() method, as shown in your original post. Something like:

<?php echo theme('mymodule_display', array(/* vars */));

The double-underscore is used for defining fallback themes, with the last one being preferred. Therefore, theme('links__mymodule_display', ...) means that Drupal will use the Links module theme only if mymodule_display cannot be resovled.

Drupal 7 and using custom templates with theme()

2 Answers