Home | History | Annotate | Download | only in intros 
      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.html#host-permissions">host permission</a> or
      8 inject a <a href="content_scripts.html">content script</a>.  Use the
      9 <a href="activeTab.html">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.html#declarative">declarative API</a>, this
     22 API lets you register rules on the
     23 <code>$ref:onPageChanged</code> $ref:[events.Event event] object which
     24 take an action (currently just <code>$ref:ShowPageAction</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.html#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.html#removingrules">removeRules</a>(undefined, function() {
     80     $ref:[onPageChanged chrome.declarativeContent.onPageChanged].<a href="events.html#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.html">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