Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(75)

Side by Side Diff: chrome/common/extensions/docs/templates/articles/content_scripts.html

Issue 219213007: Remove .html extension from links (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Created 6 years, 7 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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
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
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
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
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 &mdash; 252 that matches the pattern &mdash;
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
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
435 <pre> 435 <pre>
436 <em>//Code for displaying &lt;extensionDir>/images/myimage.png:</em> 436 <em>//Code for displaying &lt;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>
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698