FAPI/CCK Confusion: 'value' vs '#value' and form alter

<?phpfunction my_form_alter(&$form, $form_state, $form_id) {
  if (isset($form['type']) && isset($form['#node']) && $form['type']['#value'] .'_node_form' == $form_id) {
    $form['#after_build'][] = 'my_form_process';
  }
}
function my_form_process($form, &$form_state) {
  my_fix_disabled($form['field_myfiled']);
  return $form;
}
function my_fix_disabled(&$elements) {
  foreach (element_children($elements) as $key) {
    if (isset($elements[$key]) && $elements[$key]) {
      // Recurse through all children elements.
      my_fix_disabled($elements[$key]);
    }
  }
  if (!isset($elements['#attributes'])) {
    $elements['#attributes'] = array();
  }
  $elements['#attributes']['disabled'] = 'disabled';
}?>

When after_build handler is invoked, the code in FAPI that deals with $elements['#disabled'] has already been processed (_form_builder_handle_input_element executes() is executed before #after_build handlers are processed, see form_builder() ), so now you need to generate the $element['#attributes']['disabled'] = 'disabled' for the corresponding theme function of the element.


The short take-away is that CCK uses lots of advanced Form API (FAPI) voodoo to build out the details of its fields during the #process part of FAPI processing. If you want to see what CCK has added to the node form and alter it, you will need to jump in using the #after_build step, which will bring you into the form after #process has finished.
But #after_build contains a additional information you won't see in hook_form_alter(). The form looks different at that point because it has now been processed. You will see some parts that look the same as you would expect to see in a hook_form_alter():

<?php...$form['field_text'][0] = array(
  'value' => array(
    '#type' => 'textfield',
    '#default_value' => 'President',
    '#title' => 'My Title',
  ),
);$form['field_number'][0] = array(
  'value' => array(
    '#type' => 'textfield',
    '#default_value' => 30,
    '#title' => 'Years of service',
  ),
);
....?>

The 'value' item here is the name of the field itself. Many CCK fields store something in a column called 'value': text fields, number fields, email fields, etc. Other CCK fields use different column names, nodereference fields store their values in a column called 'nid' and userreference fields store values in a column called 'uid'. As used in the snippet above, 'value' is the name of the column that a CCK textfield is stored in.
If you were processing a form that looks like this in hook_form_alter(), before #process has been invoked, you would set a value for the field in the item called '#default_value'. In this example we have a field that was set to have a default value of 'President'.
But during the #process stage of FAPI processing a final value for the field will be set, and it will be transferred to an array called '#value'. So the form has picked up additional information by the time we get to #after_build:

<?php...$form['#value']['field_text'][0]['value'] = 'President';$form['#value']['field_number'][0]['value'] = 30;
    ?>

In other words, FAPI has added an array called '#value' that contains the resolved values for each item. The important thing to note is that if you want to alter the final value for these fields at this point, making changes to '#default_value' will have no effect at all, the values have already been transferred to the #value array, which is what FAPI considers the final value of these elements. To change these values in #after_build, you need to do something like this:

<?php
$form['#value']['field_text'][0]['value'] = 'Secretary';$form['#value']['field_number'][0]['value'] = 15;?>

That will set the right values in the form state for FAPI. But even with that the values that appear in the form that the user sees may still look wrong. Depending on the specific field you are trying alter, you also may need to do the following to make the form look right:

<?php
$form['field_text'][0]['value']['#value'] = 'Secretary';$form['field_number'][0]['value']['#value'] = 15;?>

Confusing? You bet!
As if that wasn't confusing enough, there is one more FAPI 'value/#value' confusion, one that has nothing to do with CCK. FAPI provides a field type called 'value', and its value is set by '#value'. This is an alternative to a element type of 'textfield' or 'select' or 'hidden', it's an element that contains a value that the end user will not see and cannot alter. It's a very handy alternative to a hidden field that can contain anything, even an object or an array (hidden fields can only contain strings). It looks like this:

<?php
$form['secret_unchangeable_value'] = array(
  '#type' => 'value',
  '#value' => 'Hidden value that no one can see.',
);
  ?>

If you happened to have something like this in your CCK form, along with all the other 'value's and '#value's.... well, you get the idea.
It would be nice if 'value' didn't have all these different meanings to CCK and FAPI. But CCK and FAPI emerged at about the same time and it just happened that both of them used that term for their own purposes.