Difference between revisions of "Widget Protocol"

From PowerUI
Jump to: navigation, search
(The content path)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The window:// protocol is used from an anchor (a href='..') element to ''cycle'' a window. If you click the link a second time, it will close the open window. It specifies what should be inside the window ''and'' the [[Window Templates|window template]] to use:
+
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 Templates|widget template]] to use:
  
 
<syntaxhighlight lang="html">
 
<syntaxhighlight lang="html">
  
<a href='window://<template name>/<path to content>'>Cycle a window</a>
+
<a href='widget://<template name>/<path to content>'>Cycle a widget</a>
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
  
== Floating - the Built in template for a typical window ==
+
== 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).
 
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).
Line 15: Line 15:
 
== The content path ==
 
== The content path ==
  
Your content path is a complete URI which defaults to being relative to resources://. 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. That makes your window URL look like this:
+
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:
  
 
<syntaxhighlight lang="html">
 
<syntaxhighlight lang="html">
  
 +
<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>
 
<a href='window://floating/UIs/Bank/index.html'>Open or close the bank!</a>
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Opening a window from code ==
+
== 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.
 +
 
 +
<syntaxhighlight lang="html">
 +
 
 +
<!-- 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 -->
 +
 
 +
</syntaxhighlight>
 +
 
 +
== Opening a widget from code ==
  
The window protocol is one way of opening up a window. If you'd like to open up a window from code, see the [[window manager web API]].
+
The widget protocol is one way of opening up a widget. If you'd like to open up a widget from code, see the [[Widgets (Web API)|widget web API]].

Latest revision as of 17:55, 23 March 2017

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.