======How to use a widget on my site/blog?======

<note warning>The BlogWidget is now deprecated, and has been superceded by [[http://eco.netvibes.com/|Ecosystem]]'s own Export tool, avalailable on the page of each UWA widget.

For those in need of more control, the [[:uwa:howto:uwa_iframe|UWA-iframe]] method is the way to go, or even the open-source [[http://netvibes.org/|Exposition server]].

This page therefore describes a method that should not be used anymore. It is however kept for historical purpose.</note>

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://wordpress.org/extend/plugins/text-control/|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".