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 11 matching lines...) Expand all Loading... |
22 | 22 |
23 <p> | 23 <p> |
24 However, content scripts have some limitations. | 24 However, content scripts have some limitations. |
25 They <b>cannot</b>: | 25 They <b>cannot</b>: |
26 </p> | 26 </p> |
27 | 27 |
28 <ul> | 28 <ul> |
29 <li> | 29 <li> |
30 Use chrome.* APIs | 30 Use chrome.* APIs |
31 (except for parts of | 31 (except for parts of |
32 <a href="extension.html"><code>chrome.extension</code></a>) | 32 <a href="extension"><code>chrome.extension</code></a>) |
33 </li> | 33 </li> |
34 <li> | 34 <li> |
35 Use variables or functions defined by their extension's pages | 35 Use variables or functions defined by their extension's pages |
36 </li> | 36 </li> |
37 <li> | 37 <li> |
38 Use variables or functions defined by web pages or by other content scripts | 38 Use variables or functions defined by web pages or by other content scripts |
39 </li> | 39 </li> |
40 </ul> | 40 </ul> |
41 | 41 |
42 <p> | 42 <p> |
43 These limitations aren't as bad as they sound. | 43 These limitations aren't as bad as they sound. |
44 Content scripts can <em>indirectly</em> use the chrome.* APIs, | 44 Content scripts can <em>indirectly</em> use the chrome.* APIs, |
45 get access to extension data, | 45 get access to extension data, |
46 and request extension actions | 46 and request extension actions |
47 by exchanging <a href="messaging.html">messages</a> | 47 by exchanging <a href="messaging">messages</a> |
48 with their parent extension. | 48 with their parent extension. |
49 Content scripts can also | 49 Content scripts can also |
50 make <a href="xhr.html">cross-site XMLHttpRequests</a> | 50 make <a href="xhr">cross-site XMLHttpRequests</a> |
51 to the same sites as their parent extensions, | 51 to the same sites as their parent extensions, |
52 and they can | 52 and they can |
53 <a href="#host-page-communication">communicate with web pages</a> | 53 <a href="#host-page-communication">communicate with web pages</a> |
54 using the shared DOM. | 54 using the shared DOM. |
55 For more insight into what content scripts can and can't do, | 55 For more insight into what content scripts can and can't do, |
56 learn about the | 56 learn about the |
57 <a href="#execution-environment">execution environment</a>. | 57 <a href="#execution-environment">execution environment</a>. |
58 </p> | 58 </p> |
59 | 59 |
60 <h2 id="registration">Manifest</h2> | 60 <h2 id="registration">Manifest</h2> |
61 | 61 |
62 <p>If your content script's code should always be injected, | 62 <p>If your content script's code should always be injected, |
63 register it in the | 63 register it in the |
64 <a href="manifest.html">extension manifest</a> | 64 <a href="manifest">extension manifest</a> |
65 using the <code>content_scripts</code> field, | 65 using the <code>content_scripts</code> field, |
66 as in the following example. | 66 as in the following example. |
67 </p> | 67 </p> |
68 | 68 |
69 <pre data-filename="manifest.json"> | 69 <pre data-filename="manifest.json"> |
70 { | 70 { |
71 "name": "My extension", | 71 "name": "My extension", |
72 ... | 72 ... |
73 <b>"content_scripts": [ | 73 <b>"content_scripts": [ |
74 { | 74 { |
75 "matches": ["http://www.google.com/*"], | 75 "matches": ["http://www.google.com/*"], |
76 "css": ["mystyles.css"], | 76 "css": ["mystyles.css"], |
77 "js": ["jquery.js", "myscript.js"] | 77 "js": ["jquery.js", "myscript.js"] |
78 } | 78 } |
79 ]</b>, | 79 ]</b>, |
80 ... | 80 ... |
81 } | 81 } |
82 </pre> | 82 </pre> |
83 | 83 |
84 <p> | 84 <p> |
85 If you want to inject the code only sometimes, | 85 If you want to inject the code only sometimes, |
86 use the | 86 use the |
87 <a href="declare_permissions.html"><code>permissions</code></a> field instead, | 87 <a href="declare_permissions"><code>permissions</code></a> field instead, |
88 as described in <a href="#pi">Programmatic injection</a>. | 88 as described in <a href="#pi">Programmatic injection</a>. |
89 </p> | 89 </p> |
90 | 90 |
91 <pre data-filename="manifest.json"> | 91 <pre data-filename="manifest.json"> |
92 { | 92 { |
93 "name": "My extension", | 93 "name": "My extension", |
94 ... | 94 ... |
95 <b>"permissions": [ | 95 <b>"permissions": [ |
96 "tabs", "http://www.google.com/*" | 96 "tabs", "http://www.google.com/*" |
97 ]</b>, | 97 ]</b>, |
(...skipping 12 matching lines...) Expand all Loading... |
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> |
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.html">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> |
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.html">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> |
137 <td><code>css<code></td> | 137 <td><code>css<code></td> |
138 <td>array of strings</td> | 138 <td>array of strings</td> |
139 <td><em>Optional.</em> | 139 <td><em>Optional.</em> |
140 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> | 140 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> |
141 </tr> | 141 </tr> |
(...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
205 For example, assume <code>matches</code> is <code>["http://*.nytimes.com/*"]</co
de>: | 205 For example, assume <code>matches</code> is <code>["http://*.nytimes.com/*"]</co
de>: |
206 </p> | 206 </p> |
207 <ul> | 207 <ul> |
208 <li>If <code>exclude_matches</code> is <code>["*://*/*business*"]</code>, then t
he content script would be injected into "http://www.nytimes.com/health" but not
into "http://www.nytimes.com/business".</li> | 208 <li>If <code>exclude_matches</code> is <code>["*://*/*business*"]</code>, then t
he content script would be injected into "http://www.nytimes.com/health" but not
into "http://www.nytimes.com/business".</li> |
209 <li>If <code>include_globs</code> is <code>["*nytimes.com/???s/*"]</code>, then
the content script would be injected into "http:/www.nytimes.com/arts/index.html
" and "http://www.nytimes.com/jobs/index.html" but not into "http://www.nytimes.
com/sports/index.html".</li> | 209 <li>If <code>include_globs</code> is <code>["*nytimes.com/???s/*"]</code>, then
the content script would be injected into "http:/www.nytimes.com/arts/index.html
" and "http://www.nytimes.com/jobs/index.html" but not into "http://www.nytimes.
com/sports/index.html".</li> |
210 <li>If <code>exclude_globs</code> is <code>["*science*"]</code>, then the conten
t script would be injected into "http://www.nytimes.com" but not into "http://sc
ience.nytimes.com" or "http://www.nytimes.com/science".</li> | 210 <li>If <code>exclude_globs</code> is <code>["*science*"]</code>, then the conten
t script would be injected into "http://www.nytimes.com" but not into "http://sc
ience.nytimes.com" or "http://www.nytimes.com/science".</li> |
211 </ul> | 211 </ul> |
212 <p> | 212 <p> |
213 | 213 |
214 <p> | 214 <p> |
215 Glob properties follow a different, more flexible syntax than <a href="match_pat
terns.html">match patterns</a>. Acceptable glob strings are URLs that may conta
in "wildcard" asterisks and question marks. The asterisk (*) matches any string
of any length (including the empty string); the question mark (?) matches any si
ngle character. | 215 Glob properties follow a different, more flexible syntax than <a href="match_pat
terns">match patterns</a>. Acceptable glob strings are URLs that may contain "w
ildcard" asterisks and question marks. The asterisk (*) matches any string of an
y length (including the empty string); the question mark (?) matches any single
character. |
216 </p> | 216 </p> |
217 | 217 |
218 <p> | 218 <p> |
219 For example, the glob "http://???.example.com/foo/*" matches any of the followin
g: | 219 For example, the glob "http://???.example.com/foo/*" matches any of the followin
g: |
220 </p> | 220 </p> |
221 <ul> | 221 <ul> |
222 <li>"http://www.example.com/foo/bar"</li> | 222 <li>"http://www.example.com/foo/bar"</li> |
223 <li>"http://the.example.com/foo/"</li> | 223 <li>"http://the.example.com/foo/"</li> |
224 </ul> | 224 </ul> |
225 <p> | 225 <p> |
(...skipping 12 matching lines...) Expand all Loading... |
238 when your JavaScript or CSS code | 238 when your JavaScript or CSS code |
239 shouldn't be injected into every single page | 239 shouldn't be injected into every single page |
240 that matches the pattern — | 240 that matches the pattern — |
241 for example, if you want a script to run | 241 for example, if you want a script to run |
242 only when the user clicks a browser action's icon. | 242 only when the user clicks a browser action's icon. |
243 </p> | 243 </p> |
244 | 244 |
245 <p> | 245 <p> |
246 To insert code into a page, | 246 To insert code into a page, |
247 your extension must have | 247 your extension must have |
248 <a href="xhr.html#requesting-permission">cross-origin permissions</a> | 248 <a href="xhr#requesting-permission">cross-origin permissions</a> |
249 for the page. | 249 for the page. |
250 It also must be able to use the <code>chrome.tabs</code> module. | 250 It also must be able to use the <code>chrome.tabs</code> module. |
251 You can get both kinds of permission | 251 You can get both kinds of permission |
252 using the manifest file's | 252 using the manifest file's |
253 <a href="declare_permissions.html">permissions</a> field. | 253 <a href="declare_permissions">permissions</a> field. |
254 </p> | 254 </p> |
255 | 255 |
256 <p> | 256 <p> |
257 Once you have permissions set up, | 257 Once you have permissions set up, |
258 you can inject JavaScript into a page by calling | 258 you can inject JavaScript into a page by calling |
259 $(ref:tabs.executeScript). | 259 $(ref:tabs.executeScript). |
260 To inject CSS, use | 260 To inject CSS, use |
261 $(ref:tabs.insertCSS). | 261 $(ref:tabs.insertCSS). |
262 </p> | 262 </p> |
263 | 263 |
(...skipping 100 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
364 window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*"
); | 364 window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*"
); |
365 }, false);</pre> | 365 }, false);</pre> |
366 <p>In the above example, example.html (which is not a part of the extension) pos
ts messages to itself, which are intercepted and inspected by the content script
, and then posted to the extension process. In this way, the page establishes a
line of communication to the extension process. The reverse is possible through
similar means.</p> | 366 <p>In the above example, example.html (which is not a part of the extension) pos
ts messages to itself, which are intercepted and inspected by the content script
, and then posted to the extension process. In this way, the page establishes a
line of communication to the extension process. The reverse is possible through
similar means.</p> |
367 | 367 |
368 <h2 id="security-considerations">Security considerations</h2> | 368 <h2 id="security-considerations">Security considerations</h2> |
369 | 369 |
370 <p>When writing a content script, you should be aware of two security issues. | 370 <p>When writing a content script, you should be aware of two security issues. |
371 First, be careful not to introduce security vulnerabilities into the web site | 371 First, be careful not to introduce security vulnerabilities into the web site |
372 your content script is injected into. For example, if your content script | 372 your content script is injected into. For example, if your content script |
373 receives content from another web site (for example, by making an <a | 373 receives content from another web site (for example, by making an <a |
374 href="xhr.html">XMLHttpRequest</a>), | 374 href="xhr">XMLHttpRequest</a>), |
375 be careful to filter that content for <a | 375 be careful to filter that content for <a |
376 href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site | 376 href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site |
377 scripting</a> attacks before injecting the content into the current page. | 377 scripting</a> attacks before injecting the content into the current page. |
378 For example, prefer to inject content via innerText rather than innerHTML. | 378 For example, prefer to inject content via innerText rather than innerHTML. |
379 Be especially careful when retrieving HTTP content on an HTTPS page because | 379 Be especially careful when retrieving HTTP content on an HTTPS page because |
380 the HTTP content might have been corrupted by a network <a | 380 the HTTP content might have been corrupted by a network <a |
381 href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">"man-in-the-middle"
</a> | 381 href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">"man-in-the-middle"
</a> |
382 if the user is on a hostile network.</p> | 382 if the user is on a hostile network.</p> |
383 | 383 |
384 <p>Second, although running your content script in an isolated world provides | 384 <p>Second, although running your content script in an isolated world provides |
(...skipping 38 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
423 <pre> | 423 <pre> |
424 <em>//Code for displaying <extensionDir>/images/myimage.png:</em> | 424 <em>//Code for displaying <extensionDir>/images/myimage.png:</em> |
425 var imgURL = <b>chrome.extension.getURL("images/myimage.png")</b>; | 425 var imgURL = <b>chrome.extension.getURL("images/myimage.png")</b>; |
426 document.getElementById("someImage").src = imgURL; | 426 document.getElementById("someImage").src = imgURL; |
427 </pre> | 427 </pre> |
428 | 428 |
429 <h2 id="examples"> Examples </h2> | 429 <h2 id="examples"> Examples </h2> |
430 | 430 |
431 <p> | 431 <p> |
432 You can find many | 432 You can find many |
433 <a href="samples.html#script">examples that use content scripts</a>. | 433 <a href="samples#script">examples that use content scripts</a>. |
434 A simple example of communication via messages is in the | 434 A simple example of communication via messages is in the |
435 <a href="samples.html#message-timer">Message Timer</a>. | 435 <a href="samples#message-timer">Message Timer</a>. |
436 See <a href="samples.html#page-redder">Page Redder</a> and | 436 See <a href="samples#page-redder">Page Redder</a> and |
437 <a href="samples.html#email-this-page-(by-google)">Email This Page</a> | 437 <a href="samples#email-this-page-(by-google)">Email This Page</a> |
438 for examples of programmatic injection. | 438 for examples of programmatic injection. |
439 </p> | 439 </p> |
440 | 440 |
441 | 441 |
442 <h2 id="videos"> Videos </h2> | 442 <h2 id="videos"> Videos </h2> |
443 | 443 |
444 <p> | 444 <p> |
445 The following videos discuss concepts that are important for content scripts. | 445 The following videos discuss concepts that are important for content scripts. |
446 The first video describes content scripts and isolated worlds. | 446 The first video describes content scripts and isolated worlds. |
447 </p> | 447 </p> |
448 | 448 |
449 <p> | 449 <p> |
450 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/laLudeUmXHM?rel=0" frameborder="0" allowfullscreen></iframe> | 450 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/laLudeUmXHM?rel=0" frameborder="0" allowfullscreen></iframe> |
451 </p> | 451 </p> |
452 | 452 |
453 <p> | 453 <p> |
454 The next video describes message passing, | 454 The next video describes message passing, |
455 featuring an example of a content script | 455 featuring an example of a content script |
456 sending a request to its parent extension. | 456 sending a request to its parent extension. |
457 </p> | 457 </p> |
458 | 458 |
459 <p> | 459 <p> |
460 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/B4M_a7xejYI?rel=0" frameborder="0" allowfullscreen></iframe> | 460 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/B4M_a7xejYI?rel=0" frameborder="0" allowfullscreen></iframe> |
461 </p> | 461 </p> |
OLD | NEW |