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

Side by Side Diff: chrome/common/extensions/docs/overview.html

Issue 225023: Another draft of the overview. Made related changes to the content scripts (Closed) Base URL: svn://chrome-svn/chrome/trunk/src/
Patch Set: '' Created 11 years, 3 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 | Annotate | Revision Log
OLDNEW
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
2 1) The <head> information in this page is significant, should be uniform 2 1) The <head> information in this page is significant, should be uniform
3 across api docs and should be edited only with knowledge of the 3 across api docs and should be edited only with knowledge of the
4 templating mechanism. 4 templating mechanism.
5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
6 browser, it will be re-generated from the template, json schema and 6 browser, it will be re-generated from the template, json schema and
7 authored overview content. 7 authored overview content.
8 4) The <body>.innerHTML is also generated by an offline step so that this 8 4) The <body>.innerHTML is also generated by an offline step so that this
9 page may easily be indexed by search engines. 9 page may easily be indexed by search engines.
10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head>
(...skipping 149 matching lines...) Expand 10 before | Expand all | Expand 10 after
160 </li><li jsinstance="2"> 160 </li><li jsinstance="2">
161 <a href="#arch">Architecture</a> 161 <a href="#arch">Architecture</a>
162 <ol> 162 <ol>
163 <li jsinstance="0"> 163 <li jsinstance="0">
164 <a href="#background">The background page</a> 164 <a href="#background">The background page</a>
165 </li><li jsinstance="*1"> 165 </li><li jsinstance="*1">
166 <a href="#contentScripts">Content scripts</a> 166 <a href="#contentScripts">Content scripts</a>
167 </li> 167 </li>
168 </ol> 168 </ol>
169 </li><li jsinstance="3"> 169 </li><li jsinstance="3">
170 <a href="#H2-7">Communication </a> 170 <a href="#H2-7">Communication between pages </a>
171 <ol> 171 <ol>
172 <li jsinstance="*0" style="display: none; "> 172 <li jsinstance="*0" style="display: none; ">
173 <a>h3Name</a> 173 <a>h3Name</a>
174 </li> 174 </li>
175 </ol> 175 </ol>
176 </li><li jsinstance="*4"> 176 </li><li jsinstance="*4">
177 <a href="#H2-8"> Summary </a> 177 <a href="#H2-8"> Summary </a>
178 <ol> 178 <ol>
179 <li jsinstance="*0" style="display: none; "> 179 <li jsinstance="*0" style="display: none; ">
180 <a>h3Name</a> 180 <a>h3Name</a>
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after
222 </div> 222 </div>
223 </ol> 223 </ol>
224 </div> 224 </div>
225 <!-- /TABLE OF CONTENTS --> 225 <!-- /TABLE OF CONTENTS -->
226 226
227 <!-- STATIC CONTENT PLACEHOLDER --> 227 <!-- STATIC CONTENT PLACEHOLDER -->
228 <div id="static"><div id="pageData-title" class="pageData">Overview</div > 228 <div id="static"><div id="pageData-title" class="pageData">Overview</div >
229 <div id="pageData-showTOC" class="pageData">true</div> 229 <div id="pageData-showTOC" class="pageData">true</div>
230 230
231 <p> 231 <p>
232 Please read this page; 232 Read this page!
233 it has vital information about the extension architecture. 233 It has vital information about the extension architecture.
234 If you get bored or restless, 234 Once you've finished this page
235 take a break! 235 and the
236 We suggest bouncing between this page 236 <a href="getstarted.html">Getting Started</a> tutorial,
237 and tutorials 237 you'll be all set to start writing extensions.
238 such as <a href="getstarted.html">Getting Started</a>
239 and <a href="tut_debugging.html">Debugging</a>.
240 </p> 238 </p>
241 239
242 240
243 <h2 id="what">The basics</h2> 241 <h2 id="what">The basics</h2>
244 242
245 <p> 243 <p>
246 An extension is a zipped bundle of files — 244 An extension is a zipped bundle of files —
247 HTML, CSS, JavaScript, images, and anything else you need — 245 HTML, CSS, JavaScript, images, and anything else you need —
248 that adds functionality to the Google Chrome browser. 246 that adds functionality to the Google Chrome browser.
249 Because an extension is just a special kind of web page, 247 Extensions are essentially web pages,
250 it can use all the APIs 248 and they can use all the APIs
251 that the browser provides 249 that the browser provides
252 to web pages and apps, 250 to web pages,
253 from XMLHttpRequest to JSON to localStorage. 251 from XMLHttpRequest to JSON to HTML5 local storage.
254 </p> 252 </p>
255 253
256 <p> 254 <p>
257 Extensions can add UI to Google Chrome, 255 Many extensions add UI to Google Chrome,
258 in the form of 256 in the form of
259 <a href="toolstrip.html">toolstrips</a> (toolbar additions) 257 <a href="toolstrip.html">toolstrips</a> (toolbar additions)
260 and <a href="pageActions.html">page actions</a> 258 or <a href="pageActions.html">page actions</a>
261 (clickable badges in the address bar). 259 (clickable badges in the address bar).
262 Extensions can also interact programmatically 260 Extensions can also interact programmatically
263 with browser features such as 261 with browser features such as
264 <a href="bookmarks.html">bookmarks</a> 262 <a href="bookmarks.html">bookmarks</a>
265 and <a href="tabs.html">tabs</a>. 263 and <a href="tabs.html">tabs</a>.
264 To interact with web pages or servers,
265 extensions can use
266 <a href="content_scripts.html">content scripts</a> or
267 <a href="xhr.html">cross-origin XMLHttpRequests</a>.
266 </p> 268 </p>
267 269
268 <p> 270 <p>
269 To find a complete list of extension features, 271 See the <a href="devguide.html">Developer's Guide</a>
272 for a complete list of extension features,
270 with implementation details 273 with implementation details
271 for each one, 274 for each one.
272 see the <a href="devguide.html">Developer's Guide</a>.
273 </p> 275 </p>
274 276
275 277
276 <h2 id="files">Files</h2> 278 <h2 id="files">Files</h2>
277 <p> 279 <p>
278 Each extension has the following files: 280 Each extension has the following files:
279 <!-- PENDING: This could use a picture --> 281 <!-- PENDING: This could use a picture -->
280 </p> 282 </p>
281 283
282 <ul> 284 <ul>
283 <li>A <b>manifest file</b></li> 285 <li>A <b>manifest file</b></li>
284 <li>One or more <b>HTML files</b> (unless the extension is a theme)</li> 286 <li>One or more <b>HTML files</b> (unless the extension is a theme)</li>
285 <li><em>Optional:</em> One or more <b>JavaScript files</b></li> 287 <li><em>Optional:</em> One or more <b>JavaScript files</b></li>
286 <li><em>Optional:</em> Any other files your extension needs — for example, ima ge files</li> 288 <li><em>Optional:</em> Any other files your extension needs —
289 for example, image files</li>
287 </ul> 290 </ul>
288 291
289 <p> 292 <p>
290 While you're working on your extension, 293 While you're working on your extension,
291 you put all these files into a single folder. 294 you put all these files into a single folder.
292 When you distribute your extension, 295 When you distribute your extension,
293 the contents of the folder are packaged into a special zipfile 296 the contents of the folder are packaged into a special ZIP file
294 that has a <code>.crx</code> suffix, 297 that has a <code>.crx</code> suffix,
295 as described in <a href="packaging.html">Packaging</a>. 298 as described in <a href="packaging.html">Packaging</a>.
296 </p> 299 </p>
297 300
298 301
299 <a name="H3-2"></a><h3>Referring to files</h3> 302 <a name="H3-2"></a><h3>Referring to files</h3>
300 303
301 <p> 304 <p>
302 You can put any file you like into an extension, 305 You can put any file you like into an extension,
303 but how do you use it? 306 but how do you use it?
304 Usually, 307 Usually,
305 you can refer to the file using a relative URL, 308 you can refer to the file using a relative URL,
306 just as you would in an ordinary HTML page. 309 just as you would in an ordinary HTML page.
307 Here's an example of referring to 310 Here's an example of referring to
308 a file named <code>myimage.png</code> 311 a file named <code>myimage.png</code>
309 that's in a subfolder named <code>images</code>. 312 that's in a subfolder named <code>images</code>.
310 </p> 313 </p>
311 314
312 <pre>&lt;img <b>src="images/myimage.png"</b> style="width:auto; height:auto"&gt; 315 <pre>&lt;img <b>src="images/myimage.png"</b>&gt;
313 </pre> 316 </pre>
314 317
315 <p> 318 <p>
316 As you might notice while you use the Google Chrome debugger, 319 As you might notice while you use the Google Chrome debugger,
317 every file in an extension is also accessible by an absolute URL like this: 320 every file in an extension is also accessible by an absolute URL like this:
318 </p> 321 </p>
319 322
320 <blockquote> 323 <blockquote>
321 <b>chrome-extension://</b><em>&lt;extensionID&gt;</em><b>/</b><em>&lt;pathToFile &gt;</em> 324 <b>chrome-extension://</b><em>&lt;extensionID&gt;</em><b>/</b><em>&lt;pathToFile &gt;</em>
322 </blockquote> 325 </blockquote>
323 326
324 <p> 327 <p>
325 In that URL, the <em>&lt;extensionID&gt;</em> is a unique identifier 328 In that URL, the <em>&lt;extensionID&gt;</em> is a unique identifier
326 that the extension system generates for each extension. 329 that the extension system generates for each extension.
327 You can see the IDs for all your loaded extensions 330 You can see the IDs for all your loaded extensions
328 by going to the URL <b>chrome://extensions/</b>. 331 by going to the URL <b>chrome://extensions/</b>.
329 The <em>&lt;pathToFile&gt;</em> is the location of the file 332 The <em>&lt;pathToFile&gt;</em> is the location of the file
330 under the extension's top folder; 333 under the extension's top folder;
331 it's the same as the relative URL. 334 it's the same as the relative URL.
332 </p> 335 </p>
333 336
334 <p> 337 <p class="comment">
335 For example, assume your extension has 338 [PENDING: Should mention/reflect/link to
336 the ID <b>aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</b> 339 <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">in ternationalization</a>
337 and the files shown in the following figure: 340 when it's ready.]
338 </p>
339
340 <pre><span class="tbd">[PENDING: someday this will be a real figure]</span>
341 toolstrip.html
342 styles.css
343 images:
344 myimage.png
345 ...
346 other:
347 more.html
348 morestyles.css
349 ...
350 </pre>
351
352 <p>
353 Here's a table that shows the relative and absolute URLs of these files.
354 Keep in mind that the relative URL is the same no matter where you're using it —
355 the relative URL of <code>myimage.png</code> is
356 <b>images/myimage.png</b>,
357 no matter whether it's being used by
358 <code>toolstrip.html</code> or <code>other/more.html</code>.
359 </p>
360
361 <table>
362 <tbody><tr>
363 <th> File </th>
364 <th> Relative URL </th>
365 <th> Absolute URL </th>
366 </tr>
367 <tr>
368 <td> toolstrip.html </td>
369 <td> toolstrip.html </td>
370 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/toolstrip.html </td>
371 </tr>
372 <tr>
373 <td> styles.css </td>
374 <td> styles.css </td>
375 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/styles.css </td>
376 </tr>
377 <tr>
378 <td> myimage.png </td>
379 <td> images/myimage.png </td>
380 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/images/myimage.png </ td>
381 </tr>
382 <tr>
383 <td> more.html </td>
384 <td> other/more.html </td>
385 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/more.html </td>
386 </tr>
387 <tr>
388 <td> morestyles.css </td>
389 <td> other/morestyles.css </td>
390 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/morestyles.css </td>
391 </tr>
392 </tbody></table>
393
394 <p class="tbd">
395 [PENDING: Mention/reflect/link to
396 <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">in ternationalization</a>]
397 </p> 341 </p>
398 342
399 343
400 <a name="H3-3"></a><h3>The manifest file</h3> 344 <a name="H3-3"></a><h3>The manifest file</h3>
401 345
402 <p> 346 <p>
403 The manifest file, called <code>manifest.json</code>, 347 The manifest file, called <code>manifest.json</code>,
404 gives information about the extension, 348 gives information about the extension,
405 such as the most important files 349 such as the most important files
406 and the capabilities that the extension might use. 350 and the capabilities that the extension might use.
(...skipping 11 matching lines...) Expand all
418 }</pre> 362 }</pre>
419 363
420 <p> 364 <p>
421 For details, see 365 For details, see
422 <a href="manifest.html">Manifest Files</a>. 366 <a href="manifest.html">Manifest Files</a>.
423 </p> 367 </p>
424 368
425 <h2 id="arch">Architecture</h2> 369 <h2 id="arch">Architecture</h2>
426 370
427 <p> 371 <p>
428 The following pictures shows the web pages associated with a typical extension 372 Remember that extensions are essentially web pages.
429 (in this case, a simple toolstrip). 373 The following figure shows what
430 The first figure shows what an extension might look like 374 a simple extension with a toolstrip
375 might look like
431 when there's a single browser window. 376 when there's a single browser window.
377 The toolstrip (T1) is at the bottom of the window.
378 The HTML and JavaScript code for T1
379 is in a web page
380 (<code>toolstrip.html</code>).
432 </p> 381 </p>
433 382
434 <p class="tbd"> [PENDING: image goes here] </p> 383 <img src="images/arch-1.gif">
435 384
436 <p> 385 <p>
437 The next figure shows that all the code in the extension's main HTML file 386 Each time the user creates a new window,
438 is duplicated each time you create a new window. 387 the browser creates new toolstrips, page actions, and so on.
439 In other words, each window has its own widgets for the extension, 388 Each new bit of UI gets its own web page,
440 which means each window adds another web page for that extension. 389 which means that toolstrips (for example)
390 that are in different windows can have different states.
391 In the following figure,
392 the two toolstrips (T1 and T2)
393 are associated with two separate web pages,
394 both of which contain code from <code>toolstrip.html</code>.
395 This means that although both toolstrips use the same code,
396 one can be blue while the other is green.
441 </p> 397 </p>
442 398
443 <p class="tbd"> [PENDING: image goes here] </p> 399 <img src="images/arch-2.gif">
444
445 <p>
446 To more easily coordinate all these web pages and to avoid duplication,
447 you should design your extension
448 so that most of the code —
449 especially the state of the extension —
450 is in a <em>background page</em>,
451 as shown in the following figure.
452 </p>
453
454 <p class="tbd"> [PENDING: image goes here] </p>
455 400
456 401
457 <h3 id="background">The background page</h3> 402 <h3 id="background">The background page</h3>
403
458 <p> 404 <p>
459 Any non-trivial extension can (and probably should) 405 If your extension's web pages need to communicate
460 have a background page. 406 or otherwise share information —
407 for example, if a browser event
408 can affect more than just one window's toolstrip —
409 the extension can use a background page.
410 The following figure shows a background page
411 (<code>background.html</code>)
412 that controls
413 the toolstrips in an extension.
414 </p>
415
416 <img src="images/arch-3.gif">
417
418 <p>
461 The background page is an invisible page 419 The background page is an invisible page
462 where you put the main logic of the extension. 420 where you can put the main logic of the extension.
463 The extension's other pages should have 421 The extension's other pages should have
464 only the code that's necessary 422 only the code that's necessary
465 to show the state of the extension 423 to show the state of the extension
466 and to get input from the user.</p> 424 and to get input from the user.</p>
467 425
468 <p> 426 <p>
469 An extension's background page exists
470 before any of the extension's other pages exist.
471 It continues to exist as long as the browser is running
472 and the extension is installed,
473 even if other pages and windows go away.
474 </p>
475
476 <p>
477 Your extension's UI —
478 its toolstrips, page actions, and so on —
479 should be dumb views.
480 When the view needs some state,
481 it should request it from the background page.
482 When the background page notices some state change,
483 it should update all the views.
484 </p>
485
486 <p>
487 For more information, see 427 For more information, see
488 <a href="background_pages.html">Background Pages</a>. 428 <a href="background_pages.html">Background Pages</a>.
489 </p> 429 </p>
490 430
491 <h3 id="contentScripts">Content scripts</h3> 431 <h3 id="contentScripts">Content scripts</h3>
492 432
493 <p> 433 <p>
494 If you want your extension to interact with web pages, 434 If your extension needs to interact with web pages,
495 you need a content script. 435 then it needs a <em>content script</em>.
496 Content scripts are JavaScript files that run in the context of web pages. 436 Content scripts are JavaScript files that run in the context of web pages.
497 By using the standard Document Object Model (DOM), 437 Using the standard
498 they can read details of the web pages the browser visits, 438 <a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document Object Model</a>
439 (DOM),
440 content scripts can read details of the web pages the browser visits,
499 and they can make changes to the pages. 441 and they can make changes to the pages.
500 </p> 442 </p>
501 443
444 <p>
445 In the following figure,
446 the content script
447 can read and modify
448 the DOM for the web page displayed in Window 1.
449 If the toolstrip's UI needs to change
450 to reflect the web page's contents,
451 the content script can request that change
452 by sending a message to the parent extension.
453 </p>
454
455 <img src="images/arch-cs.gif">
456
502 <p class="comment"> 457 <p class="comment">
503 [PENDING: add an architectural figure here, 458 [PENDING: Add overview of message passing.]
504 showing the extension's pages, a web page, and the content script
505 interacting with the web page. explain the figure.]
506 </p> 459 </p>
507 460
508 <p> 461 <p>
509 For more information, 462 For more information,
510 see <a href="content_scripts.html">Content Scripts</a>. 463 see <a href="content_scripts.html">Content Scripts</a>.
511 </p> 464 </p>
512 465
513 466
514 <a name="H2-7"></a><h2>Communication </h2> 467 <a name="H2-7"></a><h2>Communication between pages </h2>
515 468
516 <p> 469 <p>
517 Two kinds of communication happen within an extension: 470 The HTML pages within an extension often need to communicate.
471 An example is when the background page tells
472 UI pages (such as toolstrips)
473 to update their appearance.
474 Because all of an extension's pages
475 execute in same process on the same thread,
476 the pages can make direct function calls to each other.
518 </p> 477 </p>
519 478
520 <ul>
521 <li>
522 Communication <b>between pages</b> in the extension.
523 <br>
524 For example, sometimes the background page
525 needs to update all the UI pages
526 to reflect a change in the extension's state.
527 </li>
528 <li>
529 Communication <b>between content scripts and the extension</b>.
530 <br>
531 For example,
532 <span class="tbd">[PENDING: typical use case goes here]</span>.
533 See <a href="content_scripts.html">Content Scripts</a>
534 for information about this type of communication.
535 </li>
536 </ul>
537
538 <p> 479 <p>
539 Here are some keys to communication between an extension's pages: 480 To find pages in the extension, use
481 <a href="extension.html"><code>chrome.extension</code></a>
482 methods such as
483 <code>getViews()</code>,
484 <code>getBackgroundPage()</code>,
485 and <code>getToolstrips()</code>.
486 Once a page has a reference to other pages within the extension,
487 the first page can invoke functions on the other pages.
488 It can even manipulate their DOMs.
540 </p> 489 </p>
541 490
542 <ul>
543 <li>
544 All the extension's pages execute in same process,
545 on the same thread.
546 </li>
547 <li>
548 Extension pages can use
549 <a href="extension.html"><code>chrome.extension</code></a>
550 methods such as
551 <code>getViews()</code>,
552 <code>getBackgroundPage()</code>,
553 and <code>getToolstrips()</code>
554 to get access to the extension's pages.
555 </li>
556 <li>
557 Once you have references to an extension's pages,
558 you can manipulate the DOM for each page.
559 </li>
560 <li>
561 You can also make direct function calls to the pages,
562 as shown in the following example.
563 </li>
564 </ul>
565
566 <p> 491 <p>
567 Here's an example of 492 Here's an example of
568 communication between toolstrips and the background page. 493 communication between toolstrips and the background page.
569 </p> 494 </p>
570 495
571 <pre>//In background_page.html: 496 <pre>//In background.html:
572 function updateUI(checked) { 497 function updateUI(checked) {
573 var toolstrips = chrome.extension.getToolstrips(); 498 var toolstrips = chrome.extension.getToolstrips();
574 for (var i in toolstrips) { 499 for (var i in toolstrips) {
575 if (toolstrips[i].enableCheckbox) 500 if (toolstrips[i].enableCheckbox)
576 toolstrips[i].enableCheckbox(checked); 501 toolstrips[i].enableCheckbox(checked);
577 } 502 }
578 } 503 }
579 504
580 //In toolstrip.html: 505 //In toolstrip.html:
581 function enableCheckbox(checked) { 506 function enableCheckbox(checked) {
(...skipping 194 matching lines...) Expand 10 before | Expand all | Expand 10 after
776 urchinTracker(); 701 urchinTracker();
777 } 702 }
778 catch(e) {/* urchinTracker not available. */} 703 catch(e) {/* urchinTracker not available. */}
779 </script> 704 </script>
780 <!-- end analytics --> 705 <!-- end analytics -->
781 706
782 </div> <!-- /pageFooter --> 707 </div> <!-- /pageFooter -->
783 </div> <!-- /container --> 708 </div> <!-- /container -->
784 </body></html> 709 </body></html>
785 710
OLDNEW
« no previous file with comments | « chrome/common/extensions/docs/images/arch-cs.gif ('k') | chrome/common/extensions/docs/static/background_pages.html » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698