Este artigo fornece informações para usar o JavaScript™ na criação, visualização, edição e remoção de documentos em um aplicativo IBM® Lotus® Domino®. Ele também fornece uma introdução geral ao JavaScript no XPages e mostra onde e como anexar JavaScript na interface com o usuário do XPages.

Robert Perron, Technical Writer, IBM

Robert Perron é escritor técnico da IBM Lotus em Littleton, Massachusetts. Ele desenvolve documentação para Lotus Notes e Domino desde o início da década de 1990, concentrando-se primariamente na programabilidade. Ele desenvolveu a documentação para o LotusScript e para os objetos Java Domino e coescreveu o livro "60 Minute Guide to LotusScript 3 - Programming for Notes 4". Ele é o autor de vários artigos para o LDD Today (developerWorks) e The View. Atualmente, sua atenção está voltada ao XPages.



16/Mar/2010

Nota do editor: Conhece muito sobre esse tópico? Deseja compartilhar seu conhecimento? Participe hoje do programa de wiki do software IBM Lotus.

Introdução

O desenvolvimento no XPages conta, geralmente, com dois elementos de design de legado: formulários para definir dados e visualizar dados do relatório. Entretanto, eles não são um requisito absoluto. Pode-se usar JavaScript para mover dados entre os controles e os armazenamentos de dados do Lotus Domino. O JavaScript não é difícil.

Talvez você não queira adotar a abordagem JavaScript por estas razões:

  • Formulários e visualizações permitem a definição visual de estruturas complexas.
  • Quando os formulários e visualizações necessários forem colocados juntos, o desenvolvimento segue bem. Por exemplo, ligar um campo de um formulário a um controle em um XPage é uma simples questão de arrastar o campo até o controle.
  • Caso esteja colocando o XPages em um aplicativo existente do IBM Lotus Domino Designer, pode-se querer alavancar os formulários e visualizações existentes.

Projetar formulários e visualizações pode apresentar uma curva de aprendizado se o Lotus Domino Designer for uma novidade para você. Mesmo tendo conhecimento sobre o Lotus Domino Designer, os formulários e visualizações necessitam que você saia do paradigma XML. Você acabará lidando com @functions e LotusScript®.

Este artigo fornece informações para usar o JavaScript na criação, visualização, edição e remoção de documentos em um aplicativo IBM Lotus Domino. Ele mostra como ligar os dados desses documentos a controles no XPage.

Este artigo também fornece uma introdução geral ao JavaScript no XPages. O que confere poderes ao JavaScript no XPages é o acesso a uma extensa biblioteca para a manipulação fácil de ambientes de usuários e de armazenamentos de dados backend. Caso esteja familiarizado com o LotusScript, você sabe a respeito do NotesSession, NotesDatabase, NotesDocument, e muitos outros objetos Domino. Esses mesmos objetos estão disponíveis para o JavaScript, mas seu emprego no código de origem é mais simples.

Finalmente, este artigo mostra onde e como anexar JavaScript na interface com o usuário (UI) do XPages. Pode-se, por exemplo, utilizar JavaScript para retornar um valor para um campo computado. É possível anexar o JavaScript a um evento, por exemplo, o evento onclick de um botão. Pode-se, por exemplo, usar JavaScript para definir uma propriedade verdadeira ou falsa para propriedade visual de um controle.


Hello World

Inicie o Lotus Domino Designer e crie um aplicativo. Sob o nome do aplicativo, do lado esquerdo (o navegador), clique com o botão direito em XPages e selecione New XPage. Dê o nome de main ao XPage e clique em OK. Essa ação exibirá um editor no meio da página e um conjunto de controles do lado direito. Se os controles não aparecerem ou, por alguma razão, a guia for fechada, pode-se obtê-los de volta selecionando Window - Show Eclipse Views - Controls.

Para a primeira operação de design nessa nova página, arraste um Computed Field de Controls (talvez seja necessário rolar para baixo) para a paleta central. Como alternativa, pode-se clicar duas vezes em Computed Field e ele será mostrado no editor. Com foco no campo computado e guia Properties selecionada, a janela deve se parecer como a da Figura 1.

Figura 1. XPage com controle de Campo Computado
XPage with Computed Field control

Clique para ver a imagem maior

Figura 1. XPage com controle de Campo Computado

XPage with Computed Field control

Agora, definiremos um valor para esse campo computado. Selecione Value (em Properties) e selecione JavaScript. É possível digitar um script diretamente na janela exibida, mas clicaremos no botão Script Dialog no lado direito da janela, como mostra a Figura 2.

Figura 2. Selecionando JavaScript para definir um valor
Selecting JavaScript to set a value

