Você está na página 1de 103

A web fica melhor com os relacionamentos

A web é muito mais interessante quando você pode construir aplicativos que interajam facilmente
com seus amigos e colegas. Essa tendência também criou uma lista crescente de APIs específicas
para sites, que os desenvolvedores precisam aprender.
O serviço OpenSocial oferece um conjunto de APIs comuns para desenvolver aplicativos sociais
que irão funcionar em diversos sites. Elas possibilitam que os desenvolvedores criem aplicativos
utilizando JavaScript e HTML padrão para acessar amigos de uma rede social e atualizar feeds.

Muitos sites, uma API


O uso de APIs comuns significa que você precisa aprender menos para desenvolver para diversos
sites. O OpenSocial está sendo desenvolvido pelo Google em conjunto com os membros da
comunidade da web. O objetivo final é qualquer site de relacionamentos ser capaz de implementar
as APIs e hospedar aplicativos sociais de terceiros. Muitos sites estão implementando o OpenSocial,
entre eles o Engage.com, Friendster, hi5, Hyves, imeem, LinkedIn, MySpace, Ning, Oracle, orkut,
Plaxo, Salesforce.com, Six Apart, Tianji, Viadeo e XING.
Para que os desenvolvedores comecem imediatamente, o Orkut abriu um sandbox limitado que você
pode usar para começar a criar aplicativos usando as APIs do OpenSocial.

Servidor opcional
O OpenSocial foi criado com a tecnologia do Google Gadget. Você pode criar um aplicativo social
ótimo e "viral" com custos mínimos ou inexistentes de servidor. Com o Google Gadget Editor e
uma API simples de valor essencial, você pode criar um aplicativo social completo sem nenhum
servidor. É claro que você também pode hospedar seu aplicativo em seus próprios servidores, se
preferir. Em todo caso, a tecnologia de cache de gadget do Google alivia a demanda de largura de
banda, caso seu aplicativo se torne um sucesso mundial.
Seções Tópicos selecionados
"Hello, World"
Primeiros passos
Em que consiste um Gadget?
Etapas básicas
Criação dos seus próprios gadgets
Anatomia de um gadget
Seleção do tipo de conteúdo
Como transformar uma página da web ou aplicativo
existente em um gadget
Fundamentos do desenvolvimento
Uso de tipos de dados Userpref
Como salvar o estado
Criação de gadgets que necessitam de login ou cookies
Dicas de programação e depuração
Ferramentas para desenvolvedores Hospedagem através do Google Gadgets Editor
Hospedagem no Google Code
Gerenciamento da altura do gadget
Definição do título do gadget
Criação de uma interface de
Guias
usuário
MiniMessages
Flash
Uso de texto
Uso de XML
Uso de conteúdo remoto
Uso de feeds
Uso de JSON
Criação de um gadget localizado
Internacionalização Pacotes de mensagens
Uso de pacotes de mensagens em um gadget
Gadgets em idiomas diferentes do Onde posso encontrar gadgets que não sejam em inglês?
inglês Criação de gadgets em idiomas diferentes do inglês
Onde posso colocar meu gadget?
Publicação do seu gadget Preparação para a publicação
Publicação no diretório de conteúdo do iGoogle
Preferências do gadget
Referência das especificações de
Preferências do usuário
gadgets
Seção de conteúdo
Referência de JavaScript
Primeiros passos
Bem-vindo à API de gadgets!
Este guia do desenvolvedor é baseado na versão gadgets.* da API de gadgets JavaScript. A API
de gadgets foi inserida no namespace API JavaScript de gadgets.* para fornecer uma API mais
limpa para programação e suporte. Para saber mais sobre a API de gadgets.*, consulte a
documentação de referência aqui. Embora a API de gadgets.* tenha muita coisa em comum com
a API de gadgets antiga, também há diferenças importantes.
Atualmente apenas alguns recipientes (um recipiente é um site ou aplicativo que executa gadgets)
suportam a gadgets.* API. Para ver uma lista dos recipientes que suportam a gadgets.*
API, consulte a lista de recipientes do OpenSocial. Alguns recipientes mais antigos suportam
apenas a API de gadgets antiga. Portanto, verifique a documentação do seu recipiente específico
para saber qual API é suportada. Para saber mais sobre os tipos diferentes de gadgets e onde eles
podem ser executados, consulte a Visão geral da API de gadgets.
Este guia do desenvolvedor destina-se a pessoas que desejam usar a API para criar gadgets. Por
serem muito fáceis de criar, os gadgets são um excelente ponto de partida se você estiver
começando a aprender sobre programação da web.

“Hello, World"
O gadget mais simples tem apenas algumas linhas de código. Este gadget exibe a mensagem "Hello,
world!":
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="hello world example" />
<Content type="html">
<![CDATA[
Hello, world!
]]>
</Content>
</Module>

No exemplo do "Hello World" descrito no tutorial, observe que:


• Os gadgets são especificados em XML. A primeira linha é a maneira padrão de iniciar um
arquivo XML. Esta deve ser a primeira linha do arquivo.
• A tag <Module> indica que este arquivo XML contém um gadget.
• A tag <ModulePrefs> contém informações sobre o gadget, como seu título, descrição,
autor e outros recursos opcionais.
• A linha <Content type="html"> indica que o tipo de conteúdo do gadget é HTML.
• <![CDATA[ ...insert HTML here... ]]> é usada como invólucro para o HTML
quando o tipo de conteúdo do gadget é html. Ela informa ao analisador do gadget que o
texto dentro da seção CDATA não deve ser tratado como XML. A seção CDATA
normalmente contém HTML e JavaScript.
• </Content> significa o final da seção Conteúdo.
• </Module> significa o final da definição do gadget.

Em que consiste um Gadget?


A API de gadgets consiste em alguns blocos estruturais simples: XML, HTML e JavaScript. Para
começar, você só precisa de conhecimentos básicos de HTML. Nós ensinaremos tudo o que é
necessário sabe sobre XML para criar gadgets. Mais tarde, ao criar gadgets mais sofisticados, você
provavelmente aprenderá como usar JavaScript, caso ainda não esteja familiarizado com essa
linguagem.
XML é uma linguagem de markup de uso geral. Ela descreve dados estruturados de maneira que
possam ser lidos e gravados por programadores e computadores.
XML é a linguagem usada para programar as especificações do gadget. Um gadget é simplesmente
um arquivo XML, colocado em algum lugar da internet onde o Google possa encontrá-lo. O arquivo
XML que especifica um gadget contém instruções sobre como processar e exibir o gadget. O
arquivo XML pode conter todos os dados e códigos do gadget, ou pode ter referências (URLs) para
o local onde o restante dos elementos se encontram.
HTML é a linguagem de markup usada para formatar páginas da internet. O conteúdo estático de
um gadget normalmente é criado em HTML. A linguagem HTML tem aparência semelhante à
XML, mas é usada para formatar documentos da web e não para descrever dados estruturados.
JavaScript é uma linguagem de scripts que pode ser usada para adicionar comportamento dinâmico
aos gadgets.
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.

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:

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().

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á hyperlinks na web apontando para o seu gadget
Fundamentos do desenvolvimento
Este documento descreve os conceitos e tarefas básicas para o processo de desenvolvimento do
gadget. Para obter informações sobre como usar a API de gadgets, leia Primeiros passos.

Seleção do tipo de conteúdo


Uma das primeiras decisões que você deve tomar ao desenvolver um gadget é que tipo de conteúdo
irá usar. Por exemplo:
<Content type="html">

O tipo de conteúdo determina:


• Que recursos da API estão disponíveis para você como autor do gadget.
• Como seu gadget é exibido.
• Onde seu gadget pode ser implementado.
A tabela a seguir descreve os tipos de conteúdo disponíveis e quando você deve usá-los:
Tipo de
Descrição Quando usar
conteúdo
Com o tipo de conteúdo html, o conteúdo
completo normalmente reside nas especificações O tipo de conteúdo mais flexível e
html do gadget. Um gadget type="html" contém versátil é o html. Na dúvida,
HTML, possivelmente com JavaScript, Flash, selecione o tipo de conteúdo html.
ActiveX ou outros objetos incorporados ao
navegador. Este é o tipo padrão.
Com o tipo de conteúdo url, o conteúdo do Atualmente, o tipo de conteúdo
gadget reside em uma página da web remota que type="url" não é totalmente
pode ser acessada por meio de um URL suportado pelos gadgets.* ou
url localizado nas especificações do gadget. A APIs do OpenSocial. Se desejar usar
página da web remota é onde reside todo o o tipo de conteúdo type="url"
markup HTML e o JavaScript. Você NÃO pode com as bibliotecas de gadgets
colocar nenhum markup HTML ou código JavaScript, use a API de gadgets
JavaScript nas especificações do gadget. antiga.

HTML
Com o tipo de conteúdo html, o código completo normalmente reside nas especificações do
gadget. Isso inclui o XML do gadget e qualquer markup HTML e JavaScript. Quase todos os
exemplos deste guia do desenvolvedor usam o tipo de conteúdo html. Ele é o tipo mais flexível e
versátil e você deve normalmente optar por ele, a menos que esteja criando um gadget com
requisitos específicos.
O exemplo a seguir demonstra a implementação de um gadget do recurso ROT13. O ROT13
criptografa textos substituindo cada letra pela letra que está 13 posições à frente no alfabeto.
Quando o recurso ROT13 é reaplicado, ele rotaciona cada letra novamente, restaurando o texto
original.
Esta é a especificação do gadget:
<?xml version="1.0" encoding="UTF-8" ?>

