Implementando dispositivos do Google na página inicial do Lotus Connections

Este artigo apresenta a especificação iWidget, desenvolvida pela IBM® e usada em vários produtos IBM, como o IBM Lotus® Connections 2.0. Ele descreve diferentes aspectos da especificação por meio de um exemplo prático que mostra como implementar um iWidget que age como wrapper para o dispositivo Google.

Vincent Burckhardt, Software Engineer, IBM

Vincent Burckhardt is a Software Engineer at the IBM Dublin Software Laboratory. Vincent has been working as part of the IBM Lotus Connections development team since 2007. You can reach him at vincent.burckhardt@ie.ibm.com.



02/Nov/2009 (Primeira publicação 02/Nov/2009)

Aviso: Este artigo abrange o release 2.0 do Lotus Connections. Consulte a segunda seção do artigo developerWorks, "Customizing Lotus Connections 2.5 with Lotus Widget Factory and Google Gadgets", para obter um resumo das etapas envolvidas em implementar um dispositivo Google no Lotus Connections 2.5. Observe que os detalhes de programação neste artigo ainda são válidos e oferecem um bom ponto de partida para os desenvolvedores que querem aprender mais sobre os detalhes das especificações iWidget.

O Lotus Connections 2.0 inclui uma nova página principal altamente customizável e extensível que dá aos usuários uma visualização agregada de informações de fontes variadas e diferentes. O recurso de página inicial se baseia em widgets e permite estender facilmente a plataforma de software social do Lotus Connections.

A página inicial lhe permite implementar e adicionar seus próprios widgets. Um iWidget é uma nova definição da IBM para os widgets. A especificação iWidget define a estrutura do widget. O padrão iWidget não é específico do Lotus Connections e é usado em outros produtos como o componente Lotus Mashups do IBM Mashup Center, permitindo assim escrever um widget uma só vez e executá-lo em diferentes produtos.

Este artigo lhe dá uma visão geral das etapas envolvidas na criação de um iWidget básico, na implementação e execução dele na página inicial. Como exemplo, este artigo demonstra como colocar o dispositivo Google em um iWidget. Após ler este artigo, também será possível criar widgets básicos que exibem qualquer conteúdo para o usuário.

As primeiras duas seções deste artigo lhe dão o conhecimento teórico necessário sobre a especificação iWidget e os dispositivos Google. A terceira seção lhe dá o passo a passo no processo de implementação de um iWidget que aja como um wrapper de dispositivo Google básico. Por fim, o artigo trata em mais detalhes de como adicionar aprimoramentos ao wrapper de dispositivo Google.

O processo de criação e implementação de um widget básico é relativamente simples. Este artigo supõe que você conheça as tecnologias de desenvolvimento da Web mais comuns, como JavaScript™, Java™ Platform, Enterprise Edition e XML. Um conhecimento intermediário é suficiente, visto que informações adicionais sobre áreas menos comuns, como o uso do JavaScript Dojo Toolkit, são incluídas no artigo conforme a necessidade.

Visão geral de widget de página inicial e especificações de iWidget

Esta seção lhe dá uma rápida visão geral da especificação do iWidget da IBM e lhe fornece com o mínimo de conhecimento teórico necessário para entender a parte prática apresentada mais adiante neste artigo. Este artigo não trata em muitos detalhes alguns dos recursos descritos nas especificações.

Anatomia do widget de página inicial

Antes de entrarmos nos detalhes técnicos, vamos dar uma olhada na anatomia do widget de página inicial. O widget de página inicial pode ser dividido em duas partes:

  • Cabeçalho. Contém o título do widget e alguns botões de ação representados por ícones (mover widget, editar, atualizar, ajuda e fechar).
  • Corpo. O corpo tem como borda um retângulo vermelho na figura 1 e é o local onde qualquer iWidget pode ser exibido para o usuário.
Figura 1. Esqueleto do widget de página inicial
Esqueleto do widget de página inicial

O desenvolvedor de widget tem controle quase completo sobre o conteúdo exibido no corpo do widget de página inicial. O widget pode exibir qualquer coisa encontrada em uma página da Web padrão. A única restrição é seguir o modelo de componente definido nas especificações do iWidget.

O tempo de execução da página inicial gera automaticamente a barra de cabeçalho. Há apenas um nível limitado de customização na barra de cabeçalho. É possível definir que ações são suportadas pelo iWidget. A página inicial oculta automaticamente os ícones das ações não suportadas pelo iWidget integrado. O administrador define o título do widget no momento da implementação.

Descritor do iWidget

O descritor é a parte principal de qualquer iWidget. É o local onde são mencionados os diferentes recursos suportados pelo widget. O descritor do iWidget pode ser escrito usando dois estilos: o microformato ou a sintaxe XML. Visto que a página inicial do Lotus Connections suporta apenas o estilo de definição XML, este artigo não descreve a sintaxe microformato. A Listagem 1 mostra um exemplo de um descritor XML Hello World do iWidget.

Listagem 1. Descritor XML Hello World do iWidget
<iw:iwidget name="helloWorld" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" 
iScope="HelloWorldWidgetClass">
   <iw:resource uri="helloworld.js" />			
   <iw:content mode="view">
      <![CDATA[
         <div id="root">
            Hello World! <br/>
               <button id="click" 
               onclick="iContext.iScope().onClickButton()">Click me!</button>
         </div>
      ]]> 
   </iw:content>     
</iw:iwidget>

Esse widget exibe a cadeia de caractere "Hello World" e um botão como mostrado na Figura 2.

Figura 2. Widget Hello World
Widget Hello World

