Widget Protocol

The widget:// protocol (or window:// - they do the same thing) is used from an anchor (a href='..') element to cycle a widget. That means it opens the widget but if you click the link a second time, it will close it. It specifies what should be inside the widget and the widget template to use:

<a href='widget://<template name>/<path to content>'>Cycle a widget</a>

Floating - the Built in template for a window

A template called "floating" is included by default. It is essentially a classic draggable, resizable window with a title bar (which will be set from the document.title of your content).

The content path

Your content path is a complete URI which is relative to your documents basepath (which is resources:// by default). So, for example, let's say you'd like to open up a bank inside a default floating window. Your bank UI is described in Resources/UIs/Bank/index.html and your document.location is 'resources://' (the default). That makes your window URL look like this:

<a href='widget://floating/UIs/Bank/index.html'>Open or close the bank!</a>

<!-- This does exactly the same thing -->
<a href='window://floating/UIs/Bank/index.html'>Open or close the bank!</a>

Parameters

You can pass extra parameters to your window via the query string. Both the template and your content will have access to them; they're also set as global JavaScript variables for your content too.

<!-- Maybe we've got some window which asks the user to select something, and we'd like to default it to option #4 -->

<a href='widget://floating/UIs/SomeSelector/index.html?initial=4'>Open a selector</a>

<!-- index.html will end up with a JavaScript variable called initial which it can deal with however it wants -->

Opening a widget from code

The widget protocol is one way of opening up a widget. If you'd like to open up a widget from code, see the widget web API.