<Module>
<ModulePrefs title="Magic Decoder"/>
<Content type="html">
<![CDATA[
<script type="text/javascript">

// The gadget version of ROT13.


// Encodes/decodes text strings by replacing each letter with the letter
// 13 positions to the right in the alphabet.
function decodeMessage (form) {
var alpha = "abcdefghijklmnopqrstuvwxyz";
var input = form.inputbox.value;
var aChar;
var message = "";
for (var i = 0; i <input.length; i++)
{
aChar = input.charAt(i);
var index = alpha.indexOf(aChar.toLowerCase());

// if a non-alphabetic character, just append to string


if (index==-1)
{
message += aChar;
}

// if you have to wrap around the end of the alphabet


else if(index > 12) { // compensate for 0-based index
index = 25 - index; // last item in array is at [25]
index = 12 - index; // because array starts with 0
aChar = alpha.charAt(index);
message += aChar;
}

// if you don't have to wrap


else {
aChar = alpha.charAt(index+13);
message += aChar;
}
}
document.getElementById('content_div').innerHTML = "<b>Your message:
</b>" + message;
}
</script>

<FORM NAME="myform" ACTION="" METHOD="GET">Message: <BR>


<INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
<INPUT TYPE="button" NAME="button" Value="Transform"
onClick="decodeMessage(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>

As regras para um gadget type="html" são as seguintes:


• Um gadget type="html" deve conter uma seção CDATA, e todos os códigos HTML
devem estar dentro dessa seção:
<Content type="html">
<![CDATA[ HTML here... ]]>

As seções CDATA são usadas para adicionar códigos de escape a blocos de texto
contendo caracteres que, de outra forma, seriam considerados markup. O único
separador reconhecido em uma seção CDATA é a string "]]>", que finaliza a seção
CDATA.
• Você não pode usar as tags <html>, <head>, ou <body>. Os gadgets são gerados com
suas próprias tags <html>, <head>, e <body>. Basta incluir o conteúdo que
normalmente ficaria dentro da tag <body>.
Um gadget com tipo de conteúdo html também pode fazer referência a um arquivo JavaScript
externo:
<Module>
<ModulePrefs ... />
<Content type="html"><![CDATA[
<script src="http://www.example.com/gadgets/clock/clock.js"
type="text/javascript"></script>

]]></Content>
</Module>

URL
Quando um gadget possui o tipo de conteúdo type="url", o atributo href= fornece um URL e
qualquer outro conteúdo da especificação do gadget é ignorado. Com o tipo de conteúdo url,
supõe-se que todas as informações relacionadas à interface de usuário e à lógica programática do
gadget residem no arquivo apontado pelo URL. Não se deve colocar nenhum markup HTML ou
JavaScript dentro do gadget em si. Por exemplo:
<Module>
<ModulePrefs ... />
<Content type="url" href="http://www/cgi-bin/example/gadgets/mystats.cgi" />
</Module>

Para obter uma descrição

Como transformar uma página da web ou aplicativo existente


em um gadget
Para transformar uma página da web ou aplicativo existente em um gadget, siga as orientações
abaixo:
• Remova as tags <html>, <head> e <body> (em outras palavras, forneça apenas o
conteúdo HTML). Esta diretriz aplica-se somente a gadgets type="html". Ela não se
aplica a gadgets type="url".
• Para eventos onload, use gadgets.util.registerOnLoadHandler().
• Se o gadget exigir login, use um tipo de conteúdo URL. Consulte a seção Criação de gadgets
que necessitam de login ou cookies para saber como lidar com situações que podem ser
consideradas "armadilhas". Gadgets HTTPS emitem avisos de "conteúdo misto" no Internet
Explorer, o que pode incomodar os usuários.
• Faça as alterações necessárias na interface do usuário para ajustar sua página ou aplicativo
no pequeno espaço do gadget. O makeRequest() pode ser usado como proxy do
conteúdo de amadores e profissionais criando protótipos. Para gadgets desenvolvidos
comercialmente, recomendamos simplesmente criar uma pequena página nova e usar o
type="url" apontando para ela.
Uso de tipos de dados Userpref
Cada preferência de usuário tem um tipo de dados dentro da especificação do gadget. O datatype
é uma string opcional que especifica o tipo de dados do atributo. Os valores possíveis de
datatype são string, bool, enum, hidden (uma string invisível que não pode ser editada
pelo usuário), list e location (para gadgets baseados no Google Maps). O tipo de dados
padrão é string.
Consulte a referência para obter informações detalhadas sobre os tipos de dados das preferências do
usuário.
Esta seção descreve dois dos tipos de dados mais especializados: list e location. Você pode
encontrar exemplos de como usar os outros tipos de dados na documentação (por exemplo, enum,
hidden e bool).

Uso do tipo de dados list


Uma preferência de usuário com o tipo de dados list é uma matriz de valores fornecidos
dinamicamente pelos usuários durante a execução. À medida que os usuários digitam valores na
caixa de edição de preferências do usuário, os valores são adicionados à lista. Assim como qualquer
outro userpref, a lista pode ser acessada programaticamente pelo gadget durante a execução. Você
pode usar o tipo de dados list sempre que quiser permitir que os usuários forneçam uma lista de
valores arbitrários dinamicamente. Por exemplo, um gadget de condições climáticas pode permitir
que os usuários digitem uma lista de códigos postais.
Para declarar que um userpref tem tipo de dados list, use datatype="list". Por exemplo:
<UserPref name="mylist" display_name="Add Search Terms" datatype="list"
required="true"/>

O gadget acessa os valores da lista usando a função Prefs getArray(),; por exemplo:
var search_terms = prefs.getArray("mylist");

Dentro da matriz, os itens são armazenados em uma lista separada por barras verticais. Você pode
usar a função getString() de Prefs para retornar esta lista como uma única string na qual os
valores são separados pelo caractere barra vertical (|); por exemplo:
prefs.getString("mylist");

Você também pode usar uma string separada por barras verticais para definir os valores padrão de
um tipo de dados list:
<UserPref name="mylist" display_name="Add Search Terms" datatype="list"
default_value="zdnet|pc|Apple Insider"/>

Use a função setArray(name, val) de Prefs para adicionar valores à lista


programaticamente. Para usar essa função, seu gadget deve incluir <Require
feature="setprefs"/> em <ModulePrefs>. Por exemplo, o trecho a seguir adiciona os
valores "Nokia" e "CNET" à lista:
...

<ModulePrefs title="Feed Searcher" scrolling="true">


<Require feature="setprefs" />

</ModulePrefs>
...
prefs.setArray("mylist", ["Nokia","CNET"]);

Aqui está um exemplo simples que fornece os itens da lista digitados pelo usuário na caixa Edit
(Editar):
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="List Data Type Example"
scrolling="true"/>
<UserPref name="mylist"
display_name="Add Terms"
datatype="list" />
<Content type="html">
<![CDATA[
<div id=content_div></div>

<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();

// Get the array of search terms entered by the user


var terms = prefs.getArray("mylist");
var html = "";

// If the user has not added any terms yet, display message.
if (terms.length == 0)
{
html += "Edit the userprefs to add terms.";
}
else {
html += "Your terms are:<br /><br />";
for (var i = 0; i < terms.length ; i++) {
var term = (terms[i]);
html += term + "<br />";
}
}
document.getElementById("content_div").innerHTML = html;
</script>

]]>
</Content>
</Module>

Uso do tipo de dados location


Os gadgets baseados no Google Maps podem usar o tipo de dados location. O gadget do
exemplo a seguir ilustra como usar o tipo de dados location. Nos gadgets, o valor fornecido para
um tipo de dados location deve ser uma cidade ou um código postal dos Estados Unidos,
Canadá ou Reino Unido. O uso de códigos postais pode ter um resultado melhor.
Ao usar o tipo de dados location, use getString() para recuperar a longitude e a latitude do
local especificado pelo usuário.
<Module>
<ModulePrefs title="Map of __UP_loc__" height="300"
author="Jane Smith"
author_email="xxx@google.com" />
<UserPref name="loc"
display_name="Location"
datatype="location"
required="true" />
<Content type="html">
<![CDATA[
<script src="http://maps.google.com/maps?file=js"
type="text/javascript"></script>
<div id="map" style="width: 100%; height: 100%;"></div>
<script type="text/javascript">
var prefs = new gadgets.Prefs();
var map = new GMap(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.centerAndZoom(new GPoint(prefs.getString("loc.long"),
prefs.getString("loc.lat")), 6);
</script>

]]>
</Content>
</Module>

Ao ler uma preferência x de location:


• Se x for uma string vazia (significando um local vazio), x.lat e x.long são a string
vazia.
• Se x não puder ser geocodificada (significando um local inválido), x.lat e x.long são
0.0.
As versões anteriores da API de gadgets não permitiam especificar um default_value para o
tipo de local. Mas agora isso mudou.

Como salvar o estado


É comum permitir que os usuários definam suas preferências de forma explícita, através da caixa de
edição. Entretanto, às vezes é útil definir programaticamente os valores das preferências do usuário,
sem sua participação direta. Por exemplo, em um gadget de jogo, você pode armazenar
continuamente a pontuação mais alta do usuário. Você pode fazer isso de maneira programática,
definindo o valor de uma preferência de usuário "high_score".
Para usar o recurso setprefs, seu gadget deve incluir:
• Uma tag <Require feature="setprefs"/> (em <ModulePrefs>) para informar
ao gadget que ele precisa carregar a biblioteca setprefs.
• Uma userpref cujo valor você deseja definir programaticamente e armazenar continuamente.
Normalmente, esta userpref tem o tipo de dados hidden.
• Uma chamada à função JavaScript set() para a userpref cujo valor você deseja salvar.
O tamanho da preferência atualmente está restrito por limitações de URL, podendo chegar a 2K.
O gadget da amostra a seguir consiste em dois botões: um que aumenta o valor de um contador, e
outro que redefine o valor do contador para 0. Neste exemplo, "counter" é uma preferência de
usuário. O tipo de dados é hidden, o que significa que os usuários não têm permissão de
modificar diretamente o valor.
Esta é a especificação do gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="Setprefs New">
<Require feature="opensocial-0.7"/>
<Require feature="setprefs" />
</ModulePrefs>
<UserPref
name="counter"
default_value="0"
datatype="hidden"/>
<Content type="html">
<![CDATA[
<div id="content_div" style="height: 100px;"></div>
<script type="text/javascript">

// Get user preferences


var prefs = new gadgets.Prefs();
var html = "";
var div = document.getElementById('content_div');
// Increment value of "counter" user preference
function incrementCounter() {
var count = prefs.getInt("counter");
div.innerHTML = "The count is " + count + ".";
// Increment "counter" userpref
prefs.set("counter", count + 1);
}

// Reset value of "counter" userpref to 0


function resetCounter(){
prefs.set("counter", 0);
div.innerHTML = "Count reset to " + prefs.getInt("counter") + ".";
}

</script>
<input type=button value="Count" name="count" onClick="incrementCounter()">
<input type=button value="Reset" name="reset" onClick="resetCounter()">
]]>
</Content>
</Module>

Observação: Se for necessário armazenar diversos valores, recomendamos salvá-los em uma string
JSON.

Codificação de escape de caracteres especiais


É necessário adicionar códigos de escape a determinados caracteres especiais dentro dos atributos
XML de uma especificação de gadget. Você pode usar somente entidades ASCII na especificação
do gadget. Por exemplo, não é possível usar entidades do símbolo ISO 8859-1. Aqui está uma lista
dos caracteres especiais suportados:
Caractere Codificação de escape
& &amp;
< &lt;
> &gt;
" &quot;
' &apos;
Por exemplo:
• BAD: href="http://www.foo.com/bar?x=a&y=b"
• GOOD: href="http://www.foo.com/bar?x=a&amp;y=b"
• BAD: description="this is a "sexy" gadget"
• GOOD: description="this is a &quot;sexy&quot; gadget"
Observe que esse tipo de escape não é necessário no bloco CDATA. Entretanto, seu uso é
recomendável.
Dentro do código JavaScript, use a função _hesc(str) para retornar a string HTML str com os
caracteres abaixo seguidos do código de escape: <>'".

Criação de gadgets que necessitam de login ou cookies


As políticas de privacidade padrão do Microsoft Internet Explorer e do Apple Safari não permitem
que sites de terceiros definam cookies. Portanto, alguns gadgets podem não funcionar corretamente.
Os sites que usam cookies para login, especificamente, podem não funcionar corretamente dentro
de um iframe da página do iGoogle. Veja algumas soluções possíveis:
• Use parâmetros URL em vez de cookies. Por exemplo, o Orkut birthdays gadget
(aniversários do Orkut) passa credenciais de autenticação via URL. Aviso importante: Se
você optar por este método, tenha cuidado para que esses parâmetros de URL não vazem
para outros sites da web nos campos HTTP de direcionamento.
• Crie cabeçalhos P3P. Dependendo da política de privacidade do seu site, talvez você possa
criar cabeçalhos P3P, os quais permitem que o Internet Explorer (mas não o Safari) leia
cookies de terceiros do seu site. Se você estiver usando PHP e desejar definir os cabeçalhos,
use este snippet de código no alto da sua página PHP:
<?php
header("P3P: CP=\"CAO PSA OUR\"");
?>

Esse comando deve ser chamado antes da exibição de qualquer resultado na página.

VERIFIQUE SUA POLÍTICA DE PRIVACIDADE CUIDADOSAMENTE QUANTO


AOS CABEÇALHOS QUE PODEM SER USADOS EM SEU SITE.
ENCORAJAMOS VOCÊ A CONSULTAR SEU ADVOGADO.

• Informe os usuários. Isso pode ser feito em JavaScript, como nesta amostra de gadget
(experimente) . Você também pode integrar instruções à sua lógica de autenticação. Se
detectar o bloqueio de cookies, informe os usuários que eles devem afrouxar sua
configuração de privacidade ou experimentar um navegador diferente. Por exemplo, você
pode exibir uma mensagem como:
Seu navegador não é compatível com este site na configuração atual. Se estiver usando
o Microsoft Internet Explorer, altere sua configuração de segurança selecionando
Ferramentas > Opções da Internet. Abra a guia Privacidade, clique em Avançado e,
em seguida, clique em Ignorar manipulação automática de cookies. Em Cookies
Secundários, clique em Aceitar. Como alternativa, você pode usar outro navegador,
como o Firefox.
Ferramentas para desenvolvedores
Este documento fornece diretrizes gerais para programação, depuração e hospedagem de gadgets.

Dicas de programação e depuração


Parte do processo de desenvolvimento de um gadget (ou do processo de desenvolvimento de
qualquer código) é compreender que nem sempre as coisas funcionam como se espera. Esta seção
descreve algumas técnicas básicas para evitar problemas e para corrigi-los quando ocorrerem.

Comece pelo mais simples


Uma regra fundamental da programação é começar pelo mais simples. Obtenha uma estrutura
básica de gadget que esteja operante e amplie essa estrutura gradualmente. Teste-a a cada estágio
antes de prosseguir. Com essa estratégia, é mais fácil descobrir quando uma alteração que você fez
gerou algum problema.

Estude gadgets existentes


Um dos melhores recursos disponíveis para você, como desenvolvedor de gadget, são os gadgets
existentes. Visite o diretório de conteúdo e estude o código de gadgets que se parecem com o que
você está tentando implementar.

Use o console JavaScript do Firefox


Durante o desenvolvimento, você pode usar o Firefox para testar seus gadgets no iGoogle. Se um
gadget não estiver funcionando adequadamente, abra o console JavaScript (Ferramentas > Java
Console), selecione Erros e verifique se o seu gadget possui erros de sintaxe JavaScript. Antes de
cada teste, lembre-se de limpar o console para remover as mensagens de erro antigas.
Se estiver usando um tipo de navegador diferente, procure um console JavaScript ou depurador
suportado por seu navegador.

Confirme suas suposições


Confirmar suas suposições durante o processo de desenvolvimento pode economizar muito tempo e
evitar o desperdício de esforços. Você tem certeza de que sua variável tem o valor que você supõe?
Você tem certeza de que a matriz contém elementos? Talvez a função que "não parece estar
funcionando" na verdade não esteja sendo chamada? Teste suas suposições imprimindo as
mensagens de status em pontos diferentes do programa. Por exemplo, o gadget abaixo tem uma
função print() que grava mensagens de depuração em debug_div caso o sinalizador debug
tenha um valor diferente de zero:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="Debug Example"
height="200"/>
<UserPref
name="myname"
display_name="Name"
required="true" />
<UserPref
name="mycolor"
display_name="Color"
default_value="Pink"
datatype="enum" >
<EnumValue value="Blue" />
<EnumValue value="Yellow" />
<EnumValue value="Pink" />
<EnumValue value="Gray" />
</UserPref>
<Content type="html">
<![CDATA[
<div id="content_div" style="font-size:20pt; padding:5px; text-align:
center;"></div>
<div id="debug_div" style="font-size:9pt; padding:5px; color: red;"></div>
<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();

// debug flag. When its value is non-zero, debugging messages are


displayed
var debug = 1;
// The string containing debugging messages
var debug_html = "";

// Display date
function displayDate (){
// DEBUG: is the function getting called?
print("In displayDate function<br>");

// Create Date object


var today = new Date();
// Get current time
var time = today.getTime();
var content_html = "";
var element = document.getElementById('content_div');
element.style.backgroundColor=prefs.getString("mycolor");
element.style.height=100;
// DEBUG: print out prefs values
print("The background color is " + prefs.getString("mycolor") + "<br>");
print("The name is " + prefs.getString("myname") + "<br>");

content_html += today.toDateString();
// Write content HTML to div
document.getElementById("content_div").innerHTML = content_html;
}

// Outputs debug messages if debug flag has a non-zero value


function print(msg) {
if (debug) {
debug_html += msg;
// Write debug HTML to div
document.getElementById("debug_div").innerHTML = debug_html;
}
}
gadgets.util.registerOnLoadHandler(displayDate);
</script>
]]>
</Content>
</Module>

Observação: Consulte MiniMessages para obter uma descrição da API de MiniMessages, que
permite modificar o comportamento e a aparência das mensagens exibidas em um gadget.
Ferramentas adicionais
As funções adicionais do Firefox descritas abaixo podem ajudá-lo a obter uma visão mais detalhada
dos seus gadgets durante o desenvolvimento:
• O Firebug fornece ferramentas de depuração e inspeção de DOM.
• O Web Developer adiciona um menu e uma barra de ferramentas ao navegador, contendo
ferramentas de desenvolvedor da web.

Hospedagem através do Google Gadgets Editor


Caso não tenha acesso a um servidor para armazenar seus arquivos XML de gadget, o Google
Gadgets Editor (GGE) é uma ótima ferramenta para editar e hospedar gadgets rapidamente. Para
usar o GGE, faça login em uma conta do Google (ou você não poderá salvar seu gadget). Por
exemplo, se você alterar a mensagem "Hello, world!" para "Hello, gadget developers!!" e usar o
comando File > Save (Arquivo > Salvar) para salvar a especificação do gadget com um novo nome,
o GGE hospedará o novo gadget para você com o nome especificado:
Observação: O GGE ainda não suporta a totalmente API de gadgets.*. Portanto, alguns dos
recursos ainda não estão ativados. Você pode usar o GGE para editar e hospedar arquivos, mas não
pode pré-visualizar seu gadget.

Comandos do menu File


A guia Edit (Editar) tem um menu suspenso File (Arquivo) que inclui os comandos descritos
abaixo. O GGE usa sua conta do Google para identificar os arquivos que pertencem a você.
Portanto, é necessário fazer login para poder usar a maioria desses comandos.
Comando Descrição
Open (Abrir) Abre um gadget criado anteriormente e salvo através do GGE.
Salva a especificação do gadget que está sendo editado. Se você ainda não tiver
salvo o gadget, ele solicita o nome do gadget. Ao salvar um gadget no GGE, o
Save (Salvar) GGE o hospeda automaticamente para você. Um gadget deve ser hospedado em
um servidor público para poder ser publicado. O GGE hospeda o gadget e fornece
diversas maneiras de publicá-lo.
Save As
Salva o gadget sendo editado com o nome que você fornecer.
(Salvar como)
Rename Renomeia o gadget sendo editado. Disponível somente depois que o gadget é
(Renomear) salvo.
Permite navegar no sistema de arquivos para localizar recursos do gadget e salvá-
los no ambiente do GGE. Os recursos incluem especificações de gadget, arquivos
Upload
de imagem, etc. Depois que os recursos são enviados, o GGE os hospeda. Isso
(Enviar)
possibilita que você importe-os para a especificação do seu gadget, inserindo links
de referência aos URLs do GGE.
Publish O item de menu Publish (Publicar) oferece as opções abaixo para a publicação do
(Publicar) seu gadget:

• Add to my iGoogle page (Adicionar à minha página do iGoogle)


• Publish to iGoogle Directory (Publicar no diretório do iGoogle)
• Add to a webpage (Adicionar a uma página da web)

O comando fica disponível somente depois que o gadget é salvo (salvar faz o GGE
hospedar seu gadget). Para obter mais informações, consulte Publicação do seu
gadget com o GGE.
Delete Exibe uma lista dos seus gadgets no GGE e permite que você selecione os itens
(Excluir) que deseja excluir.

Publicação do seu gadget com o GGE


O comando Publish (Publicar) do menu File (Arquivo) oferece as opções abaixo para a publicação
do seu gadget:
• Add to my iGoogle page (Adicionar à minha página do iGoogle) - Adiciona o gadget à
sua página do iGoogle. Esta é a maneira mais simples de testar seu gadget durante o
desenvolvimento.
• Publish to iGoogle Directory (Publicar no diretório do iGoogle) - Leva você até a página
de envio do iGoogle, inserindo automaticamente o URL do seu gadget no formulário. Você
pode usar o formulário para enviar seu gadget ao diretório de conteúdo do iGoogle. Seu
gadget não será enviado a menos que você clique em Send (Enviar). Depois de testar e
ajustar seu gadget, essa será a etapa final do desenvolvimento. Você não precisa realizar essa
etapa para usar seu gadget e compartilhá-lo com seus amigos. Esta opção é para
desenvolvedores que desejam disponibilizar seus gadgets para um público de massa.
• Add to a webpage (Adicionar a uma página da web) - Leva você até a página do criador
da distribuição. A distribuição ainda não é suportada pela API de gadgets.* e nem pelas
APIs do OpenSocial.
O URL do seu gadget é fornecido no canto superior direito do GGE. Clique no link para ver o URL
completo.
Durante o desenvolvimento e teste do gadget, recomendamos testá-lo na sua página do iGoogle e
em outras páginas da web. Depois de testar e ajustar seu gadget, você pode optar por enviá-lo ao
diretório de conteúdo do iGoogle, onde será distribuído para um público maior.

Hospedagem no Google Code


A maneira mais fácil de hospedar especificações e recursos de gadget é através do GGE. Para os
desenvolvedores que necessitam de um sistema de controle de fonte com mais recursos,
recomendamos a hospedagem no Google Code: http://code.google.com/hosting. O Google Code é
um serviço gratuito que oferece muitas vantagens ao desenvolvedor de gadgets. Uma das principais
vantagens é o controle de versões através do Subversion, que é um sistema de controle de versões
de código aberto. Com o Subversion, você pode rastrear alterações e manter versões diferentes do
seu gadget. O histórico completo das revisões fica disponível, permitindo que você retorne a uma
versão anterior ou analise as diferenças entre as versões. Para saber mais sobre o Subversion,
consulte o Livro do Subversion.
Para hospedar seus gadgets no Google Code, primeiro é necessário instalar um programa de área de
trabalho (o "cliente do Subversion") que permite enviar e salvar arquivos no code.google.com
("repositório do Subversion"). A maioria dos clientes do Subversion contém uma interface gráfica
de usuário, que torna a interação com o Subversion mais fácil do que a interface de linha de
comando. Você pode escolher entre diversos clientes, dependendo do seu sistema operacional.
Procure instalar um que seja compatível com o seu sistema. Aqui estão alguns clientes
recomendados:
• TortoiseSVN é um cliente do Subversion para Windows fácil de usar, que integra a
funcionalidade diretamente no Windows Explorer.
• AnkhSVN é um plugin do Visual Studio que oferece acesso ao Subversion dentro do IDE
(Ambiente de desenvolvimento integrado).
• ZigVersion é um cliente do Subversion criado para o Mac OS X.
• RapidSVN é um cliente do Subversion com GUI (Interface gráfica de usuário) para diversas
plataformas. Este cliente suporta os três principais sistemas operacionais: Windows, Mac
OS X e Linux.
Aqui está uma lista completa dos clientes e plugins.
Depois de instalar o Subversion em sua máquina, siga as etapas abaixo para começar a usar o
Google Code e hospedar seus projetos.

Criação de um novo projeto


Para criar um novo projeto:
1. Vá para http://code.google.com/hosting e faça login usando sua conta do Gmail. Crie uma
conta se ainda não tiver.
2. Clique em Create a new project (Criar um novo projeto).
3. Preencha os campos do seu novo projeto:
• Crie um nome com letras minúsculas para o seu projeto, por exemplo my-
gadgets. Lembre-se de que o nome do projeto torna-se parte do URL do projeto e
não pode ser alterado depois.
• Escreva um resumo e uma descrição.
• Selecione uma licença de código aberto. Para saber mais, visite Licença de código
aberto.
• Etapa opcional: atribua marcadores para ajudar outros usuários a encontrarem o seu
projeto.
4. Confirme se todos os campos obrigatórios foram preenchidos e clique em Create Project
(Criar projeto).
5. Pronto! Você será direcionado à Página inicial do projeto. Confirme se o URL tem a
seguinte aparência: http://code.google.com/p/<project-name>/
Agora você tem um projeto no code.google.com. Um repositório do Subversion foi criado usando o
nome do seu projeto. Clique na guia Source (Fonte) e clique no link Subversion repository
(Repositório do Subversion).
O URL deve ter a seguinte aparência: http://<project-name>.googlecode.com/svn/. Você deve ver
três links de diretórios: branches, tags e trunk. Ao enviar arquivos para o seu projeto, eles são
colocados na pasta /trunk. Você pode salvar o URL http://<project-
name>.googlecode.com/svn/trunk/ em seus favoritos para referência futura.

Bloqueio de um projeto
Antes de enviar arquivos, você precisa bloquear o código a partir do repositório do seu projeto no
Subversion. Para isso, são necessárias três informações: o URL do repositório (use a versão
precedida por https, e não por http), o nome de usuário e a senha. Para encontrar estas
informações, vá para a guia Source do seu projeto (http://code.google.com/p/<project-
name>/source). Ela deve conter algo como:
svn checkout https://<project-name>.googlecode.com/svn/trunk/ gadgets-test
--username <username>
Quando solicitado, digite a senha SVN que foi gerada.

Mantenha esta página aberta em um navegador para poder recuperar as informações apropriadas
conforme necessário.
Os detalhes do bloqueio atual podem variar dependendo do cliente do Subversion que você estiver
usando, mas o processo geral é o mesmo. As instruções desta seção supõem que você esteja
usando o TortoiseSVN.
Para bloquear um projeto:
1. Crie uma nova pasta no Windows Explorer e navegue para dentro da pasta.
2. Clique com o botão direito e selecione SVN Checkout... (Bloqueio no SVN).
3. Digite o URL do repositório e clique em OK. Nesta etapa, é necessário usar a versão do
URL do repositório precedida por https. Isso garante acesso de leitura e gravação. A versão
iniciada por http fornece acesso somente para leitura, e você não poderá adicionar ou enviar
arquivos.
4. O TortoiseSVN conecta-se ao servidor e tenta autenticar você. O nome de usuário e a senha
são solicitados. Digite o nome de usuário e a senha, marque a opção Save authentication
(Salvar autenticação) e clique em OK. Se o nome de usuário e a senha não forem
solicitados, volte à Etapa 3 e verifique se o URL do seu repositório começa com https (e não
com http).
Neste ponto, o cliente conecta e bloqueia todo o repositório. Pronto!

Se o bloqueio for concluído com sucesso, você verá uma nova pasta oculta, /.svn. Não modifique
nem exclua essa pasta.

Envio de arquivos
Depois de verificar seu projeto, você pode começar a adicionar novas pastas e arquivos ao diretório,
usando os comandos do Subversion. As instruções desta seção supõem que você esteja usando o
TortoiseSVN.
Para enviar um arquivo:
1. Crie um novo arquivo no diretório <project-name>.googlecode.com/svn/trunk/ e salve-o
(por exemplo, new-gadget.xml). Você pode colocar o arquivo diretamente no diretório
/trunk ou em um subdiretório de /trunk.
2. Clique com o botão direito no arquivo e selecione Add... (Adicionar...). Isso simplesmente
marca o arquivo como adicionado. Neste ponto, o arquivo ainda não foi enviado ao servidor.
Se você colocar o arquivo em um diretório que ainda não foi adicionado ao repositório,
também será necessário adicionar o diretório. Ao adicionar um diretório, todos os arquivos
dentro dele são adicionados também. As mesmas regras se aplicam para o envio de
alterações. Você não poderá enviar um arquivo ao repositório se o diretório no qual ele está
inserido não for enviado.
3. Continue editando o arquivo até que ele esteja pronto para ser enviado.
4. Quando estiver pronto para enviá-lo, clique no arquivo com o botão direito e selecione SVN
Commit... (Enviar para SVN...).
Quando solicitado, escreva uma observação opcional no log de mensagens e clique em OK. A
transferência do arquivo para o servidor é iniciada.
Quando o arquivo é transmitido para o servidor, o envio é concluído e o arquivo fica disponível
imediatamente on-line em http://<project-name>.googlecode.com/svn/trunk/new-gadget.xml. Para
apenas ler arquivos no repositório, basta usar a versão do URL do repositório que começa com http.
Dentro do seu repositório, você pode criar estruturas de diretório que serão refletidas no URL. Por
exemplo, se você adicionar e enviar um novo arquivo em /a/b/c/new-gadget.xml, o arquivo será
hospedado em http://<project-name>.googlecode.com/svn/trunk/a/b/c/new-gadget.xml.
Criação de uma interface de usuário
Este documento descreve como adicionar os diversos elementos de interface de usuário ao seu
gadget.

Gerenciamento da altura do gadget


Por padrão, os gadgets têm 200 pixels de altura. Você pode usar o atributo <ModulePrefs>
height="nn" para especificar uma altura estática maior ou menor que a altura padrão. Você pode
usar o atributo <ModulePrefs> scrolling="true" para criar uma barra de rolagem vertical
para o gadget, caso a altura do conteúdo exceda a altura designada.
Entretanto, alguns gadgets precisam ter flexibilidade para alterar sua altura dinamicamente. Por
exemplo, suponha que você criou um gadget de lista cuja altura precisa ser expandida e contraída,
dependendo do conteúdo da lista. O gadget cresce à medida que os usuários adicionam itens à lista.
Quando eles limpam a lista, o gadget retorna à altura original. Veja aqui a aparência do gadget
sendo executado:

Para adicionar ao seu gadget o recurso de redimensionamento, adicione os itens abaixo à


especificação:
• Uma tag <Require feature="dynamic-height"/> (em <ModulePrefs>) para
informar ao gadget que ele precisa carregar a biblioteca dynamic-height.
• Uma chamada à função JavaScript gadgets.window.adjustHeight() sempre que
houver uma alteração de conteúdo ou ocorrer outro evento que exija o redimensionamento
do gadget.
Por exemplo, veja abaixo a especificação do gadget de lista de compras:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Dynamic Height"
height="100">
<Require feature="dynamic-height"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
// This example lets users add items to a grocery list and then clear the
list.
// When items are added or cleared, the gadget resizes itself.
var mylist = "";
var flag = 0;
// Function that is invoked whenever user clicks the Add button to add an
// item to the list.
function addToList (form) {
var input = _trim(form.inputbox.value);
if (input == "") {
return;
}

// Make alternating lines green/white, depending on value of flag


variable.
if(flag == 0){
mylist += "<div style='padding-left: 5px;background-color: #E6FFE6;
font-family:Arial, Helvetica;'>" +input + "</div>";
flag = 1;
}
else {
mylist += "<div style='padding-left: 5px;font-family:Arial,
Helvetica;'>" +input + "</div>";
flag = 0;
}

// Call setContent to output HTML to div and resize gadget


setContent(mylist);
}

// Clear the list


function clearList(form) {
// Call setContent to remove all items from the list and resize the
gadget
setContent("");
}

// Outputs content to the div and resizes the gadget


function setContent(html) {
document.getElementById('content_div').innerHTML = html;

// Tells gadget to resize itself


gadgets.window.adjustHeight();
}
</script>
<FORM NAME="myform" ACTION="" METHOD="GET"><BR>
<INPUT TYPE="text" NAME="inputbox" VALUE="">
<INPUT TYPE="button" NAME="button" Value="Add" onClick="addToList(this.form)">
<INPUT TYPE="button" NAME="button2" Value="Clear"
onClick="clearList(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>

Para obter orientações sobre como testar a largura e a altura de um gadget, consulte Teste de largura
e altura.

Definição do título do gadget


Use a função gadgets.window.setTitle() para definir o título do gadget
programaticamente. Para usar esta função, seu gadget deve incluir:
• Em <ModulePrefs>, uma tag <Require feature="settitle"/> para informar
ao gadget que ele precisa carregar a biblioteca settitle.
• Uma chamada a gadgets.window.setTitle() para definir o título do gadget.
Este exemplo fornece um campo de texto que permite que o usuário defina o título do gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Set Title Example">
<Require feature="settitle"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
function changeTitle(form) {
var newTitle = form.inputbox.value;
gadgets.window.setTitle(newTitle);
}
</script>
<FORM NAME="myform" ACTION="" METHOD="GET">Change the Gadget Title: <BR><BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><BR><BR>
<INPUT TYPE="button" NAME="button" Value="Change Title"
onClick="changeTitle(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>

Guias
Use a biblioteca de guias para adicionar uma interface de usuário com guias ao seu gadget. Para
usar guias, a especificação do seu gadget deve incluir no mínimo:
• Em <ModulePrefs>, um tag <Require feature="tabs"/> para informar ao
gadget que ele precisa carregar a biblioteca tabs.
• JavaScript para criar as guias e preenchê-las com conteúdo. Para obter mais detalhes,
consulte Como funciona.
Também é comum incluir a biblioteca setprefs para que o gadget possa armazenar sempre a
última guia selecionada pelo usuário. Assim, se o usuário sair e retornar à página, o gadget carrega a
guia armazenada. Para aproveitar este recurso, incorpore duas linhas de código na especificação do
seu gadget:
<Require feature="setprefs"/>
...
<UserPref name="selectedTab" datatype="hidden"/>

Anatomia de um objeto de guias


A biblioteca de guias fornece funções e CSS para realizar operações com os objetos abaixo:
• Objeto TabSet. O objeto de guias é o recipiente-pai de todas as guias. Programaticamente, o
objeto de guias é uma matriz de objetos de guia individuais. Normalmente, a implementação
básica do HTML é um elemento <table>, mencionado na API como o "header
container" (recipiente de cabeçalho). Use a função
gadgets.TabSet.getHeaderContainer() para acessar este HTML.
• Objeto de guia. Um objeto de guia é uma única guia dentro de uma matriz de guias
indexadas. Normalmente, a implementação básica do HTML é um elemento <td>,
mencionado na API como o "name container" (recipiente de nome). Use a função
gadgets.Tab.getNameContainer() para acessar este HTML.
• Recipiente de conteúdo. Um objeto de recipiente de conteúdo contém o conteúdo de um
objeto de guia individual. Normalmente, a implementação básica do HTML é um elemento
<div>, mencionado na API como o "content container" (recipiente de conteúdo). Use a
função gadgets.Tab.getContentContainer() para acessar este HTML.

Como funciona
Use o construtor gadgets.TabSet() para criar um objeto de guias (ou seja, um objeto
contendo um conjunto de guias indexadas). Por exemplo:
// Initialize tabs, designate the tab named "Two" as
// the tab selected by default.
var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");

Depois de criar o objeto de guias, adicione as guias individuais a ele usando a função addTab().
Uma guia individual apresenta três componentes principais: um índice, um nome e um ID exclusivo
que é igual ao ID de um <div> correspondente. O <div> é o local onde o conteúdo da guia é
colocado. Se você não fornecer o recipiente de <div>, a biblioteca de guias irá gerá-lo.
O método addTab() utiliza os seguintes argumentos:
• String tabName -- Marcador da guia a ser criada.
• Object opt_params -- Objeto de parâmetro opcional. Ele pode incluir:
• contentContainer --Um elemento HTML existente para ser usado como
recipiente do conteúdo da guia. Se omitido, a biblioteca de guias cria um elemento.
• callback --função mA callback a ser executada quando a guia é selecionada.
• tooltip-- Uma descrição de dica de ferramenta que aparece quando o usuário
move o cursor do mouse sobre a guia.
• index -- É o índice no qual a guia será inserida. Se omitido, a nova guia é anexada
no final.
addTab() retorna uma string contendo o ID do DOM do recipiente da guia.
Você pode adicionar uma guia a um objeto de guias e preenchê-la com conteúdo usando uma das
maneiras descritas abaixo:
Técnica 1: Capture o ID da guia ao criá-la e use o ID para adicionar conteúdo ao <div>
correspondente da guia:
var one_Id = tabs.addTab("One");
document.getElementById(one_Id).innerHTML = "Content for tab One.";

Uma variação desta abordagem é definir o nome da guia em HTML. Por exemplo:
var one_Id = tabs.addTab('<div style="color: red; font-weight: bold; background-
color:#ccf;">Cool Tab</div>');
document.getElementById(one_Id).innerHTML = "Content for tab One.";

Técnica 2: Crie a guia e adicione um <div> correspondente à parte HTML do gadget; coloque o
conteúdo estático no <div>:
tabs.addTab("Two", "two_id");
...
</script>
<div id="two_id" style="display:none">Content for tab Two.</div>
Técnica 3: Crie a guia e adicione um <div> correspondente à parte HTML do gadget; coloque o
conteúdo estático no <div>: Use uma função de retorno de chamada para adicionar conteúdo
dinâmico ao conteúdo estático:
tabs.addTab("Three", "three_id", callback);
...
function callback(tabId) {
var p = document.createElement("p");
p.innerHTML = "This is dynamic content generated in callback.";
document.getElementById(tabId).appendChild(p);
}
...
</script>
<div id="three_id" style="display:none">This is static content for tab
Three.</div>

Técnica 4: Use a função addTab(tabName, opt_params) para adicionar uma guia por
nome. Por exemplo:
tabs.addTab("Tab", {
contentContainer: document.getElementById("domId"),
callback: func,
tooltip: "Popup description"

});

Aqui está um exemplo de gadget que mostra as maneiras diferentes de adicionar guias e preenchê-
las com conteúdo:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Tabs Demo" height="140" scrolling="true" >
<Require feature="tabs" />
</ModulePrefs>
<Content type="html">
<![CDATA[

<script type="text/javascript">
// Initialize tabs, designate the tab named "Two" as
// the tab selected by default.
var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");
function init() {
// Technique #1: Capture the tab's ID when you create it, and use the ID
// to add content to the tab's corresponding <div>.
var one_Id = tabs.addTab('<div style="color: red; font-weight: bold;
background-color:#ccf;">Cool Tab</div>');
document.getElementById(one_Id).innerHTML = "Content for tab One.";

// Technique #2: Create the tab and define a corresponding <div> in the
// HTML portion of the gadget. Add static content to the <div>.

tabs.addTab("Two", {
contentContainer: document.getElementById("two_id")
});

// Technique #3: Create the tab and define a corresponding <div> in the
// HTML portion of the gadget. Add static content to the <div>.
// Use a callback function to add dynamic content to the static content.

tabs.addTab("Three", {
contentContainer: document.getElementById("three_id"),
callback: callback
});
// Technique #4: Create the tab with a tooltip message. If specified
<div>
// doesn't exist, tabs library creates one.
// Invoke callback function.
tabs.addTab("Four", {
contentContainer: document.getElementById("four_id"),
callback: callback,
tooltip: "I'm special"
});
}

// Callback that provides content to tabs Three and Four


function callback(tabId) {
var p = document.createElement("p");
// Get selected tab
var selectedTab = tabs.getSelectedTab();
p.innerHTML = "This is dynamic content generated in callback for tab " +
selectedTab.getName();
document.getElementById(tabId).appendChild(p);
}

// Call init function to initialize and display tabs.


gadgets.util.registerOnLoadHandler(init);
</script>

<div id="two_id" style="display:none">Content for tab Two.</div>


<div id="three_id" style="display:none">This is static content for tab
Three.</div>
]]>
</Content>
</Module>

Manipulação de guias por índice


A API de guias também inclui funções que permitem a manipulação das guias por índice. As guias
são indexadas de 0 a n, onde 0 é a primeira guia. Por exemplo, se houver 3 guias, os índices são 0, 1
e 2. Você pode usar os índices para selecionar uma guia programaticamente e para trocar a posição
de duas guias.
Embora o ID de uma guia permaneça constante, o mesmo não ocorre com seu índice. Por exemplo,
se você mover a terceira guia para a primeira posição, o índice é alterado de 2 para 0.
Aqui está um exemplo de como selecionar uma guia programaticamente. Este snippet cria um link.
Quando o usuário clica no link, a segunda guia é selecionada, como se o usuário tivesse clicado na
própria guia:
<script>
...
function selectTab() {
tabs.setSelectedTab(1);
}
</script>

<a href="javascript:void(0)" onclick="selectTab()">Select Second Tab</a>

Aqui está um exemplo de como mover uma guia programaticamente. Este snippet cria um link.
Quando o usuário clica no link, o gadget troca as posições da primeira e da segunda guia:
<script>
...
function switchTabs() {
tabs.swapTabs(0, 1);
}

</script>
<a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>

Personalização da exibição de guias


Esta seção descreve como você pode personalizar a aparência de suas guias usando CSS ou
JavaScript.

Personalização de guias com CSS


A folha de estilo das guias está disponível em http://www.google.com/ig/tablib.css. Ela define as
classes aplicadas aos elementos HTML que definem as guias.
Você pode usar as classes CSS abaixo para ignorar a configuração padrão e modificar a aparência
das suas guias.
Classe CSS Descrição
.tablib_table Aplicável à tabela HTML que contém as guias.
.tablib_selected Aplicável à guia selecionada.
.tablib_unselected Aplicável a todas as guias não selecionadas.
.tablib_spacerTab Aplicável aos elementos de espaçamento entre cada guia.
.tablib_emptyTab Controla os espaçamentos de início e de fim em volta das guias.
.
Aplicável ao recipiente-pai, que contém todo o conteúdo relacionado às guias
tablib_main_cont
(ou seja, cabeçalhos de guia e todos os recipientes individuais de conteúdo).
ainer
.
tablib_content_co Aplicável a todos os recipientes de conteúdo da guia.
ntainer
Para obter uma lista com as classes e as configurações que podem ser ignoradas, acesse
http://www.google.com/ig/tablib.css.
<![CDATA[
<style type="text/css">
.tablib_selected { color: #FF0000; }
.tablib_unselected { color: #660099; }
.tablib_table { font-size:20px; }
.tablib_emptyTab { padding:2px 5px; }
.tablib_spacerTab { padding:0px 5px; }
</style>

<script...>

Você também pode usar JavaScript para aplicar estilos CSS ao recipiente de cabeçalho das guias. A
função getHeaderContainer() retorna a tabela HTML das guias, que você pode modificar
conforme desejar.
Por exemplo, este snippet altera o tamanho da fonte e adiciona margem no alto:
var tabs = new gadgets.TabSet();
...
var table = tabs.getHeaderContainer();
table.style.fontSize = "10px";
table.style.marginTop = "15px";
Você pode personalizar o estilo dos cabeçalhos de guias individuais, obtendo os elementos da guia
individual e modificando suas propriedades. Veja um exemplo que torna o estilo da primeira guia
exclusivo:
var tabs = new gadgets.TabSet();
tabs.addTab("Unique");
...
var firstTab = tabs.getTabs()[0].getNameContainer();
firstTab.style.backgroundColor = "#999999";
firstTab.style.color = "#ffffff";

Alteração de alinhamento da guia


Por padrão, as guias são centralizadas ao serem adicionadas. Entretanto, se houver menos que 3 ou
4 guias, você pode alinhá-las à esquerda ou à direita. Para isso, use a função alignTabs(). Ela
aceita um parâmetro com o valor left, right ou center. Se você for alinhar guias à esquerda
ou à direita, há um parâmetro opcional que pode ser passado para indicar a largura do deslocamento
em relação ao lado esquerdo ou direito. O tamanho padrão é 3px.
Por exemplo:
var tabs = new gadgets.TabSet();
...
// Align tabs to the left and offset it by 10 pixels
tabs.alignTabs("left", 10);

Como ocultar guias


Use a função displayTabs() para alternar a exibição das guias e de seu conteúdo. Esta função
assume o valor booleano de true ou false.
Aqui está um exemplo que cria um botão que exibe ou oculta as guias:
<input onclick="toggleTabs()" type="button" value="Show/Hide"/>
<script>
var tabs = new gadgets.TabSet();
...
var showTabs = true;
function toggleTabs() {
showTabs = !showTabs;
tabs.displayTabs(showTabs);
}
</script>

MiniMessages
Uma MiniMessage é uma mensagem temporária exibida aos usuários dentro de um gadget. As
MiniMessages foram criadas para serem eliminadas programaticamente ou pelo usuário. Os tipos
básicos de MiniMessages são:
• Mensagens dispensáveis que os usuários removem clicando em um [x].
• Mensagens de temporizador que desaparecem depois de decorrido um determinado período
de tempo em segundos.
• Mensagens estáticas que devem ser dispensadas programaticamente.
Para usar MiniMessages, a especificação do seu gadget deve incluir:
• Em <ModulePrefs>, uma tag <Require feature="minimessage"/> para
informar ao gadget que ele precisa carregar a biblioteca de MiniMessages.
• Funções JavaScript descrevendo o comportamento da MiniMessage. Consulte a Referência
para obter uma lista completa das funções da biblioteca de MiniMessages.
Veja alguns dos motivos para usar MiniMessages:
• Promoção: Você pode usar as MiniMessages para exibir uma mensagem promocional no
gadget.
• Status: Muitos gadgets obtêm e carregam dados em segundo plano. Você pode usar
MiniMessages para exibir "Carregando..." ou outras mensagens relacionadas a status.
• Depuração/erro: Se um gadget encontrar um erro, ele pode usar as MiniMessages para
notificar o usuário, em vez de falhar em silêncio.
• Outros: Dependendo do tipo de gadget (por exemplo, calendário, eBay), você pode exibir
notificações para os usuários. Como as MiniMessages são pequenas e dispensáveis, use-as
para comunicar informações especiais.

Como funciona
As etapas básicas da adição de uma MiniMessage ao gadget são simples:
1. Importe a biblioteca de MiniMessages:
<Require feature="minimessage"/>

2. Crie uma instância de um novo objeto de MiniMessage usando o construtor


gadgets.MiniMessage():
var msg = new gadgets.MiniMessage(__MODULE_ID__);

Na maioria dos casos, você criará um único objeto global que possa ser acessado por todos os
escopos.
3. Crie uma nova MiniMessage com um texto:
msg.createDismissibleMessage("Please close me when you're done reading me.");

Isso adiciona no início do gadget uma mensagem pré-formatada dispensável com um [x] associado
a ela. Quando os usuários clicam no [x], a mensagem é fechada.
Pronto! Você criou um dos diversos tipos de mensagens dispensáveis.

Criação de mensagens em locais diferentes


Por padrão, as mensagens são colocadas dentro de um elemento de recipiente de HTML bem no
início do gadget. Cada mensagem subseqüente é anexada como filha ao recipiente, em ordem
decrescente. Entretanto, você pode modificar esse comportamento para todas as mensagens ou para
uma única mensagem.

Definição de um local para todas as mensagens


Você pode passar um elemento HTML ao construtor, de preferência um <div>, para ignorar a
localização padrão do elemento de recipiente da mensagem. Esse elemento torna-se o recipiente no
qual as mensagens serão inseridas e exibidas.
Por exemplo, neste snippet, a mensagem <h3> "I'm on top now!" aparece no início do gadget. As
MiniMessages são exibidas abaixo dela em messageBox <div>, na ordem em que foram
adicionadas.
<div>
<h3>I'm on top now!</h3>
</div>

<div id="messageBox"></div>

<script type="text/javascript">
// In the constructor, state that messages should be be displayed
// in the messageBox <div> rather than at the top of the gadget.
var msg = new gadgets.MiniMessage(__MODULE_ID__,
document.getElementById("messageBox"));
msg.createDismissibleMessage("I'm the first message.");
msg.createDismissibleMessage("I'm the second message.");
msg.createDismissibleMessage("I'm at the bottom.");

</script>

Definição de um local para uma única mensagem


Você pode criar uma mensagem dispensável em uma localização designada em vez de anexá-la ao
recipiente da mensagem. Para isso, faça o markup da mensagem dentro da parte HTML do gadget.
Em seguida, passe o elemento HTML (de preferência um <div>) como o primeiro parâmetro a
createDismissibleMessage().
Por exemplo, neste snippet, a mensagem é exibida dentro do status <div>:
<div id="status" style="color:#B30000;">
<b>Check out our new API documentation!</b> --
<a href="http://www.google.com/apis/gadgets" target="_blank">Read</a>
</div>

<script type="text/javascript">
var msg = new gadgets.MiniMessage(__MODULE_ID__);
// Pass the HTML element to createDismissableMessage() to indicate
// where the message should be displayed.
msg.createDismissibleMessage(document.getElementById("status"));
</script>

Criação de mensagens usando métodos DOM


Pode haver casos em que você irá gerar a mensagem dispensável usando métodos HTML DOM.
Como a mensagem não existe no DOM, ela é anexada ao recipiente de mensagens por padrão.
Por exemplo:
<script type="text/javascript">
var msg = new gadgets.MiniMessage(__MODULE_ID__);
// Generate the message using DOM methods
var div = document.createElement("div");
div.innerHTML = "New message created by W3C DOM methods.";
// Set some DOM properties
div.onmouseover = function() {
div.style.backgroundColor = "green";
};
div.onmouseout = function() {
div.style.backgroundColor = "";
};
msg.createDismissibleMessage(div);

</script>
Criação de uma mensagem de temporizador
Uma mensagem de temporizador é pré-formatada para desaparecer depois de decorrido o período
de tempo especificado. A função createTimerMessage() aceita dois parâmetros: uma string
de mensagem e um número indicando a duração, em segundos, da exibição da mensagem. Por
exemplo:
var msg = new gadgets.MiniMessage(__MODULE_ID__);
msg.createTimerMessage("I'm going to disappear in 5 seconds.", 5);

Criação de uma mensagem estática


Uma mensagem estática é pré-formatada para ser exibida até ser dispensada programaticamente
pela função dismissMessage(). Isso é útil para exibir mensagens de notificação que
mantenham o usuário informado durante a execução de tarefas do gadget em segundo plano, como a
obtenção de conteúdo. Por exemplo:
var msg = new gadgets.MiniMessage(__MODULE_ID__);
var loadMessage = msg.createStaticMessage(document.getElementById("loading"));

Personalização da exibição de MiniMessages


Há duas maneiras de se alterar a aparência padrão de MiniMessages:
• Altere a aparência das mensagens individuais.
• Altere a aparência de todas as mensagens de forma global.

Alteração do estilo de mensagens individuais


Use funções DOM para alterar o estilo de uma mensagem. Um elemento HTML é retornado quando
você cria uma nova mensagem dispensável. Você pode modificar a aparência da mensagem
configurando as propriedades de estilo desse elemento HTML retornado. Por exemplo:
<script type="text/javascript">
var msg = new gadgets.MiniMessage(__MODULE_ID__);
var statusMsg = msg.createDismissibleMessage("This is a critical error!");
// Change the message's background color to red
statusMsg.style.backgroundColor = "red";
statusMsg.style.color = "white";
</script>

Observação: Este exemplo mostra a forma correta de alterar totalmente a cor de fundo de uma
mensagem. A cor de fundo não será totalmente alterada se apenas a configuração da cor de fundo do
<div> que contém a mensagem for alterada.

Alteração do estilo de todas as mensagens


Use CSS globalmente para alterar o estilo de todas as mensagens. A folha de estilo das
MiniMessages está disponível em http://www.google.com/ig/minimessagelib.css. Ela define as
classes aplicadas aos elementos HTML que definem as MiniMessages.
Você pode usar as classes CSS abaixo para ignorar a configuração padrão e modificar a aparência
de suas mensagens.
Classe CSS Descrição
.mmlib_table Aplicável à tabela HTML que contém a mensagem.
.mmlib_xlink Aplicável ao link [x] usado para dispensar uma mensagem. A
configuração se aplica somente à mensagem dispensável.
Por exemplo, isto altera a cor de fundo para azul marinho e a cor principal para branco:
<![CDATA[
<style>

.mmlib_table__MODULE_ID__ {
background-color: #000066;
color: #ffffff;
}
</style>
<script...>

Flash
Use a biblioteca flash para incorporar um filme Flash (especificamente, um arquivo .swf) em
seu gadget. Para incorporar conteúdo Flash, a especificação do seu gadget deve incluir no mínimo:
• Em <ModulePrefs>, uma tag <Require feature="flash"/> para informar ao
gadget que ele precisa carregar a biblioteca flash.
• Uma chamada a gadgets.flash.embedFlash() para incorporar um arquivo .swf
no gadget e exibi-lo em um local designado. Para usar esse recurso, todos os recursos devem
estar em um único arquivo .swf.
A biblioteca flash inclui as seguintes funções:
Função Descrição
Incorpora o arquivo .swf especificado por swf_url e o
exibe no gadget no local especificado por swf_container.
O parâmetro opt_params é um objeto opcional que pode
conter qualquer parâmetro html válido.

gadgets.flash.embedFlas Rretorna true se for bem-sucedido, ou false se falhar.


h(swf_url,
swf_container, Observação: Se ocorrerem problemas de desempenho ou se o
swfVersion, opt_params) gadget não for exibido (esse problema ocorre às vezes no
Firefox 2.0), tente configurar wmode expressamente como
"window", conforme mostrado abaixo:
gadgets.flash.embedFlash("example.swf",
"wrapper", {wmode: "window"});

gadgets.flash.embedCach
Injeta um arquivo Flash com cache na árvore DOM. Os
edFlash(swf_url,
parâmetros e o valor retornado são os mesmos do método
swf_container,
embedFlash().
swfVersion, opt_params)
gadgets.flash.getMajorV Retorna a principal versão do Flash Player, ou zero se o Flash
ersion() Player não for detectado.

Exemplo de Flash
Quando você clica em algum botão deste exemplo de gadget, ele reproduz o arquivo .swf
correspondente. Quando você clica em Stop, o gadget exibe uma fotografia estática.
Aqui está a especificação do gadget do exemplo:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Trevor Does Tricks" height="300">
<Require feature="flash" />
</ModulePrefs>
<Content type="html">
<![CDATA[

<style type="text/css">
input.mybutton
{
background-color:#FFCC99;
border-style:solid;
border-color:#000000;
font-family:Comic Sans MS,sans-serif;
font-size:14px;
}
</style>

<div id="flashcontainer" style="text-align: center;"></div>

<script type="text/javascript">
// Display still photo.
function showPhoto() {
document.getElementById("flashcontainer").innerHTML = "<img
src='http://doc.examples.googlepages.com/Trevor.JPG' />";
}
// Play .swf file for specified trick.
function doTrick(trick) {

// The URL for the .swf file that shows the specified trick.
var url = "http://doc.examples.googlepages.com/Trevor-"+trick+".swf";

// Play .swf file.


gadgets.flash.embedFlash(url, "flashcontainer", {
swf_version: 6,
id: "flashid",
width: 300,
height: 250
})
}

// When gadget first loads, display still photo.


gadgets.util.registerOnLoadHandler(showPhoto);
</script>
<br />
<div style="text-align: center;">
<input type=submit class="mybutton" value="Spin" onClick="doTrick('spin')">
<input type=submit class="mybutton" value="Speak"
onClick="doTrick('speak')">
<input type=submit class="mybutton" value="Sit" onClick="doTrick('sit')">
<input type=submit class="mybutton" value="Down" onClick="doTrick('down')">
<input type=submit class="mybutton" value="Stop" onClick="showPhoto()">
</div>
]]>
</Content>
</Module>
Uso de conteúdo remoto
Este documento descreve como obter e manipular dados remotos textuais (normalmente HTML),
XML, JSON e de feeds RSS/Atom.

Introdução
A capacidade de combinar informações de diversas fontes de maneiras novas ou de fornecer meios
alternativos de interação com informações existentes é um dos recursos mais empolgantes
disponíveis para os gadgets. A API de gadgets permite que o gadget obtenha remotamente conteúdo
de outros servidores e páginas da web e realize operações com esse conteúdo.
A API de gadgets fornece a função makeRequest(url, callback, opt_params) para
recuperação e operação com conteúdo da web remoto. Ela aceita os seguintes argumentos:
• String url - O URL no qual o conteúdo está localizado
• Function callback - A função a ser chamada com os dados do URL após a obtenção
• Map.<gadgets.io.RequestParameters, Object> opt_params - Parâmetros
adicionais a serem passados para a solicitação
O argumento opt_params permite especificar:
• O tipo de conteúdo da solicitação (atualmente suportados: TEXT, XML e JSON)
• O tipo de método da solicitação (POST ou GET)
• Qualquer cabeçalho que você deseje incluir na solicitação
• O tipo de autorização (suportado atualmente: NONE ou SIGNED)
Para ler mais sobre os parâmetros opcionais que podem ser passados, consulte o artigo Introdução à
função makeRequest.
Observação: Você não pode usar makeRequest() com gadgets type="url".
Independentemente do tipo de dados sendo obtidos, as chamadas a makeRequest()
compartilham as mesmas características:
• Seu primeiro parâmetro é um URL usado para obter o conteúdo remoto.
• Seu segundo parâmetro é uma função de retorno de chamada, usada para processar os dados
retornados.
• Elas são assíncronas, ou seja, todo o processamento deve ocorrer dentro da função de
retorno de chamada. Um retorno de chamada é uma função passada como parâmetro (na
forma de uma referência de função) a outra função. Os retornos de chamada fornecem aos
desenvolvedores um "gancho" que pode ser conectado a uma estrutura em execução para
realizar processamentos.
• Eles não têm valores de retorno porque são retornados imediatamente, e as funções de
retorno de chamada a eles associadas são chamadas sempre que a resposta é retornada.
Por exemplo, pense no seguinte snippet de código, que obtém conteúdo remoto em forma de texto.
Este código obtém o texto HTML da página google.com da web e exibe os primeiros 400
caracteres:
function getHtml() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
var url = "http://www.google.com";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
//obj.text contains the text of the page that was requested
var str = obj.text;
var html = str.substr(0,400);
document.getElementById('content_div').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getHtml);

Este exemplo ilustra os princípios básicos por trás do funcionamento da função makeRequest():
1. Quando a função makeRequest() é chamada, a API de gadgets faz uma solicitação
HTTP GET assíncrona ao URL passado à função (neste exemplo, o URL é
http://www.google.com).
2. makeRequest() é retornada imediatamente e chama a função de retorno de chamada
posteriormente (neste exemplo, denominada response()), quando todo o conteúdo é
obtido. Isso significa que você deve colocar todos os códigos dependentes dentro da função
de retorno de chamada ou dentro de funções chamadas pela função de retorno de chamada.
3. makeRequest() retorna um objeto JavaScript com a seguinte estrutura:
{
data : <parsed data, if applicable>,
errors : <any errors that occurred>,
text : <raw text of the response>
}

Este objeto é fornecido somente como o argumento para a função de retorno de chamada. A função
de retorno de chamada executa algumas operações com os dados retornados. Normalmente, ela
extrai partes dos dados, combina-os com markup HTML e exibe o HTML resultante no gadget.

Uso de tipos de conteúdo diferentes


Como padrão, o conteúdo de um site remoto é retornado como texto. Você pode usar o campo
opt_params para definir o conteúdo retornado como um dos seguintes tipos:
• TEXT -- gadgets.io.ContentType.TEXT
• DOM -- gadgets.io.ContentType.DOM
• JSON -- gadgets.io.ContentType.JSON

Uso de texto
Aqui está um exemplo que obtém dados de um arquivo CSV (valores separados por vírgulas) e os
utiliza para preencher uma lista de contatos pessoais. Ele mostra como definir o tipo do conteúdo
obtido nos parâmetros opcionais. Na função response(obj) de retorno de chamada, o valor do
texto é extraído de obj usando obj.text:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch Text Example"/>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">

// This example fetches data from a CSV file containing contact information.
In the CSV file,
// each record consists of a name, email address, and phone number.
function getContacts() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-
gadgets/Contacts.csv";
gadgets.io.makeRequest(url, response, params);
};
// Callback function to process the response
function response(obj) {
var responseText = obj.text;
// Set CSS for div.
var html = "<div style='padding: 5px;background-color: #FFFFBF;font-
family:Arial, Helvetica;"
+ "text-align:left;font-size:90%'>";

// Use the split function to extract substrings separated by comma


// delimiters.
var contacts = responseText.split(",");
// Process array of extracted substrings.
for (var i = 0; i < contacts.length ; i++) {
// Append substrings to html.
html += contacts[i];
html += " ";

// Each record consists of 3 components: name, email, and


// phone number. The gadget displays each record on a single
// line:
//
// Mickey Mouse mickey@disneyland.com 1-800-MYMOUSE
//
// Therefore, insert a line break after each (name,email,phone)
// triplet (i.e., whenever (i+1) is a multiple of 3).
if((i+1)%3 ==0) {
html += "<br>";
}
}
html += "</div>";
// Output html in div.
document.getElementById('content_div').innerHTML = html;
}
gadgets.util.registerOnLoadHandler(getContacts);

</script>
]]>
</Content>
</Module>

Uso de XML
O DOM (Document Object Model, Modelo de objeto de documento) é uma API para navegação em
documentos HTML e XML. Você pode usar makeRequest() para recuperar um documento
XML como um objeto DOM. Você pode operar o objeto obtido usando funções DOM JavaScript
padrão. Normalmente, isso significa extrair os dados desejados do arquivo XML, combiná-los com
markup HTML e CSS e exibir o HTML resultante em seu gadget.
Com o DOM, o conteúdo da web é analisado em uma árvore de nós. Por exemplo, veja o snippet de
HTML abaixo:
<a href="http://www.google.com/">Google's <b>fast</b> home page.</a>

Este trecho ilustra os principais tipos de nós discutidos nesta seção:


• Nós de elemento. Os nós de elemento deste snippet são “a” e “b”. Os nós de elemento são os
blocos que definem a estrutura de um documento.
• Nós de texto. Os nós de texto deste trecho são ‘Google’s’, ‘fast’ e ‘home page’. Os nós de
texto são sempre inseridos em nós de elemento. Eles são os nós-filho do nó de elemento em
que estão inseridos.
• Nós de atributo. Este snippet apresenta um nó de atributo: href=’http://www.google.com’.
Um nó de atributo fornece informações adicionais sobre o nó de elemento em que está
inserido. Entretanto, os atributos não são considerados nós-filho dos elementos em que estão
inseridos, o que afeta o modo como você trabalha com eles. Para ler mais sobre este tópico,
consulte Uso de tipos de nó diferentes.
Esta é a estrutura DOM do snippet do HTML:

Para acessar os dados de um objeto DOM você "percorre a árvore", usando funções DOM para
navegar pelos relacionamentos de nó pai-filho e chegar aos dados necessários.

Exemplo
O arquivo XML abaixo contém dados para uma série de itens de café da manhã. O primeiro nó-pai
é menu, que possui diversos nós-filho food. O nó menu também contém um nó de atributo:
title="Breakfast Menu". Cada nó food possui os nós-filho name, price, description e calories.
Os nós name, price e calories contêm seus próprios nós-filho de texto. Cada nó description contém
um nó-filho CDATA. CDATA é um tipo distinto de nó. As seções CDATA são usadas para adicionar
códigos de escape a blocos de texto contendo caracteres (como sinais de menor e maior) que, de
outra forma, seriam considerados markup. O único separador reconhecido em uma seção CDATA é
a string "]]>", que finaliza a seção CDATA.
<?xml version="1.0" encoding="UTF-8" ?>
<menu title="Breakfast Menu">
<food>
<name>Early Bird Breakfast</name>
<price>$3.95</price>
<description><![CDATA[<div style="color:purple; padding-left:25px;">Two
eggs any style with your choice of bacon
or sausage, toast or English muffin.</div>]]></description>
<calories>450</calories>
</food>

<food>
<name>Chocolate Chip Belgian Waffles</name>
<price>$7.95</price>
<description><![CDATA[<div style="color:purple; padding-left:
25px;">Chocolate chip Belgian waffles covered with
chocolate syrup and whipped cream.</div>]]></description>
<calories>900</calories>
</food>


</menu>

O exemplo de gadget a seguir usa este arquivo XML como fonte de dados. Ele exibe um menu de
café da manhã e permite que os usuários definam um limite de calorias. Ele exibe qualquer caloria
acima do limite especificado em vermelho. Os usuários também podem selecionar se desejam exibir
as descrições de cada item do café da manhã.
O código a seguir ilustra como percorrer a árvore DOM para extrair os dados dos diferentes tipos de
nó, e como combiná-los a markup HTML e CSS para serem exibidos no gadget de menu de café da
manhã.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch XML" scrolling="true"/>
<UserPref
name="mycalories"
display_name="Calorie limit"
default_value="800"/>
<UserPref
name="mychoice"
display_name="Show Descriptions"
datatype="bool"
default_value="false"/>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
// get prefs
var prefs = new gadgets.Prefs();
// Calorie limit set by user
var calorieLimit = prefs.getString("mycalories");
// Indicates whether to show descriptions in the breakfast menu
var description = prefs.getBool("mychoice");

function makeDOMRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.DOM;
var url = "http://gadget-doc-
examples.googlecode.com/svn/trunk/opensocial-gadgets/breakfast-data.xml";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
// Start building HTML string that will be displayed in <div>.
// Set the style for the <div>.
var html = "<div style='padding: 5px;background-color: #ccf;font-
family:Arial, Helvetica;"
+ "text-align:left;font-size:90%'>";
// Set style for title.
html +="<div style='text-align:center; font-size: 120%; color: yellow; "
+ "font-weight: 700;'>";
// obj.data contains a Document DOM element corresponding to the
// page that was requested
var domdata = obj.data;
// Display menu title. Use getElementsByTagName() to retrieve the <menu>
element.
// Since there is only one menu element in the file,
// you can get to it by accessing the item at index "0".
// You can then use getAttribute to get the text associated with the
// menu "title" attribute.
var title =
domdata.getElementsByTagName("menu").item(0).getAttribute("title");

// Alternatively, you could retrieve the title by getting the menu


element node
// and calling the "attributes" function on it. This returns an array
// of the element node's attributes. In this case, there is only one
// attribute (title), so you could display the value for the attribute
at
// index 0. For example:
//
// var title =
domdata.getElementsByTagName("menu").item(0).attributes.item(0).nodeValue;

html += title + "</div><br>";


// Get a list of the <food> element nodes in the file
var itemList = domdata.getElementsByTagName("food");

// Loop through all <food> nodes


for (var i = 0; i < itemList.length ; i++) {
// For each <food> node, get child nodes.
var nodeList = itemList.item(i).childNodes;

// Loop through child nodes. Extract data from the text nodes that are
// the children of the associated name, price, and calories element
nodes.
for (var j = 0; j < nodeList.length ; j++) {
var node = nodeList.item(j);
if (node.nodeName == "name")
{
var name = node.firstChild.nodeValue;
}
if (node.nodeName == "price")
{
var price = node.firstChild.nodeValue;
}
if (node.nodeName == "calories")
{
var calories = node.firstChild.nodeValue;
}
// If the user chose to display descriptions and
// the child node is "#cdata-section", grab the
// contents of the description CDATA for display.
if (node.nodeName == "description" && description==true)
{
if (node.firstChild.nodeName == "#cdata-section")
var data = node.firstChild.nodeValue;
}
}
// Append extracted data to the HTML string.
html += "<i><b>";
html += name;
html += "</b></i><br>";
html += "&emsp;";
html += price;
html += " - ";
// If "calories" is greater than the user-specified calorie limit,
// display it in red.
if(calories > calorieLimit) {
html += "<font color=#ff0000>";
html += calories + " calories";
html += " </font>";
}
else
html += calories + " calories";
html += "<br>";
// If user has chosen to display descriptions
if (description==true)
{
html += "<i>" + data + "</i><br>";
}
}
// Close up div
html += "</div>";
document.getElementById('content_div').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(makeDOMRequest);
</script>
]]>
</Content>
</Module>

Esta amostra de código ilustra quatro das principais funções usadas para interagir com dados DOM:
• getElementsByTagName(tagname)-- Para um documento DOM, retorna uma matriz dos nós
de elemento cujos nomes correspondem a tagname. Você pode recuperar todos os nós de
elemento de um arquivo usando o caractere curinga (*), por exemplo:
response.getElementsByTagName("*").
• getElementById(id)-- Para um documento DOM, recupera um único nó por id.
• getAttribute(attrib)-- Para um nó de elemento, retorna o atributo attrib. Por exemplo:
response.getElementsByTagName("menu").item(0).getAttribute("title").
• attributes -- Para um nó de elemento, retorna uma matriz dos atributos do nó.
Este exemplo mostra somente algumas das diferentes funções para a navegação em uma árvore
DOM. Experimente algumas das outras funções que você usar, como lastChild, nextSibling,
previousSibling e parentNode.

Uso de tipos de nó diferentes


A chave para usar DOM de forma eficaz é compreender que, às vezes, há diferenças sutis entre
diferentes tipos de nó.
Tipo de Valores
Descrição Armadilhas
nó retornados
elemento Os blocos estruturais de nodeName: Um elemento tem nodeValue null. Para
um documento, como Qualquer texto obter o valor de um nó de texto ou atributo
<p> , <b> ou <calories>. entre os sinais associado a um elemento, é necessário ir
de menor e para esses nós. Por exemplo:
maior. Por element.firstChild.nodeValue para texto e
exemplo, o element.getAttribute(attrib) para atributos.
nodeName de
<menu> é
“menu”.

nodeType: 1
nodeValue : null
Alguns navegadores exibem todos os
espaços em branco de um documento como
nodeName: nós de texto. Assim, seu objeto DOM irá
#text conter nós de texto "vazios". Isso poderá
Texto. Um nó de texto é gerar resultados inesperados quando você
text sempre inserido em um nó nodeType: 3 percorrer a árvore. Para solucionar esse
de elemento. Ele é filho do problema, basta filtrar os nós de texto que
elemento. nodeValue: contêm somente o caractere de nova linha.
Qualquer texto Ou você pode realizar uma manipulação
inserido no nó. mais robusta. Para ler mais sobre este
tópico, consulte Espaços em branco no
DOM.
nodeName: O
valor à esquerda
do par de
atributo. Se o Embora os atributos sejam nós e estejam
atributo for inseridos em nós de elemento, eles não são
Um par de chave-valor que title=”my nós-filho do elemento. Eles são herdados
fornece informações document”, da interface de Node, mas o DOM não os
adicionais sobre um nó de nodeName será considera parte da árvore DOM. Isso
elemento (por exemplo, title. significa que, embora você possa usar
atributo
title=”my document”). Um muitas das funções de nó com os nós de
atributo é inserido em um nodeType: 2 atributo (como nodeName, nodeValue e
nó de elemento, mas não é nodeType), não é possível acessar nós de
filho do nó de elemento. nodeValue: O atributo usando as funções de navegação da
valor à direita do árvore DOM. Para acessar os atributos, use
par de atributo as funções attributes e getAttribute(attrib).
(neste exemplo,
“my
document”).
Uma seção na qual o
conteúdo não é
manipulado ou
nodeName:
interpretado. As seções
#cdata-section
CDATA são usadas para
adicionar códigos de
nodeType: 4
escape a blocos de texto O texto da seção CDATA tem seu próprio
CDATA contendo caracteres que, markup. Isso pode afetar o modo como
nodeValue:
de outra forma, seriam você irá incorporá-lo ao gadget.
Texto e markup
considerados markup. O
dentro dos
único separador
separadores
reconhecido em uma seção
CDATA.
CDATA é a string "]]>",
que finaliza a seção
CDATA.

Outros recursos
• Núcleo DOM W3C
• Tutorial do DOM JavaScript
Uso de feeds
Adicione um feed à sua página do iGoogle digitando seu URL no formulário Add by URL
(Adicionar por URL) do diretório de conteúdo. Esse formulário utiliza o suporte integrado da API
de gadgets para criar um gadget para o feed e adicioná-lo ao iGoogle. É fácil de usar, mas não
permite qualquer personalização do conteúdo ou da exibição. Além disso, você não pode usá-lo com
outros recipientes.
Para manipular feeds de maneira mais sofisticada, use o método makeRequest(). Embora a
especificação dos gadgets para makeRequest() inclua um tipo de conteúdo FEED, este recurso
ainda não é suportado por nenhum recipiente. Como alternativa, você pode processar um feed
usando o tipo de conteúdo DOM, como mostrado abaixo.
O exemplo a seguir ilustra como usar a função makeRequest() para obter um feed e exibir
partes de seus dados em um gadget. Aqui está o gadget. Ele permite que os usuários especifiquem:
• O número de entradas exibidas
• Se o gadget exibirá a data e um resumo de cada entrada

Este é o código do exemplo:


<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch Feed Example"
title_url="http://groups.google.com/group/Google-Gadgets-API"
scrolling="true">
</ModulePrefs>
<UserPref name="show_date" display_name="Show Dates?" datatype="bool"
default_value="false"/>
<UserPref name="show_summ" display_name="Show Summaries?" datatype="bool"
default_value="false"/>
<UserPref name="num_entries" display_name="Number of Entries:"
default_value="5"/>
<Content type="html">
<![CDATA[
<style> #content_div { font-size: 80%; margin: 5px; background-color:
#FFFFBF;} </style>
<div id="content_div"></div>
<script type="text/javascript">

// Get userprefs
var prefs = new gadgets.Prefs();
var showdate = prefs.getBool("show_date");
var summary = prefs.getBool("show_summ");
var entries = prefs.getInt("num_entries");
function makeDOMRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.DOM;
var url = "http://groups.google.com/group/Google-Gadgets-
API/feed/rss_v2_0_msgs.xml";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
// obj.data contains a Document DOM element corresponding to the
// page that was requested
var domdata = obj.data;
// Display the field title
var title = getFeedTitle(domdata);
var html = "<div><b>" + title + "</b></div>";

// Get a list of the <item> element nodes in the file


var itemList = domdata.getElementsByTagName("item");
// If user requested more entries than are in array, set "entries" to be
// the number of items in the array.
if (entries > itemList.length)
{
entries = itemList.length;
}
// Loop through all <item> nodes
for (var i = 0; i < entries ; i++) {
// For each <item> node, get child nodes.
var nodeList = itemList.item(i).childNodes;

// Loop through child nodes. Extract data from the text nodes that are
// the children of the associated name, price, and calories element
nodes.
for (var j = 0; j < nodeList.length ; j++) {
var node = nodeList.item(j);
if (node.nodeName == "title") {
var name = node.firstChild.nodeValue;
}
if (node.nodeName == "link")
{
var link = node.firstChild.nodeValue;
}
if (node.nodeName == "pubDate")
{
var date = node.firstChild.nodeValue;
}
if (node.nodeName == "description")
{
var desc = node.firstChild.nodeValue;
}
}
html += "<div>"
+ "<a target='_blank' href='" + link + "'>"
+ name
+ "</a>";
if (showdate==true)
{
html += "<br><i>" + date + "</i>";
}
if (summary==true)
{
html += "<br><i>" + desc + "</i>";
}
html += "</div";
}
document.getElementById('content_div').innerHTML = html;
};

// Return the feed title. This function just grabs the first element named
"title" in the feed.
function getFeedTitle(dat) {
var titles = dat.getElementsByTagName("title");
var feed_title = titles.item(0).firstChild.nodeValue;
return feed_title;
};
gadgets.util.registerOnLoadHandler(makeDOMRequest);
</script>
]]>
</Content>
</Module>

Uso de JSON
Use o tipo de conteúdo JSON para obter conteúdo com codificação JSON em forma de objeto
JavaScript.
O aplicativo descrito abaixo obtém o conteúdo de uma página PHP de amostra que contém a
seguinte string em codificação JSON:
{"validated":"This request was spoofed","query":
[],"url":"http:\/\/graargh.returnstrue.com\/buh\/fetchme.php","signature":"","si
gnature_len":1}

Ao obter conteúdo da página PHP contendo esta string, o valor retornado é um objeto JavaScript
contendo pares de chave e valor (ou seja, uma matriz associativa). Esta amostra recupera o objeto e
imprime os pares de chave e valor nele contidos:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch JSON 8">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">

function makeJSONRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.JSON;
// This URL returns a JSON-encoded string that represents a JavaScript
object
var url = "http://graargh.returnstrue.com/buh/fetchme.php";
gadgets.io.makeRequest(url, response, params);
};

function response(obj) {
var jsondata = obj.data;
var html = "<strong>Values: </strong><br /><br />";
// Returned JS object can be processed as an associative array
for (var key in jsondata) {
var item = jsondata[key];
html += key + ": ";
html += item + "<br />";
}
document.getElementById('content_div').innerHTML = html;
};
makeJSONRequest();
</script>
]]>
</Content>
</Module>

Atualização do cache
Se estiver usando a função makeRequest() para obter conteúdo atualizado mais de uma vez por
hora, como dados de feeds, pode ser que você não obtenha as últimas atualizações. Isso ocorre
porque seus resultados são armazenados em cache para tornar a execução do gadget mais rápida. Se
você quiser ter certeza de que o gadget obteve os dados mais recentes, use o parâmetro
refreshInterval para ignorar o cache e forçar uma atualização no intervalo que você
especificar. Em outras palavras, o cache é atualizado a cada X segundos, onde X =
refreshInterval.
Como padrão, as chamadas à função makeRequest são armazenadas em cache. No exemplo
abaixo, a função wrapper usa os mesmos parâmetros da chamada à função makeRequest, mas
aceita outro parâmetro denominado refreshInterval, que permite especificar a duração do
cache.
function makeCachedRequest(url, callback, params, refreshInterval) {
var ts = new Date().getTime();
var sep = "?";
if (refreshInterval && refreshInterval > 0) {
ts = Math.floor(ts / (refreshInterval * 1000));
}
if (url.indexOf("?") > -1) {
sep = "&";
}
url = [ url, sep, "nocache=", ts ].join("");
gadgets.io.makeRequest(url, response, params);
}

O uso de cache tem uma finalidade específica. Tome cuidado para não atualizar o cache com muita
freqüência, para não prejudicar o desempenho. O uso de cache agiliza a obtenção de dados. Ele
também reduz a carga sobre os servidores de terceiros que hospedam o conteúdo remoto. Evite
desativar o cache completamente (o que é feito usando-se o valor refreshInterval: 0). Se o
gadget estiver recebendo milhões de visualizações de página por dia e enviando milhões de
solicitações a estes servidores, desativar o cache não apenas afetará negativamente o desempenho
do gadget de maneira negativa, mas também poderá sobrecarregar os servidores que fornecem
dados ao seu gadget.
Como o padrão é atualizar o conteúdo a cada hora, o ideal é especificar um intervalo menor que
uma hora. O intervalo recomendado para refreshInterval é mais de 60 e menos de 3.600.
Gadgets e internacionalização (i18n)
Este documento descreve como criar gadgets que possam ser facilmente localizados para um
público internacional.

Introdução
A API de gadgets oferece uma maneira fácil de você disponibilizar seu gadget para um público
internacional. É simples: basta estruturar o gadget de forma que o texto visível para o usuário
(qualquer texto que será traduzido) esteja em pacotes de mensagens separados do gadget. Assim,
qualquer tradutor de terceiros pode traduzir suas strings e criar novos pacotes de mensagens
específicos ao local, os quais você pode adicionar à especificação do seu gadget. Dessa forma, seu
gadget fica disponível para um novo grupo de usuários.
Para ler mais sobre como criar gadgets em idiomas diferentes do inglês, consulte Gadgets em
idiomas diferentes do inglês.

Conceitos básicos
Este documento refere-se à internacionalização (i18n) e à localização (l10n):
• Internacionalizar significa estruturar aplicativos de forma a possibilitar sua localização.
• Localizar significa fazer um aplicativo funcionar para um mercado específico, como
canadenses francófonos.
Para a finalidade deste documento, o “perfil de localização” de um usuário consiste em dois
componentes: um país (com base no domínio do usuário) e um idioma de interface preferido pelo
usuário (consulte a seção Teste para obter mais detalhes).

Codificação para a internacionalização


A API de gadgets suporta codificação UTF-8 para valores de atributos XML e também na seção
<Content>. Quando o tipo de conteúdo é definido como html, a codificação padrão é definida
expressamente como UTF-8. Você não deve tentar defini-la sozinho.

Exemplo
O exemplo de gadget usado neste documento exibe a mensagem “Hello World,” mostrada aqui em
chinês:

Neste exemplo, o menu suspenso de preferências do usuário permite que o usuário especifique uma
cor de fonte para a mensagem “Hello World”. Os nomes das cores que aparecem no menu são
arquivos externos definidos (pacotes de mensagens). O idioma no qual o menu será exibido
depende do perfil de país/idioma do usuário. Se um usuário com perfil inglês executar este gadget, o
texto aparecerá em inglês. Veja aqui a aparência da versão em inglês do exemplo, com o menu
suspenso userprefs sendo exibido:
Você pode ver a especificação do gadget Hello World aqui.

Criação de um gadget localizado


As etapas básicas para a criação de um gadget localizado são:
1. Criar o gadget.
2. Extrair todo o texto que precisa de tradução e colocá-lo em pacotes de mensagens.
3. Encontrar alguém que possa ajudá-lo a traduzir o gadget.
4. O tradutor cria um novo pacote de mensagens para um local específico. Esse local pode ser
definido por idioma (francês) ou por idioma/país (francês/Canadá, francês/França). Os
pacotes de mensagens em idiomas diferentes do inglês devem ser salvos no formato UTF-8.
5. O tradutor envia um URL do novo pacote a você.
6. Modifique a especificação do gadget para usar o pacote de mensagens.
7. Se o gadget estiver no diretório de conteúdo, aguarde de 1 a 2 semanas para que o indexador
e as informações possam encontrar seu gadget atualizado e você possa então disponibilizá-lo
no novo mercado.

Pacotes de mensagens
O elemento principal da estratégia de internacionalização de gadgets são os pacotes de mensagens.
Os pacotes de mensagens são arquivos XML que contêm as strings traduzidas para um dado local.
Cada string é identificada por um nome exclusivo e esse mesmo nome é usado em todos os pacotes.
Os pacotes de mensagens podem ser hospedados por qualquer URL e compartilhados entre
aplicativos. Cada pacote de mensagens contém somente um local.
Os pacotes de mensagens têm o seguinte formato:
<messagebundle>
<msg name="hello_world">
Hello World.
</msg>
<msg name="color">Color</msg>
<msg name="red">Red</msg>
<msg name="green">Green</msg>
<msg name="blue">Blue</msg>
<msg name="gray">Gray</msg>
<msg name="purple">Purple</msg>
<msg name="black">Black</msg>
</messagebundle>

Veja abaixo os campos que você pode incluir em um arquivo de pacote de mensagens:
• messagebundle: Um grupo de mensagens para tradução.
• msg: Um único item de conteúdo traduzível, normalmente um marcador, frase ou parágrafo.
• msg name: Um ID legível para cada mensagem.
Convenções de nomenclatura
A convenção é nomear os pacotes de mensagens como descrito abaixo:
<language>_<country>.xml

Onde não houver um valor específico ao idioma ou ao país, a convenção é usar "ALL". Por
exemplo, o arquivo de_ALL.xml aplica-se a todas as pessoas que falam alemão,
independentemente de seu país. O pacote de mensagens ALL_ALL.xml é o arquivo usado como
padrão.

Melhores práticas
Não há requisitos rígidos a serem seguidos nas convenções de nomenclatura dos pacotes de
mensagem. O gadget usa os atributos lang e country de <Locale> para identificar o arquivo
de pacote de mensagens correto para o perfil do usuário. Ele não usa o nome do pacote de
mensagens em si.
Entretanto, embora a API de gadgets ofereça muita flexibilidade, recomendamos que você siga estas
orientações:
• Sempre forneça um pacote de mensagens ALL_ALL.xml ao lidar com mensagens padrão.
• Especifique um local por idioma. Ou seja, use fr_ALL, de_ALL e assim por diante.
• Se precisar ignorar locais específicos, use pacotes de mensagens idioma-país. Por exemplo,
se quiser fornecer um pacote de mensagens em inglês canadense para ignorar en_ALL, use
en_CA e não ALL_CA.

Uso de pacotes de mensagens em um gadget


Use a tag <Locale> (aninhada dentro da seção <ModulePrefs>) para listar os pacotes de
mensagens usados pelo seu gadget. Por exemplo:
<ModulePrefs title="i18n Example">
<Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/>
<Locale lang="de" messages="http://doc.examples.googlepages.com/de_ALL.xml"/>
<Locale lang="zh-cn"
messages="http://doc.examples.googlepages.com/zh_cn_ALL.xml"/>
<Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/>
<Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/>
<Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/>
<Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/>
<Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/>
</ModulePrefs>

<Locale> pode ter os seguintes atributos:


• messages: Um pacote de mensagens acessado através de um URL.
• lang: O idioma para o qual as strings do pacote de mensagens foram traduzidas.
• country: Não há exemplos desse atributo na especificação do gadget “Hello World”, mas
você também pode especificar um atributo de país. Por exemplo, este pacote de mensagens é
configurado para usuários canadenses francófonos:
<Locale lang="fr" country="CA" messages="http://example.com/fr_CA.xml"/>

Durante a execução, o gadget usa o pacote de mensagens que melhor corresponda ao perfil do
usuário.
Os valores válidos para o idioma são códigos de idioma ISO639-1 com dois dígitos e os valores
válidos para o país são códigos ISO 3166-1 alfa-2.

Consulta às mensagens
Os pacotes de mensagens possuem um recurso de consulta. Com o recurso de consulta às
mensagens, o gadget tenta usar o pacote de mensagens que melhor corresponda ao país do usuário e
ao idioma de preferência da IU (especificado no URL). Se o gadget não encontrar uma
correspondência exata, ele "consulta" todos os pacotes de mensagens para encontrar a
correspondência mais próxima.
Com a consulta às mensagens, você pode usar mensagens "padrão" (normalmente especificadas em
ALL_ALL.xml), caso não haja um pacote disponível para um determinado local.
Por exemplo, imagine que o seu gadget contém a seguinte especificação:
<Locale messages="http://x.com/ALL_ALL.xml"/>
<Locale lang="de" messages="http://x.com/de_ALL.xml"/>
<Locale lang="de" country="DE" messages="http://x.com/de_DE.xml"/>
<Locale lang="de" country="US" messages="http://x.com/de_US.xml"/>

Como esses arquivos seriam usados? Suponha que o domínio da sua usuária é nos EUA
(http://www.google.com), mas o idioma de preferência é o alemão. Ela verá as mensagens do
arquivo de_US.xml. Se não houver uma mensagem específica neste arquivo, ela verá a mensagem
de de_ALL.xml, e finalmente, de ALL_ALL.xml.
Um usuário da Alemanha usando a IU em alemão começará por de_DE.xml, um usuário da Suíça
usando a IU em alemão começará por de_ALL.xml e um usuário da Suíça usando a IU em francês
começará por ALL_ALL.xml.

Acesso a mensagens de pacotes de mensagens


Como um gadget acessa a mensagem apropriada no pacote de mensagens? Observe o arquivo
de_ALL.xml (idioma alemão, país ALL) no exemplo “Hello World”:
<messagebundle>
<msg name="hello_world">
Hallo Welt.
</msg>
<msg name="color">Farbe</msg>
<msg name="red">Rot</msg>
<msg name="green">Grün</msg>
<msg name="blue">Blau</msg>
<msg name="gray">Grau</msg>
<msg name="purple">Purpurrot</msg>
<msg name="black">Schwarz</msg>
</messagebundle>

Cada mensagem possui uma string exclusiva de nome para identificá-la. Por exemplo, nesta
mensagem:
<msg name="red">Rot</msg>

o nome exclusivo da mensagem é “red” e a string traduzida que aparece no gadget (no menu
suspenso userprefs) é “Rot”, a palavra em alemão para “vermelho”. Aqui está a string da mensagem
equivalente em inglês no pacote de mensagens ALL_ALL.xml:
<msg name="red">Red</msg>

A especificação do gadget “Hello World” usa a variável de substituição __MSG_ para indicar onde
o valor do pacote de mensagens apropriado deve ser substituído. Por exemplo, esta sentença XML
da especificação do gadget “Hello World” é usada para adicionar um item de menu ao menu
suspenso “Color” (Cor) de userprefs:
<EnumValue value="Red" display_value="__MSG_red__" />

Esta linha, na verdade, diz “Vá para o pacote de mensagens que melhor corresponda ao perfil de
país/idioma do usuário, obtenha o valor da mensagem com nome ‘red’ e use-o no lugar de
__MSG_red__”. É assim que as preferências do usuário do menu suspenso do exemplo “Hello
World” são preenchidas com nomes de cores (aqui, mostrado em alemão):

Exibição de mensagens no HTML do gadget


Para exibir as mensagens na parte XML do seu gadget, use as variáveis de substituição conforme
discutido acima. Há algumas opções diferentes dentro da parte CDATA do gadget.
A técnica mais simples é incorporar a variável de substituição no HTML:
<b>__MSG_hello_world__</b>.

Como alternativa, use a função getMsg() de userprefs. Essa função pode ser usada para acessar
todas as mensagens dos pacotes de mensagens e não apenas as mensagens relacionadas a userprefs.
Entretanto, é necessário chamar esta função para um objeto Prefs. Por exemplo:
var prefs = new gadgets.Prefs();
prefs.getMsg(“red”);

Especificação do gadget Hello World


Aqui está a especificação do gadget do exemplo "Hello World":
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="i18n Example">
<Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/>
<Locale lang="de" messages="http://doc.examples.googlepages.com/de_ALL.xml"/
>
<Locale lang="zh-cn"
messages="http://doc.examples.googlepages.com/zh_cn_ALL.xml"/>
<Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/
>
<Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/
>
<Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/
>
<Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/
>
<Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/
>
</ModulePrefs>
<UserPref name="fontcolor" display_name="__MSG_color__" default_value="Red"
datatype="enum">
<EnumValue value="Red" display_value="__MSG_red__" />
<EnumValue value="Green" display_value="__MSG_green__" />
<EnumValue value="Blue" display_value="__MSG_blue__" />
<EnumValue value="Gray" display_value="__MSG_gray__" />
<EnumValue value="Purple" display_value="__MSG_purple__" />
<EnumValue value="Black" display_value="__MSG_black__" />
</UserPref>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
// Display message in the user's preferred language
function displayMsg(){
var div = document.getElementById('content_div');
// Get userprefs
var prefs = new gadgets.Prefs();
// Set font color to user's color choice
div.style.color = prefs.getString("fontcolor");
// Display message
var html = "<br><h1>";
// Use prefs.getMsg to go to the appropriate message bundle
// and get the string associated with the "hello_world" message.
html += prefs.getMsg("hello_world");
html += "</h1>";
div.innerHTML = html;
}
gadgets.util.registerOnLoadHandler(displayMsg);
</script>
]]>
</Content>
</Module>

Criação de gadgets bidirecionais


Use a API BIDI (bidirecional) para alterar dinamicamente a direção de um gadget. "Direção"
refere-se à direção na qual o conteúdo é exibido: esquerda para a direita ou direita para a esquerda.
Isso é diferente de alinhamento. Por exemplo, você pode criar um gadget com texto em inglês
alinhado à direita, mas a direção do texto em si é da esquerda para a direita.
A API BIDI possibilita criar gadgets que suportem idiomas da direita para a esquerda (como
hebraico e árabe) e idiomas da esquerda para a direita (como inglês). A API BIDI inclui:
• Um atributo language_direction dentro da tag <Locale...>. Seu valor pode ser
"rtl" (direita para a esquerda) ou "ltr" (esquerda para a direita). Use esse atributo para definir
a direção do gadget. Como padrão, a direção dos gadgets é da esquerda para a direita.
• Um conjunto de variáveis de substituição __BIDI_... cujos valores são alterados
dependendo da direção do gadget. Por exemplo, a variável __BIDI_DIR__ tem valor "ltr"
quando o gadget está no modo da esquerda para a direita e "rtl" quando o gadget está no
modo da direita para a esquerda.
No caso mais simples, use <Locale... language_direction="rtl"> para definir
estaticamente a direção de um gadget. Por exemplo, este gadget exibe somente texto em hebraico.
Portanto, sua direção é sempre da direita para a esquerda:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="‫ כותרת‬two-‫"כיוונית‬
height="100">
<Locale lang="ALL" language_direction="rtl" />
</ModulePrefs>
<Content type="html"><![CDATA[
‫אני כותב מימין לשמאל ולא הייתי צריך להגדיר‬
dir=rtl ‫<!בשביל זה‬br>
]]>
</Content>
</Module>

Entretanto, suponha que você criou um gadget incluindo pacotes de mensagens para idiomas da
esquerda para a direita e vice-versa. Como você faria seu gadget suportar ambos os casos? Aqui está
um exemplo de gadget que altera a direção dinamicamente, de acordo com o pacote de mensagens
que é carregado para o local de um usuário. Este gadget possui pacotes de mensagens para dois
idiomas da direita para a esquerda, hebraico (iw) e árabe (ar):
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="BIDI Hello World">
<Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/>
<Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/
>
<Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/
>
<Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/
>
<Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/
>
<Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/
>
<Locale lang="iw" messages="http://doc.examples.googlepages.com/iw_ALL.xml"
language_direction="rtl"/>
<Locale lang="ar" messages="http://doc.examples.googlepages.com/ar_ALL.xml"
language_direction="rtl"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div style="margin-__BIDI_START_EDGE__:30px;"><h2>__MSG_hello_world__</h2></
div>
]]>
</Content>
</Module>

