>> Mais documentação do Visual Web Pack

Usando o componente Classificação Ajax

Março de 2007 [Número da revisão: V1-1]

Neste tutorial, você usa o componente Classificação para permitir que o usuário atribua uma classificação a um item. O tutorial fornece uma implementação de uma classe RatingData, que mantém a classificação do usuário, o número de votos e a classificação média para o item. Por padrão, o componente Classificação exibe uma linha de cinco estrelas, mas você personaliza a aparência e o texto do componente, o que é mostrado no tutorial. O aplicativo que você constrói neste tutorial simula um aplicativo real em que usuários podem classificar um item. A primeira página do aplicativo apresenta livros para usuários navegarem e classificarem. A segunda página exibe os detalhes do livro que o usuário selecionou na primeira página.

Conteúdo   -  Adicionando a classe RatingData ao projeto -  Adicionando propriedades ao Bean de sessão -  Criando a página de início -  Trabalhando com o componente Classificação -  Testando o aplicativo -  Fazendo mais: Adicionando um segundo item a ser classificado -  Fazendo mais: Separando a classificação média e a classificação do usuário

Arquivos usados neste tutorial

» RatingData.java » fieldguide.png » corejsfbook.png

Este tutorial funciona com as tecnologias e os recursos seguintes

Componentes JavaServer Faces/ Plataforma Java EE	1.2 com Java EE 5* 1.1 com J2EE 1.4
Banco de dados Viagem	Não é necessário
Biblioteca de componentes BluePrints Ajax	Necessário

* Na data da publicação deste tutorial, somente o servidor de aplicativos Sun Java System oferecia suporte ao Java EE 5.

Este tutorial foi adaptado para ser usado com o Servidor de aplicativos Sun Java System PE 9.0, versão atualizada 1, e o Tomcat 5.5.17. Se você estiver usando um servidor diferente, consulte as Notas de versão e as Perguntas freqüentes para obter informações sobre problemas conhecidos e soluções sugeridas. Para obter informações detalhadas sobre os servidores suportados e a plataforma Java EE, consulte as Notas de versão.

Adicionando a classe RatingData ao projeto:

1. Faça o download de RatingData.java para o sistema de arquivos.
2. Faça o download e importe os os componentes Ajax se ainda não o fez.
3. Crie um novo projeto de aplicativo da Web visual e nomeie-o RatingExample.

4. Na janela Projetos, clique com o botão direito do mouse no nó RatingExample > Bibliotecas de componentes e escolha Adicionar biblioteca de componentes no menu pop-up. Selecione Componentes BluePrints Ajax e clique em Adicionar biblioteca de componentes.

   O IDE copia a biblioteca de componentes no projeto, adiciona os componentes e dá suporte a Beans na Paleta.

5. No menu principal, escolha Arquivo > Adicionar item existente > Fonte Java. Na caixa de diálogo Adicionar item existente, navegue até RatingData.java, selecione-o e, em seguida, clique em Adicionar.

   O IDE adiciona a classe RatingData ao pacote ratingexample.
6. No menu principal, escolha Construir > Construir projeto principal para compilar a classe RatingData.

7. Feche e abra novamente o projeto RatingExample para que RatingData esteja disponível no tempo de design.

   Se não executar esta etapa, você verá um erro ao vincular as propriedades no componente Classificação a currentRatingData na seção final deste tutorial.
8. Se já não for o projeto principal, clique com o botão direito do mouse em RatingExample na janela Projetos e selecione Definir como projeto principal.

Adicionando propriedades ao Bean de sessão

1. Se não estiver aberta, abra Page1 no Visual Designer.
2. Na janela Esboço, clique com o botão direito do mouse no nó SessionBean1 e escolha Adicionar > Propriedade.

3. Na caixa de diálogo Novo padrão de propriedade, digite ratingMap no campo Nome e HashMap no campo Tipo. Defina o Modo como Read Only e clique em OK.

   A propriedade ratingMap armazena os dados de classificação de cada item.
