[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Contributing working draft on UI Previews
Attachment:
ui-preview.markdown
Description: Binary data
Status: Core 3.0 Draft Specification
This Version: http://open-services.net/wiki/core/User-Interface-Previews-3.0/
Latest Version: http://open-services.net/wiki/core/User-Interface-Previews-3.0/
Authors:
Contributors: OSLC Core Specification Workgroup
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.
This document outlines a technique that MAY (see OSLC Core: UI Previews) be used to show a user in-context information when displaying a link to a resource, and to show more information when the user’s mouse lingers over the link. For example, when a lifecycle resource is being presented to a user, a descriptive title can be used (rather than a URI) to display a link to a related resource . Since a 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 related 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 that resource. The approach (1) acknowledges that a lifecycle resource may refer to other resources of arbitrary types, and (2) does not require the client to know much about the particular details of those resources.
The following terms are used in discussions of previews:
To enable previews of a target resource, a Provider needs to supply the Consumer with a representation of the resource as defined in this specification (referred to as a Compact representation). The Consumer fetches the representation with an HTTP GET request to the target resource’s URI, using the application/x-oslc-compact+json media-type in the request header. If the Provider supports the preview mechanism, it responds with a Compact representation that includes information helpful to the Consumer in displaying a link and previews of the target resource.
The Compact representation MUST be in the JSON format described in this document (see JSON Representation Format below). The media-type ( application/x-oslc-compact+json) MUST be included in HTTP accept and response headers for successful negotiation of the Compact representation.
As mentioned, a referenced resource may be of any arbitrary type, however the information in a Compact representation of that resource is expected to contain specific information. For clarity and convenience, we’ve described that information below using the same terminology and format used in describing OSLC resources and properties. The locale for Strings is negotiated using HTTP-defined mechanisms.
Media-type: application/x-oslc-compact+json
The Compact document is a JSON-LD document. The typical rendering client of the Compact document and UI Preview is a Web browser.
Properties:
| Property | Value-type | Occurs | Description |
|---|---|---|---|
dcterms:title |
String | zero-or-one | Title which may be used in the display of a link to the resource. The value SHOULD include only content that is valid inside an HTML <span> element. Providers SHOULD include a dcterms: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 dcterms:title property. Providers MUST first HTML escape the contents of the dcterms:title before sending the response. |
oslc:shortTitle |
String | zero-or-one | Abbreviated title which may be used in the display of a link to the resource. The value SHOULD include only content that is valid inside an HTML <span> 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 dcterms:title, such as a defect number, makes for a good oslc:shortTitle value. When a resource has no obvious identifier or handle, Providers SHOULD omit the oslc:shortTitle property. Providers MUST first HTML escape the contents of the oslc:shortTitle before sending the response. |
oslc:icon |
Resource | zero-or-one | URI of an image which may be used in the display of a link to the resource. The image SHOULD be 16x16 pixels in size. |
oslc:iconAltLabel |
String | zero-or-one | Alternative label used in association with the oslc:icon, such as HTML img tag’s alt attribute. |
oslc:iconTitle |
String | zero-or-one | Title used in association with the oslc:icon, such as HTML img tag’s title attribute. |
oslc:smallPreview |
Local Inline Resource of type oslc:Preview |
zero-or-one | URI and sizing properties for an HTML document to be used for a small preview. |
oslc:largePreview |
Local Inline Resource of type oslc:Preview |
zero-or-one | URI and sizing properties for an HTML document to be used for a large preview. |
Name: Preview
Type URI: http://open-services.net/ns/core#Preview
Properties:
| Property | Value-type | Occurs | Description |
|---|---|---|---|
oslc:document |
Resource | zero-or-one | The URI of an HTML document to be used for the preview. |
oslc:hintWidth |
String | zero-or-one | Recommended width of the preview. Values MUST be expressed in relative length units as defined in theW3C Cascading Style Sheets Specification (CSS 2.1). Em and ex units are interpreted relative to the default system font (at 100% size). |
oslc:hintHeight |
String | zero-or-one | Recommended height of the preview. Values 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:initialHeight |
String | zero-or-one | Recommended initial height of the preview. The presence of this property indicates that the preview supports dynamically computing its size. Values 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). |
Providers that support previews 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 Compact representation, and if the representation is available for the resource, the Provider responds with a Compact representation. The following constraints apply to Providers:
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 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.
Important: In order to properly recognize when a Provider supports the preview mechanism, Consumers MUST perform two checks on the response from a Compact representation request. Only a response header including a 200 OK status code and compact-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 media-type, Consumers MUST NOT 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.
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 URI property that refers to target resource B:
At any time, the user SHOULD be able to gesture that they would like to navigate the link to the target resource, regardless of how the link to the target resource happens to be rendered.
The typical way for forming and displaying the hyperlink 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 or literal property value in the reference 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 Compact representation information described below is only viable for users who are also authorized to access resource B.
A Compact representation of the resource may contain a more accurate and slightly richer label for a target resource ( dcterms:title element), a short-form title for the resource ( oslc:shortTitle), 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 in forming the hyperlink that is displayed to the user. When available, oslc:shortTitle MAY be used instead of dcterms:title in presentations where visual space is severely limited.
Consumers SHOULD NOT fetch Compact representations 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 target resource against the costs of preemptively fetching the Compact representation 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 dcterms:title and oslc:shortTitle property values do not contain HTML markup beyond the specified set of simple elements.
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 Compact representation 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.
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.
Small and large previews are designed to be sized statically by the client. The Compact representation 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 Compact representation 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.
Values for the oslc:hintWidth, oslc:hintHeight, and oslc:initialHeight properties may be valid relative length units as specified in the W3C Cascading Style Sheets Specification (CSS 2.1). Consumers are expected to use these relative length values in combination with other client system settings to scale a rich preview to a size that fits a user’s display characteristics. Specifically, em and ex units are meant to be relative to 100% of the default system font size, giving Consumers and Providers a common basis for interpreting em- and ex-value hints. For example, an oslc:hintHeight value of “20em” means “I recommend you allow for 20 character’s worth of normal-sized text for my preview.”
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 in pixels. Whitespace characters are not allowed.
Example showing desired preview height of 277 pixels:
oslc-preview-height:277
The source of the event MUST be the preview’s window.
Providers 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:
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, "*");
}
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:
var previewURL = ...; // from oscl:document attribute for preview
var previewPreferredPixelHeight = ...; // from oslc:hintHeight property for preview normalized to pixels, or empty string if none
var previewPreferredPixelWidth = ...; // from oslc:hintWidth property for preview normalized to pixels, or empty string if none
var previewInitialPixelHeight = ...; // from oslc:initialHeight property for preview normalized to pixels, or empty string if none
var previewFrame = document.createElement("iframe"); // create iframe for preview
previewFrame.src = ""
previewFrame.height = (previewPreferredPixelHeight || DEFAULT_PREVIEW_HEIGHT);
previewFrame.width = (previewPreferredPixelWidth || DEFAULT_PREVIEW_WIDTH);
if (window.postMessage && previewInitialPixelHeight) {
previewFrame.height = previewInitialPixelHeight;
var handlePreviewResize = function(event) {
if (event.source !== previewFrame.contentWindow) return;
var 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
A representation of a Compact Resource is a JSON-LD document that looks like the following (for the target resource URL http://example.com/bugs/12345):
{
"title": "12345: Need a "fix" <em>NOW</em>",
"shortTitle": "12345",
"icon": "http://example.com/icons/defect.jpg",
"iconAltLabel": "Defect",
"iconTitle": "Defect",
"largePreview": {
"document": "http://example.com/bugs/12345?hover=large",
"hintHeight": "20em",
"hintWidth": "60em"
},
"smallPreview": {
"document": "http://example.com/bugs/12345?hover=small"
},
"@id": "http://example.com/bugs/12345",
"@type": "http://open-services.net/ns/core#Compact",
"@context": {
"title": "http://purl.org/dc/terms/title",
"shortTitle": "http://open-services.net/ns/core#shortTitle",
"iconTitle": "http://open-services.net/ns/core#iconTitle",
"iconAltLabel": "http://open-services.net/ns/core#iconAltLabel",
"icon": {
"@id": "http://open-services.net/ns/core#icon",
"@type": "@id"
},
"largePreview": {
"@id": "http://open-services.net/ns/core#largePreview",
"@type": "http://open-services.net/ns/core#Preview"
},
"smallPreview": {
"@id": "http://open-services.net/ns/core#smallPreview",
"@type": "http://open-services.net/ns/core#Preview"
},
"document": {
"@id": "http://open-services.net/ns/core#document",
"@type": "@id"
},
"hintHeight": "http://open-services.net/ns/core#hintHeight",
"hintWidth": "http://open-services.net/ns/core#hintWidth"
}
}
The JSON is intended to primarily be consumed from a browser, so the compacted document JSON-LD form is used. The JSON representation has the following syntactic and semantic constraints:
It MUST be valid JSON-LD.
It MUST be in compacted document form with a JSON-LD context that defines the following terms:
{
"@context": {
"title": "http://purl.org/dc/terms/title",
"shortTitle": "http://open-services.net/ns/core#shortTitle",
"iconTitle": "http://open-services.net/ns/core#iconTitle",
"iconAltLabel": "http://open-services.net/ns/core#iconAltLabel",
"icon": {
"@id": "http://open-services.net/ns/core#icon",
"@type": "@id"
},
"largePreview": {
"@id": "http://open-services.net/ns/core#largePreview",
"@type": "http://open-services.net/ns/core#Preview"
},
"smallPreview": {
"@id": "http://open-services.net/ns/core#smallPreview",
"@type": "http://open-services.net/ns/core#Preview"
},
"document": {
"@id": "http://open-services.net/ns/core#document",
"@type": "@id"
},
"hintHeight": "http://open-services.net/ns/core#hintHeight",
"hintWidth": "http://open-services.net/ns/core#hintWidth"
}
}
The context MAY include other terms specific to the provider.
oslc:Compact resource MUST have an “@id” whose value is the URI of the target resource.
dcterms:title, oslc:shortTitle, oslc:icon, oslc:smallPreview, and oslc:largePreview child elements MAY occur at most once.dcterms:title or oslc:shortTitle element MUST be limited to any XHTML <span> element. To afford clients the greatest flexibility to style the text to match the context in which it is being displayed, the titles SHOULD be plain text with XHTML markup used only to emphasize words or phrases or to convey additional information about the target resource.oslc:icon MUST be the URI of an image. The image SHOULD be 16x16 pixels in size.oslc:iconAltLabel and oslc:iconTitle MUST only have string content.oslc:smallPreview and oslc:largePreview MAY have any number of properties, including none.
oslc:smallPreview and oslc:largePreview, if present, MUST be of type oslc:Preview and MAY occur at most once for oslc:smallPreview and once for oslc:largePreview.
oslc:Preview MAY have any number of properties, including none.oslc:document, oslc:hintWidth, oslc:hintHeight, and oslc:initialHeight properties MAY occur at most once for a single oslc:Preview.oslc:document MUST be the URI of a document containing a preview of the resource.oslc:hintWidth, oslc:hintHeight, or oslc:initialHeight MUST be a valid relative length value.All resources MAY have additional properties not specified here. Consumers MUST quietly ignore unknown elements and attributes encountered in a Compact representation.
Providers MAY continue to support to OSLC 2.0 application/x-oslc-compact+xml representation for compatibility with OSLC 2.0 consumers.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]