While its documentation has been severly improved since then (let us know if you consider it could still be better!), there remains a feeling that implementing tabs in a widget is a complex task, best left to wizard developers.

It’s not! And this article will drive the more sceptic among you through code samples that should make everything clear. Here goes.

Sample 1: three different tabs

The first sample code presents how to combine 3 widgets into one widget with 3 tabs, each one displaying the same content as the original widget. The three panels will display, in our example,

• some regular text;
• the latest Astronomy Picture of the Day, as per the APOD sample widget;
• the latest posts from this very blog, as per the RSSReader sample widget.

The resulting widget is available here.

We can only advise you to dive into its code, and compare to the original widgets’ code. We’ve provided as much comments as possible, so as to help you understand how we implemented some parts.

Sample 2: three different tabs, paging in feeds

You’d notice in the previous example that we did not use the Pager component, in order to simplify the code to the maximum. Therefore, if the user were to change the preference to only display the 5 of the 10 items in the feeds, he wouldn’t get the expected “prev/next” buttons at the bottom of the widget. This is what this sample code implements.

The resulting widget is available here.

The difference with the previous sample code mostly resides in the block of code that starts with this line:

var pager = new UWA.Controls.Pager(

Here, the pager object is instantiated, and the rest of the code show you how to properly have it displayed.

Sample 3: three tabs with a different feed each

As you may know, the most popular use of tabs is to have one widget for many feeds, thus reducing the needed space. To that end, you’d need to re-use the previous sample widget, and duplicate the third tab into the two first ones.

The resulting widget is available here.

Since we remove the code that displays the first two tabs (the text one, and the image one), the code gets shorter, but you should actually pay more attention to the code, because it presents how to have the logic work for us, and not crash the widget every time we change tab.

For instance, in the previous sample code, the pager was placed in a given, non-changing DIV tag:

var pagerDiv = widget.createElement('div', {'class':'paging'});

It is important to understand that each of the three tabs require its one pager, and therefore to have the code properly implement the pager so that tab-changing would not break it:

var pagerDiv = widget.createElement('div', {'class':'paging_'+tabName});

There are more advanced uses of the TabView control, which will have a look at in another post…

Your turn!

Go ahead, dive into each sample widget’s code, and you should come out of it with more understanding of tabs and their inner working.

Share this post:

A reminder: JavaScript in UWA

As UWA developers know, portability and predictability in the framework’s usage has lead us to not recommend the use of JavaScript objets such as ‘window’ and ‘document’, instead recommending the equivalent to some of their methods that have been implemented in the UWA-specific ‘widget’ objet. For instance, ‘window.open()’ is to be dropped in favor of ‘widget.openURL()’, or document.getElementById(’uniqueID’)’ is to be replaced by unique classes and the use of ‘widget.boy.getElementsById(’uniqueClass’)[0]‘, among other things.
Failing to find the needed function equivalent in the UWA JS Framework, developers are suggested to implement the required code within the widget’s HTML page.

That is all fine and dandy: all UWA developers are now used to play with these idiosynchrasies, and their widgets just get sturdier thanks to that. But when it comes to Flash-JavaScript communication, things get more “idiosynchratic”, if you will…

The curious case of Flash-JavaScript communication

Flash-JS communication is a subject at least as old as Flash itself (well, at least as old as Flash 2 and FSCommand, then). The solutions at the time seemed almost magical, nowadays they are well understood and implemented within ActionScript – the Flash scripting language.

Calling a JavaScript function from the Flash application’s containing HTML page only requires a couple of ActionScript lines with Flash CS4. Let’s say we have on our Flash scene two main instances: a textfield named myInputText and a button named myButton. With a click on myButton, we want Flash to send the text content of myInputText to a JavaScript function called, for lack of a better name, theJavaScriptFunction().

Here’s how our ActionScript code could look like:

import flash.external.ExternalInterface;
myButton.addEventListener(MouseEvent.MOUSE_DOWN, mouseDownHandler);
function mouseDownHandler(event:MouseEvent):void {
  if (ExternalInterface.available) {
    try {
       var tempStr:String = ExternalInterface.call("theJavaScriptFunction", myInputText.text);
    }
    catch (error:SecurityError) {
       // ignore
    }
  }
}

Basically, with Flash CS4, the ExternalInterface object is the central place to improve your communication skillz. Past versions of Flash had other methods, that we’ll let you peruse at will, since it’s a safe bet CS4’s methods are here to stay…

Flash-JavaScript communication in UWA

Since UWA isn’t much more than a XHTML page, having Flash communicate with JS in that context should be a cake, right?

Wrong. Remember the first part of the article, where I reminded you of the “no ‘document’ object” recommendation? Well, as it turns out, JS method calls from Flash are targetted at the document – which means, basically, that if you try to call your MyWidget.AwesomeFunction(), Flash will in fact target document.MyWidget.AwesomeFunction(). Hilarity ensues.

One solution here is to break out of the “no ‘document’ object” rule, and build a proxy function for each JS method that you want called. For instance, in order to call this function:

MyWidget.AwesomeFunction = function(var) {
  // some code
}

…you’d simply have to define a proxy AwesomeFunction directly on the page’s default object (the ‘document’ one), and have it call your UWA-tied function, like so:

function AwesomeFunction(var) {
  MyWidget.AwesomeFunction(var);
}

So, this would tend to prove a little diversion can go a long way. But wait! There’s more!

Making your way through domains

Official explanation graphic from Adobe

Let’s say your ActionScript and JavaScript code is in place, as explain above. You load the widget directly in your browser (standalone mode), and it just works: awesomeness! But then you decide to install the widget on a Netvibes page, and lo!, it fails to even trigger AwesomeFunction(). Fatalitas!

No, Netvibes is not blocking such usage of UWA code. Simply put, Flash has some security restriction which you will need to check one by one before you can make it all shine.

The basis of these security measures is the domain name. In short, by default, a Flash app (.swf) can only communicate with external files (.html, .php, .xml, .js …) if it is hosted on the very same domain name.

This behavior is therefore broken once in Netvibes (or any Exposition-based widget server, for that matter), since widget’s are not only displayed within an iFrame (which might be a problem in itself), but also on a unique domain name. Hence, the HTML file can never be on the same domain as the SWF file, and therefore the data loading (or JavaScript communication, in our case) cannot happen.

Luckilly, Macromedia at the time undertstood that need, and gave us support for a crossdomain.xml file, which would let the developer allow (or disallow) a given set of domain to be accessed by the SWF. This XML file, hosted at the root of the domain bearing the Flash file, can take this form:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
  <allow-access-from domain="*" />
</cross-domain-policy>

For added fun, you can add the following lines to your ActionScript code:

import flash.system.Security;
Security.allowDomain("*");

These lines are another way for Flash to validate crossdomain access.

One down, only one more to go….

But that’s only for data, here. What we need in our case is access to the local JavaScript. This, in turn, is made possible by adding the AllowScriptAccess attribute in the SWF’s embed code, and setting it to “always”. Your embed code would therefore look like this:

<embed type="application/x-shockwave-flash"
  src="http://domain-name.net/uwa-flash.swf"
  width="250" height="100" bgcolor="#FFFFFF"
  AllowScriptAccess="always"></embed>

Still willing to use Flash for your widget? Then hop onto the next section!

Handling UWA preferences from a Flash application

As if that wasn’t enough, there are cases where you’d like your Flash application to make use of UWA’s preferences methods, if only in order to record the user’s settings for the Flash app within the confines of the UWA environment.

This case should be view from two points:

1. Have the Flash settings be saved as UWA preferences;
2. Have the Flash app load the UWA preferences on startup.

The first part is pretty ease if you you follow the instructions above: instead of calling widget.setValue() directly from ActionScript (which would result in document.widget.setValue() being called instead, and therefore nothing happenning), you’d call UWA_setValue(), which in the HTML file would be defined as…

function UWA_saveInPref(varid) {
  widget.setValue('myValue', varid);
}

Obviously, if you have more than one preference to set from Flash, you’d nees to expand on this code a bit…

Now, we want the SWF file to load up a preference, but only if it is set (obviously, else it would load the preference as ‘null’ or other unset values). That can be done pretty easily by passing variables to Flash via the embed code’s URL (or more precisely, its query string).

Why, yes it is!

Here is one way to get a nice, working query string for your Flash app…

First, retrieve the preference value, and build it into your query string via a ternary operator, for instance. Here is an example:

var myValue = widget.getValue('myValue');
div_flash.innerHTML += '<embed type="application/x-shockwave-flash"
  src="http://domain-name.net/uwa-flash.swf'+ (myValue?'?theValue='+myValue+'':'')
  +'" width="250" height="100" bgcolor="#FFFFFF" AllowScriptAccess="always"></embed>';
widget.setBody(div_flash);

If the ternary XXX finds that myValue is not empty (ergo, the preference is set), then it assigns its content to the Flash app’s theValue internal variable. If it is empty, ‘theValue’ is not even defined in the query string, and the Flash app launches in its default state – which is pretty much the whole point of this ternary operator.

Second, add the following two lines of ActionScript in your SWF’s first frame (given that you want to update a ‘myInputText’ textfield based on that query string):

var myQueryStrings = this.loaderInfo.parameters;
myInputText.text = myQueryStrings.theValue;

This will load our query string (using the loaderInfo object and its ‘parameters’ property), and assign the ‘theValue’ value as the text content of our beloved myInputText. Done: the textfield is updated with the correct UWA preference on each loading (or preference update)!

You can see it for yourself with this basic widget, the code of which is available here (you might need Flash CS4).

Two final tips, for the road

1) Don’t forget to add wmode=”opaque” to your embed code, so that i doesn’t overlap with Netvibes’s content!