Para este gadget, suponha que o idioma de preferência do usuário seja árabe. A linha <Locale
lang="ar" messages="http://.../ar_ALL.xml"
language_direction="rtl"/> diz "para árabe, exibir o texto do pacote de mensagens
ar_ALL.xml e definir a direção do gadget como rtl." A direção para o hebraico também será da
direita para a esquerda. Para outros idiomas, a direção do é implicitamente definida com o padrão
ltr (esquerda para a direita).
A linha <div style="margin-__BIDI_START_EDGE__:
30px;"><h2>__MSG_hello_world__</h2></div> diz "quando o gadget estiver em
modo da esquerda para a direita, deslocar o texto 30 pixels em relação à margem esquerda. Quando
o gadget estiver em modo da direita para a esquerda, deslocar o texto 30 pixels em relação à
margem direita". Por exemplo, se a configuração do navegador do usuário for árabe (direita para a
esquerda), a substituição realizada na execução ficará assim:
<div style="margin-right:30px;"><h2>‫ بالعال‬x
‫<أهل‬/h2></div>
Esta tabela lista as variáveis de substituição BIDI e seus possíveis valores. Seus valores sempre são
baseados na direção do próprio gadget. Ou seja, estas variáveis são designadas para serem usadas
em conjunto com a configuração de <Locale... language_direction="...">. Você
pode usas as variáveis em qualquer parte dentro do corpo do gadget.
Variável Descrição
Esta variável representa o lado
do gadget que é o ponto inicial
da exibição do conteúdo. O
valor será "left" (esquerda)
__BIDI_S quando o gadget estiver em
TART_EDG modo LTR e "right" (direita)
E__ quando o gadget estiver em
modo RTL. O gadget acima é
um exemplo de como usar esta
variável para a configuração de
margens CSS.
Esta variável representa a
lateral do gadget oposta ao lado
de início da exibição do
__BIDI_E
ND_EDGE_ conteúdo. O valor será
_ "right" (direita) quando o
gadget estiver em modo LTR e
"left" (esquerda) quando o
gadget estiver em modo RTL.
O valor desta variável será "ltr"
__BIDI_D quando o gadget estiver em
IR__ modo LTR e "rtl" quando o
gadget estiver em modo RTL.
O valor desta variável será "rtl"
__BIDI_R
EVERSE_D quando o gadget estiver em
IR__ modo LTR e "ltr" quando o
gadget estiver em modo RTL.

