Blocks, content and their regions

The block regions available to the theme are defined within .info files. It must be specified with the key of 'regions' followed by the internal "machine" readable name in square brackets and the human readable name as the value, e.g., regions[theRegion] = The region label. If none are defined, the following values are assumed.

Keep in mind that the internal names are converted into region variables inside the "page.tpl.php" template automatically. In the above example, the [left] region will output all the blocks assigned to it through the $left variable. There are a few restrictions on naming variables in PHP so make sure the internal names conform to the same restrictions. It can only contain alphanumeric characters and underscores but it cannot start with a number.

The human readable name outside the square brackets are used for labeling the region in the block administration page located at "Administer > Site building > Blocks".

Here is the block administration table for Garland:

A 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.
• 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 contents 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 clear it, do one of the following:
  1. Clear button located at "Administer > Site configuration > Performance".
  2. With devel block enabled (comes with devel module), click the "Empty cache" link.
  3. Simply visit the theme select page at "Administer > Site building > Themes".

Upgrade notes:

• In Drupal 5 and below, regions were declared with ThemeName_regions() or EngineName_regions(). It has been deprecated in Drupal 6.
• If you are upgrading your theme from versions before Drupal 6 and the region variables of $sidebar_left and $sidebar_right were used, rename them to $left and $right.
• The $footer_message region variable in versions before 6 mixed the footer region with the footer message (set from "Administer > Site configuration > Site information"). Make sure a separate $footer variable is created if your theme uses it since Drupal 6 and above no longer combines the two elements.

Manually assigning content to regions:

Content can be manually set inside regions with drupal_set_content. For example, 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.

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.