Como usar formulários visuais

Este artigo descreve como usar formulários virtuais no NetBeans IDE 6.0 ou 6.1.

Conteúdo

• Instalando o exemplo>
• Mostrar botão Formulários virtuais>
• Visão geral de administração de filmes
• Requisitos de processamento seletivos
• Introduzindo formulários visuais
• Retendo e descartando valores enviados
• A propriedade internalVirtualForm
• Caixa de diálogo Formulários virtuais
• Caixa de diálogo Configurar formulários virtuais
• Formulários virtuais e Enviar automaticamente ao alterar
• Formulários virtuais e fragmentos de página>
• Formulários virtuais e o componente Tabela de dados padrão
• Resumo

Para seguir este tutorial, você precisa dos seguintes recursos e softwares.

* Para tirar vantagem dos recursos Java EE 5 do NetBeans IDE , use um servidor da aplicação que seja totalmente compatível com a especificação Java EE 5, tal como o Servidor da aplicação GlassFish V2 UR2. Se você estiver usando um servidor diferente, consulte as Notas de versão e as Perguntas freqüentes para saber problemas conhecidos e soluções alternativas. Para obter informações detalhadas sobre os servidores suportados e a plataforma Java EE, consulte as Notas de versão.

Observação para usuários do NetBeans IDE 6.1:

• Criar um projeto no NetBeans 6.1 inclui novas opções que podem ser deixadas como padrão. Por exemplo, a caixa de verificação Usar pasta dedicada para armazenar bibliotecas pode ficar desmarcada.
• Vinculação sob demanda dos recursos do NetBeans IDE 6.1. Onde os componentes requerem codificação de Java, agora você deve adicionar manualmente o atributo de vinculação aos componentes em uma aplicação Visual Web JSF. Para fazê-lo, clique com o botão direito do mouse em cada componente e escolha Adicionar atributo de vinculação. Para obter mais informações, consulte o On-demand Binding Attribute Wiki.

Instalando o exemplo

Observação: Se você estiver usando o NetBeans 6.0 ou 6.1, então, há aplicações de amostra disponíveis por meio do assistente para Novo projeto. Simplesmente escolha Arquivo > Novo projeto > Amostras > Web > Visual JSF > Administração de filmes e continue com a etapa 3 abaixo.

1. Comece descompactando o conteúdo do arquivo MovieAdmin.zip, que contém duas pastas de projeto: MovieAdmin e MoviesClassLibrary.
2. Inicie o IDE, feche todos os projetos e abra o projeto MoviesClassLibrary.

3. Abra o projeto MovieAdmin.

   Observação: Page 1.jsp exibe um erro porque você precisa resolver uma referência de biblioteca.
4. Na janela Projetos, clique com o botão direito do mouse no nó do projeto MovieAdmin e escolha Propriedades.
5. Na caixa de diálogo Propriedades do projeto, selecione Bibliotecas na árvore Categorias e clique no botão Adicionar projeto.
6. Na caixa de diálogo Adicionar projeto, navegue para a localização do projeto MoviesClassLibrary, selecione MoviesClassLibrary e clique no botão Adicionar arquivos JAR do projeto.
7. Clique em OK.
8. Na janela Projetos, clique com o botão direito do mouse no nó do projeto MoviesClassLibrary e escolha Construir projeto no menu pop-up.
9. Saia do IDE e reabra o IDE para tornar MoviesClassLibrary disponível para o projeto MovieAdmin.

Mostrar botão Formulários virtuais

Depois de instalar o exemplo, clique duas vezes no nó Page1.jsp na janela Projetos e abra o Page1.jsp no Visual Designer. Na barra de ferramentas abaixo da aba, você verá um conjunto de botões, incluindo o botão Mostrar formulários virtuais . Clique no botão para mostrar os formulários virtuais usados na página.

Visão geral de administração de filmes

O exemplo Administração de filmes é um aplicativo administrativo hipotético para uma locadora de filmes. A empresa mantém dados sobre sua coleção de filmes em um armazenamento de dados, e o aplicativo administrativo permite que os funcionários façam alterações nos dados. A empresa também possui um site externo separado que permite aos clientes explorar a coleção. O mesmo armazenamento de dados é usado para o site externo.

Observação: Um aplicativo do mundo real usaria um banco de dados relacional ou outro armazenamento de dados externo. Entretanto, para focalizar os formulários virtuais, o exemplo Administração de filmes simplesmente armazena os dados como objetos na sessão.

