>> Mais documentação do Visual Web Pack

Usando o componente Barra de progresso Ajax

Conteúdo -  Configurando o aplicativo -  Modificando o Bean de sessão -  Criando uma barra de progresso determinada -  Adicionando código à barra de progresso -  Fazendo mais #1: Adicionando uma barra de progresso indeterminada -  Fazendo mais #2: Simulando uma tarefa falha -  Fazendo mais #3: Alterando o estilo da barra de progresso

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.

Configurando o aplicativo

1. Faça o download e importe a última versão dos componentes Ajax se ainda não tiver feito.
2. Faça o download de SimpleTask.java e pb.js e salve-os no seu sistema de arquivos.

3. Crie um novo projeto de aplicativo da Web visual e nomeie-o de ExemploBarraProgresso.

   A página inicial do ExemploBarraProgresso se abre no Visual Designer.

4. Adicione SimpleTask.java ao projeto da seguinte forma:

   1. No menu principal, escolha Arquivo > Adicionar item existente > Fonte Java. Vá até o diretório no qual salvou SimpleTask.java. Selecione o arquivo e clique em Adicionar.

   2. Na janela Projetos, expanda Pacotes de fontes > exemplobarraprogresso. Clique duas vezes no nó SimpleTask.java para abrir o arquivo no Editor Java.

      A instrução de pacote abaixo é adicionada na parte superior do arquivo:

      package exemplobarraprogresso;

5. Adicione o arquivo JavaScript pb.js ao projeto da seguinte forma:

   1. Escolha Arquivo > Adicionar item existente > Outro (todos os arquivos). Vá até pb.js, selecione-o e clique em Adicionar.
   2. Na janela Projetos, arraste pb.js de Pacotes de fontes > exemplobarraprogresso para Páginas da Web > recursos.

Modificando o Bean de sessão

1. Abra Page1 no Visual Designer.

2. Na janela Esboço, clique com o botão direito do mouse no SessionBean1 e escolha Adicionar > Propriedade.

   Observação: Se o menu de Adicionar não estiver ativado quando você abrir o menu pop-up pela primeira vez, feche o menu e clique com o botão direito do mouse no nó SessionBean1 pela segunda vez para ativar o submenu de Adicionar.

3. Na caixa de diálogo Novo padrão de propriedade, defina o Nome como taskMap, o Tipo como HashMap (observe que os campos Nome e Tipo fazem diferenciação entre maiúscula e minúscula) e o Modo como Somente leitura, como mostrado na figura abaixo. Clique em OK.

   Figura 1: Caixa de diálogo Novo padrão de propriedade

4. Clique com o botão direito do mouse no nó SessionBean1 e escolha Editar fontes Java no menu pop-up.

   As anotações de erro aparecem no código indicando que a classe HashMap não foi encontrada.

5. Clique com o botão do mouse no SessionBean1.java e escolha Corrigir importações no menu pop-up para adicionar automaticamente a seguinte instrução de importação:

   import java.util.HashMap;

