======How to open a new browser window?======

Your widget might need to open a new browser window (or a popup window) for specific purposes. This would usually be done using the ''window.open'' method, but since UWA disables access to the ''window'' object, its ''open'' method is unavailable.

UWA therefore integrates a special method, called ''widget.openURL''. It only takes one parameter, the needed URL. 

<code javascript>
widget.openURL('http://www.netvibes.com');
</code>

Note that this implementation is close to the [[http://www.w3.org/TR/widgets/#the-widget0|W3C Widget specification]]'s definition of the ''openURL'' method:
you can't define the window name, nor can you specify its height, width, scrollbar...

===== Links in Apple Dashboard =====

The Dashboard uses a custom way of handling links, which means that standard ''<a href="..."'' links will not work on their own: clicking them won't trigger a usual link request.

Using ''onclick="openURL('http://...')"'' on links is the recommended way if you intend to make your widget fully work in Apple Dashboard. You can wrap it in a function :

<code javascript>
function link(url)  {
  if (widget && widget.openURL) {
    widget.openURL(url);
    }
   }
</code>

...then using either the standard tag, or the ''span'' tag that Apple recommends.

<code html>
<!-- This will not trigger in Dashboard -->
<a href="http://example.com">Example</a>

<!-- This should trigger on all platforms -->
<a href="http://example.com" onclick="link('http://example.com');">Example</span>

<!-- This is the recommended syntax for the Dashboard platform -->
<span onclick="link('http://example.com');">Example</span>

<!-- No need for a wrapper function... -->
<span onclick="widget.openURL('http://example.com');">Example</span>
</code>

See also the [[http://developer.apple.com/documentation/AppleApplications/Conceptual/Dashboard_ProgTopics/Articles/ExternalAccess.html#//apple_ref/doc/uid/TP40003049-DontLinkElementID_21|Dashboard documentation about widget.openURL]].