Annoyingly, there's no function in Drupal 5 to grab a block and render it. You can render a region, a block container which then makes a number of decisions for you about what blocks should appear in it. Blocks can in principle be uniquely identified by (a) the module which provides the block through its implementation of hook_block() and (b) the "delta", the unique (potentially non-numeric) ID for each block in a given module. Yet there are no functions in the core block module to handle this.

One option is to move to Panels, which I'm doing for this site. Yet if your existing site is heavily based around blocks and regions, implementing Panels can be a lot of overhead just to render a single block in a template.

Here's a function which returns a single block, given the module name and block delta. It's an abstraction from block_list(), the function which returns all the blocks in a given region. You can put this in a shell module with an info file (see the previous post on theme preprocess hooks in Drupal 5 for how to quickly set up an otherwise empty module) or if you're not comfortable with that you can always name it accordingly and put it in template.php

/**
 * Get a single block for themeing
 */
function mymodule_get_block($module, $delta) {
  // User roles mean blocks are still invisible if the user
  // isn't permitted to see them
  global $user;
  $rids = array_keys($user->roles);
  $placeholders = implode(',', array_fill(0, count($rids), '%d'));
 
  // This is still cropped from block_list() , but newlines added
  // for legibility and blogposting
  $result = db_query(
      "SELECT DISTINCT b.* "
    . " FROM {blocks} b LEFT JOIN {blocks_roles} r "
    . "   ON b.module = r.module AND b.delta = r.delta "
    . " WHERE (r.rid IN ($placeholders) OR r.rid IS NULL) "
    . "   AND b.module = '%s' "
    . "   AND b.delta = '%s' "
    . " ORDER BY b.region, b.weight, b.module", 
    array_merge($rids, array($module,$delta)));
 
  // Assemble block info from the module
  while ($block = db_fetch_object($result)) {
    // Invoke the block hook in the supporting 
    // module and convert the return array
    $array = module_invoke($block->module, 'block', 'view', $block->delta);
    if (isset($array) && is_array($array)) {
      foreach ($array as $k => $v) {
        $block->$k = $v;
      }
    }
 
    // Swap in any user-defined title in admin interface
    if ($block->title) {
      $block->subject = $block->title == '<none>' ? '' : check_plain($block->title);
    }
 
    return $block;
  }
}

Once this is safely out of the way you can grab and render a block. The following code grabs the fourth block that you ever created through the block admin interface (the "block" module is the "maintainer" of those blocks, and the blocks are numbered starting at zero, hence "3"):

<?php print theme('block', mymodule_get_block('block', 3)); ?>

This is a bit unsafe, though. What if you disable mymodule? The template will break, and depending on your server configuration your visitors might see a pretty ugly error. So use the theme preprocess hooks trick. If you want the block to show in node.tpl.php then you're going to have to bite the bullet and put the bigger code snippet above in a module. Then, in the same module, you can write a hook_preprocess_node as follows:

function mymodule_preprocess_node(&$vars) {
  $vars['myblock'] = theme('block', mymodule_get_block('block', 3));
}

Then you can put just the bare variable in your node.tpl.php, which is much safer:

<?php print $myblock ?>

Turn off mymodule, and this just prints an empty string.

So, ta-da, blocks are now better exposed in your Drupal backend, for you to use in different places in your themeing. Unfortunately that still doesn't make them first-class citizens: they can't be categorized or given an "owner" i.e. an associated user ID; they can't be made to link to nodes in the same robust way that nodes can link to each other with node reference; they certainly can't have any CCK fields hung off them. But, humble though blocks are, they've still got some life left in them yet.

Drupal 5 doesn't have any preprocess hooks, unfortunately. All it has is the function _phptemplate_variables() in your theme's template.php. That's the sole instance of theme preprocessing in D5, and this bottlenecking means that the function quickly becomes the dumping ground for all of your site's pre-theme logic. Even if you're a module developer, of any level of experience, there's no incentive to factor this code out elsewhere: you just replace it with whatever the module function's called anyway, and your site becomes more brittle because of it.

With that in mind, here's how to free up your D5 theme preprocessing in a reasonably Drupalish manner. We'll use a helper module, and call a single function, safely from within your template.php. That function will replicate the basics of D6's theme preprocessing and let you start writing D5 modules with preprocess logic in them.

