Este guia o ajudará a desenvolver e gerenciar gadgets no ambiente do iGoogle. Ele se destina a desenvolvedores com alguma experiência com o iGoogle, com a API de gadgets e com JavaScript. O guia fornece também links para outros recursos relacionados ao desenvolvimento de gadgets no iGoogle.
Cada recipiente de gadget tem uma experiência de desenvolvimento diferente. Esta seção descreve o processo de desenvolvimento de gadget para uso no iGoogle.
Este guia usa os seguintes termos para descrever os elementos e os tópicos relacionados à experiência de desenvolvimento no iGoogle:
| Gadget Updates | Um gadget que exibe um feed de dados que contém as atividades de uma pessoa. |
|---|---|
| Gadget | Código de terceiros que usa as APIs de gadget e do OpenSocial para ampliar a experiência no iGoogle. |
| Definição de gadget | O arquivo XML que define o gadget. A sintaxe se baseia no XML do gadget, também conhecido como “especificação do gadget”. |
| Diretório de gadgets | Lista de gadgets disponíveis, classificados com base na popularidade e na opinião dos usuários. |
| Menu de navegação esquerdo | Lista de links do lado esquerdo das páginas do iGoogle. O menu de navegação esquerdo lista os links para o modo de exibição de tela de cada gadget na página de um usuário. |
| Link do menu de navegação esquerdo | Link no menu de navegação esquerdo que abre uma página no modo de exibição de tela de um gadget. |
| Modo de exibição | Local onde um gadget é exibido. No iGoogle, os gadgets podem ser exibidos no modo de exibição de tela ou de página inicial. Ambos os modos de exibição são particulares. O iGoogle não permite que os usuários vejam os gadgets de outros usuários. |
| Modo de exibição de página inicial | Modo de exibição pequeno de um gadget, exibido com outros gadgets. Mostra todos os seus gadgets em seu formato de exibição pequeno. O modo de exibição de página inicial é particular, o que significa que está visível apenas para o usuário conectado. |
| Modo de exibição de tela | O modo de exibição grande de um gadget, exibido sem nenhum outro gadget. O modo de exibição de tela é particular, o que significa que está visível apenas para o usuário conectado. |
| Amigos | A API do OpenSocial proporciona o acesso à rede de amigos do usuário. Na sandbox do iGoogle, você adiciona amigos usando o gadget Sandbox Friends. |
Antes de desenvolver gadget para o iGoogle é bom se familiarizar com os vários recursos de gadget e como eles funcionam juntos. O documento Anatomia de um gadget do iGoogle é um guia útil.
Se este é seu primeiro gadget, siga as etapas listadas no Tutorial do OpenSocial para se familiarizar com a API do OpenSocial. Este tutorial aborda as etapas necessárias para o desenvolvimento de um gadget simples de presente, usando a API do OpenSocial.
Caso tenha um gadget existente, você pode aprimorá-lo para tirar vantagem de alguns recursos novos oferecidos na sandbox do iGoogle, incluindo:
Caso não tenha acesso a um servidor para armazenar seus arquivos XML de gadget, o Editor de gadgets do Google (GGE) é uma ótima ferramenta para editar e hospedar gadgets rapidamente. Para criar um gadget "Hello World" rapidamente, certifique-se de entrar em uma conta do Google (ou não poderá salvar seu gadget) e modifique o gadget a seguir no GGE. Por exemplo: altere a mensagem "Hello, world!" para "Hello, iGoogle!":
Use o comando Arquivo > Salvar como para salvar o arquivo com o nome "igoogle-sample.xml." Depois disso, abra o arquivo XML de seu gadget clicando no nome do arquivo no canto superior direito do editor.
Esta ação vai abrir o XML do gadget em seu navegador. Você vai precisar do URL deste arquivo para instalar seu gadget na próxima seção.
Os gadgets precisam ser executados dentro de um recipiente para acessar os dados da rede social. O iGoogle oferece uma sandbox de desenvolvedor, onde você pode acessar as APIs do OpenSocial e outros recursos novos. Você pode se inscrever na sandbox aqui.
Para adicionar um novo gadget:
Você também pode adicionar gadgets por meio do gadget de desenvolvedor, depois de ter adicionado a guia de ferramentas do desenvolvedor.
A sandbox do iGoogle oferece dois modos de exibição diferentes de seu gadget. O primeiro é o modo de exibição de página inicial. Nele, seu gadget aparece em um formato de 3 colunas, juntamente com os outros gadgets adicionados:
Para ver um gadget em seu tamanho máximo, você pode exibi-lo no modo de exibição de tela clicando em seu link, abaixo de Página inicial. Por padrão, os gadgets são exibidos apenas em seu formato pequeno. Consulte Modos de exibição para obter informações sobre a adição de um modo de exibição de tela a seu gadget.
Veja, por exemplo, um gadget de livros no modo de exibição de página inicial. Ele simplesmente traz a lista de leitura do usuário, os livros dos amigos e os livros recomendados:
O modo de exibição de tela expandida do gadget livros oferece uma experiência mais rica, com guias, mais detalhes sobre os livros do usuário e suas análises:
Os modos de exibição de página inicial e de tela do iGoogle são particulares, o que significa que eles não podem ser visualizados por ninguém além do usuário conectado. Esta é uma distinção importante entre o iGoogle e alguns recipientes de gadget sociais como o orkut.
Para configurar o ambiente de desenvolvimento da sandbox, acesse-a e adicione a guia de ferramentas do desenvolvedor.
A guia de ferramentas do desenvolvedor inclui os seguintes gadgets:
O gadget do desenvolvedor funciona como um “centro de comando” para todos os gadgets de sua página do iGoogle. Além de listar todos os gadgets em execução, ele permite que você adicione, visualize e gerencie os gadgets. O gadget do desenvolvedor oferece recursos que você precisa para o desenvolvimento de gadgets. Permite, por exemplo, que você adicione gadgets “quebrados”, o que é útil quando se altera ativamente um gadget.
No gadget do desenvolvedor você pode clicar em links de gadgets específicos para visualizar suas especificações de XML. Esta é uma boa forma de ver como os outros gadgets são implementados.
Um recurso que o ajuda a desenvolver gadgets é a caixa de verificação Em cache. As especificações dos gadgets são armazenadas em cache, por padrão. Você pode desmarcar Em cache para os gadgets nos quais está trabalhando. Isto permite que você veja a versão mais atualizada do gadget, não a versão armazenada em cache.
O gadget Sandbox Friends permite que você gerencie seus amigos da sandbox do iGoogle.
O estabelecimento de alguém como amigo na sandbox é um processo de duas partes. Uma pessoa deve enviar um convite e a outra pessoa deve aceitá-lo.
Para exibir seus convites e convidar outras pessoas, clique em Convites e sugestões. Este painel inclui duas listas:
Para convidar alguém para ser seu amigo, clique em Adicionar como amigo próximo a um contato da lista ou digite um novo endereço de e-mail no campo de texto. O endereço de e-mail deve estar associado a uma conta do Google, caso contrário será ignorado sem aviso. Clique em Salvar alterações para salvar as alterações feitas neste painel. Esta etapa é importante, porque sem ela nenhum convite enviado ou aceito será processado.
Depois de aceitar um convite ou ter um convite aceito, a pessoa é será adicionada à sua lista de amigos. A partir daí, a pessoa se tornará acessível através da API do OpenSocial. Consulte o tutorial para ver exemplos de como trabalhar com os dados de amigos.
O gadget Sandbox Profile Editor permite editar seu perfil da sandbox do iGoogle. Observe que as únicas informações do perfil acessíveis através da API são ID, nome, local e URL da miniatura. Consulte Dados do perfil para obter mais informações.
O gadget Updates mantém uma lista corrente de todas as atividades postadas pelo usuário, começando pela mais recente.
Consulte Atualizações para ver mais discussões sobre atualizações.
Agora que você já sabe o básico para a instalação e atualização de gadgets, aqui vão algumas dicas e truques para ajudá-lo a desenvolver gadgets que aproveitam os recursos da sandbox do iGoogle.
Os gadgets do OpenSocial são um novo tipo de gadget, baseado na tecnologia de gadgets, mas estendidos para interagir com os dados sociais recuperados de um site (também conhecido como recipiente) que suportam a API do OpenSocial . O iGoogle é um exemplo de recipiente de OpenSocial; esta seção se concentra nos aspectos de desenvolvimento do trabalho com gadgets, dentro do ambiente do iGoogle.
Um modo de exibição é um local em um recipiente onde é exibido um gadget. Modos de exibição diferentes possuem características diversas. Um recipiente, por exemplo, pode ter um modo de exibição que mostra gadgets em formato pequeno e um modo de exibição que mostra os gadgets em formato de página inteira.
Na sandbox do iGoogle, o padrão é um gadget ser exibido em modo de exibição de página inicial (“modo pequeno”), o que significa que ele aparece em uma coluna, entre outros gadgets. Para criar um modo de exibição de tela (“modo grande”) de seu gadget, em que ele se expande horizontalmente para cobrir toda a área de gadgets, você deve definir uma seção <Content> para o modo de exibição de tela, conforme segue:
<Content type="html" view="canvas">
Depois de criar uma seção <Content> para o modo de exibição de tela, você deve criar também uma seção <Content> para que o gadget seja devidamente exibido no modo de exibição de página inicial. Ela pode ser “padrão” ou “página inicial”. Consulte o Guia dos desenvolvedores de JavaScript do OpenSocial para outras discussões sobre gadgets de programação compatíveis com múltiplas seções <Content>.
Aqui está uma versão do gadget Hello World que define modos de exibição de seção <Content> para "página inicial" e "tela". Sua largura varia de acordo com sua exibição no modo de exibição inicial ou no modo de exibição de tela.
|
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Hello World!">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
Hello, small world!
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
Hello, big world!
]]>
</Content>
</Module>
Os modos de exibição são suportados nos recipientes do OpenSocial, mas cada recipiente pode suportar um conjunto diferente de modos de exibição. Por exemplo, o iGoogle oferece um modo de exibição pequeno chamado home, mas esse mesmo modo de exibição no orkut é chamado de profile.
Vamos supor que você queira desenvolver um gadget que tenha a mesma exibição para o home no iGoogle e para o profile no orkut. Em vez de criar seções <Content> duplicadas, você pode concatenar os modos de exibição em uma única seção <Content>, da seguinte maneira:
<Content type="html" view="home,profile">
Você pode usar esta técnica em diversos recipientes ou dentro do mesmo recipiente. Por exemplo, os gadgets que lidam com lógica de apresentação para modos de exibição com tamanhos diferentes em uma única seção <Content> podem estender esse suporte para a página da tela declarando view="home,canvas".
No iGoogle, seu gadget pode ser exibido no modo de exibição de tela e de página inicial. Ambos os modo de exibição são visíveis apenas pelo usuário conectado.
A maneira mais fácil de obter o modo de exibição atual é incluir o recurso “modos de exibição” nas preferências de seu módulo de gadgets:
<ModulePrefs title="Views example"> <Require feature="views" /> </ModulePrefs>
Quando o recurso de modo de exibição estiver incluído, você pode obter o modo de exibição atual chamando a função gadget.util.getCurrentView(). Esse procedimento atribui um objeto gadgets.views.View à variável current_view. Consulte Modos de exibição disponíveis no iGoogle para uma lista de modos de exibição que podem obtidos por esta chamada.
O exemplo a seguir demonstra a obtenção do modo de exibição atual e da execução condicional do código com relação ao valor retornado:
function getViewName() {
return gadgets.views.getCurrentView().getName();
}
if (getViewName() == "canvas") {
/* Do canvas specific stuff here */
}
if (getViewName() == "home") {
/* Do home specific stuff here */
}
<Require
feature="views"> na seção ModulePrefs de seu gadget.Obtenha os objetos View disponíveis chamando a função gadgets.views.getSupportedViews().
var supported_views = gadgets.views.getSupportedViews();
O objeto retornado pela chamada getSupportedViews contém os objetos gadgets.views.View, representando todas os modos de exibição disponíveis no iGoogle, indexados pelo nome.
O modo de exibição de página inicial do gadget mostra o conteúdo e as notificações mais interessantes para o usuário. É um bom lugar para resumir o conteúdo e as atualizações de amigos, oferecendo uma maneira rápida de concluir tarefas simples.
O modo de exibição de tela do gadget oferece um espaço maior, permitindo conteúdo mais rico e maior funcionalidade. Tire vantagem deste modo de exibição para envolver os usuários, mostrar o que seus amigos estão fazendo e permitir que concluam tarefas complexas.
<Require
feature="views"> na seção ModulePrefs de seu gadget.Se desejar fornecer links para outros modos de exibição, você precisa passar um objeto gadgets.views.View para o método gadgets.views.requestNavigateTo(). Você pode preferir usar um dos objetos retornados pela chamada getSupportedViews() descrita nos Modos de exibição disponíveis no iGoogle. A amostra de código a seguir demonstra este método:
function navigateTo(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
navigateTo("canvas");
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
navigateTo("home");
};
Uma alternativa é criar um novo objeto View manualmente e utilizar esse código para iniciar a navegação. A amostra de código a seguir mostra a criação de um novo objeto gadgets.views.View e sua passagem para o método gadgets.views.requestNavigateTo():
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view);
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
var home_view = new gadgets.views.View("home");
gadgets.views.requestNavigateTo(home_view);
};
Este é um exemplo complexo, baseado no gadget "Hello World":
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs height="100" title="Navigation">
<Require feature="views" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
<div>Hello world Home view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('canvas')" >Go to canvas view</a><br><br>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
<div>Hello world Canvas view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('home')" >Go to home view</a><br><br>
]]>
</Content>
</Module>
Observação: No OpenSocial 0.7, não existe chamada que retorne o número de ID do seu gadget. Armazene este valor manualmente, caso deseje usá-lo em seu gadget.
<Require
feature="views"> na seção ModulePrefs de seu gadget.Se você estiver usando as chamadas gadgets.views.requestNavigateTo(), você poderá fornecer um parâmetro opcional, contendo os dados a serem transmitidos para a próxima página.
O código a seguir transmite duas variáveis: foo e bar à superfície da tela do gadget atual:
function gotoCanvas(params) {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view, params);
};
var my_params = {
foo : 12345,
bar : "Bar value"
};
gotoCanvas(my_params);
No modo de exibição de tela, procure esses valores no código a seguir:
var prefs = gadgets.views.getParams(); var foo = prefs["foo"]; /* foo contains 12345 */ var bar = prefs["bar"]; /* bar contains "Bar value" */<sup class="changed">New!</sup>
Você pode usar o recurso shareable-prefs para possibilitar a edição das preferências de usuário do gadget por diversos usuários. Dessa forma, os usuários podem compartilhar o gadget e ver as edições que cada um faz. Por exemplo, membros da família podem compartilhar um gadget de lista de compras de supermercado e cada pessoa pode adicionar seus itens favoritos. Os dados de preferência do usuário compõem a parte do estado do gadget hospedada pelo iGoogle. Para obter mais informações sobre preferências do usuário, consulte o Guia de desenvolvedor de API de gadgets.
Para compartilhar as preferências de usuário do gadget entre diversos usuários, o gadget deve incluir a linha <optional feature="shareable-prefs"/> na seção <ModulePrefs>. Por exemplo, este gadget usa a preferência do usuário listar tipos de dados para preencher uma lista de compras de supermercado:
Este é o código para o gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="Our Grocery List"
scrolling="true">
<optional feature="shareable-prefs"/>
</ModulePrefs>
<UserPref name="mylist"
display_name="Add items"
datatype="list" />
<Content type="html">
<![CDATA[
<div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>
<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();
// Get the list
var items = prefs.getArray("mylist");
var html = "";
// If there are no items in the list yet, display message.
if (items.length == 0)
{
html += "Edit the userprefs to add items to the list.";
}
else {
for (var i = 0; i < items.length ; i++) {
var term = (items[i]);
html += term + "<br />";
}
}
document.getElementById("content_div").innerHTML = html;
</script>
]]>
</Content>
</Module>
Após adicionar um gadget que suporta preferências compartilháveis ao iGoogle, você pode torná-lo cooperativo da seguinte maneira.
Etapa 1: clique no triângulo do gadget que você deseja compartilhar e selecione Compartilhar este gadget.
Etapa 2: se você é um usuário do Gmail, escolha os amigos com os quais deseja compartilhar ou digite seus endereços de e-mail.
Etapa 3: decida se quer permitir que seus amigos editem o conteúdo do seu gadget ou apenas o visualizem em suas páginas do iGoogle.
Clique em Enviar convites. Seus amigos recebem um e-mail seu convidando-os a adicionar o gadget às suas próprias páginas do iGoogle.
Os amigos aos quais você concedeu autorização para editar o gadget podem modificar as preferências de usuário do gadget e publicar suas alterações em todas as versões compartilhadas do gadget.
As atualizações são atividades postadas por amigos do usuário sobre ações que o usuário executou na interação com um gadget do iGoogle. O gadget Updates exibe uma lista corrente de todas as atualizações postadas (atividades), começando pela mais recente.
Esta amostra de gadget permite digitar uma atualização em uma caixa de texto e depois clicar em Postar atualização para postá-la. Depois de postar, você pode vê-la clicando em Atualizar agora no gadget Updates:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Post Updates" >
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
// Post an activity and set its title to be the text the user entered in the
// text box.
function postUpdate(form) {
var text = form.inputbox.value;
var div = document.getElementById('content_div');
var params = {};
params[opensocial.Activity.Field.TITLE] = text;
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH);
div.innerHTML = "Update title is: " + activity.getField(opensocial.Activity.Field.TITLE);
}
</script>
<FORM NAME="myform" ACTION="" METHOD="GET">Add Update: <BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
<INPUT TYPE="button" NAME="button" Value="Post Update" onClick="postUpdate(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>
O exemplo acima acessa apenas o campo TITLE do objeto Activity. O iGoogle suporta também esses campos opcionais: BODY, MEDIA_ITEMS, STREAM_FAVICON_URL e STREAM_URL.
Para fins de desenvolvimento, a sandbox do iGoogle é compatível com a capacidade da chamada getActivities() e de obter todas as atividades para o usuário. Posteriormente, getActivities() retornará apenas as atividades de um gadget em particular.
Para usar este recurso de depuração, configure os parâmetros opcionais conforme segue:
var optParams = {};
optParams[opensocial.DataRequest.ActivityRequestFields.APP_ID] = '*';
O asterisco (*) é um caractere curinga que indica que você deseja todas as atividades.
A tabela a seguir mostra que eventos são mostrados em quais locais:
| Tipo de evento | Gadget Updates |
|---|---|
| Eventos nativos | |
| Instalação e desinstalação de gadgets | Sim |
| Eventos de gadgets | Sim |
Para evitar que os gadgets sobrecarreguem o gadget Updates, haverá um número máximo de atualizações que podem ser postadas por dia, por usuário. Para facilitar o desenvolvimento, a sandbox atualmente não tem esta limitação. Consulte nossas Perguntas freqüentes para obter detalhes.
A API do OpenSocial oferece acesso às informações sobre os usuários do iGoogle, na forma de dados de perfil. Esta seção descreve quais campos do perfil estão disponíveis no iGoogle. A sandbox do iGoogle oferece o gadget Profile para os usuários editarem os dados de seu perfil.
A sandbox do iGoogle permite seu acesso aos seguintes campos para o usuário atual, por meio de um objeto Person:
getId()getDisplayName()getField(opensocial.Person.Field.THUMBNAIL_URL)
getField(opensocial.Person.Field.CURRENT_LOCATION)
Aqui está um exemplo que obtém os dados do usuário e exibe sua miniatura, nome, ID e local:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Profile Example" scrolling="true">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
/**
* Request for viewer information.
*/
function getData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
req.send(onLoadViewer);
};
/**
* Display the viewer's thumbnail, name, ID, and location.
*/
function onLoadViewer(dataResponse) {
var viewer = dataResponse.get('viewer').getData();
var thumb = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
var loc = viewer.getField(opensocial.Person.Field.CURRENT_LOCATION);
var address = loc.getField(opensocial.Address.Field.UNSTRUCTURED_ADDRESS);
var html = "<img src=\"" + thumb + "\"/><br />";
html += "The ID for " + viewer.getDisplayName() + " is " + viewer.getId()+"<br />";
html += "The location for " + viewer.getDisplayName() + " is " + address;
document.getElementById('message').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getData);
</script>
<div id="message"> </div>
]]>
</Content>
</Module>
A sandbox do iGoogle limita quantos dados persistentes (appdata) uma instância de usuário individual pode armazenar. Consulte o Guia do desenvolvedor de JavaScript do OpenSocial para mais discussões sobre appdata. O limite é de 10KB. Se uma operação de gravação de appdata exceder esta cota, ela vai falhar com um erro "cota excedida".
Para obter uma lista dos idiomas e países suportados pelo iGoogle, clique aqui. Para obter mais informações sobre como criar gadgets que podem ser facilmente localizados para um público internacional, consulte o Guia dos desenvolvedores da API de gadgets.
Para continuar aprendendo sobre a API do OpenSocial, consulte a documentação e os materiais adicionais hospedados na página inicial da API do OpenSocial.