Do czego służy $ form_state?

Czego $form_statezwykle używa się w kontekście interfejsu API formularza, jeśli jest on używany jako argument?

W szczególności szukam przykładu, kiedy jest używany.

$form_statejest jednym z argumentów przekazanych do procedury obsługi przesyłania formularzy lub procedury sprawdzania poprawności formularza; jego głównym zastosowaniem jest pobieranie wartości wprowadzonych od użytkownika w postaci patrz treść $form_state['values']), ale zawiera inne wartości, które można wykorzystać do innych celów.
Dokumentacja drupal_build_form () zawiera listę innych wartości zawartych w tej tablicy, które obejmują następujące:

• odbuduj: Zwykle po zakończeniu przetwarzania całego formularza i uruchomieniu procedur obsługi przesyłania uznaje się, że formularz został wykonany, a funkcja drupal_redirect_form () przekieruje użytkownika na nową stronę za pomocą żądania GET (więc odświeżanie przeglądarki nie przesyła ponownie formularz). Jeśli jednak „odbuduj” ustawiono na PRAWDA, nowa kopia formularza jest natychmiast budowana i wysyłana do przeglądarki, zamiast przekierowania. Służy to do formularzy wieloetapowych, takich jak kreatory i formularze potwierdzające. Zwykle $form_state['rebuild']jest ustawiany przez moduł obsługi przesyłania, ponieważ zazwyczaj logika w module obsługi przesyłania określa, czy formularz jest wypełniony, czy wymaga kolejnego kroku. Jednak procedura sprawdzania poprawności może już $form_state['rebuild']spowodować, że przetwarzanie formularza będzie pomijać procedury obsługi przesyłania i przebudowywać formularz, nawet jeśli nie wystąpią błędy sprawdzania poprawności.
• przekierowanie: Służy do przekierowywania formularza po przesłaniu. Może to być ciąg znaków zawierający docelowy adres URL lub tablica argumentów zgodnych z drupal_goto(). Zobacz drupal_redirect_form()pełne informacje.
• pamięć podręczna: Jeśli zostanie ustawiona TRUEoryginalna, nieprzetworzona struktura formularza będzie buforowana, co pozwala na przebudowanie całego formularza z pamięci podręcznej. Typowy obieg formularzy obejmuje dwa żądania strony; najpierw formularz jest budowany i renderowany do wypełnienia przez użytkownika. Następnie użytkownik wypełnia formularz i przesyła go, uruchamiając żądanie drugiej strony, w którym formularz musi zostać zbudowany i przetworzony. Domyślnie, $formi $form_statesą zbudowane od podstaw w ciągu każdego z tych żądań stron. Często konieczne lub pożądane jest zachowanie $formi $form_statezmienne od początkowego żądania strony do tego, które przetwarza przesyłanie. „cache” można ustawić na TRUE, aby to zrobić. Wybitnym przykładem jest formularz obsługujący Ajax, w którymajax_process_form()włącza buforowanie formularzy dla wszystkich formularzy zawierających element z właściwością #ajax. (Program obsługi Ajax nie ma możliwości zbudowania samego formularza, więc musi polegać na wersji z pamięci podręcznej.) Należy pamiętać, że trwałość $formi $form_statezdarza się automatycznie dla (wieloetapowych) formularzy z ustawioną flagą „przebuduj”, niezależnie od wartości parametru 'Pamięć podręczna'.
• Storage: $form_state['storage']nie jest specjalnym kluczem i nie jest zapewniona żadna konkretna obsługa w interfejsie API formularza. Tradycyjnie było to miejsce, w którym przechowywane były dane aplikacji do komunikacji między funkcjami przesyłania, sprawdzania poprawności i konstruktora formularzy, szczególnie w formie wieloetapowej. Implementacje formularzy mogą wykorzystywać dowolny klucz ( $form_stateklucze) wymienione w niniejszym dokumencie (inne niż klucze wymienione tutaj i inne zastrzeżone klucze używane przez formularze wewnętrzne interfejsu API) do tego rodzaju przechowywania. Zalecanym sposobem upewnienia się, że wybrany klucz nie powoduje konfliktu z kluczami używanymi przez Form API lub inne moduły, jest użycie nazwy modułu jako nazwy klucza lub prefiksu nazwy klucza. Na przykład wykorzystuje moduł Node$form_state['node'] w formularzach edycji węzła do przechowywania informacji o edytowanym węźle, a informacje te pozostają dostępne po kolejnych kliknięciach przycisku „Podgląd”, a także po ostatecznym kliknięciu przycisku „Zapisz”.

Inne funkcje, które otrzymują $form_statejako argument, to hook_form_alter () i hook_form_FORM_ID_alter () .

Jako przykład kodu używającego tego argumentu możesz przejrzeć komentarz_form_submit () , który zawiera następujący kod:

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

Aby zrozumieć, co $form_state['values']zawiera, musisz spojrzeć na wartości dodane do $formw comment_form () . Na przykład $form_statezawiera, $form_state['values']['name']ponieważ $formzawiera $form['author']['name']. Ogólnie, jeśli $form['field']jest polem formularza, wówczas $form_statebędzie zawierać $form_state['values']['field'].