======Content of the XHTML file======

A UWA widget file is made of a handful of specific parts. Among those are metadata, and the ''widget:preferences'' tag.

=====Widget icons=====

There are two kinds of icons, each with a different use. They both are defined using a ''link'' tag in the widget's header.

If not defined, the widget will fall back to a default UWA icon.

====Favicon====

This icon serves as a quick differentiator within Netvibes: it is display on the top-left side of the widget, next to its title.

The target file should be a [[http://en.wikipedia.org/wiki/Favicon|classical favicon]] file: .ico, .png or .gif, 16*16, 256 colors. We recommend the PNG format.

<code>
<link rel="icon" type="image/x-icon"
  href="http://example.com/widget/favicon.png" />
</code>

====Rich icon====

This icons serves as a quick differentiator within the following platforms: Apple Dashboard, Windows Vista, Yahoo! Widget. Since it is much more noticeable on this platform, you should make sure to provide one - which can be a screen capture, a logo, anything that helps recognize your widget. 

Moreover, it you don't provide one, the default UWA icon could lose your widget among all the other installed widget that don't define one. See [[http://dev.netvibes.com/blog/2007/12/03/introducing-rich-icons-for-uwa-widgets/|this blog post]] for an example.

The target file should a 128*128 PNG file.

<code>
<link rel="rich-icon" type="image/png"
  href="http://example.com/widget/richicon.png"/>
</code>

=====Metadata=====

Metadata are informations stored in the ''head'' part of your XHTML file, whose purpose is to describe the widget and define how it works. Those metadata are stored in ''meta'' tags, and used as follows:   

<code html>
<meta name="author" content="Jane Doe" />
</code>

Currently supported metadata are:

^  Name         ^  Role                            ^  Content example  ^
|  author       |  Name of the widget author       |  Jane Doe  |
|  website      |  URL of the author's site/page   |  http://example.org  |
|  description  |  A description of the widget     |  Access your account directly from Netvibes  |
|  version      |  The widget's version number     |  0.1 alpha  |
|  keywords     |  Words to categorize the widget  |  local, food, map  |
|  screenshot |  Full-size screen-capture of your widget in action. Aim for 280px width  |  http://example.org/widget-full.png  |
|  thumbnail    |  Smaller version of the thumbnail, or the service's logo. Aim for 120px with by 60px height  | http://example.org/widget-logo.png  |
|  apiVersion   |  Version number of the API used  |  1.0  |
|  debugMode    |  If ''true'' (and if the browser supports it), traces log messages in the browser's console                            |  false  |
|  autoRefresh  |  Set the time between to refreshing of the widget (in minutes)   |  20  |

Deprecated metadata:
^  Name         ^  Role                            ^  Reason  ^
|  inline       |  Defines how to render the widgets: ''true'' for inline rendering, ''false'' for IFRAME rendering. Used for testing purpose.            |  Has been superseded by the "Render inline" tick-box in the [[:howto:test_widget#online_test|UWA Test Widget]]   |

=====Preferences=====

Netvibes Mini-Module API modules used "configuration forms" in order to get and set the widget's user settings. UWA (Netvibes API 1.0) replaces configuration forms with the inline ''widget:preferences'' tag, which contains ''preference'' tags, each defining a possible user setting. The result is the same for the user: the Edit section of the widget is automatically created from these preferences.

<note warning>
In order to work properly on all platforms:
  * You should not use HTML entities (''&acute;'', etc) in a preference label: since the file is UTF-8 encoded, you can directly use any special character you need.

  * You should escape XML special characters in preference values: ''&'', ''<'', ''>'', ''''' and ''"'' should be rewritten as ''&amp;'', ''&lt;'', ''&gt;'', ''&quot;'', ''&apos;''. This is specially true for preference values that features a URL with a ''&'' followed by parameters. 
</note>

<note tip>
In order to work properly in iGoogle:
  * a preference name MUST only contain letters, numbers or underscores - no space.
  * a preference label MUST be unique: no other preference can use that same label.
</note>

To properly set the ''widget:preferences'' tag, your XHTML file MUST feature the following profile declaration: 

<code html>
xmlns:widget="http://www.netvibes.com/ns/"
</code>

...like so...

<code html>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" 
  <BEGIN GeSHi>xmlns:widget="http://www.netvibes.com/ns/"<END  GeSHi> >
<head>
<title>Widget title</title>
... 
</code>

The ''widget:preferences'' tag is placed in the ''head'' part of the static XHTML file, like so:

<code html>
<widget:preferences>
  <preference name="url" type="text" label="URL" 
    defaultValue="http://feeds.feedburner.com/NetvibesDevBlog" />
  <preference name="limit" type="range" label="Number of items to display" 
    defaultValue="10" step="1" min="1" max="25" />
  <preference name="search" type="hidden" defaultValue="" />
</widget:preferences>
</code>

These preferences give the following Edit form:

{{uwa_specification:example-feed-edit.png|}}

If you your widget does not use preferences, simply put an empty tag:

<code html>
<widget:preferences />
</code>

====Preference tags====
''preference'' tags may use the following types (to be set in the "type" attribute of each tag):
^  Type     ^  Description  ^ Default value  ^
|  text     |  renders a classic HTML input field. This is the default type  |  undefined   |
|  boolean  |  renders a HTML checkbox (''true'' for checked, ''false'' for unchecked)  |  false  |
|  hidden   |  renders nothing, used to initalize a value  |  (empty)  |
|  range    |  quickly generates a list of integers inside an HTML listbox (''select''/''option'')  |  (empty range)  |
|  list     |  renders an HTML listbox (''select''/''option'')  |  (empty list)  |
|  password  |  a HTML password field. The password is then saved on our servers, and never sent back to the client. To be used with the [[:howto:authentication|authentication method]].  |  undefined  |

Please note that the ''list'' preference type doesn't display properly in stand-alone mode at the moment - you need to preview it in Netvibes in order to test it properly. We are working to fix it.

The following types are in the works:
^  Type      ^  Description               ^
|  textarea  |  renders a HTML text area  |

====Preference attributes====
''preference'' tags may contain other attributes. Here are the supported ones:
^  Attribute      ^  Description  ^
|  label          |  indicates the HTML label describing the preference. Since it is actually displayed, the value should be short and descriptive  |
|  defaultValue   |  lets the user set a default value for the preference  |
|  onchange       |  targets a JavaScript callback ''widget'' method, fired when the setting is changed. Declaring ''onchange=refresh'' targets ''widget.refresh()''  |
|  min            |  defines the minimal integer possible (''range'' type only)  |
|  max            |  defines the maximal integer possible (''range'' type only)  |
|  step           |  defines the incremental step between two values (''range'' type only)  |

====Using the list preference tag====

Using a preference of type ''list'' requires more than three specific attributes, as it does for the ''range'' type. The ''list'' type requires options, which are to be set like common ''select''/''option'' tags:

<code html>
<widget:preferences>
<BEGIN GeSHi>    <preference name="category" type="list" label="Category" 
  defaultValue="1st" onchange="refresh">
      <option value="all" label="all" />
      <option value="1st" label="First category" />
      <option value="2nd" label="Second category" />
      <option value="3rd" label="Third category" />
    </preference><END  GeSHi>
</widget:preferences>
</code>

=====Preferences and JavaScript====

JavaScript can be used to get or set values in the preference tags. For this, you have the ''widget.getValue(name)'' and ''widget.setValue(name, value)'' methods, which respectively let you get and set preference values.

''widget.getValue'' works for all preference tags. In the case of the ''range'' or ''list'' preferences, it just gets the current selection's value.

''widget.setValue'' is different. It works seamlessly with the ''text'' and ''boolean'' preferences, but not with the ''range'' and ''list'' ones. It is not possible as of yet to modify those types using JavaScript, it has to be set directly in the preferences.

=====Emulation files=====

In order to test your UWA locally, you must add these two lines to your HTML header. They will emulate the UWA environment while not in Netvibes. You can let them in when submitting to Netvibes. Read "[[howto:test_widget]]".

<code html>
<link rel="stylesheet" type="text/css" 
  href="http://www.netvibes.com/themes/uwa/style.css" />
<script type="text/javascript" 
  src="http://www.netvibes.com/js/UWA/load.js.php?env=Standalone"></script>
</code>

=====General scripting and styling=====

UWA widgets dynamic data are entirely dealt with by JavaScript. Styling is done using CSS. Both of these use the usual ''script'' and ''style'' tags.

Please note that we do not support external CSS files. Same for external JavaScript files. All your code should be in the main static XHTML file.

<code html>
<script type="text/javascript">
  // your JavaScript code
</script>

<style type="text/css">
 /* your CSS rules */
</style>
</code>

You are advised to use the UWA ''widget'' object for DOM scripting (read "[[:uwa_specification:using_javascript_and_ajax]]"), and the UWA Templates for proper styling (read "[[:uwa_templates]]").

=====Body section=====
As for the content of the ''body'' part of the XHTML file, there is no best practice as of yet. You could just put the following:
<code html>
<p>Loading...</p>
</code>
...and update the whole XHTML content using JavaScript and DOM methods. But another way could be to build a static XHTML skeleton ([[:uwa_specification:uwa_skeleton|see a sample skeleton]]) in the ''body'' part, and fill the content in [[using_javascript_and_ajax|using JavaScript]], like so:

<code html>
<h3>Title goes here</h3>
<p>The content goes here</p>
</code>

Continue to [[:uwa_specification:using_javascript_and_ajax|Using JavaScript and Ajax in a UWA widget]]...