Для чого використовується $ form_state?

Для чого $form_stateзазвичай використовується контекст API API, якщо він використовується як аргумент?

Зокрема, я шукаю приклад, коли він використовується.

$form_stateє одним з аргументів, переданих оброблювачу форми подання форми, або оброблювача перевірки форми; його основне використання полягає у виведенні значень, введених у користувача у формі див. зміст $form_state['values']), але вона містить інші значення, які можна використовувати для інших цілей.
Документація для drupal_build_form () містить перелік інших значень, що містяться в цьому масиві, включаючи такі:

• відновити: Зазвичай після завершення обробки всієї форми та запуску обробників запуску форма вважається виконаною, а drupal_redirect_form () перенаправить користувача на нову сторінку за допомогою GET-запиту (тому оновлення браузера не повторно подає форма). Однак якщо для "перебудови" було встановлено значення "ІСТИНА", то нова копія форми негайно створюється та надсилається до браузера, а не перенаправлення. Це використовується для багатоступеневих форм, таких як майстри та форми підтвердження. Зазвичай $form_state['rebuild']його встановлює обробник подачі, оскільки зазвичай логіка всередині обробника подачі визначає, чи буде виконана форма чи потрібен інший крок. Однак обробник перевірки вже може встановити так, $form_state['rebuild']щоб обробка форми обходила обробку відправлень та замість неї перебудовувала форму, навіть якщо помилок перевірки немає.
• переадресація: використовується для перенаправлення форми під час подання. Це може бути або рядок, що містить цільову URL-адресу, або масив аргументів, сумісних із drupal_goto(). Дивіться drupal_redirect_form()повну інформацію.
• кеш: Якщо встановлено TRUEпочаткову, не оброблена структура форми буде кешована, що дозволяє перебудувати всю форму з кешу. Типовий робочий процес форми включає два запити на сторінку; спочатку формується і надається форма користувачеві для заповнення. Потім користувач заповнює форму і подає її, запускаючи запит на другу сторінку, в якій форму потрібно збирати та обробляти. За замовчуванням, $formі $form_stateпобудовані з нуля в протягом кожного з цих запитів сторінок. Часто потрібно або бажано зберегти $formі $form_stateзмінні від початкового запиту на сторінку до тієї, що обробляє подання. "кеш" може бути встановлено на TRUE для цього. Видатний приклад - форма з підтримкою Ajax, в якійajax_process_form()дозволяє кешувати форми для всіх форм, що містять елемент із властивістю #ajax. (Обробник Ajax не може створити форму самостійно, тому необхідно покладатися на кешовану версію.) Зауважте, що збереження $formта $form_stateвідбувається автоматично для (багатошагових) форм, що мають набір прапора "перебудувати", незалежно від значення для 'кеш'.
• зберігання: $form_state['storage']не є спеціальним ключем, і конкретна підтримка для нього не надається в API форми. За традицією, це місце, де зберігаються дані, що стосуються додатків, для зв'язку між функціями для подання, перевірки та побудови форми, особливо у багатошаговій формі. Реалізація форми може використовувати будь-які ключі в межах $form_state(крім перерахованих тут ключів та інших зарезервованих, які використовуються внутрішніми API формами) для цього типу зберігання. Рекомендований спосіб переконатися, що вибраний ключ не суперечить тим, які використовуються API форми або інших модулів, - використовувати ім'я модуля як ім'я ключа або префікса для імені ключа. Наприклад, модуль Node використовує$form_state['node'] у формах редагування вузлів, щоб зберігати інформацію про вузол, який редагується, і ця інформація залишається доступною для послідовних клацань кнопки «Попередній перегляд», а також коли нарешті натискається кнопка «Зберегти».

Іншими функціями, які стають $form_stateяк аргумент, є прив'язка_форма_алтер () та гачка_форма_FORM_ID_alter () .

Як приклад коду, який використовує цей аргумент, ви можете подивитися comment_form_submit () , який містить такий код:

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

Щоб зрозуміти , що $form_state['values']містить, ви повинні дивитися на значенні додано $formв comment_form () . Наприклад, $form_stateмістить, $form_state['values']['name']тому що $formмістить $form['author']['name']. Як правило, якщо $form['field']це поле форми, то воно $form_stateбуде містити $form_state['values']['field'].