Para que é usado o $ form_state?

Para que $form_statenormalmente é usado no contexto da API do formulário, se usado como argumento?

Especificamente, estou procurando um exemplo de quando é usado.

$form_stateé um dos argumentos passados ​​para um manipulador de envio de formulários ou manipulador de validação de formulário; seu principal uso é recuperar os valores inseridos do usuário no formulário, ver o conteúdo de $form_state['values']), mas contém outros valores que podem ser usados ​​para outros fins.
A documentação para drupal_build_form () contém a lista de outros valores contidos nessa matriz, que incluem os seguintes:

• reconstruir: normalmente, depois que todo o processamento do formulário é concluído e os manipuladores de envio são executados, um formulário é considerado concluído e drupal_redirect_form () redireciona o usuário para uma nova página usando uma solicitação GET (para que uma atualização do navegador não reenvie a forma). No entanto, se 'reconstruir' tiver sido definido como TRUE, uma nova cópia do formulário será criada imediatamente e enviada ao navegador, em vez de um redirecionamento. Isso é usado para formulários de várias etapas, como assistentes e formulários de confirmação. Normalmente, $form_state['rebuild']é definido por um manipulador de envio, pois geralmente é lógico dentro de um manipulador de envio que determina se um formulário é feito ou requer outra etapa. No entanto, um manipulador de validação já pode estar configurado $form_state['rebuild']para fazer com que o processamento do formulário ignore os manipuladores de envio e reconstrua o formulário, mesmo se não houver erros de validação.
• redirecionar: usado para redirecionar o formulário no envio. Pode ser uma sequência contendo o URL de destino ou uma matriz de argumentos compatíveis drupal_goto(). Veja drupal_redirect_form()para informações completas.
• cache: se definido como TRUEoriginal, a estrutura do formulário não processado será armazenada em cache, o que permite que todo o formulário seja reconstruído do cache. Um fluxo de trabalho de formulário típico envolve duas solicitações de página; primeiro, um formulário é criado e renderizado para o usuário preencher. Em seguida, o usuário preenche o formulário e o envia, acionando uma solicitação de segunda página na qual o formulário deve ser construído e processado. Por padrão, $forme $form_statesão criados do zero durante cada uma dessas solicitações de página. Freqüentemente, é necessário ou desejado persistir as variáveis $forme $form_statedesde a solicitação da página inicial até a que processa o envio. 'cache' pode ser definido como TRUE para fazer isso. Um exemplo de destaque é um formulário habilitado para Ajax, no qualajax_process_form()permite o cache de formulários para todos os formulários que incluem um elemento com a propriedade #ajax. (O manipulador Ajax não tem como criar o próprio formulário, portanto, deve confiar na versão em cache.) Observe que a persistência $forme $form_stateocorre automaticamente para formulários (de várias etapas) com o sinalizador 'reconstruir' definido, independentemente do valor para 'cache'.
• storage: $form_state['storage']não é uma chave especial e nenhum suporte específico é fornecido na API do formulário. Por tradição, era o local onde os dados específicos do aplicativo eram armazenados para comunicação entre as funções de envio, validação e construtor de formulários, especialmente em um formato de várias etapas. As implementações de formulário podem usar quaisquer chaves dentro $form_state(além das chaves listadas aqui e outras reservadas usadas pelos internos da API de formulário) para esse tipo de armazenamento. A maneira recomendada de garantir que a chave escolhida não entre em conflito com a usada pela API do formulário ou por outros módulos é usar o nome do módulo como o nome da chave ou um prefixo para o nome da chave. Por exemplo, o módulo Nó usa$form_state['node'] nos formulários de edição de nós para armazenar informações sobre o nó que está sendo editado, e essas informações permanecem disponíveis por cliques sucessivos no botão "Visualizar", bem como quando o botão "Salvar" é finalmente clicado.

Outras funções que obtêm $form_statecomo argumento são hook_form_alter () e hook_form_FORM_ID_alter () .

Como exemplo de código que usa esse argumento, você pode ver comment_form_submit () , que contém o seguinte código:

function comment_form_submit($form, &$form_state) {
  $node = node_load($form_state['values']['nid']);
  $comment = comment_form_submit_build_comment($form, $form_state);
  if (user_access('post comments') && (user_access('administer comments') || $node->comment == COMMENT_NODE_OPEN)) {
    // Save the anonymous user information to a cookie for reuse.
    if (user_is_anonymous()) {
      user_cookie_save(array_intersect_key($form_state['values'], array_flip(array('name', 'mail', 'homepage'))));
    }

    comment_save($comment);
    $form_state['values']['cid'] = $comment->cid;

    // Add an entry to the watchdog log.
    watchdog('content', 'Comment posted: %subject.', array('%subject' => $comment->subject), WATCHDOG_NOTICE, l(t('view'), 'comment/' . $comment->cid, array('fragment' => 'comment-' . $comment->cid)));

    // Explain the approval queue if necessary.
    if ($comment->status == COMMENT_NOT_PUBLISHED) {
      if (!user_access('administer comments')) {
        drupal_set_message(t('Your comment has been queued for review by site administrators and will be published after approval.'));
      }
    }
    else {
      drupal_set_message(t('Your comment has been posted.'));
    }
    $query = array();
    // Find the current display page for this comment.
    $page = comment_get_display_page($comment->cid, $node->type);
    if ($page > 0) {
      $query['page'] = $page;
    }
    // Redirect to the newly posted comment.
    $redirect = array('node/' . $node->nid, array(
        'query' => $query,
        'fragment' => 'comment-' . $comment->cid,
      ));
  }
  else {
    watchdog('content', 'Comment: unauthorized comment submitted or comment submitted to a closed post %subject.', array('%subject' => $comment->subject), WATCHDOG_WARNING);
    drupal_set_message(t('Comment: unauthorized comment submitted or comment submitted to a closed post %subject.', array('%subject' => $comment->subject)), 'error');
    // Redirect the user to the node they are commenting on.
    $redirect = 'node/' . $node->nid;
  }
  $form_state['redirect'] = $redirect;
  // Clear the block and page caches so that anonymous users see the comment
  // they have posted.
  cache_clear_all();
}

Para entender o que $form_state['values']contém, você precisa examinar os valores adicionados $formem comment_form () . Por exemplo, $form_statecontém $form_state['values']['name']porque $formcontém $form['author']['name']. Geralmente, se $form['field']for um campo de formulário, ele $form_stateconterá $form_state['values']['field'].