2) Choose the “hidden” preference type if you want that preference to only be changeable through your Flash app!

Now go and build more awesome Flash-based UWA widgets!

Share this post:

Today marks another milestone for animated themes in Netvibes, with the official support of 10 brand new themes, which obviously make plenty o’ use of time ranges.

I want my own!

We hear ya! One of the great projects released with the Netvibes Labs launch, back in April ‘09, was the Theme Designer, which allowed you to design your theme visually rather than through a tedious XML format.

However, our Theme Designer is not yet able to build animated themes (that’s planned for a further iteration), so in order to feast your visitors’ eyes with an everchanging design, you will still have to dive into the code. Don’t be scared: it’s quite easy as long as you know how to handle XML.

Our theme documentation already features most of the information you might need in order to code your own theme, be it static or animated.

In this article, we’ll dive into building a complete animated theme step by step, using the Theme Designer. That editor doesn’t yet support animated themes, but we can just as well use it to build a handful of static themes, and merge them into one file by hand, in order to get an animated theme!

Step one: Deciding on the time ranges and graphics

Before we hop into the editor and start choosing the header color for widgets, you should first have a clear idea of what you want your theme to look and behave like – which could greatly impact the header graphics.

For instance, you can have up to 24 different designs (one per hour of the day/night), but you can just as well have an animated theme with two different states.

