Gadgets.io (v0.9)

<?xml version="1.0" encoding="utf-8"?>
<html>
<div style="float:right; margin: 0 0 10px 10px;">

</div>
<span style="font-size:150%"><strong>gadgets.io</strong></span>

Provides remote content retrieval functions.

Methods

gadgets.io.encodeValues

;<code style="color:green"><static> String gadgets.io.encodeValues(fields)</code>

<strong>Parameters</strong>
<table cellspacing="0" cellpadding="4" border="1"> <tr><th>Name</th> <th>Type</th> <th>Description</th></tr> <tr><td>fields</td> <td>Object</td> <td>The post fields you wish to encode</td></tr> </table>

<strong>Returns</strong>
<table cellspacing="0" cellpadding="4" border="1"> <tr><th>Type</th> <th>Description</th></tr> <tr><td>String</td> <td>The processed post data; this includes a trailing ampersand (&)</td></tr> </table>

Description
<div style="margin-left:4em;">Converts an input object into a URL-encoded data string. (key=value&...)</div>

gadgets.io.getProxyUrl

;<code style="color:green"><static> String gadgets.io.getProxyUrl(url, opt_params)</code>

<strong>Parameters</strong>
<table cellspacing="0" cellpadding="4" border="1"> <tr><th>Name</th> <th>Type</th> <th>Description</th></tr> <tr><td>url</td> <td>String</td> <td>The URL to get the proxy URL for</td></tr> <tr><td>opt_params</td> <td>Map<String|String></td> <td>Optional a:proxy request parameters to pass to the request</td></tr> </table>

<strong>Returns</strong>
<table cellspacing="0" cellpadding="4" border="1"> <tr><th>Type</th> <th>Description</th></tr> <tr><td>String</td> <td>The proxied version of the URL</td></tr> </table>

Description
<div style="margin-left:4em;">Gets the proxy version of the passed-in URL.</div>

gadgets.io.makeRequest

;<code style="color:green"><static> gadgets.io.makeRequest(url, callback, opt_params)</code>

<strong>Parameters</strong>
<table cellspacing="0" cellpadding="4" border="1"> <tr><th>Name</th> <th>Type</th> <th>Description</th></tr> <tr><td>url</td> <td>String</td> <td>The URL where the content is located</td></tr> <tr><td>callback</td> <td>Function</td> <td>The function to call with the data from the URL once it is fetched. The callback function will not be called until after the existing callstack has completed execution.</td></tr> <tr><td>opt_params</td> <td>Map.<gadgets.io.RequestParameters|Object></td> <td>Additional a:request parameters </td></tr> </table>

Description
<div style="margin-left:4em;">Fetches content from the provided URL and feeds that content into the callback function.
<source lang="javascript">
var params = {};
paramsgadgets.io.RequestParameters.CONTENT_TYPE = gadgets.io.ContentType.TEXT;
gadgets.io.makeRequest(url, callback, params);
</source>
</div>

Signed authorization
<div style="margin-left:4em;">If opt_paramsgadgets.io.RequestParameters.AUTHORIZATION is set to
gadgets.io.AuthorizationType.SIGNED, the container needs to vouch for the
user's identity to the destination server. The container does this by
doing the following:

<ol>

<li>Removing any request parameters with names that begin with oauth, xoauth, or opensocial (case insensitive).</li>
<li>Adding the following parameters to the request query string:</li>

<ul>

<li>opensocial_viewer_id - Optional. The ID of the current viewer, which matches the getId() value on the viewer person

object.</li>

<li>opensocial_owner_id - Required. The ID of the current owner, which matches the getId() value on the owner person object.</li>
<li>opensocial_app_url - Required. The URL of the application making the request. Containers may alias multiple application URLs to a single canonical application URL in the case where an application

changes URLs.</li>

<li>opensocial_instance_id - Optional. An opaque identifier used to distinguish between multiple instances of the same application in a single container. If a container does not allow multiple instances of the same application to coexist, this parameter may be omitted. The combination of opensocial_app_url and opensocial_instance_id uniquely identify an instance of an application in a container.</li>
<li>opensocial_app_id - Optional. An opaque identifier for the application, unique to a particular container. Containers that wish to maintain backwards compatibility with the opensocial-0.7 specification may include this parameter.</li>
<li>xoauth_public_key - Optional. An opaque identifier for the public key used to sign the request. This parameter may be omitted by containers that do not use public keys to sign requests, or if the container arranges other means of key distribution with the target of the request.</li>
</ul>
<li>Signing the resulting request according to section 9 of the OAuth specification.</li>

