A quoi sert $ form_state?

À quoi sert $form_stategénéralement dans le contexte de l'API formulaire si elle est utilisée comme argument?

Plus précisément, je cherche un exemple de quand il est utilisé.

$form_stateest l'un des arguments transmis à un gestionnaire de soumission de formulaire ou à un gestionnaire de validation de formulaire; son utilisation principale est de récupérer les valeurs saisies par l'utilisateur dans le formulaire voir le contenu de $form_state['values']), mais il contient d'autres valeurs pouvant être utilisées à d'autres fins.
La documentation de drupal_build_form () contient la liste des autres valeurs contenues dans ce tableau, qui incluent les suivantes:

• rebuild: Normalement, une fois le traitement complet du formulaire terminé et les gestionnaires d'envoi soumis, un formulaire est considéré comme terminé et drupal_redirect_form () redirige l'utilisateur vers une nouvelle page à l'aide d'une demande GET (de sorte qu'une actualisation du navigateur ne soit pas soumise à nouveau). la forme). Cependant, si 'reconstruire' a été défini sur VRAI, une nouvelle copie du formulaire est immédiatement créée et envoyée au navigateur, au lieu d'une redirection. Ceci est utilisé pour les formulaires en plusieurs étapes, tels que les assistants et les formulaires de confirmation. Normalement, il $form_state['rebuild']est défini par un gestionnaire d'envoi, car c'est généralement la logique au sein d'un gestionnaire d'envoi qui détermine si un formulaire est terminé ou nécessite une autre étape. Cependant, un gestionnaire de validation peut déjà être configuré $form_state['rebuild']pour faire en sorte que le traitement du formulaire ignore les gestionnaires d'envoi et reconstruise le formulaire, même en l'absence d'erreur de validation.
• redirection: Utilisé pour rediriger le formulaire lors de la soumission. Il peut s'agir d'une chaîne contenant l'URL de destination ou d'un tableau d'arguments compatibles drupal_goto(). Voir drupal_redirect_form()pour des informations complètes.
• cache: Si défini sur TRUEla structure d'origine, la structure de formulaire non traitée sera mise en cache, ce qui permet de reconstruire l'intégralité du formulaire à partir du cache. Un flux de travail de formulaire typique implique deux demandes de page; tout d'abord, un formulaire est créé et rendu pour que l'utilisateur le remplisse. Ensuite, l'utilisateur remplit le formulaire et le soumet, ce qui déclenche une deuxième demande de page dans laquelle le formulaire doit être construit et traité. Par défaut, $formet $form_statesont construits à partir de zéro au cours de chacune de ces demandes de page. Il est souvent nécessaire ou souhaitable de conserver les variables $formet $form_statedepuis la demande de page initiale jusqu'à celle qui traite la soumission. 'cache' peut être réglé sur TRUE pour cela. Un exemple notable est un formulaire activé par Ajax, dans lequelajax_process_form()active la mise en cache des formulaires pour tous les formulaires qui incluent un élément avec la propriété #ajax. (Le gestionnaire Ajax n'a aucun moyen de créer le formulaire lui-même, il doit donc s'appuyer sur la version mise en cache.) Notez que la persistance $formet $form_statese produit automatiquement pour les formulaires (à étapes multiples ) pour lesquels l' indicateur de reconstruction est défini, quelle que soit la valeur de 'cache'.
• storage: $form_state['storage']n'est pas une clé spéciale et aucun support spécifique n'est fourni dans l'API de formulaire. Selon la tradition, c’était l’emplacement où les données spécifiques à l’application étaient stockées pour la communication entre les fonctions de soumission, de validation et de création de formulaires, en particulier dans un formulaire de style multi-étapes. Les implémentations de formulaire peuvent utiliser n'importe quelle clé ( $form_stateautre que celles répertoriées ici et celles réservées utilisées par les internes de l'API de formulaire) pour ce type de stockage. Pour éviter que la clé choisie n'entre en conflit avec celles utilisées par l'API Form ou d'autres modules, il est recommandé d'utiliser le nom du module en tant que nom de la clé ou un préfixe pour le nom de la clé. Par exemple, le module Node utilise$form_state['node'] dans les formulaires d'édition de nœud pour stocker des informations sur le nœud en cours d'édition, et ces informations restent disponibles lors de clics successifs sur le bouton "Aperçu" ainsi que lorsque le bouton "Enregistrer" est enfin sélectionné.

Hook_form_alter () et hook_form_FORM_ID_alter ()$form_state sont d' autres fonctions .

Comme exemple de code utilisant cet argument, vous pouvez consulter comment_form_submit () , qui contient le code suivant:

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();
}

Pour comprendre ce qui $form_state['values']contient, vous devez regarder les valeurs ajoutées $formdans comment_form () . Par exemple, $form_statecontient $form_state['values']['name']parce que $formcontient $form['author']['name']. Généralement, si $form['field']est un champ de formulaire, alors $form_statecontiendra $form_state['values']['field'].