For the purpose of this article, we’ll show you how to build a 5-parts theme, with 3 different behaviors: work, lunch, and spare time – therefore, your visitors will be able to know what you’re up to just by looking at your theme!

Each behavior fits into a specific time range:

1. 12am-9am: spare time
2. 9am-1pm: work
3. 1pm-2pm: lunch
4. 2pm-7pm: work
5. 7pm-12am: spare time

Note that while the two “spare time” ranges are next to each other, the XML format requires us to keep them separated rather than having a single “spare time” range going from 7 PM to 9 AM: valid time ranges are from 12am – 12am, and if the end time is before the start time, it will cause an error.
Also, make sure you set ranges for the full 24h of the day — you wouldn’t want your users to miss out on an hour…

Step two: Making the graphics

Our theme  has 5 parts, but we will base it upon 3 designs: “lunch” (used once), work (used twice) and “spare time” (used twice).

We’ll leave the graphic creation to you, and will simply remind you of the size recommendations for a good header image, as well as useful information:

• Images should be at least 175px tall. Since the user can expand the header’s height, it is recommended to go up to 260px, or even 300px to be on the safe side.
• Center image must be at least 640px wide.
• Tile image can be any size, but must wrap-up seamlessly.
• Image should not weight more than 100 kb. Recommended weight is 40 kb, but prefer better quality to smaller size.
• Images are centered in the header, both horizontally and vertically.
• Images can use any format. Recommended are PNG andJPG, but GIF can of course be used. Use PNG/GIF if you need to use transparency.

A lot more information is available in the theme documentation, such as a description of the various layers available for the header, and image tiling…

Step three: Making the themes using the Theme Designer

Now that you have everything at hand, you can launch the Theme Designer and simply fill-in the blanks for each section. You’ll have to do that for each of the various time ranges of your animated theme.

Once you feel you static theme is perfect, you can save it by clicking on the “Download theme” button, available from the Main tab. You end up with an XML file containing all the needed info for your static theme, and named “theme.xml” – which we advise you to promptly rename into something more informative, for fear of overwriting it with your next theme saving.

Step four: Merging static themes into a animated theme

Each of the three static themes we have created are wholly contained within the <ConfigMap type=”Skin”>…</ConfigMap> tags of each of their respective XML files. One theme XML file can contain more than one such <ConfigMap> tag, and they are differentiated using the sub-tag <Trait>, as explained in both the theme documentation and the announcement from last month.