</ol>
</div>

management for gadgets.io.AuthorizationType.SIGNED
<div style="margin-left: 4em;">

<p>If a container uses public keys to sign requests, the container may choose to use either self-signed certificates or certificates signed by a well-known certificate authority. If a container does not distribute its OAuth signing key over HTTPS, it should use a certificate signed by a well-known certificate authority.</p>

<p>The commonName attribute of the certificate should match the hostname of the container server, and should also match the value of the

oauth_consumer_key

parameter specified in the request.</p>

<p>The container should make its public key available for download at a well-known location. The location

https://[container-hostname]/opensocial/certificates/xoauth_public_keyvalue

is recommended.</p>

<p>Recipients of signed requests must verify that the signature on the request is correct, and that the timestamp on the request is within a reasonable time window. A time window of 5 minutes before and after the current time is recommended.</p>

<p>Recipients of signed requests may use the

oauth_consumer_key

and

xoauth_public_key

parameters to automatically detect when a container deploys new certificates. If the container deploys certificates at a well-known location, the recipient may automatically download the new certificate. Recipients that automatically download new certificates should cache the resulting certificates.</p>

<p>If a container's certificate is not downloaded from

https://[container-hostname]

, the recipient should verify that the certificate is signed by a well-known certificate authority before trusting the certificate.</p>
</div>

OAuth authorization
<div style="margin-left: 4em;">

<p>If opt_paramsgadgets.io.RequestParameters.AUTHORIZATION is set to

gadgets.io.AuthorizationType.OAUTH

, the container needs to use OAuth to gain access to the resource specified in the request. This may require that the gadget obtain the user's content by directing the user to the service provider to gain access.</p>

</div>

Additional parameters
<div style="margin-left: 4em;">

<p>The following additional parameters may be specified in opt_params:

<ul>

<li>gadgets.io.RequestParameters.OAUTH_SERVICE_NAME - The nickname the gadget uses to refer to the OAuth <Service> element from its XML spec. If unspecified, defaults to "".</li>
<li>gadgets.io.RequestParameters.OAUTH_TOKEN_NAME - The nickname the gadget uses to refer to an OAuth token granting access to a particular resources. If unspecified, defaults to "". Gadgets can use multiple token names if they have access to multiple resources from the same service provider. For example, a gadget with access to a contact list and a calendar might use a token name of "contacts" to use the contact list token, and a contact list of "calendar" to use the calendar token.</li>
<li>gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN - A service provider may be able to automatically provision a gadget with a request token that is preapproved for access to a resource. The gadget can use that token with the OAUTH_REQUEST_TOKEN parameter. This parameter is optional.</li>
<li>gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET - The secret corresponding to a preapproved request token. This parameter is optional.</li>
</ul>
</p>

<p>If OAuth is used, the container should execute the OAuth protocol on behalf of the gadget. If the gadget has not registered a consumer key for use with this service provider, the container may choose to use a default RSA signing key corresponding to a well-known certificate to sign requests. If the container uses a default consumer key, it will include an additional OAuth parameter xoauth_app_url that identifies the gadget making the request.</p>

</div>

The callback parameter
<div style="margin-left: 4em;">

<p>The makeRequest() callback parameter is passed a javascript object with the following standard fields:</p>
<ul>
<li>"data" - Parsed data of the response, if applicable. This will contain a different type of data depending on the type of request that was made. See the a:ContentType parameters for information about what to expect in this field. The raw response text is returned if the response could not be parsed.</li>
<li>"errors" - This will contain an array of any errors that occurred when making this request. For example, if a 500 error occurred in the request: "500 error" </li>
<li>"headers" - An object containing the response headers. Header names are used as the keys for this object.</li>
<li>"rc" - This is a numeric value representing the HTTP status code of the response.</li>
<li>"text" - This will return the unparsed text of the response.</li>
</ul>
<p>Additionally, several OAuth-specific fields may be returned:</p>
<ul>
<li>"oauthApprovalUrl" - If this value is specified, the user needs to visit an external page to approve the gadget's request to access data. Use of a pop-up window to direct the user to the external page is recommended. Once the user has approved access, the gadget can repeat the makeRequest call to retrieve the data.</li>
<li>"oauthError" - If this value is specified, it indicates an OAuth-related error occurred. The value will be one of a set of string constants that can be used for programmatically detecting errors. The constants are undefined for opensocial-0.8, but implementers should attempt to agree on a set of useful constant values for standardization in opensocial-0.9.</li>
<li>"oauthErrorText" - If this value is specified, it indicates an OAuth-related error occurred. The value is free-form text that can be used to provide debugging information for gadget developers.</li>
</ul>

</div>

gadgets.io.AuthorizationType

Used by a:RequestParameters.

gadgets.io.AuthorizationType.NONE

No authorization. This field may be used interchangeably with the string 'NONE'.

gadgets.io.AuthorizationType.OAUTH

The container will use OAuth for authentication. This field may be used interchangeably with the string 'OAUTH'.

gadgets.io.AuthorizationType.SIGNED

The request will be signed by the container. This field may be used interchangeably with the string 'SIGNED'.

gadgets.io.ContentType

Used by a:RequestParameters.

gadgets.io.ContentType.DOM

<div style="margin-left: 2em;">
Returns a DOM object; used for fetching XML. This field may be used interchangeably with the string 'DOM'. DOM requests attempt to retrieve a remote web page and parse it into a DOM document. You can use standard DOM manipulation/query methods on the resulting document to work with nodes in the response.

Make a DOM request like this:

<source lang="javascript">
function request() {

var params = {};
paramsgadgets.io.RequestParameters.CONTENT_TYPE = gadgets.io.ContentType.DOM;
var url = "http://example.com";
gadgets.io.makeRequest(url, response, params);

};
</source>

If the request is successful, the response will come back with the raw XML in the

text

field and the DOM object in the

data

field.

<source lang="javascript">
function response(obj) {

/** obj.data contains a DOM element corresponding to the requested page **/

};
</source>

If the content at

<nowiki>http://example.com</nowiki>

is the following document:

<source lang="xml">
<?xml version="1.0"?>
<root>

<title>Hello!</title>

</root>
</source>

The

obj.text

property will have the following value:

<source lang="javascript">
"<?xml version=\"1.0\"?>\n<root>\n <title>Hello!</title>\n</root>"
</source>

The

obj.data

property will have the following general structure (many of the attributes available on the returned XML document have been left out for clarity).

<source lang="javascript">
{

...

nodeName : "#document",
childNodes : [
{
nodeName : "root",
childNodes : [
"\n",
{
nodeName : "title",
childNodes : "Hello-!"
},
"\n"
]
}
],

...

}
</source>

</div>

gadgets.io.ContentType.FEED

<div style="margin-left: 2em;">
Returns a JSON representation of an RSS or Atom feed. This field may be used interchangeably with the string 'FEED'. Feed requests attempt to parse an ATOM or RSS xml feed and return the response as a JSON encoded object.

Specify a feed content type like this:

<source lang="javascript">
function request() {

var params = {};
paramsgadgets.io.RequestParameters.CONTENT_TYPE = gadgets.io.ContentType.FEED;
var url = "http://example.com";
gadgets.io.makeRequest(url, response, params);

};
</source>

If the request is successful, then the response will come back with the raw XML text in the

text

field and the parsed JavaScript object in the

data

field:

<source lang="javascript">
function response(obj) {

/** obj.data contains an object corresponding with the JSON-encoded response **/

};
</source>

If the content at

<nowiki>http://example.com</nowiki>

is the following:

<source lang="text">
<feed xmlns="http://www.w3.org/2005/Atom">

<title>Example Feed</title>
<subtitle>A subtitle.</subtitle>
<link href="http://example.com/feed/" rel="self"/>
<link href="http://example.com/"/>
<updated>2008-03-12T18:30:02Z</updated>
<author>
<name>Sample Testington</name>
<email>stestington@example.com</email>
</author>
<id>urn:uuid:60a76c80-d399-11d9-b91C-0003939e0af6</id>
<entry>
<title>You can request feeds with makeRequest</title>
<link href="http://example.com/entry12345"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2008-03-12T18:30:02Z</updated>
<summary>Some text.</summary>
</entry>

</feed>
</source>

The

obj.text

property will be set to the text of the xml document. The

obj.data

property will have the following structure:

<source lang="javascript">
{

URL : "http://example.com",
Title : "Example Feed",
Description : "A subtitle.",
Link : "http://example.com/feed/",
Author : "Sample Testington",
Entry : [
{
Title : "You can request feeds with makeRequest",
Link : "http://example.com/entry12345",
Summary : "Some text."
}
]

}
</source>
</div>

gadgets.io.ContentType.JSON

<div style="margin-left: 2em;">
Returns a JSON object. This field may be used interchangeably with the string 'JSON'. JSON requests attempt to parse the response as a JSON encoded object.

Specify a JSON content type like this:

<source lang="javascript">
function request() {

var params = {};
paramsgadgets.io.RequestParameters.CONTENT_TYPE = gadgets.io.ContentType.JSON;
var url = "http://example.com";
gadgets.io.makeRequest(url, response, params);

};
</source>

If the request is successful, then the response will come back with the raw JSON string in the

text

field and the parsed JavaScript object in the

data

field:

<source lang="javascript">
function response(obj) {

/** obj.data contains an object corresponding with the JSON-encoded response **/

};
</source>

If the content at

<nowiki>http://example.com</nowiki>

is the following:

<source lang="text">
{ "Message" : "Hello!", "Test" : "Item 1", "Item 2" }
</source>

The

obj.text

property will have the following value:

<source lang="javascript">
"{ \"Message\" : \"Hello!\", \"Test\" : -"Item 1-", -"Item 2-" }"
</source>

The

obj.data

property will have the following structure:

<source lang="javascript">
{

Message : "Hello!",
Test : [a:
"Item 1",
"Item 2"
]

}
</source>
</div>

gadgets.io.ContentType.TEXT

<div style="margin-left: 2em;">
Returns text; used for fetching HTML. This field may be used interchangeably with the string 'TEXT'. Text requests are the default content type for

makeRequest

calls. Text content type requests do not make any attempt to parse the content of the response.

Make a text content request like this:

<source lang="javascript">

function request() {
var params = {};
paramsgadgets.io.RequestParameters.CONTENT_TYPE = gadgets.io.ContentType.TEXT;
var url = "http://example.com";
gadgets.io.makeRequest(url, response, params);
};

</source>

If the request is successful, the response will come back with both the text and data fields populated with the raw response text.

<source lang="javascript">
function response(obj) {

/** obj.text contains the text of the page that was requested **/

};
</source>

If the content at

<nowiki>http://example.com</nowiki>

is the following:

<source lang="html4strict">
<html>

<body>
<h1>Hello!</h1>
</body>

</html>
</source>

Then

obj.text

and

obj.data

fields will have the following value:

<source lang="javascript">
"<html>\n <body>\n <h1>Hello!</h1>\n </body>\n</html>"
</source>
</div>

gadgets.io.MethodType

Defines values for a:RequestParameters.METHOD.

gadgets.io.MethodType.DELETE

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'DELETE'.

gadgets.io.MethodType.GET

<div style="margin-left: 2em;">
The default type. This field may be used interchangeably with the string 'GET'. Typically, you use GET to retrieve information from a website. GET is the default mode for

makeRequest

, but you can explicitly make a GET request with the following code:

<source lang="javascript">
function makeRequest(url) {

var params = {};
paramsgadgets.io.RequestParameters.METHOD = gadgets.io.MethodType.GET;
gadgets.io.makeRequest(url, response, params);

};

function response(obj) {

alert(obj.text);

};

makeRequest("http://example.com");
</source>

To pass parameters to your server in the GET request, just append them to the querystring when you make the request:

<source lang="javascript">
makeRequest("http://example.com?param1=12345&param2=hello");
</source>
</div>

gadgets.io.MethodType.HEAD

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'HEAD'.

gadgets.io.MethodType.POST

<div style="margin-left: 2em;">
Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'POST'. POST requests are typically used to pass data to a server with the intent to modify or delete records. You can pass larger amounts of data in a POST request than you would be normally able to with a GET request.

Perform a POST by using the following code:

<source lang="javascript">
function makeRequest(url, postdata) {

var params = {};
postdata = gadgets.io.encodeValues(postdata);
paramsgadgets.io.RequestParameters.METHOD = gadgets.io.MethodType.POST;
paramsgadgets.io.RequestParameters.POST_DATA= postdata;
gadgets.io.makeRequest(url, response, params);

};

function response(obj) {

output(obj.text);

};

var data = {

data1 : "test",
data2 : 123456

};

makeRequest("http://example.com", data);
</source>

In addition to specifying the METHOD in the

opt_params

for this request, you should specify a parameter under the key

gadgets.io.RequestParameters.POST_DATA