helpd6.info

First your helper module needs a .info file. It doesn't need to have very much details in it, but here's a sample file:

name = D6 forward-compatibility functions
description =  D6 functions, like theme preprocessing

helpd6.module

Next, here's the module in its entirety. Once you've saved this and the .info file into a directory called helpd6, in your site's modules directory, you should be able to enable the module in your Drupal administrative pages.

<?php
/**
 * Implementation of basic theme preprocessing
 */
function helpd6_implement_preprocess(&$vars, $hook) {
  // module_invoke_all passes by value
  // So assemble function name and invoke ourselves to pass by reference
  foreach(array('preprocess', "preprocess_$hook") as $stub) {
    foreach(module_implements($stub) as $mod) {
      $fn = $mod . "_$stub";
      $fn($vars, $hook);
    }
  }
}

Note we omit the closing PHP tag. And note also that we put an ampersand by $vars. This means we get the "real" theme variables object to play with, not a copy, so that all our logic can modify that "real" variables object and it's reflected by the time Drupal gets round to themeing.

template.php (excerpt)

Finally, this snippet ties everything together: it calls your helper module from the theme's template.php. Put it at the very end of the _phptemplate_variables() function:

function _phptemplate_variables($hook, &$vars = array()) {
  // ...
 
  // Finally, run preprocess hook functions
  function_exists('helpd6_implement_preprocess') 
    && helpd6_implement_preprocess($vars, $hook);
 
  // Now return variables
  return $vars;
}

You'll see that it checks the function exists first. You could check with module_exists('helpd6') too, but we're aiming for as robust a setup as possible, so best check the function exists rather than the general module.

We also return the variables. In practice, referring to &$vars in the function declaration means they get merged in situ, but in principle the function's definition on api.drupal.org requires the variables array to be returned. So changes inthe PHPTemplate engine might stop the &$vars trick working in the future.

Implementation

You can now implement either hook_preprocess or hook_preprocess_TYPE hooks e.g. hook_preprocess_page. These behave pretty much exactly the same as Drupal 6 preprocess hooks.

As an example, let's say that some nodes on your site have an "author" field. This might be different from Drupal's concept of node author e.g: the node might be created by an admin user, but contain information for a book or other publication; the book itself has an author, who could be anybody in the world, alive or dead. Our site also contains a biography node for each author, so we'd like to have the relevant biography present in the theme layer, to list the biography alongside the book.

Here's a "module"---again, just a single function---that accomplishes just that with the aid of our helpd6 module. It should be self-explanatory, but have a look at the comments for more details.

<?php
/**
 * Implementation of hook_preprocess_node
 */
function authorbiog_preprocess_node(&$vars) {
  // Two possible sources for a biography node:
  // 1. the author is a site user - CCK user ref field
  // 2. otherwise, use a CCK node ref field
  $this_node = $vars['node'];
  $author_uid = $this_node->field_drupal_author[0]['uid'];
  $author_nid = $this_node->field_offsite_author[0]['nid'];
 
  // Load the author's biog into the theme variables
  // (Could use Content Profile to help with this)
  if ($author_uid) {
    $biog = node_load(array('uid' =>$author_uid, 'type' => 'biography'));
  }
  else if ($author_nid) {
    $biog = node_load($author_nid);
  }
 
  // Theme preprocess hooks should ALWAYS make the HTML safe
  // Don't rely on .tpl.php files to filter out possible bad markup
  $biog && ($vars['biog'] = check_markup($biog->body, $biog->format));
 
  // &$vars has been passed by reference, so we don't return anything
  // But you can now access the biog (if it exists) in node.tpl.php as "$biog"
}

You can now access the biography text in the theme layer. Note we don't pass down the whole node: we could, but it's safer to pass down filtered HTML, to avoid any possible security holes. In general, it's the job of theme preprocess hooks to handle HTML security, because you never know where else that HTML is going to end up being rendered.

What's important to remember is that this code, and many other snippets like it, need no longer live in your template.php. It's now in a module. It's something you can turn on and off, just like a module. And it's something your themer need never worry about: that logic is now safely hidden behind the scenes, leaving template.php as a theme helper, what it's meant to be. You don't even need any control logic to determine $hook, because module_implements() and the naming conventions do that for you.