Therefore, merging static themes into one animated theme is simply a question of copy/pasting the <ConfigMap> tags from all files into the remaining one, after its own such tag. Once the pasting is done, add a <Trait> tag with the proper time range settings to each <ConfigMap>, and you’re pretty much done!

In our case, we have three static themes which apply to 5 time ranges, so two of them are bound to be duplicated within the XML. They will be singled out by their <Trait>.

In order to build our animated theme, we’ll start with the file for the static theme tied to the first time range, then paste the <ConfigMap> tags from the two other files into 5 distinct <ConfigMap> section, and finally differentiate them using their very own <Trait> tags. The sequence of the <Trait> tags might be as such:

1. “spare time” theme: <Trait name=”TimeOfDay”>12am-9am</Trait>
2. “work” theme: <Trait name=”TimeOfDay”>9am-1pm</Trait>
3. “lunch” theme: <Trait name=”TimeOfDay”>1pm-2pm</Trait>
4. “work” theme: <Trait name=”TimeOfDay”>2pm-7pm</Trait>
5. “spare time” theme: <Trait name=”TimeOfDay”>7pm-12am</Trait>

Easy as peas!

Step 5: applying the theme on your page

You must upload the XML files and all the media files it uses on a public host in order to apply it. Do not remove it from the host after installation, since your page would lose the theme altogether…

Now comes the part were you get to see your theme in action. As explained in the documentation, you can apply the theme on either one of your private pages, or your public (or all of them!) – it all depends on the syntax you use.

If it’s on a private page:

1. Go to that page of yours ;
2. Type the following in your browser’s adress bar:
   http://www.netvibes.com/?theme=http://URLOF YOURTHEME

