Document the activeTab extension permission.

Document the activeTab extension permission.


BUG=141862
Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=157945

[not at google - send to devlin, 2012-08-24 09:11:14]

First pass. Written on a Friday evening so probably not very good.

[Aaron Boodman, 2012-08-24 14:09:25]

Some thoughts. Thanks for taking the first swing. Easier to edit than create

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
File chrome/common/extensions/docs/static/activeTab.html (right):

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/static/activeTab.html:4: The
<code>activeTab</code> permission is for extensions that perform an action on a
tab in response to the user. For example, an extension with a browser action
that changes the formatting of the current page when clicked, or has a context
menu which acts on the word that was clicked on.
More direct:

The _activeTab_ permission allows extensions to access the active tab in
response to user gestures like clicking an extension button or context menu
item.

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/static/activeTab.html:8: Traditionally such
extensions would need to request both the <code>&lt;all_urls&gt;</code>
permission and the <code>tabs</code> permission, requiring a scary install
warning. With the <code>activeTab</code> permission, none of that is necessary.
Maybe you could turn this into a story/example:

Many extensions only need access to a page in response to a user gesture on the
extension. For example, consider a web clipping extension that has a browser
action and context menu item. The extension doesn't need to run automatically on
all pages, it only needs to run when one of its UI surfaces is acted upon.

Without activeTab ...

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/static/activeTab.html:16: The following qualify as
invocations:
Since this is likely to rot, let's weaken it slightly:

The activeTab permission is activated whenever a piece of extension UI is acted
upon by a user. At the time of writing, examples of such UI include:

...

But this list will grow over time as more types of extension  UI are added.

[not at google - send to devlin, 2012-08-27 04:45:49]

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
File chrome/common/extensions/docs/static/activeTab.html (right):

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/static/activeTab.html:4: The
<code>activeTab</code> permission is for extensions that perform an action on a
tab in response to the user. For example, an extension with a browser action
that changes the formatting of the current page when clicked, or has a context
menu which acts on the word that was clicked on.
On 2012/08/24 14:09:25, Aaron Boodman wrote:
> More direct:
> 
> The _activeTab_ permission allows extensions to access the active tab in
> response to user gestures like clicking an extension button or context menu
> item.

Done.

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/static/activeTab.html:8: Traditionally such
extensions would need to request both the <code>&lt;all_urls&gt;</code>
permission and the <code>tabs</code> permission, requiring a scary install
warning. With the <code>activeTab</code> permission, none of that is necessary.
On 2012/08/24 14:09:25, Aaron Boodman wrote:
> Maybe you could turn this into a story/example:
> 
> Many extensions only need access to a page in response to a user gesture on
the
> extension. For example, consider a web clipping extension that has a browser
> action and context menu item. The extension doesn't need to run automatically
on
> all pages, it only needs to run when one of its UI surfaces is acted upon.
> 
> Without activeTab ...

Done.

http://codereview.chromium.org/10874057/diff/1/chrome/common/extensions/docs/...
chrome/common/extensions/docs/static/activeTab.html:16: The following qualify as
invocations:
On 2012/08/24 14:09:25, Aaron Boodman wrote:
> Since this is likely to rot, let's weaken it slightly:
> 
> The activeTab permission is activated whenever a piece of extension UI is
acted
> upon by a user. At the time of writing, examples of such UI include:
> 
> ...
> 
> But this list will grow over time as more types of extension  UI are added.

Done.

Is it "extension UI are..." or "extension UIs are..."?

[Aaron Boodman, 2012-08-30 05:27:12]

This is too hard. Took it to Google Docs:
https://docs.google.com/a/google.com/document/d/1c7k7b9iZWBOAgTy9z2tjnpW5NU27...

[Aaron Boodman, 2012-09-11 22:51:28]

Ping?

[not at google - send to devlin, 2012-09-11 23:00:53]

I was going to ping you.

Ok I will merge in the docs changes today.

[mkearney1, 2012-09-12 17:02:37]

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
File chrome/common/extensions/docs/server2/templates/articles/activeTab.html
(right):

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
chrome/common/extensions/docs/server2/templates/articles/activeTab.html:1:
<h1>The activeTab permission</h1>
General comment: I like the heading style in the original doc but I can
understand that it might seem too much for the content within-- it might be good
to have a couple of headings like:

'What activeTab allows'

'Invoking activeTab'

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
chrome/common/extensions/docs/server2/templates/articles/activeTab.html:4: The
<code>activeTab</code> permission allows extensions to access the active tab in
response to user gestures like clicking an <a
href="browserAction.html">extension button</a> or <a
href="contextMenus.html">context menu item</a>.
I kind of like parts of the original active tab intro better, so i am going to
try a little combination here:

The activeTab permission allows an extension to access the currently active tab
in response to user gestures like ...

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
chrome/common/extensions/docs/server2/templates/articles/activeTab.html:12:
Without <code>activeTab</code> the extension would need to request both the
<code>&lt;all_urls&gt;</code> and <code>tabs</code> permissions, showing a scary
warning on installation. With <code>activeTab</code> none of that will be
necessary.

