Creating Custom Regions

Posts · 21st May 2007 · 32 comments

UPDATE
The following tutorial covers the creation of custom regions in Drupal 5 themes. If you are using Drupal 6 please see the newer creating custom regions in Drupal 6 themes instead.

----------

All Drupal themes you download will come with a number of pre-defined regions into which you can already place blocks (normally header, left-sidebar, content, right-sidebar, footer), but it can sometimes be useful to create your own.

This can seem a little daunting at first, but it's really just a simple two-step process:

  • step 1 - define the custom region in your template.php file
  • step 2 - add the custom region to your page.tpl.php file

So, lets see how it works.

Step 1 - define the custom region in your template.php file

All themes should have a template.php file contained within the theme folder.

Open the template.php file in your chosen editor and locate the function titled 'function nameoftheme_regions' (where nameoftheme will be the name of the theme to which you are adding a custom region). This will probably be the first function in the file, and should look something like this:

function nameoftheme_regions() {
  return array(
       'header' => t('header'),
       'left' => t('left sidebar'),
       'content' => t('content'),
       'right' => t('right sidebar'),
       'footer' => t('footer')
  );
}

Okay, now just add your custom region so that it looks like the pre-defined regions.

For example, I'll add a custom region called 'sub header', which I'll position below the header region.

To do this I just add the following line:

'sub_header' => t('sub header'),

to the function, so that I get

function nameoftheme_regions() {
  return array(
       'header' => t('header'),
       'sub_header' => t('sub header'),
       'left' => t('left sidebar'),
       'content' => t('content'),
       'right' => t('right sidebar'),
       'footer' => t('footer')
  );
}

Just remember that the first part of this line must not contain any spaces. In this case I have used an underscore '_', instead of a space, between sub and header (sub_header), so I'm okay.

That's step 1 sorted, so save your template.php file and continue on with step 2.

Step 2 - add the custom region to your page.tpl.php file

So far I have just defined the custom region. Drupal knows that I want the custom region, but doesn't know where to put it. So lets sort this out.

Open your theme's page.tpl.php file in your chosen editor.

This file contains the main chunk of structure for your site's pages.

Decide where you would like your custom region to appear. In this case I'm creating a custom region called 'sub header', so it kinda makes sense to have the custom region appear beneath the header!

So, just add the following code where ever you want the region to appear (replacing sub_header with the name of your own custom region):

<div id="sub_header">
<?php print $sub_header ?>
</div>

and save the file.

Technically, I actually only need to use the code:

<?php print $sub_header ?>

but doing so makes it harder to manipulate the content within the region, so in this case I have placed the region within a div also called sub_header which will be more easily controlled from the style.css file.

Well that's it, your new custom region is now ready for use.

To check that it really is there, log in to your site and navigate to
Home > Administer > Site building > Blocks

You should see your custom region highlighted, and also listed as an option in the region drop-down selections for each block.

32 comments

Drupal SEO Guy10th June 2007 @ 2:07am

Perfect! Exactly what I was looking for. My question is, why aren't great tutorials like this available on drupal.org? Thanks, Laurence!

Laurence10th June 2007 @ 3:55pm

Hi Drupal SEO Guy - good name ;) I'm glad the tutorial helped you out.

Alexei Rayu10th June 2007 @ 7:23pm

Join the SEO guy completely! Thank you very much Lawrence! I have beel looking for this - and here it is, in human language!
Again, my hearty thanks! God bless you man!

Laurence11th June 2007 @ 12:04pm

Thanks Alexei, I appreciate the comment :)

Matias O.27th June 2007 @ 4:44pm

Laurence you are the man with the Drupal plan.

Owen27th June 2007 @ 11:49pm

Hi Laurence,

Just thought I would drop a quick note... I installed Drupal 5.1 and worked with the default themes...

This meant I could not find a template.php file in them... at least the one I did find (in the garland theme) didn't have the "nameoftheme_regions()" function in it... So, I kept hunting until I found the "engines/phptemplate/phptemplate.engine" file. I then added the custom region to that.

Is that what is supposed to happen? This way I now have the region added to all themes that use the phptemplate engine?

Make sense? Your thoughts and wisdom would be kindly appreciate!
Owen