4. Na janela Esboço, clique duas vezes no nó SessionBean1 para abrir SessionBean1.java no editor de Java. Coloque o cursor no editor e pressione as teclas Alt-Shift-F para adicionar automaticamente a seguinte instrução de importação e corrigir os erros de HashMap não localizado:

   import java.util.HashMap;

5. Volte para a Page1 no Visual Designer para que a janela Esboço seja visível. Adicione uma segunda propriedade SessionBean nomeada currentRatingData do tipo RatingData. Não altere o Modo padrão de Read/Write. Clique em OK.

   Esta propriedade armazena os dados de classificação do item atual. Este aplicativo tem duas páginas e atual refere-se ao item exibido na segunda página.

6. Adicione uma terceira propriedade SessionBean nomeada itemMap do tipo HashMap. Defina o Modo como Read Only e clique em OK.

   A propriedade itemMap armazena os dados relacionados a não-classificação de cada item, neste caso o URL da imagem e a descrição do item.

7. Adicione uma quarta propriedade SessionBea. Nomeie a propriedade currentItemData, torne-a uma matriz de seqüência (String[]) e use o modo padrão Read/Write. Clique em OK.

   Esta propriedade de matriz de seqüência contém o URL da imagem e uma descrição do item atual.
8. Abra SessionBean1.java e acrescente o seguinte código mostrado em negrito ao método SessionBean1.init.
   
   

   Amostra de código 1: Propriedade de SessionBean1.init

   public void init() { // Desempenha inicializações herdadas de nossa superclasse super.init(); // Desempenho inicialização de aplicativo que deve ser completada // *antes* de componentes gerenciados serem inicializados // TODO - adicione aqui seu próprio código de inicialização ratingMap = new HashMap(); itemMap = new HashMap(); String[] itemIds = {"fieldGuide", "coreFaces"}; String[] hoverTexts = {"I hate it", "I dislike it", "It's OK", "I like it", "I love it"}; for (int i = 0; i < itemIds.length; i++) { RatingData ratingData = new RatingData(hoverTexts); ratingMap.put(itemIds[i], ratingData); if (i == 0) { currentRatingData = ratingData; } } currentItemData = new String[]{"/resources/fieldguide.png", "O guia definitivo para o NetBeans IDE."}; itemMap.put(itemIds[0], currentItemData); itemMap.put(itemIds[1], new String[] {"/resources/corejsfbook.png", "O livro de que você precisa para dominar esta tecnologia que poupa tempo."}); }

   
   

   Este código preenche as propriedades do Bean de sessão. O código primeiro inicializa ratingMap e itemMap. Em seguida o loop for cria instâncias de RatingData e as coloca no ratingMap, definindo a primeira instância de RatingData como os dados de classificação atuais.

   Observe que as instâncias de RatingData são construídas com hoverTexts, que são exibidos quando o usuário passa o mouse sobre as estrelas no componente. Depois do loop for, o código cria matrizes de seqüência para conter os dados de item (URL da imagem e descrição) e define a primeira matriz de seqüência como os dados de item atuais (currentItemData).

Criando a página de início

Agora você cria a página inicial e adiciona o componente Classificação e outros componentes básicos, como mostrado na figura abaixo. Nesta página, o usuário pode atribuir uma classificação a um livro e em seguida exibir a classificação, assim como a classificação média do livro.

Figura 1: Design da página do componente Classificação

1. Se já não fez, faça o download de fieldguide.png para o sistema de arquivos.
2. Clique na guia Page1 para retornar ao Visual Designer.
3. Na seção Básico da Paleta, arraste o componente Rótulo para a página, digite Procurar livros e pressione Enter. Na janela Propriedades, defina a propriedade id de Rótulo como headerLabel e labelLevel como Strong(1).
4. Arraste um componente Hyperlink de imagem para a página. Defina a propriedade id como fieldGuideLink e remova as palavras Image Hyperlink da propriedade text.

5. Clique com o botão direito do mouse em Hyperlink de imagem e escolha Definir imagem no menu pop-up. Vá até fieldguide.png, selecione-o e clique em OK.

   Uma imagem do Guia de campo do NetBeans IDE aparece na página. O arquivo é também copiado no subdiretório web/resources do projeto.

6. Na seção Componentes BluePrints Ajax da Paleta, arraste um componente Classificação para a página. Defina a propriedade id do como fieldGuideRating.

   Por padrão, o componente Classificação exibe uma linha de cinco estrelas, como mostrado na Figura 1 acima.

7. Clique duas vezes no Hyperlink de imagem de fieldGuideLink e substitua o corpo do método fieldGuideLink_action() pelo código que aparece abaixo em negrito.

   Certifique-se de remover return null;, porque ele será substituído por return "Detail";

   Amostra de código 2: Método fieldGuideLink_action

   public String fieldGuideLink_action() { SessionBean1 sessionBean = getSessionBean1(); sessionBean.setCurrentItemData ((String[])sessionBean.getItemMap().get("fieldGuide")); sessionBean.setCurrentRatingData ((RatingData)sessionBean.getRatingMap().get("fieldGuide")); return "Detail"; }

   
   Este código define fieldGuide como o item atual. Especificamente, o código define as propriedades de currentItemData e currentRatingData do Bean da sessão. Quando um usuário clica no Hyperlink de imagem, este método retorna ao Detalhe de resultado, fazendo com que uma segunda página se abra e exiba os dados do item atual. Você adicionará a página Detalhe ao projeto mais adiante no tutorial.

Trabalhando com o componente Classificação

1. Clique no botão Design para reabrir Page1 no Visual Designer. Selecione o componente Classificação e, em seguida, reconfigure o componente definindo as seguintes propriedades na seção Aparência da janela Propriedades.

   Propriedades da aparência
   includeClear	para True
   includeModeToggle	para True
   includeNotInterested	para True

   
   
   Quando você define cada propriedade como Verdadeiro, o IDE adiciona um controle ao componente Classificação. O resultado final é mostrado na figura abaixo.
   
   

   Figura 2: Componente Classificação personalizado

   • O controle é usado para indicar que um usuário não está interessado em um item.
   • O controle é usado para limpar uma classificação do usuário.
   • O controle é um controle de alternância de modos. O componente Classificação pode alternar entre exibir a classificação atribuída pelo usuário e a classificação média do item.

2. Defina as seguintes propriedades na seção Dados da janela Propriedades. Em diversos casos, você vincula a propriedade do componente a uma entrada no ratingMap ou no itemMap.

   É necessário inserir estas expressões de vinculação diretamente na janela Propriedades. Estas vinculações não estão disponíveis na caixa de diálogo Vinculações de propriedade porque a caixa de diálogo não mostra entradas em objetos Mapa.

   Propriedades de dados
   averageGrade	#{SessionBean1.ratingMap.fieldGuide.averageGrade}
   averageModeHoverText	Mostrar a classificação média deste item
   averageModeText	#{SessionBean1.ratingMap.fieldGuide.averageModeText}
   clearHoverText	Limpar minha classificação
   grade	#{SessionBean1.ratingMap.fieldGuide.grade}
   hoverTexts	#{SessionBean1.ratingMap.fieldGuide.hoverTexts}
   inAverageMode	para True
   normalModeHoverText	Mostrar a classificação deste item
   normalModeText	#{SessionBean1.ratingMap.fieldGuide.normalModeText}
   notInterestedHoverText	Não estou interessado neste item

   • A propriedade grade é a classificação (o número de estrelas) que o usuário atribuiu ao item, enquanto a propriedade averageGrade é o grau médio que a população de usuários atribuiu ao item.
   • As propriedades que incluem a palavra Text definem o texto que o usuário vê ao passar o mouse sobre os controles e fora deles no componente. Observe as propriedades de texto separadas para o usuário (normal) e o modo médio.
   • A propriedade inAverageMode, quando Verdadeira, define a exibição inicial do componente como o modo médio.

   Para obter mais informações sobre uma propriedade, mova o mouse sobre o nome da propriedade na janela Propriedades e o IDE exibirá uma dica de ferramenta.

Testando o aplicativo

1. Execute o projeto. O aplicativo abre-se no navegador da Web dentro do componente Classificação e exibe a classificação média, como indicado pelo controle e pelo texto a seguir:

   Average rating:  0 (from 0 votes).

   Mova o mouse sobre o componente e observe como o texto altera-se para descrever cada controle. Quando você afasta o mouse do componente, a classificação média retorna.

2. Dê ao Guia de campo uma classificação de 4 estrelas. O componente aceita a classificação e passa para o modo (normal) de usuário, como indicado pelo controle .

   Quando você afasta o mouse do componente, você vê o texto: "Saved: I like it", que indica que a classificação foi salva.
3. Mude de idéia e dê ao Guia de campo uma classificação de 5 estrelas. O texto agora é salvo como "Saved: I love it."

4. Mova o mouse sobre o controle , observe que ele se transforma no , e clique no controle.

   Quando você afasta o mouse do componente, você vê que a classificação média é 4,5 de 2 votos.

5. Continue a explorar o componente clicando nos controles Limpar e Não interessado.

   Neste ponto, nada acontece quando você clica na imagem do Guia de campo. Você irá implementar o código para este link mais adiante no tutorial.

Fazendo mais: Adicionando um segundo item a ser classificado

O projeto descrito nas etapas anteriores oferece uma boa introdução ao trabalho com o componente Classificação e sua personalização. Um aplicativo real muito provavelmente inclui mais de um item a ser classificado. Aqui você adiciona à página um segundo livro e um segundo componente Classificação, como mostra a figura abaixo.

Figura 3: Dois itens na página

1. Se já não fez, faça o download de corejsfbook.png para o sistema de arquivos.
2. Arraste um componente Hyperlink de imagem para Page1 e coloque-o no componente Classificação. Defina a propriedade id como coreFacesLink e remova as palavras ImageHyperlink da propriedade text.

3. Clique no botão de reticências (...) para abrir a propriedade imageURL. Na caixa de diálogo corejsfbook.png - URL de imagem, navegue até corejsfbook.png e o selecione. Clique em OK.

   Uma imagem do livro Core Faces aparece na página. O IDE também copia o arquivo no subdiretório web/resources do projeto.

4. Copie o componente Classificação para o livro Guia de campo e cole a cópia abaixo da imagem Core JSF. Defina a propriedade id do novo componente Classificação como coreFacesRating.

5. Na seção Dados da janela Propriedades, edite as expressões para as propriedades vinculadas, para que as propriedades contenham a chave coreFaces em vez da chave fieldGuide.

   OBSERVAÇÃO: Se a configuração da propriedade não aparecer na janela Propriedades, clique no botão de reticências (...) associado à propriedade e clique em Cancelar na janela pop-up. O texto apropriado deve aparecer na janela Propriedades. Não edite a propriedade na caixa de diálogo.

6. Clique duas vezes no Hyperlink de imagem coreFacesLink e implemente o método de ação com o código abaixo.

   Também neste caso, certifique-se de remover return null;, porque ele será substituído por return "Detail";

   Amostra de código 3: Método coreFacesLink

   public String coreFacesLink_action() { SessionBean1 sessionBean = getSessionBean1(); sessionBean.setCurrentItemData ((String[])sessionBean.getItemMap().get("coreFaces")); sessionBean.setCurrentRatingData ((RatingData)sessionBean.getRatingMap().get("coreFaces")); return "Detail"; }

7. Execute e teste o aplicativo.

Fazendo mais: Separando a classificação média e a classificação do usuário

1. Na janela Projetos, clique com o botão direito do mouse em RatingExample > Páginas da Web e escolha Nova > Página no menu pop-up. Nomeie a nova página Detail.

   A imagem abaixo mostra a página que você criará nesta seção.

   Figura 4: Design da página de detalhes

2. Arraste um componente Hyperlink para a página, digite Voltar a procurar livros e pressione Enter. Na janela Propriedades, defina a propriedade id como browseLink e a propriedade url como /faces/Page1.jsp.
3. Arraste um componente Imagem para a página. Defina a propriedade id como currentItemImage e a propriedade url como #{SessionBean1.currentItemData[0]}.
4. Arraste um componente Texto estático para a página. Defina a propriedade id como currentItemText. Defina a propriedade text como #{SessionBean1.currentItemData[1]}.
5. Arraste um componente Classificação para a página. Defina as propriedades da seguinte forma:
   
   

   Propriedades
   Geral
   id	averageRating
   Dados
   averageGrade	#{SessionBean1.currentRatingData.averageGrade}
   averageModeText	#{SessionBean1.currentRatingData.averageModeText}
   inAverageMode	para True
   Avançado
   gradeReadOnly	para True

6. Arraste um segundo componente Classificação para a página. Defina as propriedades da seguinte forma:
   
   

   Propriedades
   Geral
   id	myRating
   Aparência
   includeClear	para True
   includeNotInterested	para True
   Dados
   clearHoverText	Limpar minha classificação
   grau	#{SessionBean1.currentRatingData.grade}
   hoverTexts	#{SessionBean1.currentRatingData.hoverTexts}
   normalModeText	#{SessionBean1.currentRatingData.normalModeText}
   notInterestedHoverText	Não estou interessado neste item

7. Clique com o botão direito do mouse Visual Designer e escolha Navegação de página no menu pop-up.

   A janela Navegador de página abre-se no IDE.

8. Arraste um conector da porta do conector ao lado do ícone Page1.jsp para o ícone Detail.jsp. Nomeie o conector Detail, como mostrado na figura abaixo. Observe que, após o uso de uma porta do conector, o IDE adiciona uma outra abaixo dela.

   Figura 5: Navegação de página

9. Execute e teste o aplicativo. Clique em uma imagem de livro na primeira página para abrir uma segunda página que exibe informações detalhadas sobre o livro. Observe que os dados de classificação são preservados nas páginas.

   OBSERVAÇÃO: Quando você classifica um item na página Detalhe, é necessário atualizar a página para atualizar a classificação média. No entanto, quando você navega de volta para Page1, o grau médio atualizado é mostrado automaticamente. Estes dois comportamentos simulam um aplicativo real. Você necessita do grau médio para ser preciso quando a página for processada, mas não é necessário atualizar o grau médio em tempo real toda vez que o item é classificado.

Experimente. Para este tutorial, a página Detalhe exibe simplesmente a imagem e a descrição do item selecionado na Page1. Em um aplicativo real, você poderia incluir mais informações na página Detalhe, como uma data de publicação, o número ISBN, comentários do editor, e assim por diante. Para isso, primeiro adicione as informações às matrizes de seqüência. Em seguida adicione um componente Texto estático à página Detalhe para cada nova informação. Por fim, vincule os novos componentes Texto estático na página Detalhe aos novos membros da matriz de seqüência currentItemData.

Resumo

Seguem-se as características de destaque do componente Classificação:

• Por padrão, o componente Classificação inclui uma linha de cinco estrelas. Você pode personalizar o número de estrelas modificando o valor da propriedade maxGrade.
• O componente Classificação também tem propriedades para incluir os controles Limpar e Não interessado, e para personalizar o texto que aparece quando o usuário passa o mouse sobre esses controles ou fora deles.
• O controle de alternância de modos do componente permite que você mostre as classificações média e de usuário na mesma instância do componente. No entanto, se preferir, você também pode mostrar as classificações média e de usuário em duas instâncias. O componente tem propriedades para definir o texto e passar sobre texto associado a cada modo.
• As classificações média e de usuário são preservadas nas páginas.
• Uma vez que um aplicativo normalmente inclui mais de um item a ser classificado, é melhor criar um mapa para conter as instâncias dos dados de classificação.
• Um solicitação em Ajax é enviada somente quando o usuário altera a classificação. Se o usuário atribuir a mesma classificação já salva, uma solicitação em Ajax não será enviada.
• O texto do modo normal e o texto do modo médio do componente Classificação pode ser atualizado (e internacionalizado) no servidor, em resposta às solicitações em Ajax.

• Fazendo download e importando Ajax e outros componentes no NetBeans Visual Web Pack 5.5
• Usando o componente Visualizador de mapa Ajax
• Usando o componente Barra de progresso Ajax

---

Envie-nos seus comentários