Criação dos seus próprios gadgets

O guia Primeiros passos fornece a você uma introdução sobre como usar gadgets. A próxima etapa é a criação dos seus próprios gadgets. Este documento ensina como fazer isso.

Sumário

  1. Etapas básicas
  2. Anatomia de um gadget
    1. Definição de conteúdo
    2. Definição das preferências do usuário
    3. Definição das preferências do gadget
  3. Lembre-se: Gadgets são públicos
  4. O que fazer depois

Etapas básicas

Aqui estão as etapas básicas que você deve seguir para criar e implementar um gadget:

  1. Use qualquer editor de texto para escrever as especificações do seu gadget e guarde essas informações em um servidor da web público.
  2. Adicione seu gadget a um recipiente, como o iGoogle ou orkut. Um recipiente é um aplicativo ou site com a capacidade de executar gadgets.

Anatomia de um gadget

Depois de compreender como editar e publicar gadgets, você está pronto para incluir recursos mais avançados nas especificações do seu gadget. A especificação do gadget XML é composta por 3 partes principais:

  • Seção de conteúdo. A seção <Content> é onde ocorre o funcionamento mais importante do seu gadget. É onde você especifica o tipo de gadget, a lógica de programação e, freqüentemente, os elementos HTML que determinam a aparência do gadget.
  • Preferências do usuário. A seção <UserPrefs> define os controles que permitem que os usuários especifiquem configurações do gadget. Por exemplo, um gadget de saudações personalizadas pode fornecer um campo de texto para o usuário especificar seu nome.
  • Preferências do gadget. A seção <ModulePrefs> do arquivo XML especifica as características do gadget, como título, autor, tamanho preferido e assim por diante.

Observação: Dentro dos atributos XML das especificações de um gadget, alguns caracteres precisam ter um ''escape'' (ou seja, precisam ser codificados adequadamente) para que sejam interpretados corretamente. Para obter mais informações, consulte Codificação de escape de caracteres especiais.

Ao criar um gadget, comece pela seção <Content>.

Definição de conteúdo

A seção <Content> representa o ''cérebro'' de um gadget. A seção <Content> define o tipo de conteúdo e contém o próprio conteúdo ou um link para conteúdo externo. A seção <Content> é onde os atributos do gadget e as preferências do usuário são combinados à lógica de programação e às informações de formatação para se transformarem em um gadget executável.

A maneira mais fácil de criar um gadget é simplesmente colocando HTML (e como opção, JavaScript ou Flash) na seção <Content>. Os desenvolvedores de web experientes podem usar a seção Seleção do tipo de conteúdo para obter outras opções relacionadas a controle de acesso, hospedagem remota, uso de linguagens de scripts alternativas e outros tópicos. Veja aqui um exemplo simples de gadget. Este gadget exibe uma fotografia que pode ser clicada para abrir um álbum de fotos em uma nova página HTML:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
  <Content type="html">
  <![CDATA[ 
    <div style="text-align:center"><a
      id="Riggs" title="My Photo Album" target="_blank" 
      href="http://picasaweb.google.com/doc.examples/ShelfBoy">
<img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg"
title="Click Here."></a>
</div> ]]> </Content> </Module>

Definição das preferências do usuário

Alguns gadgets precisam fornecer um meio de informações específicas ao usuário serem inseridas. Por exemplo, um gadget de jogo pode permitir que o usuário digite uma preferência de nível de dificuldade. A seção de preferências do usuário (<UserPref>) do arquivo XML descreve os campos de entrada do usuário que são transformados em controles da interface de usuário quando o gadget é executado. As preferências do usuário são continuamente armazenadas.

Por exemplo, este gadget exibe uma saudação pessoal com base na hora do dia. Ele permite que os usuários especifiquem o seguinte:

  • Um nome a ser usado na saudação. O nome também é exibido na barra de título.
  • Uma cor de fundo.
  • A exibição ou não de uma foto.

Esta é a aparência do gadget quando o usuário clica em edit (editar) para modificar as preferências do usuário:

Controles Userprefs

As preferências do usuário que são transformadas em controles da interface de usuário do gadget sendo executado são definidas na especificação XML, conforme mostrado abaixo:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="250" />
<UserPref name="myname" display_name="Name" required="true" />
<UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
<UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
<UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" > <EnumValue value="Red" /> <EnumValue value="Aqua" /> <EnumValue value="Lime" /> <EnumValue value="Yellow" /> <EnumValue value="Pink" /> <EnumValue value="Orange" /> <EnumValue value="White" /> </UserPref>