Laurence28th June 2007 @ 1:03pm

Hello everyone

Matias - thank you for the kind comment.

Owen - you had it right first time when you were trying to add the function to garland's template.php file. Garland doesn't have this function included so you will need to add the whole thing in yourself. To do this, just open garland's template.php file and add the entire function, as it is written above, directly after the opening php tag ('<?php'). Remember to replace the 'nameoftheme' part with the actual name of your theme - in this case 'garland'. Then just follow the other instructions to add the region to your page.tpl.php file, and you should be good to go. Let me know how it goes :)

Puzzled21st November 2007 @ 10:55pm

I've been struggling with this and glad to find this page.

I don't see how the region placement is done, exactly.

MyTheme had primary links below the graphic (not at the top), and I want it to use NiceMenus.
So I guess I need to define a new region, put a Nice Menus block in it, & have the block inherit from primary links.
But how does it get the style information?
Your directions suggest creating a new div, e.g., sub_header, in page.tpl.php.
But style.css for my Theme already contains details on the div containing the existing primary links.
Is there a conflict? What to do?

Guest22nd May 2008 @ 4:17pm

Does this work in Drupal 6? Can't find the "function nameoftheme_regions()" in the php file?

Laurence27th May 2008 @ 12:56pm

Hi, this tutorial was only for 5.x themes - things are a bit different for Drupal 6.

In Drupal 6 regions are now defined via the theme's .info file. Drupal.org has a couple of good explanations of how to implement regions in a 6.x theme here and here.

Madapple1st August 2008 @ 8:25pm

Ok I am trying to figure this out

i have this in my template.php file

"

<?php
function drakemap_regions() { return array(
     
'sidebar_one'   => t('sidebar one'),
   
'sidebar_left'  => t('Sidebar left'),
   
'sidebar_right' => t('Sidebar right'),   
   
'content'       => t('Content'),
   
'footer_left'   => t('Footer left'),
   
'footer_middle' => t('Footer middle'),
   
'footer_right'  => t('Footer right'),
  );
}
?>

"

but when i go to the blocks admin page... the regions do not show up, at all.
I have reloaded, cleared the cache, run cron. what did I do wrong? I get all of the standard regions, just not my customs

Nimrod1st August 2008 @ 11:23pm

Did you add this part:

<?php
 
print $sidebar_one
?>
<?php
 
print $content
?>

to the page.tpl.php file? I'm assuming your custom region is sidebar_one and content rite?

Adnan15th August 2008 @ 6:29am

I am using drupal 5.9 and I am unable to find function "nameoftheme_regions" in template.php

what do I do?

Guest30th September 2008 @ 8:50am

hi Lawrence,

I want my default regions to be existing and i want to add my custom regions too,how do i add them to the default regions..please help me.

Thanks
Deepthi

Satish N Kota15th October 2008 @ 4:34pm

Hey Laurence,

You Really Really Rock man... Solved too many of my problems...

Thanks for the idea, I picked up your idea and also owen's idea of putting it in the template engine.. and ooo laa laaa... got it worked...

Thanks for both of you...

Regards

bub27th October 2008 @ 10:44pm

This doesn't work for drupal v6, instead, you must define "region[region_name] = Description" on template_name.info file of your template directory. :-)

Admerin15th November 2008 @ 5:05am

Cheers! Thanks for sharing this information. I have the Drupal Themes 5 ebook and I'm page 110. The best thing about it so far is that it's so boring that when I took a break I found your page.
Maybe you could answer one more question? In Zen, for example, the designer added the new region, 'content_top'. I'm sure the 'content' region's width is defined somewhere, and 'content_top' must inherit that width from the content definition because I didn't have to make any changes and it knew to make it the same width. So what would I need to do in order to change that 'content_top' region by breaking it up into two or three regions running horizontally? What I mean is, how do I put columns into a new 'content_top' region so I can direct different blocks to each one? Maybe this is too big of a question, but you're directions are flawless and I'd appreciate the help enormously. Thanks in advance.

Dan11th December 2008 @ 10:37am

Thank you man! i'm using drupal 6 but with what you provided here it was very easy to create a few custom regions for my site. Keep up the good work!
Cheers

