Drupal Tutorials

From Drupal 4.7 onwards Drupal themers now have the ability to set their own custom block regions for their themes. This gives even more power to your theme and your ability to customize your themes.

By regions I mean the regions in the page template where you can assign block content like left-sidebar,right-sidebar, content etc. Just take a look at the blocks admin area (yoursite.com?q=admin/build/block) on your site and you’ll see something similar to the image on the right. But these can default regions can be a bit restrictive so let's take a look at how you define your own custom block regions for your theme.

The template.php code

In your themes template.php file is where you define all the block regions you want using code similar to this:

This is the exact regions I am using on DrupalSN, you'd obviously need to change the YOUR_THEMES_NAME bit to the title of your theme which is whatever you called the folder your theme lives in, mines druplsn_v1.

The code returned by this function is just a simple array with the key (on the left hand side) being the computer friendly name so you shouldn't use spaces or any strange characters and the value (on the right hand side) is the human readable name that you see in the blocks admin area drop down menus.

The page.tpl.php code

Ok so we've defined our block regions now it's time make them show up in our template and this is really simple.

1. We going to be working with the page.tpl.php file, so go ahead and open that up in your favourite text editor (Notepad or Dreamweaver).
2. Now refer back to the regions array we defined in the template.php file and simply take the key name and put that into a PHP echo statement with a $ sign in front of the key name like so:
   
   <?php
echo $KEY_NAME;
?>
3. So let's put our "left sidebar" region into the left sidebar of our layout. The key for the "left sidebar" region is "left" so our code would look like this:
   
     <div class="sidebar_left">
    <?php echo $left; ?>
  </div>
   It's that simple! This bit of code places the "left" region within a div with the class "sidebar_left" and this corresponds to some CSS layout code that maybe look something like this:
   .sidebar_left{
  width:25%;
  float:left;
  margin-right:2%;
  overflow: hidden;
}

You can take this same principle to fill out your whole page layout with your custom regions.

Test the layout

Once you've added all your regions to your page.tpl.php you need to test they are working by assigning block content to the regions via the blocks admin area.

So, go to the blocks admin area (yoursite.com?q=admin/build/block) and assign a few blocks to your new regions and save the settings (save blocks). The blocks should show up in your new regions, if they don't go back to your page.tpl.php and check you have spelt the region key name correctly. If you're still having problems it's often useful to refer to another theme like the Garland theme to see how it's done there.

If you don't like getting your hands dirty with theme hacking then you should check out the Block Regions module

That concludes this tutorial I know I've not gone into too much depth here but hopefully you've grasped the principle of how to assign custom regions in your theme. Please feel free to leave any questions or comments below.

As always thanks for reading!