Alteração da direção de parte do gadget


A API BIDI altera a direção de um gadget inteiro e formata o conteúdo do gadget de forma
correspondente. Entretanto, pode haver casos em que você deseja mexer na direção de linhas de
texto individuais dentro do gadget. Talvez você não queira que a direção do gadget seja associada à
configuração de idioma do usuário ou a qualquer idioma específico. Por exemplo, você pode criar
um gadget que exibe texto simultaneamente em inglês e hebraico. Ou você pode criar um gadget
que lista frases comuns em diversos idiomas. Você pode usar chamadas regulares a funções DOM e
CSS para definir a direção do texto dentro do corpo do gadget. Por exemplo:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="DOM Hello World" height="200" />

<Content type="html"><![CDATA[
<script type="text/javascript">
// In this gadget, users choose a language from a drop-down menu, and the
gadget displays
// a "Hello World" message for the selected language. The gadget uses DOM
functions to set
// the direction and formatting for the message, depending on whether its
language is RTL
// or LTR.
// Associative array containing "Hello World" messages for different languages
var msgs = new Object();
msgs = {
"English" : "Hello World",
"Hebrew" : "‫"שלום עולם‬,
"French" : "Bonjour Monde",
"Arabic" : "‫ بالعال‬x‫"أهل‬,
"Russian" : "Здравствуйте Мир!"
};

function showMsg() {
var html="<h1>";
var div = _gel('mydiv');
div.style.color = "green";
var index = document.myform.Language.selectedIndex;
var lang = document.myform.Language.options[index].text;
var str = msgs[lang];
if (!str)
str="";
// If language is Hebrew or Arabic, set the div direction to be right-to-
left.
// Offset text 30px from right margin.
if(lang=="Hebrew" || lang=="Arabic") {
div.style.direction = "rtl";
div.style.marginRight = "30px";
html += str;
}
// For other languages, set div direction to left-to-right.
// Offset text 30px from left margin.
else {
div.style.direction = "ltr";
div.style.marginLeft = "30px";
html += str;
}
html+= "</h1>";
div.innerHTML = html;
}
</script>
<div style="background-color: #BFCFFF; height: 200px; color:green;">
<br />
<div>
<form name="myform" style="text-align: center;">
<select name="Language" onchange="showMsg()">
<option>Pick a Language
<option>English
<option>Hebrew
<option>French
<option>Arabic
<option>Russian
</select>
</form>
</div>
<br />
<div id="mydiv"><h2 style='text-align: center;'>****Pick a
language****</h2></div>
</div>
]]>
</Content>
</Module>
Teste
Para testar o gadget, altere a configuração de país e idioma de modo que ela corresponda aos
pacotes de mensagens incluídos em seu gadget.
A maneira mais simples de alterar a configuração de país e idioma no iGoogle é editar o URL:
http://www.google.com/ig?&gl=<country>&hl=<lang>