Observe os objetos globais do lado esquerdo do editor de scripts, como mostra a Figura 3. (Se a guia Reference não estiver selecionada, selecione-a. Se Global Objects não estiver selecionado, selecione-o no menu suspenso sob Libraries.) Role a lista para baixo e clique duas vezes em session. Ela será exibida no editor. Digite um ponto e espere um segundo. Uma lista de métodos é exibida. Role para baixo e clique duas vezes em getCommonUserName(): string.

Figura 3. Assistente de conteúdo para o objeto global de sessão
Content assist for session global object

Os objetos globais são pontos de entrada para a hierarquia de objeto disponível para o XPages JavaScript em um servidor Lotus Domino. O objeto de sessão dá acesso à sessão Lotus Domino e seus objetos subjacentes. Abra session sob Reference do lado esquerdo, como mostra a Figura 4. Você verá os mesmos métodos vistos no editor quando o ponto foi digitado depois da sessão.

Figura 4. Expansão de um objeto de sessão no painel Reference
Expansion of session object in Reference pane

Clique para ver a imagem maior

Figura 4. Expansão de um objeto de sessão no painel Reference

Expansion of session object in Reference pane

Agora, a partir da lista suspensa sob Libraries, selecione Domino. Role para baixo e abra NotesSession. Você verá novamente a mesma lista mostrada na Figura 5. O objeto global de sessão é, na verdade, um objeto Lotus Domino NotesSession para o usuário atual.

Figura 5. Expansão de um Domino NotesSession no painel Reference
Expansion of Domino NotesSession object in Reference pane

Clique para ver a imagem maior

Figura 5. Expansão de um Domino NotesSession no painel Reference

Expansion of Domino NotesSession object in Reference pane

Faça os ajustes no código para que ele se pareça com:

return "Hello " + session.getCommonUserName()

A palavra-chave de retorno está implícita, então o código pode ser escrito da seguinte maneira:

"Hello " + session.getCommonUserName()

Feche o editor de script e salve o que foi editado clicando em OK.

Pode-se visualizar o que foi feito selecionando-se Design - Preview no navegador da Web (ou Preview no atalho do navegador da Web) e selecionando um navegador. (Primeiramente, deve-se adicionar Anonymous ao ACL do aplicativo com, pelo menos, privilégios de autor.) Para a visualização, o Lotus Domino inicia um mini-servidor em seu computador.

O URL da página visualizada é o do formulário http://localhost/foo.nsf/main.xsp. Pode-se digitar esse URL diretamente no navegador caso a visualização já tenha sido feita anteriormente e se o Lotus Domino Designer ainda estiver sendo executado, pois o mini-servidor deve estar sendo executado. Se o aplicativo estiver no servidor Lotus Domino, use o nome do servidor, não localhost.

No Lotus Domino Designer 8.5.1, pode-se também selecionar Design - Preview in Notes (no atalho Preview in Notes).

Para configurar seu aplicativo para iniciar no Lotus Notes® com um XPage, selecione Application Properties na parte inferior do navegador. Quando as propriedades do aplicativo forem exibidas, selecione a guia Launch. Defina a opção Launch para abrir o XPage designando (cliente padrão) e especifique o XPage.

Veremos mais tarde como ir de um XPage para outro após iniciar o aplicativo. Caso esteja usando um elemento de design que não seja XPage, pode-se aplicar um URL do Lotus Notes do formulário mostrado na seguinte fórmula (esta amostra é uma ação na visualização).

@URLOpen("notes:///foo.nsf/main.xsp?OpenXPage")

Em um servidor, insira o nome do servidor:

@URLOpen("notes://myserver/foo.nsf/main.xsp?OpenXPage")

Há mais um ponto de interesse antes de mergulhar nos dados. Na parte inferior do editor, selecione Source, como mostra a Figura 6. O XML que define seu XPage### será exibido. Pode-se editar o XML diretamente, ao invés de se trabalhar no editor visual. Selecione Design para retornar ao editor visual.

Figura 6. XML fonte para um XPage
Source XML for an XPage

Dados Hello

Colocaremos um outro campo computado no XPage abaixo do primeiro. Pressione Enter e então clique duas vezes ou arraste sobre um controle do campo computado. Clique em Value sob Propriedades, clique em JavaScript e clique no botão Open Script Dialog.

Você está novamente no editor de scripts. Não é preciso abrir o editor de scripts. Como mencionado anteriormente, pode-se editar um script na janela sob o botão JavaScript, como mostra a Figura 2. Pode-se também editar o script no XML usando a guia Source. Entretanto, o editor de script fornece mais espaço e possui as guias Reference e Outline no lado esquerdo.

Role para baixo sob Global Objects, na guia Reference e clique duas vezes no banco de dados, como mostra a Figura 7. Quando ele for exibido no editor, digite um ponto depois dele e espere a lista de métodos ser exibida. Aqui está uma outra variável global muito útil. Ela cria um objeto NotesDatabase para o banco de dados atual, ou seja, o aplicativo contém um XPage.

