theme

Generates the themed output.

All requests for theme hooks must go through this function. It examines the request and routes it to the appropriate theme function. The theme registry is checked to determine which implementation to use, which may be a function or a template.

If the implementation is a function, it is executed and its return value passed along.

If the implementation is a template, the arguments are converted to a $variables array. This array is then modified by the module implementing the hook, theme engine (if applicable) and the theme. The following functions may be used to modify the $variables array. They are processed in this order when available:

• template_preprocess(&$variables, $hook) This sets a default set of variables for all template implementations.

• template_preprocess_HOOK(&$variables) This is the first preprocessor called specific to the hook; it should be implemented by the module that registers it.

• MODULE_preprocess(&$variables, $hook) This will be called for all templates; it should only be used if there is a real need. It's purpose is similar to template_preprocess().

• MODULE_preprocess_HOOK(&$variables) This is for modules that want to alter or provide extra variables for theming hooks not registered to itself. For example, if a module named "foo" wanted to alter the $submitted variable for the hook "node" a preprocess function of foo_preprocess_node() can be created to intercept and alter the variable.

• ENGINE_engine_preprocess(&$variables, $hook) This function should only be implemented by theme engines and exists so that it can set necessary variables for all hooks.

• ENGINE_engine_preprocess_HOOK(&$variables) This is the same as the previous function, but it is called for a single theming hook.

• ENGINE_preprocess(&$variables, $hook) This is meant to be used by themes that utilize a theme engine. It is provided so that the preprocessor is not locked into a specific theme. This makes it easy to share and transport code but theme authors must be careful to prevent fatal re-declaration errors when using sub-themes that have their own preprocessor named exactly the same as its base theme. In the default theme engine (PHPTemplate), sub-themes will load their own template.php file in addition to the one used for its parent theme. This increases the risk for these errors. A good practice is to use the engine name for the base theme and the theme name for the sub-themes to minimize this possibility.

• ENGINE_preprocess_HOOK(&$variables) The same applies from the previous function, but it is called for a specific hook.

• THEME_preprocess(&$variables, $hook) These functions are based upon the raw theme; they should primarily be used by themes that do not use an engine or by sub-themes. It serves the same purpose as ENGINE_preprocess().

• THEME_preprocess_HOOK(&$variables) The same applies from the previous function, but it is called for a specific hook.

There are two special variables that these hooks can set: 'template_file' and 'template_files'. These will be merged together to form a list of 'suggested' alternate template files to use, in reverse order of priority. template_file will always be a higher priority than items in template_files. theme() will then look for these files, one at a time, and use the first one that exists.

Parameters

$hook: The name of the theme function to call. May be an array, in which case the first hook that actually has an implementation registered will be used. This can be used to choose 'fallback' theme implementations, so that if the specific theme hook isn't implemented anywhere, a more generic one will be used. This can allow themes to create specific theme implementations for named objects.

...: Additional arguments to pass along to the theme function.

Return value

An HTML string that generates the themed output.

220 calls to theme()

29 string references to 'theme'

File

includes/theme.inc, line 613

The theme system, which controls the output of Drupal.

Code

function theme() {
  $args = func_get_args();
  $hook = array_shift($args);

  static $hooks = NULL;
  if (!isset($hooks)) {
    init_theme();
    $hooks = theme_get_registry();
  }

  if (is_array($hook)) {
    foreach ($hook as $candidate) {
      if (isset($hooks[$candidate])) {
        break;
      }
    }
    $hook = $candidate;
  }

  if (!isset($hooks[$hook])) {
    return;
  }

  $info = $hooks[$hook];
  global $theme_path;
  $temp = $theme_path;
  // point path_to_theme() to the currently used theme path:
  $theme_path = $hooks[$hook]['theme path'];

  // Include a file if the theme function or preprocess function is held elsewhere.
  if (!empty($info['include files'])) {
    foreach ($info['include files'] as $include_file) {
      include_once($include_file);
    }
  }

  // Handle compatibility with theme_registry_alters to prevent failures.
  if (!empty($info['file'])) {
    static $included_files = array();
    $include_file = $info['file'];
    if (!empty($info['path'])) {
      $include_file = $info['path'] . '/' . $include_file;
    }

    if (empty($included_files[$include_file])) {
      // Statically cache files we've already tried to include so we don't
      // run unnecessary file_exists calls.
      $included_files[$include_file] = TRUE;
      if (file_exists('./' . $include_file)) {
        include_once('./' . $include_file);
      }
    }
  }

  if (isset($info['function'])) {
    // The theme call is a function.
    $output = call_user_func_array($info['function'], $args);
  }
  else {
    // The theme call is a template.
    $variables = array(
      'template_files' => array(),
    );
    if (!empty($info['arguments'])) {
      $count = 0;
      foreach ($info['arguments'] as $name => $default) {
        $variables[$name] = isset($args[$count]) ? $args[$count] : $default;
        $count++;
      }
    }

    // default render function and extension.
    $render_function = 'theme_render_template';
    $extension = '.tpl.php';

    // Run through the theme engine variables, if necessary
    global $theme_engine;
    if (isset($theme_engine)) {
      // If theme or theme engine is implementing this, it may have
      // a different extension and a different renderer.
      if ($hooks[$hook]['type'] != 'module') {
        if (function_exists($theme_engine . '_render_template')) {
          $render_function = $theme_engine . '_render_template';
        }
        $extension_function = $theme_engine . '_extension';
        if (function_exists($extension_function)) {
          $extension = $extension_function();
        }
      }
    }

    if (isset($info['preprocess functions']) && is_array($info['preprocess functions'])) {
      // This construct ensures that we can keep a reference through
      // call_user_func_array.
      $args = array(&$variables, $hook);
      foreach ($info['preprocess functions'] as $preprocess_function) {
        if (function_exists($preprocess_function)) {
          call_user_func_array($preprocess_function, $args);
        }
      }
    }

    // Get suggestions for alternate templates out of the variables
    // that were set. This lets us dynamically choose a template
    // from a list. The order is FILO, so this array is ordered from
    // least appropriate first to most appropriate last.
    $suggestions = array();

    if (isset($variables['template_files'])) {
      $suggestions = $variables['template_files'];
    }
    if (isset($variables['template_file'])) {
      $suggestions[] = $variables['template_file'];
    }

    if ($suggestions) {
      $template_file = drupal_discover_template($info['theme paths'], $suggestions, $extension);
    }

    if (empty($template_file)) {
      $template_file = $hooks[$hook]['template'] . $extension;
      if (isset($hooks[$hook]['path'])) {
        $template_file = $hooks[$hook]['path'] . '/' . $template_file;
      }
    }
    $output = $render_function($template_file, $variables);
  }
  // restore path_to_theme()
  $theme_path = $temp;
  // Add final markup to the full page.
  if ($hook == 'page' || $hook == 'book_export_html') {
    $output = drupal_final_markup($output);
  }
  return $output;
}