5 files changed, 59 insertions, 18 deletions
diff --git a/includes/common.inc b/includes/common.inc
index ce21e4fa49a5..ca143d457816 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -3904,6 +3904,12 @@ function drupal_render_page($page) {
     drupal_set_page_content($page);
     $page = element_info('page');
   }
+
+  // Modules can add elements to $page as needed in hook_page_build().
+  foreach (module_implements('page_build') as $module) {
+    $function = $module . '_page_build';
+    $function($page);
+  }
   // Modules alter the $page as needed. Blocks are populated into regions like
   // 'sidebar_first', 'footer', etc.
   drupal_alter('page', $page);
diff --git a/modules/block/block.module b/modules/block/block.module
index f99a9bbc3b48..92c8fc542761 100644
--- a/modules/block/block.module
+++ b/modules/block/block.module
@@ -235,7 +235,7 @@ function block_block_view($delta = 0, $edit = array()) {
  *
  * Render blocks into their regions.
  */
-function block_page_alter($page) {
+function block_page_build(&$page) {
   global $theme;
 
   // The theme system might not yet be initialized. We need $theme.
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 6ec40db0153a..aed81c5a27e5 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -400,20 +400,57 @@ function hook_css_alter(&$css) {
 }
 
 /**
+ * Add elements to a page before it is rendered.
+ *
+ * Use this hook when you want to add elements at the page level. For your
+ * additions to be printed, they have to be placed below a top level array key
+ * of the $page array that has the name of a region of the active theme.
+ *
+ * By default, valid region keys are 'page_top', 'header', 'sidebar_first',
+ * 'content', 'sidebar_second' and 'page_bottom'. To get a list of all regions
+ * of the active theme, use system_region_list($theme). Note that $theme is a
+ * global variable.
+ *
+ * If you want to alter the elements added by other modules or if your module
+ * depends on the elements of other modules, use hook_page_alter() instead which
+ * runs after this hook.
+ *
+ * @param $page
+ *   Nested array of renderable elements that make up the page.
+ *
+ * @see hook_page_alter()
+ * @see drupal_render_page()
+ */
+function hook_page_build(&$page) {
+  if (menu_get_object('node', 1)) {
+    // We are on a node detail page. Append a standard disclaimer to the
+    // content region.
+    $page['content']['disclaimer'] = array(
+      '#markup' => t('Acme, Inc. is not responsible for the contents of this sample code.'),
+      '#weight' => 25,
+    );
+  }
+}
+
+/**
  * Perform alterations before a page is rendered.
  *
- * Use this hook when you want to add, remove, or alter elements at the page
- * level. If you are making changes to entities such as forms, menus, or user
+ * Use this hook when you want to remove or alter elements at the page
+ * level, or add elements at the page level that depend on an other module's
+ * elements (this hook runs after hook_page_build().
+ *
+ * If you are making changes to entities such as forms, menus, or user
  * profiles, use those objects' native alter hooks instead (hook_form_alter(),
  * for example).
  *
  * The $page array contains top level elements for each block region:
  * @code
+ *   $page['page_top']
  *   $page['header']
  *   $page['sidebar_first']
  *   $page['content']
  *   $page['sidebar_second']
- *   $page['footer']
+ *   $page['page_bottom']
  * @endcode
  *
  * The 'content' element contains the main content of the current page, and its
@@ -437,23 +474,21 @@ function hook_css_alter(&$css) {
  * Blocks may be referenced by their module/delta pair within a region:
  * @code
  *   // The login block in the first sidebar region.
- *   $page['sidebar_first']['user-login']['#block'];
+ *   $page['sidebar_first']['user_login']['#block'];
  * @endcode
  *
  * @param $page
  *   Nested array of renderable elements that make up the page.
  *
+ * @see hook_page_build()
  * @see drupal_render_page()
  */
-function hook_page_alter($page) {
-  if (menu_get_object('node', 1)) {
-    // We are on a node detail page. Append a standard disclaimer to the
-    // content region.
-    $page['content']['disclaimer'] = array(
-      '#markup' => t('Acme, Inc. is not responsible for the contents of this sample code.'),
-      '#weight' => 25,
-    );
-  }
+function hook_page_alter(&$page) {
+  // Add help text to the user login block.
+  $page['sidebar_first']['user_login']['help'] = array(
+    '#weight' => -10,
+    '#markup' => t('To post comments or add new content, you first have to log in.'),
+  );
 }
 
 /**
diff --git a/modules/system/system.module b/modules/system/system.module
index d9a29a0cb522..bd72b1fd80bf 100644
--- a/modules/system/system.module
+++ b/modules/system/system.module
@@ -3085,9 +3085,9 @@ function system_retrieve_file($url, $destination = NULL, $overwrite = TRUE) {
 }
 
 /**
- * Implement hook_page_alter().
+ * Implement hook_page_build().
  */
-function system_page_alter(&$page) {
+function system_page_build(&$page) {
   // Automatic cron runs.
   // @see system_run_cron_image()
   if (system_run_cron_image_access()) {
diff --git a/modules/toolbar/toolbar.module b/modules/toolbar/toolbar.module
index e650d8b157ca..b17107c4c162 100644
--- a/modules/toolbar/toolbar.module
+++ b/modules/toolbar/toolbar.module
@@ -31,11 +31,11 @@ function toolbar_theme($existing, $type, $theme, $path) {
 }
 
 /**
- * Implement hook_page_alter().
+ * Implement hook_page_build().
  * 
  * Add admin toolbar to the page_top region automatically.
  */
-function toolbar_page_alter(&$page) {
+function toolbar_page_build(&$page) {
   if (user_access('access toolbar')) {
     $page['page_top']['toolbar'] = toolbar_build();
   }