Por exemplo, no URL abaixo, o país é Alemanha (DE) e o idioma é inglês (en). Normalmente, o
país tem precedência sobre o idioma. Portanto, com este URL, o iGoogle exibe texto em alemão:
http://www.google.com/ig?&gl=DE&hl=en

Neste exemplo, o país é implicitamente EUA e o idioma é espanhol:


http://www.google.com/ig?hl=es

Este link pode ajudá-lo a criar o URL correto para um idioma específico:
http://www.google.com/help/customize.html#searchlang. Os valores válidos para o idioma são
códigos de idioma ISO639-1 com dois dígitos e os valores válidos para o país são códigos ISO
3166-1 alfa-2.

Cache
Os pacotes de mensagens têm o mesmo comportamento de cache que as especificações de gadget
em si: normalmente, atualizamos o cache a cada 1 a 2 horas, os servidores de hospedagem devem
ver somente cerca de 100 a 200 solicitações de pacotes de mensagens por dia e, se eles não
estiverem disponíveis, continuaremos usando nossa cópia "antiga" pelo tempo que for possível. No
gadget developer.xml, ao desativar o cache do gadget, você também desativa o cache dos pacotes
de mensagens do gadget.

Solução de problemas
Durante o desenvolvimento, seu gadget pode ficar em branco ou exibir ??? onde deveria haver uma
mensagem. O problema pode ser:
• Você não salvou o pacote de mensagens em UTF-8. Isso é necessário para qualquer arquivo
de idioma diferente do inglês que inclua caracteres especiais.
• Há um problema na sintaxe do seu pacote de mensagens.
• Não há um arquivo de pacote de mensagens ALL_ALL.xml para ser usado como padrão
pelo gadget.
• No gadget, o URL do pacote de mensagens está incorreto.
• Há um erro de correspondência entre o pacote de mensagens e a variável de substituição de
mensagens especificada no gadget.
Gadgets em idiomas diferentes do inglês
A maioria dos exemplos deste guia do desenvolvedor foi criada em inglês. Este documento descreve
recursos disponíveis para usuários interessados em criar gadgets em outros idiomas.

