OslcUiPreviewDRAFT < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
TWiki>
Main Web>OslcCore>OslcCoreSpecification>OslcCoreUiPreview>OslcUiPreviewDRAFT (03 May 2010, ScottBosworth) (raw view)
---+ OSLC Core Guidance: User Interface Previewing of Resources (early drafts)

This wiki topic is a record of the evolution of the Ui Preview Guidance. Please see OslcCoreUiPreview for the current approved guidance. Comments and issues on the specification may be logged at OslcCoreUiPreviewISSUES.

%TOC%

---++ Introduction

UI Preview is a technique that can be used to show a user a brief preview of a resource when displaying a link to the resource and to show more information when the user's mouse lingers over the resource. For example, when a lifecycle resource containing links to other resources is being presented to a user, a descriptive title can be displayed to represent the link. Since the descriptive title alone might not provide the user with sufficient context to decide whether the link is worth navigating at that moment, the user may linger over the link and cause the user interface to provide additional rich previews revealing even more information about the linked resource (in advance of actually navigating the link).

This specification describes a mechanism that enables client applications, given only the URI of a resource, to discover helpful information for presenting in-context links and previews of a linked resource. The approach (1) acknowledges that a lifecycle resource may contain links to resources of arbitrary types, and (2) does not require the client to know much about the particular details of the linked resources.

---+++ Terminology

The following terms are used in discussions of previews:

   * *Preview Consumer* - a web application displaying a link to a lifecycle resource.

   * *Preview Provider* - a Service Provider that offers Consumers information for displaying a link to a resource and rich previews of the resource.

---++ Conceptual Model

To enable previews of a target resource, a Provider needs to supply the Consumer with a Preview Resource. The Consumer fetches the Preview Resource by sending a GET request to the target resource's URI. If the Provider supports the preview mechanism, it responds with a representation of the Preview Resource with properties that are helpful to the Consumer in displaying the link and previews of the target resource.

Preview Resource representations *MUST* be in RDF/XML format. The preview media-type ( _application/x-oslc-preview+xml_) *MUST* be included in HTTP accept and response headers for Preview Resource requests.

---+++ Preview Resources
---++++ Resource: Preview

   * *Name*: Preview
   * *Suggested Prefix*: =oslc=
   * *Namespace URI*: !http://open-services.net/xmlns/oslc#
   * *Type URI*: !http://open-services.net/xmlns/oslc#Preview
   * *Version String*: =oslc-core-1.0=
   * *Properties*:

<blockquote style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 40px; border-width: initial; border-color: initial; border-style: none; padding: 0px">

| *Property* | *Value-type* | *Occurs* | *Description* |
| =dc:title= | XML Literal | at-most-one | Title which may be used in the display of the resource link. The value SHOULD include only content that is valid inside an XHTML &lt;span&gt; element. Providers SHOULD include a dc:title property with an informative label for the resource. The title is typically shown to a user as a hyperlink. For a resource with no obvious title, Providers SHOULD omit the dc:title property. |
| =dc:name= | XML Literal | at-most-one | Name or abbreviated title which may be used in the display of the resource link. The value SHOULD include only content that is valid inside an XHTML &lt;span&gt; element. Providers SHOULD include an abbreviated title for the resource when possible. The abbreviated title is typically shown to a user as a hyperlink in presentations where visual space is limited. As a general guideline, the length of the abbreviated title SHOULD be 5 characters or less. A user-visible identifier that ordinarily appears in the dc:title, such as a defect number, makes for a good dc:name value. When a resource has no obvious identifier or handle, Providers SHOULD omit the dc:name property. |
| =olsc:icon= | Resource | at-most-one | URI of an image which may be used in the display of the resource link. The image SHOULD be 16x16 pixels in size. |
| =oslc:smallPreview= | Local Inline Resource of type =oslc:DetailedPreview= | at-most-one | URI and sizing properties for an HTML document to be used for a small preview.  |
| =oslc:largePreview= | Local Inline Resource of type =oslc:DetailedPreview= | at-most-one | URI and sizing properties for an HTML document to be used for a large preview.  |
</blockquote>

---++++ Resource: !DetailedPreview

   * *Name*: !DetailedPreview
   * *Suggested Prefix*: oslc
   * *Namespace URI*: !http://open-services.net/xmlns/oslc#
   * *Type URI*: !http://open-services.net/xmlns/oslc#DetailedPreview
   * *Version String*: oslc-core-1.0
   * *Properties*:

