Post Message Protocol
The Post Message protocol relies on the HTML5 function
window.postMessage() (reference: HTML5), available in the
latest or pending releases of most browsers. UI Consumers must anticipate
other, unrelated uses of postMessage(), and should ignore messages not
conforming to this protocol.
Typically, the embedded page will be loaded in a window inside another
window, such as a iframe inside some surrounding web page. In such cases,
postMessage() must be called on that parent window. But in a
native application, an outer page is not needed and the embedded page may
be shown directly in the browser's "root" window. When the embedded page
has no parent window, it must call postMessage() on its own
window.
Here are the responsibilities of the UI Consumer and UI Provider in Post Message
protocol.
The UI Consumer's responsibilities
- Include the Delegated UI Dialog via iframe (i.e., setting iframe src to
the URI of the Delegated UI Dialog) or via an embedded browser. Append
the fragment identifier #oslc-core-postMessage-1.0 to the URL to
indicate that Post Message is the desired protocol.
- Add a 'message' listener to the outer window to receive messages from
the Delegated UI Dialog.
- Listen for window 'message' events, ignoring events from other sources
or not prefixed with "oslc-response:"
- When message from Delegated UI Dialog indicates user completed action,
free resources and handle action.
The UI Provider's responsibilities
- Provide Delegated UI Dialog, an HTML page that provides a user
interface for resource creation or selection.
- Allow the user to perform resource creation or selection.
- Once the user has created, selected or canceled, send notification
using
postMessage() to the page's parent window, passed in
event.data string, that is prefixed with "oslc-response:"
See below for the two possible response formats, one for resource
selection and one for creation.
- If the page is not parented, then the message is posted to the page's
own window. The page must ignore this message to itself.
The below _javascript_ code example shows how a UI Provider page would send
a response using postMessage() and taking into account the
fact that some pages are not parented.
function respondWithPostMessage(/*string*/ response) {
(window.parent || window).postMessage("oslc-response:" + response, "*");
}
Window Name Protocol
The Window Name protocol uses the HTML DOM window.name
property to communicate the response (reference: Window Object) from the
UI Provider to the UI Consumer. This special property of window maintains
its value even as the window navigates to a different origin, but the
ifame's window.name can only be read when the accessing
window shares the same origin. For this to happen, when the embedded page
is finished it must set the window.name and also change the
window.location to a page with the same origin as the outer
frame. This not only allows the UI Consumer to access the result, but
also fires an event telling the UI Consumer when to do so. This return
location is passed to the embedded page using the
window.name property.
Here are the responsibilities of the UI Consumer and UI Provider in Window Name
protocol.
The UI Consumer's responsibilities
- Include the Delegated UI Dialog via iframe (i.e setting iframe src to
the URI of the Delegated UI Dialog) or via an embedded browser. Append
the fragment identifier #oslc-core-windowName-1.0 to the URL to
indicate that Window Name is the desired protocol.
- On the iframe, set the frame's
window.name to indicate the Return URL.
- On the iframe, Listen for 'onload' events
- When an 'onload' event occures an the frame's location is equal to the Return URL
then read the response from the window.name.
The following _javascript_ code illustrates the protocol. The code for the
destroyFrame(), handleMessage() and
displayFrame() methods are not provided in this example, but
should be obvious to a _javascript_ developer. The UI Consumer must provide
these methods.
var pickerURL = ... // URL of Provider's Delegated UI Dialog
var returnURL = ... // Consumer's Return URL
var frame = document.createElement('iframe');
function windowNameProtocol() {
// Step #1: create iframe with fragment to indicate protocol
// Step #2: set the iframe's window.name to indicate the Return URL
if (ie > 0) {
frame = document.createElement('<iframe name=\'' + returnURL + '\'>');
} else {
frame = document.createElement('iframe');
frame.name = returnURL;
}
frame.src = "" + '#oslc-core-windowName-1.0';
frame.width = 450;
frame.height = 300;
displayFrame(frame);
// Step #3: listen for onload events on the iframe
var ie = window.navigator.userAgent.indexOf("MSIE");
if (ie > 0) {
frame.attachEvent("onLoad", onFrameLoaded);
} else {
frame.
}
}
function onFrameLoaded() {
try { // May throw an exception if the frame's location is still a different origin
// Step #4: when frame's location is equal to the Return URL
// then read response and return.
if (frame.contentWindow.location == returnURL) {
var message = frame.contentWindow.name;
destroyFrame(frame);
handleMessage(message);
}
} catch (e) {
// ignore: access exception when trying to access window name
}
}
The UI Provider's responsibilities
As soon as the embedded page has loaded, perform the following:
- Provide Delegated UI Dialog, an HTML page that provides a user
interface for resource creation or selection.
- Read the Return URL from the window.name variable
- Allow user to perform resource creation or selection.
- Once user has created, selected or canceled, communicate the user's
response by setting the window.name variable to the response. See below
for the two possible response formats, one for resource selection and
one for creation.
- Indicate that user has responded by setting the window.location to the
Return URL specified by the UI Consumer.
The _javascript_ example below shows a UI Provider notifying its UI Consumer
after a user has responded.
function respondWithWindowName(/*string*/ response) {
// Step #2: read the return URL
var returnURL = window.name;
// Step #4: send the response via the window.name variable
window.name = response;
// Step #5: indicate that user has responded
window.location = returnURL;
}
Resource Selection
Resource Selection can be used when a UI Consumer wants to allow a user to
pick a resource that is managed by an OSLC Service. Using either the Post
Message or Window Name protocols defined above, the UI Consumer uses an
iframe to embed a selection dialog that is provided by the service, then
awaits notification that the user has selected a resource.
To enable Resource Selection, an OSLC Service MUST provide in its
Service Resource a value for the oslc:selectionDialog
property. The property value will include a oslc:dialogURI
property that indicates the URI of the selection dialog.
Regardless of how the response from the UI Provider is conveyed to the UI
Consumer, the response SHOULD be formatted as follows:
| JSON Property Name |
Type |
Occurs |
Description |
rdf:resource |
String |
zero-or-one |
URI of the resource selected or created |
oslc:label |
String |
zero-or-one |
Short label describing the resource selected |
An empty array indicates that the resource selector has been canceled.
An example Resource Selection response:
{
"oslc:results": [
{
"oslc:label": "Bug 123: Server crash",
"rdf:resource": "http://example.com/bug123"
},
{
"oslc:label": "Bug 456: Client hangs on startup",
"rdf:resource": "http://example.com/bug456"
}
]
}
Resource Creation
Resource Creation can be used when a UI Consumer wants to allow a user to
create a new resource that is managed by an OSLC Service. Using either
the Post Message or Window Name protocols defined above, the UI Consumer
uses an iframe to embed a creation dialog that is provided by the
service, then awaits notification that the user has created a
resource.
To enable Resource Creation, an OSLC Service MUST provide in its
Service Resource a value for the oslc:creationDialog
property. The property value will include a oslc:dialogURI
property that indicates the URI of the creation dialog.
Regardless of how the response from the UI Provider is conveyed to the UI
Consumer, the response SHOULD be formatted as defined by
oslc:results
{
"oslc:results": [
{
"oslc:label": "Bug 123: Server crash",
"rdf:resource": "http://example.com/bug123"
},
{
"oslc:label": "Bug 456: Client hangs on startup",
"rdf:resource": "http://example.com/bug456"
}
]
}
Prefilling Creation Dialogs
Service providers MAY support receiving a POST request whose
content body is a resource representation to the Creation Dialog URI to
retrieve a URI that represents the embedded page to be used. Service
providers MUST respond with a response status of 201 (Created)
with the response header Location whose value is the URI to
request the newly created form. After some elapsed time, service
providers MAY respond with a 404 (Not Found), 410 (Gone) or 3xx
(Redirect) to an HTTP GET request for these URIs.
Dialog Resizing
Delegated UI dialogs receive their initial size (dimensions) based on the
oslc:hintWidth and oslc:hintHeight properties
described in oslc:Dialog resource description. There are
cases where UI Provider recognizes that the initial size of a Delegated
UI dialog is not sufficient and needs a way to ask the UI Consumer to
resize the dialog. In this section we specify a mechanism that enables
dialog resizing, but only when Post Message Protocol is used.
Consumers MAY honor a dialog's ability to dynamically resize.
Those that do (a) MUST use Post Message Protocol, (b)
MUST use the oslc:resize value instead of any
static width or height, and and (c) MUST register a handler to
receive dialog resize messages sent by the dialog Provider and adjust the
size of the dialog accordingly.
Since a dialog is allowed to resize itself any number of times, the
Consumer MUST keep a handler registered and react appropriately
each time it received a dialog resize message from that dialog.
UI Providers SHOULD NOT request sizes larger than 95% of the
current http://www.w3.org/TR/CSS2/visuren.html#viewport][viewport,
to avoid covering the entire viewport with the dialog.
Here are the responsibilities of the UI Consumer and UI Provider in dialog
resizing.
The UI Consumer's responsibilities
- Include the Delegated UI Dialog via iframe (i.e setting iframe src to
the URI of the Delegated UI Dialog) or via an embedded browser.
- Add a 'message' listener to the outer window to receive messages from
the Delegated UI Dialog.
- Listen for window 'message' events, ignoring events from other sources
or not prefixed with "oslc-resize:". Multiple resize 'message' events
may be sent while the dialog is visible.
- When message from Delegated UI Dialog indicates user completed action,
free resources and handle action.
The UI Provider's responsibilities
- Provide Delegated UI Dialog, an HTML page that provides a user
interface for resource creation or selection.
- Allow the user to perform resource creation or selection.
- Once the Provider needs to resize the dialog, send notification using
postMessage() to the page's parent window, passed in
event.data string, that is prefixed with "oslc-resize:".
Multiple resize messages may be sent. See below for the response
format.
- If the page is not parented, then the message is posted to the page's
own window. The page must ignore this message to itself.
The below _javascript_ code example shows how a UI Provider page would send
a response using postMessage() and taking into account the
fact that some pages are not parented.
function respondWithPostMessage(/*string*/ resize_response) {
(window.parent || window).postMessage("oslc-resize:" + resize_response, "*");
}
Regardless of how the response from the UI Provider is conveyed to the UI
Consumer, the response SHOULD be formatted as follows:
An example Dialog Resize response with new height of '600px' and a width
of '400px':
{
"oslc:hintHeight": "600px",
"oslc:hintWidth": "400px"
}
Attachment:
oslc-delegated.png
Description: PNG image
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