6. Anexe as seguintes linhas de código (em negrito) ao método SessionBean1.init.

   Amostra de código 1: Propriedade de SessionBean1

   public void init() { // Realizar inicializações herdadas da nossa superclasse super.init(); // Realizar a inicialização do aplicativo que deve completar-se // *antes* que os componentes gerenciados sejam inicializados // TODO - adicione o seu código de inicialização aqui Inicialização de componente gerenciado pelo Creator // Realizar a inicialização do aplicativo que deve completar-se // *depois* que os componentes gerenciados sejam inicializados // TODO - adicione o seu código de inicialização aqui taskMap = new HashMap(); taskMap.put("progressBar1", new SimpleTask("progressBar1", 241, 100, false)); }

   
   Este código preenche a propriedade taskMap construindo um HashMap e adicionando uma nova instância de SimpleTask ao HashMap.

Criando uma barra de progresso determinada

A barra de progresso determinada é usada quando você deseja determinar a porcentagem de progresso de uma tarefa quando a tarefa é concluída. Nesta seção, você cria uma página que inclui uma barra de progresso determinada e dois botões. O primeiro botão inicia, pausa e retoma a tarefa associada à barra de progresso, enquanto que o segundo botão pára a tarefa. A figura abaixo apresenta uma ilustração da aparência desta página :

Figure 2: Design da página de progresso

1. Na janela Projetos, clique com o botão direito do mouse no nó ExemploBarraProgresso > 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 em um projeto e adiciona os componentes na Paleta.
2. Abra Page1 no Visual Designer.

3. Abra a seção Componentes BluePrints Ajax da Paleta e arraste um componente Barra de progresso para a página. Para obter este tutorial, use a propriedade id padrão de progressBar1.

   Observação: A barra de progresso deve ser exibida como mostrado na Figura 2 acima. Se a barra de progresso for exibida incorretamente, clique com o botão direito do mouse no Visual Designer e escolha Atualizar no menu pop-up.
4. Arraste um componente Painel de grade da seção Layout da Paleta para a direita da barra de progresso.
5. Defina a propriedade id do Painel da grade como controlPanel e a propriedade columns como 2.

6. Arraste dois componentes Botão da seção Básico da Paleta para o Painel de grade.

   Ao soltar os componentes Botão, certifique-se de que o contorno do componente Layout de grade é uma linha azul sólida.

7. Defina as seguintes propriedades para o primeiro botão:

   Propriedade	Valor
   id	variableControl
   text	Iniciar
   onClick	handleVariableControlOnClick(this, 'form1:progressBar1', false)

   
     A função handleVariableControlOnClick faz chamadas JavaScript para iniciar, pausar ou retomar a barra de progresso quando o usuário clica no botão.

8. Defina as seguintes propriedades para o segundo botão:

   Propriedade	Valor
   id	stopControl
   text	Cancelar
   onClick	handleStopControlOnClick('form1:variableControl', 'form1:progressBar1')

   
     A função handleStopControlOnClick faz uma chamada JavaScript para parar a barra de progresso.

9. Na janela Esboço, selecione form1. Na janela Propriedades, defina a propriedade onSubmit do formulário para que retorne handleFormOnSubmit().

   Esta função JavaScript evita que a página seja enviada quando o usuário clicar em qualquer um dos dois botões.

10. Arraste um componente Script da seção Avançado da Paleta para a página.

    A janela Esboço exibe o script1 na seção Page1. Este componente não visual declara um elemento de script na marcação HTML renderizada.
11. Na janela Propriedades, defina a propriedade url do Script como /resources/pb.js. Observe que esta propriedade exige a barra inclinada (/).

Adicionando código à barra de progresso

Nesta seção, você adiciona quatro métodos ao código Java do projeto. Estes métodos realizam as seguintes ações e favorecem às propriedades Events do componente Barra de progresso:

• Iniciar ou retomar a tarefa indicada na solicitação em Ajax
• Pausar a tarefa indicada na solicitação em Ajax
• Parar a tarefa indicada na solicitação em Ajax
• Extrair o id do componente (por exemplo, progressBar1) da barra de progresso que enviou a solicitação em Ajax

1. Abra Page1 no Editor Java e adicione o seguinte código (em negrito) depois do método destroy().

   Amostra de código 2: Métodos adicionais da barra de progresso

   public void destroy() { } /** * Iniciar ou retomar a tarefa indicada na solicitação em Ajax. */ public void startOrResumeTask(FacesContext context) { String taskId = getTaskIdFromAjaxRequest(context); SimpleTask task = (SimpleTask)getSessionBean1().getTaskMap().get(taskId); Map paramMap = context.getExternalContext().getRequestParameterMap(); String doomed = (String)paramMap.get("doomed"); task.start(Boolean.parseBoolean(doomed)); } /** * Pausar a tarefa indicada na solicitação em Ajax. */ public void pauseTask(FacesContext context) { String taskId = getTaskIdFromAjaxRequest(context); SimpleTask task = (SimpleTask)getSessionBean1().getTaskMap().get(taskId); task.pause(); } /** * Parar a tarefa indicada na solicitação em Ajax. */ public void stopTask(FacesContext context) { String taskId = getTaskIdFromAjaxRequest(context); SimpleTask task = (SimpleTask)getSessionBean1().getTaskMap().get(taskId); task.cancel(); } /** * Extrair o id do componente (por exemplo, "progressBar1") da * barra de progresso que enviou a solicitação em Ajax. */ private String getTaskIdFromAjaxRequest(FacesContext context) { Map paramMap = context.getExternalContext().getRequestParameterMap(); String progressBarClientId = (String)paramMap.get("bpui_progressbar_clientId"); if (progressBarClientId == null) { throw new NullPointerException(); } //obter o trecho a partir do último sinal de dois-pontos para a frente int lastColon = progressBarClientId.lastIndexOf(NamingContainer.SEPARATOR_CHAR); if (lastColon == -1) { return progressBarClientId; } String taskId = progressBarClientId.substring(lastColon + 1); return taskId; }

   
   Quando a Barra de progresso envia solicitações em Ajax ao servidor, ela inclui o id do cliente no parâmetro de solicitação bpui_progressbar_clientId. As solicitações em Ajax para iniciar, pausar, retomar ou parar a tarefa chamam o método startOrResumeTask, pauseTask ou stopTask no Bean de página do aplicativo. Estes métodos chamam o método getTaskIdFromAjaxRequest, que extrai o id do componente (como progressBar1) do parâmetro de solicitação bpui_progressbar_clientId. Os métodos usam o id do componente para recuperar uma instância SimpleTask do taskMap e chamam o método start, pause ou cancel da tarefa.

2. Clique com o botão direito do mouse no código-fonte de Page1 e escolha Corrigir importações no menu pop-up.

   O IDE adiciona as seguintes instruções de importação para corrigir os erros de classe não encontrada:

   import java.util.Map;
import javax.faces.component.NamingContainer;
import javax.faces.context.FacesContext;

3. Volte para a exibição Design da Page1 e defina as seguintes propriedades para o componente Barra de progresso:

   Propriedade	Valor
   stopOperation	stopTask()
   resumeOperation	startOrResumeTask()
   startOperation	startOrResumeTask()
   pauseOperation	pauseTask()
   onComplete	function() {handleProgressBarOnComplete('form1:variableControl');}

   
   

   Conforme notado anteriormente, as funções handleVariableControlOnClick e handleStopControlOnClick fazem chamadas para iniciar, pausar, retomar ou parar a barra de progresso quando o usuário clicar em um dos botões. Quando tais chamadas do código de script do lado do cliente são feitas na Barra de progresso, uma solicitação em Ajax é enviada ao servidor. Como conseqüência, o método especificado para startOperation, pauseOperation, resumeOperation ou stopOperation é chamado.

   A função handleProgressBarOnComplete altera o texto do primeiro botão para "Iniciar", caso o usuário queira reiniciar a tarefa.

   Observação: Em alguns casos, o IDE pode inserir um método startOrResumeTask adicional no código, que evita que o código seja compilado. Para corrigir esse erro, remova o método adicional.

4. Abra a exibição JSP de Page1 e adicione as propriedades interval, percentage, failed e percentageText de progressBar1, como mostrado em negrito abaixo:

   Amostra de código 3: Propriedades de progressBar1

   <bp:progressBar binding="#{Page1.progressBar1}" id="progressBar1" interval="#{SessionBean1.taskMap.progressBar1.interval}" percentage="#{SessionBean1.taskMap.progressBar1.percentage}" failed="#{SessionBean1.taskMap.progressBar1.failed}" percentageText="#{SessionBean1.taskMap.progressBar1.percentageText}" onComplete="function() ... resumeOperation=...

   
   Estas propriedades da barra de progresso estão vinculadas às propriedades correspondentes da instância SimpleTask digitadas em progressBar1 na taskMap. Você adiciona o código diretamente na fonte JSP devido às limitações nos editores de propriedades.

5. Construa e execute o aplicativo. Clique no botão Iniciar para iniciar a tarefa.

   A barra de progresso vai se preenchendo conforme a operação avança e a mensagem de texto se atualiza continuamente para indicar a porcentagem de progresso concluído (por exemplo, 25%). O botão Iniciar muda para Pausar.
6. Continue explorando o aplicativo clicando no botão Pausar (que muda para Retomar) e no botão Cancelar.

Fazendo mais #1: Adicionando uma barra de progresso indeterminada

Nesta seção, você adiciona uma barra de progresso indeterminada, que usa movimentos para mostrar que uma tarefa está em andamento, em vez de preencher a barra para mostrar a porcentagem de progresso concluído. A barra de progresso indeterminada é útil por proporcionar feedbacks em casos nos quais não se pode determinar o progresso alcançado conforme a tarefa vai se completando. A página construída nesta seção deve ser semelhante à figura abaixo:

Figura 3: Adicionando uma barra de progresso indeterminada

1. Abra a exibição Design de Page1, copie os componentes Barra de progresso e Painel de grade e cole-os debaixo dos componentes originais.

   Observação: Esta seção do tutorial usa as propriedades id padrão de progressBar2, controlPanel1, variableControl1 e stopControl1 para estes componentes.

2. Selecione o novo componente Barra de progresso e altere a propriedade onComplete para que aponte para variableControl1:

   function() {handleProgressBarOnComplete('form1:variableControl1');}

3. Selecione o novo botão Iniciar e altere a propriedade onClick para que aponte para progressBar2:

   handleVariableControlOnClick(this, 'form1:progressBar2', false)

4. Selecione o novo botão Cancelar e altere a propriedade onClick para que aponte para variableControl1 e progressBar2:

   handleStopControlOnClick('form1:variableControl1', 'form1:progressBar2')

5. Abra a exibição JSP da Page1. Localize o código de progressBar2, que aparece depois da linha </h:panelGrid>. Modifique as quatro propriedades de progressBar2 (ilustrado em negrito) para que façam referência a progressBar2.

   Amostra de código 4: Propriedades de progressBar2

   </h:panelGrid> <bp:progressBar binding="#{Page1.progressBar2}" failed="#{SessionBean1.taskMap.progressBar2.failed}" id="progressBar2" interval="#{SessionBean1.taskMap.progressBar2.interval}" onComplete="function() ... percentage="#{SessionBean1.taskMap.progressBar2.percentage}" percentageText="#{SessionBean1.taskMap.progressBar2.percentageText}" resumeOperation=...

    
   Devido a falta de espaço, várias linhas do código acima foram dividas em duas linhas.

6. Abra o arquivo SessionBean1.java e acrescente a seguinte linha ao método SessionBean1.init.

   taskMap.put("progressBar2", new SimpleTask("progressBar2", 241, 100, true));

   Este código adiciona uma nova instância SimpleTask a taskMap. A segunda barra de progresso monitora esta tarefa. O parâmetro true, que é passado ao construtor de SimpleTask, estabelece que a tarefa é indeterminada.

7. Construa e execute o projeto. Clique no botão Iniciar que você adicionou nesta seção para dar início à tarefa indeterminada.

   Um pequeno retângulo se move de esquerda à direita e uma mensagem de texto exibe "(tempo restante desconhecido)" até que a tarefa seja concluída.

8. Continue explorando o aplicativo clicando nos botões Pausar, Retomar e Cancelar. A figura abaixo mostra as duas barras de progresso em ação.

   Figura 4: Barras de progresso em ação

Fazendo mais #2: Simulando uma tarefa falha

1. Abra a exibição Design de Page1.

2. Altere a propriedade onClick do botão variableControl (o primeiro botão Iniciar) para que utilize true em vez de false:

   handleVariableControlOnClick(this, 'form1:progressBar1', true)

   Este código faz com que o parâmetro de solicitação chamado doomed seja enviado na solicitação em Ajax com o valor de true. O método startOrResumeTask no Bean da página recupera este parâmetro e o passa como um argumento para o método start de SimpleTask.

3. Altere a propriedade onClick do botão variableControl1 (o segundo botão Iniciar) para que utilize true em vez de false:

   handleVariableControlOnClick(this, 'form1:progressBar2', true)

4. Defina a propriedade onFail de progressBar1 como:

   function() {handleProgressBarOnFail('form1:variableControl');}

   A função handleProgressBarOnFail altera o texto do primeiro botão para "Iniciar" quando a tarefa falha, caso o usuário queira reiniciar a tarefa.

5. Defina a propriedade onFail de progressBar1 como:

   function() {handleProgressBarOnFail('form1:variableControl1');}

6. Construa e execute o projeto.

   Desta vez a primeira barra de progresso falha em 25%. A segunda barra de progresso também falha, embora a mensagem de texto não mostre a porcentagem porque, neste caso, a tarefa é indeterminada.

Fazendo mais #3: Alterando o estilo da barra de progresso

1. Abra a folha de estilo na janela Projetos clicando duas vezes no nó ExemploBarraProgresso > Páginas da Web > recursos > stylesheet.css.

2. Adicione o seguinte código em negrito, o qual altera a cor e a fonte da barra de progresso, e salve o arquivo.

   Amostra de código 5: Código da folha de estilo para definir a cor da barra de progresso

   .bpui_progressbar_portionComplete { background: blue !important; } .bpui_progressbar_portionRemaining { background: lightgrey !important; } .bpui_progressbar_percentageText { color: blue; font-size: 14px; font-weight: bold; } .bpui_progressbar_barArea { height: 9px !important; }

3. Abra a exibição Design de Page1 para ver as alterações da barra de progresso, ilustradas na figura abaixo.

   Figura 5: Barra de progresso estilizada

Resumo

A seguir estão as características de destaque do componente Barra de progresso:

• A barra de progresso oferece suporte a casos de uso determinado e indeterminado. A barra de progresso interpreta uma porcentagem de -1 como indeterminado.
• A barra de progresso oferece suporte às funcionalidades iniciar, pausar, retomar e parar nos eventos startOperation, pauseOperation, resumeOperation e stopOperation, que podem ser vinculados a métodos no Bean da página.
• A barra de progresso oferece suporte à tarefa falha com uma propriedade booleana failed que pode ser vinculada.
• A barra de progresso oferece suporte a código de script personalizado em várias propriedades avançadas, incluindo onComplete e onFail. Você pode consolidar o JavaScript personalizado em um arquivo .js e incluir um componente Script que faça referência ao arquivo.
• A barra de progresso oferece suporte ao estilo personalizado.

Veja abaixo algumas dicas sobre o uso do componente Barra de progresso, mostrado neste tutorial:

• Mantenha um mapa de objetos da tarefa no escopo da sessão, com uma barra de progresso diferente monitorando cada tarefa.
• Mantenha as tarefas de longa duração em segmentos separados. Você pode escrever um classe que representa uma tarefa específica usando SimpleTask.java como modelo. O SimpleTask.java conserva uma referência a um segmento, expõe métodos para iniciar (ou retomar), pausar ou cancelar a tarefa e tem propriedades que indicam o intervalo de análise, a porcentagem, o texto e se a tarefa falhou.

Consulte também:

• Fazendo download e importando Ajax e outros componentes
• Usando o componente Visualizador de mapa Ajax