Blocks are the boxes visible in the sidebar(s) of your web site. These are usually generated automatically by modules (e.g. recent forum topics), but you can also create your own blocks.
-The sidebar each block appears in depends on both which theme you are using (some are left-only, some right, some both), and on the settings in block management.
+The region each block appears in depends on both which theme you are using (some are left-only, some right, some both, and some may offer other regions), and on the settings in block management.
The block management screen lets you specify the vertical sort-order of the blocks within a sidebar. You do this by assigning a weight to each block. Lighter blocks (smaller weight) "float up" towards the top of the sidebar. Heavier ones "sink down" towards the bottom of it.
A block\'s visibility depends on:
Blocks are the boxes in the left and right side bars of the web site. They are made available by modules or created manually.
-Only enabled blocks are shown. You can position the blocks by deciding which side of the page they will show up on (sidebar) and in which order they appear (weight).
+Blocks are content rendered into regions, often boxes in the left and right side bars of the web site. They are made available by modules or created manually.
+Only enabled blocks are shown. You can position the blocks by deciding which area of the page they will show up on (e.g., a sidebar) and in which order they appear (weight).
If you want certain blocks to disable themselves temporarily during high server loads, check the 'Throttle' box. You can configure the auto-throttle on the throttle configuration page after having enabled the throttle module.
", array('%throttle' => url('admin/settings/throttle'))); case 'admin/block/add': @@ -112,7 +112,7 @@ function block_admin_save($edit) { foreach ($edit as $module => $blocks) { foreach ($blocks as $delta => $block) { - db_query("UPDATE {blocks} SET region = %d, status = %d, weight = %d, throttle = %d WHERE module = '%s' AND delta = '%s'", + db_query("UPDATE {blocks} SET region = '%s', status = %d, weight = %d, throttle = %d WHERE module = '%s' AND delta = '%s'", $block['region'], $block['status'], $block['weight'], $block['throttle'], $module, $delta); } } @@ -146,20 +146,21 @@ $block['status'] = $old_blocks[$module][$delta]->status; $block['weight'] = $old_blocks[$module][$delta]->weight; $block['region'] = $old_blocks[$module][$delta]->region; + $block['themed'] = $old_blocks[$module][$delta]->themed; $block['visibility'] = $old_blocks[$module][$delta]->visibility; $block['pages'] = $old_blocks[$module][$delta]->pages; $block['custom'] = $old_blocks[$module][$delta]->custom; $block['throttle'] = $old_blocks[$module][$delta]->throttle; } else { - $block['status'] = $block['weight'] = $block['region'] = $block['custom'] = 0; + $block['status'] = $block['weight'] = $block['region'] = $block['custom'] = $block['themed'] = 0; $block['pages'] = ''; } // reinsert blocks into table - db_query("INSERT INTO {blocks} (module, delta, status, weight, region, visibility, pages, custom, throttle) VALUES ('%s', '%s', %d, %d, %d, %d, '%s', %d, %d)", - $block['module'], $block['delta'], $block['status'], $block['weight'], $block['region'], $block['visibility'], $block['pages'], $block['custom'], $block['throttle']); + db_query("INSERT INTO {blocks} (module, delta, status, weight, region, themed, visibility, pages, custom, throttle) VALUES ('%s', '%s', %d, %d, '%s', %d, %d, '%s', %d, %d)", + $block['module'], $block['delta'], $block['status'], $block['weight'], $block['region'], $block['themed'], $block['visibility'], $block['pages'], $block['custom'], $block['throttle']); $blocks[] = $block; // build array to sort on @@ -178,17 +179,19 @@ * Prepare the main block administration form. */ function block_admin_display() { + global $theme_engine; $blocks = _block_rehash(); - $header = array(t('Block'), t('Enabled'), t('Weight'), t('Sidebar')); + $header = array(t('Block'), t('Enabled'), t('Weight'), t('Placement')); if (module_exist('throttle')) { $header[] = t('Throttle'); } $header[] = array('data' => t('Operations'), 'colspan' => 2); - $left = array(); - $right = array(); + $regions = array(); $disabled = array(); + $block_regions = system_region_list(null, true); + foreach ($blocks as $block) { if ($block['module'] == 'block') { $delete = l(t('delete'), 'admin/block/delete/'. $block['delta']); @@ -200,8 +203,8 @@ $row = array(array('data' => $block['info'], 'class' => 'block'), form_checkbox(NULL, $block['module'] .']['. $block['delta'] .'][status', 1, $block['status']), form_weight(NULL, $block['module'] .']['. $block['delta'] .'][weight', $block['weight']), - form_radios(NULL, $block['module'] .']['. $block['delta'] .'][region', $block['region'], - array(t('left'), t('right')))); + form_select(NULL, $block['module'] .']['. $block['delta'] .'][region', isset($block['region']) ? $block['region'] : variable_get('default_region', 'left'), + $block_regions)); if (module_exist('throttle')) { $row[] = form_checkbox(NULL, $block['module'] .']['. $block['delta'] .'][throttle', 1, $block['throttle']); @@ -209,11 +212,10 @@ $row[] = l(t('configure'), 'admin/block/configure/'. $block['module'] .'/'. $block['delta']); $row[] = $delete; if ($block['status']) { - if ($block['region'] == 0) { - $left[] = $row; - } - if ($block['region'] == 1) { - $right[] = $row; + foreach ($block_regions as $key => $value) { + if ($block['region'] == $key) { + $regions[$key][] = $row; + } } } else if ($block['region'] <= 1) { @@ -222,19 +224,33 @@ } $rows = array(); - if (count($left)) { - $rows[] = array(array('data' => t('Left sidebar'), 'class' => 'region', 'colspan' => (module_exist('throttle') ? 7 : 6))); - $rows = array_merge($rows, $left); - } - if (count($right)) { - $rows[] = array(array('data' => t('Right sidebar'), 'class' => 'region', 'colspan' => (module_exist('throttle') ? 7 : 6))); - $rows = array_merge($rows, $right); + + if (count($regions)) { + foreach ($regions as $region => $row) { + // If the selected region is not one of the defined regions for the default theme's engine, asterix it. + $region_title = t('%region', array ('%region' => ucfirst($block_regions[$region]))); + $rows[] = array(array('data' => $region_title, 'class' => 'region', 'colspan' => (module_exist('throttle') ? 7 : 6))); + $rows = array_merge($rows, $row); + } } if (count($disabled)) { $rows[] = array(array('data' => t('Disabled'), 'class' => 'region', 'colspan' => (module_exist('throttle') ? 7 : 6))); $rows = array_merge($rows, $disabled); } $output = theme('table', $header, $rows, array('id' => 'blocks')); + + $non_default_region_message = false; + + // Test if asterix was added (therefore, if message will need to be displayed). + foreach ($block_regions as $region) { + if (substr ($region, strlen($region) - 1, 1) == '*') { + $non_default_region_message = true; + break; + } + } + if ($non_default_region_message) { + $output .= '' . t('* This region is not available in the default theme, so any blocks assigned to it will be invisible to most users.') . '
'; + } $output .= form_submit(t('Save blocks')); return form($output, 'post', url('admin/block')); @@ -412,39 +428,36 @@ } } - /** - * Return all blocks in the specied region for the current user. You may - * use this function to implement variable block regions. The default - * regions are 'left', 'right' and 'all', where 'all' means both left and - * right. - * - * @param $region - * This is a string which describes in a human readable form which region - * you need. - * - * @param $regions - * This is an optional array and contains map(s) from the string $region to - * the numerical region value(s) in the blocks table. See default value for - * examples. - * - * @return - * An array of block objects, indexed with module_delta. - * If you are displaying your blocks in one or two sidebars, you may check - * whether this array is empty to see how many columns are going to be - * displayed. - * - * @todo - * Add a proper primary key (bid) to the blocks table so we don't have - * to mess around with this module_delta construct. - * Currently, the blocks table has no primary key defined! - */ -function block_list($region, $regions = array('left' => 0, 'right' => 1, 'all' => '0, 1')) { +/** + * Return all blocks in the specified region for the current user. + * + * @param $region + * This is a string which describes in a human readable form which region + * you need. + * + * @param $regions + * This is an optional array and contains map(s) from the string $region to + * the numerical region value(s) in the blocks table. + * + * @return + * An array of block objects, indexed with module_delta. + * If you are displaying your blocks in one or two sidebars, you may check + * whether this array is empty to see how many columns are going to be + * displayed. + * + * @todo + * Add a proper primary key (bid) to the blocks table so we don't have + * to mess around with this module_delta construct. + * Currently, the blocks table has no primary key defined! + */ +function block_list($region) { global $user; + static $blocks = array(); if (!isset($blocks[$region])) { $blocks[$region] = array(); - $result = db_query("SELECT * FROM {blocks} WHERE status = 1 AND region IN ('%s') ORDER BY weight, module", $regions[$region]); + $result = db_query("SELECT * FROM {blocks} WHERE status = 1 AND region = '%s' ORDER BY weight, module", $region); while ($block = db_fetch_array($result)) { // Use the user's block visibility setting, if necessary if ($block['custom'] != 0) { Index: modules/system.module =================================================================== RCS file: /cvs/drupal/drupal/modules/system.module,v retrieving revision 1.215 diff -u -r1.215 system.module --- modules/system.module 21 Jun 2005 09:45:45 -0000 1.215 +++ modules/system.module 27 Jun 2005 04:07:25 -0000 @@ -193,6 +193,7 @@ $group .= form_textarea(t('Footer message'), 'site_footer', variable_get('site_footer', ''), 70, 5, t('This text will be displayed at the bottom of each page. Useful for adding a copyright notice to your pages.')); $group .= form_textfield(t('Anonymous user'), 'anonymous', variable_get('anonymous', 'Anonymous'), 70, 70, t('The name used to indicate anonymous users.')); $group .= form_textfield(t('Default front page'), 'site_frontpage', variable_get('site_frontpage', 'node'), 70, 70, t('The home page displays content from this relative URL. If you are not using clean URLs, specify the part after "?q=". If unsure, specify "node".')); + $group .= form_select(t('Default region'), 'default_region', variable_get('default_region', 'left'), array_merge(array('0' => '?q= in the URL). You\'ll need ModRewrite support for this to work. See the .htaccess file in Drupal\'s top-level directory for more information.'));
@@ -312,6 +313,7 @@
drupal_load('theme', $themes[$key]->name);
$themes[$key]->owner = $themes[$key]->filename;
$themes[$key]->prefix = $key;
+ $themes[$key]->regions = function_exists($key . '_regions') ? call_user_func($key . '_regions') : array();
}
// Remove all theme engines from the system table
@@ -323,17 +325,27 @@
drupal_load('theme_engine', $engine->name);
db_query("INSERT INTO {system} (name, type, filename, status, throttle, bootstrap) VALUES ('%s', '%s', '%s', %d, %d, %d)", $engine->name, 'theme_engine', $engine->filename, 1, 0, 0);
+ // Load engine's regions
+ $engine->regions = function_exists($engine->name . '_regions') ? call_user_func($engine->name . '_regions') : array();
+
// Add templates to the site listing
foreach (call_user_func($engine->name . '_templates') as $template) {
- $template->template = TRUE;
- $template->name = basename(dirname($template->filename));
- $template->owner = $engine->filename;
- $template->prefix = $engine->name;
- // do not double-insert templates with theme files in their directory
+ // Do not double-insert templates with theme files in their directory,
+ // but do register their engine data.
if (array_key_exists($template->name, $themes)) {
+ $themes[$template->name]->owner = $engine->filename;
+ $themes[$template->name]->prefix = $engine->name;
+ $themes[$template->name]->regions = array_merge($themes[$template->name]->regions, $engine->regions);
continue;
}
- $themes[$template->name] = $template;
+ else {
+ $template->template = TRUE;
+ $template->name = basename(dirname($template->filename));
+ $template->owner = $engine->filename;
+ $template->prefix = $engine->name;
+ $template->regions = $engine->regions;
+ $themes[$template->name] = $template;
+ }
}
}
@@ -345,6 +357,7 @@
$style->name = basename(dirname($style->filename));
$style->owner = $theme->filename;
$style->prefix = $theme->template ? $theme->prefix : $theme->name;
+ $style->regions = array();
// do not double-insert styles with theme files in their directory
if (array_key_exists($style->name, $themes)) {
continue;
@@ -366,6 +379,63 @@
}
/**
+ * Get a list of all defined regions.
+ *
+ * @return
+ * An array of all regions.
+ */
+function system_region_list($theme_key = null, $mark_nondefault = false, $scope = 'all') {
+ global $theme, $theme_engine;
+
+ // Load any module-defined regions.
+ $regions = module_invoke_all('regions');
+ if (!$theme || !$theme_engine) {
+ $theme = init_theme();
+ }
+
+ $themes = system_theme_data();
+
+ // Load default theme's regions.
+ $regions = array_merge($regions, $themes[$theme]->regions);
+ if($theme_key) {
+ $regions = array_merge($regions, $themes[$theme_key]->regions);
+ }
+ else {
+ foreach ($themes as $info) {
+ if (!$info->style) {
+ switch ($scope) {
+ case 'all':
+ $regions = array_merge($regions, $info->regions);
+ break;
+ case 'core':
+ $regions = array_intersect($regions, $info->regions);
+ break;
+ }
+ }
+ }
+ // Ensure default theme's region titles override other titles.
+ switch ($scope) {
+ case 'all':
+ $regions = array_merge($regions, $themes[$theme]->regions);
+ break;
+ case 'core':
+ $regions = array_intersect($themes[$theme]->regions, $regions);
+ break;
+ }
+
+ if (($scope != 'core') && $mark_nondefault) {
+ foreach ($regions as $key => $value) {
+ // If the selected region is not one of the defined regions for the default theme, asterix it.
+ if (!array_key_exists ($key, $themes[$theme]->regions)) {
+ $regions[$key] .= '*';
+ }
+ }
+ }
+ }
+ return $regions;
+}
+
+/**
* Returns an array of files objects of the given type from both the
* site-wide directory (i.e. modules/) and site-specific directory
* (i.e. sites/somesite/modules/). The returned array will be keyed
Index: themes/chameleon/chameleon.theme
===================================================================
RCS file: /cvs/drupal/drupal/themes/chameleon/chameleon.theme,v
retrieving revision 1.30
diff -u -r1.30 chameleon.theme
--- themes/chameleon/chameleon.theme 6 Jun 2005 14:07:04 -0000 1.30
+++ themes/chameleon/chameleon.theme 24 Jun 2005 17:17:19 -0000
@@ -16,6 +16,13 @@
'toggle_secondary_links');
}
+function chameleon_regions() {
+ return array(
+ 'left' => t('left sidebar'),
+ 'right' => t('right sidebar')
+ );
+}
+
function chameleon_page($content) {
$language = $GLOBALS['locale'];
Index: themes/engines/phptemplate/phptemplate.engine
===================================================================
RCS file: /cvs/drupal/drupal/themes/engines/phptemplate/phptemplate.engine,v
retrieving revision 1.4
diff -u -r1.4 phptemplate.engine
--- themes/engines/phptemplate/phptemplate.engine 25 May 2005 06:03:18 -0000 1.4
+++ themes/engines/phptemplate/phptemplate.engine 27 Jun 2005 04:32:02 -0000
@@ -17,6 +17,22 @@
return system_listing('^page\.tpl\.php$', $directory, 'filename');
}
+function phptemplate_regions() {
+ return array(
+ 'left' => t('left sidebar'),
+ 'right' => t('right sidebar'),
+ 'primary_links' => t('primary links'),
+ 'secondary_links' => t('secondary links'),
+ 'messages' => t('messages'),
+ 'help' => t('help'),
+ 'content' => t('content'),
+ 'secondary_links' => t('secondary links'),
+ 'right' => t('right sidebar'),
+ 'footer' => t('footer'),
+ 'closure' => t('closure')
+ );
+}
+
/**
* Execute a template engine call.
*
@@ -68,6 +84,7 @@
* A sequential array of variables passed to the theme function.
*/
function _phptemplate_default_variables($hook, $variables) {
+ global $theme;
static $count = array();
$count[$hook] = is_int($count[$hook]) ? $count[$hook] : 1;
$variables['zebra'] = ($count[$hook] % 2) ? 'odd' : 'even';
@@ -79,7 +96,34 @@
$variables['block_zebra'] = ($count['block_counter'][$sidebar_indicator] % 2) ? 'odd' : 'even';
$variables['block_id'] = $count['block_counter'][$sidebar_indicator]++;
}
-
+ elseif ($hook == 'page') {
+ $regions = system_region_list($theme);
+ // Load all region content assigned via blocks.
+ foreach (system_region_list() as $region => $data) {
+ // If blocks in this region have already been loaded, don't reload them.
+ if (!in_array($region, array('left', 'right', 'footer'))) {
+ // If loaded region is present in current theme, set it.
+ if (array_key_exists($region, $regions)) {
+ $variables[$region] .= theme('blocks', $region);
+ }
+ // Otherwise, add its content to the default region.
+ elseif ($default_region = variable_get('default_region', 'left')) {
+ $variables[$default_region] .= theme('blocks', $region);
+ }
+ }
+ }
+ // Load all region content assigned via drupal_set_content() calls.
+ foreach (drupal_get_content() as $region => $data) {
+ // If loaded region is present in current theme, set it.
+ if (array_key_exists($region, $regions)) {
+ $variables[$region] .= $data;
+ }
+ // Otherwise, add its content to the default region.
+ elseif ($default_region = variable_get('default_region', 'left')) {
+ $variables[$default_region] .= $data;
+ }
+ }
+ }
// Tell all templates where they are located.
$variables['directory'] = path_to_theme();
@@ -168,7 +212,7 @@
'sidebar_left' => $sidebar_left,
'content' => '' . $content . '',
'sidebar_right' => $sidebar_right,
- 'footer_message' => variable_get('site_footer', FALSE),
+ 'footer_message' => variable_get('site_footer', FALSE) . "\n" . theme('blocks', 'footer'),
'closure' => theme('closure')
);
if ((arg(0) == 'node') && is_int(arg(1))) {
@@ -244,7 +288,7 @@
* into a pluggable template engine.
*/
function phptemplate_block($block) {
- return _phptemplate_callback('block', array('block' => $block));
+ return $block->themed ? _phptemplate_callback('block', array('block' => $block)) : $block->content;
}
/**