Esta página foi traduzida pela API Cloud Translation.

Crie seus próprios gadgets

Os Vamos começar apresentam você aos gadgets. A próxima etapa é criar seus próprios gadgets. Este documento explica como fazer isso.

Etapas básicas

Veja as etapas básicas para criar e implantar um gadget:

Use qualquer editor de texto para escrever a especificação do seu gadget e hospedá-la em um servidor da Web público.
Adicione o seu gadget a um site que possa executar gadgets.

Anatomia de um gadget

Depois de entender como editar e publicar gadgets, você poderá incluir recursos mais avançados nas especificações. A especificação do gadget XML consiste em três partes principais:

Seção de conteúdo. A seção <Content> é onde o trabalho real do seu gadget acontece. É onde você especifica o tipo de gadget, a lógica de programação e, muitas vezes, os elementos HTML que determinam a aparência dele.
Preferências do usuário. A seção <UserPrefs> define controles que permitem aos usuários especificar configurações para o gadget. Por exemplo, um gadget de saudação personalizado pode fornecer um campo de texto para que os usuários especifiquem os nomes deles.
Preferências de gadget. A seção <ModulePrefs> no arquivo XML especifica as características do gadget, como título, autor, dimensionamento preferencial e assim por diante.

Observação:nos atributos XML em uma especificação de gadget, é necessário "escape" (ou seja, codificar corretamente) determinados caracteres para que eles sejam interpretados corretamente. Para mais informações, consulte Como ocultar caracteres especiais.

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

Como definir conteúdo

A seção <Content> representa os &cérebros" de um gadget. A seção <Content> define o tipo de conteúdo e define o próprio conteúdo ou tem um link para conteúdos externos. Na seção <Content>, os atributos do gadget e as preferências do usuário são combinados com a lógica de programação e as informações de formatação para se tornarem um gadget em execução.

A maneira mais fácil de criar seu gadget é simplesmente colocar HTML (e, opcionalmente, JavaScript ou Flash) na seção <Content>. Desenvolvedores experientes da Web podem ler Como escolher um tipo de conteúdo para ver outras opções relacionadas ao controle de acesso, hospedagem remota, uso de linguagens de script alternativas e outros tópicos.Veja um exemplo simples de gadget. Este gadget exibe uma foto clicável que abre 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>

Como especificar um DOCTYPE

Você pode incluir um DOCTYPE arbitrário na especificação do seu gadget. Os gadgets que não especificam um DOCTYPE são renderizados no modo quirks por padrão.

Como definir as preferências do usuário

Alguns gadgets precisam oferecer aos usuários uma maneira de fornecer informações específicas. Por exemplo, um gadget de jogo pode permitir que os usuários insiram um nível de dificuldade preferido. A seção de preferências do usuário (<UserPref>) no arquivo XML descreve os campos de entrada do usuário que são transformados em controles de interface do usuário quando o gadget é executado. As preferências do usuário são armazenadas de forma persistente.

Observação:para um mecanismo de persistência de uso mais geral que não esteja vinculado a preferências do usuário, consulte a API de persistência do GitLab.

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

Um nome para usar na saudação. O nome também é exibido na barra de título.
Cor do plano de fundo.
Indica se uma foto será exibida.

O gadget terá a aparência quando o usuário clicar em editar para modificar as preferências do usuário:

As preferências do usuário que são transformadas em controles da interface do usuário no gadget em execução são definidas na especificação XML da seguinte maneira:

<?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 o seguinte:

A linha 3 do arquivo contém o texto title="Preferences for __UP_myname__". Quando você executa o gadget, o valor fornecido para a preferência do usuário myname é substituído dinamicamente por __UP_myname__.
A preferência de usuário myname é marcada como "quot;required." Se o usuário tentar executar o gadget sem fornecer um valor para esse campo, a caixa de edição de preferências do usuário permanecerá aberta até que um valor seja fornecido.
A preferência de usuário mychoice tem um tipo de dados bool. Essa opção aparece na interface do usuário como uma caixa de seleção.
A preferência de usuário mycolor tem um tipo de dados enum. A lista de EnumValues especifica as opções que aparecem em um menu suspenso na caixa de edição de preferências do usuário.

Este é o gadget completo, incluindo o JavaScript que exibe a saudação para o 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>

Para ver uma lista de todos os atributos <UserPref>, consulte a Referência.

As preferências do usuário são acessadas no seu gadget por meio da API JavaScript de preferências de usuário, 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>

Para ver uma lista de todas as funções JavaScript, consulte a Referência do JavaScript.

Observação:se você armazenar dados confidenciais de usuários particulares nas preferências de usuários de um gadget, sugerimos o uso de um domínio bloqueado.

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

É possível usar uma variável de substituição do formato __UP_userpref__ nas seções <ModulePrefs> ou <UserPref>, em que userpref corresponde ao atributo name de uma preferência do usuário. Quando o gadget é executado, o valor da string da preferência do usuário correspondente é substituído pela variável, sem escape. Por exemplo, neste trecho, o valor que o usuário fornece no momento da execução para a preferência de usuário projects é 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>

Veja outro exemplo na amostra de preferências do usuário.

Veja as diretrizes gerais para usar variáveis de substituição de preferência do usuário:

No atributo <ModulePrefs> title, use __UP_name__. Ela tem escape de HTML.
No atributo <ModulePrefs> title_url, use __UP_name__ . Ela tem escape de URL.
Em HTML na seção <Content>, use __UP_name__. Essa opção tem escape em HTML.
No código JavaScript na seção <Content>, use a função gadgets.Prefs().

Definir preferências de gadget

A seção <ModulePrefs> no arquivo XML especifica as características do gadget, como título, autor, tamanho preferido e assim por diante. 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.

Para ver uma lista completa dos atributos <ModulePrefs>, consulte a Referência.

O que fazer depois

Quando você estiver pronto para criar gadgets mais complexos, acesse Fundamentos de desenvolvimento ou volte para a página inicial da documentação para ter uma visão geral de seções e tópicos.

Voltar ao início