Este guia o ajudará a desenvolver aplicativos OpenSocial. Ele é destinado aos desenvolvedores que já estão familiarizados com a API do Gadgets e com JavaScript, mas fornece links para outros recursos em lugares nos quais pode haver necessidade de mais informações.
Este documento foi modificado para refletir as alterações da atualização 0.7 da API do OpenSocial. As seções atualizadas possuem o indicador Novo! ou Atualizado para ajudá-lo a identificar as práticas de programação que foram alteradas desde a última versão.
Um aplicativo social é um aplicativo executado em um recipiente que suporta a API JavaScript do OpenSocial.
Para criar um aplicativo social, é necessário:
O foco da API do OpenSocial está nas pessoas. Ela permite que os usuários compartilhem suas atividades uns com os outros e acessem informações sobre seus amigos. A API do OpenSocial possui três áreas principais de funcionalidade:
Muitas chamadas da API são assíncronas e podem exigir uma solicitação ao servidor para recuperar ou atualizar informações. Por isso, é necessário passar uma função de retorno de chamada, que será executada quando os dados forem retornados do servidor.
Para obter informações detalhadas sobre as classes e o método da API JavaScript do OpenSocial, consulte a Referência da API.
Adicione a seção Requires descrita a seguir ao seu aplicativo para usar a API do OpenSocial:
<ModulePrefs title="Title of Your Application"> <Require feature="opensocial-0.7"/> </ModulePrefs>
Consulte o Guia do desenvolvedor da API do Gadgets para obter mais informações sobre a estrutura e o conteúdo de uma especificação XML de gadget.
Vamos começar com um exemplo simples que lista os nomes dos seus amigos. Primeiro, é importante compreender as funções definidas pela API do OpenSocial:
O exemplo ''List Friends'' (Listar amigos) discutido nesta seção identifica o visualizador e seus amigos e exibe uma lista de amigos do visualizador. Ele ilustra como obter e operar dados em um aplicativo do OpenSocial. As etapas básicas são:
|
DataRequest fazendo a chamada opensocial.newDataRequest(). DataRequest.add(request) para cada tipo de dados que você deseja recuperar.DataRequest, faça uma chamada DataRequest.send(callback).DataResponse que possui os resultados da solicitação. Em ''List Friends'', a DataResponse contém o visualizador e seus amigos. A função de retorno de chamada processa os dados da solicitação DataResponse.Estas etapas são discutidas abaixo em mais detalhes.
Para obter informações sobre um determinado visualizador e uma lista de seus amigos, crie um novo objeto DataRequest e adicione uma solicitação para cada tipo de dados que você deseja recuperar:
/**
* Request for friend information when the page loads.
*/
function getData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
req.add(req.newFetchPeopleRequest(opensocial.DataRequest.Group.VIEWER_FRIENDS), 'viewerFriends');
req.send(onLoadFriends);
};
O último parâmetro das chamadas newFetch*Request() é uma chave de string usada para recuperar os dados da resposta.
Suponhamos que você realizou o processo descrito no exemplo da seção anterior. Agora, você quer fazer algo com os dados retornados, que são do tipo opensocial.DataResponse. A função de retorno de chamada onLoadFriends() descrita abaixo analisa a DataResponse tomada como parâmetro e exibe o nome do visualizador e de seus amigos:
/**
* Parses the response to the friend information request and generates
* html to list the friends by their display name.
*
* @param {Object} dataResponse Friend information that was requested.
*/
function onLoadFriends(dataResponse) {
var viewer = dataResponse.get('viewer').getData();
var html = 'Friends of ' + viewer.getDisplayName();
html += ':<br><ul>';
var viewerFriends = dataResponse.get('viewerFriends').getData();
viewerFriends.each(function(person) {
html += '<li>' + person.getDisplayName() + '</li>';
});
html += '</ul>';
document.getElementById('message').innerHTML = html;
};
Uma chamada DataResponse.get(key) com a chave de string que você passou à newFetch*Request() retorna um ResponseItem contendo os resultados da solicitação.
Uma chamada dataResponse.get(key).getData() retorna os dados de resposta reais de uma solicitação bem-sucedida. Aqui estão os tipos de dados de resposta associados a solicitações comuns:
opensocial.Person. opensocial.Collection de objetos opensocial.Person.A chamada DataResponse.get(key).hasError() retorna a resposta true caso ocorra falha em uma determinada solicitação.
Esta seção lista o código completo do aplicativo ''List Friends'' discutido acima.
Normalmente, a primeira coisa que se deseja fazer dentro de um aplicativo é solicitar os dados necessários ao aplicativo. Observe que o código inclui esta linha:
gadgets.util.registerOnLoadHandler(getData);
O valor getData() é registrado como o manipulador do aplicativo durante a carga. Isso significa que a primeira coisa que o aplicativo faz (através do getData()) é obter os dados do visualizador e de seus amigos.
Aqui está o exemplo completo. Ele programa sua saída para um <div> cujo ID é "message".
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="List Friends Example">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
/**
* Request for friend information.
*/
function getData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
req.add(req.newFetchPeopleRequest(opensocial.DataRequest.Group.VIEWER_FRIENDS), 'viewerFriends');
req.send(onLoadFriends);
};
/**
* Parses the response to the friend information request and generates
* html to list the friends along with their display name.
*
* @param {Object} dataResponse Friend information that was requested.
*/
function onLoadFriends(dataResponse) {
var viewer = dataResponse.get('viewer').getData();
var html = 'Friends of ' + viewer.getDisplayName();
html += ':<br><ul>';
var viewerFriends = dataResponse.get('viewerFriends').getData();
viewerFriends.each(function(person) {
html += '<li>' + person.getDisplayName() + '</li>';
});
html += '</ul>';
document.getElementById('message').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getData);
</script>
<div id="message"> </div>
]]>
</Content>
</Module>
A API do OpenSocial suporta salvar e recuperar dados por usuário e por aplicativo. As versões 0.5 e 0.6 do OpenSocial também suportavam dados de aplicativo por aplicativo e globais. Esse recurso foi removido da v0.7.
Este trecho de código mostra como salvar os dados no armazenamento compartilhado:
function populateMyAppData() {
var req = opensocial.newDataRequest();
var data1 = Math.random() * 5;
var data2 = Math.random() * 100;
var data3 = new Date().getTime();
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField1", data1));
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField2", data2));
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField3", data3));
req.send(handlePopulateMyAppData);
};
Você pode recuperar os dados armazenados no trecho de código descrito acima da seguinte maneira:
var req = opensocial.newDataRequest();
//Request the following three app fields
var fields = [ "AppField1", "AppField2", "AppField3" ];
req.add(req.newFetchPersonAppDataRequest("VIEWER", fields), "viewer_data");
req.send(handleRequestMyData);
Aqui está o código completo do aplicativo. Ele define alguns valores para o visualizador e os recupera:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Data Persistence Example" >
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
gadgets.util.registerOnLoadHandler(populateMyAppData);
var htmlout = "";
var me = null;
/************************************************************************
* Set user data
*/
function populateMyAppData() {
var req = opensocial.newDataRequest();
var data1 = Math.random() * 5;
var data2 = Math.random() * 100;
var data3 = new Date().getTime();
htmlout += "Setting AppField1 to " + data1 + "<br />";
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField1", data1)) + "<br />";
htmlout += "Setting AppField2 to " + data2 + "<br />";
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField2", data2)) + "<br />";
htmlout += "Setting AppField3 to " + data3 + "<br />";
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField3", data3)) + "<br />";
req.send(handlePopulateMyAppData, "update_appdata");
}
/************************************************************************
* Handle responses from update person app data requests
*/
function handlePopulateMyAppData(data) {
if (data.hadError()) {
htmlout += data.getError();
}
requestMyData();
}
/************************************************************************
* Fetch app data
*/
function requestMyData() {
var req = opensocial.newDataRequest();
var fields = [ "AppField1", "AppField2", "AppField3" ];
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), "viewer");
req.add(req.newFetchPersonAppDataRequest("VIEWER", fields), "viewer_data");
req.send(handleRequestMyData);
}
/************************************************************************
* Handle responses from app data requests
*/
function handleRequestMyData(data) {
var mydata = data.get("viewer_data");
var viewer = data.get("viewer");
me = viewer.getData();
if (mydata.hadError()) {
htmlout += data.getError();
return;
}
// Do something with the returned data - note the getData call
doSomethingWithMyData(mydata.getData());
}
/************************************************************************
* Operate on user data
*/
function doSomethingWithMyData(data) {
//Data is indexed by user id, and represents an object where keys
//correspond with the app data fields.
var mydata = data[me.getId()];
var div = document.getElementById('content_div');
htmlout += "My AppField1 data is: " + mydata["AppField1"] + "<br />";
htmlout += "My AppField2 data is: " + mydata["AppField2"] + "<br />";
htmlout += "My AppField3 data is: " + mydata["AppField3"] + "<br />";
div.innerHTML = htmlout;
}
</script>
<div id="content_div"></div>
]]>
</Content>
</Module>
Observação: Os dados armazenados em um aplicativo OpenSocial estão sempre na forma de strings. Para a maioria das finalidades, é mais prático que esta string possua codificação JSON. Como o OpenSocial adiciona automaticamente códigos de escape HTML a todos os dados retornados, incluindo dados de aplicativo, é necessário excluir os códigos de escape dos objetos JSON em dados persistentes antes de analisá-los. Por exemplo:
var unescapedString = gadgets.util.unescapeString(jsondata); var obj = gadgets.json.parse(unescapedString);
A API do OpenSocial permite usar um fluxo de atividades para compartilhar atividades com seus amigos. Um fluxo de atividades é um feed no qual cada entrada representa uma ação realizada pelo usuário. Uma atividade pode ser qualquer coisa, desde modificar o estado de um aplicativo até escrever uma crítica on-line de um filme.
Se você solicitar prioridade de atividade HIGH (alta), o aplicativo solicitará a permissão do usuário para postar as atividades em seu nome, caso ainda não tenha permissão. Se você solicitar prioridade LOW (baixa), a chamada não fará nada se o aplicativo não tiver permissão de postagem.
Este exemplo simples ilustra como criar uma atividade:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Activities - v0.7" >
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
var div = document.getElementById('content_div');
function postActivity(text) {
var params = {};
params[opensocial.Activity.Field.TITLE] = text;
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH, callback);
div.innerHTML = "Activity title is: " + activity.getField(opensocial.Activity.Field.TITLE);
};
// The parameter passed to the callback is an opensocial.ResponseItem that
// indicates whether the activity creation request succeeded.
function callback(status) {
if (status.hadError())
{
alert("Error creating activity.");
}
else
{
alert("Activity successfully created.");
}
};
postActivity("This is a sample activity, created at " + new Date().toString());
</script>
]]>
</Content>
</Module>
A API do OpenSocial fornece aos aplicativos as formas abaixo de capacidade de interação com seu recipiente:
Você pode usar a chamada gadgets.views.requestNavigateTo para levar seu aplicativo de uma página para outra de um recipiente (por exemplo, para criar um link do perfil à página de tela inteira).
Este exemplo mostra como usar a API para ir de uma visualização para outra. Ele exibe uma lista de links nos quais o usuário pode clicar para navegar entre as visualizações disponíveis do recipiente.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Navigating Between Views (0.7)" description="Navigates between views">
<Require feature="opensocial-0.7" />
<Require feature="views" />
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="main"></div>
<script type="text/javascript">
/**
* Create the list of links to the other views
*/
function createLinks() {
//Get the environment, current view and an object containing the supported views
var env = opensocial.getEnvironment();
var views = gadgets.views.getSupportedViews();
var currentview = gadgets.views.getCurrentView();
var text = [ "You are currently on the ",
currentview.getName(),
" view. Other views: " ].join("");
//Set up some DOM
var outputdom = document.getElementById("main");
outputdom.appendChild(document.createTextNode(text));
var ol = document.createElement("ol");
outputdom.appendChild(ol);
//Iterate over each view
for (var viewname in views) {
var view = views[viewname];
// Make some DOM to present each link
var li = document.createElement("li");
var a = document.createElement("a");
ol.appendChild(li);
li.appendChild(a);
a.href = "javascript:void(0);";
//Put the name of the view in the link
a.appendChild(document.createTextNode("Link to " + view.getName()));
//Handle when the user clicks a link to the other server
a.onclick = getNavigateClosure(view);
}
};
/**
* Returns a function that navigates to the supplied view
*/
function getNavigateClosure(view) {
return function() { gadgets.views.requestNavigateTo(view); };
};
//Execute createLinks when the page is done loading
gadgets.util.registerOnLoadHandler(createLinks);
</script>
]]>
</Content>
</Module>
Observe esta função no exemplo acima:
function getNavigateClosure(view) {
return function() { gadgets.views.requestNavigateTo(view); };
};
Ela usa uma técnica conhecida como invólucro. Neste contexto, significa que uma função chamada de dentro de outra função tem acesso às variáveis locais da função externa. O uso de um invólucro permite que o nome da visualização selecionada seja passado para dentro do método requestNavigateTo() quando o usuário clica no link da visualização.
A classe Environment inclui o método getDomain, que informa o site no qual você está (como orkut.com ou myspace.com). Isso permite que seu aplicativo responda de maneiras diferentes a diferentes ambientes. O método getDomain pode ser útil ao criar URLs absolutos em casos nos quais a API retorna somente um URL relativo. Entretanto, em geral recomendamos o uso de outro método, o hasCapability,, para todas as alterações funcionais. O método hasCapability identifica o nome de uma função e informa se esta função está disponível no recipiente atual. Isso permite que um recipiente adicione suas próprias extensões ao OpenSocial, enquanto ainda fornece aos desenvolvedores um mecanismo comum de acesso. Esta capacidade de ampliação específica ao recipiente também aparece no método supportsField. O provedor de um recipiente pode adicionar seu próprio campo de pessoa ou atividade. Para manter conformidade com a especificação do OpenSocial, este campo precisa estar documentado em algum lugar fora do namespace opensocial.
Esta amostra de aplicativo altera sua exibição se o usuário estiver no modo de perfil ou de tela:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="My 0.7 Environment">
<Require feature="opensocial-0.7"/>
</ModulePrefs> <Content type="html">
<![CDATA[
<script type="text/javascript">
/**
* Request for friend information when the page loads.
*/
function getData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
req.send(greetUser);
}
/**
* Change the display of the user greeting depending on whether the
* user is in the profile or the canvas.
*/
function greetUser(dataResponse) {
var viewer = dataResponse.get('viewer').getData();
// Determine whether the getCurrentView feature is supported
var isAble = gadgets.util.hasFeature("gadgets.views.getCurrentView");
var html = '<h2>Greetings, ' + viewer.getDisplayName() + '!</h2>';
// If the container supports the getEnvironment method, determine whether the user
// is in the canvas or profile
if (isAble)
{
var currView = gadgets.views.getCurrentView();
// If the user is in the canvas, display the canvas view of the greeting
if (currView.getName() == 'canvas')
{
showCanvasView(html);
}
// Otherwise, display the profile view of the greeting
else
{
// If the container supports the field THUMBNAIL_URL for PERSON objects,
// include it in the profile view greeting page
var myenv = opensocial.getEnvironment();
if (myenv.supportsField(opensocial.Environment.ObjectType.PERSON, opensocial.Person.Field.THUMBNAIL_URL))
{
var thumb = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
html += "<img src=" + thumb + "/>";
}
// Display the greeting in the profile and include the user's thumbnail
document.getElementById('profile-div').innerHTML = html;
}
}
// Default: just display the greeting with no image
else {
document.getElementById('profile-div').innerHTML = html;
}
}
/** If the user is in canvas, change the display to take advantage of
* additional screen area
*/
function showCanvasView(str) {
var div = document.getElementById('canvas-div');
div.style.display="";
str += "<img src='http://gadget-doc-examples.googlecode.com/svn/trunk/my-canvas-photo.jpg' />";
div.innerHTML = str;
}
gadgets.util.registerOnLoadHandler(getData);
</script>
<div id="profile-div"> </div>
<div id="canvas-div" style="display:none; font-family:Tahoma; background-color: #FFC0CB; margin: 5px; height: 570px; text-align: center;"></div>
]]>
</Content>
</Module>
Você pode incluir mais de uma seção <Content> em um arquivo XML de gadget, onde cada seção <Content> define as visualizações nas quais deve ser exibida. Todas as seções <Content> devem ser irmãs na árvore de documentos e podem usar o parâmetro view= opcional para definir as visualizações nas quais devem ser exibidas.
Aqui está um exemplo simples que mostra um gadget com duas seções de conteúdo:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Multiple Content Sections (version 1)">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="profile">
<![CDATA[
<h1>Profile</h1>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
<h1>Canvas</h1>
]]>
</Content>
</Module>
Veja como fica a saída:
Visualização de perfil
<h1>Profile</h1>
Visualização de tela
<h1>Canvas</h1>
Qualquer outra visualização que não seja de tela ou perfil
nenhum conteúdo é exibido
As seções de conteúdo podem especificar diversas visualizações, separadas por vírgulas:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Multiple Content Sections (version 2)">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="canvas,profile">
<![CDATA[
<h1>Canvas and Profile</h1>
]]>
</Content>
</Module>
Veja como fica a saída:
Visualização de perfil
<h1>Canvas and Profile</h1>
Visualização de tela
<h1>Canvas and Profile</h1>
Qualquer outra visualização que não seja de tela ou perfil
nenhum conteúdo é exibido
Se você especificar uma seção de conteúdo com um parâmetro de visualização, ela será exibida somente nesta visualização. Se você não especificar uma seção de conteúdo padrão, as outras visualizações não exibirão nenhum conteúdo.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Multiple Content Sections (version 3)">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="profile">
<![CDATA[
<h1>Profile</h1>
]]>
</Content>
</Module>
Veja como fica a saída:
Visualização de perfil
<h1>Profile</h1>
Visualização de tela
nenhum conteúdo é exibido
Qualquer outra visualização que não seja de tela ou perfil
nenhum conteúdo é exibido
Para especificar uma seção de conteúdo padrão, basta definir uma seção de conteúdo sem nenhum parâmetro de visualização:
<Module>
<ModulePrefs title="Multiple Content Sections (version 4)">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="profile">
<![CDATA[
<h1>Profile</h1>
]]>
</Content>
<Content type="html">
<![CDATA[
<h1>Default</1>
]]>
</Content>
</Module>
Veja como fica a saída:
Visualização de perfil
<h1>Profile</h1>
Visualização de tela
<h1>Default</h1>
Qualquer outra visualização que não seja de tela ou perfil
<h1>Default</h1>
Você pode usar todas estas técnicas em um único gadget:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Multiple Content Sections (version 5)">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="profile">
<![CDATA[
<h1>Profile</h1>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
<h1>Canvas</h1>
]]>
</Content>
<Content type="html" view="canvas,profile">
<![CDATA[
<h2>This shows up in canvas and profile views</h2>
]]>
</Content>
<Content type="html">
<![CDATA[
<h1>Default</h1>
<h2>The content in this section only shows up if no other content sections are applicable</h2>
]]>
</Content>
</Module>
Veja como fica a saída:
Visualização de perfil
<h1>Profile</h1>
<h2>This shows up in canvas and profile views</h2>
Visualização de tela
<h1>Canvas</h1>
<h2>This shows up in canvas and profile views</h2>
Qualquer outra visualização que não seja de tela ou perfil
<h1>Default</h1>
<h2>The content in this section only shows up if no other content sections are applicable</h2>
Use o método gadgets.io.makeRequest() para obter conteúdo remotamente, de outros servidores e páginas da web. Por ser uma melhoria dos antigos métodos IG_Fetch... de API de gadget, a chamada gadgets.io.makeRequest() permite POSTs e GETs, e você pode especificar se deseja que sua solicitação seja assinada ou até mesmo autenticada.
O método gadgets.io.makeRequest() usa os parâmetros abaixo:
Por padrão, a solicitação makeRequest() utiliza o método GET de obtenção de dados, e o tipo padrão de conteúdo é TEXT (onde o conteúdo de uma página da web é obtido na forma de texto puro).
Este exemplo mostra um uso bem simples da API. Ele obtém os primeiros 400 caracteres do www.google.com e os fornece em um <div>:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch Content as Text">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
function makeNormalRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
var url = "http://www.google.com";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
//obj.text contains the text of the page that was requested
var str = obj.text;
var html = str.substr(0,400);
document.getElementById('content_div').innerHTML = html;
};
makeNormalRequest();
</script>
]]>
</Content>
</Module>
Como padrão, as chamadas makeRequest são armazenadas em cache. No exemplo abaixo, a função wrapper usa os mesmos parâmetros da chamada makeRequest, mas aceita outros parâmetros denominados refreshInterval, que permitem especificar a duração do cache. Entretanto, 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 especificando-se o valor 0. Para ler mais sobre este tópico, consulte o Guia do desenvolvedor da API do Gadgets.
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);
}
Este exemplo mostra como usar o tipo de conteúdo DOM para processar dados XML. Quando o tipo de conteúdo DOM é especificado, a chamadamakeRequest() recupera o documento XML especificado como um objeto DOM. Você pode operar o objeto obtido usando funções DOM JavaScript padrão. Para ler mais sobre este tópico, consulte o Guia do desenvolvedor da API do Gadgets.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Fetch XML">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
function makeDOMRequest() {
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.DOM;
var url = "http://doc.examples.googlepages.com/breakfast-data.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;
var title = domdata.getElementsByTagName("menu").item(0).getAttribute("title");
var html = "<h2>" + title + "</h2>";
// 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;
}
}
html += name + " - ";
html += price + "<br />";
}
html += "</div>";
document.getElementById('content_div').innerHTML = html;
};
makeDOMRequest();
</script>
]]>
</Content>
</Module>
Use o tipo de conteúdo JSON para obter conteúdo com codificação JSON em forma de objeto JavaScript.
O aplicativo descrito abaixo obtém o conteúdo de uma página PHP de amostra que contém a seguinte string em codificação JSON:
{"validated":"This request was spoofed","query":[],"url":"http:\/\/graargh.returnstrue.com\/buh\/fetchme.php","signature":"","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;
};
makeJSONRequest();
</script>
]]>
</Content>
</Module>
JSON (JavaScript Object Notation) é um formato de intercâmbio de dados que permite codificar determinados tipos de objetos (matrizes e coleções de pares de chave e valor) na forma de strings que podem ser facilmente transmitidas.
A API do Gadgets fornece o método gadgets.json.stringify() de codificação de objetos como as strings JSON e o método gadgets.json.parse() para transformar uma seqüência JSON em um objeto. Como o OpenSocial adiciona automaticamente códigos de escape HTML a todos os dados retornados, incluindo dados de aplicativo, é necessário excluir os códigos de escape dos objetos JSON em dados persistentes antes de analisá-los. Por exemplo: gadgets.util.unescapeString(jsondata).
Este exemplo cria uma matriz JavaScript, codifica-a como uma string JSON e converte a string JSON de volta em um objeto matriz:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="JSON Example">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
var html = "";
// Create Array object
var myfriends = new Array();
myfriends[0] = "Touki";
myfriends[1] = "Rowan";
myfriends[2] = "Trevor";
// Encode array as JSON string
var jsonString = toJSON(myfriends);
html += "The JSON string is " + jsonString + "<br />";
html += "The type of jsonString is " + typeof(jsonString) + "<br />";
// Convert JSON string back to an object
var arr_obj = toObject(jsonString);
html += "The type of arr_obj is " + typeof(arr_obj);
document.getElementById('content_div').innerHTML = html;
// Encode object as JSON string
function toJSON(obj) {
return gadgets.json.stringify(obj);
}
// Convert JSON string into an object
function toObject(str) {
return gadgets.json.parse(str);
}
</script>
]]>
</Content>
</Module>
Veja como fica a saída deste gadget:
The JSON string is ["Touki","Rowan","Trevor"] The type of jsonString is string The type of arr_obj is object
Como padrão, GET é o método usado para obter o conteúdo remoto. Em vez disso, você pode usar o parâmetro POST_DATA para usar o método POST para obter conteúdo. Por exemplo:
function makePOSTRequest() {
var params = {};
var postdata = {
data1 : "test",
data2 : 1234566
};
params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.POST;
params[gadgets.io.RequestParameters.POST_DATA] = gadgets.io.encodeValues(postdata);
var url = "http://graargh.returnstrue.com/buh/makerequest.php";
gadgets.io.makeRequest(url, response, params);
};
function response(obj) {
// do something
};
makePOSTRequest();
A API do Gadgets suporta os seguintes tipos de autorização:
gadgets.io.AuthorizationType.AUTHENTICATED (o recipiente utiliza autenticação completa) gadgets.io.AuthorizationType.SIGNED (a solicitação é assinada pelo recipiente) gadgets.io.AuthorizationType.NONE (padrão) O modo de usar estes métodos depende do recipiente. Aqui está um exemplo de como usar um tipo de autorização assinada específica do orkut.
A API do OpenSocial suporta o controle de permissão nos aplicativos. Quando um aplicativo usa uma solicitação de dados para obter um visualizador a partir do servidor, essa solicitação só recebe uma resposta se o aplicativo tiver acesso. Se o aplicativo não tiver acesso, é retornado um dos códigos de erro padrão, opensocial.ResponseItem.Error.UNAUTHORIZED. Um aplicativo também pode verificar seu acesso antecipadamente, usando a nova chamada opensocial.hasPermission. Se o acesso for negado, use opensocial.requestPermission para solicitar a permissão especificada ao visualizador. É possível que alguns recipientes sempre concedam e outros sempre neguem acesso ao visualizador, mas esta decisão cabe ao recipiente.
Este trecho ilustra como usar a API de controle de permissão:
/**
* Request the VIEWER and OWNER objects
*/
function requestData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.OWNER), "owner");
// If we have permission to see the viewer's info, then add it to the request.
if (opensocial.hasPermission(opensocial.Permission.VIEWER)) {
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), "viewer");
}
req.send(showData);
}
function showData(data) {
var viewer = data.get("viewer").getData();
var owner = data.get("owner").getData();
var ownerOutput = document.getElementById("owner-output");
var viewerOutput = document.getElementById("viewer-output");
showPerson(owner, ownerOutput);
if (opensocial.hasPermission(opensocial.Permission.VIEWER)) {
showPerson(viewer, viewerOutput);
}
}
function requestPermission() {
var reason = "To demonstrate permission capabilities";
opensocial.requestPermission(opensocial.Permission.VIEWER, reason, requestData);
}
function showPerson(person, div) {
var name = person.getDisplayName();
var thumb = person.getField(opensocial.Person.Field.THUMBNAIL_URL);
var html = '<img src="' + thumb + '"/>' + name;
div.innerHTML = html;
}
//Execute requestData when the page is done loading
gadgets.util.registerOnLoadHandler(requestData);
Aqui estão alguns recursos adicionais para saber mais sobre a API do OpenSocial:
| Revisão | Atualizado | Descrição |
|---|---|---|
| OpenSocial 0.8.1 | Setembro de 2008 | A maioria das seções foi atualizada. As instruções do tipo Require foram alteradas para 0.8. A amostra de acesso agora usa IdSpec. Foram adicionadas informações sobre a limpeza de dados persistentes. Amostra de permissões atualizada. |
| OpenSocial 0.7 | Abril de 2008 | Novo documento. |