Index: modules/block/block.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/block/block.api.php,v
retrieving revision 1.12
diff -u -p -r1.12 block.api.php
--- modules/block/block.api.php	28 Apr 2010 12:36:26 -0000	1.12
+++ modules/block/block.api.php	10 Aug 2010 03:48:29 -0000
@@ -14,19 +14,17 @@
 /**
  * Define all blocks provided by the module.
  *
- * Any module can export a block (or blocks) to be displayed by defining
- * the _block hook. This hook is called by theme.inc to display a block,
- * and also by block.module to procure the list of available blocks.
+ * This hook declares to Drupal what blocks are provided by the module and can
+ * optionally specify block configuration settings.
  *
  * @return
- *   An associative array whose keys define the $delta
- *   for each block and whose values contain the block descriptions. Each
- *   block description is itself an associative array, with the following
- *   key-value pairs:
+ *   An associative array whose keys define the $delta for each block and whose
+ *   values contain the block descriptions. Each block description is itself an
+ *   associative array, with the following key-value pairs:
  *   - 'info': (required) The human-readable name of the block.
- *   - 'cache': A bitmask of flags describing how the block should behave with
- *     respect to block caching. The following shortcut bitmasks are provided
- *     as constants in common.inc:
+ *   - 'cache': A bitmask describing what kind of caching is appropriate
+ *     for the block. common.inc provides the following bitmask constants for
+ *     defining cache granularity:
  *     - DRUPAL_CACHE_PER_ROLE (default): The block can change depending on the
  *       roles the user viewing the page belongs to.
  *     - DRUPAL_CACHE_PER_USER: The block can change depending on the user
@@ -38,14 +36,15 @@
  *     - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every
  *       page where it is visible.
  *     - DRUPAL_NO_CACHE: The block should not get cached.
- *   - 'weight', 'status', 'region', 'visibility', 'pages':
- *     You can give your blocks an explicit weight, enable them, limit them to
- *     given pages, etc. These settings will be registered when the block is first
- *     loaded at admin/block, and from there can be changed manually via block
- *     administration.
- *     Note that if you set a region that isn't available in a given theme, the
- *     block will be registered instead to that theme's default region (the first
- *     item in the _regions array).
+ *   - You may also define: 'weight', 'status', 'region', 'visibility', and
+ *     'pages'. These values are usually assigned through the block
+ *     administration UI, not in hook_block_info(). If defined in
+ *     hook_block_info(), the settings are registered when the block is first
+ *     loaded, and can then be changed manually through the block administration
+ *     UI.
+ *     Note: If you set a region that isn't available in a given theme, the
+ *     block will be registered instead to that theme's default region (the
+ *     first item in the _regions array).
  *
  * After completing your blocks, do not forget to enable them in the
  * block admin menu.
@@ -53,17 +52,14 @@
  * For a detailed usage example, see block_example.module.
  */
 function hook_block_info() {
-  $blocks['exciting'] = array(
-    'info' => t('An exciting block provided by Mymodule.'),
-    'weight' => 0,
-    'status' => 1,
-    'region' => 'sidebar_first',
-    // DRUPAL_CACHE_PER_ROLE will be assumed for block 0.
+  $blocks['syndicate'] = array(
+    'info' => t('Syndicate'),
+    'cache' => DRUPAL_NO_CACHE
   );
 
-  $blocks['amazing'] = array(
-    'info' => t('An amazing block provided by Mymodule.'),
-    'cache' => DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE,
+  $blocks['recent'] = array(
+    'info' => t('Recent content'),
+    // DRUPAL_CACHE_PER_ROLE will be assumed
   );
 
   return $blocks;
@@ -102,15 +98,16 @@ function hook_block_info_alter(&$blocks,
  * For a detailed usage example, see block_example.module.
  */
 function hook_block_configure($delta = '') {
-  if ($delta == 'exciting') {
-    $form['items'] = array(
+  $form = array();
+  if ($delta == 'recent') {
+    $form['node_recent_block_count'] = array(
       '#type' => 'select',
-      '#title' => t('Number of items'),
-      '#default_value' => variable_get('mymodule_block_items', 0),
-      '#options' => array('1', '2', '3'),
+      '#title' => t('Number of recent content items to display'),
+      '#default_value' => variable_get('node_recent_block_count', 10),
+      '#options' => drupal_map_assoc(array(2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 25, 30)),
     );
-    return $form;
   }
+  return $form;
 }
 
 /**
@@ -127,8 +124,8 @@ function hook_block_configure($delta = '
  * For a detailed usage example, see block_example.module.
  */
 function hook_block_save($delta = '', $edit = array()) {
-  if ($delta == 'exciting') {
-    variable_set('mymodule_block_items', $edit['items']);
+  if ($delta == 'recent') {
+    variable_set('node_recent_block_count', $edit['node_recent_block_count']);
   }
 }
 
@@ -144,27 +141,28 @@ function hook_block_save($delta = '', $e
  *   An array which must define a 'subject' element and a 'content' element
  *   defining the block indexed by $delta.
  *
- * The functions mymodule_display_block_exciting and _amazing, as used in the
- * example, should of course be defined somewhere in your module and return the
- * content you want to display to your users. If the "content" element is empty,
- * no block will be displayed even if "subject" is present.
- *
  * For a detailed usage example, see block_example.module.
  */
 function hook_block_view($delta = '') {
+  $block = array();
+
   switch ($delta) {
-    case 'exciting':
-      $block = array(
-        'subject' => t('Default title of the exciting block'),
-        'content' => mymodule_display_block_exciting(),
-      );
+    case 'syndicate':
+      $block['subject'] = t('Syndicate');
+      $block['content'] = theme('feed_icon', array('url' => url('rss.xml'), 'title' => t('Syndicate')));
       break;
 
-    case 'amazing':
-      $block = array(
-        'subject' => t('Default title of the amazing block'),
-        'content' => mymodule_display_block_amazing(),
-      );
+    case 'recent':
+      if (user_access('access content')) {
+        $block['subject'] = t('Recent content');
+        if ($nodes = node_get_recent(variable_get('node_recent_block_count', 10))) {
+          $block['content'] = theme('node_recent_block', array(
+            'nodes' => $nodes,
+          ));
+        } else {
+          $block['content'] = t('No content available.');
+        }
+      }
       break;
   }
   return $block;