Respostas:
$form_state
é um dos argumentos passados para um manipulador de envio de formulários ou manipulador de validação de formulário; seu principal uso é recuperar os valores inseridos do usuário no formulário, ver o conteúdo de $form_state['values']
), mas contém outros valores que podem ser usados para outros fins.
A documentação para drupal_build_form () contém a lista de outros valores contidos nessa matriz, que incluem os seguintes:
- reconstruir: normalmente, depois que todo o processamento do formulário é concluído e os manipuladores de envio são executados, um formulário é considerado concluído e drupal_redirect_form () redireciona o usuário para uma nova página usando uma solicitação GET (para que uma atualização do navegador não reenvie a forma). No entanto, se 'reconstruir' tiver sido definido como TRUE, uma nova cópia do formulário será criada imediatamente e enviada ao navegador, em vez de um redirecionamento. Isso é usado para formulários de várias etapas, como assistentes e formulários de confirmação. Normalmente,
$form_state['rebuild']
é definido por um manipulador de envio, pois geralmente é lógico dentro de um manipulador de envio que determina se um formulário é feito ou requer outra etapa. No entanto, um manipulador de validação já pode estar configurado$form_state['rebuild']
para fazer com que o processamento do formulário ignore os manipuladores de envio e reconstrua o formulário, mesmo se não houver erros de validação.- redirecionar: usado para redirecionar o formulário no envio. Pode ser uma sequência contendo o URL de destino ou uma matriz de argumentos compatíveis
drupal_goto()
. Vejadrupal_redirect_form()
para informações completas.- cache: se definido como
TRUE
original, a estrutura do formulário não processado será armazenada em cache, o que permite que todo o formulário seja reconstruído do cache. Um fluxo de trabalho de formulário típico envolve duas solicitações de página; primeiro, um formulário é criado e renderizado para o usuário preencher. Em seguida, o usuário preenche o formulário e o envia, acionando uma solicitação de segunda página na qual o formulário deve ser construído e processado. Por padrão,$form
e$form_state
são criados do zero durante cada uma dessas solicitações de página. Freqüentemente, é necessário ou desejado persistir as variáveis$form
e$form_state
desde a solicitação da página inicial até a que processa o envio. 'cache' pode ser definido como TRUE para fazer isso. Um exemplo de destaque é um formulário habilitado para Ajax, no qualajax_process_form()
permite o cache de formulários para todos os formulários que incluem um elemento com a propriedade #ajax. (O manipulador Ajax não tem como criar o próprio formulário, portanto, deve confiar na versão em cache.) Observe que a persistência$form
e$form_state
ocorre automaticamente para formulários (de várias etapas) com o sinalizador 'reconstruir' definido, independentemente do valor para 'cache'.- storage:
$form_state['storage']
não é uma chave especial e nenhum suporte específico é fornecido na API do formulário. Por tradição, era o local onde os dados específicos do aplicativo eram armazenados para comunicação entre as funções de envio, validação e construtor de formulários, especialmente em um formato de várias etapas. As implementações de formulário podem usar quaisquer chaves dentro$form_state
(além das chaves listadas aqui e outras reservadas usadas pelos internos da API de formulário) para esse tipo de armazenamento. A maneira recomendada de garantir que a chave escolhida não entre em conflito com a usada pela API do formulário ou por outros módulos é usar o nome do módulo como o nome da chave ou um prefixo para o nome da chave. Por exemplo, o módulo Nó usa$form_state['node']
nos formulários de edição de nós para armazenar informações sobre o nó que está sendo editado, e essas informações permanecem disponíveis por cliques sucessivos no botão "Visualizar", bem como quando o botão "Salvar" é finalmente clicado.
Outras funções que obtêm $form_state
como argumento são hook_form_alter () e hook_form_FORM_ID_alter () .
Como exemplo de código que usa esse argumento, você pode ver comment_form_submit () , que contém o seguinte código:
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();
}
Para entender o que $form_state['values']
contém, você precisa examinar os valores adicionados $form
em comment_form () . Por exemplo, $form_state
contém $form_state['values']['name']
porque $form
contém $form['author']['name']
. Geralmente, se $form['field']
for um campo de formulário, ele $form_state
conterá $form_state['values']['field']
.
$form
matriz; é o construtor de formulários que verifica o conteúdo de $form_state
. Foi o que vi em todos os retornos de chamada AJAX implementados por módulos que fazem a coisa certa.