[drupal-docs] [feature] Theme developers guide updates on new regioning system

[nedjo]

Issue status update for 
http://drupal.org/node/29141
Post a follow up: 
http://drupal.org/project/comments/add/29141

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     feature requests
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  nedjo
 Updated by:   nedjo
 Status:       active

The following updates to various pages are intended to I've also created
two new pages on regioning:


http://drupal.org/node/29140, Regions in themes, and
http://drupal.org/node/29139, Regioning in PHPTemplate themes


both of which I believe need to be reviewed and approved.


===================
Additions to page http://drupal.org/node/25297, Home » Developing for
Drupal » Theme developer's guide » Updating your themes » Converting
4.6 themes to HEAD
===================


Regions
Drupal theme authors can now define and implement any number of
'regions' for content to be rendered into.  This regioning system
replaces the previous 'left' and 'right' sidebar regions and should
enable much more flexible layout and design, and requires changes to
every theme and theme engine.


At a minimum, all plain PHP themes must now include a mytheme_regions()
function in their .theme file, defining the available regions.  If left
and right sidebars were already available and no new regions were
introduced, a plain PHP theme could be upgraded simply by adding the
following function:



<?php
function mytheme_regions() {
  return array(
       'left' => t('left sidebar'),
       'right' => t('right sidebar')
  );
}
?>




Want to do more?  Look to the regioning information in the plain PHP
theme [1] author's guide.


To upgrade PHPTemplate-based themes, the minimum change needed is to
add a "header" region to the page.tpl.php page (a region below the top
of page banner).  In bluemarine, the added region looked like this:



  
    
<?php
 print $header 
?>


  

See the page on regioning in PHPTemplate themes [2] for tips on how to
introduce your own custom regions.


Like plain PHP themes, template engines besides the core PHPTemplate
one can be minimally upgraded simply by adding a
mythemeengine_regions() function defining the already-available left
and right regions.  But full support for regioning will require more
extensive changes.  The phptemplate.engine section of the
recently-applied regioning patch [3] should be a partial guide for
what's needed.


===================
Changes to page http://drupal.org/node/11812, Home » Developing for
Drupal » Theme developer's guide » PHPTemplate theme engine »
Page.tpl.php
===================


[insert after: [is_front: True if the front page is currently being
displayed. Used to toggle the mission.]]
header: the HTML for the header region.


===================
Changes to page http://drupal.org/node/11795, Home » Developing for
Drupal » Theme developer's guide » Plain PHP themes
===================


[replace [Aside from theme functions, there is one function that you
need to include, called mytheme_features().], with:]


Required functions.
Aside from theme functions, there are two functions that you need to
include.


The first is mytheme_features().


[Insert after "function chameleon_features()" code block:]


The second required function is mytheme_regions(), which defines the
available regions in the theme.


Here's the chameleon.theme _regions() function:


[?


function chameleon_regions() {
  return array(
       'left' => t('left sidebar'),
       'right' => t('right sidebar')
  );
}


?]


For each region you define, you'll want to include a code block
including the region's content in the page output.  Typically, this
might look something like:



<?php
  if ($blocks = theme_blocks('regionname')) {
    $output .= '[wrapping content]' . $blocks . '[/wrapping
content]';
  }
?>




Note that 'regionname' here is the array key, not it's text description
(that is, 'left' and not 'left sidebar').  By 'wrapping content' we just
mean any div, td, text, or other elements you might want to enclose your
region's content in.


So, to introduce additional regions beyond just the standard 'left' and
'right' ones, you simply (a) add your region to the list defined in your
_regions() function and (b) render the resulting content to the output
as shown.  So the coding part's quick and easy, don't hesitate to be
creative!


[1] http://drupal.org/node/11795
[2] http://drupal.org/node/29139
[3] http://drupal.org/files/issues/regions4.patch




nedjo