Figura 7. Assistente de conteúdo para o objeto global do banco de dados
Content assist for database global object

Clique duas vezes em getAllDocuments(): NotesDocumentCollection. Ao digitar um outro ponto, uma lista de métodos que pertence ao objeto NotesDocumentCollection será exibida, um deles é getCount(): int. Clique duas vezes nesse método e digite um novo ponto. Dessa vez, a lista de métodos é para a classe de cadeia de caractere, que está na biblioteca padrão. Clique duas vezes em toFixed(): string. Neste momento, o script será:

database.getAllDocuments().getCount().toFixed()

Esse script faz uma contagem de todos os documentos no banco de dados atual como uma cadeia de caractere. Modifique o script para que ele se pareça com:

return "Number of documents in database: " + database.getAllDocuments().getCount().toFixed()

Clique em OK, salve e visualize. Para um novo aplicativo, a visualização não mostra nenhum documento no banco de dados.

Para sua informação (não faz parte do aplicativo amostra), aqui está o código que obtém o número de documentos em um banco de dados especificado. O primeiro parâmetro para session.getDatabase é o nome de um servidor no qual zero significa o sistema local. O segundo parâmetro é o nome do aplicativo referente ao diretório de dados do Lotus Notes.

return session.getDatabase(null, "fooA.nsf").getAllDocuments().getCount().toFixed()

A Listagem 1 mostra o código que obtém os nomes de todos os aplicativos NSF no diretório local do Lotus Notes. O objeto retornado por session.getDbDirectory é do tipo NotesDbDirectory. Seus métodos getFirstDatabase e getNextDatabase retornam objetos do tipo NotesDatabase.

Listagem 1. Código para a obtenção dos nomes de todos os aplicativos NSF
	var list = "";
	var dir = session.getDbDirectory(null);
	var db = dir.getFirstDatabase(1247); // 1247 = type DATABASE
	while (db != null) {
		if (!list.isEmpty()) list = list + ", ";
		list = list + db.getFileName();
		db = dir.getNextDatabase();
	}
	return list

Criando um documento

A primeira tarefa ao se criar um documento é a obtenção de dados do usuário do XPage. Criaremos dois campos para esse propósito, um é uma cadeia de caractere e outro é numérico.

  1. Crie uma tabela de 2 por 2. Procure pelo controle da tabela sob Container Controls.
  2. Na primeira coluna, coloque os controles de rótulo cujos rótulos sejam assunto e número.
  3. Na segunda coluna, coloque os controles da caixa de edição.

O editor visual deve ser parecido com o mostrado na Figura 8.

Figura 8. Caixas de edição para assunto e número.
Edit boxes for subject and number

A idéia de uma caixa de edição é permitir que usuários digitem algo nelas. Mas, como acessar esses dados? Caso se estivesse fazendo um backup do XPage com um formulário Lotus Domino, cada caixa de edição deveria ser ligada a um campo no formulário. Essa abordagem é brevemente coberta no final deste artigo. Para objetivos de programação, você ligará cada campo a uma variável global.

Foque-se na primeira caixa de edição, então selecione Data, sob Properties. Selecione Advanced. Selecione Scoped Variable na lista suspensa. No campo Parameter, selecione Request Scope na lista. Finalmente, invente um nome para a variável. Chamaremos a variável de subject. Consulte a Figura 9.

Figura 9. Ligando um campo a uma variável com escopo definido.
Binding a field to a scoped variable

Essa variável está disponível para a página quando o servidor processa a página por solicitação do URL. Ela perde escopo e libera memória quando o servidor termina de processar a solicitação URL. Na lista suspensa pode-se ver que há quatro tipos de variáveis com escopo definido. Em ordem decrescente de escopo, elas são escopos do aplicativo, da sessão, da visualização e da solicitação.

Da mesma maneira, ligue a segunda caixa de edição ao número da variável chamada Request Scope. Deve-se fazer uma especificação adicional aqui. É crucial que se altere o tipo de exibição para Number, pois você quer tratar essa entrada como dados numéricos. Consulte a Figura 10.

Figura 10. Ligando um campo a uma variável com um escopo definido do tipo numérico
Binding a field to a scoped variable of type Number

Clique para ver a imagem maior

Figura 10. Ligando um campo a uma variável com um escopo definido do tipo numérico

Binding a field to a scoped variable of type Number

Agora iremos direto ao assunto e criaremos um documento. Não é difícil!

Coloque um controle Button abaixo das caixas de edição. Altere o rótulo para criar um documento.

