update theming examples and instructions with new field rendering behaviour

theme/README.txt

 // $Id$
 
 Theming Constructed Content Types
+=================================
 
 After you have designed your content, you will likely want to lay out the
 presentation of the content. This is most easily done with PHPtemplate-based
@@ -9,6 +10,7 @@ level of control you need to exert.
 
 
 Theming individual fields
+-------------------------
 
 This method is straightforward and allows for sensible defaults, but requires a
 modest amount of setup. Place the "field.tpl.php" and "template.php" files in
@@ -31,12 +33,25 @@ contents of the item. You should always use this property in your display for
 security reasons, unless you are very familiar with how to properly process
 output and avoid scripting exploits.
 
-The included example here ("field-field_body.tpl.php") illustrates a
+The included example here ("field-field_my_field.tpl.php") illustrates a
 minimalistic approach to field theming, for a single-valued field. For a more
 flexible template, start from the included "field.tpl.php".
 
+Available variables in field templates :
+$items          : an array containg the values of the field.
+                  $items[n]['view'] contains the ready-to-use, filtered, formatted value
+$label          : the label of the field
+$label_display  : the display settings for the label ('hidden', 'above', or 'inline')
+$field_empty    : TRUE if there is nothing to display in the field
+$field_type     : the type of the field,
+$field_name     : the name of the field,
+$field_type_css : same as above, with '-' signs replaced with '_' for use in css properties
+$field_name_css : same as above, with '-' signs replaced with '_' for use in css properties
+$field          : an array containing the full CCK field object
+
 
 Theming the node as a whole
+---------------------------
 
 If you need more flexibility than is afforded by theming individual fields, you
 may theme the entire node as a unit. This allows you to affect field order, to

theme/node-content_example.tpl.php

@@ -6,13 +6,13 @@
   <span class="submitted"><?php print $submitted?></span>
   <span class="taxonomy"><?php print $terms?></span>
   <div class="content">
-    Here's the body:
-      <?php print $field_body[0]['view']; ?>
+    Here's one field:
+      <?php print $field_my_field[0]['view']; ?>
 
-    And some footnotes:
+    And another:
     <ul>
       <?php
-        foreach ($field_footnotes as $item) {
+        foreach ($field_my_other_field as $item) {
           print '<li>'. $item['view'] .'</li>';
         }
       ?>

theme/template.php

@@ -2,12 +2,24 @@
 // $Id$
 
 function phptemplate_field(&$node, &$field, &$items, $teaser, $page) {
+  $field_empty = TRUE;
+  foreach ($items as $delta => $item) {
+    if (!empty($item['view']) || $item['view'] === "0") {
+      $field_empty = FALSE;
+      break;
+    }
+  }
+
   $variables = array(
     'node' => $node,
     'field' => $field,
     'field_type' => $field['type'],
     'field_name' => $field['field_name'],
+    'field_type_css' => strtr($field['type'], '_', '-'),
+    'field_name_css' => strtr($field['field_name'], '_', '-'),
     'label' => $field['widget']['label'],
+    'label_display' => isset($field['display_settings']['label']['format']) ? $field['display_settings']['label']['format'] : 'above',
+    'field_empty' => $field_empty,
     'items' => $items,
     'teaser' => $teaser,
     'page' => $page,