Onde posso encontrar gadgets que não sejam em inglês?


Uma das características mais úteis dos gadgets é a visibilidade pública de seu código-fonte. Você
pode aprender muito sobre o desenvolvimento de gadgets observando como outros gadgets são
implementados.
Para encontrar gadgets criados em um idioma específico, faça uma filtragem no diretório de
conteúdo do iGoogle com base no país e idioma de sua preferência. Você pode usar o menu More
Languages (Mais idiomas) no diretório de conteúdo ou especificar os códigos de idioma e país no
URL. Por exemplo, para ver gadgets em japonês, use este URL:
http://www.google.com/ig/directory?&gl=JP&hl=ja&root=/ig&dpos=top

O parâmetro para o código do país é &gl e o parâmetro para o código do idioma é &hl. Neste
exemplo, o código do país (Japão) é JP, e o código do idioma japonês é ja (por padrão, os códigos
de idioma estão em letras minúsculas e os códigos de país em letras maiúsculas, mas isso não é
obrigatório). O conteúdo do diretório varia ligeiramente se você fornecer somente o código do país
ou do idioma. Portanto, inclua ambos os códigos (de país e idioma) para obter resultados mais
específicos.
Uma boa maneira de encontrar gadgets em um idioma específico é filtrar o diretório. Entretanto,
isso não retorna somente os gadgets criados no idioma de destino, pois os gadgets não recebem tags
de idioma. A API de gadgets inclui uma tag <Locale>, mas esta é opcional. O diretório exibe
gadgets para um local específico com base em sua popularidade. Portanto, ao exibir o diretório do
local Japão/japonês, por exemplo, você verá principalmente gadgets japoneses. Mas também poderá
ver gadgets populares neste local, apesar de não serem em japonês.
No diretório de conteúdo do iGoogle, você pode adicionar gadgets à sua página do iGoogle. Após
adicioná-los ao iGoogle, você poderá visualizar o código-fonte dos gadgets clicando em seus links
na página de gadgets do desenvolvedor. Os gadgets não personalizados (por exemplo, gadgets que
apenas exibem feeds) não estão listados na página de gadgets do desenvolvedor.

Criação de gadgets em idiomas diferentes do inglês


Os gadgets usam codificação UTF-8 para idiomas diferentes do inglês. A API de gadgets suporta
codificação UTF-8 para valores de atributos XML e também na seção <Content>. Quando o tipo
de conteúdo é definido como html, a codificação padrão é definida expressamente como UTF-8.
Você não deve tentar defini-la sozinho.
Se criar um gadget que suporte diversos idiomas, as strings das mensagens traduzidas serão
armazenadas em arquivos XML externos denominados pacotes de mensagens. Os pacotes de
mensagens contendo as strings traduzidas para cada local suportado pelo gadget devem ser salvos
expressamente no formato UTF-8.
Consulte a documentação Internacionalização para obter informações detalhadas sobre como criar
gadgets em diversos idiomas.
Publicação do seu gadget
Este documento descreve as diferentes opções de publicação do seu gadget. Se você usa o Google
Gadgets Editor (GGE) para criar e hospedar gadgets, a publicação dos seus gadgets ficará muito
mais fácil.

Onde posso colocar meu gadget?


Você pode colocar seus gadgets em qualquer um dos lugares a seguir:
• Nas sua página e nas páginas de seus amigos no iGoogle.
• Em outros recipientes de rede social que suportam gadgets, como o Orkut.
• No diretório de conteúdo do Google. Se você enviar seu gadget ao diretório de conteúdo, ele
ficará disponível para um público maior.
Nem todo gadget é adequado a todos os ambientes. Consulte a documentação do recipiente para
obter detalhes sobre os recursos suportados no ambiente específico.

Preparação para a publicação


Você deve testar seu gadget antes de publicá-lo, levando em consideração os requisitos e limitações
do ambiente no qual o gadget será executado.
Faça os testes abaixo para todos os gadgets:
• Tente todas as combinações de valores de UserPref.
• Execute-o em telas de tamanhos diferentes, desde 800x600 até a maior largura possível.
Vincule à extensão de desenvolvedor da web do Firefox, o que facilita o redimensionamento
do Firefox para um tamanho específico.
• Teste seu gadget em diferentes tamanhos, conforme descrito na seção Teste de largura e
altura.
• Teste seu gadget em todos os ambientes onde possa ser executado.
• Teste seu gadget nos navegadores IE 7, IE 6, Firefox 2.x, Firefox 1.5.x, IE 7, IE 6, Opera 9.x
e Safari 2.x.
• Experimente tamanhos de fonte diferentes:
• Para alterar o tamanho da fonte no Firefox, selecione Ferramentas > Opções >
Conteúdo. Clique em Avançado na seção "Fontes e cores". Altere a configuração de
fonte e desmarque "Páginas podem usar outras fontes".
• Para alterar o tamanho da fonte no Internet Explorer, selecione Ferramentas >
Opções da Internet > Geral. Use as caixas de diálogo Fontes e Acessibilidade para
alterar sua configuração de fontes.
Se estiver usando makeRequest(), verifique o que acontece se a fonte de dados estiver
inacessível ou retornar um erro. Você pode simular isso alterando o URL temporariamente.

Teste de largura e altura


O dimensionamento de um gadget depende principalmente de onde ele será executado. Consulte a
documentação do seu recipiente para obter mais detalhes.
Ao criar e testar seus gadgets, prepare-se para larguras arbitrárias que podem variar de 200 a até
mesmo 600 pixels. A largura deve ser ainda maior em determinados gadgets. Como regra geral, crie
o gadget para ser exibido adequadamente caso haja mais espaço. Por exemplo, os gadgets de mapas
devem preencher suas áreas, os gadgets de imagem devem ficar centralizados no frame e os gadgets
de texto devem manter o texto no alto (por exemplo, links do tipo "clique para obter mais detalhes",
que normalmente são na parte inferior da página, devem permanecer próximos ao conteúdo, em vez
de serem colocados na parte inferior da janela do gadget).

Aperfeiçoamento do desempenho do gadget


Se ao criar um gadget você espera causar tráfego intenso, há etapas que podem ser seguidas para
assegurar disponibilidade e um bom desempenho. Procure seguir as dicas desta seção caso seu
gadget tenha mais de 200.000 visualizações por dia ou aproximadamente 1 a 2 solicitações por
segundo. Mesmo um gadget de 50 KB recebendo 200.000 solicitações por dia consome cerca de
300 GB de largura de banda por mês.
Há motivos diferentes que podem tornar um gadget atraente para muitos usuários. Ele pode
simplesmente tornar-se popular no diretório de conteúdo. Ou ainda, ser usado em uma promoção
especial ou em publicidade, o que pode causar um excesso de tráfego.
No caso de um gadget de tráfego intenso, sua meta deve ser exibi-lo em 0,25 s (250 milissegundos)
ou menos. Use o Firebug (somente Firefox) para calcular o tempo. Uma excelente maneira de ter
impacto positivo sobre a experiência do usuário é melhorar a capacidade de resposta do seu gadget.
Consulte Otimização para tráfego intenso para obter dicas sobre como otimizar o desempenho do
gadget. Para obter dicas sobre gerenciamento, consulte Gerenciamento de tráfego intenso. As
orientações gerais de teste também são especialmente importantes para gadgets muito populares.

Otimização para tráfego intenso


Se você acha que seu gadget poderá causar tráfego intenso, siga as orientações abaixo:
• Evite usar arquivos JavaScript ou CSS externos (arquivos que contêm atributos "src" ou
"href" nas tags HTML), pois isso requer o uso de outra conexão de rede. Em vez disso,
coloque seu código JavaScript e CSS dentro das especificações do gadget.
• Use um gadget type=html. Os gadgets type=url geralmente são exibidos mais
lentamente que os gadgets type=html, devido ao desempenho e suporte a cache ruins de
outros servidores de hospedagem.
• Como padrão, o método makeRequest() armazena o conteúdo em cache por
aproximadamente 1 a 2 horas. Você pode usar o parâmetro refreshInterval com essas
funções para atualizar o cache com mais freqüência. Entretanto, o uso de cache melhora o
desempenho do gadget, minimizando o número de solicitações enviadas aos servidores
remotos que hospedam o conteúdo. Não solicite um número de atualizações de cache maior
que o necessário, pois você reduzirá a porcentagem de solicitações suportadas pelo cache.
Para uma discussão mais profunda sobre este tópico, consulte Atualização do cache.
• Use o Firebug (somente Firefox) para ajustar o desempenho do seu gadget. Para outros
navegadores, use o Fiddler.
• Se possível, evite usar o Google Analytics, pois ele requer uma conexão adicional ao
servidor. Em vez do Analytics, use http://www.google.com/ig/directory?
url=<gadget-url> para verificar o total semanal de visualizações de página do seu gadget.
• Especifique a altura e a largura de todas as tags <img> no HTML do gadget. Isso agiliza a
exibição do gadget. Se você estiver usando gadgets.io.getProxyUrl() e inserindo
o elemento imagem diretamente no DOM, não é necessário definir as propriedades de
largura e altura.
• Em vez de conectar-se diretamente ao seu provedor de hospedagem, use a função
gadgets.io.getProxyUrl() para armazenar todas as imagens incorporadas em
cache e a função embedCachedFlash() para armazenar o conteúdo Flash em cache.
Veja abaixo um exemplo de gadget que carrega as imagens previamente usando
gadgets.io.getProxyUrl():
Aqui está um exemplo de gadget que ilustra como usar gadgets.io.getProxyUrl():
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Zombies!" height="350" />
<Content type="html">
<![CDATA[
<div id="zombiecontainer"
style="text-align:center;">
</div>
<script type="text/javascript">
var counter = 0;

// Preload the images using gadgets.io.getProxyUrl()


function load(imageList) {
var ret = [];
for (var i = 0, j = imageList.length; i < j; ++i) {
var img = document.createElement("img");
img.src = gadgets.io.getProxyUrl(imageList[i]);
ret.push(img);
}
return ret;
}

var files = [
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-0.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-1.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-2.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-3.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-4.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-5.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-6.jpg"
];

var images = load(files);


browse();

// Browse through photos sequentially. When you get to the end of the array,
start over.
function browse(){
if (counter == images.length)
{
counter = 0;
}
document.getElementById("zombiecontainer").innerHTML = "";
document.getElementById("zombiecontainer").appendChild(images[counter]);
counter++;
}

</script>
<br />
<div style="text-align: center;">
<input type=submit value="Next ->" onClick="browse()">
</div>
]]>
</Content>
</Module>

Gerenciamento de tráfego intenso


Estas orientações podem ajudá-lo a gerenciar um gadget de alto volume de tráfego:
• Se estiver recebendo uma grande quantidade de e-mails dos usuários do seu gadget, use o
Gmail para configurar filtros e gerenciar o volume. Recomendamos o uso de um endereço
no formato <username>.feedback+<gadgetname>@gmail.com na especificação do
seu gadget. Isso ajuda a filtrar as mensagens recebidas dos usuários do gadget. O Gmail
ignora tudo o que está depois do sinal de mais (+), fazendo com que o endereço de e-mail
seja mapeado para <username>.feedback@gmail.com. O Gmail tem um filtro de
spams de alta qualidade.
• Se você enviar seu gadget ao diretório de conteúdo do iGoogle, visite periodicamente a
página de descrição do seu gadget para ler os comentários dos usuários. Freqüentemente, os
usuários deixam um feedback valioso, fazem solicitações e relatam bugs que encontraram ao
usar o gadget. É bom ficar a par de seus comentários e manter contato com eles.

Publicação no diretório de conteúdo do iGoogle


Depois de criar, implementar e testar o gadget, você pode enviá-lo ao Google para ser publicado no
diretório de conteúdo do iGoogle. Esta seção lista as etapas gerais que você deve seguir ao preparar
seu gadget para publicação.

Etapa 1: Defina as preferências do seu gadget.


A Referência lista todos os atributos <ModulePrefs> que podem ser usados para fornecer
informações "meta" sobre seu gadget. Aqui estão as informações que você deve incluir na
especificação do seu gadget:
• title
• description. Este atributo é importante para que as pessoas saibam o que seu gadget faz,
particularmente se isso não for óbvio.
• author
• author_email. Use esse atributo para que o Google e os usuários possam entrar em contato
com você. Você pode usar qualquer sistema de e-mail. Evite usar um endereço de e-mail
pessoal devido aos spams. Uma boa estratégia é usar um endereço de e-mail com o formato
helensmith.feedback+coolgadget@gmail.com na especificação do seu gadget.
O Gmail ignora tudo o que está depois do sinal de mais (+), fazendo com que o endereço de
e-mail seja mapeado para helensmith.feedback@gmail.com. Crie uma conta do
Gmail aqui.
• screenshot. Esta é uma string que fornece o URL de uma captura de tela do gadget. O URL
deve ser bem formado, e não relativo. Esta imagem deve estar em um site público da web
não bloqueado por robots.txt. O formato preferido é PNG, embora os formatos GIF e
JPG também sejam aceitáveis. As capturas de tela de gadgets devem ter 280 pixels de
largura. A altura da captura de tela deve ser a altura "natural" do gadget quando em uso. Isso
ajuda o usuário a identificar quanto espaço de sua tela será consumido pelo gadget antes de
adicioná-lo à sua página. A captura de tela não deve ter nenhum espaço em branco acima da
barra de cabeçalho azul do gadget. As capturas de tela devem mostrar apenas o gadget
completo, incluindo sua barra de título. Como alternativa, faça uma captura de tela do
gadget com a janela de edição aberta. Não redimensione ou corte as capturas de tela. Para
manter a qualidade e a consistência, o Google pode fazer suas próprias capturas de tela
relativas a um gadget específico.
• thumbnail. No diretório de conteúdo, as miniaturas permitem que os usuários possam
visualizar um gadget. Elas devem captar a funcionalidade principal do gadget sem mostrá-lo
totalmente. O valor deste atributo é uma string que fornece o URL da miniatura de um
gadget. O URL deve ser bem formado, e não relativo. Esta imagem deve estar em um site
público da web não bloqueado por robots.txt. O formato preferido é PNG, embora os
formatos GIF e JPG também sejam aceitáveis. As miniaturas devem medir 120x60 pixels.
Elas não devem incluir a barra de título.
• author_location
• author_affiliation
• title_url. Use este atributo para vincular o título do seu gadget a uma página HTML externa.
Por exemplo, se o gadget for o front end de um serviço, vincule o título do gadget ao site do
serviço.
• directory_title (obrigatório se o título tiver variáveis de substituição de preferências do
usuário).
Se você deseja ser incluído na página de autores, adicione estes campos:
• author_photo. URL para uma foto (o formato preferido é 70x100 PNG, mas JPG/GIF
também são suportados).
• author_aboutme. Um texto sobre si mesmo (tente limitar em aproximadamente 500
caracteres).
• author_link. Um link para o seu site, blog, etc.
• author_quote. Uma citação que você queira incluir (tente limitar em aproximadamente 300
caracteres).
Encontre mais informações aqui e um exemplo aqui.

Etapa 2: Verifique se criou um gadget robusto e seguro.


Verifique se codificou seu gadget de maneira a minimizar os riscos de segurança.

Etapa 3: Adicione todos os requisitos de compatibilidade.


Nem todos os gadgets podem ser executados em todos os ambientes. Um gadget pode exigir um
navegador ou software específico. Use a tag <MayRequire> em <ModulePrefs> para fornecer
informações sobre os requisitos especiais do seu gadget. Para obter mais informações, consulte
Especificação dos requisitos de compatibilidade.

Etapa 4: Adicione todas as informações relevantes de local.


Use as tags <Locale> em <ModulePrefs> para especificar os locais suportados pelo seu
gadget. Para obter mais informações, consulte Especificação dos locais.

Etapa 5: Facilite o processo de adição do seu gadget.


Para promover um gadget, coloque nele um botão "Adicionar ao Google".

Etapa 6: Envie seu gadget ao Google.


Você pode enviar seu gadget ao Google aqui. Você também pode enviar seu gadget ao diretório de
conteúdo, clicando em GGE e usando o comando File > Publish (Arquivo > Publicar). Consulte
as Perguntas freqüentes para obter uma explicação sobre como encontrar seu gadget no diretório e o
que determina sua posição.

Gerenciamento dos gadgets enviados


Se você enviou diversas versões de um gadget em diferentes URLs e deseja designar uma versão
como a oficial, use a página Enviar uma solicitação de alias.
Referência da API de gadgets
Esta é a referência para a API de gadgets.*. Ela inclui informações de referência para a
especificação XML do gadget.
Você pode ver a Referência de JavaScript aqui.
Observação: A API de gadgets foi inserida no namespace JavaScript de gadgets.*, para
fornecer uma API mais limpa para programação e suporte. Se você estiver interessado em
compreender melhor a API de gadgets.*, leia a Especificação do Gadgets.

Estrutura XML
As seções a seguir descrevem a estrutura e o conteúdo do arquivo XML usado para especificar um
gadget.

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="Developer Forum"
title_url="http://groups.google.com/group/Google-Gadgets-API"
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.


A tabela abaixo lista os atributos <ModulePrefs>:
Atributo Descrição
String opcional que fornece o título do gadget. Esse título é exibido na barra de
título do gadget no iGoogle. Se esta string contém variáveis de substituição de
title preferências do usuário e você pretende enviar seu gadget ao diretório de
conteúdo do iGoogle, forneça também um directory_title para ser
exibido no diretório.
String opcional que fornece o título do gadget a ser exibido no diretório de
conteúdo do iGoogle. Deve conter somente o texto que será realmente exibido,
sem variáveis de substituição de preferências do usuário. Isso é importante
directory_ti porque o diretório de conteúdo do iGoogle exibe uma versão estática do seu
gadget. Portanto, ele não pode executar a substituição necessária para fornecer
tle
um título aceitável. Por exemplo, Se o título do seu gadget for "Friends for
__UP_name__", o diretório não é capaz de executar a substituição para fornecer
um valor aceitável para " __UP_name__". Assim, configure
directory_title simplesmente como "Friends".
title_url String opcional que fornece um URL de link do título do gadget. Por exemplo,
você pode vincular o título a uma página da web relacionada ao gadget.
description String opcional que descreve o gadget.
author String opcional que revela o autor do gadget.
String opcional que fornece o endereço de e-mail do autor do gadget. Você pode
usar qualquer sistema de e-mail. Evite usar um endereço de e-mail pessoal
devido aos spams. Uma boa estratégia é usar um endereço de e-mail com o
formato helensmith.feedback+coolgadget@gmail.com na especificação do
author_email gadget.
O Gmail ignora tudo o que está depois do sinal de mais (+), fazendo com que o
endereço de e-mail seja interpretado como helensmith.feedback@gmail.com.