Summary

Drupal 5 themeing will never be as versatile as Drupal 6 themeing. But standard code patterns---especially "Drupalish" ones---can go a long way to abstracting out into modules much of the theme preprocessing that Drupal 5 would otherwise force you to do in your theme layer. The more logic you move out of your theme, the more robust it gets, and the easier it is for a non-developer to maintain.

Regions and blocks have serious limitations, though. For example, any one block---say the most recent posts from the blog, or a feed from Twitter---can only be placed in one region, although it can then be made to appear and disappear on other pages based on URL or (dangerously) bespoke PHP embedded in the database. There are modules which replicate blocks, to try to circumvent such problems. Following merlinofchaos' great talk at, once again, DrupalCon Paris 2009, I decided to use Panels and panes instead of the core Drupal region/block system.

It was touch and go initially as to whether I was going to scrap it all and start again with blocks and regions or not. I managed fairly quickly to assemble custom pages for nodes of a few different types, but then had real trouble working out the subtleties of getting custom pages together for existing non-single-node content. Panels and its associated CTools developer framework concentrate far more on front-end functionality than ease of backend user experience. That's a shame, as the most important take-home message of prioritizing user experience is that hidden functionality might as well be no functionality at all. But as with most of these things---api.drupal.org springs to mind here---the first time is the worst, and once you know what you doing, you, well, know what you're doing.

Panels lets you divide up a page into just those panels. A set of standard URL matches come with Panels as "pages" you can enable, but you can also add new pages at new URLs. In terms familiar to Drupal templaters they take over the $content variable in the page templates, leaving your existing block regions available if you still want them. So when you enable panels, you get an extra menu item under Site Building called predictably "Panels". This takes you to a dashboard where you can enable or disable panels support for existing URL schemata (e.g. the node URLs at /node/%) and create variants which take into account e.g. the node type, so your blogposts can look different from your events. 

Slightly more subtly, though, if you want to enable panels on an existing view page... you can't. There's no mechanism for overriding the existing view page at e.g. /blog, like you can with a node page, and if you try to create a new panels page at that same URL then the system complains and won't let you do it. Instead, you have to create a whole new page and eventually discard or at any rate mothball the view's own page. Assuming you have a view at /blog, create a panels page at /blog_new; you can then add the view as a panel pane. You can use any one of the view's configuration variants (default, page, block etc.), not just the standard page variant. When everything looks happy, move your view to /blog_old and your new panels page to /blog.

Drupal also provides taxonomy listings at /taxonomy/term/term-id , which with Pathauto get aliased to /category/vocabulary-name/term-name. If you want to override a taxonomy listing, you can... but again there's a catch. Panels doesn't seem to provide you with any way of replicating the original content as far as I can see, and instead you have to build a view to replace the behaviour of the original taxonomy listing, and then put that into a pane where you'd want the original dumb taxonomy content to go.

When you create the view, you give it a first argument of "term ID". Then, when you add the view to the panel, in the modal lightbox titled "Configure view NAME (Defaults)", under the "Override title" box, you should have a setting where you can choose what to pipe through into your argument. Set that to term ID too. What you end up with is, as seems to always be the case with Panels, more functional and configurable than before, but it's harder to get to. Not just harder than letting core handle it: that's to be expected. But harder than you'd expect a GUI-rich many-developer-hour content-driven application to be.

Here's a summary of my panels the configuration:

Site building > Pages

• System > node_view enabled
• System > term_view enabled
• Custom > page_blog created for the blog archives

Overall Panels has made me feel like I have total control over what I want to appear where on my site. But the learning curve is steep and doubtless puts some people off; some of the greatest advantages come from being happy to get your hands dirty with PHP and the plugin architecture too, which I'll cover at a later date, and that's not possible or advisable for most Drupal end users. If I'd not had the luxury of stepping back for a few days every once in a while I'd probably have done it all in templating with regions and blocks. I'm glad I didn't, though, and I'm looking forward to iterating and perfecting my site's use of Panels.

