======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.

=====BlogWidget environment import=====
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.

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

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

=====Full BlogWidget display code example=====
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.

<code html>
<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>
</code>

=====Deconstructing the BlogWidget display code=====
Here is what this code does...

====Creating a unique Widget ID====
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.

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

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

^  parameter  ^  Description  ^  Example  ^
|  container  |    the reference to the div where the widget will be displayed  |  container: document.getElementById('AUniqueID')  |
|  moduleUrl  |  the absolute URL to the UWA widget  |  moduleUrl: 'http://www.netvibes.com/api/uwa/examples/digg.xhtml'  |
|  id         |  (optionnal) the widget id  |  id: 'AUniqueID' (defaults to a randomly generated one)  |
|  inline     |  (optionnal) indicates if the widget uses the inline mode  |  inline: true (defaults to false)  |

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


====Setting the display configuration====
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:

^  Setting  ^  Description  ^  Example  ^  Default value  ^
|  title                   |  the title of the widget (string)  |  'title':'Digg'  | 'Default title'  |
|  height              |  the height of the div, in pixels (string)  |  'height':'250'  |  '250'  |
|  borderWidth    |  the width of the div's border, in pixels (string)  |  'borderWidth':'1'  |  '1'  |
|  color                 |  the color of the widget's border (string)  |  'color':'#aaaaaa'  |  '#aaaaaa'  |
|  displayTitle      |  wether or not to display the title (boolean)  |  'displayTitle':true  |  true  |
|  displayFooter  |  wether or not to display the footer, which includes the "powered by netvibes uwa" logo (boolean)  |  'displayFooter':true  |  true  |

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

====Setting the preferences values====
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:

<code javascript>
BW.setPreferencesValues( { 'property': 'value', 'property2': 'value2' } );
</code>

=====Placing the code=====

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

<code html>
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!
</code>

====...on a static page====

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

====....in a text form====

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===
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 [[http://dev.wp-plugins.org/wiki/TextControl|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".

=====About the inline mode=====

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.

<note>
Please note that the inline mode will add around 150 Kb to your page/site download size. Carefully consider the addition of widgets if your hosting account is limited.
</note>

<note>
[[:howto:authentication|UWA authentication]] will only work with inline widgets.
</note>

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

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

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

<note warning>
CAUTION: when you use the inline mode, only add to your page widgets from trusted sources. Be aware that there could be malicious widgets that could hijack your site's visitors. Make sure you are adding an official widget, or one from a known and trusted developer.
</note>

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

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

<script type="text/javascript">
var BW = new UWA.BlogWidget( 
  { <BEGIN GeSHi>inline: true, <END  GeSHi> 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>
</code>