- From: Tobie Langel <tobie@fb.com>
- Date: Wed, 26 Sep 2012 17:58:33 +0000
- To: Alex Russell <slightlyoff@google.com>, Greg Billock <gbillock@google.com>
- CC: WebIntents <public-web-intents@w3.org>, Brett van Zuiden <brettcvz@filepicker.io>, Jungkee Song <jungkee.song@samsung.com>, "Paul Kinlan" <paulkinlan@google.com>, Norifumi Kikkawa <Norifumi.Kikkawa@jp.sony.com>, "public-device-apis@w3.org" <public-device-apis@w3.org>, "Frederick.Hirsch@nokia.com" <Frederick.Hirsch@nokia.com>
LGTM. --tobie On 9/26/12 7:55 PM, "Alex Russell" <slightlyoff@google.com> wrote: >+1! >On Sep 26, 2012 6:44 PM, "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. >>>> >>> >> > > >
Received on Wednesday, 26 September 2012 17:59:12 UTC