As partes importantes do descritor XML no exemplo são:

  • atributo iScope. Esse atributo designa o nome da classe que contém a lógica do seu iWidget. Em geral é uma classe JavaScript definida em um dos recursos declarados em seu descritor XML (veja o próximo item nessa lista). A estrutura do iWidget instancia um objeto iScope para cada instância do seu iWidget.
  • tags iw:resource. Essas tags apontam para os diferentes recursos necessários para o seu iWidget. A página inicial suporta recursos em JavaScript e CSS (folha de estilo em cascata). Cada recurso declarado no descritor XML é procurado e avaliado. O atributo chamado "uri" (Identificador Uniforme de Recursos) se refere à localização do descritor XML. Nesse exemplo, declaramos apenas um recurso, um arquivo JavaScript chamado helloworld.js, localizado no mesmo diretório do arquivo descritor XML. tags iw:content. Esses tags definem a marcação de determinado modo. O fragmento de marcação é o código HTML renderizado pela página inicial para o iWidget quando está mostrando determinado modo. Nesse exemplo, o widget tem apenas um modo, visualização, que é o modo padrão.

A Listagem 2 mostra o código do arquivo helloworld.js que define a classe iScope do HelloWorldWidgetClass. Essa classe define apenas um método, onClickButton, que é o manipulador associado ao evento de clique do botão como definido na listagem 1. Quando os usuários clicam no botão, uma janela exibe a cadeia de caractere "Botão clicado".

Sintaxe Dojo

JavaScript é uma linguagem baseada em protótipo. Para facilitar as coisas para desenvolvedores acostumados com a programação orientada a objetos, o Dojo Toolkit fornece alguns auxiliares de classe orientados a objetos. O exemplo usa o método dojo.declare para a declaração do HelloWorldWidgetClass sem estender classe-pai (nulo) e tendo um único método (onClickButton).

Listagem 2. Conteúdo do helloworld.js
dojo.provide("HelloWorldWidgetClass");

dojo.declare(
   /* class name */                                            
   "HelloWorldWidgetClass",  
   /* parent class */ 
    null,
   /* methods and variables */ 
   {	
      onClickButton: function(){
         alert("Button clicked");
      }
   }
}

Usando os serviços fornecidos pela estrutura do iWidget

O objeto iContext é o ponto central usado para interagir com os serviços fornecidos pela estrutura do iWidget. A estrutura do iWidget injeta automaticamente um objeto chamado iContext na classe iScope do seu widget, como membro (this.iContext). Aproveite os recursos da estrutura do iWidget por meio do objeto iContext.

Além disso, o objeto iContext pode ser usado na marcação HTML do widget para chamar um método da instância associada da classe iScope, em um modo encapsulado. O exemplo na listagem 1 usa essa técnica para invocar o método onClickButton.

Encapsulação e iContext

A encapsulação é uma parte importante das especificações do iWidget. Cada iWidget exige encapsulação para evitar conflitos entre os recursos declarados por vários widgets abertos na mesma página ao mesmo tempo. A estrutura do iWidget o ajuda a encapsular seus widgets, mas também é preciso algum trabalho. Especialmente, como desenvolvedor do iWidget você precisa fazer o seguinte:

  • Declarar corretamente o escopo da classe do iWidget (iScope), como descrito na seção “Descritor do iWidget” neste artigo. Qualquer método ou variável usado pelo iWidget deve ser declarado dentro do iScope.
  • Evite o uso de funções e variáveis JavaScript globais nos recursos do seu iWidget porque não é possível garantir que outros widgets na página não declarem objetos com o mesmo nome, resultando em conflitos.
  • Interaja com a estrutura iWidget por meio do objeto iContext para obter o objeto de escopo adequado. No exemplo do Hello World, isso é feito por meio da instrução iContext.iScope().

ItemSets

Um ItemSet é um conjunto de pares nome-valor gerenciado pela estrutura do iWidget. Em geral, são usados para armazenar propriedades de um iWidget. Os ItemSets são manipulados no código da sua classe iScope por meio de métodos como getItemValue e getAllNames. (Para obter mais detalhes, consulte a especificação do iWidget.) Os ItemSets podem ser declarados no descritor XML, como mostrado na listagem 3.

Listagem 3. Declaração de ItemSets
<iw:itemSet id="itemSetId">
   <iw:item id="item1" value="value1" />
   <iw:item id="item2" value="value2" />
</iw:itemSet>

A seção final deste artigo, "Mais aprimoramentos para nosso wrapper de dispositivo", fornece um exemplo concreto de como usar um ItemSet para armazenar as preferências do wrapper de dispositivo Google que implementaremos neste artigo.

Outros serviços fornecidos pela estrutura do iWidget

