<?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.
;<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>
;<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>
;<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> |
<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> |
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> |
</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
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
and
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
, 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> <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> |
</div>
Used by a:RequestParameters.
No authorization. This field may be used interchangeably with the string 'NONE'.
The container will use OAuth for authentication. This field may be used interchangeably with the string 'OAUTH'.
The request will be signed by the container. This field may be used interchangeably with the string 'SIGNED'.
Used by a:RequestParameters.
<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 = {}; |
};
</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", |
... |
}
</source>
</div>
<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 = {}; |
};
</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> |
</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", |
}
</source>
</div>
<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 = {}; |
};
</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!", |
}
</source>
</div>
<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() { |
</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> |
</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>
Defines values for a:RequestParameters.METHOD.
Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'DELETE'.
<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 = {}; |
};
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¶m2=hello");
</source>
</div>
Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'HEAD'.
<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 = {}; |
};
function response(obj) {
output(obj.text); |
};
var data = {
data1 : "test", |
};
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", |
};
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>
Container support for this method type is OPTIONAL. This field may be used interchangeably with the string 'PUT'.
Used by a:gadgets.io.getProxyUrl() method.
<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'.
Used by the a:gadgets.io.makeRequest() method.
<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'.
<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'.
<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'.
<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", |
}
gadgets.io.makeRequest(url, callback, params);
</source>
</div>
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'.
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'.
<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", |
});
gadgets.io.makeRequest(url, callback, params);
</source>
</div>
<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>