netvibes - (re)mix the web

One question keeps coming up from people who have taken the dive and converted their module to a widget. It’s pretty simple, and represents an essential part of such conversion. This post will therefore be suitably short.

I’m done converting. It works. What’s next?

The “what’s next?” part implies a lot of questions, but mostly they are centered about the proper way to replace the module with the widget, and if/how Ecosystem will recognize it all. Also, does the user have to reinstall it? What happens to the user’s saved preferences? So, let’s tackle this: the transition period from MiniAPI to UWA.

Use the same URL if you can

One very important thing to understand on how Netvibes handles modules/widgets: your file is not stored on Netvibes server (unless it’s been inlined by us), but is directly fetched on your server through our proxy, every time the user loads his page (depending on cache).

This implies that:

• while developing and debugging your UWA widget, you should keep the MiniAPI module available for current users.
• once the UWA version works as expected, you should move the file to replace the MiniAPI version - and keep that previous version nearby for historical purpose

By placing the finalized UWA version at the exact URL of the previous MiniAPI version, the current users of your widget will not have to change anything, or add it again: their page stills points to the known URL, which is now a UWA widget. Our proxy will recognize the change, and display the widget accordingly. No fuss, just bliss.

Do not resubmit your widget to Eco, but contact us instead

Since your widget is already at the exact same URL as the previous MiniAPI version, its Ecosystem page is also already pointing to the correct URL, and new users can directly add the new version to their page. Great!

But Ecosystem treats MiniAPI modules and UWA widgets differently ; namely, as you might know, UWA widgets have the additional bonus of being portable to numerous platform, and Ecosystem is the place where a users can choose to install it (or download it) for any other platform than Netvibes. A module’s page does not feature such link.

Ecosystem only links to your item’s URL, without knowing much about it. The item’s type is determined on the first time you submit it, and remains set. Basically, Ecosystem has no way to automatically recognize when a module has been converted to a widget.

Yes, you probably guessed: the item’s type has to be changed from “MiniAPI” to “UWA” by hand, on our side, in order for your widget to unleash its full portability potentia. It might sound a bit cumbersome, but it’s actually pretty quick to do.

So once your widget is ready for the world, contact us directly using the feedback form, with the item’s Ecosystem ID (the number at the end of its URL) and its name, and you it should be updated in the next couple of days.

Make sure you don’t break the user’s settings

If your MiniAPI module has a configuration form, chances are that users have fiddled with it - and that they expect it to work continuously. Converting your module to a UWA widget shouldn’t break that expectation.

This is why, when converting your module, you should make sure that the widget’s preference form is the exact replica of the module’s configuration form.

Not only should your widget feature the same preferences as the module had, but each preference should have the same name (not label). For instance, if your MiniAPI module had this:

  Name : 

  
  Surname : 

…then you should make sure that in the UWA widget, the preference’s name attribute is exactly the same :

The value is saved by the displaying platform using the name attribute, tied to the URL. Keeping it the same during the conversion ensures that your existing users do not lose their recorded settings. If you don’t, your users will simply have to re-enter their settings, which is not much of a burden, but is still better kept avoided.

About inlined modules

From now on, widget are displayed within an iframe, to ensure maximum portability and security. That is the reason why modules that required to be inlined to work correctly will probably miss a few features, and need updating.

If you cannot use the same URL…

There will of course be some case when a developer won’t be able to keep the same exact URL during the conversion. This implies a couple issues and solutions…

Ecosystem

You still shouldn’t re-submit your widget’s URL to Ecosystem, but should rather update the existing URL with the new one. To achieve this:

1. While logged-in, go to your Ecosystem’s My Widgets page
2. Click the Edit button (right under the title)
3. In the Widget Details area, paste the full URL of the UWA widget in place of the one for the MiniAPI module
4. Validate your change by clicking on the Update button
5. Contact us so that we change your item’s type from “MiniAPI” to “UWA” in our backoffice.

Existing users

Those who have already installed your module will still have their page point at the old URL, and will not see it be updated to the new URL. They therefore will need to install the new version, and a way to make them do that is to update the module so that it displays the widget’s Ecosystem URL directly in its content. Of course, the Ecosystem URL must be up-to-date by the time this link is placed in the module…

These are the main issues to understand when you reach the final steps of converting your module to a widget. As always, if you need any help or have any question, the forum and the feedback form are here for you.

Tags: conversion, ecosystem, inline, miniapi, preference, uwa

This entry was posted on Thursday, February 14th, 2008 at 4:55 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.