Observe que:

  • A linha 3 do arquivo contém o texto title="Preferences for __UP_myname__". Ao executar o gadget, o valor fornecido pela preferência de usuário myname é substituído dinamicamente por __UP_myname__.
  • A preferência de usuário myname está marcada como ''obrigatória''. Se o usuário tentar executar o gadget sem fornecer um valor para esse campo, a caixa de edição das preferências de usuário permanece aberta até que um valor seja fornecido.
  • A preferência de usuário mychoice possui o tipo de dados bool. Ela é exibida na interface de usuário como uma caixa de seleção.
  • A preferência de usuário mycolor possui o tipo de dados enum. A lista de EnumValues especifica as opções que aparecem em um menu suspenso na caixa de edição das preferências do usuário.

Aqui está o gadget completo, incluindo o JavaScript que exibe a saudação do gadget:

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="400"/> 
  <UserPref name="myname" display_name="Name" default_value="Rowan"/>
  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
     <EnumValue value="Aqua" />
     <EnumValue value="Lime" />
     <EnumValue value="Yellow" />
     <EnumValue value="Pink" />
     <EnumValue value="Orange" />
     <EnumValue value="White" />
   </UserPref>
   <Content type="html"><![CDATA[
   <div id="content_div"></div>
   <script type="text/javascript">
   // Get userprefs
   var prefs = new gadgets.Prefs();

   function displayGreeting () {
     // Get current time
     var today = new Date();
     var time = today.getTime();
     var html = "";
  
     // Based on the time of day, display an appropriate greeting
     var hour = today.getHours();
     var salutation = "Afternoon";
     if (hour < 12) {
       salutation = "Morning";
     } else if (hour > 17) {
       salutation = "Evening";
     }

     // Set the background color according to the mycolor userpref
     var element = document.getElementById('content_div');  
     element.style.height=250;
     // Set the background color according to the mycolor userpref   
     element.style.backgroundColor=prefs.getString("mycolor"); 

     // Display a greeting based on the myname userpref
     html += "<br><FONT SIZE=6>Good " + salutation + ", " +
           prefs.getString("myname") + "!!!<br><br></FONT>";

     // If the "Show Photo?" checkbox is checked, display photo.
     if (prefs.getBool("mychoice") == true) {
       html += '<img src="' + prefs.getString("myphoto") + '">';
     }
     element.innerHTML = html;
   }
   // Pass the userprefs for this module instance to the function
   // (allows users to include multiple module instances on their page)
   gadgets.util.registerOnLoadHandler(displayGreeting); 
  
   </script> 
   ]]>  
  </Content>
</Module>

Consulte a Referência para obter uma lista de todos os atributos de <UserPref>.

Use a API JavaScript para acessar as preferências do usuário a partir do seu gadget; por exemplo:

<script type="text/javascript">
  var prefs = new gadgets.Prefs();
  var someStringPref = prefs.getString("StringPrefName");
  var someIntPref = prefs.getInt("IntPrefName");
  var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Consulte a Referência de JavaScript para obter uma lista de todas as funções JavaScript.

Variáveis de substituição de preferências do usuário

Você pode usar uma variável de substituição do formato __UP_userpref__ nas seções <ModulePrefs> ou <UserPref>, onde userpref corresponde ao atributo name (nome) de uma preferência de usuário. Quando o gadget é executado, o valor da string da preferência de usuário correspondente é substituído pela variável, sem a adição de códigos de escape. Por exemplo, neste trecho, o valor fornecido pelo usuário durante a execução para a preferência de usuário projects (projetos) é substituído por __UP_projects__ na string title_url:

<Module>
  <ModulePrefs title="Build Monitor"
             title_url="http://www.example.com/build/status.php?__UP_projects__"/>
  <UserPref name="projects" display_name="project(s)"/>
  <Content ... />
</Module>

Você pode ver outro exemplo semelhante na amostra de preferências do usuário.

Aqui estão algumas orientações gerais para o uso de variáveis de substituição de preferências de usuário:

  • Para o atributo <ModulePrefs> title, use __UP_name__ . Esta variável possui códigos de escape de HTML.
  • Para o atributo <ModulePrefs> title_url, use __UP_name__ . Esta variável possui códigos de escape de URL.
  • No HTML dentro da seção <Content>, use __UP_name__. Esta variável possui códigos de escape de HTML.
  • No código JavaScript dentro da seção <Content>, use a função .gadgets.Prefs()

Compartilhamento das preferências do usuário

