3.1 Getting the Compact Resource

This section is non-normative.

Clients can discover Compact resources in three ways:

1. Discovering Compact Resources Using the HTTP Accept Header
2. Discovering Compact Resources Using the HTTP Link Header
3. Discovering Compact Resources Using the HTTP Prefer Header

The HTTP Accept header allows clients to access previews using the application/x-oslc-compact+xml MIME type extension to request the Compact resource representation for a URI instead of the content of the resource itself. This usage is considered deprecated and is included only to maintain compatibility with [OSLCUIPreview20].

The HTTP Link header allows servers to offer previews for any resource, even binary resources with no RDF or JSON representations. To discover previews using the Link header, a client typically performs an HTTP HEAD or OPTIONS request on the resource URI. The response contains a Link header with the URI of the Compact resource. The client then performs a GET request on the Compact URI to retrieve the Compact resource.

Clients might instead use the HTTP Prefer header to get the Compact resource in a single HTTP request. If the client is confident that the resource has a preview, it makes an HTTP GET request on the resource URI using the return=representation preference [RFC7240] and an include parameter [LDP] asking for the Compact resource to be included in the response. The provider responds with a minimal representation of the resource and the Compact resource in the HTTP response body.

GET /bugs/324/screenshot HTTP/1.1
Host: example.com
Accept: application/x-oslc-compact+xml

HEAD /bugs/324/screenshot HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Length: 45789
Content-Type: image/png
ETag: "678609cdee68e0fb8aea5f252b84a511"
Link: <http://example.com/bugs/324/screenshot?compact>; rel="http://open-services.net/ns/core#Compact"

GET /bugs/324/screenshot?compact HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Length: 192
Content-Type: application/json; charset=UTF-8
ETag: "3bf6fbc90e11b3c2cc30acb534b452ea"
Vary: Accept,Accept-Language

{
    "title": "Screenshot of the problem",
    "shortTitle": "screenshot.png",
    "smallPreview": {
        "document": "http://example.com/bugs/324/screenshot?preview=small"
    }
}

POST /bugs HTTP/1.1
Host: example.com
Content-Length: 153
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .

<>      a              <http://example.com/ns#Bug> ;
        dcterms:title  "Something went wrong" .

HTTP/1.1 201 Created
Content-Length: 0
Link: <http://example.com/bugs/478?compact>; rel="http://open-services.net/ns/core#Compact"; anchor="http://example.com/bugs/478"
Location: http://example.com/bugs/478

GET /bugs/324 HTTP/1.1
Host: example.com
Accept: application/json
Prefer: return=representation; include="http://open-services.net/ns/core#PreferCompact"

HTTP/1.1 200 OK
Content-Length: 315
Content-Type: application/json; charset=UTF-8
ETag: "f9d76afe5fbed1655c5768906db8958a"
Preference-Applied: return=representation
Vary: Accept,Accept-Language,Prefer

{
    "compact": {
        "title": "324: Need a fix <em>NOW</em>",
        "icon": "http://example.com/icons/defect.jpg",
        "largePreview": {
            "document": "http://example.com/bugs/324?preview=large",
            "hintHeight": "250px",
            "hintWidth": "400px"
        }
    }
}

HTTP/1.1 200 OK
Content-Length: 788
Content-Type: application/json; charset=UTF-8
ETag: "d53d19be87fa9c61043c70bd91413dab"
Preference-Applied: return=representation
Vary: Accept,Accept-Language,Prefer

{
    "@id": "http://example.com/bugs/324",
    "@type": "http://example.com/ns#Bug",
    "@context": "https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/contexts/preview.jsonld",
    "compact": {
        "@id": "http://example.com/bugs/324?compact",
        "@type": "http://open-services.net/ns/core#Compact",
        "title": "324: Need a fix <em>NOW</em>",
        "shortTitle": "324",
        "icon": "http://example.com/icons/defect.jpg",
        "iconTitle": "Defect",
        "iconAltLabel": "Defect",
        "largePreview": {
            "document": "http://example.com/bugs/324?preview=large",
            "hintHeight": "250px",
            "hintWidth": "400px"
        },
        "smallPreview": {
            "document": "http://example.com/bugs/324?preview=small"
        }
    }
}

3.2 Displaying Previews

This section is non-normative.

When displaying a preview inside another HTML-based presentation, clients create an iframe element, setting its src attribute to the preview's document URI. Previews can contain HTML, stylesheets, and scripts and might not render properly outside of an iframe. Using the iframe element also sandboxes the preview, avoiding cross-site scripting vulnerabilities.

Typically, the server does not include the icon or title in the preview itself. The client can display these as needed. In Fig. 2 Preview iframe, the preview document is the content inside the yellow, dashed lines.

Resources can have both a small and large preview, and clients can choose which to display. Some clients display the small preview initially and let users expand to the large preview using a button or "Show more" link.

The Compact resource can include oslc:hintHeight and oslc:hintWidth properties for each preview. Values for oslc:hintWidth and oslc:hintHeight are expressed in length units specified in [CSS21].

Servers can also request dynamic resizing for small and large previews. The communication of dynamic 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. Dynamic resizing will not work inside browsers that do not support postMessage.

A resize message begins with oslc-resize: followed by a JSON object describing the dimensions using properties oslc:hintHeight and oslc:hintWidth.

For example, the following message requests that the preview be resized to height of 277 pixels and a width of 400 pixels.

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

The following JavaScript example sends a resize request to the parent window.

var size = {
    'oslc:hintHeight': '277px',
    'oslc:hintWidth': '400px'
};

if (window.postMessage && window.parent)  {
    window.parent.postMessage('oslc-resize:' + JSON.stringify(size), "*");
}

Clients can ignore a server's size hints and use other values. For instance, a client might choose another size if the preview is too large for the window.

4.1 Navigation to the target resource

This section is non-normative.

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.

4.2 Default way to display the link to the target resource

This section is non-normative.

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 Client). 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, Clients 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.

4.3 Using the Compact representation title, short title, and icon

This section is non-normative.

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), possibly chosen from a set with different sizes (oslc:iconSrcSet), all of which may be based on the current state of the target resource. If this becomes known to the Client, the client 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.

Clients should not fetch Compact representations when there is perfectly usable default display information available. When designing a Client 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).

Clients should be wary of material obtained from non-trusted sources; in particular, the Client should check that the dcterms:title and oslc:shortTitle property values do not contain HTML markup beyond the specified set of simple elements.

4.4 Preview sizing

This section is non-normative.

When the resource does not supply preferred sizing for a preview, the Client should default to a reasonably generous value. The default value a Client uses may be different for different window and screen sizes.

4.5 Displaying a small preview

This section is non-normative.

If a user mouses or hovers over a displayed link, the Client should determine whether the target resource has a small preview (oslc:smallPreview). If it does, the Client should present the small preview document in a hovering widget. Since preview documents may contain arbitrary content, including HTML and scripts, Client must use iframes if embedding the preview document inside another HTML-based presentation.

The Client 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 trade-off to increase overall system load just to decrease UI latency for low probability eventualities. Clients may wish to utilize lazy loading techniques to only access preview dialogs that users actually view, and can cache those dialogs for subsequent uses if needed to improve performance.

4.6 Displaying a large preview

This section is non-normative.

If the user then gestures that they want to see a bit more of the resource, the Client should determine whether the target resource has a large preview (oslc:largePreview). If it does, the Client 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, Clients must use iframes if embedding the preview document inside another HTML-based presentation.