drupal----confused by the argument $form_state

Question

this is an example form the pro drupal book.

  function annotate_admin_settings() {

    $options = node_get_types('names');
      $form['annotate_node_types'] = array(

   '#type' => 'checkboxes',

    '#title' => t('Users may annotate these content types'),
    '#options' => $options,
    '#default_value' => variable_get('annotate_node_types', array('page')),
     '#description' => t('A text field will be available on these content types to
     make user-specific notes.'),
    );
    return system_settings_form($form);
   }

but form the drupal documentation, the builder of a form's style is like this.

function mymodule_myform($form_state) {

}

there is a parameter($form_state) in the funcion, when i should use this parameter.thank you.

Watery

I don't understand what you mean. It's a parameter, isn't it? How it is named (the difference between $form and $form_state) doesn't matter. – Biestings

Pekka, the $form passed to system_settings_form() is not equivalent to the $form_state variable passed to other form-building functions, e.g. block_add_block_form(). Those variable names are descriptive of the actual difference between a form and a form state in Drupal. While you're right that it's possible to use 2 variable names to refer to the same thing, that's not what's happening here, and that's also a terrible coding practice. – Concenter

Answer 1

thosewhatnots is completely completely correct in their discussion of the difference between $form and $form_state. $form defines the form, $form_state carries information about the processed form.

So why do form building functions take $form_state as their first argument (along with any number of optional, user specified arguments)? To provide context and state information that may be necessary when a form is being built.

Form building functions should always return a form definition, but they may make decisions about the form definition based on information like the last button clicked, user submitted values, or other information. As mentioned by ceejayoz in a comment, a common use of $form_state in a builder function is to handle multi-step forms, where the state of the form ("step 1 + 2 complete, step 3 still to go) has an effect on the form that is displayed to the user.

In many common use cases, $form_state is completely ignored, and optional arguments are used to provide contextual information (for one of many examples, see the comment_form API documentation).

Present

One of the common uses I've seen for $form_state in a form function is for multistep/ahah_helper forms, so they can adapt to a form rebuild. – Schifra

@Schifra -- that's the most common use of $form_state that I've seen in my Drupal wanderings; I'll add it to my answer. – Present

Answer 2

If you're looking for the differences between $form and $form_state:

$form is an associative array containing the structure of the form. It is modified with calls such as hook_form_alter to add fields or do other stuff.

$form_state is a keyed array containing the current state of the form. The exact state depends on what stage in the node process that the form is in. Typically, it holds the values that will be processed upon form submission.

Aegyptus

This is right on, but it is only half the answer if I understood the question correctly, which is why form building functions take $form_state as their first argument. – Present

Answer 3

The primary use of $form_state is to hold the values of a form after it has been filled out and submitted. The $form_state is checked by validation functions to ensure values that were entered meet validation requirements. The same $form_state is then forwarded to submit functions which can do things with that data once validation has passed (e.g. save data to the database, print something to the next page, etc.).

That said, the $form_state parameter can be included in any form function, because a form can be loaded or reloaded at any point in the submission process. If you want access to values stored by your form, make sure $form_state is available to your function.

See Drupal's Form Quickstart for more details, especially the validation and submit sections.

Broida