Creating Custom Regions

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.

26 comments

1
Drupal SEO GuyJune 10th 2007 @ 02:07AM

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

2
LaurenceJune 10th 2007 @ 03:55PM

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

3
Alexei RayuJune 10th 2007 @ 07: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!

4
LaurenceJune 11th 2007 @ 12:04PM

Thanks Alexei, I appreciate the comment :)

5
Matias O.June 27th 2007 @ 04:44PM

Laurence you are the man with the Drupal plan.

6
OwenJune 27th 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

7
LaurenceJune 28th 2007 @ 01: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 :)

8
PuzzledNovember 21st 2007 @ 11: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?

9
GuestMay 22nd 2008 @ 04:17PM

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

10
LaurenceMay 27th 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.

11
MadappleAugust 1st 2008 @ 08: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

12
NimrodAugust 1st 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?

13
AdnanAugust 15th 2008 @ 06:29AM

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

what do I do?

14
GuestSeptember 30th 2008 @ 08: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

15
Satish N KotaOctober 15th 2008 @ 04: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
Satish N Kota
www.heurionconsulting.com

16
bubOctober 27th 2008 @ 11: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. :-)

17
AdmerinNovember 15th 2008 @ 06: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.

18
DanDecember 11th 2008 @ 11: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

19
Alex StompDecember 16th 2008 @ 02:57AM

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

20
JasonDecember 31st 2008 @ 04: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!

21
AdamJanuary 5th 2009 @ 01: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.

22
ConstanceFebruary 19th 2009 @ 03: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.

23
GuestMarch 9th 2009 @ 10:21AM

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

24
Filme NoiMay 27th 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.)

25
LaurenceMay 28th 2009 @ 08:15PM

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

26
GuestDecember 14th 2009 @ 08: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?

Post new comment

The content of this field is kept private and will not be shown publicly.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
  • You may post code using <code>...</code> (generic) or <?php ... ?> (highlighted PHP) tags.

More information about formatting options

6 + 6 =
Solve this simple math problem and enter the result. E.g. for 1+3, enter 4.