Alex Stomp16th December 2008 @ 1:57am

you rock man, this absolutely what I needed, and you did it perfectly.

Jason31st December 2008 @ 3:04am

Yeah I love this feature of Drupal, just checking out your site and it's great.

@Admerin
You want to create regions within a region basically, and you could tackle this by using the panels module. It breaks parts of a page up into columns however you need it. I personally don't like the panels module much because it seems counterintuitive to content creation, and is complicated to understand. Some people love it and there are some other modules out there to do this that I haven't tried.

Personally, I would create 3 more regions (content_top_left, content_top_center, content_top_right) and float them as columns in the same div as content_top, cleared just below it. That way you could assign blocks however you wanted and not have conflicts.

Hope that helps!

Adam5th January 2009 @ 12:14pm

In Drupal 6, I create custom regions by simply editing my theme's .info file and adding something like this:

regions[left] = Left Sidebar
regions[right] = Right Sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer
regions[customregion1] = Custom Region

(note all the standard region names above the custom region)

Now, if you go to the block administration you should see the 'Custom Region' available for you to place blocks into. Also, in the template files (such as page.tpl.php), you can refer to the region by it's variable name like this:

<div>
Custom region blocks will go here...
<?php print $customregion1 ?>
</div>

I also created an article about custom regions here: Drupal Custom Regions.

Constance19th February 2009 @ 2:47pm

Will you make a similar tutorial for Drupal 6 ... please? I'm sure you can do a better job than what is on the .org site. BTW, this doesn't exactly explain how you literally place the region. In other words, is that done in html/css?

Thanks and great job.

Guest9th March 2009 @ 9:21am

ZOMG!!!!!!!! I love you! This is exactly what I have been looking for!

Filme Noi27th May 2009 @ 11:33am

Hi Laurence! Excellent article.

Can you please edit your article, in case you are still maintaining it in 2009 :) , and specify for the readers the following two things:
1) that the function nameoftheme_regions may not exist in their template file, in which case they should add it themselves (and not modify the engine.php)
2) that this article applies to Drupal 5, and that the procedure for Drupal 6 is a little different.

I know that you already specified this inside comments, but I suggest you to specify them in the main article because I notice that these two issues are re-occurring in the comments. (which means that many readers that encounter these problems don't read the previous comments before posting their question.)

Laurence28th May 2009 @ 8:15pm

@ Filme Noi - thanks. I have now posted an updated version for Drupal 6:
Creating custom regions in Drupal 6 themes.

Guest14th December 2009 @ 7:10am

Hai Laurence, In my Theme Floder having template.php file. But,In this File Not Contain the Below Specifying part..

function nameoftheme_regions() {
return array(
'header' => t('header'),
'sub_header' => t('sub header'),
'left' => t('left sidebar'),
'content' => t('content'),
'right' => t('right sidebar'),
'footer' => t('footer')
);
}

what is the Solution?

milton 22nd March 2010 @ 7:23pm

Dear Lawrence, I´m glad that this post, being so old, still helps people like me and many others. This shows us that explanations don´t have to be so long to work properly.
Thank you very much.

motorcycleguy23rd April 2010 @ 10:25pm

Does this work in Drupal 6.16 ?

Oliver Davies26th April 2010 @ 12:58pm

In Drupal 6, you declare the regions in the theme's .info file. Take a look at Garland's .info file as a reference. Then print the variables with PHP statements in the page.tpl.php file - the same as what's described above.

Martin27th April 2010 @ 11:02am

Im working on a project and have to use Drupal 5. I've just made some new regions and they show up, which is great, ontop and below of each new region there are the php question mark in a box emblem. � Please can anyone explain?? / Help! It's driving me crazy!

Martin27th April 2010 @ 12:06pm

Just figured it out.. It was due to white space around the new fields on the page.tpl.php

!

breckenridge co...29th June 2010 @ 8:21pm

All the documentation makes it seem kinda easy, which is bugging me . I've not only read a load of documentaiton, I've grabbed other themes with multiple custom regions, and tried to replicate the code without luck. I must be missing something basic!.

Comments are closed

If you want to ask a question or have something to add please contact me.