Selecione a guia Events. Do lado esquerdo estão os eventos que podem ser usados com esse controle. Você quer a opção onclick, que está marcada como padrão. Então selecione Script Editor e certifique-se de que a guia Server está selecionada (ela está selecionada como padrão). Consulte a Figura 11.

Figura 11. Especificando um evento para um botão.
Specifying an event for a button

Pode-se inserir o script diretamente na janela ou clicar no botão Open Script Dialog que está do lado direito. A ação abre o editor de script modal com a guia de referência do lado esquerdo.

A Listagem 2 mostra o script.

Listagem 2. JavaScript para a criação de um documento
	var doc = database.createDocument();
	doc.replaceItemValue("subject", requestScope.subject);
	doc.replaceItemValue("number", requestScope.number)
	doc.save();
	requestScope.subject = null;
	requestScope.number = null

A primeira linha cria um objeto do NotesDocument. As duas linhas seguintes preenchem o objeto com valores do item baseados nas variáveis globais ligadas aos controles da caixa de edição. Observe que a especificação é o escopo, seguido por um ponto seguido pelo nome da variável. Espera-se que os usuários tenham inserido valores nessas caixas. Observe também que o assunto e número estão entre aspas. Eles foram criados por você e fornecem nomes para os itens no documento. Não acontece nada no armazenamento de dados até que o método para salvar tenha sido executado. Finalmente, as variáveis com escopo definido são limpas para que os valores antigos não apareçam na interface com o usuário e não interfiram em eventos futuros.

Salve e visualize a página. Insira um assunto e um número e então clique em Create document. Clicar no botão para criar o documento faz com que um URL com a informação da página seja enviado ao servidor do Lotus Domino (ou ao mini-servidor no caso de uma visualização). O servidor processa o código do evento e envia uma página revisada de volta ao navegador (ou ao cliente Lotus Notes). Ao repetir isso algumas vezes, pode-se ver que a contagem de documentos aumenta.


Visualizando documentos

Ao ver a contagem de documentos aumentar, sabe-se que algo está acontecendo. Seria útil obter alguns detalhes. O método comum para se visualizar dados no legado do Lotus Domino é com o elemento de design View. O XPages possui um controle de visualização que incorpora um elemento de design de visualização. Entretanto, você usará o controle de tabela de dados e um JavaScript.

Foque-se na parte debaixo do botão. Em Container Controls, clique duas vezes ou arraste um controle Data Table. Sob Properties, selecione JavaScript e insira um script que retorne uma coleta de documentos. Uma segunda especificação importante neste exemplo é o nome de coleta, rowdoc, fornecido. Consulte a Figura 12.

Figura 12. Especificando um controle Data Table
Specifying a Data Table control

Clique para ver a imagem maior

Figura 12. Especificando um controle Data Table

Specifying a Data Table control

A tabela de dados age na coleta específica. Esse exemplo retorna uma coleta de todos os documentos no banco de dados. Há muitas maneiras de modificar programaticamente as coletas, incluindo pesquisa de texto completa, para retornar um subconjunto de documentos.

Clique com o botão direito dentro da tabela de dados e, então, selecione Insert Column ou Append Column. Observe que a coluna exibida possui três linhas. As linhas da parte superior e inferior são naturalmente estáticas e contêm uma cópia de qualquer coisa que você tenha colocado nelas. Utilize a linha da parte superior como um cabeçalho; insira um controle Label cujo rótulo seja um assunto.

A linha do meio é essencialmente um controle Repeat. Os controles de repetição são valiosos. No caso de uma tabela de dados, o controle Repeat fornece um número variável de linhas dependendo do número de objetos na coleta básica. Cada linha age em um membro da coleta. Esse exemplo usa um NotesDocumentCollection de todos os documentos no banco de dados atual. Cada membro da coleta é um objeto do tipo NotesDocument. Lembra-se do nome de coleta rowdoc? Esse nome aponta para o objeto NotesDocument associado à linha atual, ou seja, a linha onde o usuário está.

Foque-se na linha do meio. Em Core Controls, clique duas vezes ou arraste um controle Computer Field. Sob Properties, selecione Value. Para o valor, selecione JavaScript e insira um script. O script utiliza o método getItemValueString do rowdoc (um objeto NotesDocument, como mencionado anteriormente) para obter o valor do item assunto. Consulte a Figura 13.

Figura 13. Especificando um valor para uma linha em repetição.
Specifying a value for a repeating row

Uma informação sobre o assistente de conteúdo: Infelizmente, digitar um ponto após rowdoc não traz a lista de métodos pois o editor não conhece o tipo de rowdoc. Deve-se ter cuidado e inserir os nomes dos métodos de maneira precisa usando o painel de referência ou a documentação. No painel de referência, pode-se clicar duas vezes para exibir um método no editor. Como alternativa, pode-se forçar funcionamento do assistente de conteúdo inserindo uma linha de código propícia que identifica o tipo. No código abaixo, o assistente de conteúdo reconhece que rowdoc é do tipo NotesDocument e traz seus métodos.