Crie uma conta do Gmail aqui.


author_affil Seqüência opcional, como "Google", que indica a afiliação do autor. Esse
iation atributo é necessário para gadgets incluídos no diretório de conteúdo do iGoogle.
author_locat
ion A localização geográfica do autor, como "Mountain View , CA, EUA ".
String opcional que fornece o URL de uma captura de tela do gadget. Esta
imagem deve estar em um site público da web não bloqueado por robots.txt. O
formato preferido é PNG, embora os formatos GIF e JPG também sejam
screenshot aceitáveis. As capturas de tela de gadgets devem ter 280 pixels de largura. A
altura da captura de tela deve ser a altura "natural" do gadget quando em uso.
Para ler mais sobre diretrizes de captura de tela, consulte Publicação no diretório
de conteúdo do iGoogle.
String opcional que fornece o URL de uma miniatura do gadget. Esta imagem
deve estar em um site público da web não bloqueado por robots.txt. O formato
thumbnail preferido é PNG, embora os formatos GIF e JPG também sejam aceitáveis. As
miniaturas de gadget devem medir 120x60 pixels. Para ler mais sobre diretrizes
de miniatura, consulte Publicação no diretório de conteúdo do iGoogle.
height Número inteiro positivo opcional que especifica a altura da área na qual o gadget
será executado. A altura padrão é 200.
width Número inteiro positivo opcional que especifica a largura da área na qual o
gadget será executado. A largura padrão é 320.
Valor booleano opcional que especifica se a proporção (razão entre altura e
largura) do gadget será mantida quando o navegador for redimensionado. Os
scaling gadgets que podem ser redimensionados automaticamente devem ter este valor
configurado como true. Já os gadgets com altura fixa devem ter este valor
configurado como false. O padrão é true.
Valor booleano opcional que fornece barras de rolagem vertical e/ou horizontal
scrolling caso o conteúdo exceda o espaço fornecido. Se configurado como false, o
conteúdo é recortado segundo a altura e a largura fornecidas (observe que a
largura não é configurável). O padrão é false.
singleton Valor booleano opcional que especifica se o usuário pode adicionar um gadget
várias vezes a partir de um mesmo diretório. O padrão é true. Isso significa que,
como padrão, os gadgets podem ser adicionados somente uma vez. Entretanto,
os diretórios podem manipular este atributo como desejarem. Por exemplo, o
diretório de conteúdo do iGoogle manipula o atributo singleton="true"
desabilitando (a cor fica esmaecida) os gadgets que já foram adicionados e
exibindo o texto "Added" (Adicionado) ao lado de cada gadget. As alterações
neste atributo podem não ser atualizadas imediatamente nos diretórios.

Este atributo não impede que os usuários adicionem gadgets diversas vezes
através do gadget do desenvolvedor ou que Adicionem gadgets por URL.
Conseqüentemente, continua sendo necessário que você crie seu gadget para
suportar diversas instâncias.
author_photo Para a página de autores, um URL para uma foto (o formato preferido é 70x100
PNG, mas JPG/GIF também são suportados).
author_about Para a página de autores, um texto sobre si mesmo (tente limitar em
me aproximadamente 500 caracteres).
author_link Para a página de autores, um link para seu site, blog, etc.
author_quote Para a página de autores, uma citação que você deseja de incluir (tente limitar
em aproximadamente 300 caracteres).

Uso de bibliotecas
Para usar determinados recursos da API de gadgets, como altura dinâmica ou estado de
armazenamento, é necessário carregar a biblioteca JavaScript apropriada, usando a tag
<Require> (dentro de <ModulePrefs>). A tag <Require> possui um atributo obrigatório,
feature, cujo valor especifica a biblioteca do recurso. Por exemplo:
<ModulePrefs
title="Set Userprefs Demo">
<Require feature="dynamic-height"/>
<Require feature="setprefs" />
</ModulePrefs>

Para obter mais informações sobre bibliotecas de recursos, consulte a Referência de JavaScript.

Especificação de locais
Use as tags <Locale> em <ModulePrefs> para especificar os locais suportados pelo seu
gadget. Você também pode usá-las para especificar pacotes de mensagens, como descrito em
Gadgets e internacionalização.
Por exemplo, este snippet especifica dois locais diferentes:
<ModulePrefs ...>
<Locale lang="en" country="us" />
<Locale lang="ja" country="jp" />

</ModulePrefs>

Ambos os atributos "lang" (idioma) e "country" (país) são opcionais, mas você precisa usar pelo
menos um deles para cada <Locale>. Se você omitir um dos atributos, o valor é equivalente a "*"
e "ALL" (tudo). Se você especificar um país e nenhum idioma, o sistema assumirá que seu gadget
suporta todos os idiomas associados ao país. Da mesma forma, se você especificar um idioma e
nenhum país, o sistema assumirá que seu gadget suporta todos os países associados ao idioma.
Os valores válidos para o idioma são códigos de idioma ISO639-1 com dois dígitos e os valores
válidos para o país são códigos ISO 3166-1 alfa-2.
Há algumas exceções às regras normais de idioma:
• Chinês simplificado: lang="zh-cn" (normalmente para country="cn").
• Chinês tradicional: lang="zh-tw" (normalmente para country="tw" ou "hk", Taiwan ou
Hong Kong, respectivamente).
A tabela abaixo lista os atributos <Locale>:
Atributo Descrição
lang String opcional, indicando o idioma associado ao local.
country String opcional, indicando o país associado ao local.
String opcional que é um URL apontando para um pacote de mensagens. Os
messages pacotes de mensagens são arquivos XML que contêm as strings traduzidas para
um dado local. Para obter mais informações, consulte Gadgets e
internacionalização.
String opcional que define a direção do gadget. Seu valor pode ser "rtl" (direita
para a esquerda) ou "ltr" (esquerda para a direita). O padrão é "ltr". Este atributo
permite criar gadgets que suportam idiomas lidos da esquerda para a direita e vice-
versa. Para ler mais sobre este tópico, consulte Criação de gadgets bidirecionais.
Você pode usar as variáveis de substituição descritas abaixo em conjunto com o
atributo language_direction:

• __BIDI_START_EDGE__: O valor é "left" (esquerda) quando o gadget


estiver em modo LTR e "right" (direita) quando o gadget estiver em modo
language_d RTL.
irection • __BIDI_END_EDGE__: O valor é "right" (direita) quando o gadget
estiver em modo LTR e "left" (esquerda) quando o gadget estiver em modo
RTL.
• __BIDI_DIR__: O valor desta variável é "ltr" (esquerda para a direita)
quando o gadget estiver em modo LTR e "rtl" (direita para a esquerda)
quando o gadget estiver em modo RTL.
• __BIDI_REVERSE_DIR__: O valor desta variável é "rtl" (direita para a
esquerda) quando o gadget estiver em modo LTR e "ltr" (esquerda para a
direita) quando o gadget estiver em modo RTL.

Se você não especificar um <Locale>, o padrão suposto será EUA + inglês somente.

Especificação de requisitos de compatibilidade


Nem todos os gadgets podem ser executados em todos os ambientes. Um gadget pode exigir um
navegador ou software específico. Use a tag <MayRequire> para fornecer informações sobre os
requisitos especiais do seu gadget. Por exemplo:
<ModulePrefs ...>
<MayRequire type="plugin" value="quicktime"/>
<MayRequire type="browser" value="firefox" min_version="1.06"/>

<MayRequire type="platform"
value="windows"> This gadget uses a Windows API.
</MayRequire>
</ModulePrefs>

A tabela abaixo lista os atributos <MayRequire>:


Atributo Descrição
String obrigatória indicando o tipo de requisito. Os tipos suportados são
type
"platform", "browser" e "plugin".
String obrigatória que fornece um valor para o tipo. Por exemplo,
value
type="plugin" value="flash".
min_versio
n String opcional indicando o número mínimo de versão do item obrigatório.
cdata String opcional que fornece informações adicionais sobre o requisito.
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 condições climáticas pode exigir que o usuário forneça seu código
postal. 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.
A tabela abaixo lista os atributos <UserPref>:
Atributo Descrição
O nome "simbólico" obrigatório da preferência do usuário, exibido durante a edição
caso não haja nenhum display_name definido. Deve conter somente letras,
name
números e caracteres de sublinhado, isto é, a expressão regular ^[a-zA-Z0-9_]+$.
Deve ser exclusivo.
display_n String opcional para ser exibida ao lado das preferências do usuário na janela de
ame edição. Deve ser exclusivo.
String opcional para passar como o nome do parâmetro para conteúdo
urlparam
type="url".
String opcional indicando o tipo de dados deste atributo. Pode ser string, bool,
enum, hidden (uma string invisível e não editável pelo usuário), list (uma
datatype
matriz dinâmica gerada a partir de dados inseridos pelo usuário) ou location
(para gadgets baseados no Google Maps). O padrão é string.
Argumento booleano opcional (true ou false) indicando se esta preferência do
required
usuário é obrigatória. O padrão é false.
default_v
alue String opcional que indica o valor padrão das preferências de um usuário.
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 _IG_Prefs();
var someStringPref = prefs.getString("StringPrefName");
var someIntPref = prefs.getInt("IntPrefName");
var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Tipos de dados Enum


Um dos valores que você pode especificar para o atributo datatype de <UserPref> é enum. O
tipo de dados enum é apresentado na interface de usuário como um menu de opções. Especifique o
conteúdo do menu usando <EnumValue>.
Por exemplo, esta <UserPref> permite que os usuários definam o nível de dificuldade de um
game. Cada valor que aparece no menu (Easy, Medium e Hard) é definido por meio de uma tag
<EnumValue>.
<UserPref name="difficulty"
display_name="Difficulty"
datatype="enum"

default_value="4">
<EnumValue value="3" display_value="Easy"/>
<EnumValue value="4" display_value="Medium"/>

<EnumValue value="5" display_value="Hard"/>


</UserPref>
A tabela abaixo lista os atributos <EnumValue>:
Atributo Descrição
String obrigatória que fornece um valor exclusivo. Este valor é exibido no menu
value da caixa de edição das preferências do usuário, a menos que um
display_value seja fornecido.
String opcional que é exibida no menu da caixa de edição de preferências do
display_val
usuário. Se você não especificar um display_value, o value é exibido na
ue
interface do usuário.

Seção de conteúdo
A seção <Content> define o tipo de conteúdo e contém o próprio conteúdo ou uma referência
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. Para ler mais sobre tipos de conteúdo, consulte Seleção
do tipo de conteúdo.
A tabela abaixo lista os atributos <Content>:
Atributo Descrição
String opcional que fornece o tipo de conteúdo. Os valores possíveis são html e url. O
type
padrão é html.
String que fornece um URL de destino. Obrigatório para type="url" e não permitido
href
com outros tipos de conteúdo.
cdata String opcional. Para HTML, contém o HTML puro que será exibido no iframe.
API Reference: gadgets.*
Bem-vindo a uma pré-apresentação da documentação de referência da API de gadgets. Esta
documentação contém detalhes sobre a futura inserção da API de gadgets em uma API JavaScript
de gadgets.* mais limpa.
Observação: Esta API ainda não é suportada pelo iGoogle. Se você deseja criar um gadget para o
iGoogle, consulte a Referência da API do Google Gadgets.

Sumário
• API principal
• Prefs
• io
• AuthorizationType
• ContentType
• MethodType
• RequestParameters
• json
• util
• API específica do recurso
• MiniMessage
• Tab
• TabSet
• flash
• rpc
• views
• View
• ViewType
• skins
• Property
• window
gadgets.Prefs
Classe gadgets.Prefs
Fornece acesso às preferências do usuário, dimensões do módulo e mensagens. Os clientes podem
acessar suas preferências, criando uma instância de gadgets.Prefs e passando o id do módulo.
Exemplo:
var prefs = new gadgets.Prefs();
var name = prefs.getString("name");
var lang = prefs.getLang();

Resumo do construtor
gadgets.Prefs(opt_moduleId)
Cria um novo objeto Prefs.

Resumo do método
Array.<String> getArray(key)
Recupera uma preferência de matriz.
Boolean getBool(key)
Recupera uma preferência booleana.
String getCountry()
Obtém o país atual, retornado como um código ISO 3166-1 alpha-2.
Number getFloat(key)
Recupera uma preferência de ponto flutuante.
Number getInt(key)
Recupera uma preferência de número inteiro.
String getLang()
Obtém o idioma atual que o gadget deve usar na visualização, retornado como um código de
idioma ISO 639-1.
String, Number getModuleId()
Obtém o id do módulo para a instância atual.
String getMsg(key)
Obtém uma mensagem não formatada.
String getMsgFormatted(key, opt_subst)
Retorna um valor de mensagem com o argumento de posição opt_subst no lugar, caso seja
fornecido, ou caso contrário, o valor fornecido no exemplo. Se a mensagem não for
encontrada, retorna a string vazia.
String getString(key)
Recupera uma preferência de string.
set(key, val)
Armazena uma preferência.
setArray(key, val)
Armazena uma preferência de matriz.
Detalhes do construtor

gadgets.Prefs
gadgets.Prefs(opt_moduleId)

Cria um novo objeto Prefs.


Parâmetros:
String, Number opt_moduleId - Um parâmetro opcional especificando o id
do módulo para o qual as preferências serão criadas; se não for fornecido, é usado o
id do módulo padrão

Detalhes do método

getArray
Array.<String> getArray(key)

Recupera uma preferência de matriz. Os valores de UserPref que não foram declarados
como listas são tratados como matrizes de um único elemento.
Parâmetros:
String key - A preferência a ser obtida
Retorna:
Array.<String> A preferência; se não estiver definida, uma matriz vazia

getBool
Boolean getBool(key)

Recupera uma preferência booleana.


Parâmetros:
String key - A preferência a ser obtida
Retorna:
Boolean A preferência; se não estiver definida, false (falso)

getCountry
String getCountry()

Obtém o país atual, retornado como um código ISO 3166-1 alpha-2.


Retorna:
String O país para esta instância do módulo

getFloat
Number getFloat(key)

Recupera uma preferência de ponto flutuante.


Parâmetros:
String key - A preferência a ser obtida
Retorna:
Number A preferência; se não estiver definida, 0

getInt
Number getInt(key)

Recupera uma preferência de número inteiro.


Parâmetros:
String key - A preferência a ser obtida
Retorna:
Number A preferência; se não estiver definida, 0

getLang
String getLang()

Obtém o idioma atual que o gadget deve usar na visualização, retornado como um código de
idioma ISO 639-1.
Retorna:
String O idioma para esta instância do módulo

getModuleId
String, Number getModuleId()

Obtém o id do módulo para a instância atual.


Retorna:
String, Number O id do módulo para esta instância do módulo

getMsg
String getMsg(key)

Obtém uma mensagem não formatada.


Parâmetros:
String key - A mensagem a ser obtida
Retorna:
String A mensagem

getMsgFormatted
String getMsgFormatted(key, opt_subst)

Retorna um valor de mensagem com o argumento de posição opt_subst no lugar, caso seja
fornecido, ou caso contrário, o valor fornecido no exemplo. Se a mensagem não for
encontrada, retorna a string vazia.
Parâmetros:
String key - A mensagem a ser obtida
String opt_subst - Uma string opcional para ser substituída na mensagem
Retorna:
String A string formatada

getString
String getString(key)

Recupera uma preferência de string.


Parâmetros:
String key - A preferência a ser obtida
Retorna:
String A preferência; se não estiver definida, uma string vazia

set
set(key, val)

Armazena uma preferência. Para usar esta chamada, o gadget precisa ter o recurso setprefs.
Observação: Se o gadget tiver que armazenar uma matriz, ele deverá usar setArray em vez
desta chamada.
Parâmetros:
String key - A preferência a ser armazenada
Object val - Os valores a serem armazenados

setArray
setArray(key, val)

Armazena uma preferência de matriz. Para usar esta chamada, o gadget precisa ter o recurso
setprefs.
Parâmetros:
String key - A preferência a ser armazenada
Array val - Os valores a serem armazenados
gadgets.io
Static Class gadgets.io
Fornece funções de recuperação de conteúdo remoto.

Resumo do método
<static> String encodeValues(fields)
Converte um objeto de entrada em uma string de dados codificada como URL.
<static> String getProxyUrl(url)
Obtém a versão proxy do URL passado.
<static> makeRequest(url, callback, opt_params)
Obtém o conteúdo a partir do URL fornecido e alimenta este conteúdo na função de retorno
de chamada.

Detalhes do método

encodeValues
<static> String encodeValues(fields)

Converte um objeto de entrada em uma string de dados codificada como URL.


(chave=valor&...)
Parâmetros:
Object fields - Os campos de postagem que você deseja codificar
Retorna:
String Os dados de postagem processados; isso inclui um E comercial (&) no
final

getProxyUrl
<static> String getProxyUrl(url)

Obtém a versão proxy do URL passado.


Parâmetros:
String url - O URL a partir do qual o URL com o proxy será obtido
Retorna:
String A versão do URL com o proxy

makeRequest
<static> makeRequest(url, callback, opt_params)

Obtém o conteúdo a partir do URL fornecido e alimenta este conteúdo na função de retorno
de chamada. Exemplo:
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
gadgets.io.makeRequest(url, callback, params);

Parâmetros:
String url - O URL no qual o conteúdo está localizado
Function callback - A função a ser chamada com os dados do URL após a
obtenção
Map.<gadgets.io.RequestParameters, Object> opt_params -
Parâmetros adicionais a serem passados para a solicitação
gadgets.io.AuthorizationType
Static Class gadgets.io.AuthorizationType
Usada por RequestParameters.

Resumo do campo
<static> object AUTHENTICATED
O recipiente usará autenticação completa.
<static> object NONE
Sem autorização.
<static> object SIGNED
A solicitação será assinada pelo recipiente.

Detalhes do campo

AUTHENTICATED
<static> object AUTHENTICATED

O recipiente usará autenticação completa.

NONE
<static> object NONE

Sem autorização.

SIGNED
<static> object SIGNED

A solicitação será assinada pelo recipiente.


gadgets.io.ContentType
Static Class gadgets.io.ContentType
Usada por RequestParameters.

Resumo do campo
<static> object DOM
Retorna um objeto DOM; usado para obter XML.
<static> object FEED
Retorna uma representação JSON de um feed.
<static> object JSON
Retorna um objeto JSON.
<static> object TEXT
Retorna texto; usado para obter HTML.

Detalhes do campo

DOM
<static> object DOM

Retorna um objeto DOM; usado para obter XML.

FEED
<static> object FEED

Retorna uma representação JSON de um feed.

JSON
<static> object JSON

Retorna um objeto JSON.

TEXT
<static> object TEXT

Retorna texto; usado para obter HTML.


gadgets.io.MethodType
Static Class gadgets.io.MethodType
Usada por RequestParameters.

Resumo do campo
<static> object DELETE
Não suportado por todos os recipientes.
<static> object GET
O tipo padrão.
<static> object HEAD
Não suportado por todos os recipientes.
<static> object POST
Não suportado por todos os recipientes.
<static> object PUT
Não suportado por todos os recipientes.

Detalhes do campo

DELETE
<static> object DELETE
Não suportado por todos os recipientes.

GET
<static> object GET
O tipo padrão.

HEAD
<static> object HEAD
Não suportado por todos os recipientes.

POST
<static> object POST
Não suportado por todos os recipientes.

PUT
<static> object PUT
Não suportado por todos os recipientes.
gadgets.io.RequestParameters

Static Class gadgets.io.RequestParameters


Usada pelo método gadgets.io.makeRequest().

Resumo do campo
<static> object AUTHORIZATION
O tipo de autenticação a ser usada durante a obtenção do conteúdo; o padrão é
AuthorizationType.NONE.
<static> object CONTENT_TYPE
O tipo de conteúdo que reside no URL; o padrão é ContentType.TEXT.
<static> object GET_SUMMARIES
No caso do conteúdo ser um feed, indica se os resumos do feed devem ser obtidos; o padrão é
false (falso).
<static> object HEADERS
Os cabeçalhos HTTP a serem enviados ao URL; o padrão é null (nulo).
<static> object METHOD
O método a ser usado durante a obtenção de conteúdo a partir do URL; o padrão é
MethodType.GET.
<static> object NUM_ENTRIES
Se o conteúdo for um feed, indica o número de entradas a serem obtidas; o padrão é 3.
<static> object POST_DATA
Os dados a serem enviados ao URL usando o método POST; o padrão é null (nulo).

Detalhes do campo

AUTHORIZATION
<static> object AUTHORIZATION

O tipo de autenticação a ser usada durante a obtenção do conteúdo; o padrão é


AuthorizationType.NONE. Especificado como um Tipo de autorização.

CONTENT_TYPE
<static> object CONTENT_TYPE

O tipo de conteúdo que reside no URL; o padrão é ContentType.TEXT. Especificado


como um Tipo de conteúdo.

GET_SUMMARIES
<static> object GET_SUMMARIES

