How to use a widget on my site/blog?

BlogWidget is the name of the method to use when using a UWA widget outside conventional environments (Netvibes, iGoogle, Apple Dashboard…). In short, the UWA BlogWidget environment provides you with a JavaScript code that lets you use a UWA widget on any page, wether it's a blog post or sidebar, or a regular static website.

This widget export requires a few changes to you blog/website code. First, it needs to feature the BlogWidget environment calling code in the file's header.

<script type="text/javascript" 
  src="http://www.netvibes.com/js/UWA/load.js.php?env=BlogWidget">
</script>

This code places the widget in a IFRAME on your blog.

You can then use the BlogWidget code to display the wanted widget anywhere on the page, inline with the rest of the HTML code. That code could take the following form, for the Digg sample widget.

<div id="UWADiggWidget">Loading the UWA Digg widget</div>
 
<script type="text/javascript">
var BW = new UWA.BlogWidget( 
  { container: document.getElementById('UWADiggWidget'),
    moduleUrl: 'http://www.netvibes.com/api/uwa/examples/digg.xhtml' } );
BW.setConfiguration(
  { 'title':'Digg', 'height':'250', 'borderWidth':'1', 
    'color':'#aaaaaa', 'displayTitle':true, 'displayFooter':true } );
BW.setPreferencesValues(
  { 'category':'gadgets', 'minimal':'100', 'limit':'5' } );
</script>

Here is what this code does…

First, we must create an empty div tag, which will act as a container for our widget. This tag must be made unique using the id attribute.

<div id="UWADiggWidget">Loading the UWA Digg widget</div>

Second, it instantiates the UWA.BlogWidget object, with its parameters. The available parameters are as follows:

var BW = new UWA.BlogWidget(
  { container: document.getElementById('UWADiggWidget'),
    moduleUrl: 'http://www.netvibes.com/api/uwa/examples/digg.xhtml' } );

Third, filling the different BlogWidget display configuration settings, using the setConfiguration method. These settings do not act on the widget itself, but on the block surrounding it. The setConfiguration method takes a JSON string as an argument, which features the following settings:

BW.setConfiguration(
  { 'title':'Digg', 'height':'250', 'borderWidth':'1', 'color':'#aaaaaa', 
    'displayTitle':true, 'displayFooter':true });

Fourth, setting the widget's preferences, using the setPreferencesValues method. Once a widget is put on an independant page using the BlogWidget environment, its preference form is no longer available at a click on the Edit link: you have to set these preferences within the JavaScript code itself, and the user won't be able to change them.

Every single preference must be set (unless they have a usable default setting), and you therefore must know them beforehand. The setPreferencesValues method takes a JSON string as its only argument, like so:

BW.setPreferencesValues( { 'property': 'value', 'property2': 'value2' } );

Here is an example of how you could place the widget within your own HTML code.

Check out this cool widget I found!
 
<script type="text/javascript" 
  src="http://www.netvibes.com/js/UWA/load.js.php?env=BlogWidget"></script>
 
<div id="UWADiggWidget">Loading the UWADigg Widget</div>
 
<script type="text/javascript">
var BW = new UWA.BlogWidget( { 
  container: document.getElementById('UWADiggWidget'),  
  moduleUrl: 'http://www.netvibes.com/api/uwa/examples/digg.xhtml' } );
BW.setPreferencesValues({'category':'gadgets', 'minimal':'100', 'limit':'5' });
</script>
 
That's pretty darn useful, I'd say!

The BlogWidget method should work as-is on all static systems: HTML pages, blog sidebars, etc.

If you intend to include the widget on your site by placing the code in a text-form (for instance, directly in a blog post, or on a wiki page, or any other CMS-edited page), you should make sure that some CMS/blog system tend to apply special formatting and character encoding techniques to your text, and therefore to the BlogWidget code. Since our code should be used as is, making it go through such formatting could prevent them from running.

Therefore, you must make sure your CMS/blog system does not change the code. Some CMS won't let you prevent formatting, some others won't apply any formatting at all, and last but not least some others have to be tweaked in order to prevent formatting.

WordPress is among the blog system which have to be tweaked in order for our BlogWidget code to work properly. This system features the TinyMCE editor, which is in charge of formatting. You can disable it in the Users / Your Profile page, but this prove to not be enough in our case.

In order for the BlogWidget code to work, you will have to install the free TextControl plugin. Activate it, then start editing the post that will contain the BlogWidget. Click “Save and Continue” to update the post preview and make the Text Control options appear.

You can experiment between the various modes, but it seems the combination that works best is “No Formatting” with “Default (wptexturize)”, or “nl2br” with “No Character Encoding”.

By default, the BlogWidget code generates an IFRAME that links to the widgets URL, with the proper preferences set. But an inline method is also available. While in the IFRAME mode the widget keeps its own design, in the inline mode the widget's style (fonts, colors…) uses your site's style.

If you want to use a widget inline, you need to call a different environment file:

<script type="text/javascript" 
  src="http://www.netvibes.com/js/UWA/load.js.php?env=BlogWidget-Inline">
</script>

Note that using the inline mode implies a slight change in the display code: adding inline: true to the UWA.BlogWidget object instanciation.

If you use the inline mode, the usual display code needs to be changed to this:

<div id="UWADiggWidget">Loading the UWA Digg widget</div>
 
<script type="text/javascript">
var BW = new UWA.BlogWidget( 
  { inline: true,  container: document.getElementById('UWADiggWidget'),
    moduleUrl: 'http://www.netvibes.com/api/uwa/examples/digg.xhtml' } );
BW.setConfiguration(
  { 'title':'Digg', 'height':'250', 'borderWidth':'1', 
    'color':'#aaaaaa', 'displayTitle':true, 'displayFooter':true } );
BW.setPreferencesValues(
  { 'category':'gadgets', 'minimal':'100', 'limit':'5' } );
</script>