Many of the most interesting widgets will need some form of authentication, which requires the passing of passwords. Because passwords must not be handled in a clear text way, as it is done for other preferences, we set up specific tools for handling them.

Please note that the UWA password and HTTP authentication tools are still experimental. For now, it only works within Netvibes, or in standalone mode, and only if the widget is displayed inline - it won't work if it is displayed in an IFRAME.

Each mode has its specificities:

• in Netvibes:
  • the password are sent only the first time to the server, and are encrypted there
  • using HTTPS is encouraged
• in standalone mode:
  • the password is stored in a cookie, and sent for each request

Password preference use a specific preference type: password. A username/password combo would therefore be writtent like so:

<widget:preferences>
  <preference name="username" type="text" label="Username" />
  <preference name="pass" type="password" label="Password" />
</widget:preferences>

In non-authenticated mode, a widget should display only as few elements as possible - as it is pointless displaying a design before there even is data to fill it with. Our advice is to only replace the usual <p>Loading…</p> message with a <p>Please authenticate.</p>, possibly hiding the rest of the interface using the element.hide method.

A way of only displaying your interface if the user has entered his login information is as follows:

if ( widget.getValue('username') )  {
  widget.body.getElementsByClassName('content')[0].show();
  YourWidgetName.startLogin();
} else {
  widget.body.getElementsByClassName('content')[0].hide();
  widget.body.getElementsByClassName('message')[0].setHTML('Please authenticate.');
}

The whole login process is dealt with by UWA as soon as the username and password fields are filled in.

To properly use authentication, you need to use the UWA.Data.request method with the authentication setting set to the authentication object. That is a JSON object of the following form:

{ 
  moduleId: widget.id, 
  username: widget.getValue('username'), 
  type: 'http_basic' 
}

Once UWA has verified that the user is using the correct account for the widget's service, you can retrieve the user's content using the UWA.Data.request method, to which you add the authentication parameter.

This last parameter should contain the authentication object.

YourWidgetName.startLogin = function() {
  UWA.Data.request(
    'http://example.org/myapi.php',
      {
      method: 'get', 
      type: 'json',
      onComplete: YourWidgetName.displayPrivateContent, 
      authentication: { moduleId: widget.id, 
        username: widget.getValue('username'), type: 'http_basic' } }
  );
}

To ensure that authentication works outside of the Netvibes environment, it is necessary to not directly provide the authentication object, but to point to a method, which will make sure we are providing the right data. In our examples, our method is called getAuthentication.

YourWidgetName.startLogin = function() {
  UWA.Data.request(
    'http://example.org/myapi.php',
      {
      method: 'get', 
      type: 'json',
      onComplete: YourWidgetName.displayPrivateContent, 
      authentication: YourWidgetName.getAuthentication()   
      }
  );
}
 
YourWidgetName.getAuthentication = function() {
  var authentication = { moduleId: widget.id, 
    username: widget.getValue('username'), type: 'http_basic' }
  // enable authentication outside of Netvibes
  if (widget.data.pass) 
    authentication.password = widget.data.pass;
  return authentication;
  }

Once your data is retrieved, it is sent as the first argument of the method provided in the onComplete parameter, here YourWidgetName.displayPrivateContent, which will use it to properly build the HTML representation of the data. How that representation is built is not up to the developer…

Retrieving private data is one thing, but a widget is even more useful if the user can update his content through it, securely. Fortunately, the authentication process also works for POST request, which allows us to add data in the request parameters.

YourWidgetName.submit = function {
  var data = widget.body.getElementsByTagName('textarea')[0].value
  UWA.Data.request(
    'http://example.org/submitData.php',
    {
      method: 'post',
      proxy: 'ajax',
      parameters: 'data=' + data + '&uid= ' + Math.ceil(Math.random() * 1000),
      onComplete: YourWidgetName.onSubmitOK,
      authentication: YourWidgetName.getAuthentication()
    }
  );
}

The bulk of data to be sent is here gathered in the data variable, which is filled with the value of the first textarea found in the widget (we could also use a unique class on this tag, and target it with getElementsByClassName, in order to differentiate it from potential other textareas). Just to show how to send multiple parameters in the POST request, we added a random id in the parameter option of the request JSON object - this is in now way mandatory.

We use the same authentication method as for retrieveing data, through the authentication option, and using the onComplete option we set the method to be triggered on a successful submit to onSubmitOK. This last method could be used to reload the whole content throught Ajax, which would now include the recently submitted item.