No caso do conteúdo ser um feed, indica se os resumos do feed devem ser obtidos; o padrão
é false (falso). Especificado como um Boolean.
HEADERS
<static> object HEADERS

Os cabeçalhos HTTP a serem enviados ao URL; o padrão é null (nulo). Especificado como
um Map.<String,String>.

METHOD
<static> object METHOD

O método a ser usado durante a obtenção de conteúdo a partir do URL; o padrão é


MethodType.GET. Especificado como um Tipo de método.

NUM_ENTRIES
<static> object NUM_ENTRIES

Se o conteúdo for um feed, indica o número de entradas a serem obtidas; o padrão é 3.


Especificado como um Number.

POST_DATA
<static> object POST_DATA

Os dados a serem enviados ao URL usando o método POST; o padrão é null (nulo).
Especificado como um String.
gadgets.json
Static Class gadgets.json
Fornece operações de conversão de objetos de e para JSON.

Resumo do método
<static> Object parse(text)
Analisa uma string JSON, produzindo um valor JavaScript.
<static> String stringify(v)
Converte um valor JavaScript em uma string JSON.

Detalhes do método

parse
<static> Object parse(text)

Analisa uma string JSON, produzindo um valor JavaScript.


Parâmetros:
String text - A string que será convertida em um objeto — normalmente, o
resultado de uma chamada stringify anterior
Retorna:
Object O objeto analisado do texto passado; false (falso) se ocorreu um erro

stringify
<static> String stringify(v)

Converte um valor JavaScript em uma string JSON.


Parâmetros:
Object v - O objeto a ser convertido
Retorna:
String O JSON equivalente
gadgets.util
Static Class gadgets.util
Fornece funções de utilitário de uso geral.

Resumo do método
<static> String escapeString(str)
Cria códigos de escape para os dados inseridos, usando entidades html para garantir maior
segurança.
<static> Object getFeatureParameters(feature)
Obtém os parâmetros do recurso.
<static> Object getUrlParameters()
Obtém os parâmetros do URL.
<static> Boolean hasFeature(feature)
Retorna se o recurso atual é suportado.
<static> makeClosure(scope, callback, var_args)
Cria um invólucro adequado para ser passado como um retorno de chamada.
<static> registerOnLoadHandler(callback)
Registra um manipulador durante a carga.
<static> String unescapeString(str)
Inverte escapeString.

Detalhes do método

escapeString
<static> String escapeString(str)

Cria códigos de escape para os dados inseridos, usando entidades html para garantir maior
segurança.
Parâmetros:
String str - A String para a qual serão criados os códigos de escape.
Retorna:
String A String com códigos de escape.

getFeatureParameters
<static> Object getFeatureParameters(feature)

Obtém os parâmetros do recurso.


Parâmetros:
String feature - O recurso para o qual os parâmetros serão obtidos
Retorna:
Object Os parâmetros do recurso em questão, ou null (nulo)
getUrlParameters
<static> Object getUrlParameters()

Obtém os parâmetros do URL.


Retorna:
Object Parâmetros passados para a string da consulta

hasFeature
<static> Boolean hasFeature(feature)

Retorna se o recurso atual é suportado.


Parâmetros:
String feature - O recurso a ser testado
Retorna:
Boolean True (verdadeiro) se o recurso for suportado

makeClosure
<static> makeClosure(scope, callback, var_args)

Cria um invólucro adequado para ser passado como um retorno de chamada. É possível
passar qualquer quantidade de argumentos ao retorno de chamada. Eles serão recebidos na
ordem em que forem passados.
Parâmetros:
Object scope - O escopo da execução; pode ser null se não houver necessidade
de associar uma instância específica de um objeto a este retorno de chamada
Function callback - O retorno de chamada a ser executado quando a
chamada for realizada; qualquer argumento será passado após os argumentos iniciais
Object var_args - Argumentos iniciais a serem passados ao retorno de
chamada

registerOnLoadHandler
<static> registerOnLoadHandler(callback)

Registra um manipulador durante a carga.


Parâmetros:
Function callback - O manipulador a ser executado

unescapeString
<static> String unescapeString(str)

Inverte escapeString.
Parâmetros:
String str - A String da qual serão removidos os códigos de escape.
Retorna:
String A String sem códigos de escape.
gadgets.MiniMessage
Classe gadgets.MiniMessage
Classe MiniMessage.

Resumo do construtor
gadgets.MiniMessage(opt_moduleId, opt_container)
Usado para criar mensagens que aparecerão para o usuário dentro do gadget.

Resumo do método
Element createDismissibleMessage(message, opt_callback)
Cria uma mensagem que pode ser dispensada, com um ícone [x] para permitir que os usuários
dispensem a mensagem.
Element createStaticMessage(message)
Cria uma mensagem estática que pode ser dispensada apenas programaticamente (através de
uma chamada a dismissMessage()).
Element createTimerMessage(message, seconds, opt_callback)
Cria uma mensagem que é exibida por um número especificado de segundos.
dismissMessage(message)
Dispensa a mensagem especificada.

Detalhes do construtor

gadgets.MiniMessage
gadgets.MiniMessage(opt_moduleId, opt_container)

Usado para criar mensagens que aparecerão para o usuário dentro do gadget.
Parâmetros:
String opt_moduleId - Id do módulo opcional
Element opt_container - Elemento opcional do recipiente HTML no qual
aparecerão as mini-mensagens.

Detalhes do método

createDismissibleMessage
Element createDismissibleMessage(message, opt_callback)

Cria uma mensagem que pode ser dispensada, com um ícone [x] para permitir que os
usuários dispensem a mensagem. Quando a mensagem é dispensada, ela é removida da
árvore DOM, e a função opcional de retorno de chamada, se estiver definida, é executada.
Parâmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
Function opt_callback - Função opcional de retorno de chamada a ser
executada quando a mensagem for dispensada
Retorna:
Element Elemento HTML da mensagem criada

createStaticMessage
Element createStaticMessage(message)

Cria uma mensagem estática que pode ser dispensada apenas programaticamente (através de
uma chamada a dismissMessage()).
Parâmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
Retorna:
Element Elemento HTML da mensagem criada

createTimerMessage
Element createTimerMessage(message, seconds, opt_callback)

Cria uma mensagem que é exibida por um número especificado de segundos. Quando o
temporizador expira, a mensagem é dispensada e a função opcional de retorno de chamada é
executada.
Parâmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
number seconds - Número de segundos que devem ser aguardados antes de a
mensagem ser dispensada
Function opt_callback - Função opcional de retorno de chamada a ser
executada quando a mensagem for dispensada
Retorna:
Element Elemento HTML da mensagem criada

dismissMessage
dismissMessage(message)

Dispensa a mensagem especificada.


Parâmetros:
Element message - Elemento HTML da mensagem que será removida
gadgets.Tab
Classe gadgets.Tab
Classe Tab para gadgets. Você pode criar guias usando o método TabSet addTab(). Para obter
objetos de Guia, use os métodos TabSet getSelectedTab() ou getTabs().
Veja também: TabSet

Resumo do método
Function getCallback()
Retorna a função de retorno de chamada, executada quando a guia é selecionada.
Element getContentContainer()
Retorna o elemento HTML no qual o conteúdo da guia é visualizado.
Number getIndex()
Retorna o índice da guia.
String getName()
Retorna o marcador da guia na forma de uma string (pode conter HTML).
Element getNameContainer()
Retorna o elemento HTML que contém o marcador da guia.

Detalhes do método

getCallback
Function getCallback()

Retorna a função de retorno de chamada, executada quando a guia é selecionada.


Retorna:
Function A função de retorno de chamada da guia.

getContentContainer
Element getContentContainer()

Retorna o elemento HTML no qual o conteúdo da guia é visualizado.


Retorna:
Element O elemento HTML do recipiente do conteúdo.

getIndex
Number getIndex()

Retorna o índice da guia.


Retorna:
Number O índice da guia.
getName
String getName()

Retorna o marcador da guia na forma de uma string (pode conter HTML).


Retorna:
String O marcador da guia.

getNameContainer
Element getNameContainer()

Retorna o elemento HTML que contém o marcador da guia.


Retorna:
Element O elemento HTML do marcador da guia.
gadgets.TabSet
Classe gadgets.TabSet
Uma classe que pode ser usada pelos gadgets para criar guias.

Resumo do construtor
gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)
Cria um novo objeto TabSet

Resumo do método
String addTab(tabName, opt_params)
Adiciona uma nova guia com base nos pares nome-valor especificados em opt_params.
alignTabs(align, opt_offset)
Define o alinhamento das guias.
displayTabs(display)
Exibe ou oculta guias e todo o conteúdo associado a elas.
Element getHeaderContainer()
Retorna o elemento cabeçalhos de guia do recipiente.
gadgets.Tab getSelectedTab()
Retorna o objeto de guia selecionado no momento.
Array.<gadgets.Tab> getTabs()
Retorna uma matriz de todos os objetos de guia existentes.
removeTab(tabIndex)
Remove uma guia do tabIndex (índice de guias) e todo o conteúdo associado a ela.
setSelectedTab(tabIndex)
Seleciona a guia no tabIndex e ativa a função de retorno de chamada da guia, se existir.
swapTabs(tabIndex1, tabIndex2)
Troca as posições das guias em tabIndex1 e tabIndex2.

Detalhes do construtor

gadgets.TabSet
gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

Cria um novo objeto TabSet


Parâmetros:
String opt_moduleId - Sufixo opcional para o ID do recipiente da guia.
String opt_defaultTab - Nome de guia opcional que especifica o nome da
guia selecionada após a inicialização. Se esse parâmetro for omitido, a primeira guia
é selecionada por padrão.
Element opt_container - O elemento HTML que conterá as guias. Se
omitido, um novo elemento div é criado e inserido no alto.
Detalhes do método

addTab
String addTab(tabName, opt_params)

Adiciona uma nova guia com base nos pares nome-valor especificados em opt_params.
Parâmetros:
String tabName - Marcador da guia a ser criada.
Object opt_params - Objeto de parâmetro opcional. As seguintes propriedades
são suportadas: .contentContainer. É um elemento HTML existente a ser usado como
recipiente do conteúdo da guia. Se omitido, a biblioteca de guias cria um elemento.
.callback. É uma função de retorno de chamada a ser executada quando a guia é
selecionada. .tooltip. É uma descrição de dica de ferramenta que aparece quando o
usuário move o cursor do mouse sobre a guia. .index. É o índice no qual a guia será
inserida. Se omitido, a nova guia é anexada no final.
Retorna:
String Id do DOM do recipiente da guia.

alignTabs
alignTabs(align, opt_offset)

Define o alinhamento das guias. Por padrão, as guias são centralizadas.


Parâmetros:
String align - 'left' (esquerda), 'center' (centralizado) ou 'right' (direita).
Number opt_offset - Parâmetro opcional para definir o número de pixels de
deslocamento das guias em relação à margem esquerda ou direita. O valor padrão é
3px.

displayTabs
displayTabs(display)

Exibe ou oculta guias e todo o conteúdo associado a elas.


Parâmetros:
Boolean display - true (verdadeiro) para exibir as guias; false (falso) para
ocultar as guias.

getHeaderContainer
Element getHeaderContainer()

Retorna o elemento cabeçalhos de guia do recipiente.


Retorna:
Element O elemento cabeçalhos de guia do recipiente.

getSelectedTab
gadgets.Tab getSelectedTab()
Retorna o objeto de guia selecionado no momento.
Retorna:
gadgets.Tab O objeto de guia selecionado no momento.

getTabs
Array.<gadgets.Tab> getTabs()

Retorna uma matriz de todos os objetos de guia existentes.


Retorna:
Array.<gadgets.Tab> Matriz de todos os objetos de guia existentes.

removeTab
removeTab(tabIndex)

Remove uma guia do tabIndex (índice de guias) e todo o conteúdo associado a ela.
Parâmetros:
Number tabIndex - Índice da guia a ser removida.

setSelectedTab
setSelectedTab(tabIndex)

Seleciona a guia no tabIndex e ativa a função de retorno de chamada da guia, se existir. Se a


guia já estiver selecionada, o retorno de chamada não é ativado.
Parâmetros:
Number tabIndex - Índice da guia a ser selecionada.

swapTabs
swapTabs(tabIndex1, tabIndex2)

Troca as posições das guias em tabIndex1 e tabIndex2. A guia selecionada não é alterada e
nenhuma função de retorno de chamada é executada.
Parâmetros:
Number tabIndex1 - Índice da guia a ser trocada.
Number tabIndex2 - Índice da segunda guia a ser trocada.
gadgets.flash
Static Class gadgets.flash
Integra conteúdo Flash nos gadgets.

Resumo do método
<static> Boolean embedCachedFlash()
Injeta um arquivo Flash com cache na árvore DOM.
<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion,
opt_params)
Injeta um arquivo Flash na árvore DOM.
<static> Number getMajorVersion()
Detecta o Flash Player e sua versão principal.

Detalhes do método

embedCachedFlash
<static> Boolean embedCachedFlash()

Injeta um arquivo Flash com cache na árvore DOM. Aceita os mesmos parâmetros que
gadgets.flash.embedFlash.
Retorna:
Boolean Se a chamada à função for concluída com sucesso.

embedFlash
<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)

Injeta um arquivo Flash na árvore DOM.


Parâmetros:
String swfUrl - SWF URL.
String, Object swfContainer - O ID ou referência de objeto de um
elemento existente do recipiente html.
Number swfVersion - Versão mínima do Flash Player necessária.
Object opt_params - Um objeto opcional que pode conter qualquer parâmetro
html válido. Todos os atributos serão passados através do filme flash durante a
criação.
Retorna:
Boolean Se a chamada à função for concluída com sucesso.

getMajorVersion
<static> Number getMajorVersion()

Detecta o Flash Player e sua versão principal.


Retorna:
Number A versão principal do Flash Player ou 0 se o Flash não for suportado.
gadgets.rpc
Static Class gadgets.rpc
Fornece operações para realizar chamadas rpc.

Resumo do método
<static> call(targetId, serviceName, callback, var_args)
Chama um serviço RPC.
<static> register(serviceName, handler)
Registra um serviço RPC.
<static> registerDefault(handler)
Registra um manipulador de serviços padrão para processar todas as chamadas RPC
desconhecidas, que falham sem aviso por padrão.
<static> unregister(serviceName)
Cancela o registro de um serviço RPC.
<static> unregisterDefault()
Cancela o manipulador de serviços padrão.

Detalhes do método

call
<static> call(targetId, serviceName, callback, var_args)

Chama um serviço RPC.


Parâmetros:
String targetId - Id do provedor de serviços RPC. Vazio, se estiver fazendo
uma chamada ao recipiente pai.
String serviceName - Nome do serviço a ser chamado.
Function, null callback - Função de retorno de chamada (se houver) para
processar o valor retornado pela solicitação de RPC.
* var_args - Parâmetros para a solicitação de RPC.

register
<static> register(serviceName, handler)

Registra um serviço RPC.


Parâmetros:
String serviceName - Nome do serviço a ser registrado.
Function handler - Manipulador de serviços.

registerDefault
<static> registerDefault(handler)
Registra um manipulador de serviços padrão para processar todas as chamadas RPC
desconhecidas, que falham sem aviso por padrão.
Parâmetros:
Function handler - Manipulador de serviços.

unregister
<static> unregister(serviceName)

Cancela o registro de um serviço RPC.


Parâmetros:
String serviceName - Nome do serviço cujo registro será cancelado.

unregisterDefault
<static> unregisterDefault()

Cancela o manipulador de serviços padrão. As futuras chamadas RPC desconhecidas


falharão sem aviso.
gadgets.views
Static Class gadgets.views
Fornece operações para lidar com Visualizações.

Resumo do método
<static> gadgets.views.View getCurrentView()
Retorna a visualização atual.
<static> Map.<String, String> getParams()
Retorna os parâmetros passados a este gadget para esta visualização.
<static> Map<gadgets.views.ViewType, String, gadgets.views.View>
getSupportedViews()
Retorna um mapa de todas as visualizações suportadas.
<static> requestNavigateTo(view, opt_params)
Tenta ir para uma visualização diferente deste gadget.

Detalhes do método

getCurrentView
<static> gadgets.views.View getCurrentView()

Retorna a visualização atual.


Retorna:
gadgets.views.View A visualização atual

getParams
<static> Map.<String, String> getParams()

Retorna os parâmetros passados a este gadget para esta visualização. Não inclui todos os
parâmetros de URL, somente os passados para gadgets.views.requestNavigateTo
Retorna:
Map.<String, String> O mapa de parâmetros

getSupportedViews
<static> Map<gadgets.views.ViewType, String, gadgets.views.View>
getSupportedViews()

Retorna um mapa de todas as visualizações suportadas. Associa cada gadgets.view.View ao


seu nome.
Retorna:
Map<gadgets.views.ViewType, String, gadgets.views.View>
Todas as visualizações suportadas, associadas ao atributo dos seus nomes.
requestNavigateTo
<static> requestNavigateTo(view, opt_params)

Tenta ir para uma visualização diferente deste gadget. Se o recipiente suportar parâmetros,
ele passará os parâmetros opcionais para o gadget na nova visualização.
Parâmetros:
gadgets.views.View view - A visualização de destino
Map.<String, String> opt_params - Parâmetros a serem passados ao
gadget após a visualização ser acessada
gadgets.views.View
Classe gadgets.views.View
Interface básica para todos os objetos de visualização.

Resumo do método
gadgets.views.ViewType, String getName()
Retorna o nome desta visualização.
boolean isOnlyVisibleGadget()
Retorna true (verdadeiro) se o gadget for o único gadget visível nesta visualização.

Detalhes do método

getName
gadgets.views.ViewType, String getName()

Retorna o nome desta visualização.


Retorna:
gadgets.views.ViewType, String O nome da visualização, normalmente
especificado como um gadgets.views.ViewType

isOnlyVisibleGadget
boolean isOnlyVisibleGadget()

Retorna true (verdadeiro) se o gadget for o único gadget visível nesta visualização. Em uma
página de tela inteira ou no modo maximizado, provavelmente é true (verdadeiro); em uma
página de perfil ou no modo painel, provavelmente é false (falso).
Retorna:
boolean True se o gadget for o único gadget visível; caso contrário, false
gadgets.views.ViewType
Static Class gadgets.views.ViewType
Usada pelas Visualizações.

Resumo do campo
<static> object DASHBOARD
Uma visualização na qual o gadget é exibido em uma pequena área, normalmente em uma
página com outros gadgets.
<static> object FULL_PAGE
Uma visualização na qual o gadget é exibido em um modo muito grande.
<static> object POPUP
Uma visualização na qual o gadget é exibido sozinho em uma pequena janela separada.

Detalhes do campo

DASHBOARD
<static> object DASHBOARD

Uma visualização na qual o gadget é exibido em uma pequena área, normalmente em uma
página com outros gadgets. Em um contexto social, esta normalmente é chamada de página
de perfil.

FULL_PAGE
<static> object FULL_PAGE

Uma visualização na qual o gadget é exibido em um modo muito grande. Deve ser a única
coisa na página. Em um contexto social, esta normalmente é chamada de página de tela
inteira.

POPUP
<static> object POPUP

Uma visualização na qual o gadget é exibido sozinho em uma pequena janela separada.
gadgets.skins
Static Class gadgets.skins
Fornece operações para obter informações de exibição sobre a skin exibida atualmente.

Resumo do método
<static> String getProperty(propertyKey)
Obtém a propriedade de exibição mapeada para a chave em questão.

Detalhes do método

getProperty
<static> String getProperty(propertyKey)

Obtém a propriedade de exibição mapeada para a chave em questão.


Parâmetros:
String propertyKey - A chave para a qual os dados são obtidos; as chaves
estão definidas em gadgets.skins.Property
Retorna:
String Os dados
gadgets.skins.Property
Static Class gadgets.skins.Property
Todos os valores de exibição que podem ser obtidos e usados na interface do usuário dos gadgets.
Estas são as chaves suportadas para o método gadgets.skins.getProperty().

Resumo do campo
<static> object ANCHOR_COLOR
A cor que deve ser usada pelas tags anchor.
<static> object BG_COLOR
A cor de fundo do gadget.
<static> object BG_IMAGE
Uma imagem a ser usada no fundo do gadget.
<static> object FONT_COLOR
A cor que deve ser usada pela fonte principal.

Detalhes do campo

ANCHOR_COLOR
<static> object ANCHOR_COLOR

A cor que deve ser usada pelas tags-âncora.

BG_COLOR
<static> object BG_COLOR

A cor de fundo do gadget.

BG_IMAGE
<static> object BG_IMAGE

Uma imagem a ser usada no fundo do gadget.

FONT_COLOR
<static> object FONT_COLOR

A cor que deve ser usada pela fonte principal.


gadgets.window
Static Class gadgets.window
Fornece operações para obter informações e alterar a janela na qual o gadget é colocado.

Resumo do método
<static> adjustHeight(opt_height)
Ajusta a altura do gadget
<static> Object getViewportDimensions()
Detecta as dimensões internas de um frame.
<static> setTitle(title)
Define o título do gadget.

Detalhes do método

adjustHeight
<static> adjustHeight(opt_height)

Ajusta a altura do gadget


Parâmetros:
Number opt_height - Uma altura opcional escolhida, em pixels. Se não for
especificada, tentará ajustar o gadget ao seu conteúdo.

getViewportDimensions
<static> Object getViewportDimensions()

Detecta as dimensões internas de um frame. Para obter mais informações consulte:


http://www.quirksmode.org/viewport/compatibility.html.
Retorna:
Object Um objeto com propriedades de largura e altura.

setTitle
<static> setTitle(title)

Define o título do gadget.


Parâmetros:
String title - O título escolhido