rowdoc:NotesDocument == null;
return rowdoc.

Uma visualização mostra uma tabela com uma coluna, o assunto como o cabeçalho da coluna e uma linha contendo o valor do assunto para cada documento no banco de dados atual.

Foque-se na tabela de dados (não na coluna), clique com o botão direito e selecione Append Column. Siga o mesmo processo anterior para criar uma coluna para o item número. Desta vez, o script para o campo computado é:

return rowdoc.getItemValueDouble("number")

Finalmente, adicione uma terceira coluna para exibir a data de modificação. Aqui o script é:

return rowdoc.getLastModified()

Agora uma visualização exibe três colunas com assunto, número e última data de modificação.


Editando e excluindo

Forneceremos uma maneira de editar documentos existentes.

Inclua uma outra coluna na tabela de dados. Clique duas vezes ou arraste um controle Button até a linha do meio e edite seu rótulo. Selecione a guia Events, certifique-se de que onclick e a guia Server estejam selecionados e selecione Script Editor. Insira o seguinte script:

sessionScope.docUnid = rowdoc.getUniversalID();
requestScope.subject = rowdoc.getItemValueString("subject");
requestScope.number = rowdoc.getItemValueDouble("number")

Esse código define variáveis globais para o valor do ID universal do documento mais os valores dos dois itens. Uma variável sessionScope é necessária para o ID universal pois seu uso se estende sobre duas solicitações.

As duas últimas variáveis estão ligadas às caixas de edição. Quando os usuários clicam no botão de edição, o URL vai até o servidor Lotus Domino. O servidor envia de volta uma página com as duas caixas de edição preenchidas pelos valores dessa linha da tabela de dados. Os usuários podem editar esses dados. Na Figura 14, o usuário acabou de clicar no botão de edição para a segunda linha.

Figura 14. Obtendo uma linha de dados para edição
Getting a row of data for editing

Clique para ver a imagem maior

Figura 14. Obtendo uma linha de dados para edição

Getting a row of data for editing

Agora é necessário um botão para fazer a substituição. Coloque esse botão ao lado do botão Create a document e coloque nele o rótulo Replace document. Pode-se copiar e colar o botão Create document como início. Para seu evento onclick, use o código JavaScript na Listagem 3. Esse código é o mesmo para o botão Create document, exceto pela primeira linha, que obtém um documento existente usando um ID universal ao invés de criar um documento.

Listagem 3. JavaScript para a substituição de valores em um documento
	var doc = database.getDocumentByUNID(sessionScope.docUnid);
	doc.replaceItemValue("subject", requestScope.subject);
	doc.replaceItemValue("number", requestScope.number)
	doc.save();
	requestScope.subject = null;
	requestScope.number = null

Pode-se também querer adicionar um botão Cancel com o seguinte código. Ele apaga o conteúdo das caixas de edição sem alterar nada no banco de dados.

requestScope.subject = null;
requestScope.number = null

Opcionalmente, para uma melhor usabilidade, adicione a seguinte linha de código ao evento onclick para o botão de edição.

sessionScope.editMode = true

Adicione a seguinte linha de código ao evento onclick para os botões Replace document e Cancel.

sessionScope.editMode = false

Essa adição faz com que a variável global editMode seja verdadeira somente quando os usuários estão editando. Caso contrário, ela não será inicializada ou será falsa. Acesse as propriedades para os três botões acima da tabela. Vá até a propriedade Visible. Clique no losango e então selecione Compute value. Para o botão Create document, use o seguinte script:

sessionScope.editMode != true

Para os botões Replace document e Cancel, use este script:

sessionScope.editMode == true

Agora, quando os usuários acessarem o documento, somente o botão Create document estará visível. Quando os usuários clicarem no botão de edição, o botão Create document desaparecerá e os outros dois botões serão mostrados.

A remoção de um documento é fácil. Insira uma outra coluna e coloque um botão na linha do meio. Rotule o botão remove. Para seu evento onclick, use o seguinte código:

rowdoc.remove(true)

Os códigos vistos até agora estão todos do lado do servidor. O código é executado após o navegador ou o cliente Lotus Notes passar a página para o servidor. O JavaScript é padrão, com poucas exceções. Porém, ele tem acesso a bibliotecas adicionais, em particular, a biblioteca do Domino Objects.

Pode-se também fornecer um JavaScript do lado do cliente. O código é executado após o navegador ou o cliente Lotus Notes passa a página para o servidor. O JavaScript é padrão para o cliente que está sendo usado e tem acesso ao Web DOM padrão.

