Академический Документы
Профессиональный Документы
Культура Документы
A web é muito mais interessante quando você pode construir aplicativos que interajam facilmente
com seus amigos e colegas. Essa tendência também criou uma lista crescente de APIs específicas
para sites, que os desenvolvedores precisam aprender.
O serviço OpenSocial oferece um conjunto de APIs comuns para desenvolver aplicativos sociais
que irão funcionar em diversos sites. Elas possibilitam que os desenvolvedores criem aplicativos
utilizando JavaScript e HTML padrão para acessar amigos de uma rede social e atualizar feeds.
Servidor opcional
O OpenSocial foi criado com a tecnologia do Google Gadget. Você pode criar um aplicativo social
ótimo e "viral" com custos mínimos ou inexistentes de servidor. Com o Google Gadget Editor e
uma API simples de valor essencial, você pode criar um aplicativo social completo sem nenhum
servidor. É claro que você também pode hospedar seu aplicativo em seus próprios servidores, se
preferir. Em todo caso, a tecnologia de cache de gadget do Google alivia a demanda de largura de
banda, caso seu aplicativo se torne um sucesso mundial.
Seções Tópicos selecionados
"Hello, World"
Primeiros passos
Em que consiste um Gadget?
Etapas básicas
Criação dos seus próprios gadgets
Anatomia de um gadget
Seleção do tipo de conteúdo
Como transformar uma página da web ou aplicativo
existente em um gadget
Fundamentos do desenvolvimento
Uso de tipos de dados Userpref
Como salvar o estado
Criação de gadgets que necessitam de login ou cookies
Dicas de programação e depuração
Ferramentas para desenvolvedores Hospedagem através do Google Gadgets Editor
Hospedagem no Google Code
Gerenciamento da altura do gadget
Definição do título do gadget
Criação de uma interface de
Guias
usuário
MiniMessages
Flash
Uso de texto
Uso de XML
Uso de conteúdo remoto
Uso de feeds
Uso de JSON
Criação de um gadget localizado
Internacionalização Pacotes de mensagens
Uso de pacotes de mensagens em um gadget
Gadgets em idiomas diferentes do Onde posso encontrar gadgets que não sejam em inglês?
inglês Criação de gadgets em idiomas diferentes do inglês
Onde posso colocar meu gadget?
Publicação do seu gadget Preparação para a publicação
Publicação no diretório de conteúdo do iGoogle
Preferências do gadget
Referência das especificações de
Preferências do usuário
gadgets
Seção de conteúdo
Referência de JavaScript
Primeiros passos
Bem-vindo à API de gadgets!
Este guia do desenvolvedor é baseado na versão gadgets.* da API de gadgets JavaScript. A API
de gadgets foi inserida no namespace API JavaScript de gadgets.* para fornecer uma API mais
limpa para programação e suporte. Para saber mais sobre a API de gadgets.*, consulte a
documentação de referência aqui. Embora a API de gadgets.* tenha muita coisa em comum com
a API de gadgets antiga, também há diferenças importantes.
Atualmente apenas alguns recipientes (um recipiente é um site ou aplicativo que executa gadgets)
suportam a gadgets.* API. Para ver uma lista dos recipientes que suportam a gadgets.*
API, consulte a lista de recipientes do OpenSocial. Alguns recipientes mais antigos suportam
apenas a API de gadgets antiga. Portanto, verifique a documentação do seu recipiente específico
para saber qual API é suportada. Para saber mais sobre os tipos diferentes de gadgets e onde eles
podem ser executados, consulte a Visão geral da API de gadgets.
Este guia do desenvolvedor destina-se a pessoas que desejam usar a API para criar gadgets. Por
serem muito fáceis de criar, os gadgets são um excelente ponto de partida se você estiver
começando a aprender sobre programação da web.
“Hello, World"
O gadget mais simples tem apenas algumas linhas de código. Este gadget exibe a mensagem "Hello,
world!":
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="hello world example" />
<Content type="html">
<![CDATA[
Hello, world!
]]>
</Content>
</Module>
Etapas básicas
Aqui estão as etapas básicas que você deve seguir para criar e implementar um gadget:
1. Use qualquer editor de texto para escrever as especificações do seu gadget e guarde essas
informações em um servidor da web público.
2. Adicione seu gadget a um recipiente, como o iGoogle ou Orkut. Um recipiente é um
aplicativo ou site com a capacidade de executar gadgets.
Anatomia de um gadget
Depois de compreender como editar e publicar gadgets, você está pronto para incluir recursos mais
avançados nas especificações do seu gadget. A especificação do gadget XML é composta por 3
partes principais:
• Seção de conteúdo. A seção <Content> é onde ocorre o funcionamento mais importante
do seu gadget. É onde você especifica o tipo de gadget, a lógica de programação e,
freqüentemente, os elementos HTML que determinam a aparência do gadget.
• Preferências do usuário. A seção <UserPrefs> define os controles que permitem que os
usuários especifiquem configurações do gadget. Por exemplo, um gadget de saudações
personalizadas pode fornecer um campo de texto para o usuário especificar seu nome.
• Preferências do gadget. A seção <ModulePrefs> do arquivo XML especifica as
características do gadget, como título, autor, tamanho preferido e assim por diante.
Observação: Dentro dos atributos XML das especificações de um gadget, alguns caracteres
precisam ter um "escape" (ou seja, precisam ser codificados adequadamente) para que sejam
interpretados corretamente. Para obter mais informações, consulte Codificação de escape de
caracteres especiais.
Ao criar um gadget, comece pela seção <Content>.
Definição de conteúdo
A seção <Content> representa o "cérebro" de um gadget. A seção <Content> define o tipo de
conteúdo e contém o próprio conteúdo ou um link para conteúdo externo. A seção <Content> é
onde os atributos do gadget e as preferências do usuário são combinados à lógica de programação e
às informações de formatação para se transformarem em um gadget executável.
A maneira mais fácil de criar um gadget é simplesmente colocando HTML (e como opção,
JavaScript ou Flash) na seção <Content>. Os desenvolvedores de web experientes podem usar a
seção Seleção do tipo de conteúdo para obter outras opções relacionadas a controle de acesso,
hospedagem remota, uso de linguagens de scripts alternativas e outros tópicos. Veja aqui um
exemplo simples de gadget. Este gadget exibe uma fotografia que pode ser clicada para abrir um
álbum de fotos em uma nova página HTML:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
<Content type="html">
<![CDATA[
<div style="text-align:center"><a
id="Riggs" title="My Photo Album" target="_blank"
href="http://picasaweb.google.com/doc.examples/ShelfBoy">
<img border="0" alt="Photo"
src="http://doc.examples.googlepages.com/Riggsie-OP.jpg"
title="Click Here."></a>
</div>
]]>
</Content>
</Module>
Observe que:
• A linha 3 do arquivo contém o texto title="Preferences for __UP_myname__".
Ao executar o gadget, o valor fornecido pela preferência de usuário myname é substituído
dinamicamente por __UP_myname__.
• A preferência de usuário myname está marcada como "obrigatória". Se o usuário tentar
executar o gadget sem fornecer um valor para esse campo, a caixa de edição das preferências
de usuário permanece aberta até que um valor seja fornecido.
• A preferência de usuário mychoice possui o tipo de dados bool. Ela é exibida na interface
de usuário como uma caixa de seleção.
• A preferência de usuário mycolor possui o tipo de dados enum. A lista de EnumValues
especifica as opções que aparecem em um menu suspenso na caixa de edição das
preferências do usuário.
Aqui está o gadget completo, incluindo o JavaScript que exibe a saudação do gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Preferences for __UP_myname__" height="400"/>
<UserPref name="myname" display_name="Name" default_value="Rowan"/>
<UserPref name="myphoto" display_name="Photo"
default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
<UserPref name="mychoice" display_name="Show Photo?" datatype="bool"
default_value="true"/>
<UserPref name="mycolor" display_name="Color" default_value="Yellow"
datatype="enum" >
<EnumValue value="Red" />
<EnumValue value="Aqua" />
<EnumValue value="Lime" />
<EnumValue value="Yellow" />
<EnumValue value="Pink" />
<EnumValue value="Orange" />
<EnumValue value="White" />
</UserPref>
<Content type="html"><![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();
function displayGreeting () {
// Get current time
var today = new Date();
var time = today.getTime();
var html = "";
// Based on the time of day, display an appropriate greeting
var hour = today.getHours();
var salutation = "Afternoon";
if (hour < 12) {
salutation = "Morning";
} else if (hour > 17) {
salutation = "Evening";
}
</script>
]]>
</Content>
</Module>
Consulte a Referência de JavaScript para obter uma lista de todas as funções JavaScript.
HTML
Com o tipo de conteúdo html, o código completo normalmente reside nas especificações do
gadget. Isso inclui o XML do gadget e qualquer markup HTML e JavaScript. Quase todos os
exemplos deste guia do desenvolvedor usam o tipo de conteúdo html. Ele é o tipo mais flexível e
versátil e você deve normalmente optar por ele, a menos que esteja criando um gadget com
requisitos específicos.
O exemplo a seguir demonstra a implementação de um gadget do recurso ROT13. O ROT13
criptografa textos substituindo cada letra pela letra que está 13 posições à frente no alfabeto.
Quando o recurso ROT13 é reaplicado, ele rotaciona cada letra novamente, restaurando o texto
original.
Esta é a especificação do gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Magic Decoder"/>
<Content type="html">
<![CDATA[
<script type="text/javascript">
As seções CDATA são usadas para adicionar códigos de escape a blocos de texto
contendo caracteres que, de outra forma, seriam considerados markup. O único
separador reconhecido em uma seção CDATA é a string "]]>", que finaliza a seção
CDATA.
• Você não pode usar as tags <html>, <head>, ou <body>. Os gadgets são gerados com
suas próprias tags <html>, <head>, e <body>. Basta incluir o conteúdo que
normalmente ficaria dentro da tag <body>.
Um gadget com tipo de conteúdo html também pode fazer referência a um arquivo JavaScript
externo:
<Module>
<ModulePrefs ... />
<Content type="html"><![CDATA[
<script src="http://www.example.com/gadgets/clock/clock.js"
type="text/javascript"></script>
]]></Content>
</Module>
URL
Quando um gadget possui o tipo de conteúdo type="url", o atributo href= fornece um URL e
qualquer outro conteúdo da especificação do gadget é ignorado. Com o tipo de conteúdo url,
supõe-se que todas as informações relacionadas à interface de usuário e à lógica programática do
gadget residem no arquivo apontado pelo URL. Não se deve colocar nenhum markup HTML ou
JavaScript dentro do gadget em si. Por exemplo:
<Module>
<ModulePrefs ... />
<Content type="url" href="http://www/cgi-bin/example/gadgets/mystats.cgi" />
</Module>
O gadget acessa os valores da lista usando a função Prefs getArray(),; por exemplo:
var search_terms = prefs.getArray("mylist");
Dentro da matriz, os itens são armazenados em uma lista separada por barras verticais. Você pode
usar a função getString() de Prefs para retornar esta lista como uma única string na qual os
valores são separados pelo caractere barra vertical (|); por exemplo:
prefs.getString("mylist");
Você também pode usar uma string separada por barras verticais para definir os valores padrão de
um tipo de dados list:
<UserPref name="mylist" display_name="Add Search Terms" datatype="list"
default_value="zdnet|pc|Apple Insider"/>
</ModulePrefs>
...
prefs.setArray("mylist", ["Nokia","CNET"]);
Aqui está um exemplo simples que fornece os itens da lista digitados pelo usuário na caixa Edit
(Editar):
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="List Data Type Example"
scrolling="true"/>
<UserPref name="mylist"
display_name="Add Terms"
datatype="list" />
<Content type="html">
<![CDATA[
<div id=content_div></div>
<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();
// 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>
]]>
</Content>
</Module>
</script>
<input type=button value="Count" name="count" onClick="incrementCounter()">
<input type=button value="Reset" name="reset" onClick="resetCounter()">
]]>
</Content>
</Module>
Observação: Se for necessário armazenar diversos valores, recomendamos salvá-los em uma string
JSON.
Esse comando deve ser chamado antes da exibição de qualquer resultado na página.
• Informe os usuários. Isso pode ser feito em JavaScript, como nesta amostra de gadget
(experimente) . Você também pode integrar instruções à sua lógica de autenticação. Se
detectar o bloqueio de cookies, informe os usuários que eles devem afrouxar sua
configuração de privacidade ou experimentar um navegador diferente. Por exemplo, você
pode exibir uma mensagem como:
Seu navegador não é compatível com este site na configuração atual. Se estiver usando
o Microsoft Internet Explorer, altere sua configuração de segurança selecionando
Ferramentas > Opções da Internet. Abra a guia Privacidade, clique em Avançado e,
em seguida, clique em Ignorar manipulação automática de cookies. Em Cookies
Secundários, clique em Aceitar. Como alternativa, você pode usar outro navegador,
como o Firefox.
Ferramentas para desenvolvedores
Este documento fornece diretrizes gerais para programação, depuração e hospedagem de gadgets.
// Display date
function displayDate (){
// DEBUG: is the function getting called?
print("In displayDate function<br>");
content_html += today.toDateString();
// Write content HTML to div
document.getElementById("content_div").innerHTML = content_html;
}
Observação: Consulte MiniMessages para obter uma descrição da API de MiniMessages, que
permite modificar o comportamento e a aparência das mensagens exibidas em um gadget.
Ferramentas adicionais
As funções adicionais do Firefox descritas abaixo podem ajudá-lo a obter uma visão mais detalhada
dos seus gadgets durante o desenvolvimento:
• O Firebug fornece ferramentas de depuração e inspeção de DOM.
• O Web Developer adiciona um menu e uma barra de ferramentas ao navegador, contendo
ferramentas de desenvolvedor da web.
O comando fica disponível somente depois que o gadget é salvo (salvar faz o GGE
hospedar seu gadget). Para obter mais informações, consulte Publicação do seu
gadget com o GGE.
Delete Exibe uma lista dos seus gadgets no GGE e permite que você selecione os itens
(Excluir) que deseja excluir.
Bloqueio de um projeto
Antes de enviar arquivos, você precisa bloquear o código a partir do repositório do seu projeto no
Subversion. Para isso, são necessárias três informações: o URL do repositório (use a versão
precedida por https, e não por http), o nome de usuário e a senha. Para encontrar estas
informações, vá para a guia Source do seu projeto (http://code.google.com/p/<project-
name>/source). Ela deve conter algo como:
svn checkout https://<project-name>.googlecode.com/svn/trunk/ gadgets-test
--username <username>
Quando solicitado, digite a senha SVN que foi gerada.
Mantenha esta página aberta em um navegador para poder recuperar as informações apropriadas
conforme necessário.
Os detalhes do bloqueio atual podem variar dependendo do cliente do Subversion que você estiver
usando, mas o processo geral é o mesmo. As instruções desta seção supõem que você esteja
usando o TortoiseSVN.
Para bloquear um projeto:
1. Crie uma nova pasta no Windows Explorer e navegue para dentro da pasta.
2. Clique com o botão direito e selecione SVN Checkout... (Bloqueio no SVN).
3. Digite o URL do repositório e clique em OK. Nesta etapa, é necessário usar a versão do
URL do repositório precedida por https. Isso garante acesso de leitura e gravação. A versão
iniciada por http fornece acesso somente para leitura, e você não poderá adicionar ou enviar
arquivos.
4. O TortoiseSVN conecta-se ao servidor e tenta autenticar você. O nome de usuário e a senha
são solicitados. Digite o nome de usuário e a senha, marque a opção Save authentication
(Salvar autenticação) e clique em OK. Se o nome de usuário e a senha não forem
solicitados, volte à Etapa 3 e verifique se o URL do seu repositório começa com https (e não
com http).
Neste ponto, o cliente conecta e bloqueia todo o repositório. Pronto!
Se o bloqueio for concluído com sucesso, você verá uma nova pasta oculta, /.svn. Não modifique
nem exclua essa pasta.
Envio de arquivos
Depois de verificar seu projeto, você pode começar a adicionar novas pastas e arquivos ao diretório,
usando os comandos do Subversion. As instruções desta seção supõem que você esteja usando o
TortoiseSVN.
Para enviar um arquivo:
1. Crie um novo arquivo no diretório <project-name>.googlecode.com/svn/trunk/ e salve-o
(por exemplo, new-gadget.xml). Você pode colocar o arquivo diretamente no diretório
/trunk ou em um subdiretório de /trunk.
2. Clique com o botão direito no arquivo e selecione Add... (Adicionar...). Isso simplesmente
marca o arquivo como adicionado. Neste ponto, o arquivo ainda não foi enviado ao servidor.
Se você colocar o arquivo em um diretório que ainda não foi adicionado ao repositório,
também será necessário adicionar o diretório. Ao adicionar um diretório, todos os arquivos
dentro dele são adicionados também. As mesmas regras se aplicam para o envio de
alterações. Você não poderá enviar um arquivo ao repositório se o diretório no qual ele está
inserido não for enviado.
3. Continue editando o arquivo até que ele esteja pronto para ser enviado.
4. Quando estiver pronto para enviá-lo, clique no arquivo com o botão direito e selecione SVN
Commit... (Enviar para SVN...).
Quando solicitado, escreva uma observação opcional no log de mensagens e clique em OK. A
transferência do arquivo para o servidor é iniciada.
Quando o arquivo é transmitido para o servidor, o envio é concluído e o arquivo fica disponível
imediatamente on-line em http://<project-name>.googlecode.com/svn/trunk/new-gadget.xml. Para
apenas ler arquivos no repositório, basta usar a versão do URL do repositório que começa com http.
Dentro do seu repositório, você pode criar estruturas de diretório que serão refletidas no URL. Por
exemplo, se você adicionar e enviar um novo arquivo em /a/b/c/new-gadget.xml, o arquivo será
hospedado em http://<project-name>.googlecode.com/svn/trunk/a/b/c/new-gadget.xml.
Criação de uma interface de usuário
Este documento descreve como adicionar os diversos elementos de interface de usuário ao seu
gadget.
Para obter orientações sobre como testar a largura e a altura de um gadget, consulte Teste de largura
e altura.
Guias
Use a biblioteca de guias para adicionar uma interface de usuário com guias ao seu gadget. Para
usar guias, a especificação do seu gadget deve incluir no mínimo:
• Em <ModulePrefs>, um tag <Require feature="tabs"/> para informar ao
gadget que ele precisa carregar a biblioteca tabs.
• JavaScript para criar as guias e preenchê-las com conteúdo. Para obter mais detalhes,
consulte Como funciona.
Também é comum incluir a biblioteca setprefs para que o gadget possa armazenar sempre a
última guia selecionada pelo usuário. Assim, se o usuário sair e retornar à página, o gadget carrega a
guia armazenada. Para aproveitar este recurso, incorpore duas linhas de código na especificação do
seu gadget:
<Require feature="setprefs"/>
...
<UserPref name="selectedTab" datatype="hidden"/>
Como funciona
Use o construtor gadgets.TabSet() para criar um objeto de guias (ou seja, um objeto
contendo um conjunto de guias indexadas). Por exemplo:
// Initialize tabs, designate the tab named "Two" as
// the tab selected by default.
var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");
Depois de criar o objeto de guias, adicione as guias individuais a ele usando a função addTab().
Uma guia individual apresenta três componentes principais: um índice, um nome e um ID exclusivo
que é igual ao ID de um <div> correspondente. O <div> é o local onde o conteúdo da guia é
colocado. Se você não fornecer o recipiente de <div>, a biblioteca de guias irá gerá-lo.
O método addTab() utiliza os seguintes argumentos:
• String tabName -- Marcador da guia a ser criada.
• Object opt_params -- Objeto de parâmetro opcional. Ele pode incluir:
• contentContainer --Um elemento HTML existente para ser usado como
recipiente do conteúdo da guia. Se omitido, a biblioteca de guias cria um elemento.
• callback --função mA callback a ser executada quando a guia é selecionada.
• tooltip-- Uma descrição de dica de ferramenta que aparece quando o usuário
move o cursor do mouse sobre a guia.
• index -- É o índice no qual a guia será inserida. Se omitido, a nova guia é anexada
no final.
addTab() retorna uma string contendo o ID do DOM do recipiente da guia.
Você pode adicionar uma guia a um objeto de guias e preenchê-la com conteúdo usando uma das
maneiras descritas abaixo:
Técnica 1: Capture o ID da guia ao criá-la e use o ID para adicionar conteúdo ao <div>
correspondente da guia:
var one_Id = tabs.addTab("One");
document.getElementById(one_Id).innerHTML = "Content for tab One.";
Uma variação desta abordagem é definir o nome da guia em HTML. Por exemplo:
var one_Id = tabs.addTab('<div style="color: red; font-weight: bold; background-
color:#ccf;">Cool Tab</div>');
document.getElementById(one_Id).innerHTML = "Content for tab One.";
Técnica 2: Crie a guia e adicione um <div> correspondente à parte HTML do gadget; coloque o
conteúdo estático no <div>:
tabs.addTab("Two", "two_id");
...
</script>
<div id="two_id" style="display:none">Content for tab Two.</div>
Técnica 3: Crie a guia e adicione um <div> correspondente à parte HTML do gadget; coloque o
conteúdo estático no <div>: Use uma função de retorno de chamada para adicionar conteúdo
dinâmico ao conteúdo estático:
tabs.addTab("Three", "three_id", callback);
...
function callback(tabId) {
var p = document.createElement("p");
p.innerHTML = "This is dynamic content generated in callback.";
document.getElementById(tabId).appendChild(p);
}
...
</script>
<div id="three_id" style="display:none">This is static content for tab
Three.</div>
Técnica 4: Use a função addTab(tabName, opt_params) para adicionar uma guia por
nome. Por exemplo:
tabs.addTab("Tab", {
contentContainer: document.getElementById("domId"),
callback: func,
tooltip: "Popup description"
});
Aqui está um exemplo de gadget que mostra as maneiras diferentes de adicionar guias e preenchê-
las com conteúdo:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Tabs Demo" height="140" scrolling="true" >
<Require feature="tabs" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
// Initialize tabs, designate the tab named "Two" as
// the tab selected by default.
var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");
function init() {
// Technique #1: Capture the tab's ID when you create it, and use the ID
// to add content to the tab's corresponding <div>.
var one_Id = tabs.addTab('<div style="color: red; font-weight: bold;
background-color:#ccf;">Cool Tab</div>');
document.getElementById(one_Id).innerHTML = "Content for tab One.";
// Technique #2: Create the tab and define a corresponding <div> in the
// HTML portion of the gadget. Add static content to the <div>.
tabs.addTab("Two", {
contentContainer: document.getElementById("two_id")
});
// Technique #3: Create the tab and define a corresponding <div> in the
// HTML portion of the gadget. Add static content to the <div>.
// Use a callback function to add dynamic content to the static content.
tabs.addTab("Three", {
contentContainer: document.getElementById("three_id"),
callback: callback
});
// Technique #4: Create the tab with a tooltip message. If specified
<div>
// doesn't exist, tabs library creates one.
// Invoke callback function.
tabs.addTab("Four", {
contentContainer: document.getElementById("four_id"),
callback: callback,
tooltip: "I'm special"
});
}
Aqui está um exemplo de como mover uma guia programaticamente. Este snippet cria um link.
Quando o usuário clica no link, o gadget troca as posições da primeira e da segunda guia:
<script>
...
function switchTabs() {
tabs.swapTabs(0, 1);
}
</script>
<a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>
<script...>
Você também pode usar JavaScript para aplicar estilos CSS ao recipiente de cabeçalho das guias. A
função getHeaderContainer() retorna a tabela HTML das guias, que você pode modificar
conforme desejar.
Por exemplo, este snippet altera o tamanho da fonte e adiciona margem no alto:
var tabs = new gadgets.TabSet();
...
var table = tabs.getHeaderContainer();
table.style.fontSize = "10px";
table.style.marginTop = "15px";
Você pode personalizar o estilo dos cabeçalhos de guias individuais, obtendo os elementos da guia
individual e modificando suas propriedades. Veja um exemplo que torna o estilo da primeira guia
exclusivo:
var tabs = new gadgets.TabSet();
tabs.addTab("Unique");
...
var firstTab = tabs.getTabs()[0].getNameContainer();
firstTab.style.backgroundColor = "#999999";
firstTab.style.color = "#ffffff";
MiniMessages
Uma MiniMessage é uma mensagem temporária exibida aos usuários dentro de um gadget. As
MiniMessages foram criadas para serem eliminadas programaticamente ou pelo usuário. Os tipos
básicos de MiniMessages são:
• Mensagens dispensáveis que os usuários removem clicando em um [x].
• Mensagens de temporizador que desaparecem depois de decorrido um determinado período
de tempo em segundos.
• Mensagens estáticas que devem ser dispensadas programaticamente.
Para usar MiniMessages, a especificação do seu gadget deve incluir:
• Em <ModulePrefs>, uma tag <Require feature="minimessage"/> para
informar ao gadget que ele precisa carregar a biblioteca de MiniMessages.
• Funções JavaScript descrevendo o comportamento da MiniMessage. Consulte a Referência
para obter uma lista completa das funções da biblioteca de MiniMessages.
Veja alguns dos motivos para usar MiniMessages:
• Promoção: Você pode usar as MiniMessages para exibir uma mensagem promocional no
gadget.
• Status: Muitos gadgets obtêm e carregam dados em segundo plano. Você pode usar
MiniMessages para exibir "Carregando..." ou outras mensagens relacionadas a status.
• Depuração/erro: Se um gadget encontrar um erro, ele pode usar as MiniMessages para
notificar o usuário, em vez de falhar em silêncio.
• Outros: Dependendo do tipo de gadget (por exemplo, calendário, eBay), você pode exibir
notificações para os usuários. Como as MiniMessages são pequenas e dispensáveis, use-as
para comunicar informações especiais.
Como funciona
As etapas básicas da adição de uma MiniMessage ao gadget são simples:
1. Importe a biblioteca de MiniMessages:
<Require feature="minimessage"/>
Na maioria dos casos, você criará um único objeto global que possa ser acessado por todos os
escopos.
3. Crie uma nova MiniMessage com um texto:
msg.createDismissibleMessage("Please close me when you're done reading me.");
Isso adiciona no início do gadget uma mensagem pré-formatada dispensável com um [x] associado
a ela. Quando os usuários clicam no [x], a mensagem é fechada.
Pronto! Você criou um dos diversos tipos de mensagens dispensáveis.
<div id="messageBox"></div>
<script type="text/javascript">
// In the constructor, state that messages should be be displayed
// in the messageBox <div> rather than at the top of the gadget.
var msg = new gadgets.MiniMessage(__MODULE_ID__,
document.getElementById("messageBox"));
msg.createDismissibleMessage("I'm the first message.");
msg.createDismissibleMessage("I'm the second message.");
msg.createDismissibleMessage("I'm at the bottom.");
</script>
<script type="text/javascript">
var msg = new gadgets.MiniMessage(__MODULE_ID__);
// Pass the HTML element to createDismissableMessage() to indicate
// where the message should be displayed.
msg.createDismissibleMessage(document.getElementById("status"));
</script>
</script>
Criação de uma mensagem de temporizador
Uma mensagem de temporizador é pré-formatada para desaparecer depois de decorrido o período
de tempo especificado. A função createTimerMessage() aceita dois parâmetros: uma string
de mensagem e um número indicando a duração, em segundos, da exibição da mensagem. Por
exemplo:
var msg = new gadgets.MiniMessage(__MODULE_ID__);
msg.createTimerMessage("I'm going to disappear in 5 seconds.", 5);
Observação: Este exemplo mostra a forma correta de alterar totalmente a cor de fundo de uma
mensagem. A cor de fundo não será totalmente alterada se apenas a configuração da cor de fundo do
<div> que contém a mensagem for alterada.
.mmlib_table__MODULE_ID__ {
background-color: #000066;
color: #ffffff;
}
</style>
<script...>
Flash
Use a biblioteca flash para incorporar um filme Flash (especificamente, um arquivo .swf) em
seu gadget. Para incorporar conteúdo Flash, a especificação do seu gadget deve incluir no mínimo:
• Em <ModulePrefs>, uma tag <Require feature="flash"/> para informar ao
gadget que ele precisa carregar a biblioteca flash.
• Uma chamada a gadgets.flash.embedFlash() para incorporar um arquivo .swf
no gadget e exibi-lo em um local designado. Para usar esse recurso, todos os recursos devem
estar em um único arquivo .swf.
A biblioteca flash inclui as seguintes funções:
Função Descrição
Incorpora o arquivo .swf especificado por swf_url e o
exibe no gadget no local especificado por swf_container.
O parâmetro opt_params é um objeto opcional que pode
conter qualquer parâmetro html válido.
gadgets.flash.embedCach
Injeta um arquivo Flash com cache na árvore DOM. Os
edFlash(swf_url,
parâmetros e o valor retornado são os mesmos do método
swf_container,
embedFlash().
swfVersion, opt_params)
gadgets.flash.getMajorV Retorna a principal versão do Flash Player, ou zero se o Flash
ersion() Player não for detectado.
Exemplo de Flash
Quando você clica em algum botão deste exemplo de gadget, ele reproduz o arquivo .swf
correspondente. Quando você clica em Stop, o gadget exibe uma fotografia estática.
Aqui está a especificação do gadget do exemplo:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Trevor Does Tricks" height="300">
<Require feature="flash" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<style type="text/css">
input.mybutton
{
background-color:#FFCC99;
border-style:solid;
border-color:#000000;
font-family:Comic Sans MS,sans-serif;
font-size:14px;
}
</style>
<script type="text/javascript">
// Display still photo.
function showPhoto() {
document.getElementById("flashcontainer").innerHTML = "<img
src='http://doc.examples.googlepages.com/Trevor.JPG' />";
}
// Play .swf file for specified trick.
function doTrick(trick) {
// The URL for the .swf file that shows the specified trick.
var url = "http://doc.examples.googlepages.com/Trevor-"+trick+".swf";
Introdução
A capacidade de combinar informações de diversas fontes de maneiras novas ou de fornecer meios
alternativos de interação com informações existentes é um dos recursos mais empolgantes
disponíveis para os gadgets. A API de gadgets permite que o gadget obtenha remotamente conteúdo
de outros servidores e páginas da web e realize operações com esse conteúdo.
A API de gadgets fornece a função makeRequest(url, callback, opt_params) para
recuperação e operação com conteúdo da web remoto. Ela aceita os seguintes argumentos:
• String url - O URL no qual o conteúdo está localizado
• Function callback - A função a ser chamada com os dados do URL após a obtenção
• Map.<gadgets.io.RequestParameters, Object> opt_params - Parâmetros
adicionais a serem passados para a solicitação
O argumento opt_params permite especificar:
• O tipo de conteúdo da solicitação (atualmente suportados: TEXT, XML e JSON)
• O tipo de método da solicitação (POST ou GET)
• Qualquer cabeçalho que você deseje incluir na solicitação
• O tipo de autorização (suportado atualmente: NONE ou SIGNED)
Para ler mais sobre os parâmetros opcionais que podem ser passados, consulte o artigo Introdução à
função makeRequest.
Observação: Você não pode usar makeRequest() com gadgets type="url".
Independentemente do tipo de dados sendo obtidos, as chamadas a makeRequest()
compartilham as mesmas características:
• Seu primeiro parâmetro é um URL usado para obter o conteúdo remoto.
• Seu segundo parâmetro é uma função de retorno de chamada, usada para processar os dados
retornados.
• Elas são assíncronas, ou seja, todo o processamento deve ocorrer dentro da função de
retorno de chamada. Um retorno de chamada é uma função passada como parâmetro (na
forma de uma referência de função) a outra função. Os retornos de chamada fornecem aos
desenvolvedores um "gancho" que pode ser conectado a uma estrutura em execução para
realizar processamentos.
• Eles não têm valores de retorno porque são retornados imediatamente, e as funções de
retorno de chamada a eles associadas são chamadas sempre que a resposta é retornada.
Por exemplo, pense no seguinte snippet de código, que obtém conteúdo remoto em forma de texto.
Este código obtém o texto HTML da página google.com da web e exibe os primeiros 400
caracteres:
function getHtml() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
var url = "http://www.google.com";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
//obj.text contains the text of the page that was requested
var str = obj.text;
var html = str.substr(0,400);
document.getElementById('content_div').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getHtml);
Este exemplo ilustra os princípios básicos por trás do funcionamento da função makeRequest():
1. Quando a função makeRequest() é chamada, a API de gadgets faz uma solicitação
HTTP GET assíncrona ao URL passado à função (neste exemplo, o URL é
http://www.google.com).
2. makeRequest() é retornada imediatamente e chama a função de retorno de chamada
posteriormente (neste exemplo, denominada response()), quando todo o conteúdo é
obtido. Isso significa que você deve colocar todos os códigos dependentes dentro da função
de retorno de chamada ou dentro de funções chamadas pela função de retorno de chamada.
3. makeRequest() retorna um objeto JavaScript com a seguinte estrutura:
{
data : <parsed data, if applicable>,
errors : <any errors that occurred>,
text : <raw text of the response>
}
Este objeto é fornecido somente como o argumento para a função de retorno de chamada. A função
de retorno de chamada executa algumas operações com os dados retornados. Normalmente, ela
extrai partes dos dados, combina-os com markup HTML e exibe o HTML resultante no gadget.
Uso de texto
Aqui está um exemplo que obtém dados de um arquivo CSV (valores separados por vírgulas) e os
utiliza para preencher uma lista de contatos pessoais. Ele mostra como definir o tipo do conteúdo
obtido nos parâmetros opcionais. Na função response(obj) de retorno de chamada, o valor do
texto é extraído de obj usando obj.text:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch Text Example"/>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
// This example fetches data from a CSV file containing contact information.
In the CSV file,
// each record consists of a name, email address, and phone number.
function getContacts() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-
gadgets/Contacts.csv";
gadgets.io.makeRequest(url, response, params);
};
// Callback function to process the response
function response(obj) {
var responseText = obj.text;
// Set CSS for div.
var html = "<div style='padding: 5px;background-color: #FFFFBF;font-
family:Arial, Helvetica;"
+ "text-align:left;font-size:90%'>";
</script>
]]>
</Content>
</Module>
Uso de XML
O DOM (Document Object Model, Modelo de objeto de documento) é uma API para navegação em
documentos HTML e XML. Você pode usar makeRequest() para recuperar um documento
XML como um objeto DOM. Você pode operar o objeto obtido usando funções DOM JavaScript
padrão. Normalmente, isso significa extrair os dados desejados do arquivo XML, combiná-los com
markup HTML e CSS e exibir o HTML resultante em seu gadget.
Com o DOM, o conteúdo da web é analisado em uma árvore de nós. Por exemplo, veja o snippet de
HTML abaixo:
<a href="http://www.google.com/">Google's <b>fast</b> home page.</a>
Para acessar os dados de um objeto DOM você "percorre a árvore", usando funções DOM para
navegar pelos relacionamentos de nó pai-filho e chegar aos dados necessários.
Exemplo
O arquivo XML abaixo contém dados para uma série de itens de café da manhã. O primeiro nó-pai
é menu, que possui diversos nós-filho food. O nó menu também contém um nó de atributo:
title="Breakfast Menu". Cada nó food possui os nós-filho name, price, description e calories.
Os nós name, price e calories contêm seus próprios nós-filho de texto. Cada nó description contém
um nó-filho CDATA. CDATA é um tipo distinto de nó. As seções CDATA são usadas para adicionar
códigos de escape a blocos de texto contendo caracteres (como sinais de menor e maior) que, de
outra forma, seriam considerados markup. O único separador reconhecido em uma seção CDATA é
a string "]]>", que finaliza a seção CDATA.
<?xml version="1.0" encoding="UTF-8" ?>
<menu title="Breakfast Menu">
<food>
<name>Early Bird Breakfast</name>
<price>$3.95</price>
<description><![CDATA[<div style="color:purple; padding-left:25px;">Two
eggs any style with your choice of bacon
or sausage, toast or English muffin.</div>]]></description>
<calories>450</calories>
</food>
<food>
<name>Chocolate Chip Belgian Waffles</name>
<price>$7.95</price>
<description><![CDATA[<div style="color:purple; padding-left:
25px;">Chocolate chip Belgian waffles covered with
chocolate syrup and whipped cream.</div>]]></description>
<calories>900</calories>
</food>
…
</menu>
O exemplo de gadget a seguir usa este arquivo XML como fonte de dados. Ele exibe um menu de
café da manhã e permite que os usuários definam um limite de calorias. Ele exibe qualquer caloria
acima do limite especificado em vermelho. Os usuários também podem selecionar se desejam exibir
as descrições de cada item do café da manhã.
O código a seguir ilustra como percorrer a árvore DOM para extrair os dados dos diferentes tipos de
nó, e como combiná-los a markup HTML e CSS para serem exibidos no gadget de menu de café da
manhã.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch XML" scrolling="true"/>
<UserPref
name="mycalories"
display_name="Calorie limit"
default_value="800"/>
<UserPref
name="mychoice"
display_name="Show Descriptions"
datatype="bool"
default_value="false"/>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
// get prefs
var prefs = new gadgets.Prefs();
// Calorie limit set by user
var calorieLimit = prefs.getString("mycalories");
// Indicates whether to show descriptions in the breakfast menu
var description = prefs.getBool("mychoice");
function makeDOMRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.DOM;
var url = "http://gadget-doc-
examples.googlecode.com/svn/trunk/opensocial-gadgets/breakfast-data.xml";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
// Start building HTML string that will be displayed in <div>.
// Set the style for the <div>.
var html = "<div style='padding: 5px;background-color: #ccf;font-
family:Arial, Helvetica;"
+ "text-align:left;font-size:90%'>";
// Set style for title.
html +="<div style='text-align:center; font-size: 120%; color: yellow; "
+ "font-weight: 700;'>";
// obj.data contains a Document DOM element corresponding to the
// page that was requested
var domdata = obj.data;
// Display menu title. Use getElementsByTagName() to retrieve the <menu>
element.
// Since there is only one menu element in the file,
// you can get to it by accessing the item at index "0".
// You can then use getAttribute to get the text associated with the
// menu "title" attribute.
var title =
domdata.getElementsByTagName("menu").item(0).getAttribute("title");
// 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 += " ";
html += price;
html += " - ";
// If "calories" is greater than the user-specified calorie limit,
// display it in red.
if(calories > calorieLimit) {
html += "<font color=#ff0000>";
html += calories + " calories";
html += " </font>";
}
else
html += calories + " calories";
html += "<br>";
// If user has chosen to display descriptions
if (description==true)
{
html += "<i>" + data + "</i><br>";
}
}
// Close up div
html += "</div>";
document.getElementById('content_div').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(makeDOMRequest);
</script>
]]>
</Content>
</Module>
Esta amostra de código ilustra quatro das principais funções usadas para interagir com dados DOM:
• getElementsByTagName(tagname)-- Para um documento DOM, retorna uma matriz dos nós
de elemento cujos nomes correspondem a tagname. Você pode recuperar todos os nós de
elemento de um arquivo usando o caractere curinga (*), por exemplo:
response.getElementsByTagName("*").
• getElementById(id)-- Para um documento DOM, recupera um único nó por id.
• getAttribute(attrib)-- Para um nó de elemento, retorna o atributo attrib. Por exemplo:
response.getElementsByTagName("menu").item(0).getAttribute("title").
• attributes -- Para um nó de elemento, retorna uma matriz dos atributos do nó.
Este exemplo mostra somente algumas das diferentes funções para a navegação em uma árvore
DOM. Experimente algumas das outras funções que você usar, como lastChild, nextSibling,
previousSibling e parentNode.
nodeType: 1
nodeValue : null
Alguns navegadores exibem todos os
espaços em branco de um documento como
nodeName: nós de texto. Assim, seu objeto DOM irá
#text conter nós de texto "vazios". Isso poderá
Texto. Um nó de texto é gerar resultados inesperados quando você
text sempre inserido em um nó nodeType: 3 percorrer a árvore. Para solucionar esse
de elemento. Ele é filho do problema, basta filtrar os nós de texto que
elemento. nodeValue: contêm somente o caractere de nova linha.
Qualquer texto Ou você pode realizar uma manipulação
inserido no nó. mais robusta. Para ler mais sobre este
tópico, consulte Espaços em branco no
DOM.
nodeName: O
valor à esquerda
do par de
atributo. Se o Embora os atributos sejam nós e estejam
atributo for inseridos em nós de elemento, eles não são
Um par de chave-valor que title=”my nós-filho do elemento. Eles são herdados
fornece informações document”, da interface de Node, mas o DOM não os
adicionais sobre um nó de nodeName será considera parte da árvore DOM. Isso
elemento (por exemplo, title. significa que, embora você possa usar
atributo
title=”my document”). Um muitas das funções de nó com os nós de
atributo é inserido em um nodeType: 2 atributo (como nodeName, nodeValue e
nó de elemento, mas não é nodeType), não é possível acessar nós de
filho do nó de elemento. nodeValue: O atributo usando as funções de navegação da
valor à direita do árvore DOM. Para acessar os atributos, use
par de atributo as funções attributes e getAttribute(attrib).
(neste exemplo,
“my
document”).
Uma seção na qual o
conteúdo não é
manipulado ou
nodeName:
interpretado. As seções
#cdata-section
CDATA são usadas para
adicionar códigos de
nodeType: 4
escape a blocos de texto O texto da seção CDATA tem seu próprio
CDATA contendo caracteres que, markup. Isso pode afetar o modo como
nodeValue:
de outra forma, seriam você irá incorporá-lo ao gadget.
Texto e markup
considerados markup. O
dentro dos
único separador
separadores
reconhecido em uma seção
CDATA.
CDATA é a string "]]>",
que finaliza a seção
CDATA.
Outros recursos
• Núcleo DOM W3C
• Tutorial do DOM JavaScript
Uso de feeds
Adicione um feed à sua página do iGoogle digitando seu URL no formulário Add by URL
(Adicionar por URL) do diretório de conteúdo. Esse formulário utiliza o suporte integrado da API
de gadgets para criar um gadget para o feed e adicioná-lo ao iGoogle. É fácil de usar, mas não
permite qualquer personalização do conteúdo ou da exibição. Além disso, você não pode usá-lo com
outros recipientes.
Para manipular feeds de maneira mais sofisticada, use o método makeRequest(). Embora a
especificação dos gadgets para makeRequest() inclua um tipo de conteúdo FEED, este recurso
ainda não é suportado por nenhum recipiente. Como alternativa, você pode processar um feed
usando o tipo de conteúdo DOM, como mostrado abaixo.
O exemplo a seguir ilustra como usar a função makeRequest() para obter um feed e exibir
partes de seus dados em um gadget. Aqui está o gadget. Ele permite que os usuários especifiquem:
• O número de entradas exibidas
• Se o gadget exibirá a data e um resumo de cada entrada
// Get userprefs
var prefs = new gadgets.Prefs();
var showdate = prefs.getBool("show_date");
var summary = prefs.getBool("show_summ");
var entries = prefs.getInt("num_entries");
function makeDOMRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.DOM;
var url = "http://groups.google.com/group/Google-Gadgets-
API/feed/rss_v2_0_msgs.xml";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
// obj.data contains a Document DOM element corresponding to the
// page that was requested
var domdata = obj.data;
// Display the field title
var title = getFeedTitle(domdata);
var html = "<div><b>" + title + "</b></div>";
// Loop through child nodes. Extract data from the text nodes that are
// the children of the associated name, price, and calories element
nodes.
for (var j = 0; j < nodeList.length ; j++) {
var node = nodeList.item(j);
if (node.nodeName == "title") {
var name = node.firstChild.nodeValue;
}
if (node.nodeName == "link")
{
var link = node.firstChild.nodeValue;
}
if (node.nodeName == "pubDate")
{
var date = node.firstChild.nodeValue;
}
if (node.nodeName == "description")
{
var desc = node.firstChild.nodeValue;
}
}
html += "<div>"
+ "<a target='_blank' href='" + link + "'>"
+ name
+ "</a>";
if (showdate==true)
{
html += "<br><i>" + date + "</i>";
}
if (summary==true)
{
html += "<br><i>" + desc + "</i>";
}
html += "</div";
}
document.getElementById('content_div').innerHTML = html;
};
// Return the feed title. This function just grabs the first element named
"title" in the feed.
function getFeedTitle(dat) {
var titles = dat.getElementsByTagName("title");
var feed_title = titles.item(0).firstChild.nodeValue;
return feed_title;
};
gadgets.util.registerOnLoadHandler(makeDOMRequest);
</script>
]]>
</Content>
</Module>
Uso de JSON
Use o tipo de conteúdo JSON para obter conteúdo com codificação JSON em forma de objeto
JavaScript.
O aplicativo descrito abaixo obtém o conteúdo de uma página PHP de amostra que contém a
seguinte string em codificação JSON:
{"validated":"This request was spoofed","query":
[],"url":"http:\/\/graargh.returnstrue.com\/buh\/fetchme.php","signature":"","si
gnature_len":1}
Ao obter conteúdo da página PHP contendo esta string, o valor retornado é um objeto JavaScript
contendo pares de chave e valor (ou seja, uma matriz associativa). Esta amostra recupera o objeto e
imprime os pares de chave e valor nele contidos:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch JSON 8">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
function makeJSONRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.JSON;
// This URL returns a JSON-encoded string that represents a JavaScript
object
var url = "http://graargh.returnstrue.com/buh/fetchme.php";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
var jsondata = obj.data;
var html = "<strong>Values: </strong><br /><br />";
// Returned JS object can be processed as an associative array
for (var key in jsondata) {
var item = jsondata[key];
html += key + ": ";
html += item + "<br />";
}
document.getElementById('content_div').innerHTML = html;
};
makeJSONRequest();
</script>
]]>
</Content>
</Module>
Atualização do cache
Se estiver usando a função makeRequest() para obter conteúdo atualizado mais de uma vez por
hora, como dados de feeds, pode ser que você não obtenha as últimas atualizações. Isso ocorre
porque seus resultados são armazenados em cache para tornar a execução do gadget mais rápida. Se
você quiser ter certeza de que o gadget obteve os dados mais recentes, use o parâmetro
refreshInterval para ignorar o cache e forçar uma atualização no intervalo que você
especificar. Em outras palavras, o cache é atualizado a cada X segundos, onde X =
refreshInterval.
Como padrão, as chamadas à função makeRequest são armazenadas em cache. No exemplo
abaixo, a função wrapper usa os mesmos parâmetros da chamada à função makeRequest, mas
aceita outro parâmetro denominado refreshInterval, que permite especificar a duração do
cache.
function makeCachedRequest(url, callback, params, refreshInterval) {
var ts = new Date().getTime();
var sep = "?";
if (refreshInterval && refreshInterval > 0) {
ts = Math.floor(ts / (refreshInterval * 1000));
}
if (url.indexOf("?") > -1) {
sep = "&";
}
url = [ url, sep, "nocache=", ts ].join("");
gadgets.io.makeRequest(url, response, params);
}
O uso de cache tem uma finalidade específica. Tome cuidado para não atualizar o cache com muita
freqüência, para não prejudicar o desempenho. O uso de cache agiliza a obtenção de dados. Ele
também reduz a carga sobre os servidores de terceiros que hospedam o conteúdo remoto. Evite
desativar o cache completamente (o que é feito usando-se o valor refreshInterval: 0). Se o
gadget estiver recebendo milhões de visualizações de página por dia e enviando milhões de
solicitações a estes servidores, desativar o cache não apenas afetará negativamente o desempenho
do gadget de maneira negativa, mas também poderá sobrecarregar os servidores que fornecem
dados ao seu gadget.
Como o padrão é atualizar o conteúdo a cada hora, o ideal é especificar um intervalo menor que
uma hora. O intervalo recomendado para refreshInterval é mais de 60 e menos de 3.600.
Gadgets e internacionalização (i18n)
Este documento descreve como criar gadgets que possam ser facilmente localizados para um
público internacional.
Introdução
A API de gadgets oferece uma maneira fácil de você disponibilizar seu gadget para um público
internacional. É simples: basta estruturar o gadget de forma que o texto visível para o usuário
(qualquer texto que será traduzido) esteja em pacotes de mensagens separados do gadget. Assim,
qualquer tradutor de terceiros pode traduzir suas strings e criar novos pacotes de mensagens
específicos ao local, os quais você pode adicionar à especificação do seu gadget. Dessa forma, seu
gadget fica disponível para um novo grupo de usuários.
Para ler mais sobre como criar gadgets em idiomas diferentes do inglês, consulte Gadgets em
idiomas diferentes do inglês.
Conceitos básicos
Este documento refere-se à internacionalização (i18n) e à localização (l10n):
• Internacionalizar significa estruturar aplicativos de forma a possibilitar sua localização.
• Localizar significa fazer um aplicativo funcionar para um mercado específico, como
canadenses francófonos.
Para a finalidade deste documento, o “perfil de localização” de um usuário consiste em dois
componentes: um país (com base no domínio do usuário) e um idioma de interface preferido pelo
usuário (consulte a seção Teste para obter mais detalhes).
Exemplo
O exemplo de gadget usado neste documento exibe a mensagem “Hello World,” mostrada aqui em
chinês:
Neste exemplo, o menu suspenso de preferências do usuário permite que o usuário especifique uma
cor de fonte para a mensagem “Hello World”. Os nomes das cores que aparecem no menu são
arquivos externos definidos (pacotes de mensagens). O idioma no qual o menu será exibido
depende do perfil de país/idioma do usuário. Se um usuário com perfil inglês executar este gadget, o
texto aparecerá em inglês. Veja aqui a aparência da versão em inglês do exemplo, com o menu
suspenso userprefs sendo exibido:
Você pode ver a especificação do gadget Hello World aqui.
Pacotes de mensagens
O elemento principal da estratégia de internacionalização de gadgets são os pacotes de mensagens.
Os pacotes de mensagens são arquivos XML que contêm as strings traduzidas para um dado local.
Cada string é identificada por um nome exclusivo e esse mesmo nome é usado em todos os pacotes.
Os pacotes de mensagens podem ser hospedados por qualquer URL e compartilhados entre
aplicativos. Cada pacote de mensagens contém somente um local.
Os pacotes de mensagens têm o seguinte formato:
<messagebundle>
<msg name="hello_world">
Hello World.
</msg>
<msg name="color">Color</msg>
<msg name="red">Red</msg>
<msg name="green">Green</msg>
<msg name="blue">Blue</msg>
<msg name="gray">Gray</msg>
<msg name="purple">Purple</msg>
<msg name="black">Black</msg>
</messagebundle>
Veja abaixo os campos que você pode incluir em um arquivo de pacote de mensagens:
• messagebundle: Um grupo de mensagens para tradução.
• msg: Um único item de conteúdo traduzível, normalmente um marcador, frase ou parágrafo.
• msg name: Um ID legível para cada mensagem.
Convenções de nomenclatura
A convenção é nomear os pacotes de mensagens como descrito abaixo:
<language>_<country>.xml
Onde não houver um valor específico ao idioma ou ao país, a convenção é usar "ALL". Por
exemplo, o arquivo de_ALL.xml aplica-se a todas as pessoas que falam alemão,
independentemente de seu país. O pacote de mensagens ALL_ALL.xml é o arquivo usado como
padrão.
Melhores práticas
Não há requisitos rígidos a serem seguidos nas convenções de nomenclatura dos pacotes de
mensagem. O gadget usa os atributos lang e country de <Locale> para identificar o arquivo
de pacote de mensagens correto para o perfil do usuário. Ele não usa o nome do pacote de
mensagens em si.
Entretanto, embora a API de gadgets ofereça muita flexibilidade, recomendamos que você siga estas
orientações:
• Sempre forneça um pacote de mensagens ALL_ALL.xml ao lidar com mensagens padrão.
• Especifique um local por idioma. Ou seja, use fr_ALL, de_ALL e assim por diante.
• Se precisar ignorar locais específicos, use pacotes de mensagens idioma-país. Por exemplo,
se quiser fornecer um pacote de mensagens em inglês canadense para ignorar en_ALL, use
en_CA e não ALL_CA.
Durante a execução, o gadget usa o pacote de mensagens que melhor corresponda ao perfil do
usuário.
Os valores válidos para o idioma são códigos de idioma ISO639-1 com dois dígitos e os valores
válidos para o país são códigos ISO 3166-1 alfa-2.
Consulta às mensagens
Os pacotes de mensagens possuem um recurso de consulta. Com o recurso de consulta às
mensagens, o gadget tenta usar o pacote de mensagens que melhor corresponda ao país do usuário e
ao idioma de preferência da IU (especificado no URL). Se o gadget não encontrar uma
correspondência exata, ele "consulta" todos os pacotes de mensagens para encontrar a
correspondência mais próxima.
Com a consulta às mensagens, você pode usar mensagens "padrão" (normalmente especificadas em
ALL_ALL.xml), caso não haja um pacote disponível para um determinado local.
Por exemplo, imagine que o seu gadget contém a seguinte especificação:
<Locale messages="http://x.com/ALL_ALL.xml"/>
<Locale lang="de" messages="http://x.com/de_ALL.xml"/>
<Locale lang="de" country="DE" messages="http://x.com/de_DE.xml"/>
<Locale lang="de" country="US" messages="http://x.com/de_US.xml"/>
Como esses arquivos seriam usados? Suponha que o domínio da sua usuária é nos EUA
(http://www.google.com), mas o idioma de preferência é o alemão. Ela verá as mensagens do
arquivo de_US.xml. Se não houver uma mensagem específica neste arquivo, ela verá a mensagem
de de_ALL.xml, e finalmente, de ALL_ALL.xml.
Um usuário da Alemanha usando a IU em alemão começará por de_DE.xml, um usuário da Suíça
usando a IU em alemão começará por de_ALL.xml e um usuário da Suíça usando a IU em francês
começará por ALL_ALL.xml.
Cada mensagem possui uma string exclusiva de nome para identificá-la. Por exemplo, nesta
mensagem:
<msg name="red">Rot</msg>
o nome exclusivo da mensagem é “red” e a string traduzida que aparece no gadget (no menu
suspenso userprefs) é “Rot”, a palavra em alemão para “vermelho”. Aqui está a string da mensagem
equivalente em inglês no pacote de mensagens ALL_ALL.xml:
<msg name="red">Red</msg>
A especificação do gadget “Hello World” usa a variável de substituição __MSG_ para indicar onde
o valor do pacote de mensagens apropriado deve ser substituído. Por exemplo, esta sentença XML
da especificação do gadget “Hello World” é usada para adicionar um item de menu ao menu
suspenso “Color” (Cor) de userprefs:
<EnumValue value="Red" display_value="__MSG_red__" />
Esta linha, na verdade, diz “Vá para o pacote de mensagens que melhor corresponda ao perfil de
país/idioma do usuário, obtenha o valor da mensagem com nome ‘red’ e use-o no lugar de
__MSG_red__”. É assim que as preferências do usuário do menu suspenso do exemplo “Hello
World” são preenchidas com nomes de cores (aqui, mostrado em alemão):
Como alternativa, use a função getMsg() de userprefs. Essa função pode ser usada para acessar
todas as mensagens dos pacotes de mensagens e não apenas as mensagens relacionadas a userprefs.
Entretanto, é necessário chamar esta função para um objeto Prefs. Por exemplo:
var prefs = new gadgets.Prefs();
prefs.getMsg(“red”);
Entretanto, suponha que você criou um gadget incluindo pacotes de mensagens para idiomas da
esquerda para a direita e vice-versa. Como você faria seu gadget suportar ambos os casos? Aqui está
um exemplo de gadget que altera a direção dinamicamente, de acordo com o pacote de mensagens
que é carregado para o local de um usuário. Este gadget possui pacotes de mensagens para dois
idiomas da direita para a esquerda, hebraico (iw) e árabe (ar):
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="BIDI Hello World">
<Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/>
<Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/
>
<Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/
>
<Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/
>
<Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/
>
<Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/
>
<Locale lang="iw" messages="http://doc.examples.googlepages.com/iw_ALL.xml"
language_direction="rtl"/>
<Locale lang="ar" messages="http://doc.examples.googlepages.com/ar_ALL.xml"
language_direction="rtl"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div style="margin-__BIDI_START_EDGE__:30px;"><h2>__MSG_hello_world__</h2></
div>
]]>
</Content>
</Module>
Para este gadget, suponha que o idioma de preferência do usuário seja árabe. A linha <Locale
lang="ar" messages="http://.../ar_ALL.xml"
language_direction="rtl"/> diz "para árabe, exibir o texto do pacote de mensagens
ar_ALL.xml e definir a direção do gadget como rtl." A direção para o hebraico também será da
direita para a esquerda. Para outros idiomas, a direção do é implicitamente definida com o padrão
ltr (esquerda para a direita).
A linha <div style="margin-__BIDI_START_EDGE__:
30px;"><h2>__MSG_hello_world__</h2></div> diz "quando o gadget estiver em
modo da esquerda para a direita, deslocar o texto 30 pixels em relação à margem esquerda. Quando
o gadget estiver em modo da direita para a esquerda, deslocar o texto 30 pixels em relação à
margem direita". Por exemplo, se a configuração do navegador do usuário for árabe (direita para a
esquerda), a substituição realizada na execução ficará assim:
<div style="margin-right:30px;"><h2> بالعالx
<أهل/h2></div>
Esta tabela lista as variáveis de substituição BIDI e seus possíveis valores. Seus valores sempre são
baseados na direção do próprio gadget. Ou seja, estas variáveis são designadas para serem usadas
em conjunto com a configuração de <Locale... language_direction="...">. Você
pode usas as variáveis em qualquer parte dentro do corpo do gadget.
Variável Descrição
Esta variável representa o lado
do gadget que é o ponto inicial
da exibição do conteúdo. O
valor será "left" (esquerda)
__BIDI_S quando o gadget estiver em
TART_EDG modo LTR e "right" (direita)
E__ quando o gadget estiver em
modo RTL. O gadget acima é
um exemplo de como usar esta
variável para a configuração de
margens CSS.
Esta variável representa a
lateral do gadget oposta ao lado
de início da exibição do
__BIDI_E
ND_EDGE_ conteúdo. O valor será
_ "right" (direita) quando o
gadget estiver em modo LTR e
"left" (esquerda) quando o
gadget estiver em modo RTL.
O valor desta variável será "ltr"
__BIDI_D quando o gadget estiver em
IR__ modo LTR e "rtl" quando o
gadget estiver em modo RTL.
O valor desta variável será "rtl"
__BIDI_R
EVERSE_D quando o gadget estiver em
IR__ modo LTR e "ltr" quando o
gadget estiver em modo RTL.
<Content type="html"><![CDATA[
<script type="text/javascript">
// In this gadget, users choose a language from a drop-down menu, and the
gadget displays
// a "Hello World" message for the selected language. The gadget uses DOM
functions to set
// the direction and formatting for the message, depending on whether its
language is RTL
// or LTR.
// Associative array containing "Hello World" messages for different languages
var msgs = new Object();
msgs = {
"English" : "Hello World",
"Hebrew" : ""שלום עולם,
"French" : "Bonjour Monde",
"Arabic" : " بالعالx"أهل,
"Russian" : "Здравствуйте Мир!"
};
function showMsg() {
var html="<h1>";
var div = _gel('mydiv');
div.style.color = "green";
var index = document.myform.Language.selectedIndex;
var lang = document.myform.Language.options[index].text;
var str = msgs[lang];
if (!str)
str="";
// If language is Hebrew or Arabic, set the div direction to be right-to-
left.
// Offset text 30px from right margin.
if(lang=="Hebrew" || lang=="Arabic") {
div.style.direction = "rtl";
div.style.marginRight = "30px";
html += str;
}
// For other languages, set div direction to left-to-right.
// Offset text 30px from left margin.
else {
div.style.direction = "ltr";
div.style.marginLeft = "30px";
html += str;
}
html+= "</h1>";
div.innerHTML = html;
}
</script>
<div style="background-color: #BFCFFF; height: 200px; color:green;">
<br />
<div>
<form name="myform" style="text-align: center;">
<select name="Language" onchange="showMsg()">
<option>Pick a Language
<option>English
<option>Hebrew
<option>French
<option>Arabic
<option>Russian
</select>
</form>
</div>
<br />
<div id="mydiv"><h2 style='text-align: center;'>****Pick a
language****</h2></div>
</div>
]]>
</Content>
</Module>
Teste
Para testar o gadget, altere a configuração de país e idioma de modo que ela corresponda aos
pacotes de mensagens incluídos em seu gadget.
A maneira mais simples de alterar a configuração de país e idioma no iGoogle é editar o URL:
http://www.google.com/ig?&gl=<country>&hl=<lang>
Por exemplo, no URL abaixo, o país é Alemanha (DE) e o idioma é inglês (en). Normalmente, o
país tem precedência sobre o idioma. Portanto, com este URL, o iGoogle exibe texto em alemão:
http://www.google.com/ig?&gl=DE&hl=en
Este link pode ajudá-lo a criar o URL correto para um idioma específico:
http://www.google.com/help/customize.html#searchlang. Os valores válidos para o idioma são
códigos de idioma ISO639-1 com dois dígitos e os valores válidos para o país são códigos ISO
3166-1 alfa-2.
Cache
Os pacotes de mensagens têm o mesmo comportamento de cache que as especificações de gadget
em si: normalmente, atualizamos o cache a cada 1 a 2 horas, os servidores de hospedagem devem
ver somente cerca de 100 a 200 solicitações de pacotes de mensagens por dia e, se eles não
estiverem disponíveis, continuaremos usando nossa cópia "antiga" pelo tempo que for possível. No
gadget developer.xml, ao desativar o cache do gadget, você também desativa o cache dos pacotes
de mensagens do gadget.
Solução de problemas
Durante o desenvolvimento, seu gadget pode ficar em branco ou exibir ??? onde deveria haver uma
mensagem. O problema pode ser:
• Você não salvou o pacote de mensagens em UTF-8. Isso é necessário para qualquer arquivo
de idioma diferente do inglês que inclua caracteres especiais.
• Há um problema na sintaxe do seu pacote de mensagens.
• Não há um arquivo de pacote de mensagens ALL_ALL.xml para ser usado como padrão
pelo gadget.
• No gadget, o URL do pacote de mensagens está incorreto.
• Há um erro de correspondência entre o pacote de mensagens e a variável de substituição de
mensagens especificada no gadget.
Gadgets em idiomas diferentes do inglês
A maioria dos exemplos deste guia do desenvolvedor foi criada em inglês. Este documento descreve
recursos disponíveis para usuários interessados em criar gadgets em outros idiomas.
O parâmetro para o código do país é &gl e o parâmetro para o código do idioma é &hl. Neste
exemplo, o código do país (Japão) é JP, e o código do idioma japonês é ja (por padrão, os códigos
de idioma estão em letras minúsculas e os códigos de país em letras maiúsculas, mas isso não é
obrigatório). O conteúdo do diretório varia ligeiramente se você fornecer somente o código do país
ou do idioma. Portanto, inclua ambos os códigos (de país e idioma) para obter resultados mais
específicos.
Uma boa maneira de encontrar gadgets em um idioma específico é filtrar o diretório. Entretanto,
isso não retorna somente os gadgets criados no idioma de destino, pois os gadgets não recebem tags
de idioma. A API de gadgets inclui uma tag <Locale>, mas esta é opcional. O diretório exibe
gadgets para um local específico com base em sua popularidade. Portanto, ao exibir o diretório do
local Japão/japonês, por exemplo, você verá principalmente gadgets japoneses. Mas também poderá
ver gadgets populares neste local, apesar de não serem em japonês.
No diretório de conteúdo do iGoogle, você pode adicionar gadgets à sua página do iGoogle. Após
adicioná-los ao iGoogle, você poderá visualizar o código-fonte dos gadgets clicando em seus links
na página de gadgets do desenvolvedor. Os gadgets não personalizados (por exemplo, gadgets que
apenas exibem feeds) não estão listados na página de gadgets do desenvolvedor.
var files = [
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-0.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-1.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-2.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-3.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-4.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-5.jpg",
"http://gadget-doc-examples.googlecode.com/svn/trunk/zombie-6.jpg"
];
// 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>
Estrutura XML
As seções a seguir descrevem a estrutura e o conteúdo do arquivo XML usado para especificar um
gadget.
Preferências do gadget
A seção <ModulePrefs> do arquivo XML especifica as características do gadget, como título,
autor, tamanho preferido e assim por diante. Por exemplo:
<Module>
<ModulePrefs title="Developer Forum"
title_url="http://groups.google.com/group/Google-Gadgets-API"
height="200"
author="Jane Smith"
author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>
Este atributo não impede que os usuários adicionem gadgets diversas vezes
através do gadget do desenvolvedor ou que Adicionem gadgets por URL.
Conseqüentemente, continua sendo necessário que você crie seu gadget para
suportar diversas instâncias.
author_photo Para a página de autores, um URL para uma foto (o formato preferido é 70x100
PNG, mas JPG/GIF também são suportados).
author_about Para a página de autores, um texto sobre si mesmo (tente limitar em
me aproximadamente 500 caracteres).
author_link Para a página de autores, um link para seu site, blog, etc.
author_quote Para a página de autores, uma citação que você deseja de incluir (tente limitar
em aproximadamente 300 caracteres).
Uso de bibliotecas
Para usar determinados recursos da API de gadgets, como altura dinâmica ou estado de
armazenamento, é necessário carregar a biblioteca JavaScript apropriada, usando a tag
<Require> (dentro de <ModulePrefs>). A tag <Require> possui um atributo obrigatório,
feature, cujo valor especifica a biblioteca do recurso. Por exemplo:
<ModulePrefs
title="Set Userprefs Demo">
<Require feature="dynamic-height"/>
<Require feature="setprefs" />
</ModulePrefs>
Para obter mais informações sobre bibliotecas de recursos, consulte a Referência de JavaScript.
Especificação de locais
Use as tags <Locale> em <ModulePrefs> para especificar os locais suportados pelo seu
gadget. Você também pode usá-las para especificar pacotes de mensagens, como descrito em
Gadgets e internacionalização.
Por exemplo, este snippet especifica dois locais diferentes:
<ModulePrefs ...>
<Locale lang="en" country="us" />
<Locale lang="ja" country="jp" />
</ModulePrefs>
Ambos os atributos "lang" (idioma) e "country" (país) são opcionais, mas você precisa usar pelo
menos um deles para cada <Locale>. Se você omitir um dos atributos, o valor é equivalente a "*"
e "ALL" (tudo). Se você especificar um país e nenhum idioma, o sistema assumirá que seu gadget
suporta todos os idiomas associados ao país. Da mesma forma, se você especificar um idioma e
nenhum país, o sistema assumirá que seu gadget suporta todos os países associados ao idioma.
Os valores válidos para o idioma são códigos de idioma ISO639-1 com dois dígitos e os valores
válidos para o país são códigos ISO 3166-1 alfa-2.
Há algumas exceções às regras normais de idioma:
• Chinês simplificado: lang="zh-cn" (normalmente para country="cn").
• Chinês tradicional: lang="zh-tw" (normalmente para country="tw" ou "hk", Taiwan ou
Hong Kong, respectivamente).
A tabela abaixo lista os atributos <Locale>:
Atributo Descrição
lang String opcional, indicando o idioma associado ao local.
country String opcional, indicando o país associado ao local.
String opcional que é um URL apontando para um pacote de mensagens. Os
messages pacotes de mensagens são arquivos XML que contêm as strings traduzidas para
um dado local. Para obter mais informações, consulte Gadgets e
internacionalização.
String opcional que define a direção do gadget. Seu valor pode ser "rtl" (direita
para a esquerda) ou "ltr" (esquerda para a direita). O padrão é "ltr". Este atributo
permite criar gadgets que suportam idiomas lidos da esquerda para a direita e vice-
versa. Para ler mais sobre este tópico, consulte Criação de gadgets bidirecionais.
Você pode usar as variáveis de substituição descritas abaixo em conjunto com o
atributo language_direction:
Se você não especificar um <Locale>, o padrão suposto será EUA + inglês somente.
<MayRequire type="platform"
value="windows"> This gadget uses a Windows API.
</MayRequire>
</ModulePrefs>
default_value="4">
<EnumValue value="3" display_value="Easy"/>
<EnumValue value="4" display_value="Medium"/>
Seção de conteúdo
A seção <Content> define o tipo de conteúdo e contém o próprio conteúdo ou uma referência
para conteúdo externo. A seção <Content> é onde os atributos do gadget e as preferências do
usuário são combinados à lógica de programação e às informações de formatação para se
transformarem em um gadget executável. Para ler mais sobre tipos de conteúdo, consulte Seleção
do tipo de conteúdo.
A tabela abaixo lista os atributos <Content>:
Atributo Descrição
String opcional que fornece o tipo de conteúdo. Os valores possíveis são html e url. O
type
padrão é html.
String que fornece um URL de destino. Obrigatório para type="url" e não permitido
href
com outros tipos de conteúdo.
cdata String opcional. Para HTML, contém o HTML puro que será exibido no iframe.
API Reference: gadgets.*
Bem-vindo a uma pré-apresentação da documentação de referência da API de gadgets. Esta
documentação contém detalhes sobre a futura inserção da API de gadgets em uma API JavaScript
de gadgets.* mais limpa.
Observação: Esta API ainda não é suportada pelo iGoogle. Se você deseja criar um gadget para o
iGoogle, consulte a Referência da API do Google Gadgets.
Sumário
• API principal
• Prefs
• io
• AuthorizationType
• ContentType
• MethodType
• RequestParameters
• json
• util
• API específica do recurso
• MiniMessage
• Tab
• TabSet
• flash
• rpc
• views
• View
• ViewType
• skins
• Property
• window
gadgets.Prefs
Classe gadgets.Prefs
Fornece acesso às preferências do usuário, dimensões do módulo e mensagens. Os clientes podem
acessar suas preferências, criando uma instância de gadgets.Prefs e passando o id do módulo.
Exemplo:
var prefs = new gadgets.Prefs();
var name = prefs.getString("name");
var lang = prefs.getLang();
Resumo do construtor
gadgets.Prefs(opt_moduleId)
Cria um novo objeto Prefs.
Resumo do método
Array.<String> getArray(key)
Recupera uma preferência de matriz.
Boolean getBool(key)
Recupera uma preferência booleana.
String getCountry()
Obtém o país atual, retornado como um código ISO 3166-1 alpha-2.
Number getFloat(key)
Recupera uma preferência de ponto flutuante.
Number getInt(key)
Recupera uma preferência de número inteiro.
String getLang()
Obtém o idioma atual que o gadget deve usar na visualização, retornado como um código de
idioma ISO 639-1.
String, Number getModuleId()
Obtém o id do módulo para a instância atual.
String getMsg(key)
Obtém uma mensagem não formatada.
String getMsgFormatted(key, opt_subst)
Retorna um valor de mensagem com o argumento de posição opt_subst no lugar, caso seja
fornecido, ou caso contrário, o valor fornecido no exemplo. Se a mensagem não for
encontrada, retorna a string vazia.
String getString(key)
Recupera uma preferência de string.
set(key, val)
Armazena uma preferência.
setArray(key, val)
Armazena uma preferência de matriz.
Detalhes do construtor
gadgets.Prefs
gadgets.Prefs(opt_moduleId)
Detalhes do método
getArray
Array.<String> getArray(key)
Recupera uma preferência de matriz. Os valores de UserPref que não foram declarados
como listas são tratados como matrizes de um único elemento.
Parâmetros:
String key - A preferência a ser obtida
Retorna:
Array.<String> A preferência; se não estiver definida, uma matriz vazia
getBool
Boolean getBool(key)
getCountry
String getCountry()
getFloat
Number getFloat(key)
getInt
Number getInt(key)
getLang
String getLang()
Obtém o idioma atual que o gadget deve usar na visualização, retornado como um código de
idioma ISO 639-1.
Retorna:
String O idioma para esta instância do módulo
getModuleId
String, Number getModuleId()
getMsg
String getMsg(key)
getMsgFormatted
String getMsgFormatted(key, opt_subst)
Retorna um valor de mensagem com o argumento de posição opt_subst no lugar, caso seja
fornecido, ou caso contrário, o valor fornecido no exemplo. Se a mensagem não for
encontrada, retorna a string vazia.
Parâmetros:
String key - A mensagem a ser obtida
String opt_subst - Uma string opcional para ser substituída na mensagem
Retorna:
String A string formatada
getString
String getString(key)
set
set(key, val)
Armazena uma preferência. Para usar esta chamada, o gadget precisa ter o recurso setprefs.
Observação: Se o gadget tiver que armazenar uma matriz, ele deverá usar setArray em vez
desta chamada.
Parâmetros:
String key - A preferência a ser armazenada
Object val - Os valores a serem armazenados
setArray
setArray(key, val)
Armazena uma preferência de matriz. Para usar esta chamada, o gadget precisa ter o recurso
setprefs.
Parâmetros:
String key - A preferência a ser armazenada
Array val - Os valores a serem armazenados
gadgets.io
Static Class gadgets.io
Fornece funções de recuperação de conteúdo remoto.
Resumo do método
<static> String encodeValues(fields)
Converte um objeto de entrada em uma string de dados codificada como URL.
<static> String getProxyUrl(url)
Obtém a versão proxy do URL passado.
<static> makeRequest(url, callback, opt_params)
Obtém o conteúdo a partir do URL fornecido e alimenta este conteúdo na função de retorno
de chamada.
Detalhes do método
encodeValues
<static> String encodeValues(fields)
getProxyUrl
<static> String getProxyUrl(url)
makeRequest
<static> makeRequest(url, callback, opt_params)
Obtém o conteúdo a partir do URL fornecido e alimenta este conteúdo na função de retorno
de chamada. Exemplo:
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
gadgets.io.makeRequest(url, callback, params);
Parâmetros:
String url - O URL no qual o conteúdo está localizado
Function callback - A função a ser chamada com os dados do URL após a
obtenção
Map.<gadgets.io.RequestParameters, Object> opt_params -
Parâmetros adicionais a serem passados para a solicitação
gadgets.io.AuthorizationType
Static Class gadgets.io.AuthorizationType
Usada por RequestParameters.
Resumo do campo
<static> object AUTHENTICATED
O recipiente usará autenticação completa.
<static> object NONE
Sem autorização.
<static> object SIGNED
A solicitação será assinada pelo recipiente.
Detalhes do campo
AUTHENTICATED
<static> object AUTHENTICATED
NONE
<static> object NONE
Sem autorização.
SIGNED
<static> object SIGNED
Resumo do campo
<static> object DOM
Retorna um objeto DOM; usado para obter XML.
<static> object FEED
Retorna uma representação JSON de um feed.
<static> object JSON
Retorna um objeto JSON.
<static> object TEXT
Retorna texto; usado para obter HTML.
Detalhes do campo
DOM
<static> object DOM
FEED
<static> object FEED
JSON
<static> object JSON
TEXT
<static> object TEXT
Resumo do campo
<static> object DELETE
Não suportado por todos os recipientes.
<static> object GET
O tipo padrão.
<static> object HEAD
Não suportado por todos os recipientes.
<static> object POST
Não suportado por todos os recipientes.
<static> object PUT
Não suportado por todos os recipientes.
Detalhes do campo
DELETE
<static> object DELETE
Não suportado por todos os recipientes.
GET
<static> object GET
O tipo padrão.
HEAD
<static> object HEAD
Não suportado por todos os recipientes.
POST
<static> object POST
Não suportado por todos os recipientes.
PUT
<static> object PUT
Não suportado por todos os recipientes.
gadgets.io.RequestParameters
Resumo do campo
<static> object AUTHORIZATION
O tipo de autenticação a ser usada durante a obtenção do conteúdo; o padrão é
AuthorizationType.NONE.
<static> object CONTENT_TYPE
O tipo de conteúdo que reside no URL; o padrão é ContentType.TEXT.
<static> object GET_SUMMARIES
No caso do conteúdo ser um feed, indica se os resumos do feed devem ser obtidos; o padrão é
false (falso).
<static> object HEADERS
Os cabeçalhos HTTP a serem enviados ao URL; o padrão é null (nulo).
<static> object METHOD
O método a ser usado durante a obtenção de conteúdo a partir do URL; o padrão é
MethodType.GET.
<static> object NUM_ENTRIES
Se o conteúdo for um feed, indica o número de entradas a serem obtidas; o padrão é 3.
<static> object POST_DATA
Os dados a serem enviados ao URL usando o método POST; o padrão é null (nulo).
Detalhes do campo
AUTHORIZATION
<static> object AUTHORIZATION
CONTENT_TYPE
<static> object CONTENT_TYPE
GET_SUMMARIES
<static> object GET_SUMMARIES
No caso do conteúdo ser um feed, indica se os resumos do feed devem ser obtidos; o padrão
é false (falso). Especificado como um Boolean.
HEADERS
<static> object HEADERS
Os cabeçalhos HTTP a serem enviados ao URL; o padrão é null (nulo). Especificado como
um Map.<String,String>.
METHOD
<static> object METHOD
NUM_ENTRIES
<static> object NUM_ENTRIES
POST_DATA
<static> object POST_DATA
Os dados a serem enviados ao URL usando o método POST; o padrão é null (nulo).
Especificado como um String.
gadgets.json
Static Class gadgets.json
Fornece operações de conversão de objetos de e para JSON.
Resumo do método
<static> Object parse(text)
Analisa uma string JSON, produzindo um valor JavaScript.
<static> String stringify(v)
Converte um valor JavaScript em uma string JSON.
Detalhes do método
parse
<static> Object parse(text)
stringify
<static> String stringify(v)
Resumo do método
<static> String escapeString(str)
Cria códigos de escape para os dados inseridos, usando entidades html para garantir maior
segurança.
<static> Object getFeatureParameters(feature)
Obtém os parâmetros do recurso.
<static> Object getUrlParameters()
Obtém os parâmetros do URL.
<static> Boolean hasFeature(feature)
Retorna se o recurso atual é suportado.
<static> makeClosure(scope, callback, var_args)
Cria um invólucro adequado para ser passado como um retorno de chamada.
<static> registerOnLoadHandler(callback)
Registra um manipulador durante a carga.
<static> String unescapeString(str)
Inverte escapeString.
Detalhes do método
escapeString
<static> String escapeString(str)
Cria códigos de escape para os dados inseridos, usando entidades html para garantir maior
segurança.
Parâmetros:
String str - A String para a qual serão criados os códigos de escape.
Retorna:
String A String com códigos de escape.
getFeatureParameters
<static> Object getFeatureParameters(feature)
hasFeature
<static> Boolean hasFeature(feature)
makeClosure
<static> makeClosure(scope, callback, var_args)
Cria um invólucro adequado para ser passado como um retorno de chamada. É possível
passar qualquer quantidade de argumentos ao retorno de chamada. Eles serão recebidos na
ordem em que forem passados.
Parâmetros:
Object scope - O escopo da execução; pode ser null se não houver necessidade
de associar uma instância específica de um objeto a este retorno de chamada
Function callback - O retorno de chamada a ser executado quando a
chamada for realizada; qualquer argumento será passado após os argumentos iniciais
Object var_args - Argumentos iniciais a serem passados ao retorno de
chamada
registerOnLoadHandler
<static> registerOnLoadHandler(callback)
unescapeString
<static> String unescapeString(str)
Inverte escapeString.
Parâmetros:
String str - A String da qual serão removidos os códigos de escape.
Retorna:
String A String sem códigos de escape.
gadgets.MiniMessage
Classe gadgets.MiniMessage
Classe MiniMessage.
Resumo do construtor
gadgets.MiniMessage(opt_moduleId, opt_container)
Usado para criar mensagens que aparecerão para o usuário dentro do gadget.
Resumo do método
Element createDismissibleMessage(message, opt_callback)
Cria uma mensagem que pode ser dispensada, com um ícone [x] para permitir que os usuários
dispensem a mensagem.
Element createStaticMessage(message)
Cria uma mensagem estática que pode ser dispensada apenas programaticamente (através de
uma chamada a dismissMessage()).
Element createTimerMessage(message, seconds, opt_callback)
Cria uma mensagem que é exibida por um número especificado de segundos.
dismissMessage(message)
Dispensa a mensagem especificada.
Detalhes do construtor
gadgets.MiniMessage
gadgets.MiniMessage(opt_moduleId, opt_container)
Usado para criar mensagens que aparecerão para o usuário dentro do gadget.
Parâmetros:
String opt_moduleId - Id do módulo opcional
Element opt_container - Elemento opcional do recipiente HTML no qual
aparecerão as mini-mensagens.
Detalhes do método
createDismissibleMessage
Element createDismissibleMessage(message, opt_callback)
Cria uma mensagem que pode ser dispensada, com um ícone [x] para permitir que os
usuários dispensem a mensagem. Quando a mensagem é dispensada, ela é removida da
árvore DOM, e a função opcional de retorno de chamada, se estiver definida, é executada.
Parâmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
Function opt_callback - Função opcional de retorno de chamada a ser
executada quando a mensagem for dispensada
Retorna:
Element Elemento HTML da mensagem criada
createStaticMessage
Element createStaticMessage(message)
Cria uma mensagem estática que pode ser dispensada apenas programaticamente (através de
uma chamada a dismissMessage()).
Parâmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
Retorna:
Element Elemento HTML da mensagem criada
createTimerMessage
Element createTimerMessage(message, seconds, opt_callback)
Cria uma mensagem que é exibida por um número especificado de segundos. Quando o
temporizador expira, a mensagem é dispensada e a função opcional de retorno de chamada é
executada.
Parâmetros:
String, Object message - A mensagem como uma string HTML ou um
elemento DOM
number seconds - Número de segundos que devem ser aguardados antes de a
mensagem ser dispensada
Function opt_callback - Função opcional de retorno de chamada a ser
executada quando a mensagem for dispensada
Retorna:
Element Elemento HTML da mensagem criada
dismissMessage
dismissMessage(message)
Resumo do método
Function getCallback()
Retorna a função de retorno de chamada, executada quando a guia é selecionada.
Element getContentContainer()
Retorna o elemento HTML no qual o conteúdo da guia é visualizado.
Number getIndex()
Retorna o índice da guia.
String getName()
Retorna o marcador da guia na forma de uma string (pode conter HTML).
Element getNameContainer()
Retorna o elemento HTML que contém o marcador da guia.
Detalhes do método
getCallback
Function getCallback()
getContentContainer
Element getContentContainer()
getIndex
Number getIndex()
getNameContainer
Element getNameContainer()
Resumo do construtor
gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)
Cria um novo objeto TabSet
Resumo do método
String addTab(tabName, opt_params)
Adiciona uma nova guia com base nos pares nome-valor especificados em opt_params.
alignTabs(align, opt_offset)
Define o alinhamento das guias.
displayTabs(display)
Exibe ou oculta guias e todo o conteúdo associado a elas.
Element getHeaderContainer()
Retorna o elemento cabeçalhos de guia do recipiente.
gadgets.Tab getSelectedTab()
Retorna o objeto de guia selecionado no momento.
Array.<gadgets.Tab> getTabs()
Retorna uma matriz de todos os objetos de guia existentes.
removeTab(tabIndex)
Remove uma guia do tabIndex (índice de guias) e todo o conteúdo associado a ela.
setSelectedTab(tabIndex)
Seleciona a guia no tabIndex e ativa a função de retorno de chamada da guia, se existir.
swapTabs(tabIndex1, tabIndex2)
Troca as posições das guias em tabIndex1 e tabIndex2.
Detalhes do construtor
gadgets.TabSet
gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)
addTab
String addTab(tabName, opt_params)
Adiciona uma nova guia com base nos pares nome-valor especificados em opt_params.
Parâmetros:
String tabName - Marcador da guia a ser criada.
Object opt_params - Objeto de parâmetro opcional. As seguintes propriedades
são suportadas: .contentContainer. É um elemento HTML existente a ser usado como
recipiente do conteúdo da guia. Se omitido, a biblioteca de guias cria um elemento.
.callback. É uma função de retorno de chamada a ser executada quando a guia é
selecionada. .tooltip. É uma descrição de dica de ferramenta que aparece quando o
usuário move o cursor do mouse sobre a guia. .index. É o índice no qual a guia será
inserida. Se omitido, a nova guia é anexada no final.
Retorna:
String Id do DOM do recipiente da guia.
alignTabs
alignTabs(align, opt_offset)
displayTabs
displayTabs(display)
getHeaderContainer
Element getHeaderContainer()
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()
removeTab
removeTab(tabIndex)
Remove uma guia do tabIndex (índice de guias) e todo o conteúdo associado a ela.
Parâmetros:
Number tabIndex - Índice da guia a ser removida.
setSelectedTab
setSelectedTab(tabIndex)
swapTabs
swapTabs(tabIndex1, tabIndex2)
Troca as posições das guias em tabIndex1 e tabIndex2. A guia selecionada não é alterada e
nenhuma função de retorno de chamada é executada.
Parâmetros:
Number tabIndex1 - Índice da guia a ser trocada.
Number tabIndex2 - Índice da segunda guia a ser trocada.
gadgets.flash
Static Class gadgets.flash
Integra conteúdo Flash nos gadgets.
Resumo do método
<static> Boolean embedCachedFlash()
Injeta um arquivo Flash com cache na árvore DOM.
<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion,
opt_params)
Injeta um arquivo Flash na árvore DOM.
<static> Number getMajorVersion()
Detecta o Flash Player e sua versão principal.
Detalhes do método
embedCachedFlash
<static> Boolean embedCachedFlash()
Injeta um arquivo Flash com cache na árvore DOM. Aceita os mesmos parâmetros que
gadgets.flash.embedFlash.
Retorna:
Boolean Se a chamada à função for concluída com sucesso.
embedFlash
<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)
getMajorVersion
<static> Number getMajorVersion()
Resumo do método
<static> call(targetId, serviceName, callback, var_args)
Chama um serviço RPC.
<static> register(serviceName, handler)
Registra um serviço RPC.
<static> registerDefault(handler)
Registra um manipulador de serviços padrão para processar todas as chamadas RPC
desconhecidas, que falham sem aviso por padrão.
<static> unregister(serviceName)
Cancela o registro de um serviço RPC.
<static> unregisterDefault()
Cancela o manipulador de serviços padrão.
Detalhes do método
call
<static> call(targetId, serviceName, callback, var_args)
register
<static> register(serviceName, handler)
registerDefault
<static> registerDefault(handler)
Registra um manipulador de serviços padrão para processar todas as chamadas RPC
desconhecidas, que falham sem aviso por padrão.
Parâmetros:
Function handler - Manipulador de serviços.
unregister
<static> unregister(serviceName)
unregisterDefault
<static> unregisterDefault()
Resumo do método
<static> gadgets.views.View getCurrentView()
Retorna a visualização atual.
<static> Map.<String, String> getParams()
Retorna os parâmetros passados a este gadget para esta visualização.
<static> Map<gadgets.views.ViewType, String, gadgets.views.View>
getSupportedViews()
Retorna um mapa de todas as visualizações suportadas.
<static> requestNavigateTo(view, opt_params)
Tenta ir para uma visualização diferente deste gadget.
Detalhes do método
getCurrentView
<static> gadgets.views.View getCurrentView()
getParams
<static> Map.<String, String> getParams()
Retorna os parâmetros passados a este gadget para esta visualização. Não inclui todos os
parâmetros de URL, somente os passados para gadgets.views.requestNavigateTo
Retorna:
Map.<String, String> O mapa de parâmetros
getSupportedViews
<static> Map<gadgets.views.ViewType, String, gadgets.views.View>
getSupportedViews()
Tenta ir para uma visualização diferente deste gadget. Se o recipiente suportar parâmetros,
ele passará os parâmetros opcionais para o gadget na nova visualização.
Parâmetros:
gadgets.views.View view - A visualização de destino
Map.<String, String> opt_params - Parâmetros a serem passados ao
gadget após a visualização ser acessada
gadgets.views.View
Classe gadgets.views.View
Interface básica para todos os objetos de visualização.
Resumo do método
gadgets.views.ViewType, String getName()
Retorna o nome desta visualização.
boolean isOnlyVisibleGadget()
Retorna true (verdadeiro) se o gadget for o único gadget visível nesta visualização.
Detalhes do método
getName
gadgets.views.ViewType, String getName()
isOnlyVisibleGadget
boolean isOnlyVisibleGadget()
Retorna true (verdadeiro) se o gadget for o único gadget visível nesta visualização. Em uma
página de tela inteira ou no modo maximizado, provavelmente é true (verdadeiro); em uma
página de perfil ou no modo painel, provavelmente é false (falso).
Retorna:
boolean True se o gadget for o único gadget visível; caso contrário, false
gadgets.views.ViewType
Static Class gadgets.views.ViewType
Usada pelas Visualizações.
Resumo do campo
<static> object DASHBOARD
Uma visualização na qual o gadget é exibido em uma pequena área, normalmente em uma
página com outros gadgets.
<static> object FULL_PAGE
Uma visualização na qual o gadget é exibido em um modo muito grande.
<static> object POPUP
Uma visualização na qual o gadget é exibido sozinho em uma pequena janela separada.
Detalhes do campo
DASHBOARD
<static> object DASHBOARD
Uma visualização na qual o gadget é exibido em uma pequena área, normalmente em uma
página com outros gadgets. Em um contexto social, esta normalmente é chamada de página
de perfil.
FULL_PAGE
<static> object FULL_PAGE
Uma visualização na qual o gadget é exibido em um modo muito grande. Deve ser a única
coisa na página. Em um contexto social, esta normalmente é chamada de página de tela
inteira.
POPUP
<static> object POPUP
Uma visualização na qual o gadget é exibido sozinho em uma pequena janela separada.
gadgets.skins
Static Class gadgets.skins
Fornece operações para obter informações de exibição sobre a skin exibida atualmente.
Resumo do método
<static> String getProperty(propertyKey)
Obtém a propriedade de exibição mapeada para a chave em questão.
Detalhes do método
getProperty
<static> String getProperty(propertyKey)
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
BG_COLOR
<static> object BG_COLOR
BG_IMAGE
<static> object BG_IMAGE
FONT_COLOR
<static> object FONT_COLOR
Resumo do método
<static> adjustHeight(opt_height)
Ajusta a altura do gadget
<static> Object getViewportDimensions()
Detecta as dimensões internas de um frame.
<static> setTitle(title)
Define o título do gadget.
Detalhes do método
adjustHeight
<static> adjustHeight(opt_height)
getViewportDimensions
<static> Object getViewportDimensions()
setTitle
<static> setTitle(title)