A Figura 2 mostra Page1.jsp do aplicativo Administração de filmes em um navegador. O funcionário pode ver os files de um gênero específico, fazendo uma seleção na lista suspensa Gênero atual. Na tabela, o título, ano, duração em minutos, classificação, URL da imagem e campos de descrição podem ser editados; as alterações são salvas quando o funcionário clica no botão Atualizar ou usa os controles de paginação da tabela (quando disponíveis). O funcionário pode remover um filme da coleção, clicando no botão Remover em uma das linhas. Clicar no botão Visualizar em uma das linhas navega para Preview.jsp, o que permite ao funcionário visualizar a página de detalhe de um filme como ela seria vista por um cliente que estivesse navegando no site externo. Um conjunto separado de controles aparece abaixo da tabela para a adição de um filme à coleção.

Diga: Quando executa o exemplo e adiciona filmes à coleção, você pode indicar URLs baseadas em arquivo para arquivos de imagem em sua máquina em vez de caminhos relativos para arquivos de imagem no projeto. Trata-se de um atalho que permite que você adicione esses arquivos de imagem ao projeto.

Além de permitir que o funcionário visualize os detalhes de um filme, a página Visualizar permite que o funcionário revise o gênero do filme que está sendo visualizado.

Requisitos de processamento seletivos

Page1.jsp possui um problema interessante. Quando um novo gênero atual é selecionado, queremos que a entrada da lista suspensa Gênero atual seja processada, mas não as outras entradas na página. Se as outras entradas tiverem sido processadas, quaisquer erros de conversão ou validação nessas entradas fariam com que o envio fosse rejeitado, o que evitaria a alteração do gênero, o que não é o que desejamos. Semelhantemente, quando o botão Atualizar é clicado, queremos que as entradas na tabela sejam processadas, mas não as entradas na seção Adicionar filme. Quaisquer erros de conversão ou de validação nos campos na seção Adicionar filme fariam com que o envio fosse rejeitado, o que evitaria as atualizações nos campos da tabela, o que também não é desejado. Os botões Visualizar, Remover e Adicionar também possuem requisitos de processamento seletivos semelhantes

Dessa forma, processar seletivamente certas entradas quando o usuário interage com certos componentes de envio é um requisito comum e crítico das aplicações Web. Processar uma entrada significa convertê-la e validá-la, acionando quaisquer eventos de alteração de valor associados à entrada, e mapeando a entrada para seu destino de vinculação (se o componente for vinculado). Um componente de entrada é qualquer componente que aceite entrada do usuário, tal como um campo de texto, área de texto, lista suspensa ou botão de opção. (Tecnicamente, os componentes de entrada são aqueles que implementam a interface EditableValueHolder.) Um componente de envio é qualquer componente que faça com que a página da Web seja enviada e, portanto, inicia o processamento de entrada; isso inclui não somente botões e links (que implementam a interface ActionSource), mas também componentes de entrada com o recurso Enviar automaticamente ao alterar ativado. Portanto, é possível para um componente ser de entrada e de envio. A lista suspensa Gênero atual em Page1.jsp do aplicativo Administração de filmes é tal componente.

Os requisitos de processamento seletivo completos para Page1.jsp são os seguintes:

• Lista suspensa Gênero atual. Quando um novo gênero atual é selecionado, o Gênero atual; a lista suspensa deve enviar automaticamente a página da Web e a entrada da lista suspensa deve ser processada exclusivamente, com as outras entradas na página sendo ignoradas.
• Botão Atualizar. Quando o botão Atualizar é clicado, somente os campos na tabela devem ser processados e não os campos na seção Adicionar filme. Quando isso ocorre, a seleção do gênero atual precisa ser processada, já que não foi alterada.
• Botões Visualizar/Remover. Quando um botão Visualizar ou Remover é clicado, nenhuma entrada deve ser processada. Nenhuma entrada precisa ser processada em tal caso porque o componente Tabela e as APIs DataProvider fornecem acesso para a linha em que o botão foi clicado. Quaisquer entradas indicadas nos campos da tabela ou na seção Adicionar filme devem ser ignoradas. Novamente, a seleção de gênero atual não precisa ser processada já que ela não foi alterada
• Botão Adicionar. Quando o botão Adicionar é clicado, somente as entradas na seção Adicionar filme devem ser processadas.

Page1.jsp também possui um requisito de processamento seletivo adicional. Quando a tabela exibe controles de paginação, interagir com elas deve causar o processamento somente das entradas na tabela. Caso contrário, os erros de conversão e validação nos campos fora da tabela causariam a rejeição do envio.

