Index: modules/field/field.attach.inc =================================================================== RCS file: /cvs/drupal/drupal/modules/field/field.attach.inc,v retrieving revision 1.33 diff -u -r1.33 field.attach.inc --- modules/field/field.attach.inc 16 Jul 2009 10:30:12 -0000 1.33 +++ modules/field/field.attach.inc 11 Aug 2009 00:09:11 -0000 @@ -58,14 +58,14 @@ */ /** - * 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 +353,65 @@ * 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 + * 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. + * ), + * ), + * + * // 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 +935,54 @@ * 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. Index: modules/field/field.default.inc =================================================================== RCS file: /cvs/drupal/drupal/modules/field/field.default.inc,v retrieving revision 1.12 diff -u -r1.12 field.default.inc --- modules/field/field.default.inc 2 Aug 2009 11:24:21 -0000 1.12 +++ modules/field/field.default.inc 11 Aug 2009 00:09:11 -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);