Document the activeTab extension permission.

chrome/common/extensions/docs/templates/articles/activeTab.html

Index: chrome/common/extensions/docs/templates/articles/activeTab.html
diff --git a/chrome/common/extensions/docs/templates/articles/activeTab.html b/chrome/common/extensions/docs/templates/articles/activeTab.html
new file mode 100644
index 0000000000000000000000000000000000000000..da516c618dd655d0426e67a0b9cf9fa843fa7477
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/articles/activeTab.html
@@ -0,0 +1,71 @@
+<h1>The activeTab permission</h1>
+
+<p>
+The <code>activeTab</code> permission gives an extension temporary access to the currently active tab when the user <em>invokes</em> the extension - for example by clicking its <a href="browserAction.html">browser action</a>. Access to the tab lasts until it is navigated or closed.
+</p>
+
+<p>
+The main benefit of the <code>activeTab</code> permission is that it displays <em>no warning message</em> during installation:
+
+<table>
+  <tr>
+    <td>Without <code>activeTab</code>:</td>
+    <td><img src="{{static}}/images/active-tab-before.png"></td>
+  </tr>
+  <tr>
+    <td>With <code>activeTab</code>:</td>
+    <td><img src="{{static}}/images/active-tab-after.png"></td>
+  </tr>
+</table>
+
+<h2>Manifest</h2>

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

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.

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

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

+
+<p>
+Declare <code>activeTab</code> in your extension's <a href="manifest.html">manifest</a> like this:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  "permissions": [
+    <b>"activeTab"</b>
+  ],
+  ...
+}</pre>
+
+<h2>Motivation</h2>

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

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]

Done.

+
+<p>
+Consider a web clipping extension that has a <a href="browserAction.html">browser action</a> and <a href="contextMenus.html">context menu item</a>. This extension may only really need to access tabs when its browser action is clicked, or when its context menu item is executed.
+</p>
+
+<p>
+Without <code>activeTab</code>, this extension would need to request full, persistent access to every web site, just so that it could do its work if it happened to be called upon by the user. This is a very large amount of privilege for an extension to have, especially when it doesn’t really need it. And if the extension is ever compromised by an attacker, the attacker gets all the privilege the extension had.
+</p>
+
+<p>
+In contrast, an extension with the <code>activeTab</code> permission only obtains access to a tab in response to an explicit user gesture. If the extension is compromised the attacker would need to wait for the user to invoke the extension before obtaining access. And that access only lasts until the tab is navigated or closed.
+</p>
+
+<h2>What activeTab allows</h2>
+
+<p>
+While the <code>activeTab</code> permission is enabled for a tab, an extension can:
+<ul>
+  <li>Call <code><a href="tabs.html#method-executeScript">executeScript()</a></code> on that tab.
+  <li>Get the URL, title, and favicon for that tab via an API that returns a <code><a href="tabs.html#type-Tab">Tab</a></code> object (essentially, <code>activeTab</code> grants the <code><a href="tabs.html#manifest">tabs</a></code> permission temporarily).
+</ul>
+</p>
+
+<h2>Invoking activeTab</h2>
+
+<p>
+The following user gestures enable <code>activeTab</code>:
+<ul>
+  <li>Executing a browser action
+  <li>Executing a page action
+  <li>Executing a context menu item
+  <li>Executing a keyboard shortcut from the commands API
+  <li>Accepting a suggestion from the omnibox API
+</ul>
+</p>