W3C home > Mailing lists > Public > public-device-apis@w3.org > September 2012

Re: Content of URL picked by Intent

From: Norifumi Kikkawa <Norifumi.Kikkawa@jp.sony.com>
Date: Thu, 27 Sep 2012 14:27:33 +0900
To: Greg Billock <gbillock@google.com>
Cc: Alex Russell <slightlyoff@google.com>, Brett van Zuiden <brettcvz@filepicker.io>, Tobie Langel <tobie@fb.com>, Jungkee Song <jungkee.song@samsung.com>, Paul Kinlan <paulkinlan@google.com>, WebIntents <public-web-intents@w3.org>, "public-device-apis@w3.org" <public-device-apis@w3.org>, "Frederick.Hirsch@nokia.com" <Frederick.Hirsch@nokia.com>
Message-Id: <20120927142732.5BE3.846B5FC5@jp.sony.com>
Looks good to me.

Kikkawa

On Thu, 27 Sep 2012 02:44:26 +0900
Greg Billock <gbillock@google.com> wrote:

> I was just talking to Alex at the virtual water cooler, and here's a
> proposal I think solves the issues we are wrestling with in an elegant
> way.
> 
> 1. All interchange through MIME type specifiers is done with array
> types. That is, if I say "image/png" I will pass [ { ... }, { ... } ].
> Formally, that's sequence<MimeTypeIntentData>. This goes for wildcards
> as well, so "image/*" or "video/*".
> 
> 2. We introduce a MIME type parameter indicating that the array will
> contain a single value. So if a service will only produce a single
> value, it can say "image/*;single=true". This explicitly marks a
> client or service as only handling a single value. The harm to be
> avoided is the mismatch of a service or client that will only handle a
> single value, and the other party producing multiple values, which are
> then ignored. For example, a "save" intent service which only saves
> the first value, and then returns SUCCESS, would be very unexpected to
> the client which sent it eight things to save and received that
> SUCCESS response.
> 
> This approach achieves the following goals:
> 
> a. Keeps the types consistent across all uses -- that makes it easy to
> explain and learn.
> b. Puts the burden of annotation on the service, not the client. If
> the client sends "image/*" with one value, then obviously a service
> that accepts multiple values can handle that. If a client does a
> "pick":"image/*" and the service returns multiple values, the client
> may only use the first one, but that is out of the control of the
> service. The user can learn the capability of the tool and accomodate
> that.
> c. Respect the MIME type semantics. The single=true parameter
> qualifies the type for the service for no surprises, but does not
> change the interchange format (an array).
> 
> The only worry I have remaining is that for single values, developers
> may be tempted to use direct object indexing. But I think maintaining
> type consistency is really important, and there are plenty of other
> platform APIs that use a similar convention, so I think this is a
> soluble problem.
> 
> Please speak up if there are any objections to this -- I'm planning on
> modifying the web intents wiki document to reflect this [1], but if
> the TF desires, we can draw up a more formal document about this.
> 
> [1] http://www.w3.org/wiki/WebIntents/MIME_Types
> 
> 
> On Tue, Sep 25, 2012 at 9:30 AM, Alex Russell <slightlyoff@google.com> wrote:
> > Sorry for the slow response here. Inline:
> >
> >
> > On Thu, Sep 20, 2012 at 7:34 PM, Brett van Zuiden <brettcvz@filepicker.io>
> > wrote:
> >>
> >> Hi there - I'm typically just an observer here, but felt like this was an
> >> area where we can share a lot of what we have learned.
> >>
> >> I'm one of the founders of Filepicker.io, and our first product has strong
> >> parallels to web intents. We've had thousands of developers use our product
> >> over the last handful of months, so have some real-life experience in
> >> interacting with developers around the api.
> >>
> >> Our initial approach was to treat multiple as a flag to the getFile call
> >> (our equivalent of the "pick" intent). If multiple wasn't set, we would
> >> return the url and data as an object, if it was we would return an array.
> >> I'm convinced this is the wrong way to do multiple, and that the right way
> >> is to have an explicit pickMultiple call.
> >>
> >> Rationale:
> >> * a {"multiple": true} flag has poor discoverability. I'm fairly happy
> >> with our documentation, but we still get on average one question a week from
> >> people asking if they can/how to select multiple files
> >
> >
> > Agreed.
> >
> >>
> >> * The use cases for selecting multiple files are fairly distinct from
> >> those asking for single files. We initially thought the flag would help
> >> people switch between the two - in practice, this rarely happens.
> >> * We've found that the user interface for selecting multiple files should
> >> be reasonably distinct from selecting a single file. For instance, the
> >> presence of a "shelf" where selected files are queued before being submitted
> >> * Making single-file pick an array creates a significant boiler-plate
> >> issue where every implementation needs the same blob of code. It also raises
> >> questions about edge cases: what happens if the user closes without
> >> selecting any file? Can an empty array ever be returned for a single-file
> >> pick? Will the length of the array always be identically 1?
> >
> >
> > I'm sympathetic to this, but the "boilerplate" is also what makes you
> > automatically able to handle a SEND_MULTIPLE style of intent. The default,
> > correct way to write a receiver in this world is also the way to implement
> > both single and multiple item receipt. It's surely less overhead than
> > writing the same thing in the SEND_MULTIPLE version and then having a
> > single-item handler as well, isn't it?
> >
> >>
> >> Happy to provide more insights into what we've learned from our customers.
> >> We've recently spec'd out the next version of our API and so have aggregated
> >> quite a bit of experience into that document.
> >>
> >> - Brett van Zuiden
> >> Founder | Filepicker.io
> >>
> >>
> >> On Thu, Sep 20, 2012 at 1:56 PM, Greg Billock <gbillock@google.com> wrote:
> >>>
> >>> On Thu, Sep 20, 2012 at 10:43 AM, Tobie Langel <tobie@fb..com> wrote:
> >>> > On 9/20/12 7:27 PM, "Greg Billock" <gbillock@google.com> wrote:
> >>> >
> >>> >>The discomfort I'm estimating as the most acute
> >>> >>is client developers wanting to get started. I'd like them to have as
> >>> >>few problems as possible using the API, and so I'd like to make their
> >>> >>path as clear as possible.
> >>> >
> >>> > That's actually easily mitigated by providing example code developers
> >>> > can
> >>> > copy. It also an issue during a relatively short period of time and is
> >>> > relevant to that particular API only. It's also very possible that the
> >>> > developers will be familiar with the pattern having seen it elsewhere.
> >>> >
> >>> > However, inconsistencies in the platform hurt the productivity of
> >>> > beginner, intermediate and seasoned developers alike. Not only does it
> >>> > hurt developers when they are using that particular API, but it also
> >>> > hurts
> >>> > them **every time they will use any other API where consistency with
> >>> > that
> >>> > particular API would have been expected.** In other words, coming up a
> >>> > custom solution here diminishes the quality of the platform as a
> >>> > whole..
> >>>
> >>> I completely agree, and that's a major source of discomfort I'd dearly
> >>> like to avoid. :-) If we can document around early pitfalls and give
> >>> developers touching a lot of the platform a consistent experience,
> >>> that's definitely where the balance of intuition ends up lying. I
> >>> definitely think using arrays for multiple MIME values is the way to
> >>> go, and accords well with the rest of the platform. The question is
> >>> how to best indicate that. Always using them is a good approach that
> >>> will work fine.
> >>>
> >>
> >

---------------------------------------------
 Norifumi Kikkawa <Norifumi.Kikkawa@jp.sony.com>
  Section 1
  Network Technology Dept.
  Information Technology Development Division
  System & Software Technology Platfotm 
  Sony Corporation
 (TEL) +81 50 3750 3953 
----------------------------------------------- 
Received on Thursday, 27 September 2012 05:28:08 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 27 September 2012 05:28:09 GMT