Changing a Block's Output

Oct 11 2007

Block Template

Sometimes the incredible power that Drupal gives me comes at the pain-in-the-assification of smaller things I took for granted in my pre-Drupal world.

For example, a client had given me a comp with a really small (100px wide by 50px tall) block for the login. Using logintoboggan, the default output for a logged in user is

[username] | Log out

on a single line and was wider than the box for most usernames. If this were a static html page, I could just replace the pipe (|) with a line break (<br />). Going into the module and replacing it wouldn't be much more difficult, but upgrading the module at some future date would eliminate that change. You could try to remember to make the same change again, but that will cause headaches even if you do remember. Plus, if you have that mindset, it probably won't be the only thing you changed that your updates broke!

The way I solved it (with a little help) was to create a new block template file for that block (I didn't have to worry about a node view) and make the changes I needed within the template. This creates one additional file, but it's tiny and preserves your abiility to make clean backups and clean upgrades.

The first thing I did was to view the source code for the page I wanted, looking for the block name. I scrolled through until I found this line:

<div id="block-logintoboggan-0" class="block block-logintoboggan">

which gave me the name of the block. I then made a copy of block.tpl.php in my theme's folder and renamed it block-logintoboggan.tpl.php cutting and pasting from the line above.

I then opened this file in a text editor and found the line that is displaying the html. I quickly found <?php print $block->content; ?>, which displays the content element of the block object. I treated that element as a black box and simply modified its content on output. The only thing I had to do was replace this line with a line that does a regular expression replacement. That's it! I didn't have to touch anything anywhere else.

Here's the new line to replace that one:

<?php
 print preg_replace("/ \| /", '&lt;br /&gt;', $block->content); 
?>

This goes through the output, looking for the pipe character with a space on either side and replaces it with the line break. I had to escape (\) the pipe because it is a special character.

So everything worked and I was excited enough to write this up for others, but then I found out that this isn't the standard way to do this! Although this method is fairly clean and easy, I was just informed that the more standard way is to override the function in template.php and is called a theme override.

Theme Override

The pipe is created by a function in the logintoboggan module. If you open the main file (logintoboggan.module) and search for "|" or "log out" you'll find the function:

<?php
function theme_lt_loggedinblock(){
  global $user;
  return check_plain($user->name) .' | ' . l(t('Log out'), 'logout');
}
?>

Now copy and paste that whole function into template.php in your theme folder and rename the function to phptemplate_lt_loggedinblock. You can override any function that has the prefix "theme_" by changing the prefix to "phptemplate_". (You could alternately change the prefix to your theme's name, but that would have the small disadvantage of breaking if you're theme name is changed.) This all works only if you are using the default theme engine, phptemplate. If you aren't, you presumably know a lot more than I do and aren't reading this.

Once you've pasted the function into template.php and renamed the prefix, you simply edit the function. In my case, I simply changed the pipe to a line break. Here's how it looked:

<?php
function phptemplate_lt_loggedinblock(){
  global $user;
  return check_plain($user->name) .'<br />' . l(t('Log out'), 'logout');
}
?>

In case you weren't counting, that's only three quick steps: Find the function, paste it into template.php with a new prefix, and make your changes!

If this html isn't overrideable, you should file a bug with the module and (try) to attach a patch that fixes it!

If you'd like to learn more about the guts behind this override, a good place to start is the well commented theme engine file, found here in your drupal install: themes/engines/phptemplate/phptemplate.engine.

I had fun peeking under Drupal's hood and was glad that something that would have been so daunting not long ago ended up seeming easy in the end!