Drupal 7 Module Development

Theming a Module
Theming a Drupal block
So, now that we know how to get all our data, we need to decide how
we're going to theme it. We're actually going to build three versions of our
single_blog_block_view(). This will allow us to try out several different methods
of theming and to apply all the aspects of the theme layer we learned in Chapter 3.
Looking back at the previous table, Common theme hooks, will help us decide which
existing theme hooks would be good candidates for our data. Initially, we're creating
a list of links to our blog posts, so theme_links() would actually be a perfect match.
However, in the next iteration of our hook_block_view() function we're going to
create more then a simple list of links, so let's look again. The item_list hook will
allow us to create a list that contains arbitrary data.
// Theme the list of blog entries.
$block['content'] = theme('item_list', array('items' => $items));
By looking at the documentation for theme_item_list() (available at
http://api.drupal.org/api/function/theme_item_list/7) we can see that it
expects as a parameter an items array. Each list item can be a simple string or the
string can be placed in the data key of an array in which the other keys are treated
as attributes for the list item:
$items[] = array(
'data' => l($node->title, 'node/' . $node->nid),
'class' => array('node-' . $node->nid),
);
On the surface, this construct looks similar to the Render API, but this is simply the
convention used by this theme function; it doesn't use drupal_render() to convert
the array to a string.
The internal path to a node is always "node/[node ID]". Fortunately, even if the
author gives the blog post a URL alias, we don't have to figure out the alias as the
l() function will automatically rewrite it to use the proper URL. So with the l()
function, we're taking each node's title and node ID and constructing a simple link
to the node and placing it in the list item's data element. theme_item_list() treats
the class element as an attribute for the wrapping element.
Okay. We've finished our first draft of our module. Looking at the following
screenshot, you can see that our block displays as a simple unordered list of node
titles. If this were a Drupal 6 theme implementation, we'd be done! However, in
Drupal 7, all hook_block_view() and all page callbacks (the functions that return
the main contents of a page) should return a renderable array instead of a string.
So, while our code works (since Drupal 7 considers a plain string to be a degenerate
renderable array), we'll need to fix that minor flaw in our second draft.
[ 98 ]