====== Anatomy of a UWA widget ======
A UWA widget file uses standard XHTML code, except for the preferences section, which uses a specific set of elements. Apart from preferences, the XHTML code is entirely based on Web-standards: XHTML/XML, JavaScript/Ajax, CSS.
===== The fundamentals =====
==== Must-haves ====
* **XML**: the widget must be made of well-formed XML/XHTML code ;
* **UTF-8**: the widget's file must be encoded in UTF-8 ;
* **Namespace**: the XHTML code must feature the Netvibes widget namespace on the ''html'' element, this way: ''xmlns:widget="http://www.netvibes.com/ns/"''.
==== Highly recommended ====
* **One static file**: for better portability, the widget should be made of a single XHTML file, with no server-side code (.htm, .html, .xhtml...). Any dynamic data should be fetched using Ajax methods, and displayed using JavaScript/DOM methods ;
* **Emulation files**: for standalone testing, the widget should make use of the UWA emulation files (described below) ;
* **No external CSS/JS files**: JavaScript and CSS code should be put directly with the widget's XHTML file, using the ''script'' and ''style'' tags. The only allowed external files are the emulation ones.
* **Ecosystem**: in order to be found by Netvibes users, widget should be submitted to Netvibes Ecosystem. Ecosystem is also where the widget can be compiled for others platforms.
* The XML well-formedness is very important, as widgets are rendered through the browser's XML parser. Without it, rendering the widget would be problematic.
* The emulation files enable a standalone display of the widget for easier testing. They must be included if you intend to test and debug the widget locally, before submitting it to Netvibes Ecosystem.
* Server-side scripting is not recommended for portability reasons: when compiled, the main file is encapsulated into a container, which might not play well with PHP files. Your data should be accessed through Ajax requests to a separate server-side file (PHP, ASP, etc.), which sends back text-based data (feed, JSON, XML, pure text).
===== The various sections of the XHTML file =====
==== File header ====
Apart from the Netvibes widget namespace, the header features the usual code from any well-formed XHTML 1.0 Strict files.
Title of the widgetThe ''title'' tag is used to set the actual title of the widget. Its content should therefore be meaningful.
==== File meta tags ====
UWA defines a set of new meta labels, used to either describe the widget or to give indication to the platform. They are mostly optional, but very useful.
They are coded just like regular meta tags:
Some platforms require meta tags to be filled, i.e. iGoogle. They are marked accodingly.
=== Widget meta labels ===
^ Name ^ Role ^ Content example ^
| author | Name of the widget author. Required by iGoogle | Jane Doe |
| email | E-mail adress of the widget author. Required by iGoogle | jane@example.org |
| website | URL of the author's site/page | http://example.org |
| description | A description of the widget. Required by iGoogle | 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. Required by iGoogle | 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 |
| autoRefresh | Set the time between two refreshing of the widget (in minutes) | 20 |
=== Platform meta labels ===
^ Name ^ Role ^ Content example ^
| apiVersion | Version number of the UWA API | 1.2 |
| debugMode | If ''true'' (and if the platform supports it), traces log messages in the platform's JavaScript console (i.e. Firebug) | false |
==== Icons and thumbnails ====
There are already meta labels for screenshot and thumbnail, but these are only part of the equation.
=== Favicon ===
UWA supports favicon, just like any other XHTML file:
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 (we recommend PNG) ;
* 16*16 pixels ;
* 256 colors.
=== Rich-icon ===
Some platforms ask for bigger icons. UWA sets this in the same way as the favicon:
This icons serves as a quick differentiator within the following platforms: Apple Dashboard, Windows Vista, Yahoo! Widget. Since it is much more noticeable on these platforms, you should make sure to provide one - which can be a screen capture, a logo, anything that helps differentiate your widget.
Moreover, it you don't provide one, the default UWA icon could lose your widget among all the other UWA widgets that don't define one either. See [[http://dev.netvibes.com/blog/2007/12/03/introducing-rich-icons-for-uwa-widgets/|this blog post]] for an example.
==== Emulation files ====
In order to test your UWA locally, you should add these two lines to your HTML header. They will emulate the UWA environment while not in Netvibes - what we call "Standalone mode".
Once you are done testing, you can leave them in the code: they are ignored by Netvibes or any supported platform.
The emulated environment **should not** be taken as an exact replica of how UWA widgets behave. The standalone mode offers less constraints than. Therefore, while it is very handy for local testing, only a finale test on Netvibes or a supported platforms can prove the widget to work as expected.
==== Styling ====
UWA is based on Web-standards, so widgets can make use of any HTML element and attribute (like ''table'' or ''style'', as well as CSS.
But for real styling, widget can rely on CSS. CSS rules are to be defined in the widget file's ''style'' tag. Here is an example:
UWA lets developers use CSS templates for easier styling of some well-known data formatting: data grid, e-mail list, rich list...It is not recommended to rely on an external CSS file: all CSS rules should be placed in the file's ''style'' tag.
It is recommended to only target the widget's element, not general page elements:
- no direct use of selectors such as ''h2'', ''span'', ''div''...
- better include a widget-specific class to ''body'' tag, and target that (as shown in the above sample code. You can use the addClassName() method to dynamically add that class: ''widget.body.addClassName('flickr');''
==== Scripting ====
UWA supports scripting using regular JavaScript code. Widget developers can rely on UWA's JavaScript framework for extended functionalities.
Scripts are to be put within a single ''script'' tag, inside the file's ''head'' section.
UWA lets developers use JavaScript controls for quicker creation of dynamic HTML components: paging, tabs...It is not recommended to rely on an external JavaScript file: all JS code should be placed in the file's ''script'' tag.
It is not recommended to use the ''document'' and ''window'' objects, as well as their methods, properties and events, for portability reasons. Most of these have been duplicated and expanded in the new ''widget'' object.
==== Preferences ====
UWA widgets can have user-defined preferences of several types. These preferences are stored on the local platform, and retrieved every time the widget is loaded.
If no preference is set, the widget won't display an Edit menu.
Preferences are based on the UWA-specific ''widget:preference'' element, and each preference uses a ''preferences'' tag.
There must be only one ''widget:preferences'' element per widget in the ''head'' portion of the file. There can be as many ''preference'' tags as needed, provided they are all within ''widget:preferences''.
=== Sample preferences block ===
This preferences block gives the following Edit form:
{{uwa_specification:example-feed-edit.png|}}
=== Preference tags ===
''preference'' tags can use the following types (to be set in the "type" attribute of each tag):
^ Type ^ Description ^ Default value ^
| text | Renders an HTML input field. This is the default type | undefined |
| boolean | Renders an HTML checkbox (''true'' for checked, ''false'' for unchecked) | false |
| hidden | Renders nothing, used to initalize a value | (empty) |
| range | Generates a list of integers inside an HTML listbox (''select''/''option''). Inspired by HTML5's range list | (empty range) |
| list | Renders an HTML listbox (''select''/''option'') | (empty list) |
| password | An HTML password field. The password is then saved on our servers, and never sent back to the client | undefined |
The ''list'' preference type doesn't display properly in standalone mode - you need to test the widget in Netvibes in order to see it properly displayed.The ''hidden'' preference is a handy way to locally store data without letting the user modify it.
=== Preference attributes ===
''preference'' tags may contain these attributes:
^ Attribute ^ Description ^
| label | Indicates the HTML label describing the preference. Since it is displayed to the user, the value should be short and descriptive |
| defaultValue | Lets the user set a default value for the preference |
| 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 in HTML:
=== Notes ===
Preferences can be retrieved using JavaScript. The UWA JavaScript framework provides a handful of methods for that:
* retrieving a preference value: ''widget.getValue(name)'', ''widget.getInt(name)'', ''widget.getBool(name)'' ;
* saving a value in a preference: ''widget.setValue(name, value)'' (doesn't work with the ''range'' and ''list'' types).
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.
In order to work properly on all platforms:
* You should not use HTML entities (''´'', etc) in a preference label: since the file is UTF-8 encoded, you can directly use any special character you need.
* You should URL-encode/escape XML special characters in preference values: ''&'', ''<'', ''>'', '' ' '' and ''"'' should be respectively rewritten as ''&'', ''<'', ''>'', ''"'', '''''. This is specially true for preference values that features a URL with a ''&'' followed by parameters: use ''&'' instead. If the URL already features a ''&'', then encode it to ''&''.
==== Body section ====
There is no best way to handle the ''body'' section of the XHTML file: developers are free to have their widget start with an empty body, or a fully created one.
Most of the time, developers can rely on this kind of body content:
(...)
Loading...
...and update the whole XHTML content using JavaScript and DOM methods from the UWA framework, such as ''widget.addBody()'' or ''widget.body.setHTML''.
But another way could be to build a static XHTML skeleton in the ''body'' section, and fill the content in using JS/DOM methods.
(...)