| 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 |