If it’s on your public page (http://www.netvibes.com/PAGEID):

• http://www.netvibes.com/?visit= PAGEID&theme=http://URLOF YOURTHEME

Explore 10 exclusive themes!

The 10 exclusive animated themes that were released today are available for your to browse through, in order to learn how to build awesome themes yourself!

Here are the links to their XML files, along with links to apply them on your current private page:

• 4 Seasons (apply it)
• 24 Hours (apply it)
• Aurora (apply it)
• Colors (apply it)
• Food (apply it)
• Grey Texture (apply it)
• Heart (apply it)
• Lightness (apply it)
• Sea Serpent (apply it)
• Yann Arthus-Bertrand (apply it)

Caution: Applying one of these themes will replace the current theme.

Show us your own themes!

Share this post:

Here is a sample link: http://www.netvibes.com/share?title=Netvibes%20is%20awesome!&url=http%3A//www.netvibes.com/

The resource http://www.netvibes.com/share accepts the following parameters:

• title : Title for the shared link (my be URL-encoded);
• url : The link itself (must be URL-encoded);
• autoclose : Set it to 1 if you want the popup window to close after submission.

To URL-encode your links, you can use the function urlencode in PHP or encodeURIComponent in Javascript.

We tried to make it easy for anyone to integrate those links in any page by keeping it very simple. However, if you’re looking for turnkey solutions, some universal sharing buttons have already integrated Netvibes and you may use one of them.

Share this post:

The ability to work on blogs, and for that matter on any website,  has always been part of UWA starting with the now-deprecated BlogWidget method. BlogWidget was a nice first try at including UWA widget within the premises of a website, but in the long run was a hassle to instal, and for us it quickly became hard to maintain.

UWA compilers have improved a lot since last year, and the release of the Ecosystem was for us a chance to push further the proverbial envelope of exporting UWA widgets. So we built UWA export right into Ecosystem, and called it Share.

Let’s say you like news so much, you want your website’s visitors to see our New-York Times widget in your sidebar. With the new Share tool, this previously laborious task has gotten very easy: go to the widget’s Ecosystem page, and click on the Share button, located next to the widget preview, right between the install links for the current 5 support platforms and the Source button, in all its orange glory.

Clicking that link brings you to a whole new tool in Ecosystem, where you can configure the look of the widget for better inclusion in your website. There, you can change the widget’s title, its height and the color of the header. While make these changes, you can see them live in the preview on the right side of this export tool, and can even update the height manually rather than using the counter.

Since exported widget do not offer an Edit section (by design), this tools lets you configure the widget’s preferences directly.

Once you are happy with the preview, you can directly grab the HTML code in the section below. As you can see it’s still pretty close to the old BlogWidget method, but believe me, it really has improved since that first version, the export tool being just the surface of it.

The most advanced among you might even find it cool to dabble with the code directly rather than through the interface…

Stick that in your website’s HTML code, at the right place, upload, reload, and you should new be the proud owner of a UWA widget on your website!

Share this post:

One of these “toys” is the expanded Timeline Search. As a Netvibes user, you must know about the User Timeline, where a user can post his good links, his favorite posts or simply his though of the moment, and let all your followers see them.

These three kinds of item can be posted to the timeline, respectively, using the Star-It widget (which uses the new widget.addStar() method, so you can also build starring within you own widgets), via a click on the little star that is displayed by some widgets (one of which is the internal feed reader, so that makes it easy for blog posts and podcasts), and the My Community widget (which you can find in the Essential Widget section of the Add Content panel). 

It’s all fine and dandy, but you might think that all this data is only available to logged-in Netvibes users who chose to follow your Universe – and therefore, quite walled-garden-y for the reste of teh intarwebs. Luckily, there’s more than that.

When we announced the Netvibes REST API a couple months ago, it already gave a lot of power to developers, like retrieving the whole content of a Netvibes Universe in XML form, but the documentation for the Timeline Search method wasn’t really complete a the time. We’ve been working towards improving it, and the result is that you can now easily use the Timeline data just about anywhere, thanks to an expanded set of options.

In short, the expanded Timeline Search makes it possible for anyone to create services or tools based on public Timeline data retrieval! Desktop apps, anyone?

The documentation itself features a handful of ideas already:

• Need to pull the 100 last public status updates in Atom format? You can do it.
• Want to know who’s been mentioning the iPhone 3G lately, and get it in JSON? Have a lookee here.
• Feel like visiting the recent favorite links of one’s followers, in XML? Here you go.
• Fan of the “FAIL” meme, and want to know who’s been commenting items with “FAIL”? Yup, can do.

This is just a part of what can be done with the REST API, and an avant-goût of things to come from our recent developments. Until we uncover these, you advise you to have a closer look at all the possibilities of the Netvibes REST API, which can offer a lot more than searching public timelines…
 

Share this post:

It was all content and code, until now: the design part of the widget is when that got little love around here until now, but truly deserve it. Once you have coded your widget and it’s full of content goodness, the best way to set it apart from other widget that display the same content, is to display it in a more attractive way.

There are many ways to design a better, and we’re going to explore some of them in this post.

Re-use your knowledge

Keep in mind that thanks to UWA being based on well-known web-standards, you can apply your CSS, table and/or font magic on your widget just as easily as you would. From this standpoint, widgets are just smaller websites: you can make use of your usual tricks of the trade, and even CSS hacks if needed, to achieve the look you need.

One thing to remember, though, is that even if your content is displayed in smaller setting that on a good ol’ website, you still don’t know the width of the container. Not only can the Netvibes user set his page to display widgets in a given number of columns (up to 4 currently), or even resize columns independently , but thanks to the portability of UWA, you widget can find itself displayed through a number of widget platforms, through the browser or on the desktop.
In short: cater for all possible width, and set up your content to display harmoniously from 320 pixels wide to 1280 or more. Use percentages wisely! If you are stuck with fixed width, at least try to keep it centered, so that it looks good even in one column.

From there on, you can apply to your widget all the good advices you might have received from classic web-design books, using the technique you feel more comfortable with: align your form elements and general content so as not to present a mess to your users, KISS (don’t overwhelm with content), balance graphics and white-space in a legible way, etc.

Use the available tools

Users have expectations when browsing online, which are set by mostly habits formed from reading other websites. Consequently, while going with a disruptive look might be tempting in order to get more attention than the other displayed widgets, the end-result will most probably be that your widget will feel out-of-place, or even ugly in comparison to other, better-fitting widgets. Sticking to the rules might therefore be a sound idea.

One set of rules that are easy to follow, is UWA’s templates and controls, a set of CSS conventions and JavaScript object built from the ground up to help your content integrate seamlessly with the Netvibes look-and-feel. More generally, they offer a quick way to get a particular design idea in place, with way less work than if you had to build it all by yourself.

It’s also important to know that using controls, such as the TabView one, doesn’t implies that you are stuck with having to deal with them at all times. Remember that the widget’s content can be entirely built and re-built on demand through JavaScript, and thus you can set up various sections or customize colors, using JavaScript and the DOM. Conditional statements such as if..else or switch..case where created for a reason.

See how the ever-admirable Rugby World Cup 2007 widget makes use of tabs only when needed: on loading, it checks wether the hidden “mode” preference is set to “details”, and displays the content accordingly.

if (widget.getValue('mode') == 'details') {
  RWC.buildTabs();
} else {
  RWC.buildPodium();
}

This means basically that only the podium is displayed on first load (no tabs).

The user can then click a “switcher” link, built dynamically using JavaScript and DOM methods & events:

// Switcher
var toggle = widget.createElement('p');
var a = widget.createElement('a');
toggle.className = 'toggle calendar';
a.setText(toggleText);
a.href = '#';
a.onclick = function() { return false; }
var setDetailsMode = function(event) {
  widget.setValue('mode', 'details');
  RWC.buildTabs();
}
toggle.onclick = setDetailsMode.bindAsEventListener(this);
toggle.appendChild(a);

The buildTabs() method then erases the whole podium, and puts the tabs (and inline pager) in place – along with a bottom switcher link, so that the user can go from one mode to the other.

From there, thanks to the flexibility of JavaScript, anything is possible…

A subtle image can do a big impression

Placing your content harmoniously, using the existing templates: it’s all fine and dandy, but while these are necessary, it doesn’t make your widget stand out in the crowd. What will make it stand out is graphic design: adding color and/or images. But as explained before, this should be done in light touches, so as not to disrupt the general flow of the page.

Again, the RWC widget is a good example of this, with a non-disturbing crop of grass at the bottom, which helps the widget to go from “plain” to “playful”.

Another such example is the recent Euro2008 widget, which also servers as a great example of some of the ways you can make use of tabs and paging in a widget.

The user-contributed TripTouch widget also features a light strip of image at the top and 4 photos at the bottom, fine details which help to personalize the widget, and consequently let the user identifying it quicker in his page.

There are many other examples of great-looking widgets in Ecosystem. We’ll make regular posts on widget design and inspiration, so that as to give you fresh ideas and make your widgets look always better.

Share this post:

I’ll expand my answer into a longer “development cycle of a UWA widget” of sort…

Development

UWA widget should be built by following the documented guidelines - which are also available as a single page for those who only want a reference, not the full explanation. The UWA cheat-sheet is also a way of having it all at a quick glance.

Always keep in mind the most important parts, among which those three are make-or-break:

• UTF-8
• Well-formed XML
• Netvibes namespace

Test

There are a handful of successive ways to test your widget.

1. Offline, by loading the widget file directly in your browser. This is where the JavaScript and CSS emulation files will help you make sure your data is well-displayed.
   Also, if you are using Ajax requests, make sure to have a local proxy such as this basic one for local testing. Remember that an XML issue prevents list preferences to be properly displayed in standalone mode.
2. Online, by uploading your widget to a web server (along with it’s images and the proxy, if needed), loading its URL in your browser, and checking that everything is fine. This is still standalone mode, so list preferences will probably not work, but now that your widget is online, you can test it further thanks to the two buttons located below the widget: the first one adds it to Netvibes, the second one to iGoogle.
3. Within Netvibes. This is the first online test that should be done, since if it doesn’t work in Netvibes, there’s little chance it will elsewhere. Log-in to Netvibes, add the UWA Module from the Essential Widgets menu, and add your widget’s URL in its preference.
   If all goes well, it should display your widget properly. The good thing is that if your XML code is not well-formed, it will tell you where.
4. Once it works properly in Netvibes, test it elsewhere! Add it to iGoogle, add it to your Opera browser using the UWA Opera widget, add it to your Mac OS S Dashboard using the UWA Dashboard widget! Browse to your Netvibes account from your iPhone!
   It works everwhere? Great, go to the next step!
   If not, double-check your code, visit the forum, search the UWA FAQ, the how-tos and the known issues…
5. It’s time to add your widget to Ecosystem, since this is where you will be able to add and test it with further platforms, once your widget is validated: direct downloads for Windows Vista, Apple Dashboard and Opera; direct links for Netvibes, Windows Live.com and iGoogle…

If all goes well, consider your widget fully tested and ready to launch! Congratulations

Release

Now comes the initial question: how to release a widget? There are many ways to do so, based on the fact that you have two URLs for your widget: its Ecosystem URL (once it is validated), and its direct URL to your server.

In this respect, each situation is unique, and decision should be made according to your own inner methods. We of course advise to give a link the Ecosystem URL, since this is where users are able to add to all present and future supported platforms, with no action from your part – apart from keeping the widget’s file on your server.

You may also want to have a more customized page, on your own server. This is possible, as long as you use the links provided by Ecosystem for your widget: each platform compiler is on Ecosystem, and you won’t be able to propose Vista or Dashboard version without these. Apart from the link, you are free to redesign it as you see fit.

Thirdly, you may just want to offer direct access to the standalone widget on your server, and from there on let the use add to Netvibes or iGoogle if they want to. There again, just relying on the URLs provided by Ecosystem should keep you safe.

Note that once your widget is validated in Ecosystem, it’s also available with Netvibes internal search engine – given a few hours to update the cache. So that’s one less release issue to take care of.

Update

Code changes, and so will your widget. But that doesn’t mean you will have to resubmit your widget to Ecosystem – or even, to take any action beyond updating your file. Indeed, Ecosystem simply acts as a linker to your widget file on your server: nothing is stored on our side, and so does any instance of your widget on the user’s page. You are therefore responsible of keeping the file available.

There are two cases of updates:

1. Simply updating the file. New users will automatically get the new version from Ecosystem, and Netvibes users will automatically get the new version too, with their preferences intact. Easiest update path there is…
2. Updating the file and moving it to another directory/domain (or just renaming the file). Ecosystem and user’s pages will still point to the older URL, so you have to make it so this changes. 
   On Ecosystem’s side, just go to the widget’s administration page (in the My Widgets tab at the top), and update its URL accordingly.
   Handling existing users is trickier: you have to make them re-install the widget with the new URL. The best way would be to keep the older widget file at the original URL, and add a message to its content letting the user know that an update is available and that they should use it instead – pointing to the updated Ecosystem page. After some time, you may dispose of the older version/URL when you feel it’s safe.
   If you just change the URL without notification to existing users, understand that you may lose their trust…

So basically, we advise to keep the widget’s URL as stable as possible, and failing that, to act as a good service provider would do

Deletion

Sometimes you don’t feel like supporting them anymore, or they have been bested by some other widget, or your interests have moved on to other things. While we understand the many reasons involved in the idea of killing a widget, we must urge you to understand that it’s a loss for any user that came to rely on it daily. Before doing anything irreparable, please consider giving it’s support to another developer, and letting it be of use to its users, current and future.

If your decision is final, the steps are few. Connect to Ecosystem and simply click the red cross button to delete the associated widget. No new user will be able to use it. For current users, you may choose to keep the widget on your server, since it doesn’t do much harm there, and just put the widget offline in Ecosystem to prevent further users.
But if you intend to also delete the file, please consider backing it up first (because you never know), and please add a warning message for your users, advising them on finding an alternative, and maybe giving them an ETA.

Conclusion

This is just one way of seeing the life-cycle of a widget. Please consider them as best-practice, or even guidelines, but these are not the only way to act, just the one we envision ideally. You will probably build your own life-cycle as you develop more widgets. We just hope this post has been useful to devise your own path.

Don’t hesitate to let us know about your habits in the comments.

Share this post:

• UWA.Data.getXml
  when you want to get XML data (including well-formed XHTML), and be able to parse it using XML’s DOM properties and methods (parentNode, childNodes, attributes, getElementsByTagName, etc.),
• UWA.Data.getText
  when you just want to get the data in plain text, and maybe parse it using a regexp,
• UWA.Data.getJson
  when you want to safely get JSON data, and parse it using regular JavaScript methods and properties.
• UWA.Data.getFeed
  when you want to get a syndication feed (RSS, Atom, anything…).
• UWA.Data.request
  when you want to go one step further (POST request with parameters, authentication, cache handling…)

Among these, one method is very useful for a given purpose, but sometimes misunderstood: UWA.Data.getFeed. This particular method has been built to ease the use of the many variations of syndication feeds into one handy format: our very own JSON Feed Format – which is rendered in JSON, as you might have guessed.

By rendering just any feed format into one easily-parseable one, UWA.Data.getFeed relieves developer from the pain of have to deal with the various versions of RSS, for instance.

The part that is not always understood, however, is the resulting JSON format – the one received in the first argument of the callback method. This format is not a tag-by-tag conversion of the Atom format, for instance, into JSON – no direct xml2json converter here. 

And therefore, developers who are used to deal with feeds do not find their usual tagnames. UWA’s JSON Feed Format does not have an entry tag for each post, nor a summary tag for a given post’s content, as in Atom ; likewise, it doesn’t use the respective RSS2.0’s equivalent item and description. Instead of that, any feed is rendered with posts available in an items array, and their summary/description tucked in a content variable.

For clarity’s sake, let’s make a small comparison table between a selection of equivalent values in RSS 2.0, Atom 1.0 and the JSON Feed Format (from top to bottom):

• Getting to the first item:
  rss->channel->item[0]
feed->entry[0]
feed.items[0]
• Current item’s title:
  item->title
entry->title
item.title
• Current item’s content:
  item->description
entry->summary
item.content
• Current item’s permalink:
  item->link (or item->guid with isPermalink attribute set to true)
  entry->link
item.link
• Current item’s date:
  item->pubDate
entry->updated
item.date
• Current item’s enclosure:
  item->enclosure
item->link (with rel="enclosure")
  item.enclosures[0].url

Because of this disparity, some developers have chosen to use UWA.Data.getXml in order to parse the data using XML’s DOM, and therefore be able to use tag names they know. It works ; however, we feel they’d be much better of using a data format that is built to be used with JavaScript.

Fortunately, the way to handle feeds using the JSON Feed format is documented. Here is the gist of it:

First, we instantiate the JS containing object, with an empty feed variable (that shall later contain the whole JSON data), and we trigger the UWA.Data.getFeed method directly from the widget.onLoad method…

MyWidget = {};
MyWidget.feed = null;

widget.onLoad = function() {
  UWA.Data.getFeed(
    'http://feeds.feedburner.com/NetvibesDevNetBlog'),
    MyWidget.display);
}

