¿Para qué se usa $ form_state?

¿Para qué se $form_stateusa típicamente en el contexto de la API de formulario si se usa como argumento?

Específicamente, estoy buscando un ejemplo de cuándo se usa.

$form_statees uno de los argumentos pasados ​​a un controlador de envío de formularios o un controlador de validación de formularios; su uso principal es recuperar los valores ingresados ​​por el usuario en el formulario (ver el contenido de $form_state['values']), pero contiene otros valores que pueden usarse para otros fines.
La documentación de drupal_build_form () contiene la lista de otros valores contenidos en esa matriz, que incluyen los siguientes:

• reconstruir: normalmente, una vez que se completa el procesamiento del formulario y se han ejecutado los controladores de envío, se considera que se ha completado un formulario y drupal_redirect_form () redirigirá al usuario a una nueva página utilizando una solicitud GET (para que la actualización del navegador no se vuelva a enviar la forma). Sin embargo, si 'reconstruir' se ha establecido en VERDADERO, entonces se genera una nueva copia del formulario y se envía inmediatamente al navegador, en lugar de una redirección. Esto se utiliza para formularios de varios pasos, como asistentes y formularios de confirmación. Normalmente, $form_state['rebuild']lo establece un controlador de envío, ya que generalmente es lógico dentro de un controlador de envío que determina si un formulario está hecho o requiere otro paso. Sin embargo, un controlador de validación ya puede estar configurado $form_state['rebuild']para hacer que el procesamiento del formulario omita los controladores de envío y reconstruya el formulario, incluso si no hay errores de validación.
• redireccionar: Se utiliza para redirigir el formulario al enviarlo. Puede ser una cadena que contiene la URL de destino o una matriz de argumentos compatibles con drupal_goto(). Consulte drupal_redirect_form()para obtener información completa.
• caché: si se establece en TRUEla estructura de formulario original sin procesar, se almacenará en caché, lo que permite que todo el formulario se reconstruya desde la caché. Un flujo de trabajo de formulario típico implica dos solicitudes de página; primero, se crea y se procesa un formulario para que el usuario lo complete. Luego, el usuario llena el formulario y lo envía, desencadenando una segunda solicitud de página en la que el formulario debe ser construido y procesado. Por defecto, $formy $form_statese crean desde cero durante cada una de estas solicitudes de página. A menudo, es necesario o deseado persistir las variables $formy $form_statedesde la solicitud de la página inicial hasta la que procesa el envío. 'caché' se puede establecer en VERDADERO para hacer esto. Un ejemplo destacado es un formulario habilitado para Ajax, en el queajax_process_form()habilita el almacenamiento en caché de formularios para todos los formularios que incluyen un elemento con la propiedad #ajax. (El controlador Ajax no tiene forma de construir el formulario en sí mismo, por lo que debe confiar en la versión en caché). Tenga en cuenta que la persistencia de los formularios (de varios pasos) $formy $form_statesuceden automáticamente con el indicador 'reconstruir', independientemente del valor para 'cache'.
• almacenamiento: $form_state['storage']no es una clave especial, y no se proporciona soporte específico para ello en el formulario API. Por tradición, era el lugar donde se almacenaban los datos específicos de la aplicación para la comunicación entre las funciones de envío, validación y generador de formularios, especialmente en un formulario de varios pasos. Las implementaciones de formularios pueden usar cualquier clave ( $form_stateaparte de las claves enumeradas aquí y otras reservadas utilizadas por los internos de API de formulario) para este tipo de almacenamiento. La forma recomendada de garantizar que la clave elegida no entre en conflicto con las utilizadas por la API de formulario u otros módulos es utilizar el nombre del módulo como el nombre de la clave o un prefijo para el nombre de la clave. Por ejemplo, el módulo Node usa$form_state['node'] en formularios de edición de nodos para almacenar información sobre el nodo que se está editando, y esta información permanece disponible en los clics sucesivos del botón "Vista previa", así como cuando finalmente se hace clic en el botón "Guardar".

Otras funciones que se obtienen $form_statecomo argumento son hook_form_alter () y hook_form_FORM_ID_alter () .

Como ejemplo de código que usa ese argumento, puede mirar comment_form_submit () , que contiene el siguiente 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 comprender lo que $form_state['values']contiene, debe mirar los valores agregados $formen comment_form () . Por ejemplo, $form_statecontiene $form_state['values']['name']porque $formcontiene $form['author']['name']. Generalmente, si $form['field']es un campo de formulario, entonces $form_statecontendrá $form_state['values']['field'].