Interestingly, we've ended up with common threads through the two quite different keynote talks. Fintan Galvin, who's talking about the semantic web and its effect on marketing strategies on the web we're more at home with, will be explaining how the former will change the way we think about such priorities as SEO with regard to the latter; along the way he'll be mentioning Drupal, which is an ideal solution to a whole host of web content problems. Meanwhile, Jeni Tennison will talk about a new initiative in open UK government, data.gov.uk, which is currently in closed beta and uses a complex stack of technologies including... Drupal and RDF! RDF takes centre stage in the forthcoming Drupal 7 release, so more by luck than judgment our common topic is a pretty hot one.

Of course there's microslots and the Pitch too---contact me if you want to volunteer for the sixty-second open-mic Pitch, as we've still got some spare slots---and we've got sponsorship to make sure the whole evening is not just free as in beer, but free as in... other beverages that are available. The Guardian Open Platform are sponsoring drinks again, and Apress have promised us some books for the book raffle. Torchbox is as usual very kindly sponsoring my time, venue costs and infrastructure for the night. Thanks to all our sponsors for their generosity.

Almost everything is in place, which means I might get away with a few days off before the night, but I promise to turn up on the 25th fit and rested. Assuming I'm not still stranded in Birmingham New Street. But then how likely is that, really?

It sounds pretty simple. Take the resources you want people to navigate around---so generally the furthermost leaves of your navigation tree: rich content pages, applications and the like rather than section indexes, which might contain navigational preconceptions---and try to assemble them into groups. Pretend they're written on cards---or, in a more agile way, actually write them on cards and shuffle them round a table---and try to assemble piles of similar resources. Closed card sorting involves predefining the groups, and is ideal for arranging new elements in an existing navigation and a good compromise for building a new navigation quickly; open card sorting is the same, but with no predefined groups. The results are better but it takes longer.

Card sorting really helps site maintainers escape preconceptions and build a navigational hierarchy that makes sense. So although it seems like overkill, this is actually what I have just done for this website. As with much that I'm currently doing towards the site rebuild, it's intended as a learning experience; a voyage of discovery, albeit taken on a Tonka truck within the safe confines of the wee sandbox that's my personal site.

My first pass yielded around fifteen resources---rather fuzzily defined, but including varied things like "my blog" and "a link to my Twitter feed"---which I wanted people to be able to navigate around. I arranged these in a single-parent hierarchy beneath six main headings: ongoing, literature, coding, academia and portfolio. However, this felt a bit forced (and some sections, especially "academia", are mostly opportunities for old documents to gather dust. I tried to imagine adding a more freeform vocabulary that cut across a lot of this, something like tagging, but there was something wrong.

Unsatisfied, I completely scrapped the single hierarchy and tried again. This time the list of resources had expanded to more like twenty, and I went for a more radical approach to grouping. Instead of trying to group objects as cards in a pile, so each card could only be in one pile, I tried to imagine from the start what groups plural they might fit into. Although I was still thinking in terms of menus, the parent terms were now more like categories from a taxonomy, with any menu item being available from several categories.

This resulted in seven terms:

tech, content, social, lit(erature), work, love and misc

This blog, for example, could fit under "tech", "content" and maybe "work", and would be accessible from all those places. My attempts at creative writing on Quiet little Lies could go under "content", "literature" and possibly "love".

As long as the number of objects didn't get too long (and objects didn't spread under too many terms) then these seven terms could still make sense to the user as a starting point, even if they found different things in multiple places. In fact, in the brave new world of folksonomies and tags, web users might be getting used to less hierarchical ways of navigating, so this might even pay off.

Drupal's menu system supports multiple or mixed hierarchies out of the box, but I preferred instead to actually use categories, and tie these to a menu with the Taxonomy Menu module. I might not follow that route in future, as it essentially only supports linking to Drupal's out-of-the-box category index pages, with content sorted in reverse date order, whereas I'l almost certainly want to do something nicer. But like card sorting itself it was a good springboard to getting things working and feeling happy with progress.

For now the hierarchy is implemented with dummy content, but I hope to fill it out more---and then expose the navigation---in the next few days. Right now it's just nice to see things starting to come together. Also, having seven top-level terms fits in rather neatly with the design decisions I've already made: more on those later.