#361839 by puradata and yched: Document return structures from field attach.

2 files changed, 112 insertions, 59 deletions

diff --git a/modules/field/field.attach.inc b/modules/field/field.attach.inc
index cf510ba26..9326638c0 100644
--- a/modules/field/field.attach.inc
+++ b/modules/field/field.attach.inc
@@ -58,14 +58,16 @@ class FieldQueryException extends FieldException {}
  */
 
 /**
- * Argument for an insert operation.
+ * Argument for an update operation.
+ *
  * This is used in hook_field_storage_write when updating an
  * existing object.
  */
 define('FIELD_STORAGE_UPDATE', 'update');
 
 /**
- * Argument for an update operation.
+ * Argument for an insert operation.
+ *
  * This is used in hook_field_storage_write when inserting a new object.
  */
 define('FIELD_STORAGE_INSERT', 'insert');
@@ -353,9 +355,65 @@ function _field_invoke_multiple_default($op, $obj_type, $objects, &$a = NULL, &$
  *   The form structure to fill in.
  * @param $form_state
  *   An associative array containing the current state of the form.
+ * @return
+ *   The form elements are added by reference at the top level of the $form
+ *   parameter. Sample structure:
+ *   @code
+ *   array(
+ *     '#fields' => array(
+ *       // One sub-array per field appearing in the form, keyed by field name.
+ *       'field_foo' => array (
+ *         'field' => the field definition structure,
+ *         'instance' => the field instance definition structure,
+ *         'form_path' => an array of keys indicating the path to the field
+ *           element within the full $form structure, used by the 'add more
+ *           values' AHAH button. Any 3rd party module using form_alter() to
+ *           modify the structure of the form should update this entry as well.
+ *       ),
+ *     ),
  *
- * TODO : document the resulting $form structure, like we do for
- * field_attach_view().
+ *     // One sub-array per field appearing in the form, keyed by field name.
+ *     // The structure of the array differs slightly depending on whether the
+ *     // widget is 'single-value' (provides the input for one field value,
+ *     // most common case), and will therefore be repeated as many times as
+ *     // needed, or 'multiple-values' (one single widget allows the input of
+ *     // several values, e.g checkboxes, select box...).
+ *     'field_foo' => array(
+ *       '#field_name' => the name of the field,
+ *       '#tree' => TRUE,
+ *       '#required' => whether or not the field is required,
+ *       '#title' => the label of the field instance,
+ *       '#description' => the description text for the field instance,
+ *
+ *       // Only for 'single' widgets:
+ *       '#theme' => 'field_multiple_value_form',
+ *       '#multiple' => the field cardinality,
+ *       // One sub-array per copy of the widget, keyed by delta.
+ *       0 => array(
+ *         '#title' => the title to be displayed by the widget,
+ *         '#default_value' => the field value for delta 0,
+ *         '#required' => whether the widget should be marked required,
+ *         '#delta' => 0,
+ *         '#field_name' => the name of the field,
+ *         '#bundle' => the name of the bundle,
+ *         '#columns' => the array of field columns,
+ *         // The remaining elements in the sub-array depend on the widget.
+ *         '#type' => the type of the widget,
+ *         ...
+ *       ),
+ *       1 => array(
+ *         ...
+ *       ),
+ *
+ *       // Only for multiple widgets:
+ *       '#bundle' => $instance['bundle'],
+ *       '#columns'  => array_keys($field['columns']),
+ *       // The remaining elements in the sub-array depend on the widget.
+ *       '#type' => the type of the widget,
+ *       ...
+ *     ),
+ *   )
+ *   @endcode
  */
 function field_attach_form($obj_type, $object, &$form, &$form_state) {
   $form += (array) _field_invoke_default('form', $obj_type, $object, $form, $form_state);
@@ -879,6 +937,54 @@ function field_attach_query_revisions($field_name, $conditions, $count, &$cursor
  *   Build mode, e.g. 'full', 'teaser'...
  * @return
  *   A structured content array tree for drupal_render().
+ *   Sample structure:
+ *   @code
+ *   array(
+ *     'field_foo' => array(
+ *       // The structure of the array differs slightly depending on whether
+ *       // the formatter is 'single-value' (displays one single field value,
+ *       // most common case) or 'multiple-values' (displays all the field's
+ *       // values, e.g. points on a graph or a map).
+ *       '#theme' => 'field',
+ *       '#title' => the label of the field instance,
+ *       '#label_display' => the label display mode,
+ *       '#object' => the fieldable object being displayed,
+ *       '#object_type' => the type of the object being displayed,
+ *       '#build_mode' => the build mode,
+ *       '#field_name' => the name of the field,
+ *       '#single' => boolean indicating whether the formatter is single or
+ *         multiple,
+ *       'items' => array(
+ *         // One sub-array per field value, keyed by delta.
+ *         0 => array(
+ *           '#item' => the field value for delta 0,
+ *
+ *           // Only for 'single-value' formatters:
+ *           '#theme' => the formatter's theme function,
+ *           '#formatter' => name of the formatter,
+ *           '#settings' => array of formatter settings,
+ *           '#object' => the fieldable object being displayed,
+ *           '#object_type' => the type of the object being displayed,
+ *           '#field_name' => the name of the field,
+ *           '#bundle' => the object's bundle,
+ *           '#delta' => 0,
+ *         ),
+ *         1 => array(
+ *           ...
+ *         ),
+ *
+ *         // Only for 'multiple-values' formatters:
+ *         '#theme' => the formatter's theme function,
+ *         '#formatter' => name of the formatter,
+ *         '#settings' => array of formatter settings,
+ *         '#object' => the fieldable object being displayed,
+ *         '#object_type' => the type of the object being displayed,
+ *         '#field_name' => the name of the field,
+ *         '#bundle' => the object's bundle,
+ *       ),
+ *     ),
+ *   );
+ *   @endcode
  */
 function field_attach_view($obj_type, $object, $build_mode = 'full') {
   // Let field modules sanitize their data for output.
diff --git a/modules/field/field.default.inc b/modules/field/field.default.inc
index 537583264..71906c625 100644
--- a/modules/field/field.default.inc
+++ b/modules/field/field.default.inc
@@ -50,63 +50,10 @@ function field_default_insert($obj_type, $object, $field, $instance, &$items) {
     }
   }
 }
-
 /**
- * The 'view' operation constructs the $object in a way that you can use
- * drupal_render() to display the formatted output for an individual field.
- * i.e. print drupal_render($object->content['field_foo']);
- *
- * The code supports both single value formatters, which theme an individual
- * item value, and multiple value formatters, which theme all values for the
- * field in a single theme. The multiple value formatters could be used, for
- * instance, to plot field values on a single map or display them in a graph.
- * Single value formatters are the default, multiple value formatters can be
- * designated as such in formatter_info().
+ * Default field 'view' operation.
  *
- * The $object array will look like:
- *   $object->content['field_foo'] = array(
- *     '#theme' => 'field',
- *     '#title' => 'label'
- *     '#field_name' => 'field_name',
- *     '#object' => $object,
- *     '#object_type' => $obj_type,
- *     // Value of the $build_mode param of hook_node('view').
- *     '#build_mode' => $build_mode,
- *     'items' =>
- *       0 => array(
- *         '#item' => $items[0],
- *         // Only for 'single-value' formatters
- *         '#theme' => $theme,
- *         '#field_name' => 'field_name',
- *         '#bundle' => $bundle,
- *         '#formatter' => $formatter_name,
- *         '#settings' => $formatter_settings,
- *         '#object' => $object,
- *         '#object_type' => $obj_type,
- *         '#delta' => 0,
- *       ),
- *       1 => array(
- *         '#item' => $items[1],
- *         // Only for 'single-value' formatters
- *         '#theme' => $theme,
- *         '#field_name' => 'field_name',
- *         '#bundle' => $bundle_name,
- *         '#formatter' => $formatter_name,
- *         '#settings' => $formatter_settings,
- *         '#object' => $object,
- *         '#object_type' => $obj_type,
- *         '#delta' => 1,
- *       ),
- *       // Only for 'multiple-value' formatters
- *       '#theme' => $theme,
- *       '#field_name' => 'field_name',
- *       '#bundle' => $bundle_name,
- *       '#formatter' => $formatter_name,
- *       '#settings' => $formatter_settings,
- *       '#object' => $object,
- *       '#object_type' => $obj_type,
- *     ),
- *   );
+ * @see field_attach_view()
  */
 function field_default_view($obj_type, $object, $field, $instance, $items, $build_mode) {
   list($id, $vid, $bundle) = field_attach_extract_ids($obj_type, $object);