Core-Gadget - OAuth Popup

    <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 &lt;Require&gt; or &lt;Optional&gt;
     element with the &lt;ModulePrefs&gt;. 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>
  &lt;Module>
    &lt;ModulePrefs>
      &lt;Require feature="oauthpopup" />
      &lt;OAuth>
        &lt;Service>...&lt;/Service>
      &lt;/OAuth>
    &lt;/ModulePrefs>
    &lt;Content type="html">&lt;![CDATA[
      &lt;div>
        &lt;a href="#" id="personalize">Personalize this gadget&lt;/a>
      &lt;/div>
  
      &lt;div>Please click
        &lt;a href="#" id="approvaldone">I've approved access&lt;/a>
        once you've approved access to your data.
      &lt;/div>
  
      &lt;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);
      &lt;/script>
    ]]&gt;&lt;/Content>
  &lt;/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>
  &lt;Function&gt; 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>
  &lt;Function&gt; createApprovedOnClick()
           </artwork></figure>
         </section>
       </section> 
     </section>    
   </section>