netvibes - (re)mix the web

We’ve seen how to switch to UWA pretty all available MiniAPI functionalities in this series’ previous articles. Now is the time to touch on functionalities that cannot be switch as-is, or simply put, that are not available in the stricter, more portable Universal Widget API.

One of the toughest of these is preferences. Sure, we’ve seen how to convert your MiniAPI configuration form into a UWA preference form, but there is one issue that seem to annoy switchers: UWA preferences are not as configurable as MiniAPI. That is, you cannot design them the way you’d do with classic HTML forms: UWA preferences are XML data that are parsed and display in a straight manner, without fuss.

Thing is, some developers really do miss the “fuss”: being able to place text fields side by side instead of on top of each-other, using an image for a given preference, coloring the background… All this could be done in MiniAPI, simply because the configuration form was plain HTML.

In UWA, preferences are set using XML, and in order to be truly portable, we had to let go the ability to customize the Edit form.

But that doesn’t mean that you still can’t get your very own stylish form - only not by using the widget:preferences, but your own tags inside the the body tag and handling it using JavaScript, just as MiniAPI used to do.

Once again, a fearless user leads the way

This is exactly what UWA developer Philip Hansen understood when converting his Daily Comics MiniAPI module to the Revised Daily Comics UWA widget.

See, Philip’s module used its configuration form to let the user choose the comics to display, among a rich list. That list was long enough with every comic placed side-by-side, but had he had to use the widget:preferences XML model, it would simply have gotten twice as long, and hard to manage for the user. So Philip basically took his old configuration code from his old MiniAPI module, and implemented it into UWA.

See the result: when the preferences are folded…

…and when they are expanded…

(As you can see, they are so long we had to cut a bit of it. Test them on the widget’s Ecosystem page)

Building the custom preference form

Philip’s form-building code is rather complex, because a has some special needs, but the main points are thus:

• the form is encapsulated in a div tag with the “comicform” class attribute
• the form is hidden at loading time through CSS: div.comicform { display: none; }
• a “Show/Hide Preferences” text is made into an empty link that shall be handled through JavaScript
• a “Save” button that actually saves all settings for next loading

Making sure settings are saved/retrieved

UWA’s preferences are saved to Netvibes’ server (or a local cookie if not available) every time the form is validated by the user. This way, the next time the widget is loaded, it also loads its previous settings. The preference form is the only one to have its content saved: any other form, created within the widget’s body, would have a blanc/default display on the next loading, whatever its content was.
A way to implement UWA’s preference saving rule into a custom widget is to apply the documented widget.setValue(name, value) method for each preference tag, and on loading the page, to look for data using the widget.getValue(name) method.

Philip’s widget does just this: on loading, it checks if a given setting is set, and applies it to the displayed widget…

for (comic in RevisedComics.fixed) {
  var sname=RevisedComics.shortname(comic);
  RevisedComics.addinput(comic,sname);
  if (widget.getValue(sname) != "true") continue;
  RevisedComics.createspan(comic,sname);
  RevisedComics.cdata[sname]['imgurl'] =
    RevisedComics.fixed[comic];
  RevisedComics.igen(sname);
}

(of course, this code only applies to Philip’s widget, which only uses checkbox, and therefore only needs to check for a true/false value. A more advanced form would require more advanced tests…)

…and on click on the form’s “Save” button, it saves all the checked boxes’ states:

RevisedComics.submit.onclick = function() {
  inputs = widget.body.getElementsByClassName('checkboxes')
  for (var i = 0; i < inputs.length; i++) {
    if (inputs[i].checked == true) {
      widget.setValue(inputs[i].name, "true");
    } else {
      widget.setValue(inputs[i].name, "false");
    }
  }
  RevisedComics.form.style.display = 'none';
  RevisedComics.refreshfunc();
}

Note that RevisedComics.refreshfunc() is the very method that builds check for set values and builds the content accordingly: hence, as soon as the custom form is saved, the content is updated, just as you would expect from a standard UWA preferences form.

Replicating the show/hide user interface

The “Show/Hide Preferences” link is pretty easy to set up, thanks to the combination of JavaScript and CSS. All we have to do is display the form if it’s hidden, and hide it if it’s not. Here is the whole code:

RevisedComics.link =
  widget.body.getElementsByClassName('preflink')[0];
RevisedComics.link.onclick = function() {
  if (RevisedComics.form.style.display == 'block') {
    RevisedComics.form.style.display = 'none';
  } else {
    RevisedComics.form.style.display = 'block';
  }
}

The widget.body.getElementsByClassName('preflink')[0]; call targets this line of HTML, assigning it the JavaScript behavior we have just described, using the tag’s class attribute:

<a class="preflink" href="javascript:void(0)">
  Show/Hide Preferences</a>

Being creative

While Philip’s code is pretty complex due to internal constraints, his custom preferences form is actually pretty quick to set up. From there on, you can imagine implementing anything you want, and keeping with the style of your MiniAPI configuration form.

Just remember that there is a good reason why a moved from an HTML-based configuration form to a XML-based one between MiniAPI and UWA: having your form in the body of your widget might prove not to be as portable a true UWA preference form would. Be sure to test your code thoroughly, and to handle as many platforms as you can.

Tags: conversion, custom, getvalue, miniapi, preference, setvalue, uwa

This entry was posted on Wednesday, March 19th, 2008 at 5:57 pm and is filed under Articles, Tutorials. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.