#summary Using RPC for gadget/iframe communication
==IMPORTANT:==
===gadgets.rpc is not designed to enable application developers to execute OpenSocial functions from remote containers. The below method is not secure and does not work reliably across containers or browsers and hence the library will not be supported for this purpose.===
====Developers looking to integrate remote pages with OpenSocial containers should either use makeRequest to fetch their markup and display it directly within the application or wait for their container to release a REST API.====
----
----
= Introduction =
Gadgets that rely heavily on content from a single site are faced with an unfortunate dilemma — whether to bundle up the content into a form that can be requested with makeRequest, or to forgo use of the !OpenSocial API entirely, and just open an iframe to the other site. Fortunately, these aren't the only options available. Thanks to the gadgets.rpc library, gadgets can open iframes to external sites without losing contact with their parent containers.
= Details =
==The alert gadget==
The alert gadget is a trivial use of the gadgets.rpc library, but nicely demonstrates how the library works. The gadget's purpose is to create an iframe containing HTML on a different domain. This HTML contains a simple button, called "Alert!" that when clicked displays two alert messages. The first message is called directly within the iframe (the "local" alert). The second message is called by sending a message back to the parent container (the "remote" alert, inside of the gadget).
Actual implementation of this gadget is fairly straightforward. Start, by creating a simple gadget XML file, including and including the necessary JavaScript.
{{{
var auth = "password";
gadgets.rpc.register("remote_alert", function(msg, auth_key) {
if (auth_key == auth) {
alert(msg);
}
});
]]>
}}}
Notice that the gadget also includes a call to gadgets.rpc.register. This declares a service that will be made available in the gadget to other iframes. In this particular gadget, a service called "remote_alert" is being configured, which accepts two parameters. The first parameter is the message to be displayed inside of the alert. The second parameter is an authorization key sent from the child iframe. To make sure the RPC request comes from an authorized iframe, this key is checked against a master key (auth) before the alert is displayed.
The gadget also loads the iframe to the remote page, and passes in the value of the auth key. In the example above, the key is static, changing only when the gadget XML changes. In a real gadget, you should configure the auth key to be randomly generated (and of a sufficient size to not be guessed by a malicious service trying to hijack your gadget) and create the iframe to include the generated value.
The HTML for the iframe is only slightly more complicated.
{{{
untitled
Alert!
}}}
This page, first, loads the gadgets.rpc !JavaScript (make sure to use the rpc.js appropriate for your container!). Next, a simple regular expression is used to pull the authentication key from the URL. A dummy callback function (some_callback) is defined, simply to demonstrate where a valid callback could be defined. Finally, in the body of the page a button is defined that, when clicked, first calls an alert locally (with the message "local"), and then calls the service registered in the parent iframe.
The gadgets.rpc.call declared above includes many parameters. Briefly described, the first declares the location of the target RPC ('' means the parent iframe). The second, is the name of the service called. The third, is the name of a local callback function to be executed when the call is complete. The fourth, and subsequent parameters are arguments to the RPC function — here, they are the message displayed and the authentication key.
Once the HTML page is saved to a public server (and the gadget is updated to point the iframe to this page) the gadget should be ready to go. When the gadget is loaded and the "Alert!" link is clicked, two alert boxes should appear. The first alert box should display "local", and the second should display "remote". In some browsers, the domain triggering the alert will also be displayed. In the local alert, it should display the domain of the server where you saved the HTML. In the remote alert, it should display the domain of the server rendering your gadget (some variant on gmodules.com for orkut and iGoogle).
With this simple example in mind, it should be possible to extend the functionality of the gadgets API to iframes included in your gadgets where, otherwise, those features wouldn't be available.