Last updated June 26, 2013. Created by LeeHunter on August 28, 2007.
Edited by jwilson3, Tomark, DSquaredB, JohnNoc. Log in to edit this page.

If none are defined, the following values are assumed in Drupal 6.

regions[left] = Left sidebar
regions[right] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer
 

Drupal 7 adds Highlighted and Help as default regions. By default, the textual content of the Help region is the same as the $help variable was in page.tpl.php for Drupal 6. The "machine" readable names of the sidebars have also changed names.

regions[sidebar_first] = Left sidebar
regions[sidebar_second] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer
regions[highlighted] = Highlighted
regions[help] = Help

Drupal 7 bartik theme has following default regions -

regions[header] = Header
regions[help] = Help
regions[page_top] = Page top
regions[page_bottom] = Page bottom
regions[highlighted] = Highlighted
regions[featured] = Featured
regions[content] = Content
regions[sidebar_first] = Sidebar first
regions[sidebar_second] = Sidebar second
regions[triptych_first] = Triptych first
regions[triptych_middle] = Triptych middle
regions[triptych_last] = Triptych last
regions[footer_firstcolumn] = Footer first column
regions[footer_secondcolumn] = Footer second column
regions[footer_thirdcolumn] = Footer third column
regions[footer_fourthcolumn] = Footer fourth column
regions[footer] = Footer

Keep in mind that the internal names are converted into region variables inside the "page.tpl.php" template automatically. In the above example, the [header] region will output all the blocks assigned to it through the $header variable in Drupal 6, or $page['header'] in Drupal 7. There are a few restrictions on naming variables in PHP, so make sure the internal/machine names conform to the same restrictions. Basically, your internal region names can only contain alphanumeric characters and underscores, and they should start with a letter.

The human readable names outside the square brackets are used for labeling the region in the block administration page located at "Administer > Site building > Blocks" and in Drupal 7 the block administration page is located at "Administration > Structure > Blocks" .

Here is the block administration table for Garland:
Garland block configuration exampleDrupal 7 - Block administration table for Bartik:
Bartik block configuration exampleA few notes:

  • There are template (.tpl.php) files available for rendering individual blocks.
  • Adding a custom region prevents the defaults from being used. If you want to keep the defaults in addition to custom regions, manually add in the defaults.
  • If you define custom regions, it is important to remember that you need to include the content, help, page_top and page_bottom regions in your set of regions. The page_top and page_bottom regions are hidden, which means they will not show up on the blocks administration interface.
  • The order in which the regions are defined will be reflected in the block configuration table. Garland, for example, uses the default regions. Notice the order of the regions listed in the image.
  • The content of the .info file is cached in the database, so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To learn how to clear it, check out the options in Clearing the theme cache.

Upgrade notes:

  • The $footer_message region variable has been removed in Drupal 7.

The $content region
In Drupal 6 and before the $content variable in page.tpl.php contained the main page content appended with the blocks positioned into the content region (if you had that region defined).

In Drupal 7, $content became a full region and is now mandatory in all themes. This new requirement was set up so that when enabling new themes, Drupal knows where to put the main page content by default.

In Drupal 6, it was only possible to put blocks after the main page content in this region. The only way to put blocks before the main page content was to define a specific region for that purpose. Drupal 7 now makes the main page content its own block. This makes it possible to put blocks before or after the main page content in the region without hacking in a new region.

Manually assigning content to regions:

Note: until #713462: drupal_add_region_content() not usable is resolved, drupal_add_region_content will not work in Drupal 7 or Drupal 8 without applying patches found on the aforementioned issue.

Content can be manually assigned to regions with drupal_set_content() in Drupal 6 or drupal_add_region_content for Drupal 7. For example in Drupal 6, drupal_set_content('header', 'Welcome!') would assign the text 'Welcome!' to the header region.

Here is a more useful example for building a summary of all the comments into the "right" region. Rename the "drop" prefix with the name of your theme. More information on preprocessors is available.

<?php
function drop_preprocess_comment(&$variables) {
 
// Setup a few variables.
 
$comment = $variables['comment'];
 
$title = l(
   
$comment->subject,
   
comment_node_url(),
    array(
'fragment' => "comment-$comment->cid")
  );
 
$new_marker = $comment->new ? t('new') : '';
 
$by_line = t('by') .' '. theme('username', $comment);
 
// Form the markup.
 
$summary = '<div class="comment-sidebar">';
 
$summary .= '<span class="title">' . "$title $new_marker</span>";
 
$summary .= '<span class="credit">' . "$by_line</span>";
 
$summary .= '</div>';
 
// Set the comment into the right region.
 
drupal_set_content('right', $summary);
}
?>

