Tutorial of how to use this API to build a region
Regions in Drupal are defined by the theme layer. This is problematic in instances where you want to add blocks / boxes to a specific region that is theme independent. Some examples of when you would want to use this module:

  • You want to place a top branding bar on your site that you can drop blocks into
  • You create a feature that has context positioned blocks that should ALWAYS function a certain way
  • You want an area that's theme independent so you don't need to worry about different devs ignoring theme region naming conventions
  • You want to make admin-esk places for those tasks to exist without adding blocks to the layout of your design (changing the way it functions for some users over others)

Check out Slidebox for an example of a contrib module implementing Regions API.

By using a simple function call, additional regions can be added to the system.

7.x

This module is an API by itself, it does however come with three sample regions called Admin left, Top navigation, and right slideout. This is an example of how you can build an administrative region for blocks to live outside of the block layout of the page. It also comes with an example feature that shows how to use Features / Context in order to create cross-theme compliance block placement.

6.x

This module does nothing on its own but you can find implementations in ELMS Features and ELMS core. ELMS Alpha 6+ ships with these 4 regions (top, left, right, bottom) so look to them for their method of creation. The Right region is just a module and could be the cleanest example while Top and Left provides blocks and Feature integration for automatic install and setup of the regions. Much of the code in these three regions should work in other Drupal systems though it is not directly supported.

This module seeks to replace all the insane replication currently out there in projects like appbar and others that provide far more then just scaffolding, while still replicating much of the same architecture.

Basic usage from regions.api.php:

function hook_define_regions() {
  return array(
    'myregion1' => array(
      'title' => 'My region 1',
      'css' => drupal_get_path('module', 'mymodule') .'/css/style.css',
      'js' => drupal_get_path('module', 'mymodule') .'/js/script.js',
      'render_callback' => 'mymodule_block_callback', //optional
    ),
    'myregion2' => array(
      'title' => 'My region 2',
    ),
  );
}

See the API for a list of other useful hooks or see the ELMS Navigation Left, Right or Top regions for example usage.

Created Regions can then be bundled with Features much more cleanly to do anything from provide a chat window to standardize the placement of admin like functionality without giving access to admin bar type of modules.

A note on Distros

If you package your permissions as part of a distribution, there is currently an issue where during installation of the distribution you will be unable to correctly install a feature referencing permissions generated by regions. This is because the perms don't really exist during the install phase and a db integrity check fails because the module (may or may not) be installed already. Use code of this format as a work around in your install profile .install file:

// stupid work around for regions conflict with module perms
  $roles = array('role name', 'role name2', 'role name3', 'role name4');
  foreach ($roles as $name) {
    $role = user_role_load_by_name($name);
    db_merge('role_permission')->key(array(
        'rid' => $role->rid,
        'permission' => 'view regions_admin_left region',
    ))->fields(array(
        'module' => 'regions',
    ))->execute();
  }
  drupal_static_reset('user_access');
  drupal_static_reset('user_role_permissions');

Project initially created as part of the Penn State University ELMS Initiative.

Supporting organizations: 

Project information

Releases