netvibes uwa workshop at parisweb 2007
DESCRIPTION
TRANSCRIPT
Universal Widget API :How to build
multiplaform widgetsXavier Borderie / netvibes
http://dev.netvibes.comParisWeb 2007 workshop
Saturday, November 17th, 2007
What are widgets
• Small, specialized applications (mostly)
• Available through the browser: Netvibes, iGoogle, Live.com, YourMinis...
• Available through an installed engine: Vista Gadgets, Apple Dashboard, Yahoo! Widgets, Opera...
Netvibes’ thinking when creating UWA
• MiniAPI is doing quite well
• 1000 modules since May 2006
• Positive feedbacks from the community
• No de-facto standard
• Each site/engine uses its own format
• W3C’s specification is still in its infancy (working draft)
What UWA promises
• Works on the most popular platforms, without any change to the original file
• Today: Netvibes, iGoogle, Live.com, Opera, Apple Dashboard, Windows Vista, Yahoo! Widgets
• Works just like MiniAPI, in a stricter way
• Easy to learn thanks to proven standards: XHTML/XML, JavaScript/Ajax, CSS
UWA basics
• One static XHTML file, using well-formed XML
• UTF-8 encoding
• Netvibes namespace a must: xmlns:widget=“http://www.netvibes.com/ns/”
Presenting the basic skeleton
• http://dev.netvibes.com/files/uwa-skeleton.html
• Starting point for most of the developers, through copy/pasting
• Skeleton generator is in the testing phase...
Skeleton 1 : XHTML headers
• Nothing new here...
• ...just don’t forget the Netvibes namespace
<?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" xmlns:widget="http://www.netvibes.com/ns/" > <head>
<title>Title of the Widget</title> <link rel="icon" type="image/png" href="http://www.netvibes.com/favicon.ico" />
Skeleton II : meta tags
• Various usages
• Most are optional
<meta name="author" content="John Doe" /><meta name="website" content="http://exemple.org" /><meta name="description" content="A descriptive description" /><meta name="keywords" content="these, are, key words" /><meta name="screenshot" content="http://exemple.org/widget-full.png" /><meta name="thumbnail" content="http://exemple.org/widget-logo.png" /> <meta name="apiVersion" content="1.0" /><meta name="autoRefresh" content="20" /><meta name="debugMode" content="true" />
Skeleton III : emulation files
• Optional but very useful when testing in Standalone mode
<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>
Skeleton IV :UWA preferences
• UWA-specific tag set
• Bad: doesn’t work well with the W3C XHTML validator
• Good: makes for more portable preferences<widget:preferences> <preference name="url" type="text" label="URL" defaultValue="http://feeds.feedburner.com/NetvibesDevBlog" /> <preference name="pass" type="password" label="Password" /> <preference name="displayImages" type="boolean" label="Display images?" defaultValue="true" /> <preference name="limit" type="range" label="Number of items to display" defaultValue="10" step="1" min="1" max="25" /> <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> <preference name="search" type="hidden" defaultValue="" /></widget:preferences>
<widget:preferences> <preference name="url" type="text" label="URL" defaultValue="http://feeds.feedburner.com/NetvibesDevBlog" />
<preference name="password" type="password" label="Password" />
<preference name="displayImages" type="boolean" label="Display images?" defaultValue="true" />
<preference name="limit" type="range" label="Number of items to display" defaultValue="10" step="1" min="1" max="25" />
<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>
<preference name="search" type="hidden" defaultValue="" /></widget:preferences>
Skeleton V :CSS and JavaScript code• Simple: just use the dedicated tags <style type="text/css"> /* your CSS rules */ </style> <script type="text/javascript"> var YourWidgetName = {}; YourWidgetName.data = null; YourWidgetName.display = function(responseJson) { // display code } widget.onLoad = function() { UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display); }
widget.onRefresh = widget.onLoad; widget.refresh = widget.onLoad; </script>
<style type="text/css"> /* your CSS rules */</style> <script type="text/javascript"> var YourWidgetName = {}; YourWidgetName.data = null; YourWidgetName.display = function(responseJson) { // display code } widget.onLoad = function() { UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display); }
widget.onRefresh = widget.onLoad; widget.refresh = widget.onLoad;</script>
Skeleton VI :End of file
• The body can be pre-filled or completely empty: its content is free since the DOM can update it at any time
• Data are loaded using JavaScript and placed in the body using the DOM
</head> <body> <p>Loading...</p> </body></html>
What about diving into some code?
Using CSSand JavaScript
• Works just like in a classic HTML file: <script> and <style>
• Refrain from using external files: put everything in the widget
• CSS: try prefixing every rule with class named after the widget, .myWidget p { ... }
• CSS: target with classes rather than ids
• JS: put every method/variable in an object named after the widget, var MyWidget = {};
Practical examples:ʇxǝʇdılɟFireplace
Fliptext
• http://nvmodules.typhon.net/maurice/fliptext/
• Entirely made with just HTML, CSS et JS - no external calls
• Adapted in UWA from the original code, to be found at: http://www.fliptext.org/
widget.onLoad = function() { for (i in Flip.table) { Flip.table[Flip.table[i]] = i } out = '<textarea></textarea><p><button>flip <img src="http://nvmodules.typhon.net/maurice/fliptext/refresh.png" alt="Flip" /> dılɟ</button></p><textarea></textarea>'; widget.setBody(out);
var bt = widget.body.getElementsByTagName('button')[0]; var textareas = widget.body.getElementsByTagName('textarea'); bt.onclick = function(){ var result = Flip.flipString(textareas[0].value.toLowerCase()); textareas[1].value = result; }}
Fireplace• http://nvmodules.typhon.net/maurice/
fireplace/index.html
• Demonstrating the possibility to use Flash
• The widget generates the HTML using JavaScript, but you can directly place the <object> tag within the widget’s body, and never use JavaScript
• You can also directly submit your SWF to Ecosystem, which will wrap it in a UWA container for you
widget.onLoad = function() { var contentHtml = '';
contentHtml += '<div style="margin: 0 auto;text-align:center;">';
contentHtml += '<object type="application/x-shockwave-flash" data="http://nvmodules.typhon.net/maurice/fireplace/fire.swf" width="320" height="240" class="flash">';
contentHtml += '<param name="movie" value="http://nvmodules.typhon.net/maurice/fireplace/fire.swf" />'; //contentHtml += '<param name="wmode" value="opaque" />';
contentHtml += '<embed src="http://nvmodules.typhon.net/maurice/fireplace/fire.swf" type="application/x-shockwave-flash" width="320" height="240"></embed>'; contentHtml += '</object>';
contentHtml += '</div>'; widget.setBody(contentHtml); widget.onResize();}
Let’s practice
Build a Zorglangue widget from the Fliptext widget
• http://ndiremdjian.free.fr/pics/zorglangue.htm
• Same CSS and widget.onLoad() as in Fliptext
• Just place the linked page’s JavaScript in a Zorglub object.
The final Zorglangue
• http://nvmodules.typhon.net/maurice/zorglub/
• Compare the code with Fliptext: http://nvmodules.typhon.net/maurice/fireplace/index.html
UWA’s JavaScript method and properties
• Refrain from using document or window
• Replace document.getElementById(‘id’) with widget.body.getElementsByClassName(‘class’)[0]
• HTML elements are only extended when created using widget.createElement(). You can extend them by hand:var foo = UWA.$element(widget.body.getElementsByClassName(‘bar’)[0];foo.setStyle(‘backgroundColor’, ‘red’);
UWA’s JavaScript method and properties• Most of the methods and properies have
been moved document and window, into two UWA-specific objects: widget et UWA.
• widget : usual methods found in JavaScript frameworks
• UWA : mostly only used for UWA.Data, which contains the Ajax methods
• See the UWA cheat-sheet :)
Ajax methods
• 4 quick methods:
• UWA.Data.getText(url, callback);
• UWA.Data.getXml(url, callback);
• UWA.Data.getJson(url, callback);
• UWA.Data.getFeed(url, callback);
• All are built upon the master one:
• UWA.data.request(url, request);
UWA.Data.request
• Allows you to make more complex queries: POST + parameters, authentication, cache handling...
• UWA.Data.request(url, request) :
• request = { method:’post’, proxy:’ajax’, cache:3600, parameters:’lastname=Bond&id=007’, onComplete:MyWidget.display };
Practical examples:Getting images out of a feed: FFFFOUND
Handling a feed: SkybloggetText and parsing: DeMetsgetText and parsing: LinkedIn
Getting images out of a feed: FFFFOUND
• http://nvmodules.typhon.net/maurice/uwa-ffffound/
• JS: getting the feed with getFeed(), extracting the image links (<link> from the JSON feed format), HTML code built on the fly
• CSS: placing the elements
• JSON Feed Format: http://dev.netvibes.com/doc/uwa_specification/uwa_json_feed_format
Handling RSS/Atom: Skyblog
• http://nvmodules.typhon.net/maurice/skyblog/
• Preferences: blog’s name and number of articles to display
• JS: parsing the JSON feed, building the HTML code using the DOM rather than in a string
• Nota: use of the limit preference
• Nota: UWA.Utils.setTooltip()
getText and parsing : DeMets
• http://nvmodules.typhon.net/maurice/uwa-demets/
• getText on a custom PHP script (UTF-8 conversion)
• A few RegExps to remove most of the useless content
• finally getting and displaying the restaurant’s menu
getText and parsing : LinkedIn
• http://florent.solt.googlepages.com/linkedin-pretty.html
• getText directly on the URL to be parsed
• Display the chosen section (via preference), with a bit of RegExps to simplify/manipulate the content
Models and controlers
• To better fit in the platform’s theme/style
• To ease the conception of some common applications/needs
Models
• CSS classes
• Data grid
• E-mail list
• Feed list
• Rich list
• Thumbnailed list
Controlers
• CSS classes + JavaScript behaviors
• TabView
• Pager
Practical examples:getFeed and FeedList: RSSReaderJSON request and Pager: TwittergetJson and TabView: TwitterKing
getText parsing and TabView+Pager+...: Rugby World Cup
RSS Reader
• http://www.netvibes.com/api/uwa/examples/rssreader.html
• getFeed translate any kind of feed into an internal and normalized JSON format
• http://dev.netvibes.com/doc/uwa_specification/uwa_json_feed_format
• From there on, retrieving the data in JavaScript is just a matter of knowing what’s where in the JSON feed
• http://dev.netvibes.com/files/examples/twitter-05-auth-getpost.html
• UWA.Data.request on an authenticated JSON
• HTML building with the DOM and UWA méthods (setHTML, etc.)
TwitterKing
• http://www.my-widget.com/twitter_widget.html
• Just like the previous Twitter widget, but overcharged with any possible API call and UWA controler :)
Rugby World Cup
• http://nvmodules.typhon.net/romain/rugbyworldcup/
• getText directly on a third-party URL
• Code parsing, RegExp, recomposition of the original links, Pager, TabView... the whole shebang
Thank you!
• http://dev.netvibes.com
• http://dev.netvibes.com/doc/
• http://dev.netvibes.com/forum/
• http://dev.netvibes.com/blog/
• http://eco.netvibes.com
• We are always hiring! :)http://dev.netvibes.com/doc/jobs