OLD | NEW |
1 <h1>Content Scripts</h1> | 1 <h1>Content Scripts</h1> |
2 | 2 |
3 | 3 |
4 <p> | 4 <p> |
5 Content scripts are JavaScript files that run in the context of web pages. | 5 Content scripts are JavaScript files that run in the context of web pages. |
6 By using the standard | 6 By using the standard |
7 <a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document | 7 <a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document |
8 Object Model</a> (DOM), | 8 Object Model</a> (DOM), |
9 they can read details of the web pages the browser visits, | 9 they can read details of the web pages the browser visits, |
10 or make changes to them. | 10 or make changes to them. |
(...skipping 94 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
105 each of these content scripts can have multiple JavaScript and CSS files. | 105 each of these content scripts can have multiple JavaScript and CSS files. |
106 Each item in the <code>content_scripts</code> array | 106 Each item in the <code>content_scripts</code> array |
107 can have the following properties:</p> | 107 can have the following properties:</p> |
108 | 108 |
109 <table class="simple"> | 109 <table class="simple"> |
110 <tr> | 110 <tr> |
111 <th>Name</th> | 111 <th>Name</th> |
112 <th>Type</th> | 112 <th>Type</th> |
113 <th>Description</th> | 113 <th>Description</th> |
114 </tr> | 114 </tr> |
115 <tr> | 115 <tr id="matches"> |
116 <td><code>matches</code></td> | 116 <td><code>matches</code></td> |
117 <td>array of strings</td> | 117 <td>array of strings</td> |
118 <td><em>Required.</em> | 118 <td><em>Required.</em> |
119 Specifies which pages this content script will be injected into. | 119 Specifies which pages this content script will be injected into. |
120 See <a href="match_patterns">Match Patterns</a> | 120 See <a href="match_patterns">Match Patterns</a> |
121 for more details on the syntax of these strings | 121 for more details on the syntax of these strings |
122 and <a href="#match-patterns-globs">Match patterns and globs</a> | 122 and <a href="#match-patterns-globs">Match patterns and globs</a> |
123 for information on how to exclude URLs.</td> | 123 for information on how to exclude URLs.</td> |
124 </tr> | 124 </tr> |
125 <tr> | 125 <tr id="exclude_matches"> |
126 <td><code>exclude_matches</code></td> | 126 <td><code>exclude_matches</code></td> |
127 <td>array of strings</td> | 127 <td>array of strings</td> |
128 <td><em>Optional.</em> | 128 <td><em>Optional.</em> |
129 Excludes pages that this content script would otherwise be | 129 Excludes pages that this content script would otherwise be |
130 injected into. | 130 injected into. |
131 See <a href="match_patterns">Match Patterns</a> | 131 See <a href="match_patterns">Match Patterns</a> |
132 for more details on the syntax of these strings | 132 for more details on the syntax of these strings |
133 and <a href="#match-patterns-globs">Match patterns and globs</a> | 133 and <a href="#match-patterns-globs">Match patterns and globs</a> |
134 for information on how to exclude URLs.</td> | 134 for information on how to exclude URLs.</td> |
135 </tr> | 135 </tr> |
136 <tr> | 136 <tr id="match_about_blank"> |
137 <td><code>match_about_blank<code></td> | 137 <td><code>match_about_blank<code></td> |
138 <td>boolean</td> | 138 <td>boolean</td> |
139 <td><em>Optional.</em> | 139 <td><em>Optional.</em> |
140 Whether to insert the content script on <code>about:blank</code> and | 140 Whether to insert the content script on <code>about:blank</code> and |
141 <code>about:srcdoc</code>. Content scripts will only be injected on pages | 141 <code>about:srcdoc</code>. Content scripts will only be injected on pages |
142 when their inherit URL is matched by one of the declared patterns in the | 142 when their inherit URL is matched by one of the declared patterns in the |
143 <code>matches</code> field. The inherit URL is the URL of the document that | 143 <code>matches</code> field. The inherit URL is the URL of the document that |
144 created the frame or window. | 144 created the frame or window. |
145 <br> | 145 <br> |
146 Content scripts cannot be inserted in sandboxed frames. | 146 Content scripts cannot be inserted in sandboxed frames. |
147 <br><br> | 147 <br><br> |
148 Defaults to <code>false</code>.</td> | 148 Defaults to <code>false</code>.</td> |
149 </tr> | 149 </tr> |
150 <tr> | 150 <tr id="css"> |
151 <td><code>css<code></td> | 151 <td><code>css<code></td> |
152 <td>array of strings</td> | 152 <td>array of strings</td> |
153 <td><em>Optional.</em> | 153 <td><em>Optional.</em> |
154 The list of CSS files to be injected into matching pages. These are injected
in the order they appear in this array, before any DOM is constructed or displa
yed for the page.</td> | 154 The list of CSS files to be injected into matching pages. These are injected
in the order they appear in this array, before any DOM is constructed or displa
yed for the page.</td> |
155 </tr> | 155 </tr> |
156 <tr> | 156 <tr id="js"> |
157 <td><code>js<code></td> | 157 <td><code>js<code></td> |
158 <td><nobr>array of strings</nobr></td> | 158 <td><nobr>array of strings</nobr></td> |
159 <td><em>Optional.</em> | 159 <td><em>Optional.</em> |
160 The list of JavaScript files to be injected into matching pages. These are i
njected in the order they appear in this array.</td> | 160 The list of JavaScript files to be injected into matching pages. These are i
njected in the order they appear in this array.</td> |
161 </tr> | 161 </tr> |
162 <tr id="run_at"> | 162 <tr id="run_at"> |
163 <td><code>run_at<code></td> | 163 <td><code>run_at<code></td> |
164 <td>string</td> | 164 <td>string</td> |
165 <td><em>Optional.</em> | 165 <td><em>Optional.</em> |
166 Controls when the files in <code>js</code> are injected. Can be "document_st
art", "document_end", or "document_idle". Defaults to "document_idle". | 166 Controls when the files in <code>js</code> are injected. Can be "document_st
art", "document_end", or "document_idle". Defaults to "document_idle". |
167 | 167 |
168 <br><br> | 168 <br><br> |
169 | 169 |
170 In the case of "document_start", the files are injected after any files from
<code>css</code>, but before any other DOM is constructed or any other script i
s run. | 170 In the case of "document_start", the files are injected after any files from
<code>css</code>, but before any other DOM is constructed or any other script i
s run. |
171 | 171 |
172 <br><br> | 172 <br><br> |
173 | 173 |
174 In the case of "document_end", the files are injected immediately after the
DOM is complete, but before subresources like images and frames have loaded. | 174 In the case of "document_end", the files are injected immediately after the
DOM is complete, but before subresources like images and frames have loaded. |
175 | 175 |
176 <br><br> | 176 <br><br> |
177 | 177 |
178 In the case of "document_idle", the browser chooses a time to inject scripts
between "document_end" and immediately after the <code><a href="http://www.what
wg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> eve
nt fires. The exact moment of injection depends on how complex the document is a
nd how long it is taking to load, and is optimized for page load speed. | 178 In the case of "document_idle", the browser chooses a time to inject scripts
between "document_end" and immediately after the <code><a href="http://www.what
wg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> eve
nt fires. The exact moment of injection depends on how complex the document is a
nd how long it is taking to load, and is optimized for page load speed. |
179 | 179 |
180 <br><br> | 180 <br><br> |
181 | 181 |
182 <b>Note:</b> With "document_idle", content scripts may not necessarily recei
ve the <code>window.onload</code> event, because they may run after it has | 182 <b>Note:</b> With "document_idle", content scripts may not necessarily recei
ve the <code>window.onload</code> event, because they may run after it has |
183 already fired. In most cases, listening for the <code>onload</code> event is
unnecessary for content scripts running at "document_idle" because they are gua
ranteed to run after the DOM is complete. If your script definitely needs to run
after <code>window.onload</code>, you can check if <code>onload</code> has alre
ady fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/curre
nt-work/#dom-document-readystate">document.readyState</a></code> property.</td> | 183 already fired. In most cases, listening for the <code>onload</code> event is
unnecessary for content scripts running at "document_idle" because they are gua
ranteed to run after the DOM is complete. If your script definitely needs to run
after <code>window.onload</code>, you can check if <code>onload</code> has alre
ady fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/curre
nt-work/#dom-document-readystate">document.readyState</a></code> property.</td> |
184 </tr> | 184 </tr> |
185 <tr> | 185 <tr id="all_frames"> |
186 <td><code>all_frames<code></td> | 186 <td><code>all_frames<code></td> |
187 <td>boolean</td> | 187 <td>boolean</td> |
188 <td><em>Optional.</em> | 188 <td><em>Optional.</em> |
189 Controls whether the content script runs in all frames of the matching page,
or only the top frame. | 189 Controls whether the content script runs in all frames of the matching page,
or only the top frame. |
190 <br><br> | 190 <br><br> |
191 Defaults to <code>false</code>, meaning that only the top frame is matched.<
/td> | 191 Defaults to <code>false</code>, meaning that only the top frame is matched.<
/td> |
192 </tr> | 192 </tr> |
193 <tr> | 193 <tr id="include_globs"> |
194 <td><code>include_globs</code></td> | 194 <td><code>include_globs</code></td> |
195 <td>array of string</td> | 195 <td>array of string</td> |
196 <td><em>Optional.</em> | 196 <td><em>Optional.</em> |
197 Applied after <code>matches</code> to include only those URLs that also matc
h this glob. Intended to emulate the <a href="http://wiki.greasespot.net/Metadat
a_Block#.40include"><code>@include</code></a> Greasemonkey keyword. | 197 Applied after <code>matches</code> to include only those URLs that also matc
h this glob. Intended to emulate the <a href="http://wiki.greasespot.net/Metadat
a_Block#.40include"><code>@include</code></a> Greasemonkey keyword. |
198 See <a href="#match-patterns-globs">Match patterns and globs</a> below for m
ore details.</td> | 198 See <a href="#match-patterns-globs">Match patterns and globs</a> below for m
ore details.</td> |
199 </tr> | 199 </tr> |
200 <tr> | 200 <tr id="exclude_globs"> |
201 <td><code>exclude_globs</code></td> | 201 <td><code>exclude_globs</code></td> |
202 <td>array of string</td> | 202 <td>array of string</td> |
203 <td><em>Optional.</em> | 203 <td><em>Optional.</em> |
204 Applied after <code>matches</code> to exclude URLs that match this glob. | 204 Applied after <code>matches</code> to exclude URLs that match this glob. |
205 Intended to emulate the <a href="http://wiki.greasespot.net/Metadata_Block#.
40include"><code>@exclude</code></a> Greasemonkey keyword. | 205 Intended to emulate the <a href="http://wiki.greasespot.net/Metadata_Block#.
40include"><code>@exclude</code></a> Greasemonkey keyword. |
206 See <a href="#match-patterns-globs">Match patterns and globs</a> below for m
ore details.</td> | 206 See <a href="#match-patterns-globs">Match patterns and globs</a> below for m
ore details.</td> |
207 </tr> | 207 </tr> |
208 </table> | 208 </table> |
209 | 209 |
210 <h3 id="match-patterns-globs">Match patterns and globs</h3> | 210 <h3 id="match-patterns-globs">Match patterns and globs</h3> |
(...skipping 255 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
466 | 466 |
467 <p> | 467 <p> |
468 The next video describes message passing, | 468 The next video describes message passing, |
469 featuring an example of a content script | 469 featuring an example of a content script |
470 sending a request to its parent extension. | 470 sending a request to its parent extension. |
471 </p> | 471 </p> |
472 | 472 |
473 <div class="video-container"> | 473 <div class="video-container"> |
474 <iframe title="YouTube video player" width="640" height="390" src="//www.youtu
be.com/embed/B4M_a7xejYI?rel=0" frameborder="0" allowfullscreen></iframe> | 474 <iframe title="YouTube video player" width="640" height="390" src="//www.youtu
be.com/embed/B4M_a7xejYI?rel=0" frameborder="0" allowfullscreen></iframe> |
475 </div> | 475 </div> |
OLD | NEW |