first run API complexity

[Myk Melez]

While reviewing the patch implementing first run pages, I became concerned about the complexity of the API for specifying the content that should appear on the page.

It feels like we're providing too many options. And although they're mutually exclusive, they are specified via different attributes, which obscures that characteristic.

I recommend we reduce the number of options for specifying first run content to two--html and url--which can then handle the text and image URL cases (text parses as HTML, and image URLs can be presented the same way other URLs are).

Regarding the issue of mutual exclusivity, I realize we've already built interfaces that have this issue with html and url options, so this is broader than just the first run API. My recommendation would be to overload a single attribute named content so it can handle input of both primary types (HTML, URL).

One way to do this would be to heuristically recognize string values that are URLs, so both types of values are specified as strings, but "This is some <b>content</b>!" gets parsed as HTML, while "http://example.com/this/is/a/url" gets loaded as a URL.

Another would be to distinguish between HTML content and URLs by specifying URLs via a duck-typable object notation like { spec: "http://example.com/this/is/a/url" }.

(A third option, for interfaces that take actual JS instead of JSON, is a URL constructor by which jetpacks could create a URL object, i.e. new URL("http://example.com/this/is/a/url"), but we'd still need to solve the JSON case.)

-myk

[Drew]

> I recommend we reduce the number of options for specifying first run
> content to two--html and url--which can then handle the text and image
> URL cases (text parses as HTML, and image URLs can be presented the same
> way other URLs are).

Sounds good.

> One way to do this would be to heuristically recognize string values
> that are URLs, so both types of values are specified as strings, but

> /"This is some <b>content</b>!"/ gets parsed as HTML, while
> /"http://example.com/this/is/a/url"/ gets loaded as a URL.

Good too, and Aza mentions it in the JEP, but one thing is that if I see
there's a property called "content", it's not immediately clear what
goes there, while "html" and "url" are obvious (and in step with the
other APIs, as you mention). It's true that two properties masks their
mutual exclusivity, but a single property masks types...

Which do you think people are more likely to find confusing? Which is
better for new developers? Either way, you would need to read the docs
or see example code to know for sure what properties there are and how
they're used. If I saw example code with content, I might try plugging
in a URL to see if it worked. If I saw code with only html, though,
it's probably less likely that I'd try url out of the blue.

I don't much like your latter two proposals. :)

What about the command property? Aza said he wanted a way for people to
do arbitrary things on first-run, and it seemed like an OK way to expose
that. If we go with a single content property, another possibility is
to fold the command into that; the "firstRun" manifest property would
then simply be a string or function. You couldn't both show a first-run
page and do something arbitrary, though, and it'd be really unclear what
values firstRun takes.

Drew

On 12/15/09 1:49 PM, Myk Melez wrote:
> While reviewing the patch implementing first run pages

> <https://bugzilla.mozilla.org/show_bug.cgi?id=532860>, I became

> concerned about the complexity of the API for specifying the content
> that should appear on the page.
>
> It feels like we're providing too many options. And although they're
> mutually exclusive, they are specified via different attributes, which
> obscures that characteristic.
>
> I recommend we reduce the number of options for specifying first run
> content to two--html and url--which can then handle the text and image
> URL cases (text parses as HTML, and image URLs can be presented the same
> way other URLs are).
>
> Regarding the issue of mutual exclusivity, I realize we've already built
> interfaces that have this issue with html and url options, so this is
> broader than just the first run API. My recommendation would be to
> overload a single attribute named content so it can handle input of both
> primary types (HTML, URL).
>
> One way to do this would be to heuristically recognize string values
> that are URLs, so both types of values are specified as strings, but

> /"This is some <b>content</b>!"/ gets parsed as HTML, while
> /"http://example.com/this/is/a/url"/ gets loaded as a URL.

>
> Another would be to distinguish between HTML content and URLs by
> specifying URLs via a duck-typable object notation like { spec:
> "http://example.com/this/is/a/url" }.
>
> (A third option, for interfaces that take actual JS instead of JSON, is
> a URL constructor by which jetpacks could create a URL object, i.e. new
> URL("http://example.com/this/is/a/url"), but we'd still need to solve
> the JSON case.)
>
> -myk
>

> --
>
> You received this message because you are subscribed to the Google
> Groups "mozilla-labs-jetpack" group.
> To post to this group, send email to mozilla-la...@googlegroups.com.
> To unsubscribe from this group, send email to
> mozilla-labs-jet...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/mozilla-labs-jetpack?hl=en.

[Myk Melez]

On 12/15/2009 05:24 PM, Drew wrote:
> What about the command property? Aza said he wanted a way for people to
> do arbitrary things on first-run, and it seemed like an OK way to expose
> that. If we go with a single content property, another possibility is
> to fold the command into that;

Regardless of whether we go with content or stick with html and url for
specifying the content of the first run page, I think it makes sense to
separately allow jetpacks to specify a callback function that we call.
I'd call it callback, though, rather than command, for consistency with
the use of that term in other JavaScript APIs.

-myk

[Myk Melez]

On 12/15/2009 05:24 PM, Drew wrote:

Good too, and Aza mentions it in the JEP, but one thing is that if I see 
there's a property called "content", it's not immediately clear what 
goes there, while "html" and "url" are obvious (and in step with the 
other APIs, as you mention).  It's true that two properties masks their 
mutual exclusivity, but a single property masks types...
  

Indeed, there's some masking in both cases, although I'm not sure html and url are that obvious (they beg the question of how the HTML and URL they contain are to be used), and datatype masking seems more common in parameter names.

I suppose I prefer content because it employs type polymorphism, which I've found effective in other interfaces (like some of the JS modules), and also because it describes the semantics of its value rather than its type, as is the case with html and url.

-myk

[Drew]

> <https://wiki.mozilla.org/Labs/JS_Modules>), and also because it

> describes the semantics of its value rather than its type, as is the
> case with html and url.

Yeah, that's the right distinction to make. I'll use content in the new
patch.

> The only problem with this is that manifests for packaged jetpacks will
> be specified via JSON, which doesn't accept embedded functions.

Hmm. I think we should go with callback for now (for 0.7) and cross
that bridge when we get to it.

Drew

On 12/16/09 1:00 AM, Myk Melez wrote:
> On 12/15/2009 05:24 PM, Drew wrote:
>> Good too, and Aza mentions it in the JEP, but one thing is that if I see
>> there's a property called "content", it's not immediately clear what
>> goes there, while "html" and "url" are obvious (and in step with the
>> other APIs, as you mention). It's true that two properties masks their
>> mutual exclusivity, but a single property masks types...
>>
> Indeed, there's some masking in both cases, although I'm not sure html
> and url are that obvious (they beg the question of how the HTML and URL
> they contain are to be used), and datatype masking seems more common in
> parameter names.
>
> I suppose I prefer content because it employs type polymorphism, which
> I've found effective in other interfaces (like some of the JS modules

> <https://wiki.mozilla.org/Labs/JS_Modules>), and also because it

[Aza]

I also worry about hiding the potential accepted values by using content instead of html/url. On the other hand, if we are consistent about that usage across all APIs than I believe that authors will quickly adapt and learn that they can use html, urls, and other polymorphic goodness.

In my original proposal, instead of putting the callback in the manifest, it was as a call to jetpack.onInstall()

-- aza | ɐzɐ --