A cosa serve $ form_state?

A cosa serve in $form_stategenere nel contesto dell'API Form se viene utilizzato come argomento?

In particolare, sto cercando un esempio di quando viene utilizzato.

$form_stateè uno degli argomenti passati a un gestore di invio modulo o a un gestore di convalida modulo; il suo utilizzo principale è quello di recuperare i valori inseriti dall'utente nel modulo vedere il contenuto di $form_state['values']), ma contiene altri valori che possono essere utilizzati per altri scopi.
La documentazione per drupal_build_form () contiene l'elenco di altri valori contenuti in quell'array, che include i seguenti:

• ricostruisci: normalmente, dopo che è stata completata l'intera elaborazione del modulo e sono stati eseguiti i gestori di invio, un modulo viene considerato eseguito e drupal_redirect_form () reindirizzerà l'utente a una nuova pagina utilizzando una richiesta GET (quindi un aggiornamento del browser non reinvia il modulo). Tuttavia, se 'ricostruisci' è stato impostato su TRUE, una nuova copia del modulo viene immediatamente creata e inviata al browser, anziché un reindirizzamento. Questo è usato per moduli multi-step, come procedure guidate e moduli di conferma. Normalmente, $form_state['rebuild']è impostato da un gestore di invio, poiché di solito è una logica all'interno di un gestore di invio che determina se un modulo viene eseguito o richiede un altro passaggio. Tuttavia, un gestore di convalida potrebbe già impostare $form_state['rebuild']in modo che l'elaborazione del modulo ignori i gestori di invio e ricostruisca il modulo, anche se non sono presenti errori di convalida.
• reindirizzamento: utilizzato per reindirizzare il modulo al momento dell'invio. Può essere una stringa contenente l'URL di destinazione o una matrice di argomenti compatibili con drupal_goto(). Vedere drupal_redirect_form()per informazioni complete.
• cache: se impostato sulla TRUEstruttura del modulo originale, verrà non memorizzato nella cache, il che consente di ricostruire l'intero modulo dalla cache. Un tipico flusso di lavoro del modulo comporta due richieste di pagina; in primo luogo, un modulo viene creato e reso per essere compilato dall'utente. Quindi, l'utente compila il modulo e lo invia, attivando una seconda richiesta di pagina in cui il modulo deve essere compilato ed elaborato. Per impostazione predefinita, $forme $form_statesono creati da zero durante ciascuna di queste richieste di pagina. Spesso, è necessario o desiderato mantenere le variabili $forme $form_statedalla richiesta della pagina iniziale a quella che elabora l'invio. 'cache' può essere impostato su TRUE per farlo. Un esempio importante è un modulo abilitato Ajax, in cuiajax_process_form()abilita la memorizzazione nella cache dei moduli per tutti i moduli che includono un elemento con la proprietà #ajax. (Il gestore Ajax non ha modo di compilare il modulo stesso, quindi deve fare affidamento sulla versione memorizzata nella cache.) Si noti che la persistenza $forme si $form_stateverifica automaticamente per i moduli (in più passaggi) con il flag "ricostruisci" impostato, indipendentemente dal valore per 'cache'.
• archiviazione: $form_state['storage']non è una chiave speciale e non viene fornito alcun supporto specifico nell'API del modulo. Per tradizione, era la posizione in cui venivano archiviati i dati specifici dell'applicazione per la comunicazione tra le funzioni di invio, convalida e generatore di moduli, in particolare in una forma in più fasi. Le implementazioni del modulo possono utilizzare qualsiasi chiave (o $form_statele chiavi elencate qui e altre riservate utilizzate dagli interni dell'API Form) per questo tipo di archiviazione. Il modo consigliato per garantire che la chiave scelta non sia in conflitto con quelli utilizzati dall'API del modulo o da altri moduli è di utilizzare il nome del modulo come nome della chiave o un prefisso per il nome della chiave. Ad esempio, il modulo Nodo utilizza$form_state['node'] nei moduli di modifica dei nodi per memorizzare le informazioni sul nodo in fase di modifica e queste informazioni rimangono disponibili per tutti i clic successivi del pulsante "Anteprima" e quando si fa infine clic sul pulsante "Salva".

Altre funzioni che ottengono $form_statecome argomento sono hook_form_alter () e hook_form_FORM_ID_alter () .

Come esempio di codice che utilizza tale argomento, puoi guardare comment_form_submit () , che contiene il seguente codice:

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

Per capire cosa $form_state['values']contiene, è necessario esaminare i valori aggiunti $formin comment_form () . Ad esempio, $form_statecontiene $form_state['values']['name']perché $formcontiene $form['author']['name']. Generalmente, se $form['field']è un campo modulo, $form_stateconterrà $form_state['values']['field'].