Pode-se fornecer tanto scripts do lado do servidor quanto do lado do cliente para o mesmo evento. O script do lado do cliente pode prevenir a execução da operação do lado do servidor retornando um falso.

Nesse aplicativo amostra, pode-se utilizar um script do lado do cliente para confirmar a remoção de um documento. Mais uma vez, vá até o evento onclick para o botão de remoção. O código do servidor já está lá. Como mostra a Figura 15, selecione a guia Client, selecione Script Editor e insira este código:

return window.confirm(“Do you really want to delete this document?”)

Figura 15. Código do lado do cliente para um evento
Client-side code for an event

Quando usuários clicam no botão, o script do lado do cliente exibe uma janela de confirmação. Ao clicar em OK, um "verdadeiro" retorna e o script do lado do servidor é executado. Clicando em Cancel, um "falso" retorna e o código do lado do servidor é executado.


Usando páginas múltiplas

Trataremos de um cenário mais típico no qual os usuários enviam dados de páginas separadas. Antes de iniciar, pode-se querer fazer uma cópia do XPage principal.

Crie um XPage chamado create. Corte a tabela de 4 por 4 com as caixas de edição do XPage principal e cole-a no XPage create. Copie (não corte) os botões Create document e Cancel do XPage principal e cole-os no XPage create. No XPage create, coloque focus no botão Create document e altere seu rótulo para Submit. Para ambos os botões, altere a propriedade Visible para que eles estejam sempre visíveis. Consulte a Figura 16.

Figura 16. XPage para criar um documento
XPage for creating a document

As caixas de edição estão corretas dessa maneira, mas o código do botão deve ser ajustado. Abra o editor de script para o evento onclick para o botão Submit. As primeiras quatro linhas, que criam o documento, funcionam da mesma maneira. As duas linhas que apagam o conteúdo das caixas de edição não são necessárias pois você sairá dessa página. Finalmente, uma linha deve ser adicionada para levar os usuários de volta até a página principal. O código se parece com a Listagem 4.

Listagem 4. JavaScript para criar um documento e abrir uma outra página
	var doc = database.createDocument();
	doc.replaceItemValue("subject", requestScope.subject);
	doc.replaceItemValue("number", requestScope.number)
	doc.save();
	context.redirectToPage("main")

O objeto global de contexto é do tipo XSPContext na biblioteca XSP.

Para o botão Cancel, deve-se remover o código existente e substituí-lo pela última linha do script Submit. Ou seja, você fará com que os usuários retornem à página principal. Um outro modo de executar essa tarefa é usando uma ação simples. Vá até o evento onclick para o botão. Selecione Simple Actions (clique em OK no caso de um aviso aparecer) e então selecione Add Action. Na janela exibida, certifique-se que ação é Open Page; selecione-a no menu suspenso, se necessário. Para o nome da página a ser aberta, selecione main no menu suspenso. Então clique em OK. Consulte a Figura 17.

Figura 17. Ação simples para abrir uma outra página
Simple action for opening another page

Para sua informação, há uma terceira maneira para retornar à página principal. Defina o botão como do tipo Cancel e remova qualquer código de evento. Selecione a guia Properties para a página e defina Next page (se a atualização falhar) para main.

Agora retorne ao XPage principal e foque-se no botão Create document. Remova o código para o evento onclick. (Certifique-se de remover o código antes de proceder.) Com esse botão, pode-se criar um XPage. Pode-se usar JavaScript com esse código.

context.redirectToPage("create")

Ou pode-se usar uma ação simples.

Visualize a página. Clique em Create document. Digite alguns dados. Experimente o botão Submit. Experimente o botão Cancel.

A seguir, crie um XPage chamado replace. Copie tudo do XPage create e cole no replace. Para esta página, deve-se alterar a ligação das caixas de edição com as variáveis sessionScope, pois os dados são passados através das solicitações.

O botão Submit deve ser ajustado. Ao invés de se criar um documento, quer-se obter um documento existente usando um ID universal definido no XPage principal. As variáveis globais devem ser alteradas para sessionScope. Após usar as variáveis sessionScope, zere-as como mostrado na Listagem 5.

Listagem 5. JavaScript para substituir valores em um documento e abrir uma outra página
	var doc = database.getDocumentByUNID(sessionScope.docUnid);
	doc.replaceItemValue("subject", sessionScope.subject);
	doc.replaceItemValue("number", sessionScope.number);
	doc.save();
	sessionScope.subject = null;
	sessionScope.number = null;
	context.redirectToPage("main")

De volta no XPage principal, altere o botão de edição para usar variáveis sessionScope para definir os valores dos itens atuais e abrir o XPage substituto, como mostra a Listagem 6.

