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

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 57 matching lines...) Expand 10 before | Expand all | Expand 10 after
199 The content script will be injected into a page if its URL matches any <code>mat ches</code> pattern and any <code>include_globs</code> pattern, as long as the U RL doesn't also match an <code>exclude_matches</code> or <code>exclude_globs</co de> pattern. 199 The content script will be injected into a page if its URL matches any <code>mat ches</code> pattern and any <code>include_globs</code> pattern, as long as the U RL doesn't also match an <code>exclude_matches</code> or <code>exclude_globs</co de> pattern.
200 200
201 Because the <code>matches</code> property is required, <code>exclude_matches</co de>, <code>include_globs</code>, and <code>exclude_globs</code> can only be used to limit which pages will be affected. 201 Because the <code>matches</code> property is required, <code>exclude_matches</co de>, <code>include_globs</code>, and <code>exclude_globs</code> can only be used to limit which pages will be affected.
202 </p> 202 </p>
203 203
204 <p> 204 <p>
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" and "http://www.nytimes.com/jobs/index" but not into "http://www.nytimes.com/sports /index".</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
264 <p> 264 <p>
265 The following code 265 The following code
266 (from the 266 (from the
267 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/browserAction/make_page_red/">make_page_red</a> example) 267 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension s/docs/examples/api/browserAction/make_page_red/">make_page_red</a> example)
268 reacts to a user click 268 reacts to a user click
269 by inserting JavaScript into the current tab's page 269 by inserting JavaScript into the current tab's page
270 and executing the script. 270 and executing the script.
271 </p> 271 </p>
272 272
273 <pre data-filename="background.html"> 273 <pre data-filename="background">
274 chrome.browserAction.onClicked.addListener(function(tab) { 274 chrome.browserAction.onClicked.addListener(function(tab) {
275 chrome.tabs.executeScript({ 275 chrome.tabs.executeScript({
276 code: 'document.body.style.backgroundColor="red"' 276 code: 'document.body.style.backgroundColor="red"'
277 }); 277 });
278 }); 278 });
279 </pre> 279 </pre>
280 <pre data-filename="manifest.json"> 280 <pre data-filename="manifest.json">
281 "permissions": [ 281 "permissions": [
282 "activeTab" 282 "activeTab"
283 ], 283 ],
(...skipping 16 matching lines...) Expand all
300 300
301 <pre>chrome.tabs.executeScript(null, {file: "content_script.js"});</pre> 301 <pre>chrome.tabs.executeScript(null, {file: "content_script.js"});</pre>
302 302
303 303
304 <h2 id="execution-environment">Execution environment</h2> 304 <h2 id="execution-environment">Execution environment</h2>
305 305
306 <p>Content scripts execute in a special environment called an <em>isolated world </em>. They have access to the DOM of the page they are injected into, but not t o any JavaScript variables or functions created by the page. It looks to each co ntent script as if there is no other JavaScript executing on the page it is runn ing on. The same is true in reverse: JavaScript running on the page cannot call any functions or access any variables defined by content scripts. 306 <p>Content scripts execute in a special environment called an <em>isolated world </em>. They have access to the DOM of the page they are injected into, but not t o any JavaScript variables or functions created by the page. It looks to each co ntent script as if there is no other JavaScript executing on the page it is runn ing on. The same is true in reverse: JavaScript running on the page cannot call any functions or access any variables defined by content scripts.
307 307
308 <p>For example, consider this simple page: 308 <p>For example, consider this simple page:
309 309
310 <pre data-filename="hello.html"> 310 <pre data-filename="hello">
311 &lt;html&gt; 311 &lt;html&gt;
312 &lt;button id="mybutton"&gt;click me&lt;/button&gt; 312 &lt;button id="mybutton"&gt;click me&lt;/button&gt;
313 &lt;script&gt; 313 &lt;script&gt;
314 var greeting = "hello, "; 314 var greeting = "hello, ";
315 var button = document.getElementById("mybutton"); 315 var button = document.getElementById("mybutton");
316 button.person_name = "Bob"; 316 button.person_name = "Bob";
317 button.addEventListener("click", function() { 317 button.addEventListener("click", function() {
318 alert(greeting + button.person_name + "."); 318 alert(greeting + button.person_name + ".");
319 }, false); 319 }, false);
320 &lt;/script&gt; 320 &lt;/script&gt;
321 &lt;/html&gt; 321 &lt;/html&gt;
322 </pre> 322 </pre>
323 323
324 <p>Now, suppose this content script was injected into hello.html: 324 <p>Now, suppose this content script was injected into hello:
325 325
326 <pre data-filename="contentscript.js"> 326 <pre data-filename="contentscript.js">
327 var greeting = "hola, "; 327 var greeting = "hola, ";
328 var button = document.getElementById("mybutton"); 328 var button = document.getElementById("mybutton");
329 button.person_name = "Roberto"; 329 button.person_name = "Roberto";
330 button.addEventListener("click", function() { 330 button.addEventListener("click", function() {
331 alert(greeting + button.person_name + "."); 331 alert(greeting + button.person_name + ".");
332 }, false); 332 }, false);
333 </pre> 333 </pre>
334 334
(...skipping 16 matching lines...) Expand all
351 // We only accept messages from ourselves 351 // We only accept messages from ourselves
352 if (event.source != window) 352 if (event.source != window)
353 return; 353 return;
354 354
355 if (event.data.type &amp;&amp; (event.data.type == "FROM_PAGE")) { 355 if (event.data.type &amp;&amp; (event.data.type == "FROM_PAGE")) {
356 console.log("Content script received: " + event.data.text); 356 console.log("Content script received: " + event.data.text);
357 port.postMessage(event.data.text); 357 port.postMessage(event.data.text);
358 } 358 }
359 }, false); 359 }, false);
360 </pre> 360 </pre>
361 <pre data-filename="http://foo.com/example.html"> 361 <pre data-filename="http://foo.com/example">
362 document.getElementById("theButton").addEventListener("click", 362 document.getElementById("theButton").addEventListener("click",
363 function() { 363 function() {
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 (which is not a part of the extension) posts me ssages 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 simil ar 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