Um formulário virtual é uma técnica que você pode usar para limitar os campos de entrada processados quando uma página da Web é enviada. Por exemplo, talvez você tenha dois componentes de entrada, como um campo de texto e uma lista suspensa, que deseja processar quando o usuário clica em um determinado botão. Entretanto, você não deseja que nada mais seja processado quando o botão é clicado. Para obter esse comportamento, você pode criar um formulário virtual e associar o campo de texto, a lista suspensa e o botão a ele.
Um formulário virtual define um grupo de entrada e componentes de envio em uma página. Componentes de entrada, tais como campos de texto, áreas de texto, listas suspensas, caixas de verificação, caixas de listagem e botões de opção, participam no formulário virtual. Os componentes de envio, tais como botões e hyperlinks, enviam o formulário virtual. Muitos componentes de entrada podem participar e enviar o formulário virtual, como descrito abaixo em "Formulários virtuais e Enviar automaticamente ao alterar".
Quando um usuário do site da Web envia um formulário virtual, somente os participantes do formulário virtual são processados. Os componentes de entrada restantes na página são ignorados, como se os componentes do formulário virtual estivesse em sua própria página.
Você pode adicionar um componente a um formulário virtual, clicando com o botão direito do mouse no componente e escolhendo Configurar formulários virtuais. Quando a caixa de diálogo se abre, você vê uma linha para cada formulário virtual ao qual pode adicionar o componente. Cada linha possui a cor, o nome e uma célula Participar e Enviar do formulário virtual. Se o componente puder participar do formulário, clicar nessa célula mostra uma lista suspensa que permite que você altere a configuração para sim. O mesmo acontece com a célula Enviar. Se o componente não puder enviar ou participar, nada acontece quando você clica na célula.
Embora os componentes botão e hyperlink sejam os componentes de envio mais comuns, um componente de entrada como uma lista suspensa também pode ser um componente de envio. Uma lista suspensa pode participar e enviar um formulário virtual. Configure o comportamento do formulário virtual do componente na caixa de diálogo Formulários virtuais. Entretanto, para fazer com que a lista suspensa realmente envie a página da Web, também é necessário clicar com o botão direito do mouse no componente e ativar o recurso Enviar automaticamente ao alterar.
Como parte do comportamento padrão da implementação dos formulários virtuais, sempre que o usuário envia um formulário virtual que faz com que a mesma página seja reexibida, quaisquer campos de entrada que não participam desse formulário virtual retêm e exibem seus valores enviados em vez de seus valores. Os valores enviados são as entradas desconvertidas e não-validadas que estão nos campos de entrada quando o usuário envia a página da Web. Os valores são os valores atuais reais dos componentes. Este comportamento padrão dos formulários virtuais evita a perda desnecessária de quaisquer entradas do usuário não-participantes (e, portanto, não-processadas) quando a página é reexibida.
Entretanto, há circunstâncias em que você deve sobrescrever o comportamento padrão e descartar explicitamente os valores enviados dos campos de entrada não-participantes e, em vez disso, exibir seus valores. Um exemplo é um cenário mestre/detalhe onde o detalhe contém campos editáveis. Quando o usuário seleciona um novo mestre, que por sua vez preenche novamente o provedor de dados do detalhe com novos dados, é essencial que os campos de entrada do detalhe mostrem seus valores, para o novo mestre, em vez de seus valores enviados, os dados do mestre antigo.
O componente Formulário oferece os seguintes métodos que descartam os valores enviados de campos de entrada não-participantes:
public void discardSubmittedValues(String virtualFormName)
public void discardSubmittedValue(EditableValueHolder inputField)
IllegalArgumentException se o formulário virtual especificado tiver sido enviado durante a solicitação atual.EditableValueHolder. O campo de entrada especificado descarta seus valores enviados. O campo de entrada especificado deve ser não-participante. Este método lança um IllegalArgumentException se um formulário virtual tiver sido enviado e o campo de entrada especificado participa dele.immediate.
immediate pode definir somente um grupo, mas uma página pode usar tantos formulários virtuais quanto necessários. immediate requer que você compreenda o ciclo de vida do JavaServer Faces, enquanto os formulários virtuais não afetam esse ciclo de vida e, portanto, são mais fáceis de usar.