Note that setting content through this function should happen before the block regions are retrieved and that is done with a call from template_preprocess_page > theme_blocks > drupal_get_content.

AttachmentSize
block_config_garland.png38.26 KB
blocks in D7.png112 KB

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

It'd be useful to comment more this piece of code, explaining what functions are native of PHP, which ones are Drupal functions, which ones are user-defined, and what they do. The same for variables: are they defined in PHP, in Drupal or by the user, and what are they supposed to contain.

http://Fiable.biz Web site creation.

I would love this info also.
Fact is, I expected it right from the start of this page.

This pretty much goes for all Drupal documentation, a lot of it you have to figure out for yourself, by looking at the context or or looking up, variables and functions up on api.drupal.org.

I am using drupal 7, and the "Seven" theme is enabled in both user and admin panels.

Then, I placed drupal_add_region_content('header','Welcome!');, in the "seven_preprocess_page(&$vars)" function.

But the word "Welcome1" did not got set in the header part.

Probably I may be missing that note which is describing about "template_preprocess_page > theme_blocks > drupal_get_content.".

It would be great if anyone can guide me, how to acheive this.

Thanking you all,
K Pradeep Kumar.

See Issue #713462: drupal_add_region_content() not usable, there are patches for both D7 and D8 that fix this bug. Needs testing and feedback.

I have to declare only content region?

--
marlus araujo

I think you need to use the support forums and explain what you are trying to do and why.

damn... all the tutorials in Drupal.com only contains thousands text to read. Please make some easily followable tutorials with actual code..... not just parts.. please

I agree. too much stuff confuses the new learner.

Muhammad Ishfaq
Web Designer,
Confiz Solution,
Lahore, pakistan.

i am using drupal D7, want to assign content in region using drupal_add_region_content, but content is not shoing in particular region. can you help?

Just go to admin/structure/block and say where you want each block to appear
it's THAT easy and you didn't said this anywhere in this page!!!

I want to know how I specify where each region will stay on my template

On drupal 6: just write

<?php
print $region_name
?>

DAMN!! You didn't said it anywhere in this tutorial!!!

How to do it on drupal 7???

Try this:
if($top = block_get_blocks_by_region('content_top')) print render($top);

The following will add a condition region content insertion on your template file.

<?php
/* drupal 7 region template */
if ( $page['region_name'] ):
?>

<div>Template markup
<?php
print render( $page['region_name'] );
?>
</div>
<?php
endif;
?>

Cristiano Sumariva

Is it possible to create hierarchical regions?

for example create a region Footer and inside footer you got left, center, right.
Something like this:

regions[footer] = Footer
regions[footer][left] = Left
regions[footer][center] = Center
regions[footer][right] = Right

I think this would be a great feature to make drupal more user friendly.

I think you can use divs for that, right? Are you going to put any content into footer without putting it in left, center, or right? If not, something like this could go in your page.tpl.php file:

<div id="footer">
<?php if ($page['left']) { ?>
<div id="left">
<?php print render ($page['left']) ?>
</div><!--end left triptych-->
<?php } ?>
<?php if ($page['center']) { ?>
<div id="center">
<?php print render ($page['center']) ?>
</div><!--end center triptych-->
<?php } ?>
<?php if ($page['right']) { ?>
<div id="right">
<?php print render ($page[['right']) ?>
</div><!--end right triptych-->
<?php } ?>
</div><!--end triptych container-->

I'm really new at this, and in the act of giving advice as I figure things out. If anybody with more insight has a suggestion, that'd be amazing! Oh, and I'm talking about D7 --> I read somewhere that you had to include that "render" in D7 but not in D6.

Liz
Stumbling along.

I think this tutorial needs some corrections. drupal_add_region_content does not work as expected in Drupal 7, so dont waste your time.

Here is why: http://drupal.org/node/713462

I created a sub-theme from Bartik and now I want to switch to Zen. Is there a way I can automatically assign all the blocks in the custom regions from Bartik sub-theme to a Zen sub-theme? There's over 700 blocks and the site is live.