Having trouble understanding hook_theme()

Question

I'm going through the Drupalize.me tutorials on module development, but I've come across something that has me a little stumped. In the module, called "spy_glass", we created a basic theme hook like so:

function spy_glass_theme() {
  return array(
   'spy_glass_item' => array(
       'arguments' => array('title' => NULL, 'data' => NULL),
       'template' => 'spy-glass-item',
    ),
  );
}

Which is all well and good. It eventually gets called by spy_glass_page() which uses the theme hook to create to loop through an $information array, which is formed elsewhere and consists of 2 keys: title, and data.

function spy_glass_page($node) {
    $information = _spy_glass_serious_spying_business($node);

    $content = array();
    foreach ($information as $item) {
        $content[] = array(
            '#type' => 'markup',
            '#markup' => theme('spy_glass_item', $item),
        );
    }
    return $content;
 }

All good. Everything works as expected later when its passed to a spy_glass_preprocess_spy_glass_item() function and printed to a template. But here's what I don't understand. What the heck is this line of code doing in spy_glass_theme():

 'arguments' => array('title' => NULL, 'data' => NULL),

I've removed it and it literally changed nothing at all. Everything still works perfectly. What is the purpose of this?

Answer 1

I think this is a typo on your part or Drupalize.me. You should supply a variables array that defines the default values of the variables passed to your theme function if the calling function does not supply them. It's not necessary, but seems to be good practice to NULL at least title and data.

From the api:

variables: (see above) Each array key is the name of the variable, and the value given is used as the default value if the function calling theme() does not supply it. Template implementations receive each array key as a variable in the template file (so they must be legal PHP variable names). Function implementations are passed the variables in a single $variables function argument.

function spy_glass_theme() {
  return array(
   'spy_glass_item' => array(
     'variables' => array('title' => NULL, 'data' => NULL),
     'template' => 'spy-glass-item',
    ),
  );
}

And then your theme function:

function theme_spy_glass_item($variables) {
  $title = $variables['title'];
  $data = $variables['data'];
}

Or, if you're using .tpl.php, you simply have access to the variables $title and $data.