Você pode usar o recurso shareable-prefs para possibilitar a edição das preferências de usuário do gadget por diversos usuários. Dessa forma, os usuários podem compartilhar o gadget e ver as edições que cada um faz. Por exemplo, membros da família podem compartilhar um gadget de lista de compras de supermercado e cada pessoa pode adicionar seus itens favoritos. Os dados de preferência do usuário compõem a parte do estado do gadget hospedada pelo iGoogle. Para obter mais informações sobre preferências do usuário, consulte o Guia de desenvolvedor de API de gadgets.

Para compartilhar as preferências de usuário do gadget entre diversos usuários, o gadget deve incluir a linha <optional feature="shareable-prefs"/> na seção <ModulePrefs>. Por exemplo, este gadget usa a preferência do usuário listar tipos de dados para preencher uma lista de compras de supermercado:

Compartilhamento deste gadget

Este é o código para o gadget:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs 
    title="Our Grocery List" 
    scrolling="true"> 
    <optional feature="shareable-prefs"/> 
   </ModulePrefs>
  <UserPref name="mylist" 
    display_name="Add items" 
    datatype="list" />
  <Content type="html">
  <![CDATA[ 
    <div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>

  <script type="text/javascript"> 
    // Get userprefs
    var prefs = new gadgets.Prefs();
    // Get the list
    var items = prefs.getArray("mylist");  
    var html = "";
    // If there are no items in the list yet, display message.
    if (items.length == 0)
    {
      html += "Edit the userprefs to add items to the list.";
    }
    else {
      for (var i = 0; i < items.length ; i++) {
        var term = (items[i]);
        html += term + "<br />";
      }
    }
    document.getElementById("content_div").innerHTML = html; 
  </script>
  ]]> 
  </Content>
</Module>

Após adicionar um gadget que suporta preferências compartilháveis ao iGoogle, você pode torná-lo cooperativo da seguinte maneira.

Etapa 1: clique no triângulo do gadget que você deseja compartilhar e selecione Compartilhar este gadget.

Compartilhamento deste gadget

Etapa 2: se você é um usuário do Gmail, escolha os amigos com os quais deseja compartilhar ou digite seus endereços de e-mail.

Compartilhamento deste gadget

Etapa 3: decida se quer permitir que seus amigos editem o conteúdo do seu gadget ou apenas o visualizem em suas páginas do iGoogle.

  • Se você escolher Visualizar e editar meu conteúdo, seus amigos poderão editar as preferências de usuário do gadget. Suas alterações terão efeito na sua versão e em qualquer outra versão compartilhada do gadget.
  • Se você escolher Visualizar meu conteúdo, seus amigos não poderão modificar o gadget, nem mesmo suas cópias locais. Apenas você poderá modificar o gadget e suas alterações serão aplicadas em todas as versões compartilhadas do gadget.

Clique em Enviar convites. Seus amigos recebem um e-mail seu convidando-os a adicionar o gadget às suas próprias páginas do iGoogle.

Compartilhamento do convite

Os amigos aos quais você concedeu autorização para editar o gadget podem modificar as preferências de usuário do gadget e publicar suas alterações em todas as versões compartilhadas do gadget.

Definição das preferências do gadget

A seção <ModulePrefs> do arquivo XML especifica as características do gadget, como título, autor, tamanho preferido e assim por diante. Por exemplo:

<Module>
<ModulePrefs title="Today's Network Traffic" title_url="http://www/~rowan/gadgets/stats/"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

Os usuários do seu gadget não podem alterar esses atributos.

Consulte a Referência para obter uma lista completa dos atributos de <ModulePrefs>.

Lembre-se: Gadgets são públicos

Lembre-se de que não existem gadgets privados. Quando você publica seu gadget em um site público, as pessoas podem encontrá-lo e visualizá-lo. Procure não incluir informações pessoais, como seu número de telefone ou endereço de e-mail pessoal.

E se você não quiser que seu gadget seja público? O Google encoraja os autores de gadgets a compartilharem suas especificações. Entretanto, aqui estão algumas dicas de como minimizar a visibilidade pública do seu gadget até que você esteja pronto para lançá-lo:

  • Não envie seu gadget para o diretório de conteúdo ou para diretórios como o googlemodules.com ou hotmodules.com.
  • Se as pessoas não puderem encontrar seu gadget, é improvável que descubram o URL. Para evitar que ele seja indexado por mecanismos de busca, você pode usar alguns artifícios:
    • Procure impedir que o seu servidor da web forneça uma listagem de arquivos incluindo o seu arquivo (isso também afasta os usuários bisbilhoteiros).
    • Verifique se não há hiperlinks da web apontando para o seu gadget

O que fazer depois

Quando estiver pronto para criar gadgets mais complexos, visite os Fundamentos do desenvolvimento ou retorne à página inicial de documentação para ver todas as seções e tópicos.

Voltar ao início