Listagem 6. JavaScript para abrir uma página para editar um documento existente
	sessionScope.docUnid = rowdoc.getUniversalID();
	sessionScope.subject = rowdoc.getItemValueString("subject");
	sessionScope.number = rowdoc.getItemValueDouble("number");
	context.redirectToPage("replace")

Agora temos três páginas: main, create e replace. Os usuários abrem o aplicativo para main. Ao clicar no botão Create document, eles são enviados até a página create com caixas de edição em branco. Uma ação de enviar ou cancelar os envia de volta à página principal. Um clique no botão edit os envia à página replace com as caixas de edição preenchidas. Novamente, uma ação de enviar ou cancelar os envia de volta à página principal.


Rich text

O Rich text requer atenção especial. Não se pode somente definir e obter variáveis. Caso não entenda imediatamente o código nesta seção, pode-se usá-lo como uma receita.

No formulário create, arraste ou clique duas vezes em um controle Rich Text debaixo das caixas de edição e acima dos botões. Ajuste seu tamanho conforme desejado. Selecione a guia Data sob Properties, selecione Advanced e ligue esse controle a uma variável Request Scope chamada body.

Vá até o evento onclick para o botão Submit. Ajuste o script para que fique igual ao da Listagem 7. O novo código se inicia na linha 4 com a criação de um objeto NotesStream e termina na linha 8 com o fechamento desse objeto. A variável global requestScope.body, ligada ao controle rich text, é do tipo com.ibm.xsp.http.MimeMultipart. Seu método getHTML obtém o conteúdo de um controle rich text como XML. Então crie um item rich-text no backend como um objeto NotesMIMEEntity e use o conteúdo XML do controle para definir seu valor. O objeto NotesStrem é necessário como um intermediário.

Listagem 7. JavaScript para a criação de um documento com rich text
	var doc = database.createDocument();
	doc.replaceItemValue("subject", requestScope.subject);
	doc.replaceItemValue("number", requestScope.number)
	var stream = session.createStream();
	stream.writeText(requestScope.body.getHTML());
	var entity = doc.createMIMEEntity("body");
	entity.setContentFromText(stream,"text/html;charset=UTF-8", 1725);
	stream.close()
	doc.save();
	context.redirectToPage("main")

Para obter dados do backend para um controle rich-text, pode-se usar o método getContentAsText do NotesMIMEEntity. Na página replace, adicione o controle Rich Text debaixo das caixas de edição como foi feito na página create, mas ligue-o a uma variável sessionScope chamada body e não a uma variável requestScope. Na página principal, vá até o evento onclick para o botão de edição. Ajuste o código para que ele seja igual ao da Listagem 8. O novo código está entre as linhas 4 e 6. Obtenha um documento rich-text a partir do backend como um objeto NotesMIMEEntity, então use seu método getContentAsText para definir o valor do controle rich-text. O copy na linha 6 é necessário, mais tarde, na página replace para um comparativo.

Listagem 8. JavaScript para abrir uma página para editar um documento existente contendo rich text
	sessionScope.docUnid = rowdoc.getUniversalID();
	sessionScope.subject = rowdoc.getItemValueString("subject");
	sessionScope.number = rowdoc.getItemValueDouble("number");
	var entity = rowdoc.getMIMEEntity("body");
	sessionScope.body = entity.getContentAsText();
	sessionScope.bodyCopy = sessionScope.body;
	context.redirectToPage("replace")

Na página replace, o botão Submit deve estar aditado para escrever o valor do controle rich-text mas somente se o valor do controle tiver sido alterado. Pode-se copiar e colar códigos do XPage create, mas tome cuidado na hora de fazer as mudanças necessárias. Veja a Listagem 9.

Listagem 9. JavaScript para substituir valores em de um documento com rich text
	var doc = database.getDocumentByUNID(sessionScope.docUnid);
	doc.replaceItemValue("subject", sessionScope.subject);
	doc.replaceItemValue("number", sessionScope.number)
	if(!sessionScope.body.toString().equals(sessionScope.bodyCopy.toString())) {
		var stream = session.createStream();
		stream.writeText(sessionScope.body.getHTML());
		var entity = doc.getMIMEEntity("body");
		entity.setContentFromText(stream,"text/html;charset=UTF-8", 1725);
		stream.close();
	}
	doc.save();
	sessionScope.subject = null;
	sessionScope.number = null;
	sessionScope.body = null;
	context.redirectToPage("main")

Fazendo isso com um formulário

Para completar e comparar, vamos redesenhar as páginas create e replace ligando os dados de um formulário e não usando JavaScript. Caso queira salvar seu projeto existente, faça cópias do XPages.

Clique com o botão direito em Forms no navegador e selecione New Form. Dê o nome de main ao novo formulário e clique em OK. Use Create - Field para criar três campos, do seguinte modo: Name: subject e Type: Text; Name: number e Type: Number; e Name: body e Type: Rich Text. Consulte a Figura 18.

