History   View   Links to this page Revision from: 2013 August 30 | 03:05 pm
This is the revision from 2013 August 30 at 03:05 pm   View the current live version of the article.

Status: Core 3.0 Draft Specification

OSLC_logo.png

Open Services for Lifecycle Collaboration
Core Specification Version 3.0 Delegated User Interface dialogs

This Version: http://open-services.net/wiki/core/Delegated-User-Interface-Dialogs-3.0/

Latest Version: http://open-services.net/wiki/core/Delegated-User-Interface-Dialogs-3.0/

Authors:

Contributors: OSLC Core Specification Workgroup

Table of Contents

Contents

License

TBD

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED, SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in RFC-2119. This document is a mixture of normative and informative text. See the glossary below for definitions of these terms.

Introduction

OSLC specifications target specific integration scenarios. In some cases, allowing one product to delegate to a user interface defined in another product is a more effective way to support a use case than an HTTP interface that can only be accessed programmatically. There are two cases where this is especially true:

  • Resource creation: when a user of a web application needs to create a new resource in an OSLC Service Provider. In this case the web application asks the service provider to provide a UI for resource creation and the provider notifies the application when the creation has been completed or canceled by the user.
  • Resource selection: when a user of a web application and needs to pick a resource managed by a OSLC Service Provider. In this case the web application asks the service provider to provide a UI for resource selection and the provider notifies the application when a resource or resources has been selected or if the selection was canceled.

To support these two cases, below we define OSLC Delegated User Interface (UI) Dialogs. Delegated UI Dialogs are a technique where one provider can embed a creation or selection UI into another using a combination of an HTML <iframe> and JavaScript code. The diagram below illustrates how delegated UI dialogs work in a scenario where Provider A wants to allow a user to select or create a resource managed by Provider B.

Figure #3: Delegated UI Dialog interactions

Delegated UI Dialogs

Next, the details of the Delegated UI Dialog protocol.

Terminology

The following terms are used in discussions of Delegated UI Dialogs:

  • UI Consumer - a web application that is embedding a Delegated UI Dialog from an OSLC Service Provider. This consumer could be a web page, with the Delegated UI Dialog loaded into an iframe or a native application, e.g. an IDE like Eclipse, that is embedding a web browser component.

  • UI Provider - an OSLC Service provider that offers one or more Delegated UI Dialogs. These dialogs will be specified in the provider’s Service Provider resource.

The next sections explain how Delegated UI Dialogs work.

Post Message and Window Name protocols

To support the widest range of web browsers, we define two different protocols for communicating the information about the user’s action from the UI Provider and back to the UI Consumer. These are the Post Message and Window Name protocols described below.

In both the Post Message and Window Name protocols, the way that a UI Consumer includes a Delegated UI Dialog in an HTML page is to create an iframe and specify the src as the URI of the Delegated UI Dialog to be included. The UI Consumer indicates the protocol to be used by appending one of the two fragment identifiers below to the URI:

  • #oslc-core-postMessage-1.0 - Indicates that the Post Message protocol is to be used
  • #oslc-core-windowName-1.0 - Indicates that the Window Name protocol is to be used

The JavaScript code example below shows now a UI Provider can determine which protocol is in use:

if ([removed].hash == '#oslc-core-windowName-1.0') {       
    // Window Name protocol in use
} else if ([removed].hash == '#oslc-core-postMessage-1.0') {
    // Post Message protocol in use
}

iframe Creation Considerations

Regardless of the protocol in effect, it is recommended that UI Consumers follow the below iframe creation guidelines to provide a more seamless user experience:

  • Embed the iframe within a div element, with height and width set based on the relative length values specified in the Service Resource that declares the Delegated UI Dialog.
  • Set the iframe border size to ‘0’
  • Set the iframe scrolling to ‘auto’

Next, the details for each of the two protocols.

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 webpage. 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

  1. 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.
  2. Add a ‘message’ listener to the outer window to receive messages from the Delegated UI Dialog.
  3. Listen for window ‘message’ events, ignoring events from other sources or not prefixed with “oslc-response:”
  4. When message from Delegated UI Dialog indicates user completed action, free resources and handle action.

The UI Provider’s responsibilities

  1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
  2. Allow the user to perform resource creation or selection.
  3. 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.
  4. 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, "*");
}

Now, the Window Name protocol.

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 [removed] 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

  1. 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.
  2. On the iframe, set the frame’s window.name to indicate the Return URL.
  3. On the iframe, Listen for ‘onload’ events
  4. 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 = pickerURL + '#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.onload = onFrameLoaded;
  }
}

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:

  1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
  2. Read the Return URL from the window.name variable
  3. <span Verdana, Arial, Helvetica, sans-serif; font-size: small”>Allow user to perform resource creation or selection.
  4. 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.
  5. Indicate that user has responded by setting the [removed] 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
   [removed] = 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:

  • Name: results
  • URI: http://open-services.net/ns/core#results
Prefixed Name Occurs Read-only Value-type Representation Range Description
rdf:resource zero-or-one True Resource Reference n/a URI of the resource selected or created
oslc:label zero-or-one True String n/a n/a 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

Example:

{
  "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 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

  1. 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.
  2. Add a ‘message’ listener to the outer window to receive messages from the Delegated UI Dialog.
  3. 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.
  4. When message from Delegated UI Dialog indicates user completed action, free resources and handle action.

The UI Provider’s responsibilities

  1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
  2. Allow the user to perform resource creation or selection.
  3. 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.
  4. 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:

Prefixed Name Occurs Read-only Value-type Representation Range Description
oslc:hintHeight exactly-one True String n/a n/a New dialog height size. Height size MUST be expressed in relative length units as defined in the W3C Cascading Style Sheets Specification (CSS 2.1) Em and ex units are interpreted relative to the default system font (at 100% size)
oslc:hintWidth exactly-one True String n/a n/a New dialog width size. Width size MUST be expressed in relative length units as defined in the W3C Cascading Style Sheets Specification (CSS 2.1) Em and ex units are interpreted relative to the default system font (at 100% size)

An example Dialog Resize response with new height of ‘600px’ and a width of ‘400px’:

{
  "oslc:hintHeight" : "600px",
  "oslc:hintWidth" : "400px"
}

Category:Specifications

Categories