documentacao - opensocial

103
A web fica melhor com os relacionamentos A web é muito mais interessante quando você pode construir aplicativos que interajam facilmente com seus amigos e colegas. Essa tendência também criou uma lista crescente de APIs específicas para sites, que os desenvolvedores precisam aprender. O serviço OpenSocial oferece um conjunto de APIs comuns para desenvolver aplicativos sociais que irão funcionar em diversos sites. Elas possibilitam que os desenvolvedores criem aplicativos utilizando JavaScript e HTML padrão para acessar amigos de uma rede social e atualizar feeds. Muitos sites, uma API O uso de APIs comuns significa que você precisa aprender menos para desenvolver para diversos sites. O OpenSocial está sendo desenvolvido pelo Google em conjunto com os membros da comunidade da web. O objetivo final é qualquer site de relacionamentos ser capaz de implementar as APIs e hospedar aplicativos sociais de terceiros. Muitos sites estão implementando o OpenSocial, entre eles o Engage.com, Friendster, hi5, Hyves, imeem, LinkedIn, MySpace, Ning, Oracle, orkut, Plaxo, Salesforce.com, Six Apart, Tianji, Viadeo e XING. Para que os desenvolvedores comecem imediatamente, o Orkut abriu um sandbox limitado que você pode usar para começar a criar aplicativos usando as APIs do OpenSocial. Servidor opcional O OpenSocial foi criado com a tecnologia do Google Gadget. Você pode criar um aplicativo social ótimo e "viral" com custos mínimos ou inexistentes de servidor. Com o Google Gadget Editor e uma API simples de valor essencial, você pode criar um aplicativo social completo sem nenhum servidor. É claro que você também pode hospedar seu aplicativo em seus próprios servidores, se preferir. Em todo caso, a tecnologia de cache de gadget do Google alivia a demanda de largura de banda, caso seu aplicativo se torne um sucesso mundial.

Upload: leandronix

Post on 26-Jun-2015

153 views

Category:

Documents


8 download

TRANSCRIPT

Page 1: documentacao - OpenSocial

A web fica melhor com os relacionamentosA web é muito mais interessante quando você pode construir aplicativos que interajam facilmente com seus amigos e colegas. Essa tendência também criou uma lista crescente de APIs específicas para sites, que os desenvolvedores precisam aprender.

O serviço OpenSocial oferece um conjunto de APIs comuns para desenvolver aplicativos sociais que irão funcionar em diversos sites. Elas possibilitam que os desenvolvedores criem aplicativos utilizando JavaScript e HTML padrão para acessar amigos de uma rede social e atualizar feeds.

Muitos sites, uma APIO uso de APIs comuns significa que você precisa aprender menos para desenvolver para diversos sites. O OpenSocial está sendo desenvolvido pelo Google em conjunto com os membros da comunidade da web. O objetivo final é qualquer site de relacionamentos ser capaz de implementar as APIs e hospedar aplicativos sociais de terceiros. Muitos sites estão implementando o OpenSocial, entre eles o Engage.com, Friendster, hi5, Hyves, imeem, LinkedIn, MySpace, Ning, Oracle, orkut, Plaxo, Salesforce.com, Six Apart, Tianji, Viadeo e XING.

Para que os desenvolvedores comecem imediatamente, o Orkut abriu um sandbox limitado que você pode usar para começar a criar aplicativos usando as APIs do OpenSocial.

Servidor opcionalO 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.

Page 2: documentacao - OpenSocial

Seções Tópicos selecionados

Primeiros passos "Hello, World"Em que consiste um Gadget?

Criação dos seus próprios gadgets Etapas básicasAnatomia de um gadget

Fundamentos do desenvolvimento

Seleção do tipo de conteúdoComo transformar uma página da web ou aplicativo existente em um gadgetUso de tipos de dados Userpref Como salvar o estado Criação de gadgets que necessitam de login ou cookies

Ferramentas para desenvolvedores Dicas de programação e depuraçãoHospedagem através do Google Gadgets EditorHospedagem no Google Code

Criação de uma interface de usuário

Gerenciamento da altura do gadgetDefinição do título do gadgetGuiasMiniMessagesFlash

Uso de conteúdo remoto

Uso de texto Uso de XMLUso de feedsUso de JSON

InternacionalizaçãoCriação de um gadget localizadoPacotes de mensagensUso de pacotes de mensagens em um gadget

Gadgets em idiomas diferentes do inglês

Onde posso encontrar gadgets que não sejam em inglês? Criação de gadgets em idiomas diferentes do inglês

Publicação do seu gadget Onde posso colocar meu gadget?Preparação para a publicaçãoPublicação no diretório de conteúdo do iGoogle

Referência das especificações de gadgets

Preferências do gadgetPreferências do usuárioSeção de conteúdo

Referência de JavaScript

Page 3: documentacao - OpenSocial

Primeiros passosBem-vindo à API de gadgets!

Este guia do desenvolvedor é baseado na versão gadgets.* da API de gadgets JavaScript. A API de gadgets foi inserida no namespace API JavaScript de gadgets.* para fornecer uma API mais limpa para programação e suporte. Para saber mais sobre a API de gadgets.*, consulte a documentação de referência aqui. Embora a API de gadgets.* tenha muita coisa em comum com a API de gadgets antiga, também há diferenças importantes.

Atualmente apenas alguns recipientes (um recipiente é um site ou aplicativo que executa gadgets) suportam a gadgets.* API. Para ver uma lista dos recipientes que suportam a gadgets.* API, consulte a lista de recipientes do OpenSocial. Alguns recipientes mais antigos suportam apenas a API de gadgets antiga. Portanto, verifique a documentação do seu recipiente específico para saber qual API é suportada. Para saber mais sobre os tipos diferentes de gadgets e onde eles podem ser executados, consulte a Visão geral da API de gadgets.

Este guia do desenvolvedor destina-se a pessoas que desejam usar a API para criar gadgets. Por serem muito fáceis de criar, os gadgets são um excelente ponto de partida se você estiver começando a aprender sobre programação da web.

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

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

• Os gadgets são especificados em XML. A primeira linha é a maneira padrão de iniciar um arquivo XML. Esta deve ser a primeira linha do arquivo.

• A tag <Module> indica que este arquivo XML contém um gadget. • A tag <ModulePrefs> contém informações sobre o gadget, como seu título, descrição,

autor e outros recursos opcionais. • A linha <Content type="html"> indica que o tipo de conteúdo do gadget é HTML. • <![CDATA[ ...insert HTML here... ]]> é usada como invólucro para o HTML

quando o tipo de conteúdo do gadget é html. Ela informa ao analisador do gadget que o texto dentro da seção CDATA não deve ser tratado como XML. A seção CDATA normalmente contém HTML e JavaScript.

• </Content> significa o final da seção Conteúdo. • </Module> significa o final da definição do gadget.

Em que consiste um Gadget? A API de gadgets consiste em alguns blocos estruturais simples: XML, HTML e JavaScript. Para começar, você só precisa de conhecimentos básicos de HTML. Nós ensinaremos tudo o que é

Page 4: documentacao - OpenSocial

necessário sabe sobre XML para criar gadgets. Mais tarde, ao criar gadgets mais sofisticados, você provavelmente aprenderá como usar JavaScript, caso ainda não esteja familiarizado com essa linguagem.

XML é uma linguagem de markup de uso geral. Ela descreve dados estruturados de maneira que possam ser lidos e gravados por programadores e computadores.

XML é a linguagem usada para programar as especificações do gadget. Um gadget é simplesmente um arquivo XML, colocado em algum lugar da internet onde o Google possa encontrá-lo. O arquivo XML que especifica um gadget contém instruções sobre como processar e exibir o gadget. O arquivo XML pode conter todos os dados e códigos do gadget, ou pode ter referências (URLs) para o local onde o restante dos elementos se encontram.

HTML é a linguagem de markup usada para formatar páginas da internet. O conteúdo estático de um gadget normalmente é criado em HTML. A linguagem HTML tem aparência semelhante à XML, mas é usada para formatar documentos da web e não para descrever dados estruturados.

JavaScript é uma linguagem de scripts que pode ser usada para adicionar comportamento dinâmico aos gadgets.

Page 5: documentacao - OpenSocial

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

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

1. Use qualquer editor de texto para escrever as especificações do seu gadget e guarde essas informações em um servidor da web público.

2. Adicione seu gadget a um recipiente, como o iGoogle ou Orkut. Um recipiente é um aplicativo ou site com a capacidade de executar gadgets.

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

• Seção de conteúdo. A seção <Content> é onde ocorre o funcionamento mais importante do seu gadget. É onde você especifica o tipo de gadget, a lógica de programação e, freqüentemente, os elementos HTML que determinam a aparência do gadget.

• Preferências do usuário. A seção <UserPrefs> define os controles que permitem que os usuários especifiquem configurações do gadget. Por exemplo, um gadget de saudações personalizadas pode fornecer um campo de texto para o usuário especificar seu nome.

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

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

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

Definição de conteúdoA 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">

Page 6: documentacao - OpenSocial

