[oslc-core] Draft: UI Preview with JSON-LD

[Martin P Pain]

A few thoughts on the UI Preview page. (Most of these probably don't 
relate to things that have changed, but came from either reading that 
draft or from our experience implementing UI previews):

1. There is now (which I do not remember before) a distinction between 
small preview being a "hovering widget" and a large preview "permits 
further user interaction". Has thought been given to (a) providers who 
don't want to expose a small preview but want to skip straight to the 
one with user interaction, or (b) v2 providers who only provided a small 
preview but which contains user interaction. 

   I would suggest: 

   (a) if only a large preview is available, the consumer SHOULD display 
it 
   when they would otherwise display a small preview, but they MAY display 

   it in the hovering widget and only more it to a static widget when the 
   user gestures for this, or they MAY skip straight to using the static 
   widget - whichever is more appropriate in their interface. If they do 
   the former, they SHOULD NOT lose any the state that the user has 
entered 
   in the preview when switching modes (but in some cases this may be 
   unavoidable). 

   (b) If a provider wants to have only a single preview that is suitable 
   for both hover and static widgets, then they SHOULD set both the 
   smallPreview and largePreview properties to the same URI. Consumers 
   SHOULD detect this case and not lose any the state that the user has 
   entered in the preview when switching modes (i.e. not reloading the 
   preview, just changing its parent widget - if possible). 

2. UI preview titles (also applied to dialogs) - it would be useful if 
the spec could define who is responsible for displaying the title - is 
it the consumer, so that they can ensure there is a link to the target 
resource, or the provider, so they can decorate it with whatever icons 
or other indicators that may be useful to the user (and that may be used 
elsewhere in its UIs) and because they are rendering the rest of the 
preview? In the integration we worked on, both sides assumed it was 
their responsibility to include the title, so it got displayed twice! 

Similarly, it would be good to explicitly define that any border to be 
displayed should be rendered by the consumer not the provider (but I 
believe this is more obvious that the point about titles). 

3. The line "The oslc:Compact resource must have an “@id” whose value is 
the URI of the target resource." should probably read "MUST". 

4. Does the sentance "oslc:Preview MUST be a child of an 
oslc:smallPreview or oslc:largePreview element..." mean "The value of 
the oslc:smallPreview and oslc:largePreview elements, if present, MUST 
be of type oslc:Preview..."? It's unclear if there are any other 
implications/requirements here. If not, I'd suggest changing to this 
wording if you agree it's clearer. 

Martin




From:   Samuel Padgett <spadgett at us.ibm.com>
To:     oslc-core at open-services.net, 
Date:   17/10/2013 19:19
Subject:        [oslc-core] Draft: UI Preview with JSON-LD
Sent by:        "Oslc-Core" <oslc-core-bounces at open-services.net>



I've updated the UI Preview V3 draft [1] to use JSON-LD for the Compact 
resource instead of the pseudo-RDF/XML format we had before. The thinking 
is UI previews are usually displayed in a browser, and JSON is easier to 
handle there. Comments and feedback welcome.

A few things to note:

- The current draft removes the 2.0 XML format entirely, although it does 
say providers may continue to support it for backwards compatibility.
- It also requires the compacted document form [2] of JSON-LD so that the 
document is easy to parse from the browser. Alternatives are allowing any 
valid JSON-LD or just using a simple, plain JSON format instead.

[1] http://open-services.net/wiki/core/User-Interface-Previews-3.0/
[2] http://www.w3.org/TR/json-ld/#compacted-document-form

-- 
Samuel Padgett | IBM Rational | spadgett at us.ibm.com
Eclipse Lyo: Enabling tool integration with OSLC
_______________________________________________
Oslc-Core mailing list
Oslc-Core at open-services.net
http://open-services.net/mailman/listinfo/oslc-core_open-services.net


Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-core_open-services.net/attachments/20131021/04b0c1e7/attachment-0003.html>