chrome/common/extensions/docs/templates/intros/declarativeContent.html

   1 <h2 id="usage">Usage</h2>
   2
   3 <p>
   4 The Declarative Content API allows you to show your extension's
   5 $(ref:pageAction page action) depending on the URL of a web page and
   6 the CSS selectors its content matches, without needing to take a <a
   7 href="declare_permissions#host-permissions">host permission</a> or
   8 inject a <a href="content_scripts">content script</a>.  Use the
   9 <a href="activeTab">activeTab</a> permission in order to be able
  10 to interact with a page after the user clicks on your page action.
  11 </p>
  12
  13 <p>
  14 If you need more precise control over when your page action appears or
  15 you need to change its appearance to match the current tab before the
  16 user clicks on it, you'll have to keep using the $(ref:pageAction) API.
  17 </p>
  18
  19 <h2 id="rules">Rules</h2>
  20
  21 <p>As a <a href="events#declarative">declarative API</a>, this
  22 API lets you register rules on the
  23 <code>$(ref:onPageChanged)</code> $(ref:events.Event event) object which take an
  24 action (<code>$(ref:ShowPageAction)</code> and <code>$(ref:SetIcon)</code>) when
  25 a set of conditions, represented as a
  26 <code>$(ref:PageStateMatcher)</code>, are met.
  27 </p>
  28
  29 <p>
  30 The <code>$(ref:PageStateMatcher)</code> matches web pages if and only
  31 if all listed criteria are met. The following rule would show a page
  32 action for pages on <code>https://www.google.com/</code> when a
  33 password field is present on it:
  34 </p>
  35
  36 <pre>
  37 var rule1 = {
  38   conditions: [
  39     new $(ref:PageStateMatcher chrome.declarativeContent.PageStateMatcher)({
  40       $(ref:PageStateMatcher.pageUrl pageUrl): { $(ref:events.UrlFilter.hostEquals hostEquals): 'www.google.com', $(ref:events.UrlFilter.schemes schemes): ['https'] },
  41       $(ref:PageStateMatcher.css css): ["input[type='password']"]
  42     })
  43   ],
  44   actions: [ new $(ref:ShowPageAction chrome.declarativeContent.ShowPageAction)() ]
  45 };
  46 </pre>
  47
  48 <p class="note">
  49 <strong>Note:</strong> All conditions and actions are created via a constructor
  50 as shown in the example above.
  51 </p>
  52
  53 <p>
  54 In order to also show a page action for sites with a video, you can
  55 add a second condition, as each condition is sufficient to trigger all
  56 specified actions:
  57 </p>
  58 <pre>
  59 var rule2 = {
  60   conditions: [
  61     new $(ref:PageStateMatcher chrome.declarativeContent.PageStateMatcher)({
  62       $(ref:PageStateMatcher.pageUrl pageUrl): { $(ref:events.UrlFilter.hostEquals hostEquals): 'www.google.com', $(ref:events.UrlFilter.schemes schemes): ['https'] },
  63       $(ref:PageStateMatcher.css css): ["input[type='password']"]
  64     })<strong>,
  65     new $(ref:PageStateMatcher chrome.declarativeContent.PageStateMatcher)({
  66       $(ref:PageStateMatcher.css css): ["video"]
  67     })</strong>
  68   ],
  69   actions: [ new $(ref:ShowPageAction chrome.declarativeContent.ShowPageAction)() ]
  70 };
  71 </pre>
  72
  73 <p>
  74 <a href="events#addingrules">Added rules</a> are saved across
  75 browser restarts, so register them as follows:
  76 </p>
  77 <pre>
  78 $(ref:runtime.onInstalled chrome.runtime.onInstalled).addListener(function(details) {
  79   $(ref:onPageChanged chrome.declarativeContent.onPageChanged).<a href="events#removingrules">removeRules</a>(undefined, function() {
  80     $(ref:onPageChanged chrome.declarativeContent.onPageChanged).<a href="events#addingrules">addRules</a>([rule2]);
  81   });
  82 });
  83 </pre>
  84
  85 <p class="note">
  86 <strong>Note:</strong> You should always register or unregister rules in bulk
  87 rather than individually because each of these operations recreates internal
  88 data structures.  This re-creation is computationally expensive but facilitates
  89 a faster matching algorithm.
  90 </p>
  91
  92 <p>
  93 Combine the above rule with the <a href="activeTab">activeTab</a>
  94 permission to create an extension that doesn't need any install-time
  95 permissions but can invite the user to click its page action on
  96 relevant pages and can run on those pages when the user clicks the
  97 page action.
  98 </p>
  99
 100 <h2 id="css-matching">CSS Matching</h2>
 101
 102 <p>$(ref:PageStateMatcher.css) conditions must be
 103 <i><a href="http://www.w3.org/TR/selectors4/#compound">compound selectors</a></i>,
 104 meaning that you can't
 105 include <a href="http://www.w3.org/community/webed/wiki/CSS/Selectors#Combinators">combinators</a>
 106 like whitespace or "<code>&gt;</code>" in your selectors.  This helps Chrome
 107 match the selectors more efficiently.</p>
 108
 109 <table>
 110   <tr><th>Compound Selectors (OK)</th><th>Complex Selectors (Not OK)</th></tr>
 111   <tr><td><code>a</code></td><td><code>div p</code></td></tr>
 112   <tr><td><code>iframe.special[src^='http']</code></td><td><code>p>span.highlight</code></td></tr>
 113   <tr><td><code>ns|*</code></td><td><code>p + ol</code></td></tr>
 114   <tr><td><code>#abcd:checked</code></td><td><code>p::first-line</code></td></tr>
 115 </table>
 116
 117 <p>CSS conditions only match displayed elements: if an element that matches your
 118 selector is <code>display:none</code> or one of its parent elements
 119 is <code>display:none</code>, it doesn't cause the condition to match.  Elements
 120 styled with <code>visibility:hidden</code>, positioned off-screen, or hidden by
 121 other elements can still make your condition match.</p>
 122
 123
 124 <h2 id="css-matching">Bookmarked State Matching</h2>
 125
 126 <p>The $(ref:PageStateMatcher.isBookmarked) condition allows matching of the
 127 bookmarked state of the current URL in the user's profile. To make use of this
 128 condition the "bookmarks" permission must be declared in
 129 the <a href="manifest">extension manifest</a></p>