<blockquote style="background-color: #fbfbfb; margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 40px; border-width: initial; border-color: initial; border-style: none; padding: 0px">

| *Property* | *Value-type* | *Occurs* | *Description* |
| =olsc:document= | Resource | at-most-one | The URI of an HTML document to be used for the preview. |
| =oslc:hintWidth= | String | at-most-one | Provider recommended width of the preview. Valid values are defined by the width property in the [[http://www.w3.org/TR/2009/CR-CSS2-20090423/][W3C Cascading Style Sheets Specification (CSS 2.1)]]. |
| =oslc:hintHeight= | String | at-most-one | Provider recommended height of the preview Valid values are defined by the height property in the [[http://www.w3.org/TR/2009/CR-CSS2-20090423/][W3C Cascading Style Sheets Specification (CSS 2.1)]]. |
| =oslc:initialHeight= | String | at-most-one | Provider recommended initial height of the preview. The presence of this property indicates that the preview supports dynamically computing its size. Valid values are defined by the height property in the [[http://www.w3.org/TR/2009/CR-CSS2-20090423/][W3C Cascading Style Sheets Specification (CSS 2.1)]]. |
</blockquote>

---++ Preview Provider Responsibilities

Providers that support UI preview will examine the HTTP Accept header for each incoming GET and HEAD request for a resource. If the header indicates that the client has requested a preview, and if a preview is available for the resource, the Provider responds with a UI Preview resource representation. The following constraints apply to providers that implement UI Preview:

   * Providers that implement UI Previews need not provide a preview for every resource. Providers *SHOULD* provide previews the resources that other applications or resources ordinarily link to. This is left to individual Providers to decide.
   * If the resource does not exist or is not accessible to the requesting Consumer, the Provider *SHOULD* return the same 4xx status code that it would have returned had the Consumer instead requested the default representation of the resource.
   * If the resource exists and is accessible to the Consumer, but does not have a Preview Resource (in other words, does not support the preview mechanism), the Provider *SHOULD* respond with a status code of _406 Not Acceptable_ ( _[[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1"][Section 14.1 of HTTP 1.1 specification]] says that a server "SHOULD" respond with a 406 status code if it cannot serve up the media-type specified in the accept header)._ 
      * Otherwise, the Provider *SHOULD* respond with a representation of a Preview Resource and a response header including a _200 OK_ status code and the _preview media-type_. The representation MUST follow the [[OSLCCoreSpecDRAFT#RDF_XML_Representation][guidelines for RDF/XML resource representations]] as outlined in the OSLC Core Specification Guidelines (for example representations, see [[OslcUiPreviewDRAFT#Samples][Sample Representations of Preview Resources]]).
   * Providers *SHOULD* include a Vary field in the response header when returning a Preview Resource. Experience has shown that for subsequent requests on the URL, some browser caching algorithms ignore the media-type and return a cached representation of the URL request (which may be the default target resource representation or the Preview Resource representation). Use of the Vary field allows a cache to properly interpret future requests on the resource and informs the browser that the cacheable response is subject to server-driven negotiation (see _[[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44][Section 14.44 of the HTTP 1.1 specification]]_).
   * Providers *MAY* consult the Accept-Language field on requests for a Preview Resource (and on requests for rich preview documents) and return a resource representation for the requested natural language.

---++ Guidelines and Responsibilities for Preview Consumers

Though Consumer implementations will vary, tool users will benefit if the preview mechanism is used consistently. Previews are a valuable added benefit to tool users and not a necessary element for users to perform tasks. As such, Consumers should gracefully handle unsuccessful attempts to use the preview mechanism; unsuccessful attempts should never result in failure in the way a Consumer application operates or performs. Consumers *SHOULD* anticipate that the preview mechanism may not be supported for a linked resource, or that the the preview mechanism may not work due to security or service availability issues, or even that preview capability once supported by a Provider has been phased out.
<blockquote style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 40px; border-width: initial; border-color: initial; border-style: none; padding: 0px">

*Important:* In order to properly recognize when a Provider supports the preview mechanism, Consumers *MUST* perform two checks on the response from a Preview Resource request. Only a response header including a _200 OK_ status code and the _preview media-type_ assures the Consumer that the preview protocol is understood by the Provider. Though Providers should respond with a _406 Not Acceptable_ status code when they do not recognize the preview media-type, Consumers cannot rely on this behavior. Some servers simply ignore an unrecognized media-type and respond with _200 OK_ and a default representation of the resource. If either the status code or media-type conditions are not met, then Consumers *MUST* conclude that the Provider does not support the preview mechanism.
</blockquote>

The following guidance is suggested for Consumer display of a resource link and rich previews. For purposes of this discussion, assume source resource A has a link to target resource B:

<blockquote style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 40px; border-width: initial; border-color: initial; border-style: none; padding: 0px">

---+++++ Navigation to the target resource
 At any time, the user *SHOULD* be able to gesture that they would like to navigate to the target resource, regardless of how the link to the target resource happens to be rendered. 
---+++++ Default way to display the link to the target resource
 The default display of the link *SHOULD* be based on information that is stored locally in source resource A (or that is generally known to the Consumer). Generally, link text can be derived from property values of resource A, and potentially from a string property value of the link to the target resource B, if such a property exists. Because these property values are part of the representation of the source resource A, they are available without consulting the target resource, and will be available even if the target resource B cannot be fetched. When available, Consumers *SHOULD* display this string (as opposed to the URI) when presenting resource A to indicate a potential navigation to resource B. This is the basic presentation of a link to target resource B.

The default display of the link from A to B is visible to any user authorized to access resource A. The use of Preview Resource information described below is only viable for users who are also authorized to access resource B.
---+++++ Displaying the link using the Preview Resource title, name, and icon
 A Preview Resource may contain a more accurate and slightly richer label for a target resource ( =dc:title= element), a short-form title for the resource ( =dc:name=), and a corresponding image ( =oslc:icon=), all of which may be based on the current state of the target resource. If this becomes known to the Consumer, the Consumer *SHOULD* assume that this information is better and use it to improve and replace the default link display. When available, =dc:name= MAY be used instead of dc:title in presentations where visual space is severely limited.

Consumers *SHOULD NOT* fetch Preview Resources when there is perfectly usable default display information available. When designing a Consumer application, consideration should be given to the potential benefits of obtaining an improved title and icon for the linked resource against the costs of preemptively fetching the Preview Resource in terms of added load on servers and networks (which might only be apparent to users on slow networks or heavily loaded servers).

Consumers *SHOULD* be wary of material obtained from non-trusted sources; in particular, the Consumer *SHOULD* check that the dc:title and dc:name property values do not contain HTML markup beyond the specified set of simple elements.
---+++++ Displaying a small preview
 If a user mouses or hovers over a displayed link, the Consumer *SHOULD* determine whether the target resource has a small preview (oslc:smallPreview). If it does, the Consumer *SHOULD* present the small preview document in a hovering widget. Since preview documents may contain arbitrary content, including HTML and scripts, Consumers *MUST* use iframes if embedding the preview document inside another HTML-based presentation.

The Consumer *SHOULD NOT* attempt to prefetch a Preview Resource just to have the preview URIs in hand so that the hover can come up faster. There is a low chance that the user will make a gesture that would call for the display of a small preview. It would generally be a poor tradeoff to increase overall system load just to decrease UI latency for low probability eventualities.

---+++++ Displaying a large preview
 If the user then gestures that they want to see a bit more of the resource, the Consumer should determine whether the target resource has a large preview ( =oslc:largePreview=). If it does, the Consumer *SHOULD* present the large preview document in a stationary widget that permits further user interaction. Again, since preview documents may contain arbitrary content, including HTML and scripts, Consumers MUST use iframes if embedding the preview document inside another HTML-based presentation.</blockquote>

---++ Preview sizing

Small and large previews are designed to be sized statically by the client. The Preview Resource *MAY* include =oslc:hintHeight= and/or =oslc:hintWidth= properties for each of the previews. When the resource does not supply preferred sizing for a preview, the Consumer *SHOULD* use a reasonably generous default value large enough to display previews without scroll bars or truncation. When the resource supplies preferred sizing, the Consumer *SHOULD* use the preferred value instead.

Small and large previews *MAY* also support dynamic resizing. For a preview that supports dynamic resizing, the Preview Resource *MUST* include the =oslc:initialHeight= property to indicate the initial height. A Provider MAY use dynamic resizing previews on some of their resources but not others. Moreover, dynamic resizing applies to the small and large previews independently.

The communication of dynamic preview size information happens within a web browser. !JavaScript code running in the preview iframe sends a message that is received and acted upon by !JavaScript code running in the iframe's parenting window. This cross-frame communication is done using HTML 5 postMessage. While many major web browsers support HTML 5 postMessage, support is not yet universal. In browsers that do not support postMessage, there is no way to implement dynamic resizing. In this case, everything falls back on static sizing.

A dynamic preview resize message consists of the characters "oslc-preview-height:" followed by the representation of the desired height of the preview. Whitespace characters are not allowed.

Example showing desired preview height of 277 pixels:

<pre style="width: auto; margin-top: 1em; margin-right: 0px; margin-bottom: 1em; margin-left: 0px; color: #7a4707; overflow-x: scroll; overflow-y: scroll">           oslc-preview-height:277px </pre>

The source of the event *MUST* be the preview's window.

Provders *SHOULD* make a preview dynamically resizeable where that suits their needs, but are under no obligation to do so. A Provider that chooses to offer dynamic resizing for a particular resource preview *MUST* (a) supply a static =oslc:initialHeight= value, and (b) send one or more preview resize messages when the preview is shown in an iframe. When the preview is shown in a web browser that does not support HTML 5 postMessage (e.g., Internet Explorer 7), everything falls back on static sizing.

!JavaScript snippet for a typical resource preview to report a preview resize event to its parent window:

<blockquote><verbatim>
var newPreviewHeight = ...; // desired height of preview (hard!)

if (window.postMessage && window.parent)  {
    var PREVIEW_RESIZE_MESSAGE_PREFIX = "oslc-preview-height:";
    var resizeMessage = PREVIEW_RESIZE_MESSAGE_PREFIX + newPreviewHeight;
    window.parent.postMessage(resizeMessage, "*");
 }
</verbatim></blockquote>

Note that postMessage for a preview resize message *MUST* be executed in the context of the preview's window so that the source of the event is set correctly.

Warning: Reliably computing the height of a document (newPreviewHeight above) is non-trivial owing to severe incompatibilities between browsers. Caveat emptor.

Consumers *SHOULD* honor a preview's ability to dynamic resize, but are under no obligation to do so. A Consumer that chooses to honor dynamic resizing for a particular preview *MUST* (a) use the oslc:initialHeight value instead of any static height, and (b) register a handler to receive preview resize messages sent by the preview and adjust the size of the preview accordingly. Since a preview is allowed to resize itself any number of times, the Consumer *MUST* keep a handler registered and react appropriately each time it received a preview resize message from that preview. When the preview is not shown in an iframe, or shown in a browser that does not support HTML 5 postMessage, everything falls back on static sizing.

Consumers that honor dynamic preview resizing *SHOULD* make an effort to minimize the amount of resizing behavior that the user actually sees. Consumers *SHOULD* locally cache the last known dynamic height for recently shown preview URLs, and use a cached height for a preview in preference to its oslc:initialHeight value.

!JavaScript snippet for a typical Consumer to show a preview in an iframe:

<blockquote><verbatim>
var previewURL = ...; // from oscl:document attribute for preview 
var previewPreferredHeight = ...; // from oslc:hintHeight property for preview,or empty string if none 
var previewPreferredWidth = ...; // from oslc:hintWidth property for preview, or empty string if none 
var previewInitialHeight = ...; // from oslc:initialHeight property for preview, or empty string if none  

var previewFrame = document.createElement("iframe");  // create iframe for preview 
previewFrame.src = previewURL;
previewFrame.height = (previewPreferredHeight || DEFAULT_PREVIEW_HEIGHT); 
previewFrame.width = (previewPreferredWidth || DEFAULT_PREVIEW_WIDTH);  

if (window.postMessage && previewInitialHeight) {
   previewFrame.height = previewInitialHeight;

   var handlePreviewResize = function(event) { 
        if (event.source !== previewFrame.contentWindow) return; 
        var data = event.data;  
        var PREVIEW_RESIZE_MESSAGE_PREFIX = "oslc-preview-height:"; 
        if (data && data.indexOf(PREVIEW_RESIZE_MESSAGE_PREFIX) === 0) {    
            var newHeight = data.substring(PREVIEW_RESIZE_MESSAGE_PREFIX.length);   
            previewFrame.height = newHeight;    
         } 
    } 
   dojo.connect(window, "onmessage", window, handlePreviewResize);
} 
document.body.appendChild(previewFrame); // make preview iframe visible

</verbatim></blockquote>

<a name="Samples" title="Samples"></a>
---++ Sample Representations of Preview Resources

Below is a sample preview resource representation that complies with the OSLC Core Specification v1.0 (DRAFT 20100419).

---+++ Preview resource representation: RDF/XML

<blockquote> <verbatim>

<?xml version="1.0" encoding="UTF-8"?>

<oslc:Preview
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/terms/"
   xmlns:oslc="http://open-services.net/xmlns/oslc#"
   rdf:about="http://example.com/bugs/2314">

   <dc:title> 12345: &lt;s&gt;Null pointer exception during startup&lt;/s&gt; </dc:title>
   <dc:name> 12345 </dc:name>
   <oslc:icon rdf:resource="http://example.com/icons/defect.jpg" />

   <oslc:smallPreview>
      <oslc:DetailedPreview>
         <oslc:document rdf:resource="http://example.com/bugs/12345?hover=small" />
      </oslc:DetailedPreview>
   </oslc:smallPreview>


   <oslc:largePreview>
      <oslc:DetailedPreview>
         <oslc:document rdf:resource="http://example.com/bugs/12345?hover=large" />
         <oslc:hintWidth> 60em </oslc:hintWidth>
         <oslc:hintHeight> 20em </oslc:hintHeight>
      </oslc:DetailedPreview>
   </oslc:largePreview>

 </oslc:Preview>

</verbatim></blockquote>

<blockquote style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 40px; border-width: initial; border-color: initial; border-style: none; padding: 0px">

Click [[http://www.w3.org/RDF/Validator/ARPServlet?URI=http%3A%2F%2Fopen-services.net%2Fpub%2FMain%2FOslcUiPreviewDRAFT%2Fsample1.xml&PARSE=Parse+URI%3A+&TRIPLES_AND_GRAPH=PRINT_BOTH&FORMAT=PNG_EMBED&EMBEDDED_RDF=on&NODE_COLOR=Black&NODE_TEXT_COLOR=Blue&EDGE_COLOR=Darkgreen&EDGE_TEXT_COLOR=Red&FONT_SIZE=10&ORIENTATION=LR][HERE]] to see RDF/XML validation results.
</blockquote>

---++ References

   * CSS - [[http://www.w3.org/TR/CSS2/][Cascading Style Sheets Level 2 Revision 2 v2.1]]
   * Dublin Core - [[http://dublincore.org/documents/dces/][Dublin Core Metadata Element Set, Version 1.1]]
   * HTML5 Posting Message - [[http://www.w3.org/TR/html5/comms.html#posting-messages][W3C HTML5 postMessage]]
   * HTTP - [[http://tools.ietf.org/html/rfc2616][Hyper-text Transfer Protocol (HTTP/1.1)]]
   * RDF/XML Concepts - [[http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/][RDF/XML Concepts and Abstract Syntax]]
   * RDF/XML Syntax - [[http://www.w3.org/TR/2004/REC-rdf-syntax-grammar-20040210/][RDF / XML Syntax Specification (Revised) ]]
   * Strawman Proposal - [[https://jazz.net/wiki/bin/view/Main/LinkRendering][IBM Jazz Compact Rendering 1.0]]
   * Window Object - [[http://www.w3.org/TR/Window/#window-embedding][Window Object 1.0 Window.name]]
   * XSD Datatypes - [[http://www.w3.org/TR/xmlschema-2/][XML Schema Part 2: Datatypes Second Edition]]
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
xml	sample1.xml	manage	0.9 K	20 Apr 2010 - 21:08	ScottBosworth
Topic revision: r25 - 03 May 2010 - 20:39:54 - ScottBosworth
Main.OslcUiPreviewDRAFT moved from Main.OslcCompactRenderingDRAFT on 12 Apr 2010 - 13:18 by ScottBosworth - put it back
Main
Webs
Main
Sandbox
TWiki
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback