Yesterday we added permission so only authenticated users will be able to access our test page. Today we're moving on to introducing theming and templates. Up until now, you'll notice that we're generating our test page's html code inside the function dfacebox_test_form. This is valid, but instead we're going to take advantage of Drupal's theming capabilities.

For Drupal to be able to recognize our theming function, we need to implement hook_theme. It returns an array of theming function together with its arguments.

/**
  * Implementation of hook_theme()
  */
function dfacebox_theme() {
  return array( 'test_page' => array(
      'arguments' => array('items' => NULL),
    ),
  );
}

Here you'll see that test_page is the name of our function and it accepts one argument named items. The next step is to define the function itself:

/**
 * The theming function for test_page
 */
function theme_test_page($items) {
  $out = '<fieldset>
            <legend>'. $items[0][0] .'</legend>
            '. $items[0][1] .'
          </fieldset>
          <fieldset>
            <legend>'. $items[1][0] .'</legend>
            <a href="#add-user" rel="facebox">
              Add User
            </a>
            <div id="add-user" style="display: none;">'. $items[1][1] .'</div>
          </fieldset>';
  return $out;
}

In defining a theming function, you prefix your function name with 'theme_'. Our function simply accepts an array named items and then build-up the html code and returns it. Now you might be thinking thats too much work just to wrap our tags on another function again. True, but with this one we can use Drupal's theme function and we actually register our function to Drupal's theme registry.

Now we can stop right here but I wanna show you a simple use of Drupal's templates. First, we're going modify our hook_theme to look like this:

/**
 * Implementation of hook_theme()
 */
function dfacebox_theme() {
  return array(
    'test_page'   => array(
      'arguments' => array('items' => NULL),
      'template'  => 'test-page',
      'path'      => MODULE_PATH .'/templates',
    ),
  );
}

Here we added templates and path key, template is the name of the template file and path is where this templates resides. We can omit path if the template lies on the root folder of our module but to organize things we're going to put it inside a templates folder. Drupal's default templating engine is phptemplate, and all templates files in phptemplate ends with .tpl.php. Notice that we don't have to include it when specifying the template name. We can also get rid of our theme_test_page function since the tags will be inside our template file.

Create the templates folder inside your dfacebox module folder and create a test-page.tpl.php file inside it. We're going to store all the html tags in our template file.

Also notice that whatever the name of the argument we specify on our hook_theme (in this case items), becomes a local variable inside our template file and we can just access it directly. Now try accessing the test page again, you probably won't notice any changed but if it displays and no errors appear then its working. If you happen to have any errors, make sure to empty your cache to by going to admin/settings/performance to rebuild Drupal's theme registry.

All this time we've been dealing with hooks, we haven't actually take a look at Drupal's node objects. Hopefully we can tackle it on my next post. Till then!