Core-Gadget - OAuth Popup
This is a DRAFT
<section title="The OAuth Popup Feature (gadgets.oauth.Popup)" anchor="gadgets.oauth.Popup">
<t>When a gadget attempts to access remote resources that are
protected using either the OAuth 1.0a or 2.0 protocol, the
container is required to first determine if the gadget has
received appropriate authorization in the form of an "Access Token".
If a token is not available, the container must ask the gadget
to first acquire the appropriate authorization.</t>
<t>With most scenarios, this is achieved by redirecting the user
to the third party OAuth Authorization Service and asking them to
approve access. While gadget developers are responsible for determining
how such redirection occurs, they can use the OAuth Popup Feature to
simplify the process and to promote consistent, familiar behavior.</t>
<t>The feature works by generating a hyperlink within the gadget's
user interface that, when clicked, opens a window that displays the
third party OAuth Authoriation Service's interface. When opened, the
gadget is notified via a callback function that the window is open.
The user will either approve or deny the request and then dismiss the
window, returning the user back to the gadget's user interface. The
gadget can either then automatically proceed with processing the
request or wait for the user to notify it when it continue.</t>
<t>Use of the OAuth Popup Feature is enabled within a gadget by using
feature="oauthpopup" in either a <Require> or <Optional>
element with the <ModulePrefs>. Once enabled, the
<spanx style="verb">gadgets.oauth.Popup</spanx> object will become
available for use within the JavaScript of a gadget view.</t>
<figure><preamble>The example below illustrates the basic operation of
the OAuth Popup Feature:</preamble><artwork>
<Module>
<ModulePrefs>
<Require feature="oauthpopup" />
<OAuth>
<Service>...</Service>
</OAuth>
</ModulePrefs>
<Content type="html"><![CDATA[
<div>
<a href="#" id="personalize">Personalize this gadget</a>
</div>
<div>Please click
<a href="#" id="approvaldone">I've approved access</a>
once you've approved access to your data.
</div>
<script type="text/javascript">
function $(x) {
return document.getElementById(x);
}
function fetchData() {
var url = "http://localhost:8080/social/rest/people/@me/@self";
var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
params[gadgets.io.RequestParameters.AUTHORIZATION] =
gadgets.io.AuthorizationType.OAUTH;
params[gadgets.io.RequestParameters.METHOD] =
gadgets.io.MethodType.GET;
params[gadgets.io.RequestParameters.OAUTH_SERVICE_NAME] =
"shindig";
gadgets.io.makeRequest(url, function (response) {
if (response.oauthApprovalUrl) {
var onOpen = function() {};
var onClose = function() {
fetchData();
};
var popup = new gadgets.oauth.Popup(
response.oauthApprovalUrl,
null, onOpen, onClose);
$('personalize').onclick = popup.createOpenerOnClick();
$('approvaldone').onclick = popup.createApprovedOnClick();
} else if (response.data) {
...
} else {
...
}
}, params);
}
gadgets.util.registerOnLoadHandler(fetchData);
</script>
]]></Content>
</Module>
</artwork></figure>
<t>Once the <spanx style="verb">gadgets.oauth.Popup</spanx> object
is created, the calls to <spanx style="verb">popup.createOpenerOnClick</spanx>
and <spanx style="verb">popup.createApprovedOnClick</spanx> generate the
appropriate hyperlink targets for acquiring and completing the authorization.</t>
<section title="JavaScript API">
<t>When the OAuth Popup Feature is enabled for a gadget, the
<spanx style="verb">gadgets.oauth.Popup</spanx> object becomes
available for use within the gadget's JavaScript code.</t>
<section title="The gadgets.oauth.Popup Object" anchor="gadgets.oauth.Popup.ctor">
<t>The <spanx style="verb">gadets.oauth.Popup</spanx> object
is used to manage a window that is displayed and used to acquire
OAuth Authorization from a third party. Instances of the object
are created using the JavaScript new keyword.</t>
<figure><preamble>For instance:</preamble><artwork>
var popup = new gadgets.oauth.Popup(
destination,
windowOptions,
openCallback,
closeCallback);
</artwork></figure>
<t>The constructor accepts the following input parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>destination</c>
<c>String</c>
<c>Target URL to display when the window opens.</c>
<c>windowOptions</c>
<c>String</c>
<c>Options for window.open, used to specify look and feel of the
window.</c>
<c>openCallback</c>
<c>Function</c>
<c>Function to call when the window is opened.</c>
<c>closeCallback</c>
<c>Function</c>
<c>Function to call when the window is closed.</c>
</texttable>
</t>
<t>The <spanx style="verb">gadgets.oauth.Popup</spanx>
object exposes two methods: <spanx style="verb">createOpenerOnClick</spanx>
and createApprovedOnClick.</t>
<section title="gadgets.oauth.Popup.createOpenerOnClick" anchor="gadgets.oauth.Popup.createOpenerOnClick">
<t>Generates a function that is intended to be assigned to either
a hyperlink (e.g. the onclick event of the HTML anchor tag) or
similar mechanism (e.g. an HTML button) that when invoked, will
display the OAuth Authorization window. The method accepts no
input parameters and returns a JavaScript Function object.</t>
<figure><artwork>
<Function> createOpenerOnClick()
</artwork></figure>
</section>
<section title="gadgets.oauth.Popup.createApprovedOnClick" anchor="gadgets.oauth.Popup.createApprovedOnClick">
<t>Generates a function that is intended to be assigned to either
a hyperlink (e.g. the onclick event of the HTML anchor tag) or
similar mechanism (e.g. an HTML button) that when invoked, will
notify the container that OAuth authorization is complete.</t>
<t>Typically, when the OAuth Popup window closes, the container
will be able to automatically detect that authorization is complete
and it will attempt to continue with the original request that
triggered the authorization step in the first place. However, some
containers are unable to detect when the Popup is closed. For those
cases, the <spanx style="verb">createdApprovedOnClick</spanx> method
provides a alternative. In most typical scenarios, however, the
"Approved" function returned by this method will never be invoked.</t>
<t>The method accepts no input parameters and returns a JavaScript
Function object.</t>
<figure><artwork>
<Function> createApprovedOnClick()
</artwork></figure>
</section>
</section>
</section>
</section>