Does a warning get displayed to the user at any time, say when the user first
clicks on the extension UI? This sort of implies there is no message, but surely
there is some sort of permission granting.

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
chrome/common/extensions/docs/server2/templates/articles/activeTab.html:12:
Without <code>activeTab</code> the extension would need to request both the
<code>&lt;all_urls&gt;</code> and <code>tabs</code> permissions, showing a scary
warning on installation. With <code>activeTab</code> none of that will be
necessary.
Nit, commas after 'Without activeTab' and 'With activeTab'.

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
chrome/common/extensions/docs/server2/templates/articles/activeTab.html:28:
</ul>
I'm a little bit curious about the last item here - executing a command
configured for an extension. Could we have an example of this?

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
File chrome/common/extensions/docs/server2/templates/articles/manifest.html
(right):

http://chromiumcodereview.appspot.com/10874057/diff/11/chrome/common/extensio...
chrome/common/extensions/docs/server2/templates/articles/manifest.html:479: <a
href="activeTab.html">activeTab</a> specification.
This is kind of vague. What about:

Requests permission to access the <a href="activeTab.html">active tab</a> in
response to user gestures.

[Aaron Boodman, 2012-09-16 01:02:25]

Meggin, you reviewed an old patchset. (You can see in the blue box it was
created two weeks ago)

[Aaron Boodman, 2012-09-16 01:02:35]

On 2012/09/16 01:02:25, Aaron Boodman wrote:
> Meggin, you reviewed an old patchset. (You can see in the blue box it was
> created two weeks ago)

Nearly three weeks actually.

[not at google - send to devlin, 2012-09-20 04:50:37]

Updated from content in the docs. PTAL.

[Aaron Boodman, 2012-09-21 03:10:59]

Rietveld isn't showing me the images. Can you post them somewhere?

http://codereview.chromium.org/10874057/diff/17001/chrome/common/extensions/d...
File chrome/common/extensions/docs/templates/articles/activeTab.html (right):

http://codereview.chromium.org/10874057/diff/17001/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/articles/activeTab.html:21:
<h2>Manifest</h2>
Can you make this an actual working example, like the one that I did in the
Google Doc?

Showing just the manifest is silly when it isn't enough to actually use the API.
I think a (slightly) more complete example gets the point of the API across
better.

http://codereview.chromium.org/10874057/diff/17001/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/articles/activeTab.html:36:
<h2>Motivation</h2>
I updated this section slightly in the Google Doc (sorry, I didn't realize you'd
sent this out). Can you update from there?

[not at google - send to devlin, 2012-09-21 05:08:13]

http://codereview.chromium.org/10874057/diff/17001/chrome/common/extensions/d...
File chrome/common/extensions/docs/templates/articles/activeTab.html (right):

http://codereview.chromium.org/10874057/diff/17001/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/articles/activeTab.html:21:
<h2>Manifest</h2>
On 2012/09/21 03:10:59, Aaron Boodman wrote:
> Can you make this an actual working example, like the one that I did in the
> Google Doc?
> 
> Showing just the manifest is silly when it isn't enough to actually use the
API.
> I think a (slightly) more complete example gets the point of the API across
> better.

I didn't see an example in the Google doc, but I see you've added one.

http://codereview.chromium.org/10874057/diff/17001/chrome/common/extensions/d...
chrome/common/extensions/docs/templates/articles/activeTab.html:36:
<h2>Motivation</h2>
On 2012/09/21 03:10:59, Aaron Boodman wrote:
> I updated this section slightly in the Google Doc (sorry, I didn't realize
you'd
> sent this out). Can you update from there?

Done.

[Aaron Boodman, 2012-09-21 06:05:50]

Coooool. Last nits?

- It tie things together nicely if the images were screen caps of installing the
"Page redder" extension from the sample (and I know this is pushing things, but
if there was an icon -- here's a paintbucket:
http://thenounproject.com/noun/paint-can/#icon-No1013).

- I can see ... something ... through the semitransparency of the dialog. Is it
possible somehow to arrange things such that you don't see that?

- How about a horizontal layout, like this: http://i.imgur.com/ZMSD9.png. Hacky
HTML at bottom of this comment.

- Can you make it so that the buttons are highlighted the same way in both
screen caps?

====

<table style="
    margin-top: 1em;
">
<tbody><tr>
<td valign="middle" style="
    color: #767676;
">Without activeTab:<img src="/stable/static/images/active-tab-before.png"
width="300" style="
    display: block;
"></td>
<td valign="top" style="padding-left:1em;
    color: #767676;
">With activeTab:<img src="/stable/static/images/active-tab-after.png"
width="300" style="
    display: block;
"></td></tr>
</tbody></table>

[not at google - send to devlin, 2012-09-21 06:39:38]

all done, i've updated the demo.

[Aaron Boodman, 2012-09-21 07:45:05]

lgtm w/ nits

- Add 1em spacing between table containing images and paragraph above.

- Images look better at width 334 for left one and 265 for right.

- I think it looks better without the <code> around the 'activeTab' in the
blurbs on top of each image

- It would be good if paintbucket was transparent :).

[not at google - send to devlin, 2012-09-21 07:59:59]

> - Add 1em spacing between table containing images and paragraph above.

done

> 
> - Images look better at width 334 for left one and 265 for right.

done

> 
> - I think it looks better without the <code> around the 'activeTab' in the
> blurbs on top of each image

done


> - It would be good if paintbucket was transparent :).

agreed, but, then I'd need to find an image editor and retake the screenshots.
I'll do it later...