…and then, the heart of it all, where we parse the JSON Feed Format:

MyWidget.display = function(feed) {
  if (feed) MyWidget.feed = feed;

  var feedList = widget.createElement('ul');
  feedList.className = 'nv-feedList';

  for(var i=0; i < MyWidget.feed.items.length; i++) {
    var item = MyWidget.feed.items[i];
    var li = widget.createElement('li');

    var a = widget.createElement('a');
    a.href = item.link;
    a.innerHTML = item.title;
    a.title = item.content.stripTags().truncate(255)

    li.appendChild(a);
    feedList.appendChild(li);
  }
  widget.setBody(feedList);
}

(notice that we use the FeedList template, simply by the nv-feedList class-name)

As you can see, it’s much easier to parse feed data using regular JavaScript code, than applying the tedious and longish XML DOM methods. Have a go at it, and find imaginative ways to use feeds!

Share this post:

The first one lets you keep track of the widgets and feeds you have added/removed recently ; the second one gives you the latest links you starred (using the starring functionality of the FeedReader, for instance) ; the third and last one merges all your contacts’ public activities, which means that you can get all the links they recently starred.

Above: Public activity

Above: Friends activity

This public/private starring functionality gives you a social-bookmarking tool to play with, for your private links or to share with your friends and contacts.