Sem um mecanismo de processamento seletivo suficientemente poderoso, esses requisitos não podem ser atendidos. A propriedade immediate nos componentes JavaServer oferece algum suporte de processamento seletivo, mas não o suficiente para construir uma GUI como essa. O problema é que nessa GUI, existem vários grupos de componentes de entrada que precisam ser processados seletivamente dependendo do componente de envio que o usuário utiliza. Definindo a propriedade immediate em certos componentes em uma GUI, você pode especificar um único grupo de componentes para que seja processado seletivamente, mas não vários grupos.

Introduzindo formulários visuais

Um formulário virtual define um grupo de entrada e componentes de envio em uma página. Os componentes de entrada são participantes no formulário virtual. Os componentes de envio o enviam. Quando um usuário do site interage com um componente que envia um formulário virtual, os participantes do formulário virtual serão processados enquanto as entradas restantes na página são ignoradas.

Observe o seguinte:

• Um formulário virtual pode ter zero ou mais participantes e um ou mais remetentes.
• Somente os componentes de entrada podem ser participantes de um formulário virtual. Como um componente de entrada é por definição qualquer componente que possa enviar a página da Web (incluindo componentes de entrada com o recurso Enviar automaticamente ao alterar ativado), qualquer componente de entrada também pode ser um remetente do formulário virtual.
• Os formulários virtuais não impõem limitações topográficas; seus participantes e remetentes não precisam aparecer visualmente próximos uns dos outros.
• Um componente de entrada pode participar em vários formulários virtuais, mas um componente de envio pode enviar no máximo um formulário virtual.
• Um componente de entrada pode enviar um formulário e participar simultaneamente de um ou mais formulários virtuais.
• Se um componente de envio não enviar quaisquer formulários virtuais, então, quando o usuário interagir com ele, o formulário literal será enviado, como de costume.

Ao contrário da propriedade immediate que pode definir somente um único grupo, uma página pode usar tantos formulários virtuais quanto necessários, tornando-os uma solução poderosa. Alem disso, enquanto a propriedade immediate altera o clico de vida do JavaServer Faces e é, portanto, apropriada para desenvolvedores avançados, os formulários virtuais não o são e, portanto, são mais fáceis de usar.

Observe a Figura 3, que mostra Page1.jsp do aplicativo Administração de filmes no editor visual do IDE. Os formulários virtuais são codificados por cor; linhas sólidas indicam participação; linhas pontilhadas indicam envio. Quatro formulários virtuais são usados:

• gênero. A lista suspensa Gênero atual participa e envia o formulário virtual de gênero (azul). Para mostrar que participa e envia esse formulário virtual, suas bordas norte e oeste são sólidas e suas bordas sul e leste são pontilhadas.
• atualizar. Na tabela, o título, ano, duração em minutos, classificação, URL da imagem e campos de descrição participam no formulário virtual atualizar (verde), e o botão Atualizar o envia.
• visualizar/remover. Os botões Visualizar e Remover enviam o formulário virtual visualizar/remover (vermelho), que não possui participantes.
• adicionar. Na seção Adicionar filme, o gênero, título, ano, duração em minutos, classificação, URL da imagem e os campos de descrição participam no formulário virtual adicionar (amarelo), e o botão Adicionar o envia.

Observação: Page1.jsp possui um componente Lista de mensagens incorporado em um painel de grupo. A lista de mensagens possui uma borda vermelha e o painel de grupo exibe uma borda pontilhada no editor visual. Não fique confuso com isso, as bordas desses componentes não são relacionadas a formulários virtuais.

Vale a pena repetir que, enquanto um formulário pode ter um ou mais remetentes, qualquer componente de envio determinado pode enviar no máximo um formulário virtual. Portanto, para instâncias, o formulário virtual visualizar/remover possuem dois remetentes, ou seja, os botões Visualizar e Remover. Entretanto, cada um desses botões envia somente tal formulário virtual, eles não podem enviar mais de um formulário virtual. Alem disso, embora não aconteça no aplicativo Administração de filmes, isso seria perfeitamente correto (e é extremamente comum) para um componente de entrada participar em vários formulários virtuais. Além disso, enquanto os componentes associados a cada formulário virtual em Page1.jsp tendem a aparecer visualmente próximos um do outro, isso não é um requisito do mecanismo de formulários virtuais.

Os quatro formulários virtuais usados em Page1.jsp satisfazem os requisitos de processamento seletivo da página, da seguinte forma:

• gênero. Quando o funcionário altera e seleção na lista suspensa Gênero atual, o formulário virtual gênero é enviado. Como a lista suspensa é o único participante no formulário virtual, somente sua entrada é processada; as outras entradas na página são ignoradas. Como resultado, os conversores e validadores associados a essas outras entradas não rejeitam o envio.
• atualizar. Quando o funcionário clica no botão Atualizar, o formulário virtual atualizar é enviado. Como somente as entradas na tabela participam nesse formulário virtual, essas entradas são processadas enquanto todas as entradas são ignoradas. Como resultado, os conversores e os validadores em campos na seção Adicionar filme não rejeitam o envio.
• visualizar/remover. Quando o funcionário clica em um botão Visualizar ou Remover, o formulário virtual visualizar/remover é enviado. Nenhuma entrada é processada, já que o formulário virtual não contém participantes. Como mencionado anteriormente, nenhuma entrada precisa ser processada porque o componente Tabela e as APIs DataProvider fornecem acesso para a linha em que o botão foi clicado. Como resultado, nenhum dos conversores ou validadores na página rejeitam o envio.
• adicionar. Quando o funcionário clica no botão Adicionar, o formulário virtual adicionar é enviado. Como somente as entradas na seção Adicionar filme participam nesse formulário virtual, essas entradas são processadas enquanto as outras entradas são ignoradas. Como resultado, os conversores e validadores em campos na tabela não rejeitam o envio.

Retendo e descartando valores enviados

Se o usuário envia um formulário virtual que faz com que a mesma página seja reexibida, o comportamento padrão da implementação dos formulários virtuais é reter e exibir os valores enviados de não-participantes. Isso evita a perda de quaisquer entradas do usuário que não foram processadas. Por exemplo, digamos que o usuário indique alguns dados nos campos na seção Adicionar filme. Entretanto, antes de clicar no botão Adicionar, o usuário decide alterar a seleção na lista suspensa Gênero atual ou modificar alguns dados na tabela e clicar no botão Atualizar. Como resultado, será enviado um formulário virtual em que os campos de entrada na seção Adicionar filme não participam. Para não perder as entradas do usuário nesse campos de entrada, quando a página é reexibida, esses campos de entrada retêm e exibem seus valores enviados em vez de exibir 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. The values are the actual current values of the components.

Entretanto, existem alguns gestos do usuário para os quais desejamos anular o comportamento padrão. Nesses casos, em vez de reter e exibir os valores enviados de alguns não-participantes, queremos descartar explicitamente seus valores enviados e exibir seus valores. Por exemplo, os campos de entrada na tabela não participam no formulário virtual do gênero. Portanto, quando o usuário altera a seleção na lista suspensa Gênero atual e a página é reexibida subseqüentemente, o comportamento padrão é para os campos de entrada na tabela reterem e exibirem seus valores enviados. Isso não é o que queremos, já que os filmes do gênero antigo aparecerão na tabela em vez dos que estão no novo gênero. Portanto, é necessário anular o comportamento padrão, descartando explicitamente os valores enviados no método currentGenreDropDown_processValueChange:

// the genre virtual form, in which only the currentGenreDropDown
// participates, has been submitted
// make sure the input fields in the movies table do not
// retain their submitted values
form1.discardSubmittedValues("update");

Aqui os participantes da atualização do formulário virtual (ou seja, todos os campos de entrada na tabela) descartam explicitamente seus valores enviados. Como resultado, eles irão exibir seus valores, o que significa que a tabela exibirá os filmes no novo gênero em vez do gênero 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)

O primeiro método acima aceita um nome de formulário virtual. Os participantes do formulário virtual especificado descartam seus valores enviados. O formulário virtual especificado não pode ser aquele que foi enviado. Este método lança um IllegalArgumentException se o formulário virtual especificado tiver sido enviado durante a solicitação atual.

O segundo método acima aceita um único campo de entrada como um objeto EditableValueHolder. O campo de entrada especificado descartará seu valor enviado. Observe que 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.

A propriedade internalVirtualForm

O componente Tabela possui uma propriedade internalVirtualForm que é falsa por padrão. Na tabela em Page1.jsp, essa propriedade foi definida como verdadeira. Isso faz com que a tabela use um formulário virtual internamente. Como resultado, quando os controles de paginação são usados, somente as entradas na tabela são processadas. Isso evita que os conversores e validadores nos campos fora da tabela rejeitem o envio.

Caixa de diálogo Formulários virtuais

No NetBeans IDE, você pode criar, excluir e renomear formulários virtuais e alterar seus códigos de cor, clicando com o botão direito do mouse no próprio editor visual (não em qualquer componente) e escolhendo o item Formulários virtuais do menu contextual. A caixa de diálogo Formulários virtuais se abre, como mostrado na figura seguinte.

Usar essa caixa de diálogo é extremamente direto. Para alterar a cor associada a um formulário virtual, clique na célula Cor e selecione uma cor na lista. Para renomear um formulário virtual, clique duas vezes na célula Nome e edite o nome. Você também cria e exclui formulários virtuais nessa caixa de diálogo.

Caixa de diálogo Configurar formulários virtuais

Embora a caixa de diálogo Formulários virtuais permita que você crie, exclua e renomeie formulários virtuais e altere seus códigos de cor, ela não permite que você configure os componentes que participam e enviam cada formulário virtual. A caixa de diálogo Configurar formulários virtuais permite que você faça todas essas coisas. Para acessar essa caixa de diálogo, selecione um ou mais componentes na janela Editor visual ou Esboço, clique com o botão direito do mouse e escolha o item do menu contextual Configurar formulários virtuais. A caixa de diálogo resultante permite que você especifique os formulários virtuais em que os componentes selecionados participam. Você também pode especificar um formulário virtual que os componentes selecionados enviam. Como a caixa de diálogo Formulários virtuais, a caixa de diálogo Configurar formulários virtuais também permite que você crie, exclua e renomeie os formulários virtuais e altere seus códigos de cor. A figura abaixo mostra a caixa de diálogo Configurar formulários virtuais depois da seleção de todos os componentes de entrada na seção Adicionar filme em Page1.jsp.

Formulários virtuais e Enviar automaticamente ao alterar

Embora os componentes botão e link sejam os componentes de envio mais comuns, um componente de entrada como uma lista suspensa também pode ser um componente de envio. Em Page1.jsp do exemplo Administração de filmes, a lista suspensa Gênero atual participa e envia o formulário virtual gênero. Ela foi configurada dessa forma por meio da caixa de diálogo Configurar 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. Observe que não há opção Enviar automaticamente ao alterar para componentes botão e link porque eles intrinsecamente enviam a página da Web.

Formulários virtuais e Fragmentos de página

No NetBeans IDE, não há suporte para formulários virtuais em fragmentos de página. Para configurar o processamento seletivo em componentes em um fragmento de página, defina a propriedade immediate como verdadeira nesses componentes. Essa solução é suficiente para cobrir inúmeros casos de uso; entretanto, ela ainda é limitada porque só pode configurar o processamento seletivo em um grupo de componentes.

Formulários virtuais e o componente Tabela de dados padrão

Embora não seja um caso de uso comum, é importante observar que se quiser que um botão ou link em um componente Tabela de dados padrão (não o novo componente Tabela) envie um formulário virtual, você deve adicionar script extra à propriedade onClick (ou onclick) do botão ou do link. Digamos que você tenha um componente Botão cuja propriedade id seja button1 dentro de um componente Tabela de dados padrão. Você precisaria adicionar o seguinte a propriedade onClick do botão:

Exemplo de código 3:

common_leaveSubmitterTrace(this.form,'button1');

Sem esse script extra, o botão não conseguiria enviar um formulário virtual. Novamente, isso só se aplica aos botões e links (não aos componentes de entrada) dentro de um componente Tabela de dados padrão (não ao novo componente Tabela).

Resumo

Este artigo técnico explora o novo recurso Formulários virtuais no NetBeans IDE. Um formulário virtual define um grupo de componentes de entrada ("participantes") e componentes de envio ("remetentes") em uma página, de forma que quando o usuário interage com um dos remetentes, os participantes são processados exclusivamente enquanto as entradas restantes na página são ignoradas. Você também aprendeu sobre:

• Os requisitos de processamento seletivo do aplicativo de exemplo Administração de filmes e testemunhou como os formulários virtuais fornecem uma solução poderosa e abrangente para atender a esses requisitos.
• Como modificar a configuração do formulário virtual da página no IDE por meio das caixas de diálogo Formulários virtuais e Configurar formulários virtuais.
• Como os componentes de entrada podem enviar um formulário virtual se seu recurso Enviar automaticamente ao alterar estiver ativado.
• Que, a propriedade immediate, os formulários virtuais não alteram o ciclo de vida do JavaServer Faces e, portanto, são fáceis de usar.

Consulte também

• Trilha do aprendizado das aplicações Web

início