| <h2 id="usage">Usage</h2> |
| |
| <p> |
| The Declarative Content API allows you to show your extension's |
| $ref:[pageAction page action] depending on the URL of a web page and |
| the CSS selectors its content matches, without needing to take a <a |
| href="declare_permissions.html#host-permission">host permission</a> or |
| inject a <a href="content_scripts.html">content script</a>. Use the |
| <a href="activeTab.html">activeTab</a> permission in order to be able |
| to interact with a page after the user clicks on your page action. |
| </p> |
| |
| <p> |
| If you need more precise control over when your page action appears or |
| you need to change its appearance to match the current tab before the |
| user clicks on it, you'll have to keep using the $ref:pageAction API. |
| </p> |
| |
| <h2 id="rules">Rules</h2> |
| |
| <p>As a <a href="events.html#declarative">declarative API</a>, this |
| API lets you register rules on the |
| <code>$ref:onPageChanged</code> $ref:[events.Event event] object which |
| take an action (currently just <code>$ref:ShowPageAction</code>) when |
| a set of conditions, represented as a |
| <code>$ref:[PageStateMatcher]</code>, are met. |
| </p> |
| |
| <p> |
| The <code>$ref:PageStateMatcher</code> matches web pages if and only |
| if all listed criteria are met. The following rule would show a page |
| action for pages on <code>https://www.google.com/</code> when a |
| password field is present on it: |
| </p> |
| |
| <pre> |
| var rule1 = { |
| conditions: [ |
| new $ref:[PageStateMatcher chrome.declarativeContent.PageStateMatcher]({ |
| $ref:[PageStateMatcher.pageUrl pageUrl]: { $ref:[events.UrlFilter.hostEquals hostEquals]: 'www.google.com', $ref:[events.UrlFilter.schemes schemes]: ['https'] }, |
| $ref:[PageStateMatcher.css css]: ["input[type='password']"] |
| }) |
| ], |
| actions: [ new $ref:[ShowPageAction chrome.declarativeContent.ShowPageAction]() ] |
| }; |
| </pre> |
| |
| <p class="note"> |
| <strong>Note:</strong> All conditions and actions are created via a constructor |
| as shown in the example above. |
| </p> |
| |
| <p> |
| In order to also show a page action for sites with a video, you can |
| add a second condition, as each condition is sufficient to trigger all |
| specified actions: |
| </p> |
| <pre> |
| var rule2 = { |
| conditions: [ |
| new $ref:[PageStateMatcher chrome.declarativeContent.PageStateMatcher]({ |
| $ref:[PageStateMatcher.pageUrl pageUrl]: { $ref:[events.UrlFilter.hostEquals hostEquals]: 'www.google.com', $ref:[events.UrlFilter.schemes schemes]: ['https'] }, |
| $ref:[PageStateMatcher.css css]: ["input[type='password']"] |
| })<strong>, |
| new $ref:[PageStateMatcher chrome.declarativeContent.PageStateMatcher]({ |
| $ref:[PageStateMatcher.css css]: ["video"] |
| })</strong> |
| ], |
| actions: [ new $ref:[ShowPageAction chrome.declarativeContent.ShowPageAction]() ] |
| }; |
| </pre> |
| |
| <p> |
| <a href="events.html#addingrules">Added rules</a> are saved across |
| browser restarts, so register them as follows: |
| </p> |
| <pre> |
| $ref:[runtime.onInstalled chrome.runtime.onInstalled].addListener(function(details) { |
| $ref:[onPageChanged chrome.declarativeContent.onPageChanged].<a href="events.html#removingrules">removeRules</a>(undefined, function() { |
| $ref:[onPageChanged chrome.declarativeContent.onPageChanged].<a href="events.html#addingrules">addRules</a>([rule2]); |
| }); |
| }); |
| </pre> |
| |
| <p class="note"> |
| <strong>Note:</strong> You should always register or unregister rules in bulk |
| rather than individually because each of these operations recreates internal |
| data structures. This re-creation is computationally expensive but facilitates |
| a faster matching algorithm. |
| </p> |
| |
| <p> |
| Combine the above rule with the <a href="activeTab.html">activeTab</a> |
| permission to create an extension that doesn't need any install-time |
| permissions but can invite the user to click its page action on |
| relevant pages and can run on those pages when the user clicks the |
| page action. |
| </p> |
| |
| <h2 id="css-matching">CSS Matching</h2> |
| |
| <p>$ref:PageStateMatcher.css conditions must be |
| <i><a href="http://www.w3.org/TR/selectors4/#compound">compound selectors</a></i>, |
| meaning that you can't |
| include <a href="http://www.w3.org/community/webed/wiki/CSS/Selectors#Combinators">combinators</a> |
| like whitespace or "<code>></code>" in your selectors. This helps Chrome |
| match the selectors more efficiently.</p> |
| |
| <table> |
| <tr><th>Compound Selectors (OK)</th><th>Complex Selectors (Not OK)</th></tr> |
| <tr><td><code>a</code></td><td><code>div p</code></td></tr> |
| <tr><td><code>iframe.special[src^='http']</code></td><td><code>p>span.highlight</code></td></tr> |
| <tr><td><code>ns|*</code></td><td><code>p + ol</code></td></tr> |
| <tr><td><code>#abcd:checked</code></td><td><code>p::first-line</code></td></tr> |
| </table> |
| |
| <p>CSS conditions only match displayed elements: if an element that matches your |
| selector is <code>display:none</code> or one of its parent elements |
| is <code>display:none</code>, it doesn't cause the condition to match. Elements |
| styled with <code>visibility:hidden</code>, positioned off-screen, or hidden by |
| other elements can still make your condition match.</p> |