Documentacao - OpenSocial PDF

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 tendncia tambm criou uma lista crescente de APIs especficas
para sites, que os desenvolvedores precisam aprender.
O servio OpenSocial oferece um conjunto de APIs comuns para desenvolver aplicativos sociais
que iro funcionar em diversos sites. Elas possibilitam que os desenvolvedores criem aplicativos
utilizando JavaScript e HTML padro 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 esto 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 comear 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 mnimos 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 tambm pode hospedar seu aplicativo em seus prprios 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.
Sees Tpicos selecionados
"Hello, World"
Primeiros passos
Em que consiste um Gadget?
Etapas bsicas
Criao dos seus prprios gadgets
Anatomia de um gadget
Seleo do tipo de contedo
Como transformar uma pgina da web ou aplicativo
existente em um gadget
Fundamentos do desenvolvimento
Uso de tipos de dados Userpref
Como salvar o estado
Criao de gadgets que necessitam de login ou cookies
Dicas de programao e depurao
Ferramentas para desenvolvedores Hospedagem atravs do Google Gadgets Editor
Hospedagem no Google Code
Gerenciamento da altura do gadget
Definio do ttulo do gadget
Criao de uma interface de
Guias
usurio
MiniMessages
Flash
Uso de texto
Uso de XML
Uso de contedo remoto
Uso de feeds
Uso de JSON
Criao de um gadget localizado
Internacionalizao Pacotes de mensagens
Uso de pacotes de mensagens em um gadget
Gadgets em idiomas diferentes do Onde posso encontrar gadgets que no sejam em ingls?
ingls Criao de gadgets em idiomas diferentes do ingls
Onde posso colocar meu gadget?
Publicao do seu gadget Preparao para a publicao
Publicao no diretrio de contedo do iGoogle
Preferncias do gadget
Referncia das especificaes de
Preferncias do usurio
gadgets
Seo de contedo
Referncia de JavaScript
Primeiros passos
Bem-vindo API de gadgets!
Este guia do desenvolvedor baseado na verso 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 programao e suporte. Para saber mais sobre a API de gadgets.*, consulte a
documentao de referncia aqui. Embora a API de gadgets.* tenha muita coisa em comum com
a API de gadgets antiga, tambm h diferenas 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 documentao do seu recipiente especfico
para saber qual API suportada. Para saber mais sobre os tipos diferentes de gadgets e onde eles
podem ser executados, consulte a Viso geral da API de gadgets.
Este guia do desenvolvedor destina-se a pessoas que desejam usar a API para criar gadgets. Por
serem muito fceis de criar, os gadgets so um excelente ponto de partida se voc estiver
comeando a aprender sobre programao da web.
Hello, World"
O gadget mais simples tem apenas algumas linhas de cdigo. 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 so especificados em XML. A primeira linha a maneira padro de iniciar um
arquivo XML. Esta deve ser a primeira linha do arquivo.
A tag <Module> indica que este arquivo XML contm um gadget.
A tag <ModulePrefs> contm informaes sobre o gadget, como seu ttulo, descrio,
autor e outros recursos opcionais.
A linha <Content type="html"> indica que o tipo de contedo do gadget HTML.
<![CDATA[ ...insert HTML here... ]]> usada como invlucro para o HTML
quando o tipo de contedo do gadget html. Ela informa ao analisador do gadget que o
texto dentro da seo CDATA no deve ser tratado como XML. A seo CDATA
normalmente contm HTML e JavaScript.
</Content> significa o final da seo Contedo.
</Module> significa o final da definio do gadget.
Em que consiste um Gadget?

A API de gadgets consiste em alguns blocos estruturais simples: XML, HTML e JavaScript. Para
comear, voc s precisa de conhecimentos bsicos de HTML. Ns ensinaremos tudo o que
necessrio sabe sobre XML para criar gadgets. Mais tarde, ao criar gadgets mais sofisticados, voc
provavelmente aprender como usar JavaScript, caso ainda no 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 especificaes 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 contm instrues sobre como processar e exibir o gadget. O
arquivo XML pode conter todos os dados e cdigos do gadget, ou pode ter referncias (URLs) para
o local onde o restante dos elementos se encontram.
HTML a linguagem de markup usada para formatar pginas da internet. O contedo esttico de
um gadget normalmente criado em HTML. A linguagem HTML tem aparncia semelhante
XML, mas usada para formatar documentos da web e no para descrever dados estruturados.
JavaScript uma linguagem de scripts que pode ser usada para adicionar comportamento dinmico
aos gadgets.
Criao dos seus prprios gadgets
O guia Primeiros passos fornece a voc uma introduo sobre como usar gadgets. A prxima etapa
a criao dos seus prprios gadgets. Este documento ensina como fazer isso.
Etapas bsicas
Aqui esto as etapas bsicas que voc deve seguir para criar e implementar um gadget:
1. Use qualquer editor de texto para escrever as especificaes do seu gadget e guarde essas
informaes em um servidor da web pblico.
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
avanados nas especificaes do seu gadget. A especificao do gadget XML composta por 3
partes principais:
Seo de contedo. A seo <Content> onde ocorre o funcionamento mais importante
do seu gadget. onde voc especifica o tipo de gadget, a lgica de programao e,
freqentemente, os elementos HTML que determinam a aparncia do gadget.
Preferncias do usurio. A seo <UserPrefs> define os controles que permitem que os
usurios especifiquem configuraes do gadget. Por exemplo, um gadget de saudaes
personalizadas pode fornecer um campo de texto para o usurio especificar seu nome.
Preferncias do gadget. A seo <ModulePrefs> do arquivo XML especifica as
caractersticas do gadget, como ttulo, autor, tamanho preferido e assim por diante.
Observao: Dentro dos atributos XML das especificaes de um gadget, alguns caracteres
precisam ter um "escape" (ou seja, precisam ser codificados adequadamente) para que sejam
interpretados corretamente. Para obter mais informaes, consulte Codificao de escape de
caracteres especiais.
Ao criar um gadget, comece pela seo <Content>.
Definio de contedo
A seo <Content> representa o "crebro" de um gadget. A seo <Content> define o tipo de
contedo e contm o prprio contedo ou um link para contedo externo. A seo <Content>
onde os atributos do gadget e as preferncias do usurio so combinados lgica de programao e
s informaes de formatao para se transformarem em um gadget executvel.
A maneira mais fcil de criar um gadget simplesmente colocando HTML (e como opo,
JavaScript ou Flash) na seo <Content>. Os desenvolvedores de web experientes podem usar a
seo Seleo do tipo de contedo para obter outras opes relacionadas a controle de acesso,
hospedagem remota, uso de linguagens de scripts alternativas e outros tpicos. 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 pgina HTML:
<Module>
<ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
<![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>
Definio das preferncias do usurio

Alguns gadgets precisam fornecer um meio de informaes especficas ao usurio serem inseridas.
Por exemplo, um gadget de jogo pode permitir que o usurio digite uma preferncia de nvel de
dificuldade. A seo de preferncias do usurio (<UserPref>) do arquivo XML descreve os
campos de entrada do usurio que so transformados em controles da interface de usurio quando o
gadget executado. As preferncias do usurio so continuamente armazenadas.
Por exemplo, este gadget exibe uma saudao pessoal com base na hora do dia. Ele permite que os
usurios especifiquem o seguinte:
Um nome a ser usado na saudao. O nome tambm exibido na barra de ttulo.
Uma cor de fundo.
A exibio ou no de uma foto.
Esta a aparncia do gadget quando o usurio clica em edit (editar) para modificar as preferncias
do usurio:
As preferncias do usurio que so transformadas em controles da interface de usurio do gadget

sendo executado so definidas na especificao XML, conforme mostrado abaixo:
<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 contm o texto title="Preferences for __UP_myname__".
Ao executar o gadget, o valor fornecido pela preferncia de usurio myname substitudo
dinamicamente por __UP_myname__.
A preferncia de usurio myname est marcada como "obrigatria". Se o usurio tentar
executar o gadget sem fornecer um valor para esse campo, a caixa de edio das preferncias
de usurio permanece aberta at que um valor seja fornecido.
A preferncia de usurio mychoice possui o tipo de dados bool. Ela exibida na interface
de usurio como uma caixa de seleo.
A preferncia de usurio mycolor possui o tipo de dados enum. A lista de EnumValues
especifica as opes que aparecem em um menu suspenso na caixa de edio das
preferncias do usurio.
Aqui est o gadget completo, incluindo o JavaScript que exibe a saudao do gadget:
<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="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 Referncia para obter uma lista de todos os atributos de <UserPref>.

Use a API JavaScript para acessar as preferncias do usurio a partir do seu gadget; por exemplo:
var someStringPref = prefs.getString("StringPrefName");
var someIntPref = prefs.getInt("IntPrefName");
var someBoolPref = prefs.getBool("BoolPrefName");
</script>
Consulte a Referncia de JavaScript para obter uma lista de todas as funes JavaScript.
Variveis de substituio de preferncias do usurio

Voc pode usar uma varivel de substituio do formato __UP_userpref__ nas sees
<ModulePrefs> ou <UserPref>, onde userpref corresponde ao atributo name (nome) de uma
preferncia de usurio. Quando o gadget executado, o valor da string da preferncia de usurio
correspondente substitudo pela varivel, sem a adio de cdigos de escape. Por exemplo, neste
trecho, o valor fornecido pelo usurio durante a execuo para a preferncia de usurio projects
(projetos) substitudo 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 preferncias do usurio.

Aqui esto algumas orientaes gerais para o uso de variveis de substituio de preferncias de
usurio:
Para o atributo <ModulePrefs> title, use __UP_name__ . Esta varivel possui
cdigos de escape de HTML.
Para o atributo <ModulePrefs> title_url, use __UP_name__ . Esta varivel possui
cdigos de escape de URL.
No HTML dentro da seo <Content>, use __UP_name__. Esta varivel possui cdigos
de escape de HTML.
No cdigo JavaScript dentro da seo <Content>, use a funo gadgets.Prefs().
Definio das preferncias do gadget

A seo <ModulePrefs> do arquivo XML especifica as caractersticas do gadget, como ttulo,
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 usurios do seu gadget no podem alterar esses atributos.

Consulte a Referncia para obter uma lista completa dos atributos de <ModulePrefs>.
Lembre-se: Gadgets so pblicos

Lembre-se de que no existem gadgets privados. Quando voc publica seu gadget em um site
pblico, as pessoas podem encontr-lo e visualiz-lo. Procure no incluir informaes pessoais,
como seu nmero de telefone ou endereo de e-mail pessoal.
E se voc no quiser que seu gadget seja pblico? O Google encoraja os autores de gadgets a
compartilharem suas especificaes. Entretanto, aqui esto algumas dicas de como minimizar a
visibilidade pblica do seu gadget at que voc esteja pronto para lan-lo:
No envie seu gadget para o diretrio de contedo ou para diretrios como o
googlemodules.com ou hotmodules.com.
Se as pessoas no puderem encontrar seu gadget, improvvel que descubram o URL. Para
evitar que ele seja indexado por mecanismos de busca, voc pode usar alguns artifcios:
Procure impedir que o seu servidor da web fornea uma listagem de arquivos
incluindo o seu arquivo (isso tambm afasta os usurios bisbilhoteiros).
Verifique se no h hyperlinks na web apontando para o seu gadget
Fundamentos do desenvolvimento
Este documento descreve os conceitos e tarefas bsicas para o processo de desenvolvimento do
gadget. Para obter informaes sobre como usar a API de gadgets, leia Primeiros passos.
Seleo do tipo de contedo

Uma das primeiras decises que voc deve tomar ao desenvolver um gadget que tipo de contedo
ir usar. Por exemplo:
O tipo de contedo determina:

Que recursos da API esto disponveis para voc como autor do gadget.
Como seu gadget exibido.
Onde seu gadget pode ser implementado.
A tabela a seguir descreve os tipos de contedo disponveis e quando voc deve us-los:
Tipo de
Descrio Quando usar
contedo
Com o tipo de contedo html, o contedo
completo normalmente reside nas especificaes O tipo de contedo mais flexvel e
html do gadget. Um gadget type="html" contm verstil o html. Na dvida,
HTML, possivelmente com JavaScript, Flash, selecione o tipo de contedo html.
ActiveX ou outros objetos incorporados ao
navegador. Este o tipo padro.
Com o tipo de contedo url, o contedo do Atualmente, o tipo de contedo
gadget reside em uma pgina da web remota que type="url" no totalmente
pode ser acessada por meio de um URL suportado pelos gadgets.* ou
url localizado nas especificaes do gadget. A APIs do OpenSocial. Se desejar usar
pgina da web remota onde reside todo o o tipo de contedo type="url"
markup HTML e o JavaScript. Voc NO pode com as bibliotecas de gadgets
colocar nenhum markup HTML ou cdigo JavaScript, use a API de gadgets
JavaScript nas especificaes do gadget. antiga.
HTML
Com o tipo de contedo html, o cdigo completo normalmente reside nas especificaes 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 contedo html. Ele o tipo mais flexvel e
verstil e voc deve normalmente optar por ele, a menos que esteja criando um gadget com
requisitos especficos.
O exemplo a seguir demonstra a implementao de um gadget do recurso ROT13. O ROT13
criptografa textos substituindo cada letra pela letra que est 13 posies frente no alfabeto.
Quando o recurso ROT13 reaplicado, ele rotaciona cada letra novamente, restaurando o texto
original.
Esta a especificao do gadget:
<Module>
<ModulePrefs title="Magic Decoder"/>
<![CDATA[
// 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>
]]>
</Content>
</Module>
As regras para um gadget type="html" so as seguintes:

Um gadget type="html" deve conter uma seo CDATA, e todos os cdigos HTML
devem estar dentro dessa seo:
<![CDATA[ HTML here... ]]>
As sees CDATA so usadas para adicionar cdigos de escape a blocos de texto

contendo caracteres que, de outra forma, seriam considerados markup. O nico
separador reconhecido em uma seo CDATA a string "]]>", que finaliza a seo
CDATA.
Voc no pode usar as tags <html>, <head>, ou <body>. Os gadgets so gerados com
suas prprias tags <html>, <head>, e <body>. Basta incluir o contedo que
normalmente ficaria dentro da tag <body>.
Um gadget com tipo de contedo html tambm pode fazer referncia a um arquivo JavaScript
externo:
<Module>
<ModulePrefs ... />
<script src="http://www.example.com/gadgets/clock/clock.js"
type="text/javascript"></script>
]]></Content>
</Module>
URL
Quando um gadget possui o tipo de contedo type="url", o atributo href= fornece um URL e
qualquer outro contedo da especificao do gadget ignorado. Com o tipo de contedo url,
supe-se que todas as informaes relacionadas interface de usurio e lgica programtica do
gadget residem no arquivo apontado pelo URL. No 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 descrio
Como transformar uma pgina da web ou aplicativo existente

em um gadget
Para transformar uma pgina da web ou aplicativo existente em um gadget, siga as orientaes
abaixo:
Remova as tags <html>, <head> e <body> (em outras palavras, fornea apenas o
contedo HTML). Esta diretriz aplica-se somente a gadgets type="html". Ela no se
aplica a gadgets type="url".
Para eventos onload, use gadgets.util.registerOnLoadHandler().
Se o gadget exigir login, use um tipo de contedo URL. Consulte a seo Criao de gadgets
que necessitam de login ou cookies para saber como lidar com situaes que podem ser
consideradas "armadilhas". Gadgets HTTPS emitem avisos de "contedo misto" no Internet
Explorer, o que pode incomodar os usurios.
Faa as alteraes necessrias na interface do usurio para ajustar sua pgina ou aplicativo
no pequeno espao do gadget. O makeRequest() pode ser usado como proxy do
contedo de amadores e profissionais criando prottipos. Para gadgets desenvolvidos
comercialmente, recomendamos simplesmente criar uma pequena pgina nova e usar o
type="url" apontando para ela.
Uso de tipos de dados Userpref
Cada preferncia de usurio tem um tipo de dados dentro da especificao do gadget. O datatype
uma string opcional que especifica o tipo de dados do atributo. Os valores possveis de
datatype so string, bool, enum, hidden (uma string invisvel que no pode ser editada
pelo usurio), list e location (para gadgets baseados no Google Maps). O tipo de dados
padro string.
Consulte a referncia para obter informaes detalhadas sobre os tipos de dados das preferncias do
usurio.
Esta seo descreve dois dos tipos de dados mais especializados: list e location. Voc pode
encontrar exemplos de como usar os outros tipos de dados na documentao (por exemplo, enum,
hidden e bool).
Uso do tipo de dados list

Uma preferncia de usurio com o tipo de dados list uma matriz de valores fornecidos
dinamicamente pelos usurios durante a execuo. medida que os usurios digitam valores na
caixa de edio de preferncias do usurio, os valores so adicionados lista. Assim como qualquer
outro userpref, a lista pode ser acessada programaticamente pelo gadget durante a execuo. Voc
pode usar o tipo de dados list sempre que quiser permitir que os usurios forneam uma lista de
valores arbitrrios dinamicamente. Por exemplo, um gadget de condies climticas pode permitir
que os usurios digitem uma lista de cdigos 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 funo Prefs getArray(),; por exemplo:
var search_terms = prefs.getArray("mylist");
Dentro da matriz, os itens so armazenados em uma lista separada por barras verticais. Voc pode
usar a funo getString() de Prefs para retornar esta lista como uma nica string na qual os
valores so separados pelo caractere barra vertical (|); por exemplo:
prefs.getString("mylist");
Voc tambm pode usar uma string separada por barras verticais para definir os valores padro de
um tipo de dados list:
<UserPref name="mylist" display_name="Add Search Terms" datatype="list"
default_value="zdnet|pc|Apple Insider"/>
Use a funo setArray(name, val) de Prefs para adicionar valores lista

programaticamente. Para usar essa funo, 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 usurio na caixa Edit
(Editar):
<Module>
<ModulePrefs
title="List Data Type Example"
scrolling="true"/>
<UserPref name="mylist"
display_name="Add Terms"
datatype="list" />
<![CDATA[
<div id=content_div></div>
// Get userprefs
// 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 cdigo postal dos Estados Unidos,
Canad ou Reino Unido. O uso de cdigos 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 usurio.
<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" />
<![CDATA[
<script src="http://maps.google.com/maps?file=js"
type="text/javascript"></script>
<div id="map" style="width: 100%; height: 100%;"></div>
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 preferncia x de location:

Se x for uma string vazia (significando um local vazio), x.lat e x.long so a string
vazia.
Se x no puder ser geocodificada (significando um local invlido), x.lat e x.long so
0.0.
As verses anteriores da API de gadgets no permitiam especificar um default_value para o
tipo de local. Mas agora isso mudou.
Como salvar o estado

comum permitir que os usurios definam suas preferncias de forma explcita, atravs da caixa de
edio. Entretanto, s vezes til definir programaticamente os valores das preferncias do usurio,
sem sua participao direta. Por exemplo, em um gadget de jogo, voc pode armazenar
continuamente a pontuao mais alta do usurio. Voc pode fazer isso de maneira programtica,
definindo o valor de uma preferncia de usurio "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 funo JavaScript set() para a userpref cujo valor voc deseja salvar.
O tamanho da preferncia atualmente est restrito por limitaes de URL, podendo chegar a 2K.
O gadget da amostra a seguir consiste em dois botes: um que aumenta o valor de um contador, e
outro que redefine o valor do contador para 0. Neste exemplo, "counter" uma preferncia de
usurio. O tipo de dados hidden, o que significa que os usurios no tm permisso de
modificar diretamente o valor.
Esta a especificao do gadget:
<Module>
<ModulePrefs
title="Setprefs New">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<UserPref
name="counter"
default_value="0"
datatype="hidden"/>
<![CDATA[
<div id="content_div" style="height: 100px;"></div>
// Get user preferences

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>
Observao: Se for necessrio armazenar diversos valores, recomendamos salv-los em uma string
JSON.
Codificao de escape de caracteres especiais

necessrio adicionar cdigos de escape a determinados caracteres especiais dentro dos atributos
XML de uma especificao de gadget. Voc pode usar somente entidades ASCII na especificao
do gadget. Por exemplo, no possvel usar entidades do smbolo ISO 8859-1. Aqui est uma lista
dos caracteres especiais suportados:
Caractere Codificao de escape
& &
< <
> >
" "
' '
Por exemplo:
BAD: href="http://www.foo.com/bar?x=a&y=b"
GOOD: href="http://www.foo.com/bar?x=a&y=b"
BAD: description="this is a "sexy" gadget"
GOOD: description="this is a "sexy" gadget"
Observe que esse tipo de escape no necessrio no bloco CDATA. Entretanto, seu uso
recomendvel.
Dentro do cdigo JavaScript, use a funo _hesc(str) para retornar a string HTML str com os
caracteres abaixo seguidos do cdigo de escape: <>'".
Criao de gadgets que necessitam de login ou cookies

As polticas de privacidade padro do Microsoft Internet Explorer e do Apple Safari no permitem
que sites de terceiros definam cookies. Portanto, alguns gadgets podem no funcionar corretamente.
Os sites que usam cookies para login, especificamente, podem no funcionar corretamente dentro
de um iframe da pgina do iGoogle. Veja algumas solues possveis:
Use parmetros URL em vez de cookies. Por exemplo, o Orkut birthdays gadget
(aniversrios do Orkut) passa credenciais de autenticao via URL. Aviso importante: Se
voc optar por este mtodo, tenha cuidado para que esses parmetros de URL no vazem
para outros sites da web nos campos HTTP de direcionamento.
Crie cabealhos P3P. Dependendo da poltica de privacidade do seu site, talvez voc possa
criar cabealhos P3P, os quais permitem que o Internet Explorer (mas no o Safari) leia
cookies de terceiros do seu site. Se voc estiver usando PHP e desejar definir os cabealhos,
use este snippet de cdigo no alto da sua pgina PHP:
<?php
header("P3P: CP=\"CAO PSA OUR\"");
?>
Esse comando deve ser chamado antes da exibio de qualquer resultado na pgina.
VERIFIQUE SUA POLTICA DE PRIVACIDADE CUIDADOSAMENTE QUANTO

AOS CABEALHOS QUE PODEM SER USADOS EM SEU SITE.
ENCORAJAMOS VOC A CONSULTAR SEU ADVOGADO.
Informe os usurios. Isso pode ser feito em JavaScript, como nesta amostra de gadget
(experimente) . Voc tambm pode integrar instrues sua lgica de autenticao. Se
detectar o bloqueio de cookies, informe os usurios que eles devem afrouxar sua
configurao de privacidade ou experimentar um navegador diferente. Por exemplo, voc
pode exibir uma mensagem como:
Seu navegador no compatvel com este site na configurao atual. Se estiver usando
o Microsoft Internet Explorer, altere sua configurao de segurana selecionando
Ferramentas > Opes da Internet. Abra a guia Privacidade, clique em Avanado e,
em seguida, clique em Ignorar manipulao automtica de cookies. Em Cookies
Secundrios, clique em Aceitar. Como alternativa, voc pode usar outro navegador,
como o Firefox.
Ferramentas para desenvolvedores
Este documento fornece diretrizes gerais para programao, depurao e hospedagem de gadgets.
Dicas de programao e depurao

Parte do processo de desenvolvimento de um gadget (ou do processo de desenvolvimento de
qualquer cdigo) compreender que nem sempre as coisas funcionam como se espera. Esta seo
descreve algumas tcnicas bsicas para evitar problemas e para corrigi-los quando ocorrerem.
Comece pelo mais simples

Uma regra fundamental da programao comear pelo mais simples. Obtenha uma estrutura
bsica de gadget que esteja operante e amplie essa estrutura gradualmente. Teste-a a cada estgio
antes de prosseguir. Com essa estratgia, mais fcil descobrir quando uma alterao que voc fez
gerou algum problema.
Estude gadgets existentes

Um dos melhores recursos disponveis para voc, como desenvolvedor de gadget, so os gadgets
existentes. Visite o diretrio de contedo e estude o cdigo 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 no 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 suposies

Confirmar suas suposies durante o processo de desenvolvimento pode economizar muito tempo e
evitar o desperdcio de esforos. Voc tem certeza de que sua varivel tem o valor que voc supe?
Voc tem certeza de que a matriz contm elementos? Talvez a funo que "no parece estar
funcionando" na verdade no esteja sendo chamada? Teste suas suposies imprimindo as
mensagens de status em pontos diferentes do programa. Por exemplo, o gadget abaixo tem uma
funo print() que grava mensagens de depurao em debug_div caso o sinalizador debug
tenha um valor diferente de zero:
<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="Gray" />
</UserPref>
<![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>
// Get userprefs
// 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>
Observao: Consulte MiniMessages para obter uma descrio da API de MiniMessages, que
permite modificar o comportamento e a aparncia das mensagens exibidas em um gadget.
Ferramentas adicionais
As funes adicionais do Firefox descritas abaixo podem ajud-lo a obter uma viso mais detalhada
dos seus gadgets durante o desenvolvimento:
O Firebug fornece ferramentas de depurao e inspeo de DOM.
O Web Developer adiciona um menu e uma barra de ferramentas ao navegador, contendo
ferramentas de desenvolvedor da web.
Hospedagem atravs do Google Gadgets Editor

Caso no 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, faa login em uma conta do Google (ou voc no 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 especificao do gadget com um novo nome,
o GGE hospedar o novo gadget para voc com o nome especificado:
Observao: O GGE ainda no suporta a totalmente API de gadgets.*. Portanto, alguns dos
recursos ainda no esto ativados. Voc pode usar o GGE para editar e hospedar arquivos, mas no
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, necessrio fazer login para poder usar a maioria desses comandos.
Comando Descrio
Open (Abrir) Abre um gadget criado anteriormente e salvo atravs do GGE.
Salva a especificao do gadget que est sendo editado. Se voc ainda no 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 pblico 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. Disponvel 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 especificaes de gadget, arquivos
Upload
de imagem, etc. Depois que os recursos so enviados, o GGE os hospeda. Isso
(Enviar)
possibilita que voc importe-os para a especificao do seu gadget, inserindo links
de referncia aos URLs do GGE.
Publish O item de menu Publish (Publicar) oferece as opes abaixo para a publicao do
(Publicar) seu gadget:
Add to my iGoogle page (Adicionar minha pgina do iGoogle)

Publish to iGoogle Directory (Publicar no diretrio do iGoogle)
Add to a webpage (Adicionar a uma pgina da web)
O comando fica disponvel somente depois que o gadget salvo (salvar faz o GGE
hospedar seu gadget). Para obter mais informaes, consulte Publicao 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.
Publicao do seu gadget com o GGE

O comando Publish (Publicar) do menu File (Arquivo) oferece as opes abaixo para a publicao
do seu gadget:
Add to my iGoogle page (Adicionar minha pgina do iGoogle) - Adiciona o gadget
sua pgina do iGoogle. Esta a maneira mais simples de testar seu gadget durante o
desenvolvimento.
Publish to iGoogle Directory (Publicar no diretrio do iGoogle) - Leva voc at a pgina
de envio do iGoogle, inserindo automaticamente o URL do seu gadget no formulrio. Voc
pode usar o formulrio para enviar seu gadget ao diretrio de contedo do iGoogle. Seu
gadget no 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 no precisa realizar essa
etapa para usar seu gadget e compartilh-lo com seus amigos. Esta opo para
desenvolvedores que desejam disponibilizar seus gadgets para um pblico de massa.
Add to a webpage (Adicionar a uma pgina da web) - Leva voc at a pgina do criador
da distribuio. A distribuio ainda no 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 pgina do iGoogle e
em outras pginas da web. Depois de testar e ajustar seu gadget, voc pode optar por envi-lo ao
diretrio de contedo do iGoogle, onde ser distribudo para um pblico maior.
Hospedagem no Google Code

A maneira mais fcil de hospedar especificaes e recursos de gadget atravs 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 servio gratuito que oferece muitas vantagens ao desenvolvedor de gadgets. Uma das principais
vantagens o controle de verses atravs do Subversion, que um sistema de controle de verses
de cdigo aberto. Com o Subversion, voc pode rastrear alteraes e manter verses diferentes do
seu gadget. O histrico completo das revises fica disponvel, permitindo que voc retorne a uma
verso anterior ou analise as diferenas entre as verses. Para saber mais sobre o Subversion,
consulte o Livro do Subversion.
Para hospedar seus gadgets no Google Code, primeiro necessrio instalar um programa de rea de
trabalho (o "cliente do Subversion") que permite enviar e salvar arquivos no code.google.com
("repositrio do Subversion"). A maioria dos clientes do Subversion contm uma interface grfica
de usurio, que torna a interao com o Subversion mais fcil do que a interface de linha de
comando. Voc pode escolher entre diversos clientes, dependendo do seu sistema operacional.
Procure instalar um que seja compatvel com o seu sistema. Aqui esto alguns clientes
recomendados:
TortoiseSVN um cliente do Subversion para Windows fcil 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 grfica de usurio) para diversas
plataformas. Este cliente suporta os trs 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 mquina, siga as etapas abaixo para comear a usar o
Google Code e hospedar seus projetos.
Criao de um novo projeto

Para criar um novo projeto:
1. V para http://code.google.com/hosting e faa login usando sua conta do Gmail. Crie uma
conta se ainda no 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 minsculas para o seu projeto, por exemplo my-
gadgets. Lembre-se de que o nome do projeto torna-se parte do URL do projeto e
no pode ser alterado depois.
Escreva um resumo e uma descrio.
Selecione uma licena de cdigo aberto. Para saber mais, visite Licena de cdigo
aberto.
Etapa opcional: atribua marcadores para ajudar outros usurios a encontrarem o seu
projeto.
4. Confirme se todos os campos obrigatrios foram preenchidos e clique em Create Project
(Criar projeto).
5. Pronto! Voc ser direcionado Pgina inicial do projeto. Confirme se o URL tem a
seguinte aparncia: http://code.google.com/p/<project-name>/
Agora voc tem um projeto no code.google.com. Um repositrio do Subversion foi criado usando o
nome do seu projeto. Clique na guia Source (Fonte) e clique no link Subversion repository
(Repositrio do Subversion).
O URL deve ter a seguinte aparncia: http://<project-name>.googlecode.com/svn/. Voc deve ver
trs links de diretrios: branches, tags e trunk. Ao enviar arquivos para o seu projeto, eles so
colocados na pasta /trunk. Voc pode salvar o URL http://<project-
name>.googlecode.com/svn/trunk/ em seus favoritos para referncia futura.
Bloqueio de um projeto
Antes de enviar arquivos, voc precisa bloquear o cdigo a partir do repositrio do seu projeto no
Subversion. Para isso, so necessrias trs informaes: o URL do repositrio (use a verso
precedida por https, e no por http), o nome de usurio e a senha. Para encontrar estas
informaes, 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 pgina aberta em um navegador para poder recuperar as informaes apropriadas
conforme necessrio.
Os detalhes do bloqueio atual podem variar dependendo do cliente do Subversion que voc estiver
usando, mas o processo geral o mesmo. As instrues desta seo supem 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 boto direito e selecione SVN Checkout... (Bloqueio no SVN).
3. Digite o URL do repositrio e clique em OK. Nesta etapa, necessrio usar a verso do
URL do repositrio precedida por https. Isso garante acesso de leitura e gravao. A verso
iniciada por http fornece acesso somente para leitura, e voc no poder adicionar ou enviar
arquivos.
4. O TortoiseSVN conecta-se ao servidor e tenta autenticar voc. O nome de usurio e a senha
so solicitados. Digite o nome de usurio e a senha, marque a opo Save authentication
(Salvar autenticao) e clique em OK. Se o nome de usurio e a senha no forem
solicitados, volte Etapa 3 e verifique se o URL do seu repositrio comea com https (e no
com http).
Neste ponto, o cliente conecta e bloqueia todo o repositrio. Pronto!
Se o bloqueio for concludo com sucesso, voc ver uma nova pasta oculta, /.svn. No modifique
nem exclua essa pasta.
Envio de arquivos
Depois de verificar seu projeto, voc pode comear a adicionar novas pastas e arquivos ao diretrio,
usando os comandos do Subversion. As instrues desta seo supem que voc esteja usando o
TortoiseSVN.
Para enviar um arquivo:
1. Crie um novo arquivo no diretrio <project-name>.googlecode.com/svn/trunk/ e salve-o
(por exemplo, new-gadget.xml). Voc pode colocar o arquivo diretamente no diretrio
/trunk ou em um subdiretrio de /trunk.
2. Clique com o boto direito no arquivo e selecione Add... (Adicionar...). Isso simplesmente
marca o arquivo como adicionado. Neste ponto, o arquivo ainda no foi enviado ao servidor.
Se voc colocar o arquivo em um diretrio que ainda no foi adicionado ao repositrio,
tambm ser necessrio adicionar o diretrio. Ao adicionar um diretrio, todos os arquivos
dentro dele so adicionados tambm. As mesmas regras se aplicam para o envio de
alteraes. Voc no poder enviar um arquivo ao repositrio se o diretrio no qual ele est
inserido no 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 boto direito e selecione SVN
Commit... (Enviar para SVN...).
Quando solicitado, escreva uma observao opcional no log de mensagens e clique em OK. A
transferncia do arquivo para o servidor iniciada.
Quando o arquivo transmitido para o servidor, o envio concludo e o arquivo fica disponvel
imediatamente on-line em http://<project-name>.googlecode.com/svn/trunk/new-gadget.xml. Para
apenas ler arquivos no repositrio, basta usar a verso do URL do repositrio que comea com http.
Dentro do seu repositrio, voc pode criar estruturas de diretrio que sero 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.
Criao de uma interface de usurio
Este documento descreve como adicionar os diversos elementos de interface de usurio ao seu
gadget.
Gerenciamento da altura do gadget

Por padro, os gadgets tm 200 pixels de altura. Voc pode usar o atributo <ModulePrefs>
height="nn" para especificar uma altura esttica maior ou menor que a altura padro. Voc pode
usar o atributo <ModulePrefs> scrolling="true" para criar uma barra de rolagem vertical
para o gadget, caso a altura do contedo 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 contrada,
dependendo do contedo da lista. O gadget cresce medida que os usurios adicionam itens lista.
Quando eles limpam a lista, o gadget retorna altura original. Veja aqui a aparncia do gadget
sendo executado:
Para adicionar ao seu gadget o recurso de redimensionamento, adicione os itens abaixo

especificao:
Uma tag <Require feature="dynamic-height"/> (em <ModulePrefs>) para
informar ao gadget que ele precisa carregar a biblioteca dynamic-height.
Uma chamada funo JavaScript gadgets.window.adjustHeight() sempre que
houver uma alterao de contedo ou ocorrer outro evento que exija o redimensionamento
do gadget.
Por exemplo, veja abaixo a especificao do gadget de lista de compras:
<Module>
<ModulePrefs title="Dynamic Height"
height="100">
<Require feature="dynamic-height"/>
</ModulePrefs>
<![CDATA[
// 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>
]]>
</Content>
</Module>
Para obter orientaes sobre como testar a largura e a altura de um gadget, consulte Teste de largura
e altura.
Definio do ttulo do gadget

Use a funo gadgets.window.setTitle() para definir o ttulo do gadget
programaticamente. Para usar esta funo, 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 ttulo do gadget.
Este exemplo fornece um campo de texto que permite que o usurio defina o ttulo do gadget:
<Module>
<ModulePrefs title="Set Title Example">
<Require feature="settitle"/>
</ModulePrefs>
<![CDATA[
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>
]]>
</Content>
</Module>
Guias
Use a biblioteca de guias para adicionar uma interface de usurio com guias ao seu gadget. Para
usar guias, a especificao do seu gadget deve incluir no mnimo:
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 contedo. Para obter mais detalhes,
consulte Como funciona.
Tambm comum incluir a biblioteca setprefs para que o gadget possa armazenar sempre a
ltima guia selecionada pelo usurio. Assim, se o usurio sair e retornar pgina, o gadget carrega a
guia armazenada. Para aproveitar este recurso, incorpore duas linhas de cdigo na especificao do
seu gadget:
<Require feature="setprefs"/>
...
<UserPref name="selectedTab" datatype="hidden"/>
Anatomia de um objeto de guias

A biblioteca de guias fornece funes e CSS para realizar operaes 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 implementao
bsica do HTML um elemento <table>, mencionado na API como o "header
container" (recipiente de cabealho). Use a funo
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 implementao bsica do HTML um elemento <td>,
mencionado na API como o "name container" (recipiente de nome). Use a funo
gadgets.Tab.getNameContainer() para acessar este HTML.
Recipiente de contedo. Um objeto de recipiente de contedo contm o contedo de um
objeto de guia individual. Normalmente, a implementao bsica do HTML um elemento
<div>, mencionado na API como o "content container" (recipiente de contedo). Use a
funo 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 funo addTab().
Uma guia individual apresenta trs componentes principais: um ndice, um nome e um ID exclusivo
que igual ao ID de um <div> correspondente. O <div> o local onde o contedo da guia
colocado. Se voc no fornecer o recipiente de <div>, a biblioteca de guias ir ger-lo.
O mtodo addTab() utiliza os seguintes argumentos:
String tabName -- Marcador da guia a ser criada.
Object opt_params -- Objeto de parmetro opcional. Ele pode incluir:
contentContainer --Um elemento HTML existente para ser usado como
recipiente do contedo da guia. Se omitido, a biblioteca de guias cria um elemento.
callback --funo mA callback a ser executada quando a guia selecionada.
tooltip-- Uma descrio de dica de ferramenta que aparece quando o usurio
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 contedo usando uma das
maneiras descritas abaixo:
Tcnica 1: Capture o ID da guia ao cri-la e use o ID para adicionar contedo ao <div>
correspondente da guia:
var one_Id = tabs.addTab("One");
document.getElementById(one_Id).innerHTML = "Content for tab One.";
Uma variao 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>');
Tcnica 2: Crie a guia e adicione um <div> correspondente parte HTML do gadget; coloque o
contedo esttico no <div>:
tabs.addTab("Two", "two_id");
...
</script>
<div id="two_id" style="display:none">Content for tab Two.</div>
Tcnica 3: Crie a guia e adicione um <div> correspondente parte HTML do gadget; coloque o
contedo esttico no <div>: Use uma funo de retorno de chamada para adicionar contedo
dinmico ao contedo esttico:
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>
Tcnica 4: Use a funo 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 contedo:
<Module>
<ModulePrefs title="Tabs Demo" height="140" scrolling="true" >
<Require feature="tabs" />
</ModulePrefs>
<![CDATA[
// 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>');
// 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>
Manipulao de guias por ndice

A API de guias tambm inclui funes que permitem a manipulao das guias por ndice. As guias
so indexadas de 0 a n, onde 0 a primeira guia. Por exemplo, se houver 3 guias, os ndices so 0, 1
e 2. Voc pode usar os ndices para selecionar uma guia programaticamente e para trocar a posio
de duas guias.
Embora o ID de uma guia permanea constante, o mesmo no ocorre com seu ndice. Por exemplo,
se voc mover a terceira guia para a primeira posio, o ndice alterado de 2 para 0.
Aqui est um exemplo de como selecionar uma guia programaticamente. Este snippet cria um link.
Quando o usurio clica no link, a segunda guia selecionada, como se o usurio tivesse clicado na
prpria 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 usurio clica no link, o gadget troca as posies da primeira e da segunda guia:
<script>
...
function switchTabs() {
tabs.swapTabs(0, 1);
}
</script>
<a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>
Personalizao da exibio de guias

Esta seo descreve como voc pode personalizar a aparncia de suas guias usando CSS ou
JavaScript.
Personalizao de guias com CSS

A folha de estilo das guias est disponvel 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 configurao padro e modificar a aparncia
das suas guias.
Classe CSS Descrio
.tablib_table Aplicvel tabela HTML que contm as guias.
.tablib_selected Aplicvel guia selecionada.
.tablib_unselected Aplicvel a todas as guias no selecionadas.
.tablib_spacerTab Aplicvel aos elementos de espaamento entre cada guia.
.tablib_emptyTab Controla os espaamentos de incio e de fim em volta das guias.
.
Aplicvel ao recipiente-pai, que contm todo o contedo relacionado s guias
tablib_main_cont
(ou seja, cabealhos de guia e todos os recipientes individuais de contedo).
ainer
.
tablib_content_co Aplicvel a todos os recipientes de contedo da guia.
ntainer
Para obter uma lista com as classes e as configuraes 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 tambm pode usar JavaScript para aplicar estilos CSS ao recipiente de cabealho das guias. A
funo 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 cabealhos de guias individuais, obtendo os elementos da guia
individual e modificando suas propriedades. Veja um exemplo que torna o estilo da primeira guia
exclusivo:
tabs.addTab("Unique");
...
var firstTab = tabs.getTabs()[0].getNameContainer();
firstTab.style.backgroundColor = "#999999";
firstTab.style.color = "#ffffff";
Alterao de alinhamento da guia

Por padro, as guias so centralizadas ao serem adicionadas. Entretanto, se houver menos que 3 ou
4 guias, voc pode alinh-las esquerda ou direita. Para isso, use a funo alignTabs(). Ela
aceita um parmetro com o valor left, right ou center. Se voc for alinhar guias esquerda
ou direita, h um parmetro opcional que pode ser passado para indicar a largura do deslocamento
em relao ao lado esquerdo ou direito. O tamanho padro 3px.
Por exemplo:
...
// Align tabs to the left and offset it by 10 pixels
tabs.alignTabs("left", 10);
Como ocultar guias

Use a funo displayTabs() para alternar a exibio das guias e de seu contedo. Esta funo
assume o valor booleano de true ou false.
Aqui est um exemplo que cria um boto que exibe ou oculta as guias:
<input onclick="toggleTabs()" type="button" value="Show/Hide"/>
<script>
...
var showTabs = true;
function toggleTabs() {
showTabs = !showTabs;
tabs.displayTabs(showTabs);
}
</script>
MiniMessages
Uma MiniMessage uma mensagem temporria exibida aos usurios dentro de um gadget. As
MiniMessages foram criadas para serem eliminadas programaticamente ou pelo usurio. Os tipos
bsicos de MiniMessages so:
Mensagens dispensveis que os usurios removem clicando em um [x].
Mensagens de temporizador que desaparecem depois de decorrido um determinado perodo
de tempo em segundos.
Mensagens estticas que devem ser dispensadas programaticamente.
Para usar MiniMessages, a especificao do seu gadget deve incluir:
Em <ModulePrefs>, uma tag <Require feature="minimessage"/> para
informar ao gadget que ele precisa carregar a biblioteca de MiniMessages.
Funes JavaScript descrevendo o comportamento da MiniMessage. Consulte a Referncia
para obter uma lista completa das funes da biblioteca de MiniMessages.
Veja alguns dos motivos para usar MiniMessages:
Promoo: Voc pode usar as MiniMessages para exibir uma mensagem promocional no
gadget.
Status: Muitos gadgets obtm e carregam dados em segundo plano. Voc pode usar
MiniMessages para exibir "Carregando..." ou outras mensagens relacionadas a status.
Depurao/erro: Se um gadget encontrar um erro, ele pode usar as MiniMessages para
notificar o usurio, em vez de falhar em silncio.
Outros: Dependendo do tipo de gadget (por exemplo, calendrio, eBay), voc pode exibir
notificaes para os usurios. Como as MiniMessages so pequenas e dispensveis, use-as
para comunicar informaes especiais.
Como funciona
As etapas bsicas da adio de uma MiniMessage ao gadget so simples:
1. Importe a biblioteca de MiniMessages:
<Require feature="minimessage"/>
2. Crie uma instncia 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 incio do gadget uma mensagem pr-formatada dispensvel com um [x] associado
a ela. Quando os usurios clicam no [x], a mensagem fechada.
Pronto! Voc criou um dos diversos tipos de mensagens dispensveis.
Criao de mensagens em locais diferentes

Por padro, as mensagens so colocadas dentro de um elemento de recipiente de HTML bem no
incio do gadget. Cada mensagem subseqente anexada como filha ao recipiente, em ordem
decrescente. Entretanto, voc pode modificar esse comportamento para todas as mensagens ou para
uma nica mensagem.
Definio de um local para todas as mensagens

Voc pode passar um elemento HTML ao construtor, de preferncia um <div>, para ignorar a
localizao padro do elemento de recipiente da mensagem. Esse elemento torna-se o recipiente no
qual as mensagens sero inseridas e exibidas.
Por exemplo, neste snippet, a mensagem <h3> "I'm on top now!" aparece no incio do gadget. As
MiniMessages so 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>
// 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>
Definio de um local para uma nica mensagem

Voc pode criar uma mensagem dispensvel em uma localizao designada em vez de anex-la ao
recipiente da mensagem. Para isso, faa o markup da mensagem dentro da parte HTML do gadget.
Em seguida, passe o elemento HTML (de preferncia um <div>) como o primeiro parmetro 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>
// Pass the HTML element to createDismissableMessage() to indicate
// where the message should be displayed.
msg.createDismissibleMessage(document.getElementById("status"));
</script>
Criao de mensagens usando mtodos DOM

Pode haver casos em que voc ir gerar a mensagem dispensvel usando mtodos HTML DOM.
Como a mensagem no existe no DOM, ela anexada ao recipiente de mensagens por padro.
Por exemplo:
// 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>
Criao de uma mensagem de temporizador
Uma mensagem de temporizador pr-formatada para desaparecer depois de decorrido o perodo
de tempo especificado. A funo createTimerMessage() aceita dois parmetros: uma string
de mensagem e um nmero indicando a durao, em segundos, da exibio da mensagem. Por
exemplo:
msg.createTimerMessage("I'm going to disappear in 5 seconds.", 5);
Criao de uma mensagem esttica

Uma mensagem esttica pr-formatada para ser exibida at ser dispensada programaticamente
pela funo dismissMessage(). Isso til para exibir mensagens de notificao que
mantenham o usurio informado durante a execuo de tarefas do gadget em segundo plano, como a
obteno de contedo. Por exemplo:
var loadMessage = msg.createStaticMessage(document.getElementById("loading"));
Personalizao da exibio de MiniMessages

H duas maneiras de se alterar a aparncia padro de MiniMessages:
Altere a aparncia das mensagens individuais.
Altere a aparncia de todas as mensagens de forma global.
Alterao do estilo de mensagens individuais

Use funes DOM para alterar o estilo de uma mensagem. Um elemento HTML retornado quando
voc cria uma nova mensagem dispensvel. Voc pode modificar a aparncia da mensagem
configurando as propriedades de estilo desse elemento HTML retornado. Por exemplo:
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>
Observao: Este exemplo mostra a forma correta de alterar totalmente a cor de fundo de uma
mensagem. A cor de fundo no ser totalmente alterada se apenas a configurao da cor de fundo do
<div> que contm a mensagem for alterada.
Alterao do estilo de todas as mensagens

Use CSS globalmente para alterar o estilo de todas as mensagens. A folha de estilo das
MiniMessages est disponvel 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 configurao padro e modificar a aparncia
de suas mensagens.
Classe CSS Descrio
.mmlib_table Aplicvel tabela HTML que contm a mensagem.
.mmlib_xlink Aplicvel ao link [x] usado para dispensar uma mensagem. A
configurao se aplica somente mensagem dispensvel.
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 contedo Flash, a especificao do seu gadget deve incluir no mnimo:
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 funes:
Funo Descrio
Incorpora o arquivo .swf especificado por swf_url e o
exibe no gadget no local especificado por swf_container.
O parmetro opt_params um objeto opcional que pode
conter qualquer parmetro html vlido.
gadgets.flash.embedFlas Rretorna true se for bem-sucedido, ou false se falhar.

h(swf_url,
swf_container, Observao: Se ocorrerem problemas de desempenho ou se o
swfVersion, opt_params) gadget no 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,
parmetros e o valor retornado so os mesmos do mtodo
swf_container,
embedFlash().
swfVersion, opt_params)
gadgets.flash.getMajorV Retorna a principal verso do Flash Player, ou zero se o Flash
ersion() Player no for detectado.
Exemplo de Flash
Quando voc clica em algum boto deste exemplo de gadget, ele reproduz o arquivo .swf
correspondente. Quando voc clica em Stop, o gadget exibe uma fotografia esttica.
Aqui est a especificao do gadget do exemplo:
<Module>
<ModulePrefs title="Trevor Does Tricks" height="300">
<Require feature="flash" />
</ModulePrefs>
<![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>
// 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 contedo remoto
Este documento descreve como obter e manipular dados remotos textuais (normalmente HTML),
XML, JSON e de feeds RSS/Atom.
Introduo
A capacidade de combinar informaes de diversas fontes de maneiras novas ou de fornecer meios
alternativos de interao com informaes existentes um dos recursos mais empolgantes
disponveis para os gadgets. A API de gadgets permite que o gadget obtenha remotamente contedo
de outros servidores e pginas da web e realize operaes com esse contedo.
A API de gadgets fornece a funo makeRequest(url, callback, opt_params) para
recuperao e operao com contedo da web remoto. Ela aceita os seguintes argumentos:
String url - O URL no qual o contedo est localizado
Function callback - A funo a ser chamada com os dados do URL aps a obteno
Map.<gadgets.io.RequestParameters, Object> opt_params - Parmetros
adicionais a serem passados para a solicitao
O argumento opt_params permite especificar:
O tipo de contedo da solicitao (atualmente suportados: TEXT, XML e JSON)
O tipo de mtodo da solicitao (POST ou GET)
Qualquer cabealho que voc deseje incluir na solicitao
O tipo de autorizao (suportado atualmente: NONE ou SIGNED)
Para ler mais sobre os parmetros opcionais que podem ser passados, consulte o artigo Introduo
funo makeRequest.
Observao: Voc no pode usar makeRequest() com gadgets type="url".
Independentemente do tipo de dados sendo obtidos, as chamadas a makeRequest()
compartilham as mesmas caractersticas:
Seu primeiro parmetro um URL usado para obter o contedo remoto.
Seu segundo parmetro uma funo de retorno de chamada, usada para processar os dados
retornados.
Elas so assncronas, ou seja, todo o processamento deve ocorrer dentro da funo de
retorno de chamada. Um retorno de chamada uma funo passada como parmetro (na
forma de uma referncia de funo) a outra funo. Os retornos de chamada fornecem aos
desenvolvedores um "gancho" que pode ser conectado a uma estrutura em execuo para
realizar processamentos.
Eles no tm valores de retorno porque so retornados imediatamente, e as funes de
retorno de chamada a eles associadas so chamadas sempre que a resposta retornada.
Por exemplo, pense no seguinte snippet de cdigo, que obtm contedo remoto em forma de texto.
Este cdigo obtm o texto HTML da pgina 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);
};
gadgets.util.registerOnLoadHandler(getHtml);
Este exemplo ilustra os princpios bsicos por trs do funcionamento da funo makeRequest():
1. Quando a funo makeRequest() chamada, a API de gadgets faz uma solicitao
HTTP GET assncrona ao URL passado funo (neste exemplo, o URL
http://www.google.com).
2. makeRequest() retornada imediatamente e chama a funo de retorno de chamada
posteriormente (neste exemplo, denominada response()), quando todo o contedo
obtido. Isso significa que voc deve colocar todos os cdigos dependentes dentro da funo
de retorno de chamada ou dentro de funes chamadas pela funo 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 funo de retorno de chamada. A funo
de retorno de chamada executa algumas operaes 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 contedo diferentes

Como padro, o contedo de um site remoto retornado como texto. Voc pode usar o campo
opt_params para definir o contedo 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 obtm dados de um arquivo CSV (valores separados por vrgulas) e os
utiliza para preencher uma lista de contatos pessoais. Ele mostra como definir o tipo do contedo
obtido nos parmetros opcionais. Na funo response(obj) de retorno de chamada, o valor do
texto extrado de obj usando obj.text:
<Module>
<ModulePrefs title="Fetch Text Example"/>
<![CDATA[
// 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 = {};
var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-
gadgets/Contacts.csv";
};
// Callback function to process the response
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.
}
gadgets.util.registerOnLoadHandler(getContacts);
</script>
]]>
</Content>
</Module>
Uso de XML
O DOM (Document Object Model, Modelo de objeto de documento) uma API para navegao 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 funes DOM JavaScript
padro. 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 contedo da web analisado em uma rvore de ns. 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 ns discutidos nesta seo:

Ns de elemento. Os ns de elemento deste snippet so a e b. Os ns de elemento so os
blocos que definem a estrutura de um documento.
Ns de texto. Os ns de texto deste trecho so Googles, fast e home page. Os ns de
texto so sempre inseridos em ns de elemento. Eles so os ns-filho do n de elemento em
que esto inseridos.
Ns de atributo. Este snippet apresenta um n de atributo: href=http://www.google.com.
Um n de atributo fornece informaes adicionais sobre o n de elemento em que est
inserido. Entretanto, os atributos no so considerados ns-filho dos elementos em que esto
inseridos, o que afeta o modo como voc trabalha com eles. Para ler mais sobre este tpico,
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 funes DOM para
navegar pelos relacionamentos de n pai-filho e chegar aos dados necessrios.
Exemplo
O arquivo XML abaixo contm dados para uma srie de itens de caf da manh. O primeiro n-pai
menu, que possui diversos ns-filho food. O n menu tambm contm um n de atributo:
title="Breakfast Menu". Cada n food possui os ns-filho name, price, description e calories.
Os ns name, price e calories contm seus prprios ns-filho de texto. Cada n description contm
um n-filho CDATA. CDATA um tipo distinto de n. As sees CDATA so usadas para adicionar
cdigos 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 seo CDATA
a string "]]>", que finaliza a seo CDATA.
<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 usurios definam um limite de calorias. Ele exibe qualquer caloria
acima do limite especificado em vermelho. Os usurios tambm podem selecionar se desejam exibir
as descries de cada item do caf da manh.
O cdigo 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.
<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"/>
<![CDATA[
// get 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 = {};
gadgets.io.ContentType.DOM;
var url = "http://gadget-doc-
examples.googlecode.com/svn/trunk/opensocial-gadgets/breakfast-data.xml";
};
// 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>";
};
gadgets.util.registerOnLoadHandler(makeDOMRequest);
</script>
]]>
</Content>
</Module>
Esta amostra de cdigo ilustra quatro das principais funes usadas para interagir com dados DOM:
getElementsByTagName(tagname)-- Para um documento DOM, retorna uma matriz dos ns
de elemento cujos nomes correspondem a tagname. Voc pode recuperar todos os ns 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 funes para a navegao em uma rvore
DOM. Experimente algumas das outras funes 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 diferenas sutis entre
diferentes tipos de n.
Tipo de Valores
Descrio 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, necessrio ir
de menor e para esses ns. 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
espaos em branco de um documento como
nodeName: ns de texto. Assim, seu objeto DOM ir
#text conter ns 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 ns de texto que
elemento. nodeValue: contm somente o caractere de nova linha.
Qualquer texto Ou voc pode realizar uma manipulao
inserido no n. mais robusta. Para ler mais sobre este
tpico, consulte Espaos em branco no
DOM.
nodeName: O
valor esquerda
do par de
atributo. Se o Embora os atributos sejam ns e estejam
atributo for inseridos em ns de elemento, eles no so
Um par de chave-valor que title=my ns-filho do elemento. Eles so herdados
fornece informaes document, da interface de Node, mas o DOM no 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 funes de n com os ns de
atributo inserido em um nodeType: 2 atributo (como nodeName, nodeValue e
n de elemento, mas no nodeType), no possvel acessar ns de
filho do n de elemento. nodeValue: O atributo usando as funes de navegao da
valor direita do rvore DOM. Para acessar os atributos, use
par de atributo as funes attributes e getAttribute(attrib).
(neste exemplo,
my
document).
Uma seo na qual o
contedo no
manipulado ou
nodeName:
interpretado. As sees
#cdata-section
CDATA so usadas para
adicionar cdigos de
nodeType: 4
escape a blocos de texto O texto da seo CDATA tem seu prprio
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 seo
CDATA.
CDATA a string "]]>",
que finaliza a seo
CDATA.
Outros recursos
Ncleo DOM W3C
Tutorial do DOM JavaScript
Uso de feeds
Adicione um feed sua pgina do iGoogle digitando seu URL no formulrio Add by URL
(Adicionar por URL) do diretrio de contedo. Esse formulrio utiliza o suporte integrado da API
de gadgets para criar um gadget para o feed e adicion-lo ao iGoogle. fcil de usar, mas no
permite qualquer personalizao do contedo ou da exibio. Alm disso, voc no pode us-lo com
outros recipientes.
Para manipular feeds de maneira mais sofisticada, use o mtodo makeRequest(). Embora a
especificao dos gadgets para makeRequest() inclua um tipo de contedo FEED, este recurso
ainda no suportado por nenhum recipiente. Como alternativa, voc pode processar um feed
usando o tipo de contedo DOM, como mostrado abaixo.
O exemplo a seguir ilustra como usar a funo makeRequest() para obter um feed e exibir
partes de seus dados em um gadget. Aqui est o gadget. Ele permite que os usurios especifiquem:
O nmero de entradas exibidas
Se o gadget exibir a data e um resumo de cada entrada
Este o cdigo do exemplo:

<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"
<UserPref name="show_summ" display_name="Show Summaries?" datatype="bool"
<UserPref name="num_entries" display_name="Number of Entries:"
default_value="5"/>
<![CDATA[
<style> #content_div { font-size: 80%; margin: 5px; background-color:
#FFFFBF;} </style>
// Get userprefs
var showdate = prefs.getBool("show_date");
var summary = prefs.getBool("show_summ");
var entries = prefs.getInt("num_entries");
function makeDOMRequest() {
var params = {};
gadgets.io.ContentType.DOM;
var url = "http://groups.google.com/group/Google-Gadgets-
API/feed/rss_v2_0_msgs.xml";
};
// 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";
}
};
// 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 contedo JSON para obter contedo com codificao JSON em forma de objeto
JavaScript.
O aplicativo descrito abaixo obtm o contedo de uma pgina PHP de amostra que contm a
seguinte string em codificao JSON:
{"validated":"This request was spoofed","query":
[],"url":"http:\/\/graargh.returnstrue.com\/buh\/fetchme.php","signature":"","si
gnature_len":1}
Ao obter contedo da pgina 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:
<Module>
<ModulePrefs title="Fetch JSON 8">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<![CDATA[
function makeJSONRequest() {
var params = {};
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";
};
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 />";
}
};
makeJSONRequest();
</script>
]]>
</Content>
</Module>
Atualizao do cache
Se estiver usando a funo makeRequest() para obter contedo atualizado mais de uma vez por
hora, como dados de feeds, pode ser que voc no obtenha as ltimas atualizaes. Isso ocorre
porque seus resultados so armazenados em cache para tornar a execuo do gadget mais rpida. Se
voc quiser ter certeza de que o gadget obteve os dados mais recentes, use o parmetro
refreshInterval para ignorar o cache e forar uma atualizao no intervalo que voc
especificar. Em outras palavras, o cache atualizado a cada X segundos, onde X =
refreshInterval.
Como padro, as chamadas funo makeRequest so armazenadas em cache. No exemplo
abaixo, a funo wrapper usa os mesmos parmetros da chamada funo makeRequest, mas
aceita outro parmetro denominado refreshInterval, que permite especificar a durao 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("");
}
O uso de cache tem uma finalidade especfica. Tome cuidado para no atualizar o cache com muita
freqncia, para no prejudicar o desempenho. O uso de cache agiliza a obteno de dados. Ele
tambm reduz a carga sobre os servidores de terceiros que hospedam o contedo remoto. Evite
desativar o cache completamente (o que feito usando-se o valor refreshInterval: 0). Se o
gadget estiver recebendo milhes de visualizaes de pgina por dia e enviando milhes de
solicitaes a estes servidores, desativar o cache no apenas afetar negativamente o desempenho
do gadget de maneira negativa, mas tambm poder sobrecarregar os servidores que fornecem
dados ao seu gadget.
Como o padro atualizar o contedo 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 internacionalizao (i18n)
Este documento descreve como criar gadgets que possam ser facilmente localizados para um
pblico internacional.
Introduo
A API de gadgets oferece uma maneira fcil de voc disponibilizar seu gadget para um pblico
internacional. simples: basta estruturar o gadget de forma que o texto visvel para o usurio
(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
especficos ao local, os quais voc pode adicionar especificao do seu gadget. Dessa forma, seu
gadget fica disponvel para um novo grupo de usurios.
Para ler mais sobre como criar gadgets em idiomas diferentes do ingls, consulte Gadgets em
idiomas diferentes do ingls.
Conceitos bsicos
Este documento refere-se internacionalizao (i18n) e localizao (l10n):
Internacionalizar significa estruturar aplicativos de forma a possibilitar sua localizao.
Localizar significa fazer um aplicativo funcionar para um mercado especfico, como
canadenses francfonos.
Para a finalidade deste documento, o perfil de localizao de um usurio consiste em dois
componentes: um pas (com base no domnio do usurio) e um idioma de interface preferido pelo
usurio (consulte a seo Teste para obter mais detalhes).
Codificao para a internacionalizao

A API de gadgets suporta codificao UTF-8 para valores de atributos XML e tambm na seo
<Content>. Quando o tipo de contedo definido como html, a codificao padro definida
expressamente como UTF-8. Voc no deve tentar defini-la sozinho.
Exemplo
O exemplo de gadget usado neste documento exibe a mensagem Hello World, mostrada aqui em
chins:
Neste exemplo, o menu suspenso de preferncias do usurio permite que o usurio especifique uma
cor de fonte para a mensagem Hello World. Os nomes das cores que aparecem no menu so
arquivos externos definidos (pacotes de mensagens). O idioma no qual o menu ser exibido
depende do perfil de pas/idioma do usurio. Se um usurio com perfil ingls executar este gadget, o
texto aparecer em ingls. Veja aqui a aparncia da verso em ingls do exemplo, com o menu
suspenso userprefs sendo exibido:
Voc pode ver a especificao do gadget Hello World aqui.
Criao de um gadget localizado

As etapas bsicas para a criao de um gadget localizado so:
1. Criar o gadget.
2. Extrair todo o texto que precisa de traduo e coloc-lo em pacotes de mensagens.
3. Encontrar algum que possa ajud-lo a traduzir o gadget.
4. O tradutor cria um novo pacote de mensagens para um local especfico. Esse local pode ser
definido por idioma (francs) ou por idioma/pas (francs/Canad, francs/Frana). Os
pacotes de mensagens em idiomas diferentes do ingls devem ser salvos no formato UTF-8.
5. O tradutor envia um URL do novo pacote a voc.
6. Modifique a especificao do gadget para usar o pacote de mensagens.
7. Se o gadget estiver no diretrio de contedo, aguarde de 1 a 2 semanas para que o indexador
e as informaes possam encontrar seu gadget atualizado e voc possa ento disponibiliz-lo
no novo mercado.
Pacotes de mensagens
O elemento principal da estratgia de internacionalizao de gadgets so os pacotes de mensagens.
Os pacotes de mensagens so arquivos XML que contm 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 contm somente um local.
Os pacotes de mensagens tm 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 traduo.
msg: Um nico item de contedo traduzvel, normalmente um marcador, frase ou pargrafo.
msg name: Um ID legvel para cada mensagem.
Convenes de nomenclatura
A conveno nomear os pacotes de mensagens como descrito abaixo:
<language>_<country>.xml
Onde no houver um valor especfico ao idioma ou ao pas, a conveno usar "ALL". Por
exemplo, o arquivo de_ALL.xml aplica-se a todas as pessoas que falam alemo,
independentemente de seu pas. O pacote de mensagens ALL_ALL.xml o arquivo usado como
padro.
Melhores prticas
No h requisitos rgidos a serem seguidos nas convenes 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 usurio. Ele no usa o nome do pacote de
mensagens em si.
Entretanto, embora a API de gadgets oferea muita flexibilidade, recomendamos que voc siga estas
orientaes:
Sempre fornea um pacote de mensagens ALL_ALL.xml ao lidar com mensagens padro.
Especifique um local por idioma. Ou seja, use fr_ALL, de_ALL e assim por diante.
Se precisar ignorar locais especficos, use pacotes de mensagens idioma-pas. Por exemplo,
se quiser fornecer um pacote de mensagens em ingls canadense para ignorar en_ALL, use
en_CA e no ALL_CA.
Uso de pacotes de mensagens em um gadget

Use a tag <Locale> (aninhada dentro da seo <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 atravs de um URL.
lang: O idioma para o qual as strings do pacote de mensagens foram traduzidas.
country: No h exemplos desse atributo na especificao do gadget Hello World, mas
voc tambm pode especificar um atributo de pas. Por exemplo, este pacote de mensagens
configurado para usurios canadenses francfonos:
<Locale lang="fr" country="CA" messages="http://example.com/fr_CA.xml"/>
Durante a execuo, o gadget usa o pacote de mensagens que melhor corresponda ao perfil do
usurio.
Os valores vlidos para o idioma so cdigos de idioma ISO639-1 com dois dgitos e os valores
vlidos para o pas so cdigos 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 pas do usurio e
ao idioma de preferncia da IU (especificado no URL). Se o gadget no encontrar uma
correspondncia exata, ele "consulta" todos os pacotes de mensagens para encontrar a
correspondncia mais prxima.
Com a consulta s mensagens, voc pode usar mensagens "padro" (normalmente especificadas em
ALL_ALL.xml), caso no haja um pacote disponvel para um determinado local.
Por exemplo, imagine que o seu gadget contm a seguinte especificao:
<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 domnio da sua usuria nos EUA
(http://www.google.com), mas o idioma de preferncia o alemo. Ela ver as mensagens do
arquivo de_US.xml. Se no houver uma mensagem especfica neste arquivo, ela ver a mensagem
de de_ALL.xml, e finalmente, de ALL_ALL.xml.
Um usurio da Alemanha usando a IU em alemo comear por de_DE.xml, um usurio da Sua
usando a IU em alemo comear por de_ALL.xml e um usurio da Sua usando a IU em francs
comear 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 alemo, pas 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">Grn</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 alemo para vermelho. Aqui est a string da mensagem
equivalente em ingls no pacote de mensagens ALL_ALL.xml:
<msg name="red">Red</msg>
A especificao do gadget Hello World usa a varivel de substituio __MSG_ para indicar onde
o valor do pacote de mensagens apropriado deve ser substitudo. Por exemplo, esta sentena XML
da especificao 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
pas/idioma do usurio, obtenha o valor da mensagem com nome red e use-o no lugar de
__MSG_red__. assim que as preferncias do usurio do menu suspenso do exemplo Hello
World so preenchidas com nomes de cores (aqui, mostrado em alemo):
Exibio de mensagens no HTML do gadget

Para exibir as mensagens na parte XML do seu gadget, use as variveis de substituio conforme
discutido acima. H algumas opes diferentes dentro da parte CDATA do gadget.
A tcnica mais simples incorporar a varivel de substituio no HTML:
<b>__MSG_hello_world__</b>.
Como alternativa, use a funo getMsg() de userprefs. Essa funo pode ser usada para acessar
todas as mensagens dos pacotes de mensagens e no apenas as mensagens relacionadas a userprefs.
Entretanto, necessrio chamar esta funo para um objeto Prefs. Por exemplo:
prefs.getMsg(red);
Especificao do gadget Hello World

Aqui est a especificao do gadget do exemplo "Hello World":
<Module>
<ModulePrefs title="i18n Example">
<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>
<![CDATA[
// Display message in the user's preferred language
function displayMsg(){
var div = document.getElementById('content_div');
// Get userprefs
// 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>
Criao de gadgets bidirecionais

Use a API BIDI (bidirecional) para alterar dinamicamente a direo de um gadget. "Direo"
refere-se direo na qual o contedo exibido: esquerda para a direita ou direita para a esquerda.
Isso diferente de alinhamento. Por exemplo, voc pode criar um gadget com texto em ingls
alinhado direita, mas a direo 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 ingls). 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 direo do gadget. Como padro, a direo dos gadgets da esquerda para a direita.
Um conjunto de variveis de substituio __BIDI_... cujos valores so alterados
dependendo da direo do gadget. Por exemplo, a varivel __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 direo de um gadget. Por exemplo, este gadget exibe somente texto em hebraico.
Portanto, sua direo sempre da direita para a esquerda:
<Module>
<ModulePrefs title=" two-"
height="100">
<Locale lang="ALL" language_direction="rtl" />
</ModulePrefs>

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 direo dinamicamente, de acordo com o pacote de mensagens
que carregado para o local de um usurio. Este gadget possui pacotes de mensagens para dois
idiomas da direita para a esquerda, hebraico (iw) e rabe (ar):
<Module>
<ModulePrefs title="BIDI Hello World">
<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>
<![CDATA[
<div style="margin-__BIDI_START_EDGE__:30px;"><h2>__MSG_hello_world__</h2></
div>
]]>
</Content>
</Module>
Para este gadget, suponha que o idioma de preferncia do usurio 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 direo do gadget como rtl." A direo para o hebraico tambm ser da
direita para a esquerda. Para outros idiomas, a direo do implicitamente definida com o padro
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 relao margem esquerda. Quando
o gadget estiver em modo da direita para a esquerda, deslocar o texto 30 pixels em relao
margem direita". Por exemplo, se a configurao do navegador do usurio for rabe (direita para a
esquerda), a substituio realizada na execuo ficar assim:
<div style="margin-right:30px;"><h2> x
</h2></div>
Esta tabela lista as variveis de substituio BIDI e seus possveis valores. Seus valores sempre so
baseados na direo do prprio gadget. Ou seja, estas variveis so designadas para serem usadas
em conjunto com a configurao de <Locale... language_direction="...">. Voc
pode usas as variveis em qualquer parte dentro do corpo do gadget.
Varivel Descrio
Esta varivel representa o lado
do gadget que o ponto inicial
da exibio do contedo. 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
varivel para a configurao de
margens CSS.
Esta varivel representa a
lateral do gadget oposta ao lado
de incio da exibio do
__BIDI_E
ND_EDGE_ contedo. 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 varivel ser "ltr"
__BIDI_D quando o gadget estiver em
IR__ modo LTR e "rtl" quando o
O valor desta varivel ser "rtl"
__BIDI_R
EVERSE_D quando o gadget estiver em
IR__ modo LTR e "ltr" quando o
Alterao da direo de parte do gadget

A API BIDI altera a direo de um gadget inteiro e formata o contedo do gadget de forma
correspondente. Entretanto, pode haver casos em que voc deseja mexer na direo de linhas de
texto individuais dentro do gadget. Talvez voc no queira que a direo do gadget seja associada
configurao de idioma do usurio ou a qualquer idioma especfico. Por exemplo, voc pode criar
um gadget que exibe texto simultaneamente em ingls e hebraico. Ou voc pode criar um gadget
que lista frases comuns em diversos idiomas. Voc pode usar chamadas regulares a funes DOM e
CSS para definir a direo do texto dentro do corpo do gadget. Por exemplo:
<Module>
<ModulePrefs title="DOM Hello World" height="200" />
// 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 configurao de pas e idioma de modo que ela corresponda aos
pacotes de mensagens includos em seu gadget.
A maneira mais simples de alterar a configurao de pas e idioma no iGoogle editar o URL:
http://www.google.com/ig?&gl=<country>&hl=<lang>
Por exemplo, no URL abaixo, o pas Alemanha (DE) e o idioma ingls (en). Normalmente, o
pas tem precedncia sobre o idioma. Portanto, com este URL, o iGoogle exibe texto em alemo:
http://www.google.com/ig?&gl=DE&hl=en
Neste exemplo, o pas 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 especfico:
http://www.google.com/help/customize.html#searchlang. Os valores vlidos para o idioma so
cdigos de idioma ISO639-1 com dois dgitos e os valores vlidos para o pas so cdigos ISO
3166-1 alfa-2.
Cache
Os pacotes de mensagens tm o mesmo comportamento de cache que as especificaes 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 solicitaes de pacotes de mensagens por dia e, se eles no
estiverem disponveis, continuaremos usando nossa cpia "antiga" pelo tempo que for possvel. No
gadget developer.xml, ao desativar o cache do gadget, voc tambm desativa o cache dos pacotes
de mensagens do gadget.
Soluo de problemas
Durante o desenvolvimento, seu gadget pode ficar em branco ou exibir ??? onde deveria haver uma
mensagem. O problema pode ser:
Voc no salvou o pacote de mensagens em UTF-8. Isso necessrio para qualquer arquivo
de idioma diferente do ingls que inclua caracteres especiais.
H um problema na sintaxe do seu pacote de mensagens.
No h um arquivo de pacote de mensagens ALL_ALL.xml para ser usado como padro
pelo gadget.
No gadget, o URL do pacote de mensagens est incorreto.
H um erro de correspondncia entre o pacote de mensagens e a varivel de substituio de
mensagens especificada no gadget.
Gadgets em idiomas diferentes do ingls
A maioria dos exemplos deste guia do desenvolvedor foi criada em ingls. Este documento descreve
recursos disponveis para usurios interessados em criar gadgets em outros idiomas.
Onde posso encontrar gadgets que no sejam em ingls?

Uma das caractersticas mais teis dos gadgets a visibilidade pblica de seu cdigo-fonte. Voc
pode aprender muito sobre o desenvolvimento de gadgets observando como outros gadgets so
implementados.
Para encontrar gadgets criados em um idioma especfico, faa uma filtragem no diretrio de
contedo do iGoogle com base no pas e idioma de sua preferncia. Voc pode usar o menu More
Languages (Mais idiomas) no diretrio de contedo ou especificar os cdigos de idioma e pas no
URL. Por exemplo, para ver gadgets em japons, use este URL:
http://www.google.com/ig/directory?&gl=JP&hl=ja&root=/ig&dpos=top
O parmetro para o cdigo do pas &gl e o parmetro para o cdigo do idioma &hl. Neste
exemplo, o cdigo do pas (Japo) JP, e o cdigo do idioma japons ja (por padro, os cdigos
de idioma esto em letras minsculas e os cdigos de pas em letras maisculas, mas isso no
obrigatrio). O contedo do diretrio varia ligeiramente se voc fornecer somente o cdigo do pas
ou do idioma. Portanto, inclua ambos os cdigos (de pas e idioma) para obter resultados mais
especficos.
Uma boa maneira de encontrar gadgets em um idioma especfico filtrar o diretrio. Entretanto,
isso no retorna somente os gadgets criados no idioma de destino, pois os gadgets no recebem tags
de idioma. A API de gadgets inclui uma tag <Locale>, mas esta opcional. O diretrio exibe
gadgets para um local especfico com base em sua popularidade. Portanto, ao exibir o diretrio do
local Japo/japons, por exemplo, voc ver principalmente gadgets japoneses. Mas tambm poder
ver gadgets populares neste local, apesar de no serem em japons.
No diretrio de contedo do iGoogle, voc pode adicionar gadgets sua pgina do iGoogle. Aps
adicion-los ao iGoogle, voc poder visualizar o cdigo-fonte dos gadgets clicando em seus links
na pgina de gadgets do desenvolvedor. Os gadgets no personalizados (por exemplo, gadgets que
apenas exibem feeds) no esto listados na pgina de gadgets do desenvolvedor.
Criao de gadgets em idiomas diferentes do ingls

Os gadgets usam codificao UTF-8 para idiomas diferentes do ingls. A API de gadgets suporta
codificao UTF-8 para valores de atributos XML e tambm na seo <Content>. Quando o tipo
de contedo definido como html, a codificao padro definida expressamente como UTF-8.
Voc no deve tentar defini-la sozinho.
Se criar um gadget que suporte diversos idiomas, as strings das mensagens traduzidas sero
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 documentao Internacionalizao para obter informaes detalhadas sobre como criar
gadgets em diversos idiomas.
Publicao do seu gadget
Este documento descreve as diferentes opes de publicao do seu gadget. Se voc usa o Google
Gadgets Editor (GGE) para criar e hospedar gadgets, a publicao dos seus gadgets ficar muito
mais fcil.
Onde posso colocar meu gadget?

Voc pode colocar seus gadgets em qualquer um dos lugares a seguir:
Nas sua pgina e nas pginas de seus amigos no iGoogle.
Em outros recipientes de rede social que suportam gadgets, como o Orkut.
No diretrio de contedo do Google. Se voc enviar seu gadget ao diretrio de contedo, ele
ficar disponvel para um pblico maior.
Nem todo gadget adequado a todos os ambientes. Consulte a documentao do recipiente para
obter detalhes sobre os recursos suportados no ambiente especfico.
Preparao para a publicao

Voc deve testar seu gadget antes de public-lo, levando em considerao os requisitos e limitaes
do ambiente no qual o gadget ser executado.
Faa os testes abaixo para todos os gadgets:
Tente todas as combinaes de valores de UserPref.
Execute-o em telas de tamanhos diferentes, desde 800x600 at a maior largura possvel.
Vincule extenso de desenvolvedor da web do Firefox, o que facilita o redimensionamento
do Firefox para um tamanho especfico.
Teste seu gadget em diferentes tamanhos, conforme descrito na seo 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 > Opes >
Contedo. Clique em Avanado na seo "Fontes e cores". Altere a configurao de
fonte e desmarque "Pginas podem usar outras fontes".
Para alterar o tamanho da fonte no Internet Explorer, selecione Ferramentas >
Opes da Internet > Geral. Use as caixas de dilogo Fontes e Acessibilidade para
alterar sua configurao de fontes.
Se estiver usando makeRequest(), verifique o que acontece se a fonte de dados estiver
inacessvel 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
documentao do seu recipiente para obter mais detalhes.
Ao criar e testar seus gadgets, prepare-se para larguras arbitrrias 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 espao. 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 so na parte inferior da pgina, devem permanecer prximos ao contedo, em vez
de serem colocados na parte inferior da janela do gadget).
Aperfeioamento do desempenho do gadget

Se ao criar um gadget voc espera causar trfego intenso, h etapas que podem ser seguidas para
assegurar disponibilidade e um bom desempenho. Procure seguir as dicas desta seo caso seu
gadget tenha mais de 200.000 visualizaes por dia ou aproximadamente 1 a 2 solicitaes por
segundo. Mesmo um gadget de 50 KB recebendo 200.000 solicitaes por dia consome cerca de
300 GB de largura de banda por ms.
H motivos diferentes que podem tornar um gadget atraente para muitos usurios. Ele pode
simplesmente tornar-se popular no diretrio de contedo. Ou ainda, ser usado em uma promoo
especial ou em publicidade, o que pode causar um excesso de trfego.
No caso de um gadget de trfego 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 experincia do usurio melhorar a capacidade de resposta do seu gadget.
Consulte Otimizao para trfego intenso para obter dicas sobre como otimizar o desempenho do
gadget. Para obter dicas sobre gerenciamento, consulte Gerenciamento de trfego intenso. As
orientaes gerais de teste tambm so especialmente importantes para gadgets muito populares.
Otimizao para trfego intenso

Se voc acha que seu gadget poder causar trfego intenso, siga as orientaes abaixo:
Evite usar arquivos JavaScript ou CSS externos (arquivos que contm atributos "src" ou
"href" nas tags HTML), pois isso requer o uso de outra conexo de rede. Em vez disso,
coloque seu cdigo JavaScript e CSS dentro das especificaes do gadget.
Use um gadget type=html. Os gadgets type=url geralmente so exibidos mais
lentamente que os gadgets type=html, devido ao desempenho e suporte a cache ruins de
outros servidores de hospedagem.
Como padro, o mtodo makeRequest() armazena o contedo em cache por
aproximadamente 1 a 2 horas. Voc pode usar o parmetro refreshInterval com essas
funes para atualizar o cache com mais freqncia. Entretanto, o uso de cache melhora o
desempenho do gadget, minimizando o nmero de solicitaes enviadas aos servidores
remotos que hospedam o contedo. No solicite um nmero de atualizaes de cache maior
que o necessrio, pois voc reduzir a porcentagem de solicitaes suportadas pelo cache.
Para uma discusso mais profunda sobre este tpico, consulte Atualizao do cache.
Use o Firebug (somente Firefox) para ajustar o desempenho do seu gadget. Para outros
navegadores, use o Fiddler.
Se possvel, evite usar o Google Analytics, pois ele requer uma conexo adicional ao
servidor. Em vez do Analytics, use http://www.google.com/ig/directory?
url=<gadget-url> para verificar o total semanal de visualizaes de pgina do seu gadget.
Especifique a altura e a largura de todas as tags <img> no HTML do gadget. Isso agiliza a
exibio do gadget. Se voc estiver usando gadgets.io.getProxyUrl() e inserindo
o elemento imagem diretamente no DOM, no necessrio definir as propriedades de
largura e altura.
Em vez de conectar-se diretamente ao seu provedor de hospedagem, use a funo
gadgets.io.getProxyUrl() para armazenar todas as imagens incorporadas em
cache e a funo embedCachedFlash() para armazenar o contedo 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():
<Module>
<ModulePrefs title="Zombies!" height="350" />
<![CDATA[
<div id="zombiecontainer"
style="text-align:center;">
</div>
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-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 trfego intenso

Estas orientaes podem ajud-lo a gerenciar um gadget de alto volume de trfego:
Se estiver recebendo uma grande quantidade de e-mails dos usurios do seu gadget, use o
Gmail para configurar filtros e gerenciar o volume. Recomendamos o uso de um endereo
no formato <username>.feedback+<gadgetname>@gmail.com na especificao do
seu gadget. Isso ajuda a filtrar as mensagens recebidas dos usurios do gadget. O Gmail
ignora tudo o que est depois do sinal de mais (+), fazendo com que o endereo 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 diretrio de contedo do iGoogle, visite periodicamente a
pgina de descrio do seu gadget para ler os comentrios dos usurios. Freqentemente, os
usurios deixam um feedback valioso, fazem solicitaes e relatam bugs que encontraram ao
usar o gadget. bom ficar a par de seus comentrios e manter contato com eles.
Publicao no diretrio de contedo do iGoogle

Depois de criar, implementar e testar o gadget, voc pode envi-lo ao Google para ser publicado no
diretrio de contedo do iGoogle. Esta seo lista as etapas gerais que voc deve seguir ao preparar
seu gadget para publicao.
Etapa 1: Defina as preferncias do seu gadget.

A Referncia lista todos os atributos <ModulePrefs> que podem ser usados para fornecer
informaes "meta" sobre seu gadget. Aqui esto as informaes que voc deve incluir na
especificao do seu gadget:
title
description. Este atributo importante para que as pessoas saibam o que seu gadget faz,
particularmente se isso no for bvio.
author
author_email. Use esse atributo para que o Google e os usurios possam entrar em contato
com voc. Voc pode usar qualquer sistema de e-mail. Evite usar um endereo de e-mail
pessoal devido aos spams. Uma boa estratgia usar um endereo de e-mail com o formato
helensmith.feedback+coolgadget@gmail.com na especificao do seu gadget.
O Gmail ignora tudo o que est depois do sinal de mais (+), fazendo com que o endereo 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 no relativo. Esta imagem deve estar em um site pblico da web
no bloqueado por robots.txt. O formato preferido PNG, embora os formatos GIF e
JPG tambm sejam aceitveis. 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 usurio a identificar quanto espao de sua tela ser consumido pelo gadget antes de
adicion-lo sua pgina. A captura de tela no deve ter nenhum espao em branco acima da
barra de cabealho azul do gadget. As capturas de tela devem mostrar apenas o gadget
completo, incluindo sua barra de ttulo. Como alternativa, faa uma captura de tela do
gadget com a janela de edio aberta. No redimensione ou corte as capturas de tela. Para
manter a qualidade e a consistncia, o Google pode fazer suas prprias capturas de tela
relativas a um gadget especfico.
thumbnail. No diretrio de contedo, as miniaturas permitem que os usurios 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 no relativo. Esta imagem deve estar em um site
pblico da web no bloqueado por robots.txt. O formato preferido PNG, embora os
formatos GIF e JPG tambm sejam aceitveis. As miniaturas devem medir 120x60 pixels.
Elas no devem incluir a barra de ttulo.
author_location
author_affiliation
title_url. Use este atributo para vincular o ttulo do seu gadget a uma pgina HTML externa.
Por exemplo, se o gadget for o front end de um servio, vincule o ttulo do gadget ao site do
servio.
directory_title (obrigatrio se o ttulo tiver variveis de substituio de preferncias do
usurio).
Se voc deseja ser includo na pgina de autores, adicione estes campos:
author_photo. URL para uma foto (o formato preferido 70x100 PNG, mas JPG/GIF
tambm so 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 citao que voc queira incluir (tente limitar em aproximadamente 300
caracteres).
Encontre mais informaes 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 segurana.
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 especfico. Use a tag <MayRequire> em <ModulePrefs> para fornecer
informaes sobre os requisitos especiais do seu gadget. Para obter mais informaes, consulte
Especificao dos requisitos de compatibilidade.
Etapa 4: Adicione todas as informaes relevantes de local.

Use as tags <Locale> em <ModulePrefs> para especificar os locais suportados pelo seu
gadget. Para obter mais informaes, consulte Especificao dos locais.
Etapa 5: Facilite o processo de adio do seu gadget.

Para promover um gadget, coloque nele um boto "Adicionar ao Google".
Etapa 6: Envie seu gadget ao Google.

Voc pode enviar seu gadget ao Google aqui. Voc tambm pode enviar seu gadget ao diretrio de
contedo, clicando em GGE e usando o comando File > Publish (Arquivo > Publicar). Consulte
as Perguntas freqentes para obter uma explicao sobre como encontrar seu gadget no diretrio e o
que determina sua posio.
Gerenciamento dos gadgets enviados

Se voc enviou diversas verses de um gadget em diferentes URLs e deseja designar uma verso
como a oficial, use a pgina Enviar uma solicitao de alias.
Referncia da API de gadgets
Esta a referncia para a API de gadgets.*. Ela inclui informaes de referncia para a
especificao XML do gadget.
Voc pode ver a Referncia de JavaScript aqui.
Observao: A API de gadgets foi inserida no namespace JavaScript de gadgets.*, para
fornecer uma API mais limpa para programao e suporte. Se voc estiver interessado em
compreender melhor a API de gadgets.*, leia a Especificao do Gadgets.
Estrutura XML
As sees a seguir descrevem a estrutura e o contedo do arquivo XML usado para especificar um
gadget.
Preferncias do gadget
A seo <ModulePrefs> do arquivo XML especifica as caractersticas do gadget, como ttulo,
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 usurios do seu gadget no podem alterar esses atributos.

A tabela abaixo lista os atributos <ModulePrefs>:
Atributo Descrio
String opcional que fornece o ttulo do gadget. Esse ttulo exibido na barra de
ttulo do gadget no iGoogle. Se esta string contm variveis de substituio de
title preferncias do usurio e voc pretende enviar seu gadget ao diretrio de
contedo do iGoogle, fornea tambm um directory_title para ser
exibido no diretrio.
String opcional que fornece o ttulo do gadget a ser exibido no diretrio de
contedo do iGoogle. Deve conter somente o texto que ser realmente exibido,
sem variveis de substituio de preferncias do usurio. Isso importante
directory_ti porque o diretrio de contedo do iGoogle exibe uma verso esttica do seu
gadget. Portanto, ele no pode executar a substituio necessria para fornecer
tle
um ttulo aceitvel. Por exemplo, Se o ttulo do seu gadget for "Friends for
__UP_name__", o diretrio no capaz de executar a substituio para fornecer
um valor aceitvel para " __UP_name__". Assim, configure
directory_title simplesmente como "Friends".
title_url String opcional que fornece um URL de link do ttulo do gadget. Por exemplo,
voc pode vincular o ttulo a uma pgina 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 endereo de e-mail do autor do gadget. Voc pode
usar qualquer sistema de e-mail. Evite usar um endereo de e-mail pessoal
devido aos spams. Uma boa estratgia usar um endereo de e-mail com o
formato helensmith.feedback+coolgadget@gmail.com na especificao do
author_email gadget.
O Gmail ignora tudo o que est depois do sinal de mais (+), fazendo com que o
endereo de e-mail seja interpretado como helensmith.feedback@gmail.com.
Crie uma conta do Gmail aqui.

author_affil Seqncia opcional, como "Google", que indica a afiliao do autor. Esse
iation atributo necessrio para gadgets includos no diretrio de contedo do iGoogle.
author_locat
ion A localizao geogrfica 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 pblico da web no bloqueado por robots.txt. O
formato preferido PNG, embora os formatos GIF e JPG tambm sejam
screenshot aceitveis. 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 Publicao no diretrio
de contedo do iGoogle.
String opcional que fornece o URL de uma miniatura do gadget. Esta imagem
deve estar em um site pblico da web no bloqueado por robots.txt. O formato
thumbnail preferido PNG, embora os formatos GIF e JPG tambm sejam aceitveis. As
miniaturas de gadget devem medir 120x60 pixels. Para ler mais sobre diretrizes
de miniatura, consulte Publicao no diretrio de contedo do iGoogle.
height Nmero inteiro positivo opcional que especifica a altura da rea na qual o gadget
ser executado. A altura padro 200.
width Nmero inteiro positivo opcional que especifica a largura da rea na qual o
gadget ser executado. A largura padro 320.
Valor booleano opcional que especifica se a proporo (razo 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 padro true.
Valor booleano opcional que fornece barras de rolagem vertical e/ou horizontal
scrolling caso o contedo exceda o espao fornecido. Se configurado como false, o
contedo recortado segundo a altura e a largura fornecidas (observe que a
largura no configurvel). O padro false.
singleton Valor booleano opcional que especifica se o usurio pode adicionar um gadget
vrias vezes a partir de um mesmo diretrio. O padro true. Isso significa que,
como padro, os gadgets podem ser adicionados somente uma vez. Entretanto,
os diretrios podem manipular este atributo como desejarem. Por exemplo, o
diretrio de contedo 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 alteraes
neste atributo podem no ser atualizadas imediatamente nos diretrios.
Este atributo no impede que os usurios adicionem gadgets diversas vezes

atravs do gadget do desenvolvedor ou que Adicionem gadgets por URL.
Conseqentemente, continua sendo necessrio que voc crie seu gadget para
suportar diversas instncias.
author_photo Para a pgina de autores, um URL para uma foto (o formato preferido 70x100
PNG, mas JPG/GIF tambm so suportados).
author_about Para a pgina de autores, um texto sobre si mesmo (tente limitar em
me aproximadamente 500 caracteres).
author_link Para a pgina de autores, um link para seu site, blog, etc.
author_quote Para a pgina de autores, uma citao que voc deseja de incluir (tente limitar
em aproximadamente 300 caracteres).
Uso de bibliotecas
Para usar determinados recursos da API de gadgets, como altura dinmica ou estado de
armazenamento, necessrio carregar a biblioteca JavaScript apropriada, usando a tag
<Require> (dentro de <ModulePrefs>). A tag <Require> possui um atributo obrigatrio,
feature, cujo valor especifica a biblioteca do recurso. Por exemplo:
<ModulePrefs
title="Set Userprefs Demo">
<Require feature="dynamic-height"/>
</ModulePrefs>
Para obter mais informaes sobre bibliotecas de recursos, consulte a Referncia de JavaScript.
Especificao de locais
Use as tags <Locale> em <ModulePrefs> para especificar os locais suportados pelo seu
gadget. Voc tambm pode us-las para especificar pacotes de mensagens, como descrito em
Gadgets e internacionalizao.
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" (pas) so 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 pas e nenhum idioma, o sistema assumir que seu gadget
suporta todos os idiomas associados ao pas. Da mesma forma, se voc especificar um idioma e
nenhum pas, o sistema assumir que seu gadget suporta todos os pases associados ao idioma.
Os valores vlidos para o idioma so cdigos de idioma ISO639-1 com dois dgitos e os valores
vlidos para o pas so cdigos ISO 3166-1 alfa-2.
H algumas excees s regras normais de idioma:
Chins simplificado: lang="zh-cn" (normalmente para country="cn").
Chins tradicional: lang="zh-tw" (normalmente para country="tw" ou "hk", Taiwan ou
Hong Kong, respectivamente).
A tabela abaixo lista os atributos <Locale>:
Atributo Descrio
lang String opcional, indicando o idioma associado ao local.
country String opcional, indicando o pas associado ao local.
String opcional que um URL apontando para um pacote de mensagens. Os
messages pacotes de mensagens so arquivos XML que contm as strings traduzidas para
um dado local. Para obter mais informaes, consulte Gadgets e
internacionalizao.
String opcional que define a direo do gadget. Seu valor pode ser "rtl" (direita
para a esquerda) ou "ltr" (esquerda para a direita). O padro "ltr". Este atributo
permite criar gadgets que suportam idiomas lidos da esquerda para a direita e vice-
versa. Para ler mais sobre este tpico, consulte Criao de gadgets bidirecionais.
Voc pode usar as variveis de substituio 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 varivel "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 varivel "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 no especificar um <Locale>, o padro suposto ser EUA + ingls somente.
Especificao de requisitos de compatibilidade

Nem todos os gadgets podem ser executados em todos os ambientes. Um gadget pode exigir um
navegador ou software especfico. Use a tag <MayRequire> para fornecer informaes 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 Descrio
String obrigatria indicando o tipo de requisito. Os tipos suportados so
type
"platform", "browser" e "plugin".
String obrigatria que fornece um valor para o tipo. Por exemplo,
value
type="plugin" value="flash".
min_versio
n String opcional indicando o nmero mnimo de verso do item obrigatrio.
cdata String opcional que fornece informaes adicionais sobre o requisito.
Preferncias do usurio
Alguns gadgets precisam fornecer um meio de informaes especficas ao usurio serem inseridas.
Por exemplo, um gadget de condies climticas pode exigir que o usurio fornea seu cdigo
postal. A seo de preferncias do usurio (<UserPref>) do arquivo XML descreve os campos de
entrada do usurio que so transformados em controles da interface de usurio quando o gadget
executado.
A tabela abaixo lista os atributos <UserPref>:
Atributo Descrio
O nome "simblico" obrigatrio da preferncia do usurio, exibido durante a edio
caso no haja nenhum display_name definido. Deve conter somente letras,
name
nmeros e caracteres de sublinhado, isto , a expresso regular ^[a-zA-Z0-9_]+$.
Deve ser exclusivo.
display_n String opcional para ser exibida ao lado das preferncias do usurio na janela de
ame edio. Deve ser exclusivo.
String opcional para passar como o nome do parmetro para contedo
urlparam
type="url".
String opcional indicando o tipo de dados deste atributo. Pode ser string, bool,
enum, hidden (uma string invisvel e no editvel pelo usurio), list (uma
datatype
matriz dinmica gerada a partir de dados inseridos pelo usurio) ou location
(para gadgets baseados no Google Maps). O padro string.
Argumento booleano opcional (true ou false) indicando se esta preferncia do
required
usurio obrigatria. O padro false.
default_v
alue String opcional que indica o valor padro das preferncias de um usurio.
Use a API JavaScript para acessar as preferncias do usurio a partir do seu gadget; por exemplo:
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 usurio como um menu de opes. Especifique o
contedo do menu usando <EnumValue>.
Por exemplo, esta <UserPref> permite que os usurios definam o nvel 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 Descrio
String obrigatria que fornece um valor exclusivo. Este valor exibido no menu
value da caixa de edio das preferncias do usurio, a menos que um
display_value seja fornecido.
String opcional que exibida no menu da caixa de edio de preferncias do
display_val
usurio. Se voc no especificar um display_value, o value exibido na
ue
interface do usurio.
Seo de contedo
A seo <Content> define o tipo de contedo e contm o prprio contedo ou uma referncia
para contedo externo. A seo <Content> onde os atributos do gadget e as preferncias do
usurio so combinados lgica de programao e s informaes de formatao para se
transformarem em um gadget executvel. Para ler mais sobre tipos de contedo, consulte Seleo
do tipo de contedo.
A tabela abaixo lista os atributos <Content>:
Atributo Descrio
String opcional que fornece o tipo de contedo. Os valores possveis so html e url. O
type
padro html.
String que fornece um URL de destino. Obrigatrio para type="url" e no permitido
href
com outros tipos de contedo.
cdata String opcional. Para HTML, contm o HTML puro que ser exibido no iframe.
API Reference: gadgets.*
Bem-vindo a uma pr-apresentao da documentao de referncia da API de gadgets. Esta
documentao contm detalhes sobre a futura insero da API de gadgets em uma API JavaScript
de gadgets.* mais limpa.
Observao: Esta API ainda no suportada pelo iGoogle. Se voc deseja criar um gadget para o
iGoogle, consulte a Referncia da API do Google Gadgets.
Sumrio
API principal
Prefs
io
AuthorizationType
ContentType
MethodType
RequestParameters
json
util
API especfica do recurso
MiniMessage
Tab
TabSet
flash
rpc
views
View
ViewType
skins
Property
window
gadgets.Prefs
Classe gadgets.Prefs
Fornece acesso s preferncias do usurio, dimenses do mdulo e mensagens. Os clientes podem
acessar suas preferncias, criando uma instncia de gadgets.Prefs e passando o id do mdulo.
Exemplo:
var name = prefs.getString("name");
var lang = prefs.getLang();
Resumo do construtor
gadgets.Prefs(opt_moduleId)
Cria um novo objeto Prefs.
Resumo do mtodo
Array.<String> getArray(key)
Recupera uma preferncia de matriz.
Boolean getBool(key)
Recupera uma preferncia booleana.
String getCountry()
Obtm o pas atual, retornado como um cdigo ISO 3166-1 alpha-2.
Number getFloat(key)
Recupera uma preferncia de ponto flutuante.
Number getInt(key)
Recupera uma preferncia de nmero inteiro.
String getLang()
Obtm o idioma atual que o gadget deve usar na visualizao, retornado como um cdigo de
idioma ISO 639-1.
String, Number getModuleId()
Obtm o id do mdulo para a instncia atual.
String getMsg(key)
Obtm uma mensagem no formatada.
String getMsgFormatted(key, opt_subst)
Retorna um valor de mensagem com o argumento de posio opt_subst no lugar, caso seja
fornecido, ou caso contrrio, o valor fornecido no exemplo. Se a mensagem no for
encontrada, retorna a string vazia.
String getString(key)
Recupera uma preferncia de string.
set(key, val)
Armazena uma preferncia.
setArray(key, val)
Armazena uma preferncia de matriz.
Detalhes do construtor
gadgets.Prefs
gadgets.Prefs(opt_moduleId)
Cria um novo objeto Prefs.

Parmetros:
String, Number opt_moduleId - Um parmetro opcional especificando o id
do mdulo para o qual as preferncias sero criadas; se no for fornecido, usado o
id do mdulo padro
Detalhes do mtodo
getArray
Array.<String> getArray(key)
Recupera uma preferncia de matriz. Os valores de UserPref que no foram declarados

como listas so tratados como matrizes de um nico elemento.
Parmetros:
String key - A preferncia a ser obtida
Retorna:
Array.<String> A preferncia; se no estiver definida, uma matriz vazia
getBool
Boolean getBool(key)
Recupera uma preferncia booleana.

Parmetros:
Retorna:
Boolean A preferncia; se no estiver definida, false (falso)
getCountry
String getCountry()
Obtm o pas atual, retornado como um cdigo ISO 3166-1 alpha-2.

Retorna:
String O pas para esta instncia do mdulo
getFloat
Number getFloat(key)
Recupera uma preferncia de ponto flutuante.

Parmetros:
Retorna:
Number A preferncia; se no estiver definida, 0
getInt
Number getInt(key)
Recupera uma preferncia de nmero inteiro.

Parmetros:
Retorna:
Number A preferncia; se no estiver definida, 0
getLang
String getLang()
Obtm o idioma atual que o gadget deve usar na visualizao, retornado como um cdigo de
idioma ISO 639-1.
Retorna:
String O idioma para esta instncia do mdulo
getModuleId
String, Number getModuleId()
Obtm o id do mdulo para a instncia atual.

Retorna:
String, Number O id do mdulo para esta instncia do mdulo
getMsg
String getMsg(key)
Obtm uma mensagem no formatada.

Parmetros:
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 posio opt_subst no lugar, caso seja
fornecido, ou caso contrrio, o valor fornecido no exemplo. Se a mensagem no for
encontrada, retorna a string vazia.
Parmetros:
String key - A mensagem a ser obtida
String opt_subst - Uma string opcional para ser substituda na mensagem
Retorna:
String A string formatada
getString
String getString(key)
Recupera uma preferncia de string.

Parmetros:
Retorna:
String A preferncia; se no estiver definida, uma string vazia
set
set(key, val)
Armazena uma preferncia. Para usar esta chamada, o gadget precisa ter o recurso setprefs.
Observao: Se o gadget tiver que armazenar uma matriz, ele dever usar setArray em vez
desta chamada.
Parmetros:
String key - A preferncia a ser armazenada
Object val - Os valores a serem armazenados
setArray
setArray(key, val)
Armazena uma preferncia de matriz. Para usar esta chamada, o gadget precisa ter o recurso
setprefs.
Parmetros:
String key - A preferncia a ser armazenada
Array val - Os valores a serem armazenados
gadgets.io
Static Class gadgets.io
Fornece funes de recuperao de contedo remoto.
Resumo do mtodo
<static> String encodeValues(fields)
Converte um objeto de entrada em uma string de dados codificada como URL.
<static> String getProxyUrl(url)
Obtm a verso proxy do URL passado.
<static> makeRequest(url, callback, opt_params)
Obtm o contedo a partir do URL fornecido e alimenta este contedo na funo de retorno
de chamada.
Detalhes do mtodo
encodeValues
<static> String encodeValues(fields)
Converte um objeto de entrada em uma string de dados codificada como URL.

(chave=valor&...)
Parmetros:
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)
Obtm a verso proxy do URL passado.

Parmetros:
String url - O URL a partir do qual o URL com o proxy ser obtido
Retorna:
String A verso do URL com o proxy
makeRequest
<static> makeRequest(url, callback, opt_params)
Obtm o contedo a partir do URL fornecido e alimenta este contedo na funo de retorno
de chamada. Exemplo:
var params = {};
gadgets.io.makeRequest(url, callback, params);
Parmetros:
String url - O URL no qual o contedo est localizado
Function callback - A funo a ser chamada com os dados do URL aps a
obteno
Map.<gadgets.io.RequestParameters, Object> opt_params -
Parmetros adicionais a serem passados para a solicitao
gadgets.io.AuthorizationType
Static Class gadgets.io.AuthorizationType
Usada por RequestParameters.
Resumo do campo
<static> object AUTHENTICATED
O recipiente usar autenticao completa.
<static> object NONE
Sem autorizao.
<static> object SIGNED
A solicitao ser assinada pelo recipiente.
Detalhes do campo
AUTHENTICATED
<static> object AUTHENTICATED
O recipiente usar autenticao completa.
NONE
<static> object NONE
Sem autorizao.
SIGNED
<static> object SIGNED
A solicitao ser assinada pelo recipiente.

gadgets.io.ContentType
Static Class gadgets.io.ContentType
Resumo do campo
<static> object DOM
Retorna um objeto DOM; usado para obter XML.
<static> object FEED
Retorna uma representao 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 representao 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
Resumo do campo
<static> object DELETE
No suportado por todos os recipientes.
<static> object GET
O tipo padro.
<static> object HEAD
<static> object POST
<static> object PUT
Detalhes do campo
DELETE
<static> object DELETE
GET
<static> object GET
O tipo padro.
HEAD
<static> object HEAD
POST
<static> object POST
PUT
<static> object PUT
gadgets.io.RequestParameters
Static Class gadgets.io.RequestParameters

Usada pelo mtodo gadgets.io.makeRequest().
Resumo do campo
<static> object AUTHORIZATION
O tipo de autenticao a ser usada durante a obteno do contedo; o padro
AuthorizationType.NONE.
<static> object CONTENT_TYPE
O tipo de contedo que reside no URL; o padro ContentType.TEXT.
<static> object GET_SUMMARIES
No caso do contedo ser um feed, indica se os resumos do feed devem ser obtidos; o padro
false (falso).
<static> object HEADERS
Os cabealhos HTTP a serem enviados ao URL; o padro null (nulo).
<static> object METHOD
O mtodo a ser usado durante a obteno de contedo a partir do URL; o padro
MethodType.GET.
<static> object NUM_ENTRIES
Se o contedo for um feed, indica o nmero de entradas a serem obtidas; o padro 3.
<static> object POST_DATA
Os dados a serem enviados ao URL usando o mtodo POST; o padro null (nulo).
Detalhes do campo
AUTHORIZATION
<static> object AUTHORIZATION
O tipo de autenticao a ser usada durante a obteno do contedo; o padro

AuthorizationType.NONE. Especificado como um Tipo de autorizao.
CONTENT_TYPE
<static> object CONTENT_TYPE
O tipo de contedo que reside no URL; o padro ContentType.TEXT. Especificado

como um Tipo de contedo.
GET_SUMMARIES
<static> object GET_SUMMARIES
No caso do contedo ser um feed, indica se os resumos do feed devem ser obtidos; o padro
false (falso). Especificado como um Boolean.
HEADERS
<static> object HEADERS
Os cabealhos HTTP a serem enviados ao URL; o padro null (nulo). Especificado como
um Map.<String,String>.
METHOD
<static> object METHOD
O mtodo a ser usado durante a obteno de contedo a partir do URL; o padro

MethodType.GET. Especificado como um Tipo de mtodo.
NUM_ENTRIES
<static> object NUM_ENTRIES
Se o contedo for um feed, indica o nmero de entradas a serem obtidas; o padro 3.

Especificado como um Number.
POST_DATA
<static> object POST_DATA
Os dados a serem enviados ao URL usando o mtodo POST; o padro null (nulo).
Especificado como um String.
gadgets.json
Static Class gadgets.json
Fornece operaes de converso de objetos de e para JSON.
Resumo do mtodo
<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 mtodo
parse
<static> Object parse(text)
Analisa uma string JSON, produzindo um valor JavaScript.

Parmetros:
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.

Parmetros:
Object v - O objeto a ser convertido
Retorna:
String O JSON equivalente
gadgets.util
Static Class gadgets.util
Fornece funes de utilitrio de uso geral.
Resumo do mtodo
<static> String escapeString(str)
Cria cdigos de escape para os dados inseridos, usando entidades html para garantir maior
segurana.
<static> Object getFeatureParameters(feature)
Obtm os parmetros do recurso.
<static> Object getUrlParameters()
Obtm os parmetros do URL.
<static> Boolean hasFeature(feature)
Retorna se o recurso atual suportado.
<static> makeClosure(scope, callback, var_args)
Cria um invlucro 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 mtodo
escapeString
<static> String escapeString(str)
Cria cdigos de escape para os dados inseridos, usando entidades html para garantir maior
segurana.
Parmetros:
String str - A String para a qual sero criados os cdigos de escape.
Retorna:
String A String com cdigos de escape.
getFeatureParameters
<static> Object getFeatureParameters(feature)
Obtm os parmetros do recurso.

Parmetros:
String feature - O recurso para o qual os parmetros sero obtidos
Retorna:
Object Os parmetros do recurso em questo, ou null (nulo)
getUrlParameters
<static> Object getUrlParameters()
Obtm os parmetros do URL.

Retorna:
Object Parmetros passados para a string da consulta
hasFeature
<static> Boolean hasFeature(feature)
Retorna se o recurso atual suportado.

Parmetros:
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 invlucro adequado para ser passado como um retorno de chamada. possvel
passar qualquer quantidade de argumentos ao retorno de chamada. Eles sero recebidos na
ordem em que forem passados.
Parmetros:
Object scope - O escopo da execuo; pode ser null se no houver necessidade
de associar uma instncia especfica 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 aps 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.

Parmetros:
Function callback - O manipulador a ser executado
unescapeString
<static> String unescapeString(str)
Inverte escapeString.
Parmetros:
String str - A String da qual sero removidos os cdigos de escape.
Retorna:
String A String sem cdigos de escape.
gadgets.MiniMessage
Classe gadgets.MiniMessage
Classe MiniMessage.
gadgets.MiniMessage(opt_moduleId, opt_container)
Usado para criar mensagens que aparecero para o usurio dentro do gadget.
Resumo do mtodo
Element createDismissibleMessage(message, opt_callback)
Cria uma mensagem que pode ser dispensada, com um cone [x] para permitir que os usurios
dispensem a mensagem.
Element createStaticMessage(message)
Cria uma mensagem esttica que pode ser dispensada apenas programaticamente (atravs de
uma chamada a dismissMessage()).
Element createTimerMessage(message, seconds, opt_callback)
Cria uma mensagem que exibida por um nmero especificado de segundos.
dismissMessage(message)
Dispensa a mensagem especificada.
gadgets.MiniMessage
gadgets.MiniMessage(opt_moduleId, opt_container)
Usado para criar mensagens que aparecero para o usurio dentro do gadget.
Parmetros:
String opt_moduleId - Id do mdulo opcional
Element opt_container - Elemento opcional do recipiente HTML no qual
aparecero as mini-mensagens.
Detalhes do mtodo
createDismissibleMessage
Element createDismissibleMessage(message, opt_callback)
Cria uma mensagem que pode ser dispensada, com um cone [x] para permitir que os
usurios dispensem a mensagem. Quando a mensagem dispensada, ela removida da
rvore DOM, e a funo opcional de retorno de chamada, se estiver definida, executada.
Parmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
Function opt_callback - Funo 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 esttica que pode ser dispensada apenas programaticamente (atravs de
uma chamada a dismissMessage()).
Parmetros:
elemento DOM
Retorna:
createTimerMessage
Element createTimerMessage(message, seconds, opt_callback)
Cria uma mensagem que exibida por um nmero especificado de segundos. Quando o
temporizador expira, a mensagem dispensada e a funo opcional de retorno de chamada
executada.
Parmetros:
elemento DOM
number seconds - Nmero de segundos que devem ser aguardados antes de a
mensagem ser dispensada
Function opt_callback - Funo opcional de retorno de chamada a ser
executada quando a mensagem for dispensada
Retorna:
dismissMessage
dismissMessage(message)
Dispensa a mensagem especificada.

Parmetros:
Element message - Elemento HTML da mensagem que ser removida
gadgets.Tab
Classe gadgets.Tab
Classe Tab para gadgets. Voc pode criar guias usando o mtodo TabSet addTab(). Para obter
objetos de Guia, use os mtodos TabSet getSelectedTab() ou getTabs().
Veja tambm: TabSet
Resumo do mtodo
Function getCallback()
Retorna a funo de retorno de chamada, executada quando a guia selecionada.
Element getContentContainer()
Retorna o elemento HTML no qual o contedo 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 contm o marcador da guia.
Detalhes do mtodo
getCallback
Function getCallback()
Retorna a funo de retorno de chamada, executada quando a guia selecionada.

Retorna:
Function A funo de retorno de chamada da guia.
getContentContainer
Element getContentContainer()
Retorna o elemento HTML no qual o contedo da guia visualizado.

Retorna:
Element O elemento HTML do recipiente do contedo.
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 contm 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.
gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)
Cria um novo objeto TabSet
Resumo do mtodo
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 contedo associado a elas.
Element getHeaderContainer()
Retorna o elemento cabealhos 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 contedo associado a ela.
setSelectedTab(tabIndex)
Seleciona a guia no tabIndex e ativa a funo de retorno de chamada da guia, se existir.
swapTabs(tabIndex1, tabIndex2)
Troca as posies das guias em tabIndex1 e tabIndex2.
gadgets.TabSet
gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)
Cria um novo objeto TabSet

Parmetros:
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 aps a inicializao. Se esse parmetro for omitido, a primeira guia
selecionada por padro.
Element opt_container - O elemento HTML que conter as guias. Se
omitido, um novo elemento div criado e inserido no alto.
Detalhes do mtodo
addTab
String addTab(tabName, opt_params)
Adiciona uma nova guia com base nos pares nome-valor especificados em opt_params.
Parmetros:
String tabName - Marcador da guia a ser criada.
Object opt_params - Objeto de parmetro opcional. As seguintes propriedades
so suportadas: .contentContainer. um elemento HTML existente a ser usado como
recipiente do contedo da guia. Se omitido, a biblioteca de guias cria um elemento.
.callback. uma funo de retorno de chamada a ser executada quando a guia
selecionada. .tooltip. uma descrio de dica de ferramenta que aparece quando o
usurio 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 padro, as guias so centralizadas.

Parmetros:
String align - 'left' (esquerda), 'center' (centralizado) ou 'right' (direita).
Number opt_offset - Parmetro opcional para definir o nmero de pixels de
deslocamento das guias em relao margem esquerda ou direita. O valor padro
3px.
displayTabs
displayTabs(display)
Exibe ou oculta guias e todo o contedo associado a elas.

Parmetros:
Boolean display - true (verdadeiro) para exibir as guias; false (falso) para
ocultar as guias.
getHeaderContainer
Element getHeaderContainer()
Retorna o elemento cabealhos de guia do recipiente.

Retorna:
Element O elemento cabealhos 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 contedo associado a ela.
Parmetros:
Number tabIndex - ndice da guia a ser removida.
setSelectedTab
setSelectedTab(tabIndex)
Seleciona a guia no tabIndex e ativa a funo de retorno de chamada da guia, se existir. Se a

guia j estiver selecionada, o retorno de chamada no ativado.
Parmetros:
Number tabIndex - ndice da guia a ser selecionada.
swapTabs
swapTabs(tabIndex1, tabIndex2)
Troca as posies das guias em tabIndex1 e tabIndex2. A guia selecionada no alterada e

nenhuma funo de retorno de chamada executada.
Parmetros:
Number tabIndex1 - ndice da guia a ser trocada.
Number tabIndex2 - ndice da segunda guia a ser trocada.
gadgets.flash
Static Class gadgets.flash
Integra contedo Flash nos gadgets.
Resumo do mtodo
<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 verso principal.
Detalhes do mtodo
embedCachedFlash
<static> Boolean embedCachedFlash()
Injeta um arquivo Flash com cache na rvore DOM. Aceita os mesmos parmetros que
gadgets.flash.embedFlash.
Retorna:
Boolean Se a chamada funo for concluda com sucesso.
embedFlash
<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)
Injeta um arquivo Flash na rvore DOM.

Parmetros:
String swfUrl - SWF URL.
String, Object swfContainer - O ID ou referncia de objeto de um
elemento existente do recipiente html.
Number swfVersion - Verso mnima do Flash Player necessria.
Object opt_params - Um objeto opcional que pode conter qualquer parmetro
html vlido. Todos os atributos sero passados atravs do filme flash durante a
criao.
Retorna:
Boolean Se a chamada funo for concluda com sucesso.
getMajorVersion
<static> Number getMajorVersion()
Detecta o Flash Player e sua verso principal.

Retorna:
Number A verso principal do Flash Player ou 0 se o Flash no for suportado.
gadgets.rpc
Static Class gadgets.rpc
Fornece operaes para realizar chamadas rpc.
Resumo do mtodo
<static> call(targetId, serviceName, callback, var_args)
Chama um servio RPC.
<static> register(serviceName, handler)
Registra um servio RPC.
<static> registerDefault(handler)
Registra um manipulador de servios padro para processar todas as chamadas RPC
desconhecidas, que falham sem aviso por padro.
<static> unregister(serviceName)
Cancela o registro de um servio RPC.
<static> unregisterDefault()
Cancela o manipulador de servios padro.
Detalhes do mtodo
call
<static> call(targetId, serviceName, callback, var_args)
Chama um servio RPC.

Parmetros:
String targetId - Id do provedor de servios RPC. Vazio, se estiver fazendo
uma chamada ao recipiente pai.
String serviceName - Nome do servio a ser chamado.
Function, null callback - Funo de retorno de chamada (se houver) para
processar o valor retornado pela solicitao de RPC.
* var_args - Parmetros para a solicitao de RPC.
register
<static> register(serviceName, handler)
Registra um servio RPC.

Parmetros:
String serviceName - Nome do servio a ser registrado.
Function handler - Manipulador de servios.
registerDefault
<static> registerDefault(handler)
Registra um manipulador de servios padro para processar todas as chamadas RPC
desconhecidas, que falham sem aviso por padro.
Parmetros:
Function handler - Manipulador de servios.
unregister
<static> unregister(serviceName)
Cancela o registro de um servio RPC.

Parmetros:
String serviceName - Nome do servio cujo registro ser cancelado.
unregisterDefault
<static> unregisterDefault()
Cancela o manipulador de servios padro. As futuras chamadas RPC desconhecidas

falharo sem aviso.
gadgets.views
Static Class gadgets.views
Fornece operaes para lidar com Visualizaes.
Resumo do mtodo
<static> gadgets.views.View getCurrentView()
Retorna a visualizao atual.
<static> Map.<String, String> getParams()
Retorna os parmetros passados a este gadget para esta visualizao.
<static> Map<gadgets.views.ViewType, String, gadgets.views.View>
getSupportedViews()
Retorna um mapa de todas as visualizaes suportadas.
<static> requestNavigateTo(view, opt_params)
Tenta ir para uma visualizao diferente deste gadget.
Detalhes do mtodo
getCurrentView
<static> gadgets.views.View getCurrentView()
Retorna a visualizao atual.

Retorna:
gadgets.views.View A visualizao atual
getParams
<static> Map.<String, String> getParams()
Retorna os parmetros passados a este gadget para esta visualizao. No inclui todos os
parmetros de URL, somente os passados para gadgets.views.requestNavigateTo
Retorna:
Map.<String, String> O mapa de parmetros
getSupportedViews
<static> Map<gadgets.views.ViewType, String, gadgets.views.View>
getSupportedViews()
Retorna um mapa de todas as visualizaes suportadas. Associa cada gadgets.view.View ao

seu nome.
Retorna:
Map<gadgets.views.ViewType, String, gadgets.views.View>
Todas as visualizaes suportadas, associadas ao atributo dos seus nomes.
requestNavigateTo
<static> requestNavigateTo(view, opt_params)
Tenta ir para uma visualizao diferente deste gadget. Se o recipiente suportar parmetros,
ele passar os parmetros opcionais para o gadget na nova visualizao.
Parmetros:
gadgets.views.View view - A visualizao de destino
Map.<String, String> opt_params - Parmetros a serem passados ao
gadget aps a visualizao ser acessada
gadgets.views.View
Classe gadgets.views.View
Interface bsica para todos os objetos de visualizao.
Resumo do mtodo
gadgets.views.ViewType, String getName()
Retorna o nome desta visualizao.
boolean isOnlyVisibleGadget()
Retorna true (verdadeiro) se o gadget for o nico gadget visvel nesta visualizao.
Detalhes do mtodo
getName
gadgets.views.ViewType, String getName()
Retorna o nome desta visualizao.

Retorna:
gadgets.views.ViewType, String O nome da visualizao, normalmente
especificado como um gadgets.views.ViewType
isOnlyVisibleGadget
boolean isOnlyVisibleGadget()
Retorna true (verdadeiro) se o gadget for o nico gadget visvel nesta visualizao. Em uma
pgina de tela inteira ou no modo maximizado, provavelmente true (verdadeiro); em uma
pgina de perfil ou no modo painel, provavelmente false (falso).
Retorna:
boolean True se o gadget for o nico gadget visvel; caso contrrio, false
gadgets.views.ViewType
Static Class gadgets.views.ViewType
Usada pelas Visualizaes.
Resumo do campo
<static> object DASHBOARD
Uma visualizao na qual o gadget exibido em uma pequena rea, normalmente em uma
pgina com outros gadgets.
<static> object FULL_PAGE
Uma visualizao na qual o gadget exibido em um modo muito grande.
<static> object POPUP
Uma visualizao na qual o gadget exibido sozinho em uma pequena janela separada.
Detalhes do campo
DASHBOARD
<static> object DASHBOARD
Uma visualizao na qual o gadget exibido em uma pequena rea, normalmente em uma
pgina com outros gadgets. Em um contexto social, esta normalmente chamada de pgina
de perfil.
FULL_PAGE
<static> object FULL_PAGE
Uma visualizao na qual o gadget exibido em um modo muito grande. Deve ser a nica
coisa na pgina. Em um contexto social, esta normalmente chamada de pgina de tela
inteira.
POPUP
<static> object POPUP
Uma visualizao na qual o gadget exibido sozinho em uma pequena janela separada.
gadgets.skins
Static Class gadgets.skins
Fornece operaes para obter informaes de exibio sobre a skin exibida atualmente.
Resumo do mtodo
<static> String getProperty(propertyKey)
Obtm a propriedade de exibio mapeada para a chave em questo.
Detalhes do mtodo
getProperty
<static> String getProperty(propertyKey)
Obtm a propriedade de exibio mapeada para a chave em questo.

Parmetros:
String propertyKey - A chave para a qual os dados so obtidos; as chaves
esto definidas em gadgets.skins.Property
Retorna:
String Os dados
gadgets.skins.Property
Static Class gadgets.skins.Property
Todos os valores de exibio que podem ser obtidos e usados na interface do usurio dos gadgets.
Estas so as chaves suportadas para o mtodo 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 operaes para obter informaes e alterar a janela na qual o gadget colocado.
Resumo do mtodo
<static> adjustHeight(opt_height)
Ajusta a altura do gadget
<static> Object getViewportDimensions()
Detecta as dimenses internas de um frame.
<static> setTitle(title)
Define o ttulo do gadget.
Detalhes do mtodo
adjustHeight
<static> adjustHeight(opt_height)
Ajusta a altura do gadget

Parmetros:
Number opt_height - Uma altura opcional escolhida, em pixels. Se no for
especificada, tentar ajustar o gadget ao seu contedo.
getViewportDimensions
<static> Object getViewportDimensions()
Detecta as dimenses internas de um frame. Para obter mais informaes consulte:

http://www.quirksmode.org/viewport/compatibility.html.
Retorna:
Object Um objeto com propriedades de largura e altura.
setTitle
<static> setTitle(title)
Define o ttulo do gadget.

Parmetros:
String title - O ttulo escolhido

Documentacao - OpenSocial PDF

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Documentacao - OpenSocial PDF

Enviado por

Direitos autorais:

Formatos disponíveis

A web fica melhor com os relacionamentos

Muitos sites, uma API

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

Em que consiste um Gadget?

Definio das preferncias do usurio

As preferncias do usurio que so transformadas em controles da interface de usurio do gadget

// Set the background color according to the mycolor userpref

// Display a greeting based on the myname userpref

// If the "Show Photo?" checkbox is checked, display photo.

Consulte a Referncia para obter uma lista de todos os atributos de <UserPref>.

Variveis de substituio de preferncias do usurio

Voc pode ver outro exemplo semelhante na amostra de preferncias do usurio.

Definio das preferncias do gadget

Os usurios do seu gadget no podem alterar esses atributos.

Lembre-se: Gadgets so pblicos

Seleo do tipo de contedo

O tipo de contedo determina:

// The gadget version of ROT13.

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

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

// if you don't have to wrap

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

As regras para um gadget type="html" so as seguintes:

As sees CDATA so usadas para adicionar cdigos de escape a blocos de texto

Para obter uma descrio

Como transformar uma pgina da web ou aplicativo existente

Uso do tipo de dados list

Use a funo setArray(name, val) de Prefs para adicionar valores lista

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

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

Uso do tipo de dados location

Ao ler uma preferncia x de location:

Como salvar o estado

// Get user preferences

// Reset value of "counter" userpref to 0

Codificao de escape de caracteres especiais

Criao de gadgets que necessitam de login ou cookies

VERIFIQUE SUA POLTICA DE PRIVACIDADE CUIDADOSAMENTE QUANTO

Dicas de programao e depurao

Comece pelo mais simples

Estude gadgets existentes

Use o console JavaScript do Firefox

Confirme suas suposies

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

// Create Date object

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

Hospedagem atravs do Google Gadgets Editor

Comandos do menu File

Add to my iGoogle page (Adicionar minha pgina do iGoogle)

Publicao do seu gadget com o GGE

Hospedagem no Google Code

Criao de um novo projeto

Gerenciamento da altura do gadget

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

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

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

// Clear the list

// Outputs content to the div and resizes the gadget

// Tells gadget to resize itself

Definio do ttulo do gadget

Anatomia de um objeto de guias

// Callback that provides content to tabs Three and Four

// Call init function to initialize and display tabs.