Figura 18. Formulário com três campos
Form with three fields

É possível colocar os campos em qualquer parte do formulário. Neste exemplo, a aparência não importa. Salve o formulário.

Abra o XPage create. Com foco no próprio XPage, selecione XPage sob Properties e especifique Next page (sucess or cancel) como main. Essa seleção significa que a página principal é enviada ao navegador (ou cliente Lotus Notes) quando se clica no botão Submit ou Cancel (a ser explicado). Consulte a Figura 19.

Figura 19. Especificando a próxima página para abrir
Specifying next page to open

Selecione Data e adicione uma fonte de dados Lotus Domino Document. Especifique current para o aplicativo, main para o formulário e Create document para a ação padrão. O nome document1 pode ser deixado como está. Essa abordagem faz do formulário uma fonte de definições de dados para o XPage. Consulte a Figura 20.

Figura 20. Especificando um formulário com fonte de dados para um XPage.
Specifying a form as a data source for an Xpage

Clique para ver a imagem maior

Figura 20. Especificando um formulário com fonte de dados para um XPage.

Specifying a form as a data source for an Xpage

Agora o foco deverá ser na primeira caixa de edição. Selecione Simple data binding. Especifique a fonte de dados como document1 e ligue o controle ao assunto. Essa referência é para o campo sujeito no formulário principal. Faça o mesmo para a segunda caixa de edição, mas ligue-a ao number. Consulte a Figura 21. Pode-se também fazer essa ligação arrastando o campo da paleta de dados no lado direito do controle.

Figura 21. Ligando um controle a um campo em um formulário
Binding a control to a field on a form

Foque-se no controle rich-text. Ligue-o ao body. Seus controles XPage agora estão ligados aos dados definidos no formulário.

Altere o primeiro botão para ser do tipo Submit. Sob Events, certifique-se de que todos os códigos de evento foram removidos. Nenhum código é necessário para um botão desse tipo. Consulte a Figura 22.

Figura 22. Especificando um botão do tipo Submit.
Specifying a button of type Submit

Clique para ver a imagem maior

Figura 22. Especificando um botão do tipo Submit.

Specifying a button of type Submit

Altere o segundo botão para ser do tipo Cancel. Da mesma maneira, certifique-se de que todos os códigos de evento ou ação simples sejam excluídos.

Esse processo toma conta da página create. Ele substitui o JavaScript por ligações de formulário e tipos especiais de botão.

A página replace é redefinida de maneira similar. As ligações de dados para os controles são as mesmas da página create. Os botões são os mesmos. A única diferença é que a ação padrão para os dados XPage é Edit document.

Agora vá até a página principal. Exclua o código do evento onclick para o botão edit e especifique-o novamente como uma ação simples Open Page. Você quer abrir a página replace no modo de edição do documento. Compute o documento a ser editado usando a variável rowdoc (da tabela de dados) para se obter o UNID do documento que você quer editar. (Então é necessário um pouco de JavaScript.) Consulte a Figura 23.

Figura 23. Ação simples para abrir uma página e editar um documento
Simple action for opening a page to edit a document

O botão Create document, que abre a página create, pode ser deixado como está. É possível excluir os botões Replace document e Cancel.

Agora você está pronto para começar. O código JavaScript para criar e substituir documentos foi eliminado. Essas funções agora são implementadas pelo desenho e ligação dos dados a um formulário, usando botões do tipo Submit e Cancel e configurando a próxima página após a ação de enviar ou cancelar. O botão remove é deixado como está pois a solução JavaScript é a mais simples possível.

Pode-se também criar um elemento de design para visualização e usá-lo como base para um controle View no lugar da tabela de dados. As funções dos botões edit e remove podem ser trabalhadas nessa visualização.


Conclusão

O Lotus Domino Designer mantém seus dados backend como notas de documento no aplicativo Lotus Domino (o arquivo NSF) usando protocolos Lotus Notes. O acesso tradicional se dá através de elementos de design chamados formulários e visualizações. Os formulários definem tanto os dados quanto como um documento é exibido. As visualizações são os meios de exibição e ação nas coletas de documentos.

Agora, o elemento de design XPages encapsula toda a interface com o usuário. Para definir dados, pode-se escolher ligar os controles XPages a campos nos formulários. Como alternativa, pode-se acessar os dados por meio de JavaScript ou objetos Domino. Da mesma maneira, pode-se usar uma visualização para exibir e acessar agregados de documentos, mas também se pode fazer esse design com tabelas de dados e JavaScript.

Recursos

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Lotus
ArticleID=474951
ArticleTitle=XPages sem enrolação
publish-date=03162010