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

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, 8 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>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
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
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 &mdash; 240 that matches the pattern &mdash;
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
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
423 <pre> 423 <pre>
424 <em>//Code for displaying &lt;extensionDir>/images/myimage.png:</em> 424 <em>//Code for displaying &lt;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>
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698