OLD | NEW |
1 <h2 id="usage">Usage</h2> | 1 <h2 id="usage">Usage</h2> |
2 | 2 |
3 <p> | 3 <p> |
4 The Declarative Content API allows you to show your extension's | 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 | 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 | 6 the CSS selectors its content matches, without needing to take a <a |
7 href="declare_permissions.html#host-permissions">host permission</a> or | 7 href="declare_permissions#host-permissions">host permission</a> or |
8 inject a <a href="content_scripts.html">content script</a>. Use the | 8 inject a <a href="content_scripts">content script</a>. Use the |
9 <a href="activeTab.html">activeTab</a> permission in order to be able | 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. | 10 to interact with a page after the user clicks on your page action. |
11 </p> | 11 </p> |
12 | 12 |
13 <p> | 13 <p> |
14 If you need more precise control over when your page action appears or | 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 | 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. | 16 user clicks on it, you'll have to keep using the $(ref:pageAction) API. |
17 </p> | 17 </p> |
18 | 18 |
19 <h2 id="rules">Rules</h2> | 19 <h2 id="rules">Rules</h2> |
20 | 20 |
21 <p>As a <a href="events.html#declarative">declarative API</a>, this | 21 <p>As a <a href="events#declarative">declarative API</a>, this |
22 API lets you register rules on the | 22 API lets you register rules on the |
23 <code>$(ref:onPageChanged)</code> $(ref:events.Event event) object which | 23 <code>$(ref:onPageChanged)</code> $(ref:events.Event event) object which |
24 take an action (currently just <code>$(ref:ShowPageAction)</code>) when | 24 take an action (currently just <code>$(ref:ShowPageAction)</code>) when |
25 a set of conditions, represented as a | 25 a set of conditions, represented as a |
26 <code>$(ref:PageStateMatcher)</code>, are met. | 26 <code>$(ref:PageStateMatcher)</code>, are met. |
27 </p> | 27 </p> |
28 | 28 |
29 <p> | 29 <p> |
30 The <code>$(ref:PageStateMatcher)</code> matches web pages if and only | 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 | 31 if all listed criteria are met. The following rule would show a page |
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
64 })<strong>, | 64 })<strong>, |
65 new $(ref:PageStateMatcher chrome.declarativeContent.PageStateMatcher)({ | 65 new $(ref:PageStateMatcher chrome.declarativeContent.PageStateMatcher)({ |
66 $(ref:PageStateMatcher.css css): ["video"] | 66 $(ref:PageStateMatcher.css css): ["video"] |
67 })</strong> | 67 })</strong> |
68 ], | 68 ], |
69 actions: [ new $(ref:ShowPageAction chrome.declarativeContent.ShowPageAction)(
) ] | 69 actions: [ new $(ref:ShowPageAction chrome.declarativeContent.ShowPageAction)(
) ] |
70 }; | 70 }; |
71 </pre> | 71 </pre> |
72 | 72 |
73 <p> | 73 <p> |
74 <a href="events.html#addingrules">Added rules</a> are saved across | 74 <a href="events#addingrules">Added rules</a> are saved across |
75 browser restarts, so register them as follows: | 75 browser restarts, so register them as follows: |
76 </p> | 76 </p> |
77 <pre> | 77 <pre> |
78 $(ref:runtime.onInstalled chrome.runtime.onInstalled).addListener(function(detai
ls) { | 78 $(ref:runtime.onInstalled chrome.runtime.onInstalled).addListener(function(detai
ls) { |
79 $(ref:onPageChanged chrome.declarativeContent.onPageChanged).<a href="events.h
tml#removingrules">removeRules</a>(undefined, function() { | 79 $(ref:onPageChanged chrome.declarativeContent.onPageChanged).<a href="events#r
emovingrules">removeRules</a>(undefined, function() { |
80 $(ref:onPageChanged chrome.declarativeContent.onPageChanged).<a href="events
.html#addingrules">addRules</a>([rule2]); | 80 $(ref:onPageChanged chrome.declarativeContent.onPageChanged).<a href="events
#addingrules">addRules</a>([rule2]); |
81 }); | 81 }); |
82 }); | 82 }); |
83 </pre> | 83 </pre> |
84 | 84 |
85 <p class="note"> | 85 <p class="note"> |
86 <strong>Note:</strong> You should always register or unregister rules in bulk | 86 <strong>Note:</strong> You should always register or unregister rules in bulk |
87 rather than individually because each of these operations recreates internal | 87 rather than individually because each of these operations recreates internal |
88 data structures. This re-creation is computationally expensive but facilitates | 88 data structures. This re-creation is computationally expensive but facilitates |
89 a faster matching algorithm. | 89 a faster matching algorithm. |
90 </p> | 90 </p> |
91 | 91 |
92 <p> | 92 <p> |
93 Combine the above rule with the <a href="activeTab.html">activeTab</a> | 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 | 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 | 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 | 96 relevant pages and can run on those pages when the user clicks the |
97 page action. | 97 page action. |
98 </p> | 98 </p> |
99 | 99 |
100 <h2 id="css-matching">CSS Matching</h2> | 100 <h2 id="css-matching">CSS Matching</h2> |
101 | 101 |
102 <p>$(ref:PageStateMatcher.css) conditions must be | 102 <p>$(ref:PageStateMatcher.css) conditions must be |
103 <i><a href="http://www.w3.org/TR/selectors4/#compound">compound selectors</a></i
>, | 103 <i><a href="http://www.w3.org/TR/selectors4/#compound">compound selectors</a></i
>, |
104 meaning that you can't | 104 meaning that you can't |
105 include <a href="http://www.w3.org/community/webed/wiki/CSS/Selectors#Combinator
s">combinators</a> | 105 include <a href="http://www.w3.org/community/webed/wiki/CSS/Selectors#Combinator
s">combinators</a> |
106 like whitespace or "<code>></code>" in your selectors. This helps Chrome | 106 like whitespace or "<code>></code>" in your selectors. This helps Chrome |
107 match the selectors more efficiently.</p> | 107 match the selectors more efficiently.</p> |
108 | 108 |
109 <table> | 109 <table> |
110 <tr><th>Compound Selectors (OK)</th><th>Complex Selectors (Not OK)</th></tr> | 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> | 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.highligh
t</code></td></tr> | 112 <tr><td><code>iframe.special[src^='http']</code></td><td><code>p>span.highligh
t</code></td></tr> |
113 <tr><td><code>ns|*</code></td><td><code>p + ol</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
> | 114 <tr><td><code>#abcd:checked</code></td><td><code>p::first-line</code></td></tr
> |
115 </table> | 115 </table> |
116 | 116 |
117 <p>CSS conditions only match displayed elements: if an element that matches your | 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 | 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 | 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 | 120 styled with <code>visibility:hidden</code>, positioned off-screen, or hidden by |
121 other elements can still make your condition match.</p> | 121 other elements can still make your condition match.</p> |
OLD | NEW |