Drupal 7 Module Development

Chapter 3
Second, the theme function will only have a single parameter, as follows:
function theme_THEME_HOOK_NAME($variables) {…}
The theme function variables are an associative array containing the pieces of data
we wish to markup and any options we want to pass to the function. It may seem
extremely odd not to use multiple parameters and PHP's ability to specify default
values for each parameter. In fact, previous versions of Drupal did use multiple
parameters. We'll see why Drupal now only uses one parameter in just a moment
when we talk about preprocess functions.
For an example of a $variables array, let's look at how the DocBlock of the
theme_item_list() function defines it:
• Items: An array of items to be displayed in the list. If an item is a string, then
it is used as is. If an item is an array, then the "data" element of the array is
used as the contents of the list item. If an item is an array with a "children"
element, those children are displayed in a nested list. All other elements are
treated as attributes of the list item element.
• Title: The title of the list.
• Type: The type of list to return (e.g. ul, ol).
• Attributes: The attributes applied to the list element.
The items and title keys hold the actual data, and the type and attributes keys
are options that specify how to build the item list.
Third, the theme function should return a string that contains the rendered
representation of the data. This is usually a string of HTML, but some theme hooks
return other types of themed markup. For example, theme_syslog_format returns
a simple string with pipe-separated data values for use in a *NIX syslog error log.
That's it! As you can see, theme functions have very simple requirements and in
every other way are standard PHP functions.
The major difference between most functions and theme functions is that you should
never call theme functions directly. It may be tempting to take your data and call
theme_item_list($vars) directly, but you should instead call theme("item_list",
$vars). This method of calling theme functions indirectly ensures that themes are
able to override any module's default theme function (or template). It also allows the
theme() function to work additional magic, including allowing other modules to alter
the theme function's variables before they are used.
[ 67 ]