Overview

This would be added as a new section Dialog Resizing at OSLC Core Delegated

Proposed Changes

Dialog Resizing

There are cases where the initial static size for the dialogs is no longer desired, new size information can be provided to allow for dynamic resizing of these dialogs. Delegated UI dialogs receive their initial size (dimensions) based on the oslc:hintWidth and oslc:hintHeight properties described in oslc:Dialog resource description.

Consumers SHOULD honor a dialog's ability to dynamicly resize but are under no obligation to do so. A Consumer that chooses to honor dynamic resizing for a particular dialog MUST (a) use the oslc:resize value instead of any static width or height, and (b) 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. When the dialog is not shown in an iframe, or shown in a browser that does not support HTML 5 postMessage, everything falls back on static sizing. 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 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.
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:

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

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

Comments

The more I think about it the more I like the full JSON approach, yes it is "heavier" weight but I think it will solve some ambiguities with the original proposed format:

1. Which is width and which is height? oslc-resize:500px,300px

2. What does this mean? oslc-resize:500px

3. What does this mean? oslc-resize: ,500px

Using the full JSON is better and it would be good to "get it right" now and possibly deal with UI Preview later. Though that is a simpler case since it is 1 name=value pair and we aren't attaching special meaning to the value format to mean 2 values.

So I propose / recommend this (since some code changes will have to be made anyway): { "oslc:resize" : { "hintHeight" : "500px", "hintWidth" : "300px" } }

-- SteveSpeicher - 25 Feb 2011

I also have a preference for full JSON. It's trivial to emit on the provider side and much easier to consume on the consumer's side. Otherwise you have to do manual parsing. So +1 for Steve's proposal.

-- BillHiggins - 07 Mar 2011

Here's a modification to my proposal, since messages from dialogs are already emitted with a prefix of 'oslc-response:' instead create a new prefixed response of 'oslc-resize:' with a json payload, so it would look like:

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

-- SteveSpeicher - 07 Mar 2011