Index: modules/field/field.attach.inc =================================================================== RCS file: /cvs/drupal/drupal/modules/field/field.attach.inc,v retrieving revision 1.33 diff -u -p -r1.33 field.attach.inc --- modules/field/field.attach.inc 16 Jul 2009 10:30:12 -0000 1.33 +++ modules/field/field.attach.inc 8 Aug 2009 19:32:35 -0000 @@ -58,14 +58,14 @@ class FieldQueryException extends FieldE */ /** - * 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'); @@ -135,6 +135,7 @@ define('FIELD_STORAGE_INSERT', 'insert') * - delete revision * - sanitize * - view + * - preprocess * - prepare translation * @param $obj_type * The type of $object; e.g. 'node' or 'user'. @@ -353,9 +354,96 @@ function _field_invoke_multiple_default( * The form structure to fill in. * @param $form_state * An associative array containing the current state of the form. - * - * TODO : document the resulting $form structure, like we do for - * field_attach_view(). + * @return + * An associative array that is combined the with original form. Note that the orginial $form + * is also modified inside the call to field_attach_form. It is passed in by reference. + * The elements listed are the only ones either added of changed. + * The $form array with a field named 'field_foo' will look like: + * $form array( + * '#fields' = > array( + * // One sub-array where the key is the field name for each field in the bundle. + * 'field_foo' => array ( + * 'field' => the field definition structure, + * 'instance' => the field instance definition structure, + * 'form_path' => 'field_name', + * ) + * ) + * // Unless it is AHAH then TRUE. + * '#cache' => FALSE + * // One sub-array where the key is the field name for each field in the bundle. + * 'field_foo' array( + * '#theme' => 'field_multiple_value_form', + * // Number of field values. + * '#multiple' => the field cardinality, + * // Field title. + * '#title' => the label of the field instance, + * // Whether or not it is required. + * '#required' => FALSE, + * // One numbered sub-array for each field value. + * // Only multiple form elements: one numbered sub-array + * // for each field value. + * 0 => array( + * '#type' => 'widget type', + * '#default_value' => array) + * 'value' => 'value0', + * 'format' => null, + * 'safe' => 'value0', + * ) + * // Whether or not field is required. + * '#required' => TRUE, + * '#columns' => array( + * 0 => 'value', + * 1 => 'format', + * ) + * '#title' => the label of the field instance, + * // Value index. + * '#delta' => 0, + * '#field_name' => 'field_name', + * '#bundle' => $bundle, + * ) + * 1 => array( + * '#type' => 'widget type', + * '#default_value' => array) + * 'value' => 'value1', + * 'format' => null, + * 'safe' => 'value1', + * ) + * '#title' => the label of the field instance, + * // Whether or not field is required. + * '#required' => TRUE, + * '#weight' => weight of this value + * // Value index. + * '#delta' => 1, + * '#columns' => array( + * 0 => 'value', + * 1 => 'format', + * ) + * '#field_name' => 'field_name', + * '#bundle' => $bundle, + * ) + * 2 => array( + * '#type' => 'widget type', + * '#default_value' => array( + * 'value' => 'value2', + * 'format' => null, + * 'safe' => 'value2', + * ) + * // Whether or not field is required. + * '#required' => TRUE, + * '#columns' => array( + * 0 => 'value', + * 1 => 'format', + * ) + * '#title' => the label of the field instance, + * // Value index. + * '#delta' => 2, + * '#field_name' => 'field_name', + * '#bundle' => $bundle, + * ) + * '#field_name' => 'field_name', + * '#tree' => TRUE, + * '#weight' => 'weight', + * ) */ function field_attach_form($obj_type, $object, &$form, &$form_state) { $form += (array) _field_invoke_default('form', $obj_type, $object, $form, $form_state); @@ -877,8 +965,61 @@ function field_attach_query_revisions($f * The object with fields to render. * @param $build_mode * Build mode, e.g. 'full', 'teaser'... - * @return * A structured content array tree for drupal_render(). + * 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(). + * The $object array will look like: + * $object->content['field_foo']['wrapper'] = array( + * '#theme' => 'field', + * '#title' => label of field instance + * '#field_name' => 'field_name', + * '#object' => $object, + * '#object_type' => $obj_type, + * // Value of the $teaser param of hook_node('view'). + * '#teaser' => $teaser, + * 'items' => + * // One numbered sub-array for each field value. + * // Only multiple form elements: one numbered sub-array + * // for each field value. + * 0 => array( + * '#item' => $items[0], + * '#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], + * '#theme' => $theme, + * '#field_name' => 'field_name', + * '#bundle' => $bundle_name, + * '#formatter' => $formatter_name, + * '#settings' => $formatter_settings, + * '#object' => $object, + * '#object_type' => $obj_type, + * '#delta' => 1, + * ), + * '#theme' => $theme, + * '#field_name' => 'field_name', + * '#bundle' => $bundle_name, + * '#formatter' => $formatter_name, + * '#settings' => $formatter_settings, + * '#object' => $object, + * '#object_type' => $obj_type, + * ), + * ); */ function field_attach_view($obj_type, $object, $build_mode = 'full') { // Let field modules sanitize their data for output. Index: modules/field/field.default.inc =================================================================== RCS file: /cvs/drupal/drupal/modules/field/field.default.inc,v retrieving revision 1.12 diff -u -p -r1.12 field.default.inc --- modules/field/field.default.inc 2 Aug 2009 11:24:21 -0000 1.12 +++ modules/field/field.default.inc 8 Aug 2009 19:32:35 -0000 @@ -1,5 +1,5 @@ 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(). - * - * 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, - * ), - * ); + * Default field 'view' operation + * @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);