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>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 if | 141 <code>about:srcdoc</code>. Content scripts will only be injected on pages if |
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
217 For example, assume <code>matches</code> is <code>["http://*.nytimes.com/*"]</co
de>: | 217 For example, assume <code>matches</code> is <code>["http://*.nytimes.com/*"]</co
de>: |
218 </p> | 218 </p> |
219 <ul> | 219 <ul> |
220 <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> | 220 <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> |
221 <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> | 221 <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> |
222 <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> | 222 <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> |
223 </ul> | 223 </ul> |
224 <p> | 224 <p> |
225 | 225 |
226 <p> | 226 <p> |
227 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. | 227 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. |
228 </p> | 228 </p> |
229 | 229 |
230 <p> | 230 <p> |
231 For example, the glob "http://???.example.com/foo/*" matches any of the followin
g: | 231 For example, the glob "http://???.example.com/foo/*" matches any of the followin
g: |
232 </p> | 232 </p> |
233 <ul> | 233 <ul> |
234 <li>"http://www.example.com/foo/bar"</li> | 234 <li>"http://www.example.com/foo/bar"</li> |
235 <li>"http://the.example.com/foo/"</li> | 235 <li>"http://the.example.com/foo/"</li> |
236 </ul> | 236 </ul> |
237 <p> | 237 <p> |
(...skipping 12 matching lines...) Expand all Loading... |
250 when your JavaScript or CSS code | 250 when your JavaScript or CSS code |
251 shouldn't be injected into every single page | 251 shouldn't be injected into every single page |
252 that matches the pattern — | 252 that matches the pattern — |
253 for example, if you want a script to run | 253 for example, if you want a script to run |
254 only when the user clicks a browser action's icon. | 254 only when the user clicks a browser action's icon. |
255 </p> | 255 </p> |
256 | 256 |
257 <p> | 257 <p> |
258 To insert code into a page, | 258 To insert code into a page, |
259 your extension must have | 259 your extension must have |
260 <a href="xhr.html#requesting-permission">cross-origin permissions</a> | 260 <a href="xhr#requesting-permission">cross-origin permissions</a> |
261 for the page. | 261 for the page. |
262 It also must be able to use the <code>chrome.tabs</code> module. | 262 It also must be able to use the <code>chrome.tabs</code> module. |
263 You can get both kinds of permission | 263 You can get both kinds of permission |
264 using the manifest file's | 264 using the manifest file's |
265 <a href="declare_permissions.html">permissions</a> field. | 265 <a href="declare_permissions">permissions</a> field. |
266 </p> | 266 </p> |
267 | 267 |
268 <p> | 268 <p> |
269 Once you have permissions set up, | 269 Once you have permissions set up, |
270 you can inject JavaScript into a page by calling | 270 you can inject JavaScript into a page by calling |
271 $(ref:tabs.executeScript). | 271 $(ref:tabs.executeScript). |
272 To inject CSS, use | 272 To inject CSS, use |
273 $(ref:tabs.insertCSS). | 273 $(ref:tabs.insertCSS). |
274 </p> | 274 </p> |
275 | 275 |
(...skipping 100 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
376 window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*"
); | 376 window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*"
); |
377 }, false);</pre> | 377 }, false);</pre> |
378 <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> | 378 <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> |
379 | 379 |
380 <h2 id="security-considerations">Security considerations</h2> | 380 <h2 id="security-considerations">Security considerations</h2> |
381 | 381 |
382 <p>When writing a content script, you should be aware of two security issues. | 382 <p>When writing a content script, you should be aware of two security issues. |
383 First, be careful not to introduce security vulnerabilities into the web site | 383 First, be careful not to introduce security vulnerabilities into the web site |
384 your content script is injected into. For example, if your content script | 384 your content script is injected into. For example, if your content script |
385 receives content from another web site (for example, by making an <a | 385 receives content from another web site (for example, by making an <a |
386 href="xhr.html">XMLHttpRequest</a>), | 386 href="xhr">XMLHttpRequest</a>), |
387 be careful to filter that content for <a | 387 be careful to filter that content for <a |
388 href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site | 388 href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site |
389 scripting</a> attacks before injecting the content into the current page. | 389 scripting</a> attacks before injecting the content into the current page. |
390 For example, prefer to inject content via innerText rather than innerHTML. | 390 For example, prefer to inject content via innerText rather than innerHTML. |
391 Be especially careful when retrieving HTTP content on an HTTPS page because | 391 Be especially careful when retrieving HTTP content on an HTTPS page because |
392 the HTTP content might have been corrupted by a network <a | 392 the HTTP content might have been corrupted by a network <a |
393 href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">"man-in-the-middle"
</a> | 393 href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">"man-in-the-middle"
</a> |
394 if the user is on a hostile network.</p> | 394 if the user is on a hostile network.</p> |
395 | 395 |
396 <p>Second, although running your content script in an isolated world provides | 396 <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... |
435 <pre> | 435 <pre> |
436 <em>//Code for displaying <extensionDir>/images/myimage.png:</em> | 436 <em>//Code for displaying <extensionDir>/images/myimage.png:</em> |
437 var imgURL = <b>chrome.extension.getURL("images/myimage.png")</b>; | 437 var imgURL = <b>chrome.extension.getURL("images/myimage.png")</b>; |
438 document.getElementById("someImage").src = imgURL; | 438 document.getElementById("someImage").src = imgURL; |
439 </pre> | 439 </pre> |
440 | 440 |
441 <h2 id="examples"> Examples </h2> | 441 <h2 id="examples"> Examples </h2> |
442 | 442 |
443 <p> | 443 <p> |
444 You can find many | 444 You can find many |
445 <a href="samples.html#script">examples that use content scripts</a>. | 445 <a href="samples#script">examples that use content scripts</a>. |
446 A simple example of communication via messages is in the | 446 A simple example of communication via messages is in the |
447 <a href="samples.html#message-timer">Message Timer</a>. | 447 <a href="samples#message-timer">Message Timer</a>. |
448 See <a href="samples.html#page-redder">Page Redder</a> and | 448 See <a href="samples#page-redder">Page Redder</a> and |
449 <a href="samples.html#email-this-page-(by-google)">Email This Page</a> | 449 <a href="samples#email-this-page-(by-google)">Email This Page</a> |
450 for examples of programmatic injection. | 450 for examples of programmatic injection. |
451 </p> | 451 </p> |
452 | 452 |
453 | 453 |
454 <h2 id="videos"> Videos </h2> | 454 <h2 id="videos"> Videos </h2> |
455 | 455 |
456 <p> | 456 <p> |
457 The following videos discuss concepts that are important for content scripts. | 457 The following videos discuss concepts that are important for content scripts. |
458 The first video describes content scripts and isolated worlds. | 458 The first video describes content scripts and isolated worlds. |
459 </p> | 459 </p> |
460 | 460 |
461 <p> | 461 <p> |
462 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/laLudeUmXHM?rel=0" frameborder="0" allowfullscreen></iframe> | 462 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/laLudeUmXHM?rel=0" frameborder="0" allowfullscreen></iframe> |
463 </p> | 463 </p> |
464 | 464 |
465 <p> | 465 <p> |
466 The next video describes message passing, | 466 The next video describes message passing, |
467 featuring an example of a content script | 467 featuring an example of a content script |
468 sending a request to its parent extension. | 468 sending a request to its parent extension. |
469 </p> | 469 </p> |
470 | 470 |
471 <p> | 471 <p> |
472 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/B4M_a7xejYI?rel=0" frameborder="0" allowfullscreen></iframe> | 472 <iframe title="YouTube video player" width="640" height="390" src="//www.youtube
.com/embed/B4M_a7xejYI?rel=0" frameborder="0" allowfullscreen></iframe> |
473 </p> | 473 </p> |
OLD | NEW |