<![CDATA[ <div style="text-align:center"><a id="Riggs" title="My Photo Album" target="_blank" href="http://picasaweb.google.com/doc.examples/ShelfBoy"> <img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg" title="Click Here."></a> </div> ]]> </Content></Module>

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

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

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

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

As preferências do usuário que são transformadas em controles da interface de usuário do gadget sendo executado são definidas na especificação XML, conforme mostrado abaixo:<?xml version="1.0" encoding="UTF-8" ?><Module>

Page 7: documentacao - OpenSocial

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

Observe que:

• A linha 3 do arquivo contém o texto title="Preferences for __UP_myname__". Ao executar o gadget, o valor fornecido pela preferência de usuário myname é substituído dinamicamente por __UP_myname__.

• A preferência de usuário myname está marcada como "obrigatória". Se o usuário tentar executar o gadget sem fornecer um valor para esse campo, a caixa de edição das preferências de usuário permanece aberta até que um valor seja fornecido.

• A preferência de usuário mychoice possui o tipo de dados bool. Ela é exibida na interface de usuário como uma caixa de seleção.

• A preferência de usuário mycolor possui o tipo de dados enum. A lista de EnumValues especifica as opções que aparecem em um menu suspenso na caixa de edição das preferências do usuário.

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

function displayGreeting () { // Get current time var today = new Date(); var time = today.getTime(); var html = "";

Page 8: documentacao - OpenSocial

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

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

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

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

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

Use a API JavaScript para acessar as preferências do usuário a partir do seu gadget; por exemplo:<script type="text/javascript"> var prefs = new gadgets.Prefs(); var someStringPref = prefs.getString("StringPrefName"); var someIntPref = prefs.getInt("IntPrefName"); var someBoolPref = prefs.getBool("BoolPrefName");</script>

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

Variáveis de substituição de preferências do usuárioVocê pode usar uma variável de substituição do formato __UP_userpref__ nas seções <ModulePrefs> ou <UserPref>, onde userpref corresponde ao atributo name (nome) de uma preferência de usuário. Quando o gadget é executado, o valor da string da preferência de usuário correspondente é substituído pela variável, sem a adição de códigos de escape. Por exemplo, neste trecho, o valor fornecido pelo usuário durante a execução para a preferência de usuário projects (projetos) é substituído por __UP_projects__ na string title_url:<Module> <ModulePrefs title="Build Monitor" title_url="http://www.example.com/build/status.php?__UP_projects__"/> <UserPref name="projects" display_name="project(s)"/>

Page 9: documentacao - OpenSocial

<Content ... /></Module>

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

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

• Para o atributo <ModulePrefs> title, use __UP_name__ . Esta variável possui códigos de escape de HTML.

• Para o atributo <ModulePrefs> title_url, use __UP_name__ . Esta variável possui códigos de escape de URL.

• No HTML dentro da seção <Content>, use __UP_name__. Esta variável possui códigos de escape de HTML.

• No código JavaScript dentro da seção <Content>, use a função gadgets.Prefs().

Definição das preferências do gadgetA seção <ModulePrefs> do arquivo XML especifica as características do gadget, como título, autor, tamanho preferido e assim por diante. Por exemplo:<Module> <ModulePrefs title="Today's Network Traffic" title_url="http://www/~rowan/gadgets/stats/" height="200" author="Jane Smith" author_email="[email protected]"/> <Content ...> ... content ... </Content> </Module>

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

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

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

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

• Não envie seu gadget para o diretório de conteúdo ou para diretórios como o googlemodules.com ou hotmodules.com.

• Se as pessoas não puderem encontrar seu gadget, é improvável que descubram o URL. Para evitar que ele seja indexado por mecanismos de busca, você pode usar alguns artifícios:

• Procure impedir que o seu servidor da web forneça uma listagem de arquivos incluindo o seu arquivo (isso também afasta os usuários bisbilhoteiros).

• Verifique se não há hyperlinks na web apontando para o seu gadget

Page 10: documentacao - OpenSocial

Fundamentos do desenvolvimentoEste documento descreve os conceitos e tarefas básicas para o processo de desenvolvimento do gadget. Para obter informações sobre como usar a API de gadgets, leia Primeiros passos.

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

O tipo de conteúdo determina:

• Que recursos da API estão disponíveis para você como autor do gadget. • Como seu gadget é exibido. • Onde seu gadget pode ser implementado.

A tabela a seguir descreve os tipos de conteúdo disponíveis e quando você deve usá-los:

Tipo de conteúdo Descrição Quando usar

html

Com o tipo de conteúdo html, o conteúdo completo normalmente reside nas especificações do gadget. Um gadget type="html" contém HTML, possivelmente com JavaScript, Flash, ActiveX ou outros objetos incorporados ao navegador. Este é o tipo padrão.

O tipo de conteúdo mais flexível e versátil é o html. Na dúvida, selecione o tipo de conteúdo html.

url

Com o tipo de conteúdo url, o conteúdo do gadget reside em uma página da web remota que pode ser acessada por meio de um URL localizado nas especificações do gadget. A página da web remota é onde reside todo o markup HTML e o JavaScript. Você NÃO pode colocar nenhum markup HTML ou código JavaScript nas especificações do gadget.

Atualmente, o tipo de conteúdo type="url" não é totalmente suportado pelos gadgets.* ou APIs do OpenSocial. Se desejar usar o tipo de conteúdo type="url" com as bibliotecas de gadgets JavaScript, use a API de gadgets antiga.

HTMLCom 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>

Page 11: documentacao - OpenSocial

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

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

// if a non-alphabetic character, just append to string if (index==-1) { message += aChar; }

// if you have to wrap around the end of the alphabet else if(index > 12) { // compensate for 0-based index index = 25 - index; // last item in array is at [25] index = 12 - index; // because array starts with 0 aChar = alpha.charAt(index); message += aChar; }

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

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

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

• Um gadget type="html" deve conter uma seção CDATA, e todos os códigos HTML devem estar dentro dessa seção:

<Content type="html"> <![CDATA[ HTML here... ]]>

As seções CDATA são usadas para adicionar códigos de escape a blocos de texto contendo caracteres que, de outra forma, seriam considerados markup. O único

Page 12: documentacao - OpenSocial

separador reconhecido em uma seção CDATA é a string "]]>", que finaliza a seção CDATA.

• Você não pode usar as tags <html>, <head>, ou <body>. Os gadgets são gerados com suas próprias tags <html>, <head>, e <body>. Basta incluir o conteúdo que normalmente ficaria dentro da tag <body>.

Um gadget com tipo de conteúdo html também pode fazer referência a um arquivo JavaScript externo: <Module> <ModulePrefs ... /> <Content type="html"><![CDATA[ <script src="http://www.example.com/gadgets/clock/clock.js" type="text/javascript"></script>

]]></Content> </Module>

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

Para obter uma descrição

Como transformar uma página da web ou aplicativo existente em um gadgetPara transformar uma página da web ou aplicativo existente em um gadget, siga as orientações abaixo:

• Remova as tags <html>, <head> e <body> (em outras palavras, forneça apenas o conteúdo HTML). Esta diretriz aplica-se somente a gadgets type="html". Ela não se aplica a gadgets type="url".

• Para eventos onload, use gadgets.util.registerOnLoadHandler(). • Se o gadget exigir login, use um tipo de conteúdo URL. Consulte a seção Criação de gadgets

que necessitam de login ou cookies para saber como lidar com situações que podem ser consideradas "armadilhas". Gadgets HTTPS emitem avisos de "conteúdo misto" no Internet Explorer, o que pode incomodar os usuários.

• Faça as alterações necessárias na interface do usuário para ajustar sua página ou aplicativo no pequeno espaço do gadget. O makeRequest() pode ser usado como proxy do conteúdo de amadores e profissionais criando protótipos. Para gadgets desenvolvidos comercialmente, recomendamos simplesmente criar uma pequena página nova e usar o type="url" apontando para ela.

Page 13: documentacao - OpenSocial

Uso de tipos de dados UserprefCada preferência de usuário tem um tipo de dados dentro da especificação do gadget. O datatype é uma string opcional que especifica o tipo de dados do atributo. Os valores possíveis de datatype são string, bool, enum, hidden (uma string invisível que não pode ser editada pelo usuário), list e location (para gadgets baseados no Google Maps). O tipo de dados padrão é string.

Consulte a referência para obter informações detalhadas sobre os tipos de dados das preferências do usuário.

Esta seção descreve dois dos tipos de dados mais especializados: list e location. Você pode encontrar exemplos de como usar os outros tipos de dados na documentação (por exemplo, enum, hidden e bool).

Uso do tipo de dados listUma preferência de usuário com o tipo de dados list é uma matriz de valores fornecidos dinamicamente pelos usuários durante a execução. À medida que os usuários digitam valores na caixa de edição de preferências do usuário, os valores são adicionados à lista. Assim como qualquer outro userpref, a lista pode ser acessada programaticamente pelo gadget durante a execução. Você pode usar o tipo de dados list sempre que quiser permitir que os usuários forneçam uma lista de valores arbitrários dinamicamente. Por exemplo, um gadget de condições climáticas pode permitir que os usuários digitem uma lista de códigos postais.

Para declarar que um userpref tem tipo de dados list, use datatype="list". Por exemplo:<UserPref name="mylist" display_name="Add Search Terms" datatype="list" required="true"/>

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

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

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

Use a função setArray(name, val) de Prefs para adicionar valores à lista programaticamente. Para usar essa função, seu gadget deve incluir <Require feature="setprefs"/> em <ModulePrefs>. Por exemplo, o trecho a seguir adiciona os valores "Nokia" e "CNET" à lista: ...

<ModulePrefs title="Feed Searcher" scrolling="true"> <Require feature="setprefs" />

</ModulePrefs>

Page 14: documentacao - OpenSocial

...prefs.setArray("mylist", ["Nokia","CNET"]);

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

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

// Get the array of search terms entered by the user var terms = prefs.getArray("mylist"); var html = "";

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

]]> </Content></Module>

Uso do tipo de dados locationOs gadgets baseados no Google Maps podem usar o tipo de dados location. O gadget do exemplo a seguir ilustra como usar o tipo de dados location. Nos gadgets, o valor fornecido para um tipo de dados location deve ser uma cidade ou um código postal dos Estados Unidos, Canadá ou Reino Unido. O uso de códigos postais pode ter um resultado melhor.

Ao usar o tipo de dados location, use getString() para recuperar a longitude e a latitude do local especificado pelo usuário.<Module> <ModulePrefs title="Map of __UP_loc__" height="300" author="Jane Smith" author_email="[email protected]" /> <UserPref name="loc" display_name="Location" datatype="location"

Page 15: documentacao - OpenSocial

required="true" /> <Content type="html"> <![CDATA[ <script src="http://maps.google.com/maps?file=js" type="text/javascript"></script> <div id="map" style="width: 100%; height: 100%;"></div> <script type="text/javascript"> var prefs = new gadgets.Prefs(); var map = new GMap(document.getElementById("map")); map.addControl(new GSmallMapControl()); map.addControl(new GMapTypeControl()); map.centerAndZoom(new GPoint(prefs.getString("loc.long"), prefs.getString("loc.lat")), 6); </script>

]]> </Content></Module>

Ao ler uma preferência x de location:

• Se x for uma string vazia (significando um local vazio), x.lat e x.long são a string vazia.

• Se x não puder ser geocodificada (significando um local inválido), x.lat e x.long são 0.0.

As versões anteriores da API de gadgets não permitiam especificar um default_value para o tipo de local. Mas agora isso mudou.

Como salvar o estado É comum permitir que os usuários definam suas preferências de forma explícita, através da caixa de edição. Entretanto, às vezes é útil definir programaticamente os valores das preferências do usuário, sem sua participação direta. Por exemplo, em um gadget de jogo, você pode armazenar continuamente a pontuação mais alta do usuário. Você pode fazer isso de maneira programática, definindo o valor de uma preferência de usuário "high_score".

Para usar o recurso setprefs, seu gadget deve incluir:

• Uma tag <Require feature="setprefs"/> (em <ModulePrefs>) para informar ao gadget que ele precisa carregar a biblioteca setprefs.

• Uma userpref cujo valor você deseja definir programaticamente e armazenar continuamente. Normalmente, esta userpref tem o tipo de dados hidden.

• Uma chamada à função JavaScript set() para a userpref cujo valor você deseja salvar.

O tamanho da preferência atualmente está restrito por limitações de URL, podendo chegar a 2K.

O gadget da amostra a seguir consiste em dois botões: um que aumenta o valor de um contador, e outro que redefine o valor do contador para 0. Neste exemplo, "counter" é uma preferência de usuário. O tipo de dados é hidden, o que significa que os usuários não têm permissão de modificar diretamente o valor.

Esta é a especificação do gadget: <?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Setprefs New"> <Require feature="opensocial-0.7"/> <Require feature="setprefs" />

Page 16: documentacao - OpenSocial

</ModulePrefs> <UserPref name="counter" default_value="0" datatype="hidden"/> <Content type="html"> <![CDATA[ <div id="content_div" style="height: 100px;"></div> <script type="text/javascript">

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

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

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

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

Codificação de escape de caracteres especiaisÉ necessário adicionar códigos de escape a determinados caracteres especiais dentro dos atributos XML de uma especificação de gadget. Você pode usar somente entidades ASCII na especificação do gadget. Por exemplo, não é possível usar entidades do símbolo ISO 8859-1. Aqui está uma lista dos caracteres especiais suportados:

Caractere Codificação de escape & &amp;< &lt;> &gt;" &quot;' &apos;Por exemplo:

• BAD: href="http://www.foo.com/bar?x=a&y=b" • GOOD: href="http://www.foo.com/bar?x=a&amp;y=b" • BAD: description="this is a "sexy" gadget" • GOOD: description="this is a &quot;sexy&quot; gadget"

Page 17: documentacao - OpenSocial

Observe que esse tipo de escape não é necessário no bloco CDATA. Entretanto, seu uso é recomendável.

Dentro do código JavaScript, use a função _hesc(str) para retornar a string HTML str com os caracteres abaixo seguidos do código de escape: <>'".

Criação de gadgets que necessitam de login ou cookiesAs políticas de privacidade padrão do Microsoft Internet Explorer e do Apple Safari não permitem que sites de terceiros definam cookies. Portanto, alguns gadgets podem não funcionar corretamente. Os sites que usam cookies para login, especificamente, podem não funcionar corretamente dentro de um iframe da página do iGoogle. Veja algumas soluções possíveis:

• Use parâmetros URL em vez de cookies. Por exemplo, o Orkut birthdays gadget (aniversários do Orkut) passa credenciais de autenticação via URL. Aviso importante: Se você optar por este método, tenha cuidado para que esses parâmetros de URL não vazem para outros sites da web nos campos HTTP de direcionamento.

• Crie cabeçalhos P3P. Dependendo da política de privacidade do seu site, talvez você possa criar cabeçalhos P3P, os quais permitem que o Internet Explorer (mas não o Safari) leia cookies de terceiros do seu site. Se você estiver usando PHP e desejar definir os cabeçalhos, use este snippet de código no alto da sua página PHP:

<?php header("P3P: CP=\"CAO PSA OUR\"");?>

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

VERIFIQUE SUA POLÍTICA DE PRIVACIDADE CUIDADOSAMENTE QUANTO AOS CABEÇALHOS QUE PODEM SER USADOS EM SEU SITE. ENCORAJAMOS VOCÊ A CONSULTAR SEU ADVOGADO.

• Informe os usuários. Isso pode ser feito em JavaScript, como nesta amostra de gadget (experimente) . Você também pode integrar instruções à sua lógica de autenticação. Se detectar o bloqueio de cookies, informe os usuários que eles devem afrouxar sua configuração de privacidade ou experimentar um navegador diferente. Por exemplo, você pode exibir uma mensagem como:

Seu navegador não é compatível com este site na configuração atual. Se estiver usando o Microsoft Internet Explorer, altere sua configuração de segurança selecionando Ferramentas > Opções da Internet. Abra a guia Privacidade, clique em Avançado e, em seguida, clique em Ignorar manipulação automática de cookies. Em Cookies Secundários, clique em Aceitar. Como alternativa, você pode usar outro navegador, como o Firefox.

Page 18: documentacao - OpenSocial

Ferramentas para desenvolvedoresEste documento fornece diretrizes gerais para programação, depuração e hospedagem de gadgets.

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

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

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

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

Se estiver usando um tipo de navegador diferente, procure um console JavaScript ou depurador suportado por seu navegador.

Confirme suas suposições Confirmar suas suposições durante o processo de desenvolvimento pode economizar muito tempo e evitar o desperdício de esforços. Você tem certeza de que sua variável tem o valor que você supõe? Você tem certeza de que a matriz contém elementos? Talvez a função que "não parece estar funcionando" na verdade não esteja sendo chamada? Teste suas suposições imprimindo as mensagens de status em pontos diferentes do programa. Por exemplo, o gadget abaixo tem uma função print() que grava mensagens de depuração em debug_div caso o sinalizador debug tenha um valor diferente de zero: <?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Debug Example" height="200"/> <UserPref name="myname" display_name="Name" required="true" /> <UserPref name="mycolor"

Page 19: documentacao - OpenSocial

display_name="Color" default_value="Pink" datatype="enum" > <EnumValue value="Blue" /> <EnumValue value="Yellow" /> <EnumValue value="Pink" /> <EnumValue value="Gray" /> </UserPref> <Content type="html"> <![CDATA[ <div id="content_div" style="font-size:20pt; padding:5px; text-align: center;"></div> <div id="debug_div" style="font-size:9pt; padding:5px; color: red;"></div> <script type="text/javascript"> // Get userprefs var prefs = new gadgets.Prefs();

// debug flag. When its value is non-zero, debugging messages are displayed var debug = 1; // The string containing debugging messages var debug_html = "";

// Display date function displayDate (){ // DEBUG: is the function getting called? print("In displayDate function<br>"); // Create Date object var today = new Date(); // Get current time var time = today.getTime(); var content_html = ""; var element = document.getElementById('content_div'); element.style.backgroundColor=prefs.getString("mycolor"); element.style.height=100; // DEBUG: print out prefs values print("The background color is " + prefs.getString("mycolor") + "<br>"); print("The name is " + prefs.getString("myname") + "<br>"); content_html += today.toDateString(); // Write content HTML to div document.getElementById("content_div").innerHTML = content_html; } // Outputs debug messages if debug flag has a non-zero value function print(msg) { if (debug) { debug_html += msg; // Write debug HTML to div document.getElementById("debug_div").innerHTML = debug_html; } } gadgets.util.registerOnLoadHandler(displayDate); </script> ]]> </Content></Module>

Observação: Consulte MiniMessages para obter uma descrição da API de MiniMessages, que permite modificar o comportamento e a aparência das mensagens exibidas em um gadget.

Page 20: documentacao - OpenSocial

Ferramentas adicionaisAs funções adicionais do Firefox descritas abaixo podem ajudá-lo a obter uma visão mais detalhada dos seus gadgets durante o desenvolvimento:

• O Firebug fornece ferramentas de depuração e inspeção de DOM. • O Web Developer adiciona um menu e uma barra de ferramentas ao navegador, contendo

ferramentas de desenvolvedor da web.

Hospedagem através do Google Gadgets EditorCaso não tenha acesso a um servidor para armazenar seus arquivos XML de gadget, o Google Gadgets Editor (GGE) é uma ótima ferramenta para editar e hospedar gadgets rapidamente. Para usar o GGE, faça login em uma conta do Google (ou você não poderá salvar seu gadget). Por exemplo, se você alterar a mensagem "Hello, world!" para "Hello, gadget developers!!" e usar o comando File > Save (Arquivo > Salvar) para salvar a especificação do gadget com um novo nome, o GGE hospedará o novo gadget para você com o nome especificado:

Observação: O GGE ainda não suporta a totalmente API de gadgets.*. Portanto, alguns dos recursos ainda não estão ativados. Você pode usar o GGE para editar e hospedar arquivos, mas não pode pré-visualizar seu gadget.

Comandos do menu FileA guia Edit (Editar) tem um menu suspenso File (Arquivo) que inclui os comandos descritos abaixo. O GGE usa sua conta do Google para identificar os arquivos que pertencem a você. Portanto, é necessário fazer login para poder usar a maioria desses comandos.

Comando DescriçãoOpen (Abrir) Abre um gadget criado anteriormente e salvo através do GGE.

Save (Salvar)

Salva a especificação do gadget que está sendo editado. Se você ainda não tiver salvo o gadget, ele solicita o nome do gadget. Ao salvar um gadget no GGE, o GGE o hospeda automaticamente para você. Um gadget deve ser hospedado em um servidor público para poder ser publicado. O GGE hospeda o gadget e fornece diversas maneiras de publicá-lo.

Save As (Salvar como) Salva o gadget sendo editado com o nome que você fornecer.

Rename (Renomear)

Renomeia o gadget sendo editado. Disponível somente depois que o gadget é salvo.

Upload (Enviar)

Permite navegar no sistema de arquivos para localizar recursos do gadget e salvá-los no ambiente do GGE. Os recursos incluem especificações de gadget, arquivos de imagem, etc. Depois que os recursos são enviados, o GGE os hospeda. Isso possibilita que você importe-os para a especificação do seu gadget, inserindo links de referência aos URLs do GGE.

Publish (Publicar)

O item de menu Publish (Publicar) oferece as opções abaixo para a publicação do seu gadget:

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

O comando fica disponível somente depois que o gadget é salvo (salvar faz o GGE

Page 21: documentacao - OpenSocial

hospedar seu gadget). Para obter mais informações, consulte Publicação do seu gadget com o GGE.

Delete (Excluir)

Exibe uma lista dos seus gadgets no GGE e permite que você selecione os itens que deseja excluir.

Publicação do seu gadget com o GGEO comando Publish (Publicar) do menu File (Arquivo) oferece as opções abaixo para a publicação do seu gadget:

• Add to my iGoogle page (Adicionar à minha página do iGoogle) - Adiciona o gadget à sua página do iGoogle. Esta é a maneira mais simples de testar seu gadget durante o desenvolvimento.

• Publish to iGoogle Directory (Publicar no diretório do iGoogle) - Leva você até a página de envio do iGoogle, inserindo automaticamente o URL do seu gadget no formulário. Você pode usar o formulário para enviar seu gadget ao diretório de conteúdo do iGoogle. Seu gadget não será enviado a menos que você clique em Send (Enviar). Depois de testar e ajustar seu gadget, essa será a etapa final do desenvolvimento. Você não precisa realizar essa etapa para usar seu gadget e compartilhá-lo com seus amigos. Esta opção é para desenvolvedores que desejam disponibilizar seus gadgets para um público de massa.

• Add to a webpage (Adicionar a uma página da web) - Leva você até a página do criador da distribuição. A distribuição ainda não é suportada pela API de gadgets.* e nem pelas APIs do OpenSocial.

O URL do seu gadget é fornecido no canto superior direito do GGE. Clique no link para ver o URL completo.

Durante o desenvolvimento e teste do gadget, recomendamos testá-lo na sua página do iGoogle e em outras páginas da web. Depois de testar e ajustar seu gadget, você pode optar por enviá-lo ao diretório de conteúdo do iGoogle, onde será distribuído para um público maior.

Hospedagem no Google CodeA maneira mais fácil de hospedar especificações e recursos de gadget é através do GGE. Para os desenvolvedores que necessitam de um sistema de controle de fonte com mais recursos, recomendamos a hospedagem no Google Code: http://code.google.com/hosting. O Google Code é um serviço gratuito que oferece muitas vantagens ao desenvolvedor de gadgets. Uma das principais vantagens é o controle de versões através do Subversion, que é um sistema de controle de versões de código aberto. Com o Subversion, você pode rastrear alterações e manter versões diferentes do seu gadget. O histórico completo das revisões fica disponível, permitindo que você retorne a uma versão anterior ou analise as diferenças entre as versões. Para saber mais sobre o Subversion, consulte o Livro do Subversion.

Para hospedar seus gadgets no Google Code, primeiro é necessário instalar um programa de área de trabalho (o "cliente do Subversion") que permite enviar e salvar arquivos no code.google.com ("repositório do Subversion"). A maioria dos clientes do Subversion contém uma interface gráfica de usuário, que torna a interação com o Subversion mais fácil do que a interface de linha de comando. Você pode escolher entre diversos clientes, dependendo do seu sistema operacional. Procure instalar um que seja compatível com o seu sistema. Aqui estão alguns clientes recomendados:

• TortoiseSVN é um cliente do Subversion para Windows fácil de usar, que integra a funcionalidade diretamente no Windows Explorer.

• AnkhSVN é um plugin do Visual Studio que oferece acesso ao Subversion dentro do IDE (Ambiente de desenvolvimento integrado).

Page 22: documentacao - OpenSocial

• ZigVersion é um cliente do Subversion criado para o Mac OS X.• RapidSVN é um cliente do Subversion com GUI (Interface gráfica de usuário) para diversas

plataformas. Este cliente suporta os três principais sistemas operacionais: Windows, Mac OS X e Linux.

Aqui está uma lista completa dos clientes e plugins.

Depois de instalar o Subversion em sua máquina, siga as etapas abaixo para começar a usar o Google Code e hospedar seus projetos.

Criação de um novo projeto Para criar um novo projeto:

1. Vá para http://code.google.com/hosting e faça login usando sua conta do Gmail. Crie uma conta se ainda não tiver.

2. Clique em Create a new project (Criar um novo projeto). 3. Preencha os campos do seu novo projeto:

• Crie um nome com letras minúsculas para o seu projeto, por exemplo my-gadgets. Lembre-se de que o nome do projeto torna-se parte do URL do projeto e não pode ser alterado depois.

• Escreva um resumo e uma descrição. • Selecione uma licença de código aberto. Para saber mais, visite Licença de código

aberto. • Etapa opcional: atribua marcadores para ajudar outros usuários a encontrarem o seu

projeto. 4. Confirme se todos os campos obrigatórios foram preenchidos e clique em Create Project

(Criar projeto). 5. Pronto! Você será direcionado à Página inicial do projeto. Confirme se o URL tem a

seguinte aparência: http://code.google.com/p/<project-name>/

Agora você tem um projeto no code.google.com. Um repositório do Subversion foi criado usando o nome do seu projeto. Clique na guia Source (Fonte) e clique no link Subversion repository (Repositório do Subversion).

O URL deve ter a seguinte aparência: http://<project-name>.googlecode.com/svn/. Você deve ver três links de diretórios: branches, tags e trunk. Ao enviar arquivos para o seu projeto, eles são colocados na pasta /trunk. Você pode salvar o URL http://<project-name>.googlecode.com/svn/trunk/ em seus favoritos para referência futura.

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

svn checkout https://<project-name>.googlecode.com/svn/trunk/ gadgets-test --username <username>

Quando solicitado, digite a senha SVN que foi gerada.

Mantenha esta página aberta em um navegador para poder recuperar as informações apropriadas conforme necessário.

Page 23: documentacao - OpenSocial

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.

Page 24: documentacao - OpenSocial

Criação de uma interface de usuárioEste documento descreve como adicionar os diversos elementos de interface de usuário ao seu gadget.

Gerenciamento da altura do gadgetPor padrão, os gadgets têm 200 pixels de altura. Você pode usar o atributo <ModulePrefs> height="nn" para especificar uma altura estática maior ou menor que a altura padrão. Você pode usar o atributo <ModulePrefs> scrolling="true" para criar uma barra de rolagem vertical para o gadget, caso a altura do conteúdo exceda a altura designada.

Entretanto, alguns gadgets precisam ter flexibilidade para alterar sua altura dinamicamente. Por exemplo, suponha que você criou um gadget de lista cuja altura precisa ser expandida e contraída, dependendo do conteúdo da lista. O gadget cresce à medida que os usuários adicionam itens à lista. Quando eles limpam a lista, o gadget retorna à altura original. Veja aqui a aparência do gadget sendo executado:

Para adicionar ao seu gadget o recurso de redimensionamento, adicione os itens abaixo à especificação:

• Uma tag <Require feature="dynamic-height"/> (em <ModulePrefs>) para informar ao gadget que ele precisa carregar a biblioteca dynamic-height.

• Uma chamada à função JavaScript gadgets.window.adjustHeight() sempre que houver uma alteração de conteúdo ou ocorrer outro evento que exija o redimensionamento do gadget.

Por exemplo, veja abaixo a especificação do gadget de lista de compras:<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Dynamic Height" height="100"> <Require feature="dynamic-height"/> </ModulePrefs> <Content type="html"> <![CDATA[ <script type="text/javascript"> // This example lets users add items to a grocery list and then clear the list. // When items are added or cleared, the gadget resizes itself. var mylist = ""; var flag = 0;

Page 25: documentacao - OpenSocial

// Function that is invoked whenever user clicks the Add button to add an // item to the list. function addToList (form) { var input = _trim(form.inputbox.value); if (input == "") { return; }

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

// Call setContent to output HTML to div and resize gadget setContent(mylist); }

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

// Outputs content to the div and resizes the gadget function setContent(html) { document.getElementById('content_div').innerHTML = html;

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

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

Definição do título do gadgetUse a função gadgets.window.setTitle() para definir o título do gadget programaticamente. Para usar esta função, seu gadget deve incluir:

• Em <ModulePrefs>, uma tag <Require feature="settitle"/> para informar

Page 26: documentacao - OpenSocial

ao gadget que ele precisa carregar a biblioteca settitle. • Uma chamada a gadgets.window.setTitle() para definir o título do gadget.

Este exemplo fornece um campo de texto que permite que o usuário defina o título do gadget:<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Set Title Example"> <Require feature="settitle"/> </ModulePrefs> <Content type="html"> <![CDATA[ <script type="text/javascript"> function changeTitle(form) { var newTitle = form.inputbox.value; gadgets.window.setTitle(newTitle); } </script><FORM NAME="myform" ACTION="" METHOD="GET">Change the Gadget Title: <BR><BR><INPUT TYPE="text" NAME="inputbox" VALUE=""><BR><BR><INPUT TYPE="button" NAME="button" Value="Change Title" onClick="changeTitle(this.form)"></FORM><div id="content_div"></div> ]]> </Content></Module>

GuiasUse a biblioteca de guias para adicionar uma interface de usuário com guias ao seu gadget. Para usar guias, a especificação do seu gadget deve incluir no mínimo:

• Em <ModulePrefs>, um tag <Require feature="tabs"/> para informar ao gadget que ele precisa carregar a biblioteca tabs.

• JavaScript para criar as guias e preenchê-las com conteúdo. Para obter mais detalhes, consulte Como funciona.

Também é comum incluir a biblioteca setprefs para que o gadget possa armazenar sempre a última guia selecionada pelo usuário. Assim, se o usuário sair e retornar à página, o gadget carrega a guia armazenada. Para aproveitar este recurso, incorpore duas linhas de código na especificação do seu gadget:<Require feature="setprefs"/>...<UserPref name="selectedTab" datatype="hidden"/>

Anatomia de um objeto de guias A biblioteca de guias fornece funções e CSS para realizar operações com os objetos abaixo:

• Objeto TabSet. O objeto de guias é o recipiente-pai de todas as guias. Programaticamente, o objeto de guias é uma matriz de objetos de guia individuais. Normalmente, a implementação básica do HTML é um elemento <table>, mencionado na API como o "header container" (recipiente de cabeçalho). Use a função gadgets.TabSet.getHeaderContainer() para acessar este HTML.

• Objeto de guia. Um objeto de guia é uma única guia dentro de uma matriz de guias indexadas. Normalmente, a implementação básica do HTML é um elemento <td>,

Page 27: documentacao - OpenSocial

mencionado na API como o "name container" (recipiente de nome). Use a função gadgets.Tab.getNameContainer() para acessar este HTML.

• Recipiente de conteúdo. Um objeto de recipiente de conteúdo contém o conteúdo de um objeto de guia individual. Normalmente, a implementação básica do HTML é um elemento <div>, mencionado na API como o "content container" (recipiente de conteúdo). Use a função gadgets.Tab.getContentContainer() para acessar este HTML.

Como funcionaUse 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>

Page 28: documentacao - OpenSocial

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 });

Page 29: documentacao - OpenSocial

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

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

// Call init function to initialize and display tabs. gadgets.util.registerOnLoadHandler(init); </script>

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

Manipulação de guias por índiceA API de guias também inclui funções que permitem a manipulação das guias por índice. As guias são indexadas de 0 a n, onde 0 é a primeira guia. Por exemplo, se houver 3 guias, os índices são 0, 1 e 2. Você pode usar os índices para selecionar uma guia programaticamente e para trocar a posição de duas guias.

Embora o ID de uma guia permaneça constante, o mesmo não ocorre com seu índice. Por exemplo, se você mover a terceira guia para a primeira posição, o índice é alterado de 2 para 0.

Aqui está um exemplo de como selecionar uma guia programaticamente. Este snippet cria um link. Quando o usuário clica no link, a segunda guia é selecionada, como se o usuário tivesse clicado na própria guia:<script>...function selectTab() { tabs.setSelectedTab(1);}</script>

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

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

Page 30: documentacao - OpenSocial

tabs.swapTabs(0, 1);}

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

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

Personalização de guias com CSS A folha de estilo das guias está disponível em http://www.google.com/ig/tablib.css. Ela define as classes aplicadas aos elementos HTML que definem as guias.

Você pode usar as classes CSS abaixo para ignorar a configuração padrão e modificar a aparência das suas guias.

Classe CSS Descrição.tablib_table Aplicável à tabela HTML que contém as guias..tablib_selected Aplicável à guia selecionada..tablib_unselected Aplicável a todas as guias não selecionadas..tablib_spacerTab Aplicável aos elementos de espaçamento entre cada guia..tablib_emptyTab Controla os espaçamentos de início e de fim em volta das guias..tablib_main_container

Aplicável ao recipiente-pai, que contém todo o conteúdo relacionado às guias (ou seja, cabeçalhos de guia e todos os recipientes individuais de conteúdo).

.tablib_content_container

Aplicável a todos os recipientes de conteúdo da guia.

Para obter uma lista com as classes e as configurações que podem ser ignoradas, acesse http://www.google.com/ig/tablib.css.<![CDATA[ <style type="text/css"> .tablib_selected { color: #FF0000; } .tablib_unselected { color: #660099; } .tablib_table { font-size:20px; } .tablib_emptyTab { padding:2px 5px; } .tablib_spacerTab { padding:0px 5px; } </style>

<script...>

Você também pode usar JavaScript para aplicar estilos CSS ao recipiente de cabeçalho das guias. A função getHeaderContainer() retorna a tabela HTML das guias, que você pode modificar conforme desejar.

Por exemplo, este snippet altera o tamanho da fonte e adiciona margem no alto: var tabs = new gadgets.TabSet();...var table = tabs.getHeaderContainer();table.style.fontSize = "10px";table.style.marginTop = "15px";

Page 31: documentacao - OpenSocial

Você pode personalizar o estilo dos cabeçalhos de guias individuais, obtendo os elementos da guia individual e modificando suas propriedades. Veja um exemplo que torna o estilo da primeira guia exclusivo:var tabs = new gadgets.TabSet();tabs.addTab("Unique");...var firstTab = tabs.getTabs()[0].getNameContainer();firstTab.style.backgroundColor = "#999999";firstTab.style.color = "#ffffff";

Alteração de alinhamento da guia Por padrão, as guias são centralizadas ao serem adicionadas. Entretanto, se houver menos que 3 ou 4 guias, você pode alinhá-las à esquerda ou à direita. Para isso, use a função alignTabs(). Ela aceita um parâmetro com o valor left, right ou center. Se você for alinhar guias à esquerda ou à direita, há um parâmetro opcional que pode ser passado para indicar a largura do deslocamento em relação ao lado esquerdo ou direito. O tamanho padrão é 3px.

Por exemplo: var tabs = new gadgets.TabSet();...// Align tabs to the left and offset it by 10 pixelstabs.alignTabs("left", 10);

Como ocultar guiasUse a função displayTabs() para alternar a exibição das guias e de seu conteúdo. Esta função assume o valor booleano de true ou false.

Aqui está um exemplo que cria um botão que exibe ou oculta as guias: <input onclick="toggleTabs()" type="button" value="Show/Hide"/><script>var tabs = new gadgets.TabSet();...var showTabs = true;function toggleTabs() { showTabs = !showTabs; tabs.displayTabs(showTabs);}</script>

MiniMessagesUma 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.

Page 32: documentacao - OpenSocial

• 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 funcionaAs etapas básicas da adição de uma MiniMessage ao gadget são simples:

1. Importe a biblioteca de MiniMessages: <Require feature="minimessage"/>

2. Crie uma instância de um novo objeto de MiniMessage usando o construtor gadgets.MiniMessage(): var msg = new gadgets.MiniMessage(__MODULE_ID__);

Na maioria dos casos, você criará um único objeto global que possa ser acessado por todos os escopos.

3. Crie uma nova MiniMessage com um texto: msg.createDismissibleMessage("Please close me when you're done reading me.");

Isso adiciona no início do gadget uma mensagem pré-formatada dispensável com um [x] associado a ela. Quando os usuários clicam no [x], a mensagem é fechada.

Pronto! Você criou um dos diversos tipos de mensagens dispensáveis.

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

Definição de um local para todas as mensagens Você pode passar um elemento HTML ao construtor, de preferência um <div>, para ignorar a localização padrão do elemento de recipiente da mensagem. Esse elemento torna-se o recipiente no qual as mensagens serão inseridas e exibidas.

Por exemplo, neste snippet, a mensagem <h3> "I'm on top now!" aparece no início do gadget. As MiniMessages são exibidas abaixo dela em messageBox <div>, na ordem em que foram adicionadas. <div> <h3>I'm on top now!</h3>

Page 33: documentacao - OpenSocial

</div>

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

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

</script>

Definição de um local para uma única mensagemVocê pode criar uma mensagem dispensável em uma localização designada em vez de anexá-la ao recipiente da mensagem. Para isso, faça o markup da mensagem dentro da parte HTML do gadget. Em seguida, passe o elemento HTML (de preferência um <div>) como o primeiro parâmetro a createDismissibleMessage().

Por exemplo, neste snippet, a mensagem é exibida dentro do status <div>: <div id="status" style="color:#B30000;"> <b>Check out our new API documentation!</b> -- <a href="http://www.google.com/apis/gadgets" target="_blank">Read</a></div>

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

Criação de mensagens usando métodos DOMPode haver casos em que você irá gerar a mensagem dispensável usando métodos HTML DOM. Como a mensagem não existe no DOM, ela é anexada ao recipiente de mensagens por padrão.

Por exemplo:<script type="text/javascript"> var msg = new gadgets.MiniMessage(__MODULE_ID__); // Generate the message using DOM methods var div = document.createElement("div"); div.innerHTML = "New message created by W3C DOM methods."; // Set some DOM properties div.onmouseover = function() { div.style.backgroundColor = "green"; }; div.onmouseout = function() { div.style.backgroundColor = ""; }; msg.createDismissibleMessage(div);

</script>

Page 34: documentacao - OpenSocial

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

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

Personalização da exibição de MiniMessagesHá duas maneiras de se alterar a aparência padrão de MiniMessages:

• Altere a aparência das mensagens individuais. • Altere a aparência de todas as mensagens de forma global.

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

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

Alteração do estilo de todas as mensagens Use CSS globalmente para alterar o estilo de todas as mensagens. A folha de estilo das MiniMessages está disponível em http://www.google.com/ig/minimessagelib.css. Ela define as classes aplicadas aos elementos HTML que definem as MiniMessages.

Você pode usar as classes CSS abaixo para ignorar a configuração padrão e modificar a aparência de suas mensagens.

Classe CSS Descrição.mmlib_table Aplicável à tabela HTML que contém a mensagem..mmlib_xlink Aplicável ao link [x] usado para dispensar uma mensagem. A

Page 35: documentacao - OpenSocial

configuração se aplica somente à mensagem dispensável.Por exemplo, isto altera a cor de fundo para azul marinho e a cor principal para branco: <![CDATA[ <style>

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

FlashUse 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

gadgets.flash.embedFlash(swf_url, swf_container, swfVersion, opt_params)

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.

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

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

gadgets.flash.embedCachedFlash(swf_url, swf_container, swfVersion, opt_params)

Injeta um arquivo Flash com cache na árvore DOM. Os parâmetros e o valor retornado são os mesmos do método embedFlash().

gadgets.flash.getMajorVersion()

Retorna a principal versão do Flash Player, ou zero se o Flash 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:

Page 36: documentacao - OpenSocial

<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Trevor Does Tricks" height="300"> <Require feature="flash" /></ModulePrefs><Content type="html"><![CDATA[

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

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

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

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

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

// When gadget first loads, display still photo. gadgets.util.registerOnLoadHandler(showPhoto); </script> <br /> <div style="text-align: center;"> <input type=submit class="mybutton" value="Spin" onClick="doTrick('spin')"> <input type=submit class="mybutton" value="Speak" onClick="doTrick('speak')"> <input type=submit class="mybutton" value="Sit" onClick="doTrick('sit')"> <input type=submit class="mybutton" value="Down" onClick="doTrick('down')"> <input type=submit class="mybutton" value="Stop" onClick="showPhoto()"> </div> ]]></Content></Module>

Page 37: documentacao - OpenSocial

Uso de conteúdo remotoEste documento descreve como obter e manipular dados remotos textuais (normalmente HTML), XML, JSON e de feeds RSS/Atom.

IntroduçãoA 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); };

Page 38: documentacao - OpenSocial

function response(obj) { //obj.text contains the text of the page that was requested var str = obj.text; var html = str.substr(0,400); document.getElementById('content_div').innerHTML = html; }; gadgets.util.registerOnLoadHandler(getHtml);

Este exemplo ilustra os princípios básicos por trás do funcionamento da função makeRequest():

1. Quando a função makeRequest() é chamada, a API de gadgets faz uma solicitação HTTP GET assíncrona ao URL passado à função (neste exemplo, o URL é http://www.google.com).

2. makeRequest() é retornada imediatamente e chama a função de retorno de chamada posteriormente (neste exemplo, denominada response()), quando todo o conteúdo é obtido. Isso significa que você deve colocar todos os códigos dependentes dentro da função de retorno de chamada ou dentro de funções chamadas pela função de retorno de chamada.

3. makeRequest() retorna um objeto JavaScript com a seguinte estrutura: { data : <parsed data, if applicable>, errors : <any errors that occurred>, text : <raw text of the response> }

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

Uso de tipos de conteúdo diferentes Como padrão, o conteúdo de um site remoto é retornado como texto. Você pode usar o campo opt_params para definir o conteúdo retornado como um dos seguintes tipos:

• TEXT -- gadgets.io.ContentType.TEXT • DOM -- gadgets.io.ContentType.DOM • JSON -- gadgets.io.ContentType.JSON

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

// This example fetches data from a CSV file containing contact information. In the CSV file, // each record consists of a name, email address, and phone number. function getContacts() { var params = {};

Page 39: documentacao - OpenSocial

params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT; var url = "http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-gadgets/Contacts.csv"; gadgets.io.makeRequest(url, response, params); }; // Callback function to process the response function response(obj) { var responseText = obj.text; // Set CSS for div. var html = "<div style='padding: 5px;background-color: #FFFFBF;font-family:Arial, Helvetica;" + "text-align:left;font-size:90%'>";

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

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

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

Uso de XMLO DOM (Document Object Model, Modelo de objeto de documento) é uma API para navegação em documentos HTML e XML. Você pode usar makeRequest() para recuperar um documento XML como um objeto DOM. Você pode operar o objeto obtido usando funções DOM JavaScript padrão. Normalmente, isso significa extrair os dados desejados do arquivo XML, combiná-los com markup HTML e CSS e exibir o HTML resultante em seu gadget.

Com o DOM, o conteúdo da web é analisado em uma árvore de nós. Por exemplo, veja o snippet de HTML abaixo:<a href="http://www.google.com/">Google's <b>fast</b> home page.</a>

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

• Nós de elemento. Os nós de elemento deste snippet são “a” e “b”. Os nós de elemento são os

Page 40: documentacao - OpenSocial

blocos que definem a estrutura de um documento. • Nós de texto. Os nós de texto deste trecho são ‘Google’s’, ‘fast’ e ‘home page’. Os nós de

texto são sempre inseridos em nós de elemento. Eles são os nós-filho do nó de elemento em que estão inseridos.

• Nós de atributo. Este snippet apresenta um nó de atributo: href=’http://www.google.com’. Um nó de atributo fornece informações adicionais sobre o nó de elemento em que está inserido. Entretanto, os atributos não são considerados nós-filho dos elementos em que estão inseridos, o que afeta o modo como você trabalha com eles. Para ler mais sobre este tópico, consulte Uso de tipos de nó diferentes.

Esta é a estrutura DOM do snippet do HTML:

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

ExemploO 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>

Page 41: documentacao - OpenSocial

<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;

Page 42: documentacao - OpenSocial

// Display menu title. Use getElementsByTagName() to retrieve the <menu> element. // Since there is only one menu element in the file, // you can get to it by accessing the item at index "0". // You can then use getAttribute to get the text associated with the // menu "title" attribute. var title = domdata.getElementsByTagName("menu").item(0).getAttribute("title");

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

html += title + "</div><br>"; // Get a list of the <food> element nodes in the file var itemList = domdata.getElementsByTagName("food"); // Loop through all <food> nodes for (var i = 0; i < itemList.length ; i++) { // For each <food> node, get child nodes. var nodeList = itemList.item(i).childNodes;

// Loop through child nodes. Extract data from the text nodes that are // the children of the associated name, price, and calories element nodes. for (var j = 0; j < nodeList.length ; j++) { var node = nodeList.item(j); if (node.nodeName == "name") { var name = node.firstChild.nodeValue; } if (node.nodeName == "price") { var price = node.firstChild.nodeValue; } if (node.nodeName == "calories") { var calories = node.firstChild.nodeValue; } // If the user chose to display descriptions and // the child node is "#cdata-section", grab the // contents of the description CDATA for display. if (node.nodeName == "description" && description==true) { if (node.firstChild.nodeName == "#cdata-section") var data = node.firstChild.nodeValue; } } // Append extracted data to the HTML string. html += "<i><b>"; html += name; html += "</b></i><br>"; html += "&emsp;"; html += price; html += " - "; // If "calories" is greater than the user-specified calorie limit, // display it in red.

Page 43: documentacao - OpenSocial

if(calories > calorieLimit) { html += "<font color=#ff0000>"; html += calories + " calories"; html += " </font>"; } else html += calories + " calories"; html += "<br>"; // If user has chosen to display descriptions if (description==true) { html += "<i>" + data + "</i><br>"; } } // Close up div html += "</div>"; document.getElementById('content_div').innerHTML = html; }; gadgets.util.registerOnLoadHandler(makeDOMRequest); </script> ]]> </Content></Module>

Esta amostra de código ilustra quatro das principais funções usadas para interagir com dados DOM:

• getElementsByTagName(tagname)-- Para um documento DOM, retorna uma matriz dos nós de elemento cujos nomes correspondem a tagname. Você pode recuperar todos os nós de elemento de um arquivo usando o caractere curinga (*), por exemplo: response.getElementsByTagName("*").

• getElementById(id)-- Para um documento DOM, recupera um único nó por id. • getAttribute(attrib)-- Para um nó de elemento, retorna o atributo attrib. Por exemplo:

response.getElementsByTagName("menu").item(0).getAttribute("title"). • attributes -- Para um nó de elemento, retorna uma matriz dos atributos do nó.

Este exemplo mostra somente algumas das diferentes funções para a navegação em uma árvore DOM. Experimente algumas das outras funções que você usar, como lastChild, nextSibling, previousSibling e parentNode.

Uso de tipos de nó diferentesA chave para usar DOM de forma eficaz é compreender que, às vezes, há diferenças sutis entre diferentes tipos de nó.

Tipo de nó Descrição Valores

retornados Armadilhas

elemento Os blocos estruturais de um documento, como <p> , <b> ou <calories>.

nodeName: Qualquer texto entre os sinais de menor e maior. Por exemplo, o nodeName de <menu> é “menu”.

nodeType: 1

Um elemento tem nodeValue null. Para obter o valor de um nó de texto ou atributo associado a um elemento, é necessário ir para esses nós. Por exemplo: element.firstChild.nodeValue para texto e element.getAttribute(attrib) para atributos.

Page 44: documentacao - OpenSocial

nodeValue : null

textTexto. Um nó de texto é sempre inserido em um nó de elemento. Ele é filho do elemento.

nodeName: #text

nodeType: 3

nodeValue: Qualquer texto inserido no nó.

Alguns navegadores exibem todos os espaços em branco de um documento como nós de texto. Assim, seu objeto DOM irá conter nós de texto "vazios". Isso poderá gerar resultados inesperados quando você percorrer a árvore. Para solucionar esse problema, basta filtrar os nós de texto que contêm somente o caractere de nova linha. Ou você pode realizar uma manipulação mais robusta. Para ler mais sobre este tópico, consulte Espaços em branco no DOM.

atributo

Um par de chave-valor que fornece informações adicionais sobre um nó de elemento (por exemplo, title=”my document”). Um atributo é inserido em um nó de elemento, mas não é filho do nó de elemento.

nodeName: O valor à esquerda do par de atributo. Se o atributo for title=”my document”, nodeName será title.

nodeType: 2

nodeValue: O valor à direita do par de atributo (neste exemplo, “my document”).

Embora os atributos sejam nós e estejam inseridos em nós de elemento, eles não são nós-filho do elemento. Eles são herdados da interface de Node, mas o DOM não os considera parte da árvore DOM. Isso significa que, embora você possa usar muitas das funções de nó com os nós de atributo (como nodeName, nodeValue e nodeType), não é possível acessar nós de atributo usando as funções de navegação da árvore DOM. Para acessar os atributos, use as funções attributes e getAttribute(attrib).

CDATA

Uma seção na qual o conteúdo não é manipulado ou interpretado. 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.

nodeName: #cdata-section

nodeType: 4

nodeValue: Texto e markup dentro dos separadores CDATA.

O texto da seção CDATA tem seu próprio markup. Isso pode afetar o modo como você irá incorporá-lo ao gadget.

Outros recursos

• Núcleo DOM W3C • Tutorial do DOM JavaScript

Page 45: documentacao - OpenSocial

Uso de feedsAdicione um feed à sua página do iGoogle digitando seu URL no formulário Add by URL (Adicionar por URL) do diretório de conteúdo. Esse formulário utiliza o suporte integrado da API de gadgets para criar um gadget para o feed e adicioná-lo ao iGoogle. É fácil de usar, mas não permite qualquer personalização do conteúdo ou da exibição. Além disso, você não pode usá-lo com outros recipientes.

Para manipular feeds de maneira mais sofisticada, use o método makeRequest(). Embora a especificação dos gadgets para makeRequest() inclua um tipo de conteúdo FEED, este recurso ainda não é suportado por nenhum recipiente. Como alternativa, você pode processar um feed usando o tipo de conteúdo DOM, como mostrado abaixo.

O exemplo a seguir ilustra como usar a função makeRequest() para obter um feed e exibir partes de seus dados em um gadget. Aqui está o gadget. Ele permite que os usuários especifiquem:

• O número de entradas exibidas • Se o gadget exibirá a data e um resumo de cada entrada

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

// Get userprefs var prefs = new gadgets.Prefs(); var showdate = prefs.getBool("show_date"); var summary = prefs.getBool("show_summ"); var entries = prefs.getInt("num_entries");

Page 46: documentacao - OpenSocial

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

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

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

Page 47: documentacao - OpenSocial

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 JSONUse 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":"","signature_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;

Page 48: documentacao - OpenSocial

}; 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.

Page 49: documentacao - OpenSocial

Gadgets e internacionalização (i18n)Este documento descreve como criar gadgets que possam ser facilmente localizados para um público internacional.

IntroduçãoA 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ásicosEste documento refere-se à internacionalização (i18n) e à localização (l10n):

• Internacionalizar significa estruturar aplicativos de forma a possibilitar sua localização. • Localizar significa fazer um aplicativo funcionar para um mercado específico, como

canadenses francófonos.

Para a finalidade deste documento, o “perfil de localização” de um usuário consiste em dois componentes: um país (com base no domínio do usuário) e um idioma de interface preferido pelo usuário (consulte a seção Teste para obter mais detalhes).

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

ExemploO 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:

Page 50: documentacao - OpenSocial

Você pode ver a especificação do gadget Hello World aqui.

Criação de um gadget localizadoAs etapas básicas para a criação de um gadget localizado são:

1. Criar o gadget. 2. Extrair todo o texto que precisa de tradução e colocá-lo em pacotes de mensagens. 3. Encontrar alguém que possa ajudá-lo a traduzir o gadget. 4. O tradutor cria um novo pacote de mensagens para um local específico. Esse local pode ser

definido por idioma (francês) ou por idioma/país (francês/Canadá, francês/França). Os pacotes de mensagens em idiomas diferentes do inglês devem ser salvos no formato UTF-8.

5. O tradutor envia um URL do novo pacote a você. 6. Modifique a especificação do gadget para usar o pacote de mensagens. 7. Se o gadget estiver no diretório de conteúdo, aguarde de 1 a 2 semanas para que o indexador

e as informações possam encontrar seu gadget atualizado e você possa então disponibilizá-lo no novo mercado.

Pacotes de mensagensO 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.

Page 51: documentacao - OpenSocial

Convenções de nomenclaturaA 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áticasNão há requisitos rígidos a serem seguidos nas convenções de nomenclatura dos pacotes de mensagem. O gadget usa os atributos lang e country de <Locale> para identificar o arquivo de pacote de mensagens correto para o perfil do usuário. Ele não usa o nome do pacote de mensagens em si.

Entretanto, embora a API de gadgets ofereça muita flexibilidade, recomendamos que você siga estas orientações:

• Sempre forneça um pacote de mensagens ALL_ALL.xml ao lidar com mensagens padrão. • Especifique um local por idioma. Ou seja, use fr_ALL, de_ALL e assim por diante. • Se precisar ignorar locais específicos, use pacotes de mensagens idioma-país. Por exemplo,

se quiser fornecer um pacote de mensagens em inglês canadense para ignorar en_ALL, use en_CA e não ALL_CA.

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

<Locale> pode ter os seguintes atributos:

• messages: Um pacote de mensagens acessado através de um URL. • lang: O idioma para o qual as strings do pacote de mensagens foram traduzidas. • country: Não há exemplos desse atributo na especificação do gadget “Hello World”, mas

você também pode especificar um atributo de país. Por exemplo, este pacote de mensagens é configurado para usuários canadenses francófonos:

<Locale lang="fr" country="CA" messages="http://example.com/fr_CA.xml"/>

Durante a execução, o gadget usa o pacote de mensagens que melhor corresponda ao perfil do usuário.

Os valores válidos para o idioma são códigos de idioma ISO639-1 com dois dígitos e os valores

Page 52: documentacao - OpenSocial

válidos para o país são códigos ISO 3166-1 alfa-2.

Consulta às mensagensOs pacotes de mensagens possuem um recurso de consulta. Com o recurso de consulta às mensagens, o gadget tenta usar o pacote de mensagens que melhor corresponda ao país do usuário e ao idioma de preferência da IU (especificado no URL). Se o gadget não encontrar uma correspondência exata, ele "consulta" todos os pacotes de mensagens para encontrar a correspondência mais próxima.

Com a consulta às mensagens, você pode usar mensagens "padrão" (normalmente especificadas em ALL_ALL.xml), caso não haja um pacote disponível para um determinado local.

Por exemplo, imagine que o seu gadget contém a seguinte especificação:<Locale messages="http://x.com/ALL_ALL.xml"/> <Locale lang="de" messages="http://x.com/de_ALL.xml"/><Locale lang="de" country="DE" messages="http://x.com/de_DE.xml"/> <Locale lang="de" country="US" messages="http://x.com/de_US.xml"/>

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

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

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

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

A especificação do gadget “Hello World” usa a variável de substituição __MSG_ para indicar onde

Page 53: documentacao - OpenSocial

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

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

Exibição de mensagens no HTML do gadgetPara exibir as mensagens na parte XML do seu gadget, use as variáveis de substituição conforme discutido acima. Há algumas opções diferentes dentro da parte CDATA do gadget.

A técnica mais simples é incorporar a variável de substituição no HTML:<b>__MSG_hello_world__</b>.

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

Especificação do gadget Hello World Aqui está a especificação do gadget do exemplo "Hello World":<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="i18n Example"> <Locale messages="http://doc.examples.googlepages.com/ALL_ALL.xml"/> <Locale lang="de" messages="http://doc.examples.googlepages.com/de_ALL.xml"/> <Locale lang="zh-cn" messages="http://doc.examples.googlepages.com/zh_cn_ALL.xml"/> <Locale lang="fr" messages="http://doc.examples.googlepages.com/fr_ALL.xml"/> <Locale lang="ja" messages="http://doc.examples.googlepages.com/ja_ALL.xml"/> <Locale lang="es" messages="http://doc.examples.googlepages.com/es_ALL.xml"/> <Locale lang="it" messages="http://doc.examples.googlepages.com/it_ALL.xml"/> <Locale lang="ru" messages="http://doc.examples.googlepages.com/ru_ALL.xml"/

Page 54: documentacao - OpenSocial

> </ModulePrefs> <UserPref name="fontcolor" display_name="__MSG_color__" default_value="Red" datatype="enum"> <EnumValue value="Red" display_value="__MSG_red__" /> <EnumValue value="Green" display_value="__MSG_green__" /> <EnumValue value="Blue" display_value="__MSG_blue__" /> <EnumValue value="Gray" display_value="__MSG_gray__" /> <EnumValue value="Purple" display_value="__MSG_purple__" /> <EnumValue value="Black" display_value="__MSG_black__" /> </UserPref> <Content type="html"> <![CDATA[ <div id="content_div"></div> <script type="text/javascript"> // Display message in the user's preferred language function displayMsg(){ var div = document.getElementById('content_div'); // Get userprefs var prefs = new gadgets.Prefs(); // Set font color to user's color choice div.style.color = prefs.getString("fontcolor"); // Display message var html = "<br><h1>"; // Use prefs.getMsg to go to the appropriate message bundle // and get the string associated with the "hello_world" message. html += prefs.getMsg("hello_world"); html += "</h1>"; div.innerHTML = html; } gadgets.util.registerOnLoadHandler(displayMsg); </script> ]]> </Content></Module>

Criação de gadgets bidirecionaisUse a API BIDI (bidirecional) para alterar dinamicamente a direção de um gadget. "Direção" refere-se à direção na qual o conteúdo é exibido: esquerda para a direita ou direita para a esquerda. Isso é diferente de alinhamento. Por exemplo, você pode criar um gadget com texto em inglês alinhado à direita, mas a direção do texto em si é da esquerda para a direita.

A API BIDI possibilita criar gadgets que suportem idiomas da direita para a esquerda (como hebraico e árabe) e idiomas da esquerda para a direita (como inglês). A API BIDI inclui:

• Um atributo language_direction dentro da tag <Locale...>. Seu valor pode ser "rtl" (direita para a esquerda) ou "ltr" (esquerda para a direita). Use esse atributo para definir a direção do gadget. Como padrão, a direção dos gadgets é da esquerda para a direita.

• Um conjunto de variáveis de substituição __BIDI_... cujos valores são alterados dependendo da direção do gadget. Por exemplo, a variável __BIDI_DIR__ tem valor "ltr" quando o gadget está no modo da esquerda para a direita e "rtl" quando o gadget está no modo da direita para a esquerda.

No caso mais simples, use <Locale... language_direction="rtl"> para definir estaticamente a direção de um gadget. Por exemplo, este gadget exibe somente texto em hebraico. Portanto, sua direção é sempre da direita para a esquerda:<?xml version="1.0" encoding="UTF-8" ?><Module>

Page 55: documentacao - OpenSocial

<ModulePrefs title="כותרת two-כיוונית" height="100"> <Locale lang="ALL" language_direction="rtl" /> </ModulePrefs> <Content type="html"><![CDATA[ אני כותב מימין לשמאל ולא הייתי צריך להגדיר dir=rtl בשביל זה!<br> ]]> </Content></Module>

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

Para este gadget, suponha que o idioma de preferência do usuário seja árabe. A linha <Locale lang="ar" messages="http://.../ar_ALL.xml" language_direction="rtl"/> diz "para árabe, exibir o texto do pacote de mensagens ar_ALL.xml e definir a direção do gadget como rtl." A direção para o hebraico também será da direita para a esquerda. Para outros idiomas, a direção do é implicitamente definida com o padrão ltr (esquerda para a direita).

A linha <div style="margin-__BIDI_START_EDGE__:30px;"><h2>__MSG_hello_world__</h2></div> diz "quando o gadget estiver em modo da esquerda para a direita, deslocar o texto 30 pixels em relação à margem esquerda. Quando o gadget estiver em modo da direita para a esquerda, deslocar o texto 30 pixels em relação à margem direita". Por exemplo, se a configuração do navegador do usuário for árabe (direita para a esquerda), a substituição realizada na execução ficará assim: <div style="margin-right:30px;"><h2>بالعال xأهل</h2></div>

Page 56: documentacao - OpenSocial

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

__BIDI_START_EDGE__

Esta variável representa o lado do gadget que é o ponto inicial da exibição do conteúdo. O valor será "left" (esquerda) quando o gadget estiver em modo LTR e "right" (direita) 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.

__BIDI_END_EDGE__

Esta variável representa a lateral do gadget oposta ao lado de início da exibição do conteúdo. O valor será "right" (direita) quando o gadget estiver em modo LTR e "left" (esquerda) quando o gadget estiver em modo RTL.

__BIDI_DIR__

O valor desta variável será "ltr" quando o gadget estiver em modo LTR e "rtl" quando o gadget estiver em modo RTL.

__BIDI_REVERSE_DIR__

O valor desta variável será "rtl" quando o gadget estiver em modo LTR e "ltr" quando o gadget estiver em modo RTL.

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

<Content type="html"><![CDATA[ <script type="text/javascript"> // In this gadget, users choose a language from a drop-down menu, and the gadget displays // a "Hello World" message for the selected language. The gadget uses DOM functions to set // the direction and formatting for the message, depending on whether its

Page 57: documentacao - OpenSocial

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>

Page 58: documentacao - OpenSocial

TestePara testar o gadget, altere a configuração de país e idioma de modo que ela corresponda aos pacotes de mensagens incluídos em seu gadget.

A maneira mais simples de alterar a configuração de país e idioma no iGoogle é editar o URL:http://www.google.com/ig?&gl=<country>&hl=<lang>

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

Neste exemplo, o país é implicitamente EUA e o idioma é espanhol: http://www.google.com/ig?hl=es

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

CacheOs 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 problemasDurante 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.

Page 59: documentacao - OpenSocial

Gadgets em idiomas diferentes do inglêsA maioria dos exemplos deste guia do desenvolvedor foi criada em inglês. Este documento descreve recursos disponíveis para usuários interessados em criar gadgets em outros idiomas.

Onde posso encontrar gadgets que não sejam em inglês? Uma das características mais úteis dos gadgets é a visibilidade pública de seu código-fonte. Você pode aprender muito sobre o desenvolvimento de gadgets observando como outros gadgets são implementados.

Para encontrar gadgets criados em um idioma específico, faça uma filtragem no diretório de conteúdo do iGoogle com base no país e idioma de sua preferência. Você pode usar o menu More Languages (Mais idiomas) no diretório de conteúdo ou especificar os códigos de idioma e país no URL. Por exemplo, para ver gadgets em japonês, use este URL:http://www.google.com/ig/directory?&gl=JP&hl=ja&root=/ig&dpos=top

O parâmetro para o código do país é &gl e o parâmetro para o código do idioma é &hl. Neste exemplo, o código do país (Japão) é JP, e o código do idioma japonês é ja (por padrão, os códigos de idioma estão em letras minúsculas e os códigos de país em letras maiúsculas, mas isso não é obrigatório). O conteúdo do diretório varia ligeiramente se você fornecer somente o código do país ou do idioma. Portanto, inclua ambos os códigos (de país e idioma) para obter resultados mais específicos.

Uma boa maneira de encontrar gadgets em um idioma específico é filtrar o diretório. Entretanto, isso não retorna somente os gadgets criados no idioma de destino, pois os gadgets não recebem tags de idioma. A API de gadgets inclui uma tag <Locale>, mas esta é opcional. O diretório exibe gadgets para um local específico com base em sua popularidade. Portanto, ao exibir o diretório do local Japão/japonês, por exemplo, você verá principalmente gadgets japoneses. Mas também poderá ver gadgets populares neste local, apesar de não serem em japonês.

No diretório de conteúdo do iGoogle, você pode adicionar gadgets à sua página do iGoogle. Após adicioná-los ao iGoogle, você poderá visualizar o código-fonte dos gadgets clicando em seus links na página de gadgets do desenvolvedor. Os gadgets não personalizados (por exemplo, gadgets que apenas exibem feeds) não estão listados na página de gadgets do desenvolvedor.

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

Se criar um gadget que suporte diversos idiomas, as strings das mensagens traduzidas serão armazenadas em arquivos XML externos denominados pacotes de mensagens. Os pacotes de mensagens contendo as strings traduzidas para cada local suportado pelo gadget devem ser salvos expressamente no formato UTF-8.

Consulte a documentação Internacionalização para obter informações detalhadas sobre como criar gadgets em diversos idiomas.

Page 60: documentacao - OpenSocial

Publicação do seu gadgetEste documento descreve as diferentes opções de publicação do seu gadget. Se você usa o Google Gadgets Editor (GGE) para criar e hospedar gadgets, a publicação dos seus gadgets ficará muito mais fácil.

Onde posso colocar meu gadget?Você pode colocar seus gadgets em qualquer um dos lugares a seguir:

• Nas sua página e nas páginas de seus amigos no iGoogle. • Em outros recipientes de rede social que suportam gadgets, como o Orkut. • No diretório de conteúdo do Google. Se você enviar seu gadget ao diretório de conteúdo, ele

ficará disponível para um público maior.

Nem todo gadget é adequado a todos os ambientes. Consulte a documentação do recipiente para obter detalhes sobre os recursos suportados no ambiente específico.

Preparação para a publicação Você deve testar seu gadget antes de publicá-lo, levando em consideração os requisitos e limitações do ambiente no qual o gadget será executado.

Faça os testes abaixo para todos os gadgets:

• Tente todas as combinações de valores de UserPref. • Execute-o em telas de tamanhos diferentes, desde 800x600 até a maior largura possível.

Vincule à extensão de desenvolvedor da web do Firefox, o que facilita o redimensionamento do Firefox para um tamanho específico.

• Teste seu gadget em diferentes tamanhos, conforme descrito na seção Teste de largura e altura.

• Teste seu gadget em todos os ambientes onde possa ser executado. • Teste seu gadget nos navegadores IE 7, IE 6, Firefox 2.x, Firefox 1.5.x, IE 7, IE 6, Opera 9.x

e Safari 2.x. • Experimente tamanhos de fonte diferentes:

• Para alterar o tamanho da fonte no Firefox, selecione Ferramentas > Opções > Conteúdo. Clique em Avançado na seção "Fontes e cores". Altere a configuração de fonte e desmarque "Páginas podem usar outras fontes".

• Para alterar o tamanho da fonte no Internet Explorer, selecione Ferramentas > Opções da Internet > Geral. Use as caixas de diálogo Fontes e Acessibilidade para alterar sua configuração de fontes.

Se estiver usando makeRequest(), verifique o que acontece se a fonte de dados estiver inacessível ou retornar um erro. Você pode simular isso alterando o URL temporariamente.

Teste de largura e altura O dimensionamento de um gadget depende principalmente de onde ele será executado. Consulte a documentação do seu recipiente para obter mais detalhes.

Ao criar e testar seus gadgets, prepare-se para larguras arbitrárias que podem variar de 200 a até mesmo 600 pixels. A largura deve ser ainda maior em determinados gadgets. Como regra geral, crie o gadget para ser exibido adequadamente caso haja mais espaço. Por exemplo, os gadgets de mapas devem preencher suas áreas, os gadgets de imagem devem ficar centralizados no frame e os gadgets

Page 61: documentacao - OpenSocial

de texto devem manter o texto no alto (por exemplo, links do tipo "clique para obter mais detalhes", que normalmente são na parte inferior da página, devem permanecer próximos ao conteúdo, em vez de serem colocados na parte inferior da janela do gadget).

Aperfeiçoamento do desempenho do gadget Se ao criar um gadget você espera causar tráfego intenso, há etapas que podem ser seguidas para assegurar disponibilidade e um bom desempenho. Procure seguir as dicas desta seção caso seu gadget tenha mais de 200.000 visualizações por dia ou aproximadamente 1 a 2 solicitações por segundo. Mesmo um gadget de 50 KB recebendo 200.000 solicitações por dia consome cerca de 300 GB de largura de banda por mês.

Há motivos diferentes que podem tornar um gadget atraente para muitos usuários. Ele pode simplesmente tornar-se popular no diretório de conteúdo. Ou ainda, ser usado em uma promoção especial ou em publicidade, o que pode causar um excesso de tráfego.

No caso de um gadget de tráfego intenso, sua meta deve ser exibi-lo em 0,25 s (250 milissegundos) ou menos. Use o Firebug (somente Firefox) para calcular o tempo. Uma excelente maneira de ter impacto positivo sobre a experiência do usuário é melhorar a capacidade de resposta do seu gadget. Consulte Otimização para tráfego intenso para obter dicas sobre como otimizar o desempenho do gadget. Para obter dicas sobre gerenciamento, consulte Gerenciamento de tráfego intenso. As orientações gerais de teste também são especialmente importantes para gadgets muito populares.

Otimização para tráfego intenso Se você acha que seu gadget poderá causar tráfego intenso, siga as orientações abaixo:

• Evite usar arquivos JavaScript ou CSS externos (arquivos que contêm atributos "src" ou "href" nas tags HTML), pois isso requer o uso de outra conexão de rede. Em vez disso, coloque seu código JavaScript e CSS dentro das especificações do gadget.

• Use um gadget type=html. Os gadgets type=url geralmente são exibidos mais lentamente que os gadgets type=html, devido ao desempenho e suporte a cache ruins de outros servidores de hospedagem.

• Como padrão, o método makeRequest() armazena o conteúdo em cache por aproximadamente 1 a 2 horas. Você pode usar o parâmetro refreshInterval com essas funções para atualizar o cache com mais freqüência. Entretanto, o uso de cache melhora o desempenho do gadget, minimizando o número de solicitações enviadas aos servidores remotos que hospedam o conteúdo. Não solicite um número de atualizações de cache maior que o necessário, pois você reduzirá a porcentagem de solicitações suportadas pelo cache. Para uma discussão mais profunda sobre este tópico, consulte Atualização do cache.

• Use o Firebug (somente Firefox) para ajustar o desempenho do seu gadget. Para outros navegadores, use o Fiddler.

• Se possível, evite usar o Google Analytics, pois ele requer uma conexão adicional ao servidor. Em vez do Analytics, use http://www.google.com/ig/directory?url=<gadget-url> para verificar o total semanal de visualizações de página do seu gadget.

• Especifique a altura e a largura de todas as tags <img> no HTML do gadget. Isso agiliza a exibição do gadget. Se você estiver usando gadgets.io.getProxyUrl() e inserindo o elemento imagem diretamente no DOM, não é necessário definir as propriedades de largura e altura.

• Em vez de conectar-se diretamente ao seu provedor de hospedagem, use a função gadgets.io.getProxyUrl() para armazenar todas as imagens incorporadas em cache e a função embedCachedFlash() para armazenar o conteúdo Flash em cache. Veja abaixo um exemplo de gadget que carrega as imagens previamente usando gadgets.io.getProxyUrl():

Page 62: documentacao - OpenSocial

Aqui está um exemplo de gadget que ilustra como usar gadgets.io.getProxyUrl(): <?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs title="Zombies!" height="350" /> <Content type="html"> <![CDATA[ <div id="zombiecontainer" style="text-align:center;"> </div> <script type="text/javascript"> var counter = 0;

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

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

var images = load(files); browse();

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

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

Gerenciamento de tráfego intenso Estas orientações podem ajudá-lo a gerenciar um gadget de alto volume de tráfego:

• Se estiver recebendo uma grande quantidade de e-mails dos usuários do seu gadget, use o

Page 63: documentacao - OpenSocial

Gmail para configurar filtros e gerenciar o volume. Recomendamos o uso de um endereço no formato <username>.feedback+<gadgetname>@gmail.com na especificação do seu gadget. Isso ajuda a filtrar as mensagens recebidas dos usuários do gadget. O Gmail ignora tudo o que está depois do sinal de mais (+), fazendo com que o endereço de e-mail seja mapeado para <username>[email protected]. O Gmail tem um filtro de spams de alta qualidade.

• Se você enviar seu gadget ao diretório de conteúdo do iGoogle, visite periodicamente a página de descrição do seu gadget para ler os comentários dos usuários. Freqüentemente, os usuários deixam um feedback valioso, fazem solicitações e relatam bugs que encontraram ao usar o gadget. É bom ficar a par de seus comentários e manter contato com eles.

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

Etapa 1: Defina as preferências do seu gadget.A Referência lista todos os atributos <ModulePrefs> que podem ser usados para fornecer informações "meta" sobre seu gadget. Aqui estão as informações que você deve incluir na especificação do seu gadget:

• title • description. Este atributo é importante para que as pessoas saibam o que seu gadget faz,

particularmente se isso não for óbvio. • author • author_email. Use esse atributo para que o Google e os usuários possam entrar em contato

com você. Você pode usar qualquer sistema de e-mail. Evite usar um endereço de e-mail pessoal devido aos spams. Uma boa estratégia é usar um endereço de e-mail com o formato [email protected] na especificação do seu gadget. O Gmail ignora tudo o que está depois do sinal de mais (+), fazendo com que o endereço de e-mail seja mapeado para [email protected]. Crie uma conta do Gmail aqui.

• screenshot. Esta é uma string que fornece o URL de uma captura de tela do gadget. O URL deve ser bem formado, e não relativo. Esta imagem deve estar em um site público da web não bloqueado por robots.txt. O formato preferido é PNG, embora os formatos GIF e JPG também sejam aceitáveis. As capturas de tela de gadgets devem ter 280 pixels de largura. A altura da captura de tela deve ser a altura "natural" do gadget quando em uso. Isso ajuda o usuário a identificar quanto espaço de sua tela será consumido pelo gadget antes de adicioná-lo à sua página. A captura de tela não deve ter nenhum espaço em branco acima da barra de cabeçalho azul do gadget. As capturas de tela devem mostrar apenas o gadget completo, incluindo sua barra de título. Como alternativa, faça uma captura de tela do gadget com a janela de edição aberta. Não redimensione ou corte as capturas de tela. Para manter a qualidade e a consistência, o Google pode fazer suas próprias capturas de tela relativas a um gadget específico.

• thumbnail. No diretório de conteúdo, as miniaturas permitem que os usuários possam visualizar um gadget. Elas devem captar a funcionalidade principal do gadget sem mostrá-lo totalmente. O valor deste atributo é uma string que fornece o URL da miniatura de um gadget. O URL deve ser bem formado, e não relativo. Esta imagem deve estar em um site público da web não bloqueado por robots.txt. O formato preferido é PNG, embora os formatos GIF e JPG também sejam aceitáveis. As miniaturas devem medir 120x60 pixels.

Page 64: documentacao - OpenSocial

Elas não devem incluir a barra de título. • author_location • author_affiliation • title_url. Use este atributo para vincular o título do seu gadget a uma página HTML externa.

Por exemplo, se o gadget for o front end de um serviço, vincule o título do gadget ao site do serviço.

• directory_title (obrigatório se o título tiver variáveis de substituição de preferências do usuário).

Se você deseja ser incluído na página de autores, adicione estes campos:

• author_photo. URL para uma foto (o formato preferido é 70x100 PNG, mas JPG/GIF também são suportados).

• author_aboutme. Um texto sobre si mesmo (tente limitar em aproximadamente 500 caracteres).

• author_link. Um link para o seu site, blog, etc. • author_quote. Uma citação que você queira incluir (tente limitar em aproximadamente 300

caracteres).

Encontre mais informações aqui e um exemplo aqui.

Etapa 2: Verifique se criou um gadget robusto e seguro.Verifique se codificou seu gadget de maneira a minimizar os riscos de segurança.

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

Etapa 4: Adicione todas as informações relevantes de local. Use as tags <Locale> em <ModulePrefs> para especificar os locais suportados pelo seu gadget. Para obter mais informações, consulte Especificação dos locais.

Etapa 5: Facilite o processo de adição do seu gadget.Para promover um gadget, coloque nele um botão "Adicionar ao Google".

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

Gerenciamento dos gadgets enviados Se você enviou diversas versões de um gadget em diferentes URLs e deseja designar uma versão como a oficial, use a página Enviar uma solicitação de alias.

Page 65: documentacao - OpenSocial

Referência da API de gadgetsEsta é a referência para a API de gadgets.*. Ela inclui informações de referência para a especificação XML do gadget.

Você pode ver a Referência de JavaScript aqui.

Observação: A API de gadgets foi inserida no namespace JavaScript de gadgets.*, para fornecer uma API mais limpa para programação e suporte. Se você estiver interessado em compreender melhor a API de gadgets.*, leia a Especificação do Gadgets.

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

Preferências do gadgetA 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="[email protected]"/> <Content ...> ... content ... </Content> </Module>

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

A tabela abaixo lista os atributos <ModulePrefs>:

Atributo Descrição

title

String opcional que fornece o título do gadget. Esse título é exibido na barra de título do gadget no iGoogle. Se esta string contém variáveis de substituição de preferências do usuário e você pretende enviar seu gadget ao diretório de conteúdo do iGoogle, forneça também um directory_title para ser exibido no diretório.

directory_title

String opcional que fornece o título do gadget a ser exibido no diretório de conteúdo do iGoogle. Deve conter somente o texto que será realmente exibido, sem variáveis de substituição de preferências do usuário. Isso é importante porque o diretório de conteúdo do iGoogle exibe uma versão estática do seu gadget. Portanto, ele não pode executar a substituição necessária para fornecer um título aceitável. Por exemplo, Se o título do seu gadget for "Friends for __UP_name__", o diretório não é capaz de executar a substituição para fornecer um valor aceitável para " __UP_name__". Assim, configure directory_title simplesmente como "Friends".

title_url String opcional que fornece um URL de link do título do gadget. Por exemplo, você pode vincular o título a uma página da web relacionada ao gadget.

description String opcional que descreve o gadget.

Page 66: documentacao - OpenSocial

author String opcional que revela o autor do gadget.

author_email

String opcional que fornece o endereço de e-mail do autor do gadget. Você pode usar qualquer sistema de e-mail. Evite usar um endereço de e-mail pessoal devido aos spams. Uma boa estratégia é usar um endereço de e-mail com o formato [email protected] na especificação do gadget.

O Gmail ignora tudo o que está depois do sinal de mais (+), fazendo com que o endereço de e-mail seja interpretado como [email protected].

Crie uma conta do Gmail aqui.author_affiliation

Seqüência opcional, como "Google", que indica a afiliação do autor. Esse atributo é necessário para gadgets incluídos no diretório de conteúdo do iGoogle.

author_location A localização geográfica do autor, como "Mountain View , CA, EUA ".

screenshot

String opcional que fornece o URL de uma captura de tela do gadget. Esta imagem deve estar em um site público da web não bloqueado por robots.txt. O formato preferido é PNG, embora os formatos GIF e JPG também sejam aceitáveis. As capturas de tela de gadgets devem ter 280 pixels de largura. A altura da captura de tela deve ser a altura "natural" do gadget quando em uso. Para ler mais sobre diretrizes de captura de tela, consulte Publicação no diretório de conteúdo do iGoogle.

thumbnail

String opcional que fornece o URL de uma miniatura do gadget. Esta imagem deve estar em um site público da web não bloqueado por robots.txt. O formato preferido é PNG, embora os formatos GIF e JPG também sejam aceitáveis. As miniaturas de gadget devem medir 120x60 pixels. Para ler mais sobre diretrizes de miniatura, consulte Publicação no diretório de conteúdo do iGoogle.

height Número inteiro positivo opcional que especifica a altura da área na qual o gadget será executado. A altura padrão é 200.

width Número inteiro positivo opcional que especifica a largura da área na qual o gadget será executado. A largura padrão é 320.

scaling

Valor booleano opcional que especifica se a proporção (razão entre altura e largura) do gadget será mantida quando o navegador for redimensionado. Os gadgets que podem ser redimensionados automaticamente devem ter este valor configurado como true. Já os gadgets com altura fixa devem ter este valor configurado como false. O padrão é true.

scrolling Valor booleano opcional que fornece barras de rolagem vertical e/ou horizontal caso o conteúdo exceda o espaço fornecido. Se configurado como false, o conteúdo é recortado segundo a altura e a largura fornecidas (observe que a largura não é configurável). O padrão é false.

singleton Valor booleano opcional que especifica se o usuário pode adicionar um gadget várias vezes a partir de um mesmo diretório. O padrão é true. Isso significa que, como padrão, os gadgets podem ser adicionados somente uma vez. Entretanto, os diretórios podem manipular este atributo como desejarem. Por exemplo, o diretório de conteúdo do iGoogle manipula o atributo singleton="true" desabilitando (a cor fica esmaecida) os gadgets que já foram adicionados e exibindo o texto "Added" (Adicionado) ao lado de cada gadget. As alterações neste atributo podem não ser atualizadas imediatamente nos diretórios.

Este atributo não impede que os usuários adicionem gadgets diversas vezes

Page 67: documentacao - OpenSocial

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_aboutme

Para a página de autores, um texto sobre si mesmo (tente limitar em 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 bibliotecasPara 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 locaisUse 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

Page 68: documentacao - OpenSocial

lang String opcional, indicando o idioma associado ao local.country String opcional, indicando o país associado ao local.

messagesString opcional que é um URL apontando para um pacote de mensagens. Os 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.

language_direction

String opcional que define a direção do gadget. Seu valor pode ser "rtl" (direita para a esquerda) ou "ltr" (esquerda para a direita). O padrão é "ltr". Este atributo permite criar gadgets que suportam idiomas lidos da esquerda para a direita e vice-versa. Para ler mais sobre este tópico, consulte Criação de gadgets bidirecionais. Você pode usar as variáveis de substituição descritas abaixo em conjunto com o atributo language_direction:

• __BIDI_START_EDGE__: O valor é "left" (esquerda) quando o gadget estiver em modo LTR e "right" (direita) quando o gadget estiver em modo RTL.

• __BIDI_END_EDGE__: O valor é "right" (direita) quando o gadget estiver em modo LTR e "left" (esquerda) quando o gadget estiver em modo RTL.

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

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

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

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

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

A tabela abaixo lista os atributos <MayRequire>:

Atributo Descrição

type String obrigatória indicando o tipo de requisito. Os tipos suportados são "platform", "browser" e "plugin".

value String obrigatória que fornece um valor para o tipo. Por exemplo, type="plugin" value="flash".

min_version String opcional indicando o número mínimo de versão do item obrigatório.

cdata String opcional que fornece informações adicionais sobre o requisito.

Page 69: documentacao - OpenSocial

Preferências do usuário Alguns gadgets precisam fornecer um meio de informações específicas ao usuário serem inseridas. Por exemplo, um gadget de condições climáticas pode exigir que o usuário forneça seu código postal. A seção de preferências do usuário (<UserPref>) do arquivo XML descreve os campos de entrada do usuário que são transformados em controles da interface de usuário quando o gadget é executado.

A tabela abaixo lista os atributos <UserPref>:

Atributo Descrição

name O nome "simbólico" obrigatório da preferência do usuário, exibido durante a edição caso não haja nenhum display_name definido. Deve conter somente letras, números e caracteres de sublinhado, isto é, a expressão regular ^[a-zA-Z0-9_]+$. Deve ser exclusivo.

display_name

String opcional para ser exibida ao lado das preferências do usuário na janela de edição. Deve ser exclusivo.

urlparam String opcional para passar como o nome do parâmetro para conteúdo type="url".

datatype String opcional indicando o tipo de dados deste atributo. Pode ser string, bool, enum, hidden (uma string invisível e não editável pelo usuário), list (uma matriz dinâmica gerada a partir de dados inseridos pelo usuário) ou location (para gadgets baseados no Google Maps). O padrão é string.

required Argumento booleano opcional (true ou false) indicando se esta preferência do usuário é obrigatória. O padrão é false.

default_value String opcional que indica o valor padrão das preferências de um usuário.

Use a API JavaScript para acessar as preferências do usuário a partir do seu gadget; por exemplo:<script type="text/javascript"> var prefs = new _IG_Prefs(); var someStringPref = prefs.getString("StringPrefName"); var someIntPref = prefs.getInt("IntPrefName"); var someBoolPref = prefs.getBool("BoolPrefName");</script>

Tipos de dados EnumUm dos valores que você pode especificar para o atributo datatype de <UserPref> é enum. O tipo de dados enum é apresentado na interface de usuário como um menu de opções. Especifique o conteúdo do menu usando <EnumValue>.

Por exemplo, esta <UserPref> permite que os usuários definam o nível de dificuldade de um game. Cada valor que aparece no menu (Easy, Medium e Hard) é definido por meio de uma tag <EnumValue>. <UserPref name="difficulty" display_name="Difficulty" datatype="enum"

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

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

Page 70: documentacao - OpenSocial

A tabela abaixo lista os atributos <EnumValue>:

Atributo Descrição

value String obrigatória que fornece um valor exclusivo. Este valor é exibido no menu da caixa de edição das preferências do usuário, a menos que um display_value seja fornecido.

display_value

String opcional que é exibida no menu da caixa de edição de preferências do usuário. Se você não especificar um display_value, o value é exibido na interface do usuário.

Seção de conteúdo A seção <Content> define o tipo de conteúdo e contém o próprio conteúdo ou uma referência para conteúdo externo. A seção <Content> é onde os atributos do gadget e as preferências do usuário são combinados à lógica de programação e às informações de formatação para se transformarem em um gadget executável. Para ler mais sobre tipos de conteúdo, consulte Seleção do tipo de conteúdo.

A tabela abaixo lista os atributos <Content>:

Atributo Descrição

type String opcional que fornece o tipo de conteúdo. Os valores possíveis são html e url. O padrão é html.

href String que fornece um URL de destino. Obrigatório para type="url" e não permitido com outros tipos de conteúdo.

cdata String opcional. Para HTML, contém o HTML puro que será exibido no iframe.

Page 71: documentacao - OpenSocial

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

Page 72: documentacao - OpenSocial

gadgets.Prefs

Classe gadgets.PrefsFornece 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 construtorgadgets.Prefs(opt_moduleId)

Cria um novo objeto Prefs.

Resumo do métodoArray.<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.

Page 73: documentacao - OpenSocial

Detalhes do construtor

gadgets.Prefsgadgets.Prefs(opt_moduleId)

Cria um novo objeto Prefs.

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

Detalhes do método

getArrayArray.<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

getBoolBoolean getBool(key)

Recupera uma preferência booleana.

Parâmetros: String key - A preferência a ser obtida

Retorna: Boolean A preferência; se não estiver definida, false (falso)

getCountryString getCountry()

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

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

getFloatNumber getFloat(key)

Recupera uma preferência de ponto flutuante.

Parâmetros:

Page 74: documentacao - OpenSocial

String key - A preferência a ser obtida

Retorna: Number A preferência; se não estiver definida, 0

getIntNumber getInt(key)

Recupera uma preferência de número inteiro.

Parâmetros: String key - A preferência a ser obtida

Retorna: Number A preferência; se não estiver definida, 0

getLangString 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

getModuleIdString, Number getModuleId()

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

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

getMsgString getMsg(key)

Obtém uma mensagem não formatada.

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

Retorna: String A mensagem

getMsgFormattedString 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:

Page 75: documentacao - OpenSocial

String key - A mensagem a ser obtida String opt_subst - Uma string opcional para ser substituída na mensagem

Retorna: String A string formatada

getStringString getString(key)

Recupera uma preferência de string.

Parâmetros: String key - A preferência a ser obtida

Retorna: String A preferência; se não estiver definida, uma string vazia

setset(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

setArraysetArray(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

Page 76: documentacao - OpenSocial

gadgets.io

Static Class gadgets.io

Fornece funções de recuperação de conteúdo remoto.

Resumo do método<static> String encodeValues(fields)

Converte um objeto de entrada em uma string de dados codificada como URL. <static> String getProxyUrl(url)

Obtém a versão proxy do URL passado. <static> makeRequest(url, callback, opt_params)

Obtém o conteúdo a partir do URL fornecido e alimenta este conteúdo na função de retorno de chamada.

Detalhes do método

encodeValues<static> String encodeValues(fields)

Converte um objeto de entrada em uma string de dados codificada como URL. (chave=valor&...)

Parâmetros: Object fields - Os campos de postagem que você deseja codificar

Retorna: String Os dados de postagem processados; isso inclui um E comercial (&) no final

getProxyUrl<static> String getProxyUrl(url)

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

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

Retorna: String A versão do URL com o proxy

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

Obtém o conteúdo a partir do URL fornecido e alimenta este conteúdo na função de retorno de chamada. Exemplo: var params = {};

Page 77: documentacao - OpenSocial

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

Page 78: documentacao - OpenSocial

gadgets.io.AuthorizationType

Static Class gadgets.io.AuthorizationTypeUsada por RequestParameters.

Resumo do campo<static> object AUTHENTICATED

O recipiente usará autenticação completa. <static> object NONE

Sem autorização. <static> object SIGNED

A solicitação será assinada pelo recipiente.

Detalhes do campo

AUTHENTICATED<static> object AUTHENTICATED

O recipiente usará autenticação completa.

NONE<static> object NONE

Sem autorização.

SIGNED<static> object SIGNED

A solicitação será assinada pelo recipiente.

Page 79: documentacao - OpenSocial

gadgets.io.ContentType

Static Class gadgets.io.ContentTypeUsada por RequestParameters.

Resumo do campo<static> object DOM

Retorna um objeto DOM; usado para obter XML. <static> object FEED

Retorna uma representação JSON de um feed. <static> object JSON

Retorna um objeto JSON. <static> object TEXT

Retorna texto; usado para obter HTML.

Detalhes do campo

DOM<static> object DOM

Retorna um objeto DOM; usado para obter XML.

FEED<static> object FEED

Retorna uma representação JSON de um feed.

JSON<static> object JSON

Retorna um objeto JSON.

TEXT<static> object TEXT

Retorna texto; usado para obter HTML.

Page 80: documentacao - OpenSocial

gadgets.io.MethodType

Static Class gadgets.io.MethodTypeUsada por RequestParameters.

Resumo do campo<static> object DELETE

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

O tipo padrão. <static> object HEAD

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

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

Não suportado por todos os recipientes.

Detalhes do campo

DELETE<static> object DELETE

Não suportado por todos os recipientes.

GET<static> object GET

O tipo padrão.

HEAD<static> object HEAD

Não suportado por todos os recipientes.

POST<static> object POST

Não suportado por todos os recipientes.

PUT<static> object PUT

Não suportado por todos os recipientes.

Page 81: documentacao - OpenSocial

gadgets.io.RequestParameters

Static Class gadgets.io.RequestParametersUsada pelo método gadgets.io.makeRequest().

Resumo do campo<static> object AUTHORIZATION

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

<static> object CONTENT_TYPE O tipo de conteúdo que reside no URL; o padrão é ContentType.TEXT.

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

<static> object HEADERS Os cabeçalhos HTTP a serem enviados ao URL; o padrão é null (nulo).

<static> object METHOD O método a ser usado durante a obtenção de conteúdo a partir do URL; o padrão é MethodType.GET.

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

<static> object POST_DATA Os dados a serem enviados ao URL usando o método POST; o padrão é null (nulo).

Detalhes do campo

AUTHORIZATION<static> object AUTHORIZATION

O tipo de autenticação a ser usada durante a obtenção do conteúdo; o padrão é AuthorizationType.NONE. Especificado como um Tipo de autorização.

CONTENT_TYPE<static> object CONTENT_TYPE

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

GET_SUMMARIES<static> object GET_SUMMARIES

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

Page 82: documentacao - OpenSocial

HEADERS<static> object HEADERS

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

METHOD<static> object METHOD

O método a ser usado durante a obtenção de conteúdo a partir do URL; o padrão é MethodType.GET. Especificado como um Tipo de método.

NUM_ENTRIES<static> object NUM_ENTRIES

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

POST_DATA<static> object POST_DATA

Os dados a serem enviados ao URL usando o método POST; o padrão é null (nulo). Especificado como um String.

Page 83: documentacao - OpenSocial

gadgets.json

Static Class gadgets.jsonFornece operações de conversão de objetos de e para JSON.

Resumo do método<static> Object parse(text)

Analisa uma string JSON, produzindo um valor JavaScript. <static> String stringify(v)

Converte um valor JavaScript em uma string JSON.

Detalhes do método

parse<static> Object parse(text)

Analisa uma string JSON, produzindo um valor JavaScript.

Parâmetros: String text - A string que será convertida em um objeto — normalmente, o resultado de uma chamada stringify anterior

Retorna: Object O objeto analisado do texto passado; false (falso) se ocorreu um erro

stringify<static> String stringify(v)

Converte um valor JavaScript em uma string JSON.

Parâmetros: Object v - O objeto a ser convertido

Retorna: String O JSON equivalente

Page 84: documentacao - OpenSocial

gadgets.util

Static Class gadgets.utilFornece funções de utilitário de uso geral.

Resumo do método<static> String escapeString(str)

Cria códigos de escape para os dados inseridos, usando entidades html para garantir maior segurança.

<static> Object getFeatureParameters(feature) Obtém os parâmetros do recurso.

<static> Object getUrlParameters() Obtém os parâmetros do URL.

<static> Boolean hasFeature(feature) Retorna se o recurso atual é suportado.

<static> makeClosure(scope, callback, var_args) Cria um invólucro adequado para ser passado como um retorno de chamada.

<static> registerOnLoadHandler(callback) Registra um manipulador durante a carga.

<static> String unescapeString(str) Inverte escapeString.

Detalhes do método

escapeString<static> String escapeString(str)

Cria códigos de escape para os dados inseridos, usando entidades html para garantir maior segurança.

Parâmetros: String str - A String para a qual serão criados os códigos de escape.

Retorna: String A String com códigos de escape.

getFeatureParameters<static> Object getFeatureParameters(feature)

Obtém os parâmetros do recurso.

Parâmetros: String feature - O recurso para o qual os parâmetros serão obtidos

Retorna: Object Os parâmetros do recurso em questão, ou null (nulo)

Page 85: documentacao - OpenSocial

getUrlParameters<static> Object getUrlParameters()

Obtém os parâmetros do URL.

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

hasFeature<static> Boolean hasFeature(feature)

Retorna se o recurso atual é suportado.

Parâmetros: String feature - O recurso a ser testado

Retorna: Boolean True (verdadeiro) se o recurso for suportado

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

Cria um invólucro adequado para ser passado como um retorno de chamada. É possível passar qualquer quantidade de argumentos ao retorno de chamada. Eles serão recebidos na ordem em que forem passados.

Parâmetros: Object scope - O escopo da execução; pode ser null se não houver necessidade de associar uma instância específica de um objeto a este retorno de chamada Function callback - O retorno de chamada a ser executado quando a chamada for realizada; qualquer argumento será passado após os argumentos iniciais Object var_args - Argumentos iniciais a serem passados ao retorno de chamada

registerOnLoadHandler<static> registerOnLoadHandler(callback)

Registra um manipulador durante a carga.

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

unescapeString<static> String unescapeString(str)

Inverte escapeString.

Parâmetros: String str - A String da qual serão removidos os códigos de escape.

Retorna: String A String sem códigos de escape.

Page 86: documentacao - OpenSocial

gadgets.MiniMessage

Classe gadgets.MiniMessageClasse MiniMessage.

Resumo do construtorgadgets.MiniMessage(opt_moduleId, opt_container)

Usado para criar mensagens que aparecerão para o usuário dentro do gadget.

Resumo do métodoElement 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.MiniMessagegadgets.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

createDismissibleMessageElement 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

Page 87: documentacao - OpenSocial

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

createStaticMessageElement 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

createTimerMessageElement 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

dismissMessagedismissMessage(message)

Dispensa a mensagem especificada.

Parâmetros: Element message - Elemento HTML da mensagem que será removida

Page 88: documentacao - OpenSocial

gadgets.Tab

Classe gadgets.TabClasse Tab para gadgets. Você pode criar guias usando o método TabSet addTab(). Para obter objetos de Guia, use os métodos TabSet getSelectedTab() ou getTabs().

Veja também: TabSet

Resumo do métodoFunction 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

getCallbackFunction getCallback()

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

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

getContentContainerElement getContentContainer()

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

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

getIndexNumber getIndex()

Retorna o índice da guia.

Retorna: Number O índice da guia.

Page 89: documentacao - OpenSocial

getNameString getName()

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

Retorna: String O marcador da guia.

getNameContainerElement getNameContainer()

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

Retorna: Element O elemento HTML do marcador da guia.

Page 90: documentacao - OpenSocial

gadgets.TabSet

Classe gadgets.TabSetUma classe que pode ser usada pelos gadgets para criar guias.

Resumo do construtorgadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

Cria um novo objeto TabSet

Resumo do métodoString 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.TabSetgadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

Cria um novo objeto TabSet

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

Page 91: documentacao - OpenSocial

Detalhes do método

addTabString 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.

alignTabsalignTabs(align, opt_offset)

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

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

displayTabsdisplayTabs(display)

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

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

getHeaderContainerElement getHeaderContainer()

Retorna o elemento cabeçalhos de guia do recipiente.

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

getSelectedTabgadgets.Tab getSelectedTab()

Page 92: documentacao - OpenSocial

Retorna o objeto de guia selecionado no momento.

Retorna: gadgets.Tab O objeto de guia selecionado no momento.

getTabsArray.<gadgets.Tab> getTabs()

Retorna uma matriz de todos os objetos de guia existentes.

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

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

setSelectedTabsetSelectedTab(tabIndex)

Seleciona a guia no tabIndex e ativa a função de retorno de chamada da guia, se existir. Se a guia já estiver selecionada, o retorno de chamada não é ativado.

Parâmetros: Number tabIndex - Índice da guia a ser selecionada.

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

Page 93: documentacao - OpenSocial

gadgets.flash

Static Class gadgets.flashIntegra conteúdo Flash nos gadgets.

Resumo do método<static> Boolean embedCachedFlash()

Injeta um arquivo Flash com cache na árvore DOM. <static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)

Injeta um arquivo Flash na árvore DOM. <static> Number getMajorVersion()

Detecta o Flash Player e sua versão principal.

Detalhes do método

embedCachedFlash<static> Boolean embedCachedFlash()

Injeta um arquivo Flash com cache na árvore DOM. Aceita os mesmos parâmetros que gadgets.flash.embedFlash.

Retorna: Boolean Se a chamada à função for concluída com sucesso.

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

Injeta um arquivo Flash na árvore DOM.

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

Retorna: Boolean Se a chamada à função for concluída com sucesso.

getMajorVersion<static> Number getMajorVersion()

Detecta o Flash Player e sua versão principal.

Page 94: documentacao - OpenSocial

Retorna: Number A versão principal do Flash Player ou 0 se o Flash não for suportado.

Page 95: documentacao - OpenSocial

gadgets.rpc

Static Class gadgets.rpcFornece operações para realizar chamadas rpc.

Resumo do método<static> call(targetId, serviceName, callback, var_args)

Chama um serviço RPC. <static> register(serviceName, handler)

Registra um serviço RPC. <static> registerDefault(handler)

Registra um manipulador de serviços padrão para processar todas as chamadas RPC desconhecidas, que falham sem aviso por padrão.

<static> unregister(serviceName) Cancela o registro de um serviço RPC.

<static> unregisterDefault() Cancela o manipulador de serviços padrão.

Detalhes do método

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

Chama um serviço RPC.

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

register<static> register(serviceName, handler)

Registra um serviço RPC.

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

registerDefault<static> registerDefault(handler)

Page 96: documentacao - OpenSocial

Registra um manipulador de serviços padrão para processar todas as chamadas RPC desconhecidas, que falham sem aviso por padrão.

Parâmetros: Function handler - Manipulador de serviços.

unregister<static> unregister(serviceName)

Cancela o registro de um serviço RPC.

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

unregisterDefault<static> unregisterDefault()

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

Page 97: documentacao - OpenSocial

gadgets.views

Static Class gadgets.viewsFornece operações para lidar com Visualizações.

Resumo do método<static> gadgets.views.View getCurrentView()

Retorna a visualização atual. <static> Map.<String, String> getParams()

Retorna os parâmetros passados a este gadget para esta visualização. <static> Map<gadgets.views.ViewType, String, gadgets.views.View> getSupportedViews()

Retorna um mapa de todas as visualizações suportadas. <static> requestNavigateTo(view, opt_params)

Tenta ir para uma visualização diferente deste gadget.

Detalhes do método

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

Retorna a visualização atual.

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

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

Retorna os parâmetros passados a este gadget para esta visualização. Não inclui todos os parâmetros de URL, somente os passados para gadgets.views.requestNavigateTo

Retorna: Map.<String, String> O mapa de parâmetros

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

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

Retorna: Map<gadgets.views.ViewType, String, gadgets.views.View> Todas as visualizações suportadas, associadas ao atributo dos seus nomes.

Page 98: documentacao - OpenSocial

requestNavigateTo<static> requestNavigateTo(view, opt_params)

Tenta ir para uma visualização diferente deste gadget. Se o recipiente suportar parâmetros, ele passará os parâmetros opcionais para o gadget na nova visualização.

Parâmetros: gadgets.views.View view - A visualização de destino Map.<String, String> opt_params - Parâmetros a serem passados ao gadget após a visualização ser acessada

Page 99: documentacao - OpenSocial

gadgets.views.View

Classe gadgets.views.ViewInterface básica para todos os objetos de visualização.

Resumo do métodogadgets.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

getNamegadgets.views.ViewType, String getName()

Retorna o nome desta visualização.

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

isOnlyVisibleGadgetboolean 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

Page 100: documentacao - OpenSocial

gadgets.views.ViewType

Static Class gadgets.views.ViewTypeUsada 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.

Page 101: documentacao - OpenSocial

gadgets.skins

Static Class gadgets.skinsFornece operações para obter informações de exibição sobre a skin exibida atualmente.

Resumo do método<static> String getProperty(propertyKey)

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

Detalhes do método

getProperty<static> String getProperty(propertyKey)

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

Parâmetros: String propertyKey - A chave para a qual os dados são obtidos; as chaves estão definidas em gadgets.skins.Property

Retorna: String Os dados

Page 102: documentacao - OpenSocial

gadgets.skins.Property

Static Class gadgets.skins.PropertyTodos os valores de exibição que podem ser obtidos e usados na interface do usuário dos gadgets. Estas são as chaves suportadas para o método gadgets.skins.getProperty().

Resumo do campo<static> object ANCHOR_COLOR

A cor que deve ser usada pelas tags anchor. <static> object BG_COLOR

A cor de fundo do gadget. <static> object BG_IMAGE

Uma imagem a ser usada no fundo do gadget. <static> object FONT_COLOR

A cor que deve ser usada pela fonte principal.

Detalhes do campo

ANCHOR_COLOR<static> object ANCHOR_COLOR

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

BG_COLOR<static> object BG_COLOR

A cor de fundo do gadget.

BG_IMAGE<static> object BG_IMAGE

Uma imagem a ser usada no fundo do gadget.

FONT_COLOR<static> object FONT_COLOR

A cor que deve ser usada pela fonte principal.

Page 103: documentacao - OpenSocial

gadgets.window

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

Resumo do método<static> adjustHeight(opt_height)

Ajusta a altura do gadget <static> Object getViewportDimensions()

Detecta as dimensões internas de um frame. <static> setTitle(title)

Define o título do gadget.

Detalhes do método

adjustHeight<static> adjustHeight(opt_height)

Ajusta a altura do gadget

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

getViewportDimensions<static> Object getViewportDimensions()

Detecta as dimensões internas de um frame. Para obter mais informações consulte: http://www.quirksmode.org/viewport/compatibility.html.

Retorna: Object Um objeto com propriedades de largura e altura.

setTitle<static> setTitle(title)

Define o título do gadget.

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