Drupal theme functions workflow in module

Question

I am a bit newbie in Drupal theming and I can't get one detail in Forum modules theming.

forum.module file contains forum_theme function that controls how this module is themed and has this line

function forum_theme() {
......
'forum_list' => array(
  'template' => 'forum-list',
  'arguments' => array('forums' => NULL, 'parents' => NULL, 'tid' => NULL),
),

I also see forum-list.tpl.php file in forum directory, so I start to wonder when this file is called and where it gets data from, but all I can find in forum.module is this function.

function template_preprocess_forum_list(&$variables) 

Am I missing something? So in general my question is who and when invokes custom registered theme function, like forum_list

Answer 1

Simple answer is if you in your theme directory put mytheme-forum-list.tpl.php (where mytheme is the name of your theme) and customise it drupal should pick it up (clear the cache first).

This line in template_preprocess_forum calls the Drupal theme function

$variables['forums'] = theme('forum_list',
                              $variables['forums'],
                              $variables['parents'],
                              $variables['tid']);

This will reference the line in forum_theme()

  'forum_list' => array(
      'template' => 'forum-list',
      'arguments' => array('forums' => NULL, 'parents' => NULL, 'tid' => NULL),
    ),

Which tells the templating enging to look for forum-list.php and provides arguments.

If you install the devel module and turn on the theme developer module. This will show you all of the candidate templates and functions which Drupal will look for when rendering content.

In general (but with specific exceptions) Drupal looks for the best match template and falls back to the pre defined functions.

if there is nothing that matches. Have a look at the theme guide and in specific the section on Overriding themable output you may also find hook_theme of interest.