diff options
Diffstat (limited to 'chrome/common/extensions/docs/overview.html')
| -rwxr-xr-x | chrome/common/extensions/docs/overview.html | 723 |
1 files changed, 362 insertions, 361 deletions
diff --git a/chrome/common/extensions/docs/overview.html b/chrome/common/extensions/docs/overview.html index 4ea2eac..9305fff 100755 --- a/chrome/common/extensions/docs/overview.html +++ b/chrome/common/extensions/docs/overview.html @@ -2,173 +2,218 @@ 1) The <head> information in this page is significant, should be uniform across api docs and should be edited only with knowledge of the templating mechanism. - 2) The <body> tag *must* retain id="body" 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a browser, it will be re-generated from the template, json schema and authored overview content. 4) The <body>.innerHTML is also generated by an offline step so that this page may easily be indexed by search engines. - - TODO(rafaelw): Abstract this into a "pageshell" that becomes the single - version of page template shell and the "instance" pages (bookmarks.html, - etc...) can be generated with a build step. ---><!-- <html> must retain id="template --><html xmlns="http://www.w3.org/1999/xhtml" jstcache="0"><!-- <head> data is significant and loads the needed libraries and styles --><head jstcache="0"> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" jstcache="0"> - <title jscontent="getPageTitle()" jstcache="1">Overview</title> - <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css" jstcache="0"> - <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js" jstcache="0"> +--><html xmlns="http://www.w3.org/1999/xhtml"><head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> + <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> </script> - <script type="text/javascript" src="js/api_page_generator.js" jstcache="0"></script> - <script type="text/javascript" src="js/bootstrap.js" jstcache="0"></script> - </head><!-- <body> content is completely generated. Do not edit, as it will be - and rewritten. --><body jstcache="0"> <div id="container" jstcache="0"> - <a name="top" jstcache="0"> </a> + <script type="text/javascript" src="js/api_page_generator.js"></script> + <script type="text/javascript" src="js/bootstrap.js"></script> + <title>Overview</title></head><body> <div id="container"> + <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> + <!-- In particular, sub-templates that recursive, must be used by allowing + jstemplate to make a copy of the template in this section which + are not operated on by way of the jsskip="true" --> + <div style="display:none"> + + <!-- VALUE --> + <div id="valueTemplate"> + <dt> + <var>paramName</var> + <em> + + <!-- TYPE --> + <div style="display:inline"> + ( + <span class="optional">optional</span> + <span id="typeTemplate"> + <span> + <a> Type</a> + </span> + <span> + <span> + array of <span><span></span></span> + </span> + <span>paramType</span> + </span> + </span> + ) + </div> + + </em> + </dt> + <dd class="todo"> + Undocumented. + </dd> + <dd> + Description of this parameter from the json schema. + </dd> + + <!-- OBJECT PROPERTIES --> + <dd> + <dl> + <div> + <div> + </div> + </div> + </dl> + </dd> + </div> <!-- /VALUE --> + + </div> <!-- /SUBTEMPLATES --> + + <a name="top"> </a> <!-- API HEADER --> - <div id="pageHeader" jstcache="0"> - <div id="searchbox" jstcache="0"> - <form action="http://www.google.com/cse" id="cse-search-box" jstcache="0"> - <div jstcache="0"> - <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno" jstcache="0"> - <input type="hidden" name="ie" value="UTF-8" jstcache="0"> - <input type="text" name="q" size="31" jstcache="0"> - <input type="submit" name="sa" value="Search" jstcache="0"> + <div id="pageHeader"> + <div id="searchbox"> + <form action="http://www.google.com/cse" id="cse-search-box"> + <div> + <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> + <input type="hidden" name="ie" value="UTF-8"> + <input type="text" name="q" size="31"> + <input type="submit" name="sa" value="Search"> </div> </form> - <script type="text/javascript" src="http://www.google.com/jsapi" jstcache="0"></script> - <script type="text/javascript" jstcache="0">google.load("elements", "1", {packages: "transliteration"});</script> - <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-search-box&t13n_langs=en" jstcache="0"></script> - <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-search-box&lang=en" jstcache="0"></script> + <script type="text/javascript" src="http://www.google.com/jsapi"></script> + <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> + <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-search-box&t13n_langs=en"></script> + <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-search-box&lang=en"></script> </div> - <div id="pageTitle" jstcache="0"> - <h1 jscontent="getPageTitle()" jstcache="1">Overview</h1> + <div id="pageTitle"> + <h1>Overview</h1> </div> </div> <!-- /pageHeader --> - <div id="pageContent" jstcache="0"> + <div id="pageContent"> <!-- SIDENAV --> - <div id="leftNav" jstcache="0"> - <ul jstcache="0"> - <li jstcache="0"> <a href="index.html" jstcache="0">Home</a></li> - <li jstcache="0"> <a href="getstarted.html" jstcache="0">Getting Started</a></li> - <li jstcache="0" class="leftNavSelected">Overview </li> - <li jstcache="0"> <a href="devguide.html" jstcache="0"><div jstcache="0">Developer's Guide</div></a> - <ul jstcache="0"> - <li jstcache="0"><a href="toolstrip.html" jstcache="0">Toolstrips</a></li> - <li jstcache="0"><a href="pageActions.html" jstcache="0">Page Actions</a></li> - <li jstcache="0"><a href="background_pages.html" jstcache="0">Background Pages</a></li> - <li jstcache="0"><a href="content_scripts.html" jstcache="0">Content Scripts</a></li> - <li jstcache="0"><a href="events.html" jstcache="0">Events</a></li> - <li jstcache="0"><a href="tabs.html" jstcache="0">Tabs</a></li> - <li jstcache="0"><a href="windows.html" jstcache="0">Windows</a></li> - <li jstcache="0"><a href="bookmarks.html" jstcache="0">Bookmarks</a></li> - <li jstcache="0"><a href="themes.html" jstcache="0">Themes</a></li> - <li jstcache="0"><a href="npapi.html" jstcache="0">NPAPI Plugins</a></li> - <li jstcache="0"><a href="xhr.html" jstcache="0">Cross-Origin XHR</a></li> - <li jstcache="0"><a href="packaging.html" jstcache="0">Packaging</a></li> - <li jstcache="0">Autoupdate</li> + <div id="leftNav"> + <ul> + <li> <a href="index.html">Home</a></li> + <li> <a href="getstarted.html">Getting Started</a></li> + <li class="leftNavSelected">Overview </li> + <li> <a href="devguide.html"><div>Developer's Guide</div></a> + <ul> + <li><a href="toolstrip.html">Toolstrips</a></li> + <li><a href="pageActions.html">Page Actions</a></li> + <li><a href="background_pages.html">Background Pages</a></li> + <li><a href="content_scripts.html">Content Scripts</a></li> + <li><a href="events.html">Events</a></li> + <li><a href="tabs.html">Tabs</a></li> + <li><a href="windows.html">Windows</a></li> + <li><a href="bookmarks.html">Bookmarks</a></li> + <li><a href="themes.html">Themes</a></li> + <li><a href="npapi.html">NPAPI Plugins</a></li> + <li><a href="xhr.html">Cross-Origin XHR</a></li> + <li><a href="packaging.html">Packaging</a></li> + <li>Autoupdate</li> </ul> </li> - <li jstcache="0"><a href="tutorials.html" jstcache="0"><div jstcache="0">Tutorials</div></a> - <ul jstcache="0"> - <li jstcache="0"><a href="tut_debugging.html" jstcache="0">Debugging</a></li> + <li><a href="tutorials.html"><div>Tutorials</div></a> + <ul> + <li><a href="tut_debugging.html">Debugging</a></li> </ul> </li> - <li jstcache="0">Reference - <ul jstcache="0"> - <li jstcache="0"> Formats - <ul jstcache="0"> - <li jstcache="0"><a href="manifest.html" jstcache="0">Manifest Files</a></li> - <li jstcache="0"><a href="match_patterns.html" jstcache="0">Match Patterns</a></li> - <li jstcache="0">Packages (.crx)</li> + <li>Reference + <ul> + <li> Formats + <ul> + <li><a href="manifest.html">Manifest Files</a></li> + <li><a href="match_patterns.html">Match Patterns</a></li> + <li>Packages (.crx)</li> </ul> </li> - <li jstcache="0"> <a href="api_index.html" jstcache="0">chrome.* APIs</a> </li> - <li jstcache="0"> <a href="api_other.html" jstcache="0">Other APIs</a> </li> + <li> <a href="api_index.html">chrome.* APIs</a> </li> + <li> <a href="api_other.html">Other APIs</a> </li> </ul> </li> - <li jstcache="0"><a href="http://dev.chromium.org/developers/design-documents/extensions/samples" jstcache="0">Samples</a></li> + <li><a href="http://dev.chromium.org/developers/design-documents/extensions/samples">Samples</a></li> </ul> </div> - <div id="mainColumn" jstcache="0"> + <div id="mainColumn"> <!-- TABLE OF CONTENTS --> - <div id="toc" jsdisplay="showPageTOC()" jstcache="2"> - <p jstcache="0">Contents</p> - <ol jstcache="0"> - <li jsselect="getStaticTOC()" jstcache="9" jsinstance="0"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#what">The basics</a> - <ol jstcache="0"> - <li jsselect="$this.children" jstcache="22" jsinstance="*0" style="display: none; "> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">h3Name</a> + <div id="toc"> + <p>Contents</p> + <ol> + <li jsinstance="0"> + <a href="#what">The basics</a> + <ol> + <li jsinstance="*0" style="display: none; "> + <a>h3Name</a> </li> </ol> - </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="1"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#files">Files</a> - <ol jstcache="0"> - <li jsselect="$this.children" jstcache="22" jsinstance="0"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H3-2">Referring to files</a> - </li><li jsselect="$this.children" jstcache="22" jsinstance="*1"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H3-3">The manifest file</a> + </li><li jsinstance="1"> + <a href="#files">Files</a> + <ol> + <li jsinstance="0"> + <a href="#H3-2">Referring to files</a> + </li><li jsinstance="*1"> + <a href="#H3-3">The manifest file</a> </li> </ol> - </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="2"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#arch">Architecture</a> - <ol jstcache="0"> - <li jsselect="$this.children" jstcache="22" jsinstance="0"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#background">The background page</a> - </li><li jsselect="$this.children" jstcache="22" jsinstance="*1"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#contentScripts">Content scripts</a> + </li><li jsinstance="2"> + <a href="#arch">Architecture</a> + <ol> + <li jsinstance="0"> + <a href="#background">The background page</a> + </li><li jsinstance="*1"> + <a href="#contentScripts">Content scripts</a> </li> </ol> - </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="3"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H2-7">Communication </a> - <ol jstcache="0"> - <li jsselect="$this.children" jstcache="22" jsinstance="*0" style="display: none; "> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">h3Name</a> + </li><li jsinstance="3"> + <a href="#H2-7">Communication </a> + <ol> + <li jsinstance="*0" style="display: none; "> + <a>h3Name</a> </li> </ol> - </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="*4"> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H2-8"> Summary </a> - <ol jstcache="0"> - <li jsselect="$this.children" jstcache="22" jsinstance="*0" style="display: none; "> - <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">h3Name</a> + </li><li jsinstance="*4"> + <a href="#H2-8"> Summary </a> + <ol> + <li jsinstance="*0" style="display: none; "> + <a>h3Name</a> </li> </ol> </li> - <div jsselect="apiDefinition" jstcache="3" style="display: none; "> - <li jstcache="0"> - <a href="#apiReference" jscontent="'API reference: ' + getModuleName()" jstcache="4">API reference</a> - <ol jstcache="0"> - <li jsdisplay="$this.properties" jstcache="5"> - <a href="#properties" jstcache="0">Properties</a> - <ol jstcache="0"> - <li jsselect="getPropertyListFromObject($this)" jstcache="10"> - <a jscontent="name" jsvalues=".href:'#property-' + name" href="#property-anchor" jstcache="42">propertyName</a> + <div style="display: none; "> + <li> + <a href="#apiReference">API reference</a> + <ol> + <li> + <a href="#properties">Properties</a> + <ol> + <li> + <a href="#property-anchor">propertyName</a> </li> </ol> </li> - <li jsdisplay="functions && functions.length > 0" jstcache="6"> - <a href="#methods" jstcache="0">Methods</a> - <ol jstcache="0"> - <li jsselect="functions.sort(sortByName)" jstcache="11"> - <a jscontent="name" jsvalues=".href:'#method-' + name" href="#method-anchor" jstcache="43">methodName</a> + <li> + <a href="#methods">Methods</a> + <ol> + <li> + <a href="#method-anchor">methodName</a> </li> </ol> </li> - <li jsdisplay="events && events.length > 0" jstcache="7"> - <a href="#events" jstcache="0">Events</a> - <ol jstcache="0"> - <li jsselect="events.sort(sortByName)" jstcache="12"> - <a jscontent="name" jsvalues=".href:'#event-' + name" href="#event-anchor" jstcache="44">eventName</a> + <li> + <a href="#events">Events</a> + <ol> + <li> + <a href="#event-anchor">eventName</a> </li> </ol> </li> - <li jsdisplay="types && types.length > 0" jstcache="8"> - <a href="#types" jstcache="0">Types</a> - <ol jstcache="0"> - <li jsselect="types.sort(sortByName)" jstcache="38"> - <a jscontent="id" jsvalues=".href:'#type-' + id" href="#id-anchor" jstcache="45">id</a> + <li> + <a href="#types">Types</a> + <ol> + <li> + <a href="#id-anchor">id</a> </li> </ol> </li> @@ -180,24 +225,24 @@ <!-- /TABLE OF CONTENTS --> <!-- STATIC CONTENT PLACEHOLDER --> - <div id="static" jstcache="0"><div id="pageData-title" class="pageData" jstcache="0">Overview</div> -<div id="pageData-showTOC" class="pageData" jstcache="0">true</div> + <div id="static"><div id="pageData-title" class="pageData">Overview</div> +<div id="pageData-showTOC" class="pageData">true</div> -<p jstcache="0"> +<p> Please read this page; it has vital information about the extension architecture. If you get bored or restless, take a break! We suggest bouncing between this page and tutorials -such as <a href="getstarted.html" jstcache="0">Getting Started</a> -and <a href="tut_debugging.html" jstcache="0">Debugging</a>. +such as <a href="getstarted.html">Getting Started</a> +and <a href="tut_debugging.html">Debugging</a>. </p> -<h2 id="what" jstcache="0">The basics</h2> +<h2 id="what">The basics</h2> -<p jstcache="0"> +<p> An extension is a zipped bundle of files — HTML, CSS, JavaScript, images, and anything else you need — that adds functionality to the Google Chrome browser. @@ -208,91 +253,91 @@ to web pages and apps, from XMLHttpRequest to JSON to localStorage. </p> -<p jstcache="0"> +<p> Extensions can add UI to Google Chrome, in the form of -<a href="toolstrip.html" jstcache="0">toolstrips</a> (toolbar additions) -and <a href="pageActions.html" jstcache="0">page actions</a> +<a href="toolstrip.html">toolstrips</a> (toolbar additions) +and <a href="pageActions.html">page actions</a> (clickable badges in the address bar). Extensions can also interact programmatically with browser features such as -<a href="bookmarks.html" jstcache="0">bookmarks</a> -and <a href="tabs.html" jstcache="0">tabs</a>. +<a href="bookmarks.html">bookmarks</a> +and <a href="tabs.html">tabs</a>. </p> -<p jstcache="0"> +<p> To find a complete list of extension features, with implementation details for each one, -see the <a href="devguide.html" jstcache="0">Developer's Guide</a>. +see the <a href="devguide.html">Developer's Guide</a>. </p> -<h2 id="files" jstcache="0">Files</h2> -<p jstcache="0"> +<h2 id="files">Files</h2> +<p> Each extension has the following files: <!-- PENDING: This could use a picture --> </p> -<ul jstcache="0"> - <li jstcache="0">A <b jstcache="0">manifest file</b></li> - <li jstcache="0">One or more <b jstcache="0">HTML files</b> (unless the extension is a theme)</li> - <li jstcache="0"><em jstcache="0">Optional:</em> One or more <b jstcache="0">JavaScript files</b></li> - <li jstcache="0"><em jstcache="0">Optional:</em> Any other files your extension needs — for example, image files</li> +<ul> + <li>A <b>manifest file</b></li> + <li>One or more <b>HTML files</b> (unless the extension is a theme)</li> + <li><em>Optional:</em> One or more <b>JavaScript files</b></li> + <li><em>Optional:</em> Any other files your extension needs — for example, image files</li> </ul> -<p jstcache="0"> +<p> While you're working on your extension, you put all these files into a single folder. When you distribute your extension, the contents of the folder are packaged into a special zipfile -that has a <code jstcache="0">.crx</code> suffix, -as described in <a href="packaging.html" jstcache="0">Packaging</a>. +that has a <code>.crx</code> suffix, +as described in <a href="packaging.html">Packaging</a>. </p> -<a name="H3-2" jstcache="0"></a><h3 jstcache="0">Referring to files</h3> +<a name="H3-2"></a><h3>Referring to files</h3> -<p jstcache="0"> +<p> You can put any file you like into an extension, but how do you use it? Usually, you can refer to the file using a relative URL, just as you would in an ordinary HTML page. Here's an example of referring to -a file named <code jstcache="0">myimage.png</code> -that's in a subdirectory named <code jstcache="0">images</code>. +a file named <code>myimage.png</code> +that's in a subdirectory named <code>images</code>. </p> -<pre jstcache="0"><img <b jstcache="0">src="images/myimage.png"</b> style="width:auto; height:auto"> +<pre><img <b>src="images/myimage.png"</b> style="width:auto; height:auto"> </pre> -<p jstcache="0"> +<p> As you might notice while you use the Google Chrome debugger, every file in an extension is also accessible by an absolute URL like this: </p> -<blockquote jstcache="0"> -<b jstcache="0">chrome-extension://</b><em jstcache="0"><extensionID></em><b jstcache="0">/</b><em jstcache="0"><pathToFile></em> +<blockquote> +<b>chrome-extension://</b><em><extensionID></em><b>/</b><em><pathToFile></em> </blockquote> -<p jstcache="0"> -In that URL, the <em jstcache="0"><extensionID></em> is a unique identifier +<p> +In that URL, the <em><extensionID></em> is a unique identifier that the extension system generates for each extension. You can see the IDs for all your loaded extensions -by going to the URL <b jstcache="0">chrome://extensions/</b>. -The <em jstcache="0"><pathToFile></em> is the location of the file +by going to the URL <b>chrome://extensions/</b>. +The <em><pathToFile></em> is the location of the file under the extension's top directory; it's the same as the relative URL. </p> -<p jstcache="0"> +<p> For example, assume your extension has -the ID <b jstcache="0">aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</b> +the ID <b>aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</b> and the files shown in the following figure: </p> -<pre jstcache="0"><span class="tbd" jstcache="0">[PENDING: someday this will be a real figure]</span> +<pre><span class="tbd">[PENDING: someday this will be a real figure]</span> toolstrip.html styles.css images: @@ -304,58 +349,58 @@ other: ... </pre> -<p jstcache="0"> +<p> Here's a table that shows the relative and absolute URLs of these files. Keep in mind that the relative URL is the same no matter where you're using it — -the relative URL of <code jstcache="0">myimage.png</code> is -<b jstcache="0">images/myimage.png</b>, +the relative URL of <code>myimage.png</code> is +<b>images/myimage.png</b>, no matter whether it's being used by -<code jstcache="0">toolstrip.html</code> or <code jstcache="0">other/more.html</code>. +<code>toolstrip.html</code> or <code>other/more.html</code>. </p> -<table jstcache="0"> -<tbody jstcache="0"><tr jstcache="0"> - <th jstcache="0"> File </th> - <th jstcache="0"> Relative URL </th> - <th jstcache="0"> Absolute URL </th> +<table> +<tbody><tr> + <th> File </th> + <th> Relative URL </th> + <th> Absolute URL </th> </tr> -<tr jstcache="0"> - <td jstcache="0"> toolstrip.html </td> - <td jstcache="0"> toolstrip.html </td> - <td jstcache="0"> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/toolstrip.html </td> +<tr> + <td> toolstrip.html </td> + <td> toolstrip.html </td> + <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/toolstrip.html </td> </tr> -<tr jstcache="0"> - <td jstcache="0"> styles.css </td> - <td jstcache="0"> styles.css </td> - <td jstcache="0"> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/styles.css </td> +<tr> + <td> styles.css </td> + <td> styles.css </td> + <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/styles.css </td> </tr> -<tr jstcache="0"> - <td jstcache="0"> myimage.png </td> - <td jstcache="0"> images/myimage.png </td> - <td jstcache="0"> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/images/myimage.png </td> +<tr> + <td> myimage.png </td> + <td> images/myimage.png </td> + <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/images/myimage.png </td> </tr> -<tr jstcache="0"> - <td jstcache="0"> more.html </td> - <td jstcache="0"> other/more.html </td> - <td jstcache="0"> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/more.html </td> +<tr> + <td> more.html </td> + <td> other/more.html </td> + <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/more.html </td> </tr> -<tr jstcache="0"> - <td jstcache="0"> morestyles.css </td> - <td jstcache="0"> other/morestyles.css </td> - <td jstcache="0"> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/morestyles.css </td> +<tr> + <td> morestyles.css </td> + <td> other/morestyles.css </td> + <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/morestyles.css </td> </tr> </tbody></table> -<p class="tbd" jstcache="0"> +<p class="tbd"> [PENDING: Mention/reflect/link to -<a href="http://dev.chromium.org/developers/design-documents/extensions/i18n" jstcache="0">internationalization</a>] +<a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">internationalization</a>] </p> -<a name="H3-3" jstcache="0"></a><h3 jstcache="0">The manifest file</h3> +<a name="H3-3"></a><h3>The manifest file</h3> -<p jstcache="0"> -The manifest file, called <code jstcache="0">manifest.json</code>, +<p> +The manifest file, called <code>manifest.json</code>, gives information about the extension, such as the most important files and the capabilities that the extension might use. @@ -363,7 +408,7 @@ Here's a typical manifest file for a toolstrip that uses information from google.com: </p> -<pre jstcache="0">{ +<pre>{ "name": "My Extension", "version": "2.1", "description": "Gets information from Google.", @@ -372,45 +417,45 @@ that uses information from google.com: "toolstrips": ["my_toolstrip.html"] }</pre> -<p jstcache="0"> +<p> For details, see -<a href="manifest.html" jstcache="0">Manifest Files</a>. +<a href="manifest.html">Manifest Files</a>. </p> -<h2 id="arch" jstcache="0">Architecture</h2> +<h2 id="arch">Architecture</h2> -<p jstcache="0"> +<p> The following pictures shows the web pages associated with a typical extension (in this case, a simple toolstrip). The first figure shows what an extension might look like when there's a single browser window. </p> -<p class="tbd" jstcache="0"> [PENDING: image goes here] </p> +<p class="tbd"> [PENDING: image goes here] </p> -<p jstcache="0"> +<p> The next figure shows that all the code in the extension's main HTML file is duplicated each time you create a new window. In other words, each window has its own widgets for the extension, which means each window adds another web page for that extension. </p> -<p class="tbd" jstcache="0"> [PENDING: image goes here] </p> +<p class="tbd"> [PENDING: image goes here] </p> -<p jstcache="0"> +<p> To more easily coordinate all these web pages and to avoid duplication, you should design your extension so that most of the code — especially the state of the extension — -is in a <em jstcache="0">background page</em>, +is in a <em>background page</em>, as shown in the following figure. </p> -<p class="tbd" jstcache="0"> [PENDING: image goes here] </p> +<p class="tbd"> [PENDING: image goes here] </p> -<h3 id="background" jstcache="0">The background page</h3> -<p jstcache="0"> +<h3 id="background">The background page</h3> +<p> Any non-trivial extension can (and probably should) have a background page. The background page is an invisible page @@ -420,7 +465,7 @@ only the code that's necessary to show the state of the extension and to get input from the user.</p> -<p jstcache="0"> +<p> An extension's background page exists before any of the extension's other pages exist. It continues to exist as long as the browser is running @@ -428,7 +473,7 @@ and the extension is installed, even if other pages and windows go away. </p> -<p jstcache="0"> +<p> Your extension's UI — its toolstrips, page actions, and so on — should be dumb views. @@ -438,14 +483,14 @@ When the background page notices some state change, it should update all the views. </p> -<p jstcache="0"> +<p> For more information, see -<a href="background_pages.html" jstcache="0">Background Pages</a>. +<a href="background_pages.html">Background Pages</a>. </p> -<h3 id="contentScripts" jstcache="0">Content scripts</h3> +<h3 id="contentScripts">Content scripts</h3> -<p jstcache="0"> +<p> If you want your extension to interact with web pages, you need a content script. Content scripts are JavaScript files that run in the context of web pages. @@ -454,76 +499,76 @@ they can read details of the web pages the browser visits, and they can make changes to the pages. </p> -<p class="comment" jstcache="0"> +<p class="comment"> [PENDING: add an architectural figure here, showing the extension's pages, a web page, and the content script interacting with the web page. explain the figure.] </p> -<p jstcache="0"> +<p> For more information, -see <a href="content_scripts.html" jstcache="0">Content Scripts</a>. +see <a href="content_scripts.html">Content Scripts</a>. </p> -<a name="H2-7" jstcache="0"></a><h2 jstcache="0">Communication </h2> +<a name="H2-7"></a><h2>Communication </h2> -<p jstcache="0"> +<p> Two kinds of communication happen within an extension: </p> -<ul jstcache="0"> - <li jstcache="0"> - Communication <b jstcache="0">between pages</b> in the extension. - <br jstcache="0"> +<ul> + <li> + Communication <b>between pages</b> in the extension. + <br> For example, sometimes the background page needs to update all the UI pages to reflect a change in the extension's state. </li> - <li jstcache="0"> - Communication <b jstcache="0">between content scripts and the extension</b>. - <br jstcache="0"> + <li> + Communication <b>between content scripts and the extension</b>. + <br> For example, - <span class="tbd" jstcache="0">[PENDING: typical use case goes here]</span>. - See <a href="content_scripts.html" jstcache="0">Content Scripts</a> + <span class="tbd">[PENDING: typical use case goes here]</span>. + See <a href="content_scripts.html">Content Scripts</a> for information about this type of communication. </li> </ul> -<p jstcache="0"> +<p> Here are some keys to communication between an extension's pages: </p> -<ul jstcache="0"> - <li jstcache="0"> +<ul> + <li> All the extension's pages execute in same process, on the same thread. </li> - <li jstcache="0"> + <li> Extension pages can use - <a href="extension.html" jstcache="0"><code jstcache="0">chrome.extension</code></a> + <a href="extension.html"><code>chrome.extension</code></a> methods such as - <code jstcache="0">getViews()</code>, - <code jstcache="0">getBackgroundPage()</code>, - and <code jstcache="0">getToolstrips()</code> + <code>getViews()</code>, + <code>getBackgroundPage()</code>, + and <code>getToolstrips()</code> to get access to the extension's pages. </li> - <li jstcache="0"> + <li> Once you have references to an extension's pages, you can manipulate the DOM for each page. </li> - <li jstcache="0"> + <li> You can also make direct function calls to the pages, as shown in the following example. </li> </ul> -<p jstcache="0"> +<p> Here's an example of communication between toolstrips and the background page. </p> -<pre jstcache="0">//In background_page.html: +<pre>//In background_page.html: function updateUI(checked) { var toolstrips = chrome.extension.getToolstrips(); for (var i in toolstrips) { @@ -539,144 +584,100 @@ function enableCheckbox(checked) { } </pre> -<p jstcache="0"> +<p> A good summary of communication mechanisms is at -<a href="http://www.chromeplugins.org/google/plugins-development/communication-7883.html" jstcache="0">http://www.chromeplugins.org/google/plugins-development/communication-7883.html</a>. +<a href="http://www.chromeplugins.org/google/plugins-development/communication-7883.html">http://www.chromeplugins.org/google/plugins-development/communication-7883.html</a>. </p> -<a name="H2-8" jstcache="0"></a><h2 jstcache="0"> Summary </h2> +<a name="H2-8"></a><h2> Summary </h2> -<p class="tbd" jstcache="0"> +<p class="tbd"> [ PENDING: summarize, suggest where to go next. Probably: -<a href="getstarted.html" jstcache="0">Getting Started</a>, -<a href="tut_debugging.html" jstcache="0">Debugging</a>, -<a href="devguide.html" jstcache="0">Developer's Guide</a>. +<a href="getstarted.html">Getting Started</a>, +<a href="tut_debugging.html">Debugging</a>, +<a href="devguide.html">Developer's Guide</a>. ] </p> </div> <!-- API PAGE --> - <div class="apiPage" jsselect="apiDefinition" jstcache="3" style="display: none; "> - <a name="apiReference" jstcache="0"></a> - <h2 jscontent="'API reference: ' + getModuleName()" jstcache="4">API reference: chrome.apiname </h2> + <div class="apiPage" style="display: none; "> + <a name="apiReference"></a> + <h2>API reference: chrome.apiname </h2> <!-- PROPERTIES --> - <div jsdisplay="$this.properties" class="apiGroup" jstcache="5"> - <a name="properties" jstcache="0"></a> - <h3 id="properties" jstcache="0">Properties</h3> - - <div jsselect="getPropertyListFromObject($this)" jstcache="10"> - <a jsvalues=".name:'property-' + name" jstcache="15"></a> - <h4 jscontent="name" jstcache="16">getLastError</h4> - <div class="summary" jstcache="0"> + <div class="apiGroup"> + <a name="properties"></a> + <h3 id="properties">Properties</h3> + + <div> + <a></a> + <h4>getLastError</h4> + <div class="summary"> <!-- Note: intentionally longer 80 columns --> - <span jscontent="getModuleName() + '.'" jstcache="23">chrome.extension</span><span jscontent="$this.name" jstcache="24">lastError</span> + <span>chrome.extension</span><span>lastError</span> </div> - <div transclude="valueTemplate" jstcache="17"> + <div> </div> </div> </div> <!-- /apiGroup --> <!-- METHODS --> - <div jsdisplay="functions && functions.length > 0" class="apiGroup" id="methods" jstcache="6"> - <a name="methods" jstcache="0"></a> - <h3 jstcache="0">Methods</h3> + <div class="apiGroup" id="methods"> + <a name="methods"></a> + <h3>Methods</h3> <!-- iterates over all functions --> - <div class="apiItem" jsselect="functions.sort(sortByName)" jstcache="11"> - <a jsvalues=".name:'method-' + name" jstcache="18"></a> <!-- method-anchor --> - <h4 jscontent="name" jstcache="16">method name</h4> + <div class="apiItem"> + <a></a> <!-- method-anchor --> + <h4>method name</h4> - <div class="summary" jstcache="0"><span jsdisplay="returns" jscontent="getTypeName(returns)" jstcache="25">void</span> + <div class="summary"><span>void</span> <!-- Note: intentionally longer 80 columns --> - <span jscontent="getFullyQualifiedFunctionName($this)" jstcache="26">chrome.module.methodName</span>(<span jsselect="parameters" jsvalues="class:optional ? 'optional' : ''" jstcache="27"><span jsdisplay="$index" jstcache="33">, </span><span jscontent="getTypeName($this)" jstcache="34"></span> - <var jstcache="0"><span jscontent="name" jstcache="16"></span></var></span>)</div> + <span>chrome.module.methodName</span>(<span><span>, </span><span></span> + <var><span></span></var></span>)</div> - <div class="description" jstcache="0"> - <p class="todo" jsdisplay="!description" jstcache="28">Undocumented.</p> - <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="29"> + <div class="description"> + <p class="todo">Undocumented.</p> + <p> A description from the json schema def of the function goes here. </p> <!-- PARAMETERS --> - <h4 jstcache="0">Parameters</h4> - <dl jstcache="0"> - <div jsselect="parameters" jstcache="35"> - - <!-- VALUE: This is a subtemplate that is used elsewhere - via jsTemplate *transclude* --> - <div id="valueTemplate" jstcache="0"> - <dt jstcache="0"> - <var jsdisplay="$this.name" jscontent="$this.name" jstcache="46">paramName</var> - <em jstcache="0"> - - <!-- TYPE --> - <div style="display:inline" jstcache="0"> - ( - <span class="optional" jsdisplay="optional" jstcache="47">optional</span> - <span id="typeTemplate" jstcache="0"> - <span jsdisplay="getTypeRef($this)" jstcache="48"> - <a jsvalues=".href: getTypeRefPage($this) + '#type-' + getTypeRef($this)" jscontent="getTypeRef($this)" jstcache="50"> Type</a> - </span> - <span jsdisplay="!getTypeRef($this)" jstcache="49"> - <span jsdisplay="isArray($this)" jstcache="51"> - array of <span jsselect="items" jstcache="53"><span transclude="typeTemplate" jstcache="54"></span></span> - </span> - <span jsdisplay="!isArray($this)" jscontent="getTypeName($this)" jstcache="52">paramType</span> - </span> - </span> - ) - </div> - - </em> - </dt> - <dd class="todo" jsdisplay="!$this.description" jstcache="39"> - Undocumented. - </dd> - <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description" jstcache="40"> - Description of this parameter from the json schema. - </dd> - - <!-- OBJECT PROPERTIES --> - <dd jsdisplay="shouldExpandObject($this)" jstcache="41"> - <dl jstcache="0"> - <div jsselect="getPropertyListFromObject($this)" jstcache="10"> - <div transclude="valueTemplate" jstcache="17"> - </div> - </div> - </dl> - </dd> - </div> <!-- /VALUE --> - + <h4>Parameters</h4> + <dl> + <div> + <div> + </div> </div> </dl> <!-- RETURNS --> - <h4 jsdisplay="returns" jstcache="30">Returns</h4> - <dl jstcache="0"> - <div jsselect="returns" jstcache="36"> - <div transclude="valueTemplate" jstcache="17"> + <h4>Returns</h4> + <dl> + <div> + <div> </div> </div> </dl> <!-- CALLBACK --> - <div jsdisplay="hasCallback(parameters)" jstcache="31"> - <div jsselect="getCallbackParameters(parameters)" jstcache="37"> - <h4 jstcache="0">Callback function</h4> - <p jstcache="0"> - If you specify the <em jstcache="0">callback</em> parameter, + <div> + <div> + <h4>Callback function</h4> + <p> + If you specify the <em>callback</em> parameter, it should specify a function that looks like this: </p> <!-- Note: intentionally longer 80 columns --> - <pre jstcache="0">function(<span jscontent="getSignatureString(parameters)" jstcache="32">Type param1, Type param2</span>) <span class="subdued" jstcache="0">{...}</span>);</pre> - <dl jstcache="0"> - <div jsselect="parameters" jstcache="35"> - <div transclude="valueTemplate" jstcache="17"> + <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre> + <dl> + <div> + <div> </div> </div> </dl> @@ -690,31 +691,31 @@ PENDING: summarize, suggest where to go next. Probably: </div> <!-- /apiGroup --> <!-- EVENTS --> - <div jsdisplay="events && events.length > 0" class="apiGroup" jstcache="7"> - <a name="events" jstcache="0"></a> - <h3 id="events" jstcache="0">Events</h3> + <div class="apiGroup"> + <a name="events"></a> + <h3 id="events">Events</h3> <!-- iterates over all events --> - <div jsselect="events.sort(sortByName)" class="apiItem" jstcache="12"> - <a jsvalues=".name:'event-' + name" jstcache="19"></a> - <h4 jscontent="name" jstcache="16">event name</h4> + <div class="apiItem"> + <a></a> + <h4>event name</h4> - <div class="summary" jstcache="0"> + <div class="summary"> <!-- Note: intentionally longer 80 columns --> - <span jscontent="getModuleName() + '.'" class="subdued" jstcache="23">chrome.bookmarks</span><span jscontent="name" jstcache="16">onEvent</span><span class="subdued" jstcache="0">.addListener</span>(function(<span jscontent="getSignatureString(parameters)" jstcache="32">Type param1, Type param2</span>) <span class="subdued" jstcache="0">{...}</span>); + <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); </div> - <div class="description" jstcache="0"> - <p class="todo" jsdisplay="!description" jstcache="28">Undocumented.</p> - <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="29"> + <div class="description"> + <p class="todo">Undocumented.</p> + <p> A description from the json schema def of the event goes here. </p> <!-- PARAMETERS --> - <h4 jstcache="0">Parameters</h4> - <dl jstcache="0"> - <div jsselect="parameters" jstcache="35"> - <div transclude="valueTemplate" jstcache="17"> + <h4>Parameters</h4> + <dl> + <div> + <div> </div> </div> </dl> @@ -726,16 +727,16 @@ PENDING: summarize, suggest where to go next. Probably: </div> <!-- /apiGroup --> <!-- TYPES --> - <div jsdisplay="types && types.length > 0" class="apiGroup" jstcache="8"> - <a name="types.sort(sortByName)" jstcache="0"></a> - <h3 id="types" jstcache="0">Types</h3> + <div class="apiGroup"> + <a name="types.sort(sortByName)"></a> + <h3 id="types">Types</h3> <!-- iterates over all types --> - <div jsselect="types" class="apiItem" jstcache="13"> - <a jsvalues=".name:'type-' + id" jstcache="20"></a> - <h4 jscontent="id" jstcache="21">type name</h4> + <div class="apiItem"> + <a></a> + <h4>type name</h4> - <div transclude="valueTemplate" jstcache="17"> + <div> </div> </div> <!-- /apiItem --> @@ -745,17 +746,17 @@ PENDING: summarize, suggest where to go next. Probably: </div> <!-- /apiPage --> </div> <!-- /mainColumn --> </div> <!-- /pageContent --> - <div id="pageFooter" --="" jstcache="0"> - <p jstcache="0"> - Except as otherwise <a href="http://code.google.com/policies.html#restrictions" jstcache="0">noted</a>, - the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/" jstcache="0">Creative Commons + <div id="pageFooter" --=""> + <p> + Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, + the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>, and code samples are licensed under the - <a rel="license" href="http://code.google.com/google_bsd_license.html" jstcache="0">BSD License</a>. + <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. </p> - <p jstcache="0"> + <p> ©2009 Google </p> </div> <!-- /pageFooter --> </div> <!-- /container --> </body></html> -#EOF + |