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

   1 <style>
   2   #active-tab-images {
   3     margin-top: 1em;
   4   }
   5   #active-tab-images tr {
   6     vertical-align: top;
   7   }
   8   #active-tab-images .spacing {
   9     width: 1em;
  10   }
  11   #active-tab-before {
  12     width: 334px;
  13   }
  14   #active-tab-after {
  15     width: 334px;
  16   }
  17 </style>
  18
  19 <h1>The activeTab permission</h1>
  20
  21 <p>
  22 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 the tab is navigated or closed.
  23 </p>
  24
  25 <p>
  26 This serves as an alternative for many uses of <code>&lt;all_urls&gt;</code>, but displays <em>no warning message</em> during installation:
  27 </p>
  28
  29 <table id="active-tab-images" class="simple">
  30   <tr>
  31     <th>Without activeTab</th>
  32     <th class="spacing"></th>
  33     <th>With activeTab</th>
  34   </tr>
  35   <tr>
  36     <td><img id="active-tab-before" src="{{static}}/images/active-tab-before.png"></td>
  37     <td class="spacing"></td>
  38     <td><img id="active-tab-after" src="{{static}}/images/active-tab-after.png"></td>
  39   </tr>
  40 </table>
  41
  42 <h2 id="example">Example</h2>
  43
  44 <p>
  45 See the <a href="samples.html#page-redder">Page Redder</a> sample extension:
  46 </p>
  47
  48 <pre data-filename="manifest.json">
  49 {
  50   "name": "Page Redder",
  51   "version": "2.0",
  52   <b>"permissions": [
  53     "activeTab"
  54   ],</b>
  55   "background": {
  56     "scripts": ["background.js"],
  57     "persistent": false
  58   },
  59   "browser_action": {
  60     "default_title": "Make this page red"
  61   },
  62   "manifest_version": 2
  63 }
  64 </pre>
  65
  66 <pre data-filename="background.js">
  67 // Called when the user clicks on the browser action.
  68 chrome.browserAction.onClicked.addListener(function(tab) {
  69   // No tabs or host permissions needed!
  70   console.log('Turning ' + tab.url + ' red!');
  71   chrome.tabs.executeScript({
  72     code: 'document.body.style.backgroundColor="red"'
  73   });
  74 });
  75 </pre>
  76
  77 <h2 id="motivation">Motivation</h2>
  78
  79 <p>
  80 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.
  81 </p>
  82
  83 <p>
  84 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 lot of power to entrust to such a simple extension. And if the extension is ever compromised, the attacker gets access to everything the extension had.
  85 </p>
  86
  87 <p>
  88 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.
  89 </p>
  90
  91 <h2 id="what-activeTab-allows">What activeTab allows</h2>
  92
  93 <p>
  94 While the <code>activeTab</code> permission is enabled for a tab, an extension can:
  95 <ul>
  96   <li>Call <code>$ref:tabs.executeScript</code> or <code>$ref:tabs.insertCSS</code> on that tab.
  97   <li>Get the URL, title, and favicon for that tab via an API that returns a <code>$ref:tabs.Tab</code> object (essentially, <code>activeTab</code> grants the <code><a href="tabs.html#manifest">tabs</a></code> permission temporarily).
  98 </ul>
  99 </p>
 100
 101 <h2 id="invoking-activeTab">Invoking activeTab</h2>
 102
 103 <p>
 104 The following user gestures enable <code>activeTab</code>:
 105 <ul>
 106   <li>Executing a <a href="browserAction.html">browser action</a>
 107   <li>Executing a <a href="pageAction.html">page action</a>
 108   <li>Executing a <a href="contextMenus.html">context menu item</a>
 109   <li>Executing a keyboard shortcut from the <a href="commands.html">commands API</a>
 110   <li>Accepting a suggestion from the <a href="omnibox.html">omnibox API</a>
 111 </ul>
 112 </p>