Gadgets.io (v0.9)

Methods

gadgets.io.encodeValues

<static> String gadgets.io.encodeValues(fields)

Parameters

Name	Type	Description
fields	Object	The post fields you wish to encode

Returns

Type	Description
String	The processed post data; this includes a trailing ampersand (&)

Description

Converts an input object into a URL-encoded data string. (key=value&...)

gadgets.io.getProxyUrl

<static> String gadgets.io.getProxyUrl(url, opt_params)

Parameters

Name	Type	Description
url	String	The URL to get the proxy URL for
opt_params	Map<String\|String>	Optional proxy request parameters to pass to the request

Returns

Type	Description
String	The proxied version of the URL

Description

Gets the proxy version of the passed-in URL.

gadgets.io.makeRequest

<static> gadgets.io.makeRequest(url, callback, opt_params)

Parameters

Name	Type	Description
url	String	The URL where the content is located
callback	Function	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.
opt_params	Map.<gadgets.io.RequestParameters\|Object>	Additional request parameters

Description

Fetches content from the provided URL and feeds that content into the callback function. Note that the hosts or IPs you are requesting have to be whitelisted in your Gadget XML, see Gadgets_XML#ModulePrefs.2FAllowedDomain.

var params = {}; 
params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT; 
gadgets.io.makeRequest(url, callback, params);

Signed authorization

If opt_params[gadgets.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:

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

opensocial_viewer_id - The ID of the current viewer, which matches the getId() value on the viewer person object.
opensocial_owner_id - The ID of the current owner, which matches the getId() value on the owner person object.
opensocial_app_url - 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.
opensocial_instance_id - 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.
opensocial_app_id - The gadget id.
xoauth_public_key - The URL where the current public key can be fetched from.

Signing the resulting request according to section 9 of the OAuth specification.

management for gadgets.io.AuthorizationType.SIGNED

We use self-signed certificates to sign the requests. You can download the public key currently at

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.

The URL of the public key is also given with the xoauth_signature_publickey parameter.

If using signed requests you have to 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.

For more information on making backend requests see Tutorial Backend

OAuth authorization

If opt_params[gadgets.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.

Additional parameters

The following additional parameters may be specified in opt_params:

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 "".
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.
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.
gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET - The secret corresponding to a preapproved request token. This parameter is optional.

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.

The callback parameter

The makeRequest() callback parameter is passed a javascript object with the following standard fields:

"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 ContentType parameters for information about what to expect in this field. The raw response text is returned if the response could not be parsed.
"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" ]
"headers" - An object containing the response headers. Header names are used as the keys for this object.
"rc" - This is a numeric value representing the HTTP status code of the response.
"text" - This will return the unparsed text of the response.

Additionally, several OAuth-specific fields may be returned:

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

gadgets.io.AuthorizationType

Used by RequestParameters.

gadgets.io.AuthorizationType.NONE

No authorization. This field may be used interchangeably with the string 'NONE'. Currently the Apache Shindig only supports form encoded POST_DATA strings ("test=one&foo=bar")

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

gadgets.io.ContentType.DOM

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:

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

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.

function response(obj) {
  /** obj.data contains a DOM element corresponding to the requested page **/
};

If the content at http://example.com is the following document:

<?xml version="1.0"?>
<root>
  <title>Hello!</title>
</root>

The obj.text property will have the following value:

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

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

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

gadgets.io.ContentType.FEED

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:

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

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:

 
function response(obj) {
  /** obj.data contains an object corresponding with the JSON-encoded response **/
};

If the content at http://example.com is the following:

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

The obj.text property will be set to the text of the xml document. The obj.data property will have the following structure:

{
  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."
    }
  ]
}

gadgets.io.ContentType.JSON

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:

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

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:

function response(obj) {
  /** obj.data contains an object corresponding with the JSON-encoded response **/
};

If the content at http://example.com is the following:

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

The obj.text property will have the following value:

 
"{ \"Message\" : \"Hello!\", \"Test\" : [ \"Item 1\", \"Item 2\" ] }"

The obj.data property will have the following structure:

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

gadgets.io.ContentType.TEXT

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:

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

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

function response(obj) {
  /** obj.text contains the text of the page that was requested **/
};

If the content at http://example.com is the following:

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

Then obj.text and obj.data fields will have the following value:

"<html>\n  <body>\n    <h1>Hello!</h1>\n  </body>\n</html>"

gadgets.io.MethodType

Defines values for 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

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:

function makeRequest(url) {
  var params = {};
  params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.GET;
  gadgets.io.makeRequest(url, response, params);
};
 
function response(obj) {
  alert(obj.text);
};
 
makeRequest("http://example.com");

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

makeRequest("http://example.com?param1=12345&param2=hello");

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

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:

function makeRequest(url, postdata) {
  var params = {};
  postdata = gadgets.io.encodeValues(postdata);
  params[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.POST;
  params[gadgets.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);

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:

 
var data = {
  data1 : "test",
  data2 : 123456
};

gadgets.io.encodeValues(data);

produces the string:

"data1=test&data2=123456"

This string can be passed directly as the value for gadgets.io.RequestParameters.POST_DATA.

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

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

var params = {}; 
params[gadgets.io.RequestParameters.HEADERS] = {
  "Content-Type" : "application/atom+xml",
  "Accept-Language": "en-us"
}
gadgets.io.makeRequest(url, callback, params);

gadgets.io.RequestParameters.METHOD

The method to use when fetching content from the URL; defaults to MethodType.GET. Valid values are specified by 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

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

var params = {}; 
params[gadgets.io.RequestParameters.POST_DATA] = gadgets.io.encodeValues({
  data1 : "test",
  data2 : 123456
});
gadgets.io.makeRequest(url, callback, params);

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