diff options
Diffstat (limited to 'includes')
| -rw-r--r-- | includes/form.inc | 38 |
1 files changed, 24 insertions, 14 deletions
diff --git a/includes/form.inc b/includes/form.inc index ac9ea2bb9..83a59fb31 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -1269,20 +1269,30 @@ function form_type_token_value($form, $edit = FALSE) { } /** - * Use this function to make changes to form values in the form validate - * phase, so they will be available in the submit phase in $form_state. - * - * Specifically, if $form['#parents'] is array('foo', 'bar') - * and $value is 'baz' then this function will make - * $form_state['values']['foo']['bar'] to be 'baz'. - * - * @param $form - * The form item. Keys used: #parents, #value + * Change submitted form values during the form processing cycle. + * + * Use this function to change the submitted value of a form item in the + * validation phase so that it persists in $form_state through to the + * submission handlers in the submission phase. + * + * Since $form_state['values'] can either be a flat array of values, or a tree + * of nested values, some care must be taken when using this function. + * Specifically, $form_item['#parents'] is an array that describes the branch of + * the tree whose value should be updated. For example, if we wanted to update + * $form_state['values']['one']['two'] to 'new value', we'd pass in + * $form_item['#parents'] = array('one', 'two') and $value = 'new value'. + * + * @param $form_item + * The form item that should have its value updated. Keys used: #parents, + * #value. In most cases you can just pass in the right element from the $form + * array. * @param $value - * The value for the form item. + * The new value for the form item. + * @param $form_state + * The array where the value change should be recorded. */ -function form_set_value($form, $value, &$form_state) { - _form_set_value($form_state['values'], $form, $form['#parents'], $value); +function form_set_value($form_item, $value, &$form_state) { + _form_set_value($form_state['values'], $form_item, $form_item['#parents'], $value); } /** @@ -1292,7 +1302,7 @@ function form_set_value($form, $value, &$form_state) { * in $form_state['values'] if needed. Then we insert the value into * the right array. */ -function _form_set_value(&$form_values, $form, $parents, $value) { +function _form_set_value(&$form_values, $form_item, $parents, $value) { $parent = array_shift($parents); if (empty($parents)) { $form_values[$parent] = $value; @@ -1301,7 +1311,7 @@ function _form_set_value(&$form_values, $form, $parents, $value) { if (!isset($form_values[$parent])) { $form_values[$parent] = array(); } - _form_set_value($form_values[$parent], $form, $parents, $value); + _form_set_value($form_values[$parent], $form_item, $parents, $value); } } |