Provide pattern and suggestion theme templates from a module

Pattern and suggestion theme template can reside in the theme directory only. What if you want to provide pre-built override templates out of your module and not require copying them into the theme directory. This way, module is self contain and theme can be left untouched. This makes installing and upgrading theme and module easier. Of course, user can still override these template inside theme. Here is the code to make this happen:

function hddigitalworks_theme_registry_alter(&$theme_registry) {
  $my_path = drupal_get_path('module', 'hddigitalworks');
  
  // make pattern template from our module take effect
  // if no theme provide such.
  $theme_registry_copy = $theme_registry;       // munge on a copy
  // pretend we are a theme and tell it to work on it
  // this will discover pattern hooks in our module directory
  _theme_process_registry($theme_registry_copy, 'phptemplate', 'theme_engine', 'hddigitalworks', $my_path);
  // add only the newly discover hooks 
  $theme_registry += array_diff_key($theme_registry_copy, $theme_registry);
  
  // the following make our moudule available for alternate suggestion template search
  // insert our module path at second spot behind hook definer so
  // theme suggestion tamplate take priority
  $hooks = array('node');
  foreach ($hooks as $h) {
    _hddigitalworks_insert_after_first_element($theme_registry[$h]['theme paths'], $my_path);
  }
}


function _hddigitalworks_insert_after_first_element(&$a, $element) {
  $first_element = array_shift($a);
  array_unshift($a, $first_element, $element);
}

I'm using the theme_registry_alter() to alter the theme registry to include the pattern template from our module. The key is line 9 call to _theme_process_registry(). This function takes the theme registry, the type, name and directory of a theme or module, and scans the given directory for theme hook function or template override, and of particular interest here, does pattern template expansion. It will update the theme registry (pass by reference). We just pretend our module is a theme and tell tell this function to process it. On line 11 we bring in only the newly discover hooks while leaving existing one untouched by not replacing any hooks that already exist before our module directory was processed. Next in line 16-19 adds our module path to the suggestion templates search path. With this, suggestion templates can come out of the module directory. The new path is added at the right place so that theme retains precedent. The _theme_process_registry() is normally off limit for non-core code. But it's unlikely this function all the sudden change or disappear within one Drupal version. So what's the difference between pattern template and template suggestions? They both serves the same purpose: enable template override a given theme hook. The reason to use pattern template is probably performance. Pattern template hook is pre-computed and stored in the theme registry so using it is very fast. Whereas template suggestion must be searched for each time the hook is used. So for theme hook that can be used many many times per page render, then pattern template is better. I suspect this is probably the reason merlinofchaos invented pattern template for used in Views2. I've not seen much information about pattern template theme hook. The hook_theme() api doc describes the 'pattern' key but doesn't go in any details. the views module is a very good place to learn how to create and use pattern template hooks. Pattern template theme hooks move the suggestion template search to theme registry build, eliminating this overhead during actual use. Just by have template file match the expression of a pattern template theme hook, a new theme hook is created.