Esta seção descreve outros serviços definidos nas especificações. Nem todos esses serviços são usados no nosso wrapper de dispositivo Google. Os recursos fornecidos pelas especificações são os seguintes:

  • Sistema de evento. Esse sistema permite que um iWidget acione e capture eventos. Na página inicial, esse mecanismo é usado para acionar eventos do seu iWidget quando o usuário seleciona uma das ações localizadas na barra de cabeçalho (como editar ou atualizar).
  • Módulo IO. Devido à mesma política de segurança de origem imposta pelo JavaScript (mais detalhes em http://www.mozilla.org/projects/security/components/same-origin.html), por padrão não é possível acionar solicitações Ajax em um domínio diferente do domínio da página inicial. Para fornecer a habilidade de enviar solicitações para outros domínios, a página inicial vem com um proxy Ajax. O módulo IO especificado pode ser usado para reescrever qualquer URL a fim de rotear novamente as solicitações Ajax por meio do proxy Ajax incorporado à página inicial. Também pode ser usado para localizar um recurso relativo à localização do descritor XML.
  • Sistema de conexão. Os usuários podem configurar dois ou mais widgets para trocarem dados usando o sistema de evento descrito no primeiro item desta lista. Observe que esse recurso não é ativado na página inicial do Lotus Connections e sim no Lotus Mashups.

Visão geral do dispositivo Google

Os dispositivos Google são pequenos aplicativos leves feitos em XML, HTML e JavaScript. Os dispositivos Google podem ser adicionados a contêineres de Dispositivos, como o iGoogle (a página inicial customizável do Google), Orkut, Google Maps ou Google Desktop. O desenvolvimento de dispositivos pode ser feito por qualquer pessoa. O Google fornece um diretório público no qual é possível publicar seus dispositivos.

Como acontece com o iWidgets, a parte principal de um dispositivo Google encontra-se no seu arquivo de definição XML. É possível encontrar mais detalhes sobre a anatomia de um descritor de dispositivo XML no capítulo "Escrevendo seus próprios dispositivos" no guia oficial do desenvolvedor. Resumidamente, a definição XML de um dispositivo especifica dois aspectos principais: a marcação do dispositivo (código HTML) e um conjunto de preferências.

Observe que atualmente há duas APIs distintas para dispositivos Google. Este artigo refere-se à API de legado que o Google suporta para dispositivos organizados.

Adicionando um dispositivo Google a qualquer Web site

O Google oferece a habilidade de executar dispositivos em qualquer página da Web, o que é conhecido como organização. É possível aproveitar essa capacidade para criar seu wrapper que permita exibir dispositivos Google na página inicial do Lotus Connections.

  • Para permitir a execução de um dispositivo fora de um contêiner de dispositivo, o Google fornece um serviço da Web que retorna uma saída formatada em JavaScript e HTML que é responsável pelo início das dependências do dispositivo e pela renderização dele. O serviço usa vários atributos de pedido, especialmente: URL para o arquivo de definição em XML do dispositivo Google.
  • Preferências do usuário definidas no descritor XML do dispositivo, às quais pode ser atribuído um valor passando o nome da preferência, precedido por _up, como parâmetro de solicitação do serviço. Os valores de preferência do usuário passados substituem os valores-padrão especificados na definição XML do dispositivo Google.
  • Preferências de exibição, como título, largura (l), altura (a) e estilo da borda.

A URL base do serviço Google é http://www.gmodule.com/ig/ifr. Aqui vai um exemplo de uma URL completa, incluindo os atributos de pedido do serviço Google que retorna o código JavaScript do dispositivo Date Time Google:

http://www.gmodules.com/ig/ifr?url=http://www.google.com/ig/modules/
datetime.xml&up_color=blue&up_firstDay=0&
w=320&h=136&output=js

Naquele exemplo, note os seguintes parâmetros:

  • A URL para o descritor XML do dispositivo Date Time é fornecida: a cadeia de caractere http://www.google.com/ig/modules/datetime.xml.
  • Preferências do usuário Color e firstDay (específicas desse dispositivo) estão configuradas como azul e 0 (que quer dizer domingo).
  • Os parâmetros de exibição largura (l) e altura (a) estão configurados como 320 px e 136 px.

Embora seja possível criar a URL para o serviço da Web manualmente, para incluir qualquer parâmetro de solicitação necessário, como melhor prática use a ferramenta Page Creator fornecida pelo Google. Essa ferramenta constrói facilmente a URL em uma forma gráfica. Essa ferramenta lhe permite especificar valores para as preferências do dispositivo e gerar a URL para o serviço, incluindo os parâmetros de solicitação corretos para as diferentes preferências definidas na definição XML do dispositivo. Para usar a ferramenta Page Creator, execute as seguintes etapas:

  1. Vá até a biblioteca de dispositivos Google.
  2. Escolha um dispositivo e então selecione a opção "Add to your webpage". Customize as configurações do dispositivo e os valores das preferências do usuário. A página mostra uma visualização do dispositivo com os novos valores.
  3. Após terminar as configurações, selecione a opção "Get the code".
  4. A página mostra o código a incluir. A URL do serviço da Web é a cadeia de caractere no atributo src da tag de script.

OBSERVAÇÃO: Como você já deve ter notado, a URL retornada pelo Page Creator deixa escapar alguns caracteres especiais. Por exemplo, o caractere de "e comercial" (&) escapa como &. Visto que a URL foi feita para ser colocada em um documento HTML ou XML, o escape dos caracteres especiais é necessário para ter certeza de que o documento permaneça válido.


Fazendo o wrapper do dispositivo Google em um descritor iWidget

Agora, estamos prontos para escrever um wrapper para o dispositivo Date Time Google. A Figura 3 mostra o resultado após a implementação na página inicial.

Figura 3. Dispositivo Google Date Time implementado na página inicial
Dispositivo Google Date Time implementado na página inicial

O método exposto nesta seção é o mesmo para qualquer outro dispositivo Google, com apenas uma linha de código a modificar para indicar o dispositivo apropriado.

Como primeira abordagem, seu wrapper continua básico: o único objetivo dele é renderizar o dispositivo na página inicial. A seção final deste artigo se concentra em acrescentar recursos a esse wrapper, como uma visualização de edição onde os usuários possam modificar os valores das preferências do dispositivo.

Método para renderizar o dispositivo e o descritor XML

Para renderizar um dispositivo Google na página inicial, chame o serviço de Web do Google mencionado na seção “Adicionando um dispositivo Google a qualquer Web site” com os parâmetros de solicitação apropriados. A resposta, uma mistura de HTML e JavaScript, é inserida em um elemento de script. O elemento de script fica em um documento HTML carregado na parte IFRAME do iWidget.

IFRAME

Um IFRAME é um quadro sequencial que contém outro documento. É um elemento HTML padrão, sem nenhuma relação específica com as especificações iWidget. O atributo src de um IFRAME indica a URL do documento a carregar.

A Listagem 4 mostra o esqueleto de código do descritor XML do seu iWidget. A Listagem 5 contém um fragmento do documento JSP (gadgetWrapper.jsp) com o elemento de script indicando o serviço do Google.

Listagem 4. Definição para wrapper de iWidget em um dispositivo Google
<iw:iwidget name="googleDateTime" 
xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget">
   <iw:content mode=”view”>
   <![CDATA[
      <iframe scrolling="auto" width="100%" height="300px" frameborder="0" 
      src="/gadgetWrapper/gadgetWrapper.jsp?url=<google gadget xml url>">
      </iframe>
   ]]> 
   </iw:content>     
</iw:iwidget>
Listagem 5. gadgetWrapper.jsp
<%
    StringBuffer url = new StringBuffer();
    url.append("http://www.gmodules.com/ig/ifr?");
    url.append(request.getQueryString());
%>

<script src="<%= url.toString() %>"></script>

Como se pode ver, o iWidget renderiza um elemento HTML de IFRAME que indica a página JSP gadgetWrapper. A página JSP é responsável pelas seguintes tarefas:

  • Obter a parte de cadeia de consultas da URL. Essa é uma subcadeia após o caractere ? na URL. Nesse caso, a parte de cadeia de consultas de /gadgetWrapper/gadgetWrapper.jsp?url=<google gadget xml url> é url=<google gadget xml url>.
  • Criar a URL do serviço Google acrescentando a cadeia de consultas à raiz de contexto do serviço em gmodule.com.
  • Configurar o atributo src do elemento de script para apontar para o serviço Google com os parâmetros de dispositivo apropriados a partir da cadeia de consultas.

Se não usa Java, você pode adaptar o comportamento descrito pela página JSP na linguagem do lado de serviço da sua opção (PHP ou .NET, por exemplo). A parte importante é simplesmente configurar o elemento de script com a URL para o serviço Google.

Observe três aspectos neste ponto:

  • Poderíamos ter inserido o elemento de script diretamente na definição XML do código do iWidget. Alguns conflitos entre o código JavaScript retornado pelo serviço Google e a estrutura do iWidget, contudo, o forçam a escolher a solução de isolamento da tag SCRIPT em um elemento IFRAME.
  • O serviço Google aceita o valor de html para o parâmetro de solicitação de saída (em vez de js). Esse resultado de gerar o código HTML pode ser inserido diretamente no IFRAME mostrado na listagem 4, sem ter de usar a solução da página JSP. Essa solução, porém, não inclui os botões "gadget powered by Google" e "+Google" sob o dispositivo Google, o que viola os termos de serviço do dispositivo Google.
  • Não há lógica de apoio a esse iWidget. Portanto, a definição XML não contém nenhuma referência aos recursos iScope ou JavaScript. É possível adicionar lógica ao seu iWidget na seção final deste artigo.

Dispositivo Google Date Time

A Listagem 6 mostra o código do descritor XML para um iWidget que cria o wrapper do dispositivo Date Time Google mostrado na figura 3. O atributo src do elemento IFRAME apontam para a URL do descritor XML desse dispositivo localizado em http://www.google.com/ig/modules/datetime.xml. Ele também configura os parâmetros de usuário específicos desse dispositivo, como cor de fundo (laranja) e primeiro dia da semana (0, que significa domingo). Como já descrito, é possível inspecionar a definição XML do dispositivo para descobrir que parâmetros de usuário estão disponíveis para determinado dispositivo, ou se pode usar a ferramenta Page Creator do Google.

Listagem 6. Definição para wrapper de iWidget no dispositivo Google Date Time
<iw:iwidget name="googleDateTime"  
xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget">
    <iw:content mode="view">
    <![CDATA[
       <iframe scrolling="auto" width="100%" frameborder="0"
 	   src="/gadgetWrapper/gadgetWrapper.jsp?url= 
http://www.google.com/ig/modules/datetime.xml&amp;up_color= 
orange&amp;up_firstDay=0&amp;title=&amp;border= 
&amp;output=js"></iframe>
         ]]>
      </iw:content>
</iw:iwidget>

Para obter a URL do dispositivo Google da sua escolha a fim de inserir o atributo src (origem) do IFRAME, siga as etapas descritas na seção "Adicionando um dispositivo Google a qualquer Web site". Nesse ponto, as preferências do usuário devem ser codificadas permanentemente como parte da cadeia de solicitação de URL. Na última seção do artigo, vamos modificar essa codificação de modo que os usuários possam alterar as preferências.

OBSERVAÇÃO: Na listagem 6, note que também configuramos dois parâmetros de exibição (título e borda) para valores vazios. Essa configuração lhe permite renderizar o dispositivo Google sem título e sem estilo de borda.


Implementando o dispositivo Google na página inicial

Implementamos um iWidget na página inicial com duas etapas principais:

  1. Implementar o descritor XML e todos os recursos do iWidget em um servidor da Web.
  2. Registrar o widget no catálogo da página inicial indicando a URL do descritor XML do iWidget implementado.

Implementar o iWidget

A implementação do iWidget em um servidor da Web é flexível porque o usuário não fica amarrado a nenhuma tecnologia de servidor específica. Por exemplo, seu iWidget pode ser um projeto PHP e implementado em um servidor PHP. Também é possível implementar seu widget como projeto de Java Platform, Enterprise Edition e implementá-lo em um contêiner de servlet/Java Platform, Enterprise Edition como o WebSphere® Application Server ou Tomcat. A escolha é sua. Observe que, se não for usado o contêiner da Java Platform, Enterprise Edition, será preciso adaptar a página JSP descrita na seção "Método para renderizar o dispositivo e o descritor XML".

As etapas a seguir dão detalhes do processo de criação do projeto iWidget em Eclipse como projeto da Web e de exportá-lo como arquivo EAR. O arquivo EAR pode então ser implementado em um contêiner da Java Platform, Enterprise Edition.

OBSERVAÇÃO: É preciso ter o plug-in de ferramentas da Web instalado para criar um projeto da Web no Eclipse. Faça o download dele em http://download.eclipse.org/webtools/downloads/. A versão Java Platform, Enterprise Edition do Eclipse inclui esse plug-in.

Vamos criar seu projeto e arquivo EAR para serem implementados. No Eclipse, primeiro crie o projeto:

  1. Vá em File - New - Project.
  2. Selecione Web - Dynamic Web Project na janela e clique em Next.
  3. Digite o nome do projeto à sua escolha, por exemplo gadgetWrapper. Selecione um tempo de execução alvo se quiser implementar o projeto diretamente do Eclipse; se não, selecione None.
  4. Selecione a opção "Add Project to an EAR" para dizer ao Eclipse para criar e associar um projeto EAR a esse Projeto da Web.
  5. Selecione Next para obter a última janela. Não modifique nenhuma das configurações padrão. Clique em Finish para criar o projeto da Web.

Nesse ponto, estamos prontos para trabalhar no projeto.

A seguir, adicione o descritor iWidget XML ao projeto:

  1. Sob WebContent, crie um novo arquivo XML clicando à direita no nome de diretório e selecionando New - File. Digite gadgetWrapper.xml como nome do arquivo.
  2. Abra o arquivo no Eclipse dando um clique duplo nele e depois cole o código mostrado na listagem 6. Se não for possível editar o arquivo, confirme se a guia de origem está selecionada. Veja a figura 4.
  3. Salve o arquivo.
Figura 4. gadgetWrapper.xml sendo editado no Eclipse
gadgetWrapper.xml sendo editado no Eclipse

Repita essas etapas para adicionar o descritor XML bem como o JSP definido na listagem 5 do projeto. A versão integral desse arquivo encontra-se dentro do gadgetWrapper.ear na seção Download deste artigo.

A seguir, gere o arquivo EAR para implementar em um contêiner da Java Platform, Enterprise Edition como o WebSphere Application Server:

  1. Selecione o projeto EAR associado ao projeto da Web criado anteriormente.
  2. Dê um clique com o botão direito do mouse e selecione Export - EAR file.
  3. Selecione um destino no seu disco.

É isso! O arquivo EAR que contém os recursos do iWidget e o arquivo XML está pronto para ser implementado em qualquer contêiner de Java Platform, Enterprise Edition.

Nesse ponto, é possível implementar o arquivo EAR no contêiner da Java Platform, Enterprise Edition como implementaria qualquer outro arquivo EAR.

OBSERVAÇÃO: O IFRAME mostrado na listagem 6 faz referência à página JSP (mostrada na listagem 5) com a raiz de contexto configurada como /gadgetWrapper. Talvez seja preciso adaptar essa configuração dependendo da raiz de contexto real sob a qual o arquivo EAR for implementado. Na seção final deste artigo, nós lhe mostramos como se livrar dessa limitação usando o módulo IO do iWidget.

Registrar o widget no catálogo da página inicial

A página inicial fornece uma interface com o usuário de administração para adicionar novos widgets ao banco de dados de catálogo. Observe que apenas usuários com direitos de administrador podem adicionar novos widgets ao catálogo da página inicial.

Siga estas etapas para adicionar seu iWidget usando a interface com o usuário de administração da Web da página inicial:

  1. Efetue login com uma conta de administrador na página inicial.
  2. Selecione a guia Administration na página inicial, como mostrado na figura 5.
    Figura 5. Guia Administration
    Guia Administration
  3. Selecione a opção "Add another widget" na parte inferior direita da página.
  4. O formulário mostrado na figura 6 é exibido. Digite o nome do título e a localização do descritor XML do iWidget.
    Figura 6. Página inicial de Administradores
    Página inicial de Administradores
  5. Digite um título para o widget. O título digitado será exibido na barra de título do widget; por exemplo, o título pode ser Data e Hora do Google.
  6. Digite a localização do descritor XML. Esse campo depende de onde foi implementado seu widget na seção anterior “Implementar o iWidget”.
  7. Os outros campos de texto são opcionais e podem ser deixados em branco. É possível indicar um ícone, por exemplo. O ícone é exibido na barra lateral quando o widget está fechado.
  8. Deixe todas as caixas em branco. São necessários apenas para widgets que lidam com outros recursos do Lotus Connections, que não é o caso para seu iWidget com wrapper para dispositivo Google.
  9. Clique em Save.

É possível encontrar mais detalhes sobre as opções de administração para gerenciar widgets no Lotus Connections v2 Information Center.


Mais aprimoramentos para nosso wrapper de dispositivo

Esta seção descreve como adicionar mais recursos ao iWidget básico. Em especial, podemos adicionar a habilidade de os usuários modificarem algumas das preferências declaradas na definição do dispositivo Google. Observe que as preferências do usuário são manuseadas pelo próprio dispositivo Google visto que são declaradas como elementos <UserPrefs> na definição XML do dispositivo Google. O objetivo é permitir que os usuários escolham valores para essas preferências e os passem para o serviço Google.

Para permitir que os usuários customizem o dispositivo Google em wrapper, faça o seguinte:

  1. Implemente uma visualização de edição para o iWidget na qual os usuários customizem os valores das preferências declaradas na definição do dispositivo Google.
  2. Passe os valores inseridos para o serviço Google apresentado na seção “Adicionando um dispositivo Google a qualquer Web site”, acima. Isso é feito passando os novos valores de preferência para o serviço Google como parte da URL.

Por meio dessas etapas, também é possível ver um exemplo prático do uso de vários conceitos apresentados neste artigo, como ItemSets, os mecanismos de encapsulação fornecidos pela estrutura do iWidget e um sistema de evento.

Preferências do dispositivo Date Time

Nesta seção, modificamos nosso iWidget existente para permitir que os usuários determinem as preferências do dispositivo Google Date Time. Observe que as etapas a seguir são as mesmas de qualquer outro dispositivo Google; assim, não é difícil adaptar os conceitos apresentados aqui para customizar qualquer dispositivo da página inicial.

Em geral, há dois modos de obter lista das preferências do usuário de um dispositivo Google:

  • Inspecione o descritor XML do dispositivo e procure os elementos <UserPrefs>.
  • Use a ferramenta Page Creator. As preferências são alistadas sob a seção de configurações do Dispositivo.

Inspecionando a definição XML do dispositivo Date Time, vemos que há duas preferências de usuário:

  • Cor de fundo
  • Primeiro dia da semana no calendário

Esses dois parâmetros têm uma lista de valores permitidos definidos como enumerações. A Listagem 7 mostra um fragmento do código de enumeração da definição XML do dispositivo para a preferência do usuário de cor. A preferência do primeiro dia da semana também usa o mesmo tipo de enumeração. No restante desta seção, deixaremos os usuários escolher um dos valores alistados nessas enumerações para cada uma de duas preferências.

Listagem 7. Trecho da definição XML do dispositivo Date Time mostrando a enumeração de preferência do usuário para cor
<UserPref name="color" datatype="enum" default_value="blue" 
display_name="__MSG_color__">
   <EnumValue value="blue" display_value="__MSG_blue__"/>
   <EnumValue value="green" display_value="__MSG_green__"/>
   <EnumValue value="orange" display_value="__MSG_orange__"/>
   <EnumValue value="pink" display_value="__MSG_pink__"/>
   <EnumValue value="purple" display_value="__MSG_purple__"/>
   <EnumValue value="red" display_value="__MSG_red__"/>
   <EnumValue value="yellow" display_value="__MSG_yellow__"/>
</UserPref>

Adicionando lógica ao iWidget

O iWidget apresentado antes é um widget básico que contém apenas algumas marcações, mas não inclui a lógica JavaScript. Nesse caso, a URL para o serviço Google foi codificada permanentemente de forma direta na seção de marcação (iw:content) do iWidget. Agora, queremos criar uma URL baseada dinamicamente nos valores inseridos pelos usuários. Para executar essa etapa, é preciso escrever um código de apoio que implemente a lógica para geração de cadeia URL. O primeiro objetivo aqui é mover a localização da URL de serviço Google da marcação HTML do iWidget para o código de apoio nestas etapas:

  1. Remova a URL da marcação removendo o atributo src do IFRAME em uma definição XML do iWidget. A parte de conteúdo deve se parecer agora ao código mostrado na listagem 8.

    Listagem 8. Marcação da visualização do wrapper do iWidget
    <iw:content mode="view">
       <![CDATA[
          <iframe id="frame" scrolling="auto" width="100%" 
          frameborder="0"></iframe>
       ]]> 
    </iw:content>
  2. Crie um arquivo JavaScript que contenha a lógica de apoio. Como já descrito, a lógica é implementada em uma classe JavaScript chamada iScope. No Eclipse, o processo de criar e adicionar o arquivo JavaScript segue as mesmas etapas usadas para adicionar o arquivo de definição XML ao projeto, como descrito na seção “Implementar o iWidget”. Nome do arquivo JavaScript: googleGadgetWrapper.js. A Listagem 9 mostra o código a adicionar a esse arquivo.

    Listagem 9. Primeira versão do googleGadgetWrapper.js
    dojo.provide("GoogleGadgetWrapper");
    
    dojo.declare("GoogleGadgetWrapper", null, {	
    
       onLoad: function(){
       },
    	
       onview: function(){
       // get the frame DOM object declared in the widget markup
       var frame = this.iContext.getElementById("frame");	
    
       // get the URL to the JSP page location without having to hard-code
       // the context root in the code. For instance, if the context root  
       // after deployment is /gadgetWrapper/, jspLocation is set to
       // /gadgetWrapper/gadgetWrapper.jsp
       var jspLocation = this.iContext.io.rewriteURI("gadgetWrapper.jsp");
    	
       // set the src attribute of the iframe		
       frame.src = jspLocation + "?url=http://www.google.com/ig/modules/datetime.xml&
       title=&border=&output=js&w=400";
       }
    }

Vamos repassar o código da listagem 9:

  1. A estrutura do iWidget envia um iEvent chamado Load para o widget. Sem entrar em muitos detalhes sobre o mecanismo de manuseio de eventos, o que é preciso saber é isso resulta em invocar um método chamado + <nome do evento> do iScope no seu iWidget. Nesse caso, o mecanismo resulta na invocação do método onLoad.
  2. A estrutura iWidget carrega o modo padrão (visualização) do widget. Um modo é carregado em duas etapas:
    • A marcação (o elemento de conteúdo do descritor XML) correspondente ao modo é mostrada ao usuário. Observe que é declarada a marcação do seu widget dentro desse modo na listagem 7 (modo=atributo "view").
    • Em iEvent com o nome do modo é enviado para o widget. No seu caso, isso resulta em ser invocado o método onview.

O resultado é que os métodos onLoad e onview são invocados automaticamente pela estrutura quando o widget é colocado na página.

Além disso, note que usamos o método rewriteURI do módulo IO fornecido pela estrutura do iWidget (por meio do objeto iContext). Essa abordagem lhe permite obter a localização real do arquivo JSP sem ter de incluir no código a raiz de contexto do projeto. Não é possível saber, no momento do desenvolvimento, qual é a raiz de contexto sob a qual o iWidget será implementado visto que esse valor pode ser modificado pelo administrador no momento da implementação.

A lógica backend precisa ser conectada à definição XML do iWidget. A conexão é feita em duas etapas:

  1. Adicione uma tag de elemento de recurso para indicar o arquivo JavaScript recém-adicionado ao projeto:
    <iw:resource uri="googleGadgetWrapper.js" />
  2. Configure o atributo iScope no elemento de tag iw:widget do descritor XML do iWidget para indicar a classe JavaScript definida em googleGadgetWrapper.js. Visto que o nome da sua classe JavaScript é GoogleGadgetWrapper, a tag iw:widget agora deve ter a seguinte aparência:
    <iw:iwidget name="googleDateTime"
    xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" iScope="GoogleGadgetWrapper">

É isso! Agora o atributo src do IFRAME é configurado dinamicamente na inicialização do widget. Nesse ponto, não há diferença de comportamento do widget para os usuários. Agora, estamos prontos para gerar a parte de consulta da URL ao serviço Google.

Armazenando os parâmetros e gerando a URL para o serviço Google

Vimos uma forma fácil de gerar e modificar a URL para o serviço Google antes de configurá-la para IFRAME. Nesta seção, modificaremos a URL para adicionar valores das preferências de usuário em três etapas:

  1. Armazene os valores das preferências de usuário do dispositivo Google em um ItemSet do seu iWidget. Use um ItemSet para armazenar as preferências pelas seguintes razões:
    • Ele fornece um armazenamento de dados conveniente que pode ser usado em diferentes partes do seu código para determinar e obter valores escolhidos pelos usuários.
    • Ele lhe permite persistir as preferências entre sessões de usuário no servidor da página inicial. Esse ponto é implementado na seção “Persistindo as preferências de usuário”, mais adiante neste artigo.

    Para isso, vamos modificar a definição XML do iWidget para declarar o ItemSet. Chame o ItemSet de userPrefs. A Listagem 10 mostra o fragmento de código das duas preferências de usuário que queremos recuperar mais adiante na visualização de edição.

    Listagem 10. ItemSet armazenando as preferências de usuário do dispositivo Date Time
    <iw:itemSet id="userPrefs">
       <iw:item id="color" value="green" />
       <iw:item id="firstDay" value="0" />
    </iw:itemSet>

    Observe que também é possível especificar um valor-padrão para cada preferência do usuário (verde e 0 para domingo).

  2. É preciso implementar o mecanismo para gerar dinamicamente a URL para o serviço Google a partir dos valores armazenados no ItemSet. Para isso, adicione um método adicional chamado getQueryString à classe iScope do iWidget. A Listagem 11 mostra o código do método.
    Listagem 11. Método retornando a cadeia de consultas da preferência ItemSet
    getQueryString: function(){
       // get the ItemSet object
       var userPrefs = this.iContext.getItemSet("userPrefs");
    		
       // get the names ("id") of the items as an array		
       var prefNames = userPrefs.getAllNames();
    		
       // initialize an empty JavaScript object used as a map		
       var params = {};
    		
       // populate the params map with the user parameters
       dojo.forEach(prefNames, function(name) { 
          // we need to prefix the name with "up_" to pass it to the Google Service 
          as discussed in “Google gadget overview” part
          var upName = "up_" + name;
    	params[upName] = userPrefs.getItemValue(name);		
       });
    		
      // generate the string from the params map
      return dojo.objectToQuery(params);		
    }

    Esse método retorna uma cadeia de caractere que codifica os valores das preferências do usuário. Por exemplo, para o dispositivo Date Time, ele retorna a cadeia de caractere up_color=green&up_firstDay=0. Essa cadeia de caractere pode ser usada diretamente para criar a URL no serviço Google, que retorna a marcação correspondente para o dispositivo Google.

  3. É preciso modificar o método onview apresentado na listagem 8 para chamar getQueryString a fim de criar a URL para o serviço Google, antes de configurá-la para o atributo src do iFrame. A Listagem 12 mostra a nova versão do onview.
    Listagem 12. Nova versão do onview com geração dinâmica da cadeia URL, incluindo os valores da preferência do usuário
    onview: function(){   
       var frame = this.iContext.getElementById("frame");	
    	
       var query = this.getQueryString();
    
       var jspLocation = this.iContext.io.rewriteURI("gadgetWrapper.jsp");
    			
       frame.src = jspLocation + "?url=http://www.google.com/ig/modules/datetime.xml&
       title=&border=&output=js&w=400&" + query;
    }

Implementando a visualização de edição

Nesse ponto, implementamos o mecanismo para armazenar as preferências de usuário e para gerar a URL para o serviço Google, incluindo os valores de preferência. Nessa subseção, preencha o ItemSet a partir dos valores digitados pelos usuários. Execute essa tarefa em três etapas:

  1. Implemente uma interface gráfica que permita aos usuários escolher os valores das preferências. Para isso, implemente a marcação da visualização de edição. Essa implementação é a visualização com as quais os usuários interagem quando a visualização de edição está ativada. No caso do dispositivo Date Time Google, estamos interessados em permitir que os usuários customizem a cor de fundo e o primeiro dia da semana. Portanto, simplesmente implemente a visualização de edição como formulário com duas listas suspensas com os valores permitidos para as duas preferências de usuário.

    A Figura 7 mostra a visualização de edição do seu iWidget com wrapper para o dispositivo Date Time.

    Figura 7. Visualização de edição do wrapper iWidget
    Visualização de edição do wrapper iWidget

    A Listagem 13 mostra um fragmento de código de marcação como parte do descritor XML do iWidget.

    Listagem 13. Código da visualização de edição do widget <iw:content mode="edit">
       <![CDATA[
       <table>
       <tr>
          <td>Color: </td>
    	<td>
          <select id="color">
    	   <option value="blue">Blue</option>
    	   <option value="green">Green</option>
    	   <!—other options here 
    	</select>
    	</td>
       </tr>
       <tr>
      --- same principle as for the color drop-down list here -->
       </tr>
       </table>
       <br/>
       <input id="saveButton" type="button" value="Save" 
       onclick="iContext.iScope().onSave()" />
       <input id="cancelButton" type="button" value="Cancel" 
       onclick="iContext.iScope().onCancel()" />
       ]]> 
    </iw:content>

    Observe o seguinte na listagem:

    • A marcação é colocada em um elemento iw:content com o atributo de modo ajustado para editar.
    • O método iContext.iScope() é usado para assegurar a encapsulação correta.
    • A marcação é simplesmente uma tabela HTML com duas listas suspensas e dois botões (Save e Cancel).
  2. Adicione métodos à lógica de apoio do seu iWidget para preencher o ItemSet a partir de entradas de usuários. Para isso, é preciso implementar a lógica de apoio para os botões (botões onSave() e onCancel()). A Listagem 14 mostra o código do método onSave() invocado quando os usuários clicam no botão Save.
    Listagem 14. Código para o método onSave()
    onSave: function(){
       // get ItemSet object
       var userPrefs = this.iContext.getItemSet("userPrefs"); 
    
       // set the item values from the drop-down list selections
       userPrefs.setItemValue("color", 
       this.iContext.getElementById("color").value);
       userPrefs.setItemValue("firstDay", 
       this.iContext.getElementById("firstDay").value);
    		
       // switch back to the view mode (widget normal view with the gadget)		
       this.iContext.iEvents.fireEvent("onModeChanged", 
       null, "{newMode: 'view'}");		
    }

    O método onSave() determina os novos valores para as duas preferências em ItemSet a partir das entradas de usuários. A última linha do método salvo é usada para retornar ao modo de visualização do widget. Para isso, acione um evento onModeChanged no widget. Esse evento é interpretado pela estrutura como uma solicitação para mudar o modo atual do widget de edição para visualização. Seguindo essa etapa, o mecanismo sobre manuseio de modo descrito na seção “Adicionando lógica ao iWidget” é invocado.

    O objetivo do botão Cancel é retornar ao modo de visualização sem salvar as preferências no ItemSet. Assim, onCancel() é apenas a última linha do onSave(), que aciona o evento onModeChanged.

  3. Registre o modo de edição no descritor XML do seu iWidget. Para isso, adicione o atributo supportedMode ao elemento iw:iwidget do seu descritor XML como mostrado aqui:
    <iw:iwidget name="googleDateTime"
    xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
    iScope="GoogleGadgetWrapper" supportedModes="edit view">

    Quando se faz essa mudança e reimplementa o widget, os usuários veem um ícone de edição na barra de cabeçalho do widget na página inicial, como mostrado na Figura 8.

Figura 8. Botão de edição na barra de cabeçalho do iWidget
Botão de edição na barra de cabeçalho do iWidget

Quando os usuários clicam no botão Edit, o tempo de execução da página inicial aciona o evento onModeChanged no iWidget integrado. Esse evento faz a estrutura renderizar a visualização de edição e invocar um método chamado onedit no iScope do iWidget. Para terminar, a listagem 15 mostra como adicionar lógica no método onedit para configurar as duas listas suspensas na visualização de edição com os valores armazenados em ItemSet.

Listagem 15. Configuração do método onedit para as listas suspensas da visualização de edição com os valores armazenados
onedit: function(){
   var userPrefs = this.iContext.getItemSet("userPrefs"); 
   this.iContext.getElementById("color").value = userPrefs.getItemValue("color");
   this.iContext.getElementById("firstDay").value = userPrefs.getItemValue("firstDay");
}

Persistindo as preferências de usuário

Atualização: O Lotus Connections 2.5 agora suporta a persistência das preferências do usuário de acordo com as especificações do iWidget. Embora as informações nesta seção ainda sejam válidas visto que o Lotus Connections 2.5 oferece compatibilidade com versões anteriores, aconselha-se o uso do modo padrão do iWidget. Consulte a seção "Especificação do iWidget v1.0 no Lotus Connections 2.5” do artigo "Customizing Lotus Connections 2.5 with Lotus Widget Factory and Google Gadgets” para obter mais detalhes.

O aprimoramento final do seu wrapper do iWidget é persistir as preferências de usuário armazenadas no ItemSet. Ao executar essa tarefa, as customizações feitas pelo usuário não são perdidas. O tempo de execução da página inicial fornece dois métodos (_save e _load) para persistir um ItemSet do lado do servidor.

OBSERVAÇÃO: Essa implementação é uma extensão da estrutura iWidget específica da página inicial; não funciona em outros contêineres iWidget, como o Lotus Mashups.

Os métodos _save e _load aceitam um URI como parâmetro, que é o local onde o ItemSet persiste. A serialização usada por esses métodos para codificar e decodificar o ItemSet está fora do escopo deste artigo. Só é preciso saber que a página inicial fornece um serviço (Servlet) que aceita e retorna a cadeia de caractere serializada localizada em handleUP?Act=XXX&FId=XXX, com Act assumindo SaveCustomization e LoadCustomization como valores e FId sendo o ID de iWidget.

OBSERVAÇÃO: Na página inicial, é possível obter o ID do widget a partir do iContext (iContext.widgetId). Essa variável é específica da página inicial e não faz parte da especificação iWidget.

A Listagem 16 mostra o código do método onLoad (chamado logo após o widget ser colocado na página) que é responsável por preencher o userPrefs ItemSet com os valores da camada de persistência. Observe que, se não for persistido nenhum valor (o que significa que o usuário não editou e salvou as preferências para esse widget), os valores-padrão são aqueles definidos no descritor XML do iWidget (listagem 9).

Listagem 16. Carregando as preferências do usuário a partir da camada de persistência da página inicial
onLoad: function(){
   var userPrefs = this.iContext.getItemSet("userPrefs");
   userPrefs._load("handleUP?Act=LoadCustomization&FId=" + this.iContext.widgetId);
}

Por fim, é preciso salvar os valores ItemSet. Execute essa etapa quando os usuários clicarem no botão Save na visualização de edição. Assim, é preciso chamar o método _save no objeto userPrefs do método onSave, logo antes de acionar o evento onModeChanged. Consulte o código de origem no arquivo EAR na seção Download deste artigo.


Conclusão

Este artigo abrangeu as diferentes etapas de implementação de um wrapper básico do iWidget para dispositivo Google na página inicial do Lotus Connections. Além da implementação do próprio wrapper, este artigo apresentou-lhe alguns dos recursos fornecidos pela estrutura do iWidget por meio de um exemplo concreto. Após ler este artigo, você deve saber o suficiente sobre conceitos como descritor XML, ItemSets, modos e eventos para conseguir escrever widgets básicos para página inicial. Além disso, também poderá continuar implementando aprimoramentos no wrapper Google, como, por exemplo, permitir que os usuários insiram a localização do descritor do dispositivo na visualização de edição do iWidget.


Agradecimentos

O autor gostaria de agradecer a Luis Benitez por guiá-lo em todo o processo de escrita de um artigo para developerWorks. O autor gostaria de agradecer a Adrian Spender por ter sugerido que ele escrevesse um artigo sobre esse tópico.

Além disso, o autor gostaria de agradecer a Luis, Adrian e Li Xu por terem revisado este artigo e dado sugestões para melhorá-lo.


Download

DescriçãoNomeTamanho
Código de amostragadgetWrapper.ear4KB

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=442550
ArticleTitle=Implementando dispositivos do Google na página inicial do Lotus Connections
publish-date=11022009