form_set_value

Versions
4.7 – 5: form_set_value($form, $value)
6: form_set_value($form_item, $value, &$form_state)
7: form_set_value($element, $value, &$form_state)

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'.

Parameters

$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.

$value The new value for the form item.

$form_state The array where the value change should be recorded.

▸ 8 functions call form_set_value()

▾ 8 functions call form_set_value()

node_search_validate in modules/node/node.module: Form API callback for the search form. Registered in node_form_alter().
node_teaser_include_verify in modules/node/node.module: Ensure value of "teaser_include" checkbox is consistent with other form data.
node_teaser_js in modules/node/node.module: See if the user used JS to submit a teaser.
password_confirm_validate in includes/form.inc: Validate password_confirm element.
search_form_validate in modules/search/search.pages.inc: As the search form collates keys from other modules hooked in via hook_form_alter, the validation takes place in _submit. search_form_validate() is used solely to set the 'processed_keys' form value for the basic search form.
user_pass_validate in modules/user/user.pages.inc
_form_builder_handle_input_element in includes/form.inc: Populate the #value and #name properties of input elements so they can be processed and rendered. Also, execute any #process handlers attached to a specific element.
_install_settings_form_validate in ./install.php: Helper function for install_settings_validate.

Code

includes/form.inc, line 1318

<?php
function form_set_value($form_item, $value, &$form_state) {
  _form_set_value($form_state['values'], $form_item, $form_item['#parents'], $value);
}
?>

Code Example

lance.gliser - Mon, 2009-09-07 06:19

Having fought with this for a couple hours now, I thought I'd leave notes of what I found here.
Before I begin:
http://drupal.org/node/160160 is unclear, but is the top result after this page on search engines due to length. This page may need to be updated if the proper documentation can not be understood from this page.

When using drupal 6, this is the process you must use:

Optional

<?php
function hook_form(){
//... Previous Code

// You *can* (and should) declare a placeholder for the value to be inserted into later.
$form['placeholder'] = array(
 '#type' => 'value'
 ,'#value' = > NULL // Placeholder value. Meaningless
);
//... Other Code
}
?>

Required

Because the form_set_value function requires more arguments than standard hook_validate functions provide, you must use hook_form_alter to do custom validation for your form:

<?php
function hook_form_alter(&$form, $form_state, $form_id){
 if ($form_id == '{node_type}_node_form') {
  $form['#validate'][] = 'hook_validate_custom';
 }
?>

With the form set to validate through your new function, create it. Note that $form_state must be a reference.

<?php
hook_validate_custom($form, &$form_state){
 // ... Validation Code
 form_set_value( array('#parents' => array('array_key_parent', 'array_key_to_replace')) , $value, $form_state);
 // ... Other Code
}
?>

Sorry for the inline array.
Here's a breakdown of the three parameters you must pass in:

An array with one item: '#parents'. '#parents' is another array. '#parents' should be the arrays keys needed to reach the form value you want to replace. For instance:

<?php $first_parameter = array( '#parents' => array( 'first_key_in_path' ,'second_key_in_path' ,'key_to_replace' // Always the last one. *Will* create if it doesn't exist. ) ); ?>
The value you want inserted.
$form_state

Another example

Todd Nienkerk - Mon, 2009-10-12 03:13

I banged my head against this same problem for about an hour. Here's how I solved it.

What I wanted to do

I needed to hide the default "Title" field and automatically populate it using two CCK fields: "First name" and "Last name." The value of the "Title" field would be: "[First name] [Last name]."

How I did it

First, I had to implement hook_form_FORM_ID_alter() for the "profile" content type's node form:

<?php
function mymodule_form_profile_node_form_alter(&$form, &$form_state) {
  // Hide the extraneous title ("Name") field
  $form['title']['#type'] = 'hidden';

  // Add placeholder for #value
  $form['title']['#value'] = NULL;

  // Add a validation function that will fill in the value of the title ("Name") field
  $form['#validate'][] = 'mymodule_profile_node_form_validate';
}
?>

In this case, the placeholder value was required. The form would throw this error otherwise: "The Title field is required."

Second, I implemented the validation form I assigned in hook_form_FORM_ID_alter() above:

<?php
function mymodule_profile_node_form_validate($form, &$form_state) {
  $name = $form_state['values']['field_profile_firstname'][0]['value'] . ' ' . $form_state['values']['field_profile_lastname'][0]['value'];
  form_set_value($form['title'], $name, $form_state);
}
?>

In this case, I was able to pass form_set_value() the form element itself: $form['title']. Passing it a nested array, as described in the above comment, failed.