Now you might be telling yourself, “it’s all fine and dandy, but it would be even better to be able to star items from my own widget.” And right you are.

So, without any further ado, here’s the method to implement, in order to get a URL from your widget, into the user’s public timeline – and henceforth, into other users’ “friends activity” timeline:

widget.addStar(
  {
  'title':'The title for the starred link',
  'url':'http://www.example.org/',
  'comment':'pre-fill the comment here'
  });

Once this method is triggered, it pops up a window within Netvibes, which lets you specify where you want that link saved (private or public timeline), and add a comment (personal reminder or quick summary for your followers, depending of the context):

Once validated, a confirmation windows pops in and fades out, and your link is available in the chosen timeline:

The new addStar() method is only available starting with the Ginger release of Netvibes, and cannot work from another UWA-supported platform ; so when writing your code, you should pay attention to check if it is indeed available, and work around it if not. For instance, see how the starring-specific Star It! widget is doing it:

if (typeof widget.environment.netvibes == "undefined"
  || typeof widget.addStar == "undefined" ) {
  alert('This widget can only be used with Netvibes Ginger');
} else {
  widget.addStar({'title':Star.title, 'url':Star.url});
}

If you know how to make use of JavaScript events, this starring functionality can be made to look a lot nicer than a plain HTML form. See for instance the FFFFOUND widget, from which you can star a picture by clicking on the little yellow star that appears when the mouse rolls over a picture. Read its source code. The interesting part is this one:

if (!widget.readOnly) {
  if (typeof widget.environment.netvibes == "undefined"
    || typeof widget.addStar == "undefined" ) {
    //cannot star
  } else {
    var span = widget.createElement('span');
    span.className = 'star';
    span.innerHTML = _("Star");
    span.onclick = function(e) {
      var a = this.parentNode.firstChild;
      e.stopPropagation();
      widget.addStar({'title':a.innerHTML, 'url':a.href});
      return false;
    };
    li.appendChild(span);
  }
}

Try it out! It’s really not hard to implement it, and most widget could use it in inventive ways!

Share this post: