#942310 by an.droid, yched, fago, sun: Fixed Field form cannot be attached more than once

1 files changed, 43 insertions, 9 deletions

diff --git a/modules/field/field.api.php b/modules/field/field.api.php
index 0c24730cb..474499d7c 100644
--- a/modules/field/field.api.php
+++ b/modules/field/field.api.php
@@ -789,7 +789,8 @@ function hook_field_widget_info_alter(&$info) {
  * @see field_widget_instance()
  *
  * @param $form
- *   The entire form array.
+ *   The form structure where widgets are being attached to. This might be a
+ *   full form structure, or a sub-element of a larger form.
  * @param $form_state
  *   An associative array containing the current state of the form.
  * @param $field
@@ -808,6 +809,12 @@ function hook_field_widget_info_alter(&$info) {
  *   - #bundle: The name of the field bundle the field is contained in.
  *   - #field_name: The name of the field.
  *   - #language: The language the field is being edited in.
+ *   - #field_parents: The 'parents' space for the field in the form. Most
+ *       widgets can simply overlook this property. This identifies the
+ *       location where the field values are placed within
+ *       $form_state['values'], and is used to access processing information
+ *       for the field through the field_form_get_state() and
+ *       field_form_set_state() functions.
  *   - #columns: A list of field storage columns of the field.
  *   - #title: The sanitized element label for the field instance, ready for
  *     output.
@@ -844,7 +851,8 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
  *     errors to different form elements inside the widget.
  *   - message: the human readable message to be displayed.
  * @param $form
- *   The form array.
+ *   The form structure where field elements are attached to. This might be a
+ *   full form structure, or a sub-element of a larger form.
  * @param $form_state
  *   An associative array containing the current state of the form.
  */
@@ -1079,7 +1087,7 @@ function hook_field_formatter_view($entity_type, $entity, $field, $instance, $la
  */
 
 /**
- * Act on field_attach_form.
+ * Act on field_attach_form().
  *
  * This hook is invoked after the field module has performed the operation.
  * Implementing modules should alter the $form or $form_state parameters.
@@ -1087,10 +1095,15 @@ function hook_field_formatter_view($entity_type, $entity, $field, $instance, $la
  * @param $entity_type
  *   The type of $entity; for example, 'node' or 'user'.
  * @param $entity
- *   The entity for which to load form elements, used to initialize
- *   default form values.
+ *   The entity for which an edit form is being built.
  * @param $form
- *   The form structure to fill in.
+ *   The form structure where field elements are attached to. This might be a
+ *   full form structure, or a sub-element of a larger form. The
+ *   $form['#parents'] property can be used to identify the corresponding part
+ *   of $form_state['values']. Hook implementations that need to act on the
+ *   top-level properties of the global form (like #submit, #validate...) can
+ *   add a #process callback to the array received in the $form parameter, and
+ *   act on the $complete_form parameter in the process callback.
  * @param $form_state
  *   An associative array containing the current state of the form.
  * @param $langcode
@@ -1098,7 +1111,12 @@ function hook_field_formatter_view($entity_type, $entity, $field, $instance, $la
  *   is provided the default site language will be used.
  */
 function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode) {
-  // @todo Needs function body.
+  // Add a checkbox allowing a given field to be emptied.
+  // See hook_field_attach_submit() for the corresponding processing code.
+  $form['empty_field_foo'] = array(
+    '#type' => 'checkbox',
+    '#title' => t("Empty the 'field_foo' field"),
+  );
 }
 
 /**
@@ -1136,10 +1154,26 @@ function hook_field_attach_validate($entity_type, $entity, &$errors) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_submit() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; for example, 'node' or 'user'.
+ * @param $entity
+ *   The entity for which an edit form is being submitted. The incoming form
+ *   values have been extracted as field values of the $entity object.
+ * @param $form
+ *   The form structure where field elements are attached to. This might be a
+ *   full form structure, or a sub-part of a larger form. The $form['#parents']
+ *   property can be used to identify the corresponding part of
+ *   $form_state['values'].
+ * @param $form_state
+ *   An associative array containing the current state of the form.
  */
 function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) {
-  // @todo Needs function body.
+  // Sample case of an 'Empty the field' checkbox added on the form, allowing
+  // a given field to be emptied.
+  $values = drupal_array_get_nested_value($form_state['values'], $form['#parents']);
+  if (!empty($values['empty_field_foo'])) {
+    unset($entity->field_foo);
+  }
 }
 
 /**