. The default encoding for POST is application/x-www-form-urlencoded which means that the value for the POST_DATA parameter should be a series of urlencoded key/value pairs joined with ampersands (&). To make converting objects of data into this format easier, the function

gadgets.io.encodeValues

is provided.

encodeValues

accepts a JavaScript object and returns an encoded string suitable for the POST_DATA parameter.

For example, running:

<source lang="javascript">
var data = {

data1 : "test",
data2 : 123456

};

gadgets.io.encodeValues(data);
</source>

produces the string:

<source lang="javascript">
"data1=test&data2=123456"
</source>

This string can be passed directly as the value for

gadgets.io.RequestParameters.POST_DATA

.
</div>

gadgets.io.MethodType.PUT

Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'PUT'.

gadgets.io.ProxyUrlRequestParameters

Used by a:gadgets.io.getProxyUrl() method.

gadgets.io.ProxyUrlRequestParameters.REFRESH_INTERVAL

<static> Member of: gadgets.io.ProxyUrlRequestParameters.REFRESH_INTERVAL Explicitly sets the lifespan of cached content. The Refresh Interval is the number of seconds the container should cache the given response. By default, the HTTP caching headers will be respected for fetched content. If the refresh interval is set, this value will take precedence over any HTTP cache headers. If this value is not set and there are no HTTP caching headers specified, this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached. This field may be used interchangeably with the string 'REFRESH_INTERVAL'.

gadgets.io.RequestParameters

Used by the a:gadgets.io.makeRequest() method.

gadgets.io.RequestParameters.AUTHORIZATION

<static> Member of: gadgets.io.RequestParameters.AUTHORIZATION The type of authentication to use when fetching the content; defaults to AuthorizationType.NONE. Specified as an a:AuthorizationType. This field may be used interchangeably with the string 'AUTHORIZATION'.

gadgets.io.RequestParameters.CONTENT_TYPE

<static> Member of: gadgets.io.RequestParameters.CONTENT_TYPE The type of content that lives at the URL; defaults to ContentType.TEXT. Specified as a a:ContentType. This field may be used interchangeably with the string 'CONTENT_TYPE'.

gadgets.io.RequestParameters.GET_SUMMARIES

<static> Member of: gadgets.io.RequestParameters.GET_SUMMARIES If the content is a feed, whether to fetch summaries for that feed; defaults to false. Specified as a Boolean. This field may be used interchangeably with the string 'GET_SUMMARIES'.

gadgets.io.RequestParameters.HEADERS

<div style="margin-left: 2em;">
The HTTP headers to send to the URL; defaults to null. Specified as a Map.<String,String>. This field may be used interchangeably with the string 'HEADERS'.

<source lang="javascript">
var params = {};
paramsgadgets.io.RequestParameters.HEADERS = {

"Content-Type" : "application/atom+xml",
"Accept-Language": "en-us"

}
gadgets.io.makeRequest(url, callback, params);
</source>
</div>

gadgets.io.RequestParameters.METHOD

The method to use when fetching content from the URL; defaults to a:MethodType.GET. Valid values are specified by a:MethodType. This field may be used interchangeably with the string 'METHOD'.

gadgets.io.RequestParameters.NUM_ENTRIES

If the content is a feed, the number of entries to fetch; defaults to 3. Specified as a Number. This field may be used interchangeably with the string 'NUM_ENTRIES'.

gadgets.io.RequestParameters.POST_DATA

<div style="margin-left: 2em;">
The data to send to the URL using the POST method; defaults to null. Specified as a String. This field may be used interchangeably with the string 'POST_DATA'.

<source lang="javascript">
var params = {};
paramsgadgets.io.RequestParameters.POST_DATA = gadgets.io.encodeValues({

data1 : "test",
data2 : 123456

});
gadgets.io.makeRequest(url, callback, params);
</source>
</div>

gadgets.io.RequestParameters.REFRESH_INTERVAL

<static> Member of: gadgets.io.RequestParameters.REFRESH_INTERVAL Explicitly sets the lifespan of cached content. The Refresh Interval is the number of seconds the container should cache the given response. By default, the HTTP caching headers will be respected for fetched content. If the refresh interval is set, this value will take precedence over any HTTP cache headers. If this value is not set and there are no HTTP caching headers specified, this value will default to 3600 (one hour). Note that Signed requests and objects with POST_DATA present will generally not be cached. This field may be used interchangeably with the string 'REFRESH_INTERVAL'.

{{ JsApiAlphaList_(v0.9) }}

</html>