Consistently pass in $form_state to #value_callback functions

subscribe

Looks proper to me. Committed!

This needs some documentation as it changes the way the value callback is used. (I only looked at the migration guide)

The Drupal 6 example element page shows why:

<?php
function form_type_example_field_value($element, $edit = FALSE) {
  if (func_num_args() == 1) {
     return $element['#default_value'];
  }
  return $edit;
}
?>

In Drupal 6, that would give false positives to fields that have a value set to FALSE. Thus the check on the number of arguments.

This is from the handbook page: http://drupal.org/node/169815 Creating Custom Elements Using Drupal 6.x

For some reason, I did get this once, but for the life of me, I can not remember the set up. Probably a logical error somewhere else... I'm sure I would have used "===".

But anyway, I think this should be documented somewhere, and since I'm just not sure on the exact place / protocol, I just tagged it. I guess that the $form_state should be used to check the submit value.

Something like:

---------------------------------------------------------------------------------------
Parameters to form_type_HOOK_field_value() have changed

Value callback functions, as defined by an FAPI element #value_callback property or the elements type_HOOK_field_value() callback, now get passed the $form_state as the third parameter.

Drupal 6.x:

<?php
function form_type_example_field_value($element, $edit = FALSE) {
  if ($edit === FALSE) {
     // The form has not been submitted, set the default value here.
  }
  return $edit;
}
?>

Drupal 7.x:

function form_type_example_field_value($element, $edit, $form_state) {
  // ??? I haven't programmed much in Drupal 7 yet, so not sure on the best practice here.
  if (empty($form_state['submitted'])) {
     // The form has not been submitted, set the default value here.
  }
  return $edit;
}

---------------------------------------------------------------------------------------

And I see that the signature for _form_builder_handle_input_element() has changed.

function _form_builder_handle_input_element($form_id, &$element, &$form_state) {
.....

Which means (??) that we can update the $form_state from the value callback too! Very cool! I guess that had something to do with File & Image in core?

Looks like we are asking for something to be added to the 6/7 module update guide? Changing tag accordingly. If you want some other documentation to be done, please comment and add back the other tag again.

I added a section to the module update guide about this. I didn't think an example was all that necessary, and there's a link to this issue in it.
http://drupal.org/update/modules/6/7#value-callback-state