Untuk apa $ form_state digunakan?

Apa yang $form_statebiasanya digunakan dalam konteks API Formulir jika digunakan sebagai argumen?

Secara khusus, saya mencari contoh kapan digunakan.

$form_stateadalah salah satu argumen yang diteruskan ke penangan pengajuan formulir, atau penangan validasi formulir; penggunaan utamanya adalah untuk mengambil nilai yang dimasukkan dari pengguna dalam bentuk melihat konten $form_state['values']), tetapi mengandung nilai-nilai lain yang dapat digunakan untuk tujuan lain.
Dokumentasi untuk drupal_build_form () berisi daftar nilai-nilai lain yang terkandung dalam array itu, yang meliputi yang berikut:

• membangun kembali: Biasanya, setelah seluruh pemrosesan formulir selesai dan mengirimkan penangan telah berjalan, formulir dianggap selesai dan drupal_redirect_form () akan mengarahkan pengguna ke halaman baru menggunakan permintaan GET (sehingga pembaruan browser tidak mengirim ulang formulir). Namun, jika 'membangun kembali' telah disetel ke TRUE, maka salinan baru formulir segera dibuat dan dikirim ke browser, alih-alih redirect. Ini digunakan untuk formulir multi-langkah, seperti penyihir dan formulir konfirmasi. Biasanya, $form_state['rebuild']diatur oleh pengatur pengiriman, karena biasanya logika di dalam pengatur pengiriman yang menentukan apakah suatu formulir dilakukan atau memerlukan langkah lain. Namun, penangan validasi mungkin sudah diatur $form_state['rebuild']untuk menyebabkan pemrosesan formulir memotong pengiriman penangan dan membangun kembali formulir sebagai gantinya, bahkan jika tidak ada kesalahan validasi.
• redirect: Digunakan untuk mengarahkan ulang formulir saat pengiriman. Ini bisa berupa string yang berisi URL tujuan, atau array argumen yang kompatibel dengan drupal_goto(). Lihat drupal_redirect_form()untuk informasi lengkap.
• cache: Jika diatur ke TRUEaslinya, struktur formulir yang tidak diproses akan di-cache, yang memungkinkan seluruh formulir dibangun kembali dari cache. Alur kerja formulir tipikal melibatkan dua permintaan halaman; pertama, formulir dibuat dan diberikan untuk diisi oleh pengguna. Kemudian, pengguna mengisi formulir dan mengirimkannya, memicu permintaan halaman kedua di mana formulir harus dibangun dan diproses. Secara default, $formdan $form_statedibangun dari awal selama setiap permintaan halaman ini. Seringkali, perlu atau diinginkan untuk bertahan $formdan $form_statevariabel dari permintaan halaman awal ke yang memproses pengajuan. 'cache' dapat disetel ke TRUE untuk melakukan ini. Contoh yang menonjol adalah formulir yang diaktifkan Ajax, di manaajax_process_form()memungkinkan caching formulir untuk semua formulir yang menyertakan elemen dengan properti #ajax. (The Ajax handler tidak memiliki cara untuk membangun bentuk itu sendiri, sehingga harus bergantung pada versi cache.) Perhatikan bahwa kegigihan $formdan $form_stateterjadi secara otomatis untuk (multi-langkah) bentuk memiliki 'membangun kembali' flag set, terlepas dari nilai untuk 'cache'.
• penyimpanan: $form_state['storage']bukan kunci khusus, dan tidak ada dukungan khusus disediakan untuk itu di Formulir API. Secara tradisional itu adalah lokasi di mana data spesifik aplikasi disimpan untuk komunikasi antara fungsi kirim, validasi, dan pembuat formulir, terutama dalam bentuk gaya multi-langkah. Implementasi formulir dapat menggunakan kunci apa saja di dalam $form_state(selain kunci yang tercantum di sini dan yang lain yang dicadangkan yang digunakan oleh internal API Formulir) untuk jenis penyimpanan ini. Cara yang disarankan untuk memastikan bahwa kunci yang dipilih tidak bertentangan dengan yang digunakan oleh API Formulir atau modul lain adalah dengan menggunakan nama modul sebagai nama kunci atau awalan untuk nama kunci. Sebagai contoh, modul Node menggunakan$form_state['node'] dalam bentuk pengeditan simpul untuk menyimpan informasi tentang simpul yang sedang diedit, dan informasi ini tetap tersedia di klik beruntun dari tombol "Pratinjau" serta ketika tombol "Simpan" akhirnya diklik.

Fungsi lain yang $form_statedijadikan argumen adalah hook_form_alter () dan hook_form_FORM_ID_alter () .

Sebagai contoh kode yang menggunakan argumen itu, Anda dapat melihat comment_form_submit () , yang berisi kode berikut:

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

Untuk memahami apa yang $form_state['values']mengandung, Anda perlu melihat nilai yang ditambahkan ke $formdalam comment_form () . Misalnya $form_statemengandung $form_state['values']['name']karena $formmengandung $form['author']['name']. Secara umum, jika $form['field']isian formulir, maka $form_stateakan berisi $form_state['values']['field'].