Index: developer/hooks/core.php
===================================================================
RCS file: /cvs/drupal/contributions/docs/developer/hooks/core.php,v
retrieving revision 1.175
diff -u -p -r1.175 core.php
--- developer/hooks/core.php	30 Apr 2008 15:47:11 -0000	1.175
+++ developer/hooks/core.php	5 May 2008 16:13:45 -0000
@@ -100,14 +100,17 @@ function hook_action_info() {
  *   - 'save': Save the configuration options.
  *   - 'view': Information about a particular block and default settings.
  * @param $delta
- *   Which block to return (not applicable if $op is 'list'). Although it is
- *   most commonly an integer starting at 0, this is not mandatory. For
- *   instance, aggregator.module uses string values for $delta
+ *   Which block to return (not applicable if $op is 'list'). This is a
+ *   descriptive string used to identify blocks within each module and also
+ *   within the theme system. The $delta for each block is defined within
+ *   the array that your module returns when $op is 'list' (see below).
  * @param $edit
  *   If $op is 'save', the submitted form data from the configuration form.
  * @return
- *   - If $op is 'list': An array of block descriptions. Each block description
- *     is an associative array, with the following key-value pairs:
+ *   - If $op is 'list': 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
@@ -136,28 +139,34 @@ function hook_action_info() {
  *   - If $op is 'view': return an array which must define a 'subject' element
  *     and a 'content' element defining the block indexed by $delta.
  *
- * The functions mymodule_display_block_1 and 2, 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.
+ * 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.
  *
  * After completing your blocks, do not forget to enable them in the
  * block admin menu.
  *
  * For a detailed usage example, see block_example.module.
  */
-function hook_block($op = 'list', $delta = 0, $edit = array()) {
+function hook_block($op = 'list', $delta = '', $edit = array()) {
   if ($op == 'list') {
-    $blocks[0] = array('info' => t('Mymodule block #1 shows ...'),
-      'weight' => 0, 'status' => 1, 'region' => 'left');
+    $blocks['exciting'] = array(
+      'info' => t('An exciting block provided by Mymodule.'),
+      'weight' => 0,
+      'status' => 1,
+      'region' => 'left',
       // BLOCK_CACHE_PER_ROLE will be assumed for block 0.
+    );
 
-    $blocks[1] = array('info' => t('Mymodule block #2 describes ...'),
-      'cache' => BLOCK_CACHE_PER_ROLE | BLOCK_CACHE_PER_PAGE);
+    $blocks['amazing'] = array(
+      'info' => t('An amazing block provided by Mymodule.'),
+      'cache' => BLOCK_CACHE_PER_ROLE | BLOCK_CACHE_PER_PAGE,
+    );
 
     return $blocks;
   }
-  else if ($op == 'configure' && $delta == 0) {
+  else if ($op == 'configure' && $delta == 'exciting') {
     $form['items'] = array(
       '#type' => 'select',
       '#title' => t('Number of items'),
@@ -166,18 +175,22 @@ function hook_block($op = 'list', $delta
     );
     return $form;
   }
-  else if ($op == 'save' && $delta == 0) {
+  else if ($op == 'save' && $delta == 'exciting') {
     variable_set('mymodule_block_items', $edit['items']);
   }
   else if ($op == 'view') {
     switch($delta) {
-      case 0:
-        $block = array('subject' => t('Title of block #1'),
-          'content' => mymodule_display_block_1());
+      case 'exciting':
+        $block = array(
+          'subject' => t('Default title of the exciting block'),
+          'content' => mymodule_display_block_exciting(),
+        );
         break;
-      case 1:
-        $block = array('subject' => t('Title of block #2'),
-          'content' => mymodule_display_block_2());
+      case 'amazing':
+        $block = array(
+          'subject' => t('Default title of the amazing block'),
+          'content' => mymodule_display_block_amazing(),
+        );
         break;
     }
     return $block;
Index: developer/examples/block_example.module
===================================================================
RCS file: /cvs/drupal/contributions/docs/developer/examples/block_example.module,v
retrieving revision 1.9
diff -u -p -r1.9 block_example.module
--- developer/examples/block_example.module	6 Jul 2007 18:16:15 -0000	1.9
+++ developer/examples/block_example.module	5 May 2008 16:13:45 -0000
@@ -13,19 +13,19 @@
  * This hook both declares to Drupal what blocks are provided by the module, and
  * generates the contents of the blocks themselves.
  */
-function block_example_block($op = 'list', $delta = 0, $edit = array()) {
+function block_example_block($op = 'list', $delta = '', $edit = array()) {
   // The $op parameter determines what piece of information is being requested.
   switch ($op) {
     case 'list':
       // If $op is "list", we just need to return a list of block descriptions.
-      // This is used to provide a list of possible blocks to the administrator,
+      // This is used to provide a list of possible blocks to the administrator;
       // end users will not see these descriptions.
-      $blocks[0] = array(
+      $blocks['configurable-text'] = array(
         'info'       => t('Example: configurable text string'),
       );
       // A block can provide default settings. In this case we'll enable the 
       // block and make it visible only on the 'node/*' pages. 
-      $blocks[1] = array(
+      $blocks['empty'] = array(
         'info'       => t('Example: empty block'),
         'status'     => TRUE,
         'weight'     => 0,
@@ -39,7 +39,7 @@ function block_example_block($op = 'list
       // configured. In this example, we'll allow the administrator to customize
       // the text of the first block.
       $form = array();
-      if ($delta == 0) {
+      if ($delta == 'configurable-text') {
         // All we need to provide is a text field, Drupal will take care of
         // the other block configuration options and the save button.
         $form['block_example_string'] = array(
@@ -55,16 +55,16 @@ function block_example_block($op = 'list
       // If $op is "save", we need to save settings from the configuration form.
       // Since the first block is the only one that allows configuration, we
       // need to check $delta to make sure we only save it.
-      if ($delta == 0) {
+      if ($delta == 'configurable-text') {
         // Have Drupal save the string to the database.
         variable_set('block_example_string', $edit['block_example_string']);
       }
       return;
-    case 'view': default:
+    case 'view':
       // If $op is "view", then we need to generate the block for display
       // purposes. The $delta parameter tells us which block is being requested.
       switch ($delta) {
-        case 0:
+        case 'configurable-text':
           // The subject is displayed at the top of the block. Note that it
           // should be passed through t() for translation.
           $block['subject'] = t('Title of block #1');
@@ -72,7 +72,7 @@ function block_example_block($op = 'list
           // function.
           $block['content'] = block_example_contents(1);
           break;
-        case 1:
+        case 'empty':
           $block['subject'] = t('Title of block #2');
           $block['content'] = block_example_contents(2);
           break;