| 1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc.
Note: 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 mecha
nism. 2) The <body> tag *must* retain id="body" 3) All <body>.innerHTML is gener
eated 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>.innerHTM
L is also generated by an offline step so that this page may easily be indexed b
y search engines. TODO(rafaelw): Abstract this into a "pageshell" that becomes t
he single version of page template shell and the "instance" pages (bookmarks.htm
l, etc...) can be generated with a build step. --><!-- <html> must retain id="te
mplate --><html xmlns="http://www.w3.org/1999/xhtml" jstcache="0"><!-- <head> da
ta 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 typ
e="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"
jstcache="0"> </script> <script type="text/javascript" src="js/api_page_generat
or.js" jstcache="0"></script> <script type="text/javascript" src="js/bootstrap.j
s" jstcache="0"></script> </head><!-- <body> content is completely generated. Do
not edit, as it will be and rewritten. --><body jstcache="0"> <div id="containe
r" jstcache="0"> <a name="top" jstcache="0"> </a> <!-- API HEADER --> <div id="p
ageHeader" 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" na
me="q" size="31" jstcache="0"> <input type="submit" name="sa" value="Search" jst
cache="0"> </div> </form> <script type="text/javascript" src="http://www.google.
com/jsapi" jstcache="0"></script> <script type="text/javascript" jstcache="0">go
ogle.load("elements", "1", {packages: "transliteration"});</script> <script type
="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-search-box&
amp;t13n_langs=en" jstcache="0"></script> <script type="text/javascript" src="ht
tp://www.google.com/coop/cse/brand?form=cse-search-box&lang=en" jstcache="0"
></script> </div> <div id="pageTitle" jstcache="0"> <h1 jscontent="getPageTitle(
)" jstcache="1">Overview</h1> </div> </div> <!-- /pageHeader --> <div id="pageCo
ntent" jstcache="0"> <!-- SIDENAV --> <div id="leftNav" jstcache="0"> <ul jstcac
he="0"> <li jstcache="0"> <a href="index.html" jstcache="0">Home</a></li> <li js
tcache="0"> <a href="getstarted.html" jstcache="0">Getting Started</a></li> <li
jstcache="0" class="leftNavSelected">Overview </li> <li jstcache="0"> <a href="d
evguide.html" jstcache="0"><div jstcache="0">Developer's Guide</div></a> <ul jst
cache="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 Pa
ges</a></li> <li jstcache="0"><a href="content_scripts.html" jstcache="0">Conten
t Scripts</a></li> <li jstcache="0">Events</li> <li jstcache="0"><a href="tabs.h
tml" 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">Boo
kmarks</a></li> <li jstcache="0">Themes</li> <li jstcache="0"><a href="npapi.htm
l" jstcache="0">NPAPI Plugins</a></li> <li jstcache="0"><a href="packaging.html"
jstcache="0">Packaging</a></li> <li jstcache="0">Autoupdate</li> </ul> </li> <l
i 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" jstca
che="0">Debugging</a></li> </ul> </li> <li jstcache="0">Reference <ul jstcache="
0"> <li jstcache="0"> Formats <ul jstcache="0"> <li jstcache="0"><a href="manife
st.html" jstcache="0">Manifest Files</a></li> <li jstcache="0">Match Patterns</l
i> <li jstcache="0">Packages (.crx)</li> </ul> </li> <li jstcache="0"> <a href="
api_index.html" jstcache="0">chrome.* APIs</a> </li> <li jstcache="0">Other APIs
</li> </ul> </li> <li jstcache="0">Samples <ul jstcache="0"> <li jstcache="0">[s
ample 1]</li> <li jstcache="0">[sample 2]</li> </ul> </li> </ul> </div> <div id=
"mainColumn" jstcache="0"> <!-- TABLE OF CONTENTS --> <div id="toc" jsdisplay="s
howPageTOC()" jstcache="2" style="display: none; "> <p jstcache="0">Contents</p>
<ol jstcache="0"> <li jsselect="getStaticTOC()" jstcache="9"> <a jscontent="nam
e" jsvalues=".href:'#' + href" jstcache="14">h2Name</a> <ol jstcache="0"> <li js
select="$this.children" jstcache="22"> <a jscontent="name" jsvalues=".href:'#' +
href" jstcache="14">h3Name</a> </li> </ol> </li> <div jsselect="apiDefinition"
jstcache="3"> <li jstcache="0"> <a href="#apiReference" jscontent="'API Referenc
e: ' + getModuleName()" jstcache="23">API Reference</a> <ol jstcache="0"> <li js
display="$this.properties" jstcache="5"> <a href="#properties" jstcache="0">Prop
erties</a> <ol jstcache="0"> <li jsselect="getPropertyListFromObject($this)" jst
cache="10"> <a jscontent="name" jsvalues=".href:'#property-' + name" href="#prop
erty-anchor" jstcache="42">propertyName</a> </li> </ol> </li> <li jsdisplay="fun
ctions && functions.length > 0" jstcache="6"> <a href="#methods" jstc
ache="0">Methods</a> <ol jstcache="0"> <li jsselect="functions" jstcache="11"> <
a jscontent="name" jsvalues=".href:'#method-' + name" href="#method-anchor" jstc
ache="43">methodName</a> </li> </ol> </li> <li jsdisplay="events && even
ts.length > 0" jstcache="7"> <a href="#events" jstcache="0">Events</a> <ol js
tcache="0"> <li jsselect="events" jstcache="12"> <a jscontent="name" jsvalues=".
href:'#event-' + name" href="#event-anchor" jstcache="44">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" jstc
ache="13"> <a jscontent="id" jsvalues=".href:'#type-' + id" href="#id-anchor" js
tcache="45">id</a> </li> </ol> </li> </ol> </li> </div> </ol> </div> <!-- /TABLE
OF CONTENTS --> <!-- STATIC CONTENT PLACEHOLDER --> <div id="static" jstcache="
0"><p jstcache="0"> This page should perhaps be renamed from "overview" to "conc
epts". In any case, what I'd like to cover here is the conceptual underpinning o
f extensions, such as: </p><ul jstcache="0"> <li jstcache="0">Zip file of web pa
ges </li><li jstcache="0">All resources accessible with a URL scheme </li><li js
tcache="0">How IDs are generated </li><li jstcache="0">The manifest </li><li jst
cache="0">The background page, how extensions are typically structured </li><li
jstcache="0">Process model </li><li jstcache="0">Content scripts (lightweight, l
ink off to other page for details) </li><li jstcache="0">Asynchronous APIs </li>
<li jstcache="0">Extension IDs, how they are generated </li><li jstcache="0">How
packaging works at a high level (lightweight, link off to other page for detail
s) </li></ul></div> <!-- API PAGE --> <div class="apiPage" jsselect="apiDefiniti
on" jstcache="3" style="display: none; "> <a name="apiReference" jstcache="0"></
a> <h2 jscontent="getModuleName() + ' API reference'" jstcache="4">chrome.apinam
e API reference</h2> <!-- PROPERTIES --> <div jsdisplay="$this.properties" class
="apiGroup" jstcache="5"> <a name="properties" jstcache="0"></a> <h3 id="propert
ies" 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"> <!-- Note: intentionally longer 80 columns --> <span jscontent="getModuleNam
e() + '.'" jstcache="24">chrome.extension</span><span jscontent="$this.name" jst
cache="25">lastError</span> </div> <div transclude="valueTemplate" jstcache="17"
> </div> </div> </div> <!-- /apiGroup --> <!-- METHODS --> <div jsdisplay="funct
ions && functions.length > 0" class="apiGroup" id="methods" jstcache=
"6"> <a name="methods" jstcache="0"></a> <h3 jstcache="0">Methods</h3> <!-- iter
ates over all functions --> <div class="apiItem" jsselect="functions" jstcache="
11"> <a jsvalues=".name:'method-' + name" jstcache="18"></a> <!-- method-anchor
--> <h4 jscontent="name" jstcache="16">method name</h4> <div class="summary" jst
cache="0"><span jsdisplay="returns" jscontent="getTypeName(returns)" jstcache="2
6">void</span> <!-- Note: intentionally longer 80 columns --> <span jscontent="g
etFullyQualifiedFunctionName($this)" jstcache="27">chrome.module.methodName</spa
n>(<span jsselect="parameters" jsvalues="class:optional ? 'optional' : ''" jstca
che="28"><span jsdisplay="$index" jstcache="34">, </span><span jscontent="getTyp
eName($this)" jstcache="35"></span> <var jstcache="0"><span jscontent="name" jst
cache="16"></span></var></span>)</div> <div class="description" jstcache="0"> <p
class="todo" jsdisplay="!description" jstcache="29">Undocumented.</p> <p jsdisp
lay="description" jsvalues=".innerHTML:description" jstcache="30"> A description
from the json schema def of the function goes here. </p> <!-- PARAMETERS --> <h
4 jstcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="parameters" jstc
ache="36"> <!-- VALUE: This is a subtemplate that is used elsewhere via jsTempla
te *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 c
lass="optional" jsdisplay="optional" jstcache="47">optional</span> <span id="typ
eTemplate" jstcache="0"> <span jsdisplay="getTypeRef($this)" jstcache="48"> <a j
svalues=".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="getTypeN
ame($this)" jstcache="52">paramType</span> </span> </span> ) </div> </em> </dt>
<dd class="todo" jsdisplay="!$this.description" jstcache="39"> Undocumented. </d
d> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description" jst
cache="40"> Description of this parameter from the json schema. </dd> <!-- OBJEC
T PROPERTIES --> <dd jsdisplay="shouldExpandObject($this)" jstcache="41"> <dl js
tcache="0"> <div jsselect="getPropertyListFromObject($this)" jstcache="10"> <div
transclude="valueTemplate" jstcache="17"> </div> </div> </dl> </dd> </div> <!--
/VALUE --> </div> </dl> <!-- RETURNS --> <h4 jsdisplay="returns" jstcache="31">
Returns</h4> <dl jstcache="0"> <div jsselect="returns" jstcache="37"> <div trans
clude="valueTemplate" jstcache="17"> </div> </div> </dl> <!-- CALLBACK -->
<div jsdisplay="hasCallback(parameters)" jstcache="32"> <div jsselect="getCallb
ackParameters(parameters)" jstcache="38"> <h4 jstcache="0">Callback function</h4
> <p jstcache="0"> If you specify the <em jstcache="0">callback</em> parameter,
it should specify a function that looks like this: </p> <!-- Note: intentionally
longer 80 columns --> <pre jstcache="0">function(<span jscontent="getSignatureS
tring(parameters)" jstcache="33">Type param1, Type param2</span>) <span class="s
ubdued" jstcache="0">{...}</span>);</pre> <dl jstcache="0"> <div jsselect="param
eters" jstcache="36"> <div transclude="valueTemplate" jstcache="17"> </div> </di
v> </dl> </div> </div> </div> <!-- /description --> </div> <!-- /apiItem --> </d
iv> <!-- /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> <!-- iterates over all events --> <div
jsselect="events" class="apiItem" jstcache="12"> <a jsvalues=".name:'event-' +
name" jstcache="19"></a> <h4 jscontent="name" jstcache="16">event name</h4> <div
class="summary" jstcache="0"> <!-- Note: intentionally longer 80 columns --> <s
pan jscontent="getModuleName() + '.'" class="subdued" jstcache="24">chrome.bookm
arks</span><span jscontent="name" jstcache="16">onEvent</span><span class="subdu
ed" jstcache="0">.addListener</span>(function(<span jscontent="getSignatureStrin
g(parameters)" jstcache="33">Type param1, Type param2</span>) <span class="subdu
ed" jstcache="0">{...}</span>); </div> <div class="description" jstcache="0"> <p
class="todo" jsdisplay="!description" jstcache="29">Undocumented.</p> <p jsdisp
lay="description" jsvalues=".innerHTML:description" jstcache="30"> A description
from the json schema def of the event goes here. </p> <!-- PARAMETERS --> <h4 j
stcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="parameters" jstcach
e="36"> <div transclude="valueTemplate" jstcache="17"> </div> </div> </dl> </div
> <!-- /decription --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- T
YPES --> <div jsdisplay="types && types.length > 0" class="apiGroup"
jstcache="8"> <a name="types" jstcache="0"></a> <h3 id="types" jstcache="0">Type
s</h3> <!-- iterates over all types --> <div jsselect="types" class="apiItem" js
tcache="13"> <a jsvalues=".name:'type-' + id" jstcache="20"></a> <h4 jscontent="
id" jstcache="21">type name</h4> <div transclude="valueTemplate" jstcache="17">
</div> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> </div> <!-- /apiPage -
-> </div> <!-- /mainColumn --> </div> <!-- /pageContent --> <div id="pageFooter"
--="" jstcache="0"> Copyright 2009. For terms of use, see the Chromium <a href=
"http://src.chromium.org/viewvc/chrome/trunk/src/LICENSE" jstcache="0">license</
a>. </div> <!-- /pageFooter --> </div> <!-- /container --> </body></html> | 1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc.
Note: 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 mecha
nism. 2) The <body> tag *must* retain id="body" 3) All <body>.innerHTML is gener
eated 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>.innerHTM
L is also generated by an offline step so that this page may easily be indexed b
y search engines. TODO(rafaelw): Abstract this into a "pageshell" that becomes t
he single version of page template shell and the "instance" pages (bookmarks.htm
l, etc...) can be generated with a build step. --><!-- <html> must retain id="te
mplate --><html xmlns="http://www.w3.org/1999/xhtml" jstcache="0"><!-- <head> da
ta 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 typ
e="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"
jstcache="0"> </script> <script type="text/javascript" src="js/api_page_generat
or.js" jstcache="0"></script> <script type="text/javascript" src="js/bootstrap.j
s" jstcache="0"></script> </head><!-- <body> content is completely generated. Do
not edit, as it will be and rewritten. --><body jstcache="0"> <div id="containe
r" jstcache="0"> <a name="top" jstcache="0"> </a> <!-- API HEADER --> <div id="p
ageHeader" 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" na
me="q" size="31" jstcache="0"> <input type="submit" name="sa" value="Search" jst
cache="0"> </div> </form> <script type="text/javascript" src="http://www.google.
com/jsapi" jstcache="0"></script> <script type="text/javascript" jstcache="0">go
ogle.load("elements", "1", {packages: "transliteration"});</script> <script type
="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-search-box&
amp;t13n_langs=en" jstcache="0"></script> <script type="text/javascript" src="ht
tp://www.google.com/coop/cse/brand?form=cse-search-box&lang=en" jstcache="0"
></script> </div> <div id="pageTitle" jstcache="0"> <h1 jscontent="getPageTitle(
)" jstcache="1">Overview</h1> </div> </div> <!-- /pageHeader --> <div id="pageCo
ntent" jstcache="0"> <!-- SIDENAV --> <div id="leftNav" jstcache="0"> <ul jstcac
he="0"> <li jstcache="0"> <a href="index.html" jstcache="0">Home</a></li> <li js
tcache="0"> <a href="getstarted.html" jstcache="0">Getting Started</a></li> <li
jstcache="0" class="leftNavSelected">Overview </li> <li jstcache="0"> <a href="d
evguide.html" jstcache="0"><div jstcache="0">Developer's Guide</div></a> <ul jst
cache="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 Pa
ges</a></li> <li jstcache="0"><a href="content_scripts.html" jstcache="0">Conten
t Scripts</a></li> <li jstcache="0">Events</li> <li jstcache="0"><a href="tabs.h
tml" 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">Boo
kmarks</a></li> <li jstcache="0">Themes</li> <li jstcache="0"><a href="npapi.htm
l" jstcache="0">NPAPI Plugins</a></li> <li jstcache="0"><a href="packaging.html"
jstcache="0">Packaging</a></li> <li jstcache="0">Autoupdate</li> </ul> </li> <l
i 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" jstca
che="0">Debugging</a></li> </ul> </li> <li jstcache="0">Reference <ul jstcache="
0"> <li jstcache="0"> Formats <ul jstcache="0"> <li jstcache="0"><a href="manife
st.html" jstcache="0">Manifest Files</a></li> <li jstcache="0">Match Patterns</l
i> <li jstcache="0">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> </ul> </li> <li jstcache="0"><
a href="http://dev.chromium.org/developers/design-documents/extensions/samples"
jstcache="0">Samples</a></li> </ul> </div> <div id="mainColumn" jstcache="0"> <!
-- TABLE OF CONTENTS --> <div id="toc" jsdisplay="showPageTOC()" jstcache="2"> <
p jstcache="0">Contents</p> <ol jstcache="0"> <li jsselect="getStaticTOC()" jstc
ache="9" jsinstance="0"> <a jscontent="name" jsvalues=".href:'#' + href" jstcach
e="14" href="#H2-0">The basics</a> <ol jstcache="0"> <li jsselect="$this.childre
n" jstcache="22" jsinstance="*0" style="display: none; "> <a jscontent="name" js
values=".href:'#' + href" jstcache="14">h3Name</a> </li> </ol> </li><li jsselect
="getStaticTOC()" jstcache="9" jsinstance="1"> <a jscontent="name" jsvalues=".hr
ef:'#' + href" jstcache="14" href="#H2-1">Files</a> <ol jstcache="0"> <li jssele
ct="$this.children" jstcache="22" jsinstance="0"> <a jscontent="name" jsvalues="
.href:'#' + href" jstcache="14" href="#H3-2">Referring to files</a> </li><li jss
elect="$this.children" jstcache="22" jsinstance="*1"> <a jscontent="name" jsvalu
es=".href:'#' + href" jstcache="14" href="#H3-3">The manifest file</a> </li> </o
l> </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="2"> <a jscontent=
"name" jsvalues=".href:'#' + href" jstcache="14" href="#H2-4">Architecture</a> <
ol jstcache="0"> <li jsselect="$this.children" jstcache="22" jsinstance="0"> <a
jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H3-5">The back
ground page</a> </li><li jsselect="$this.children" jstcache="22" jsinstance="*1"
> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H3-6">Con
tent scripts</a> </li> </ol> </li><li jsselect="getStaticTOC()" jstcache="9" jsi
nstance="3"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href=
"#H2-7">Communication </a> <ol jstcache="0"> <li jsselect="$this.children" jstca
che="22" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues="
.href:'#' + href" jstcache="14">h3Name</a> </li> </ol> </li><li jsselect="getSta
ticTOC()" 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 jscon
tent="name" jsvalues=".href:'#' + href" jstcache="14">h3Name</a> </li> </ol> </l
i> <div jsselect="apiDefinition" jstcache="3" style="display: none; "> <li jstca
che="0"> <a href="#apiReference" jscontent="'API reference: ' + getModuleName()"
jstcache="4">API reference</a> <ol jstcache="0"> <li jsdisplay="$this.propertie
s" 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="4
1">propertyName</a> </li> </ol> </li> <li jsdisplay="functions && functi
ons.length > 0" jstcache="6"> <a href="#methods" jstcache="0">Methods</a> <ol
jstcache="0"> <li jsselect="functions" jstcache="11"> <a jscontent="name" jsval
ues=".href:'#method-' + name" href="#method-anchor" jstcache="42">methodName</a>
</li> </ol> </li> <li jsdisplay="events && events.length > 0" jstcac
he="7"> <a href="#events" jstcache="0">Events</a> <ol jstcache="0"> <li jsselect
="events" jstcache="12"> <a jscontent="name" jsvalues=".href:'#event-' + name" h
ref="#event-anchor" jstcache="43">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" jstcache="13"> <a jscontent=
"id" jsvalues=".href:'#type-' + id" href="#id-anchor" jstcache="44">id</a> </li>
</ol> </li> </ol> </li> </div> </ol> </div> <!-- /TABLE OF CONTENTS --> <!-- ST
ATIC CONTENT PLACEHOLDER --> <div id="static" jstcache="0"><div id="pageData-tit
le" class="pageData" jstcache="0">Overview</div> <div id="pageData-showTOC" clas
s="pageData" jstcache="0">true</div> <p jstcache="0"> Please read this page; it
has vital information about the extension architecture. If you get bored or rest
less, 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_debu
gging.html" jstcache="0">Debugging</a>. </p> <a name="H2-0" jstcache="0"></a><h2
id="what" jstcache="0">The basics</h2> <p jstcache="0"> An extension is a zippe
d bundle of files — HTML, CSS, JavaScript, images, and anything else you need —
that adds functionality to the Google Chrome browser. Because an extension is ju
st a special kind of web page, it can use all the APIs that the browser provides
to web pages and apps, from XMLHttpRequest to JSON to localStorage. </p> <p jst
cache="0"> Extensions can add UI to Google Chrome, in the form of <a href="tools
trip.html" jstcache="0">toolstrips</a> (toolbar additions) and <a href="pageActi
ons.html" jstcache="0">page actions</a> (clickable badges in the address bar). E
xtensions can also interact programmatically with browser features such as <a hr
ef="bookmarks.html" jstcache="0">bookmarks</a> and <a href="tabs.html" jstcache=
"0">tabs</a>. </p> <p jstcache="0"> To find a complete list of extension feature
s, with implementation details for each one, see the <a href="devguide.html" jst
cache="0">Developer's Guide</a>. </p> <a name="H2-1" jstcache="0"></a><h2 id="fi
les" jstcache="0">Files</h2> <p jstcache="0"> Each extension has the following f
iles: <!-- PENDING: This could use a picture --> </p> <ul jstcache="0"> <li jstc
ache="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 jstcach
e="0"><em jstcache="0">Optional:</em> One or more <b jstcache="0">JavaScript fil
es</b></li> <li jstcache="0"><em jstcache="0">Optional:</em> Any other files you
r extension needs — for example, image files</li> </ul> <p jstcache="0"> While y
ou're working on your extension, you put all these files into a single folder. W
hen 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>. </p> <a name="H3-2" jst
cache="0"></a><h3 jstcache="0">Referring to files</h3> <p jstcache="0"> 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 p
age. Here's an example of referring to a file named <code jstcache="0">myimage.p
ng</code> that's in a subdirectory named <code jstcache="0">images</code>. </p>
<pre jstcache="0"><img <b jstcache="0">src="images/myimage.png"</b> style="wi
dth:auto; height:auto"> </pre> <p jstcache="0"> As you might notice while you
use the Google Chrome debugger, every file in an extension is also accessible b
y an absolute URL like this: </p> <blockquote jstcache="0"> <b jstcache="0">chro
me-extension://</b><em jstcache="0"><extensionID></em><b jstcache="0">/</b
><em jstcache="0"><pathToFile></em> </blockquote> <p jstcache="0"> In that
URL, the <em jstcache="0"><extensionID></em> is a unique identifier that
the extension system generates for each extension. You can see the IDs for all y
our 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 und
er the extension's top directory; it's the same as the relative URL. </p> <p cla
ss="comment" jstcache="0"> [QUESTION TO REVIEWERS: Is this section too big/detai
led? It seems a little weird to mention absolute URLs with mentioning getURL and
when you'd need it. What's the motivation for covering absolute URLs? Is the de
bugger the place you're most likely to see them?] </p> <p jstcache="0"> For exam
ple, assume your extension has the ID <b jstcache="0">aaaaaaaaaaaaaaaaaaaaaaaaaa
aaaaaa</b> and the files shown in the following figure: </p> <pre jstcache="0"><
span class="comment" jstcache="0">[PENDING: convert this into a figure]</span> t
oolstrip.html styles.css images: myimage.png ... other: more.html morestyles.css
... </pre> <p jstcache="0"> 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 w
here you're using it — the relative URL of <code jstcache="0">myimage.png</code>
is <b jstcache="0">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>. </p> <table jstcache="0"> <tbody jstcache="0"><tr jstcache="0"> <th jstc
ache="0"> File </th> <th jstcache="0"> Relative URL </th> <th jstcache="0"> Abso
lute URL </th> </tr> <tr jstcache="0"> <td jstcache="0"> toolstrip.html </td> <t
d jstcache="0"> toolstrip.html </td> <td jstcache="0"> chrome-extension://aaaaaa
aaaaaaaaaaaaaaaaaaaaaaaaaa/toolstrip.html </td> </tr> <tr jstcache="0"> <td jstc
ache="0"> styles.css </td> <td jstcache="0"> styles.css </td> <td jstcache="0">
chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/styles.css </td> </tr> <tr j
stcache="0"> <td jstcache="0"> myimage.png </td> <td jstcache="0"> images/myimag
e.png </td> <td jstcache="0"> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
a/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> <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> </tbody></table> <p class="comment" jstcache="0"> [P
ENDING: Mention/reflect/link to <a href="http://dev.chromium.org/developers/desi
gn-documents/extensions/i18n" jstcache="0">internationalization</a>] </p> <a nam
e="H3-3" jstcache="0"></a><h3 jstcache="0">The manifest file</h3> <p jstcache="0
"> The manifest file, called <code jstcache="0">manifest.json</code>, gives info
rmation about the extension, such as the most important files and the capabiliti
es that the extension might use. Here's a typical manifest file for a toolstrip
that uses information from google.com: </p> <pre jstcache="0">{ "name": "My Exte
nsion", "version": "2.1", "description": "Gets information from Google.", "updat
e_url": "http://example.com/mytestextension/updates.xml", "permissions": ["http:
//*.google.com/", "https://*.google.com/"], "toolstrips": ["my_toolstrip.html"]
}</pre> <p jstcache="0"> For details, see <a href="manifest.html" jstcache="0">M
anifest Files</a>. </p> <a name="H2-4" jstcache="0"></a><h2 id="arch" jstcache="
0">Architecture</h2> <p jstcache="0"> The following pictures shows the web pages
associated with a typical extension (in this case, a simple toolstrip). The fir
st figure shows what an extension might look like when there's a single browser
window. </p> <p class="comment" jstcache="0"> [PENDING: image goes here] </p> <p
jstcache="0"> The next figure shows that all the code in the extension's main H
TML file is duplicated each time you create a new window. In other words, each w
indow has its own widgets for the extension, which means each window adds anothe
r web page for that extension. </p> <p class="comment" jstcache="0"> [PENDING: i
mage goes here] </p> <p jstcache="0"> To more easily coordinate all these web pa
ges and to avoid duplication, you should design your extension so that most of t
he code — especially the state of the extension — is in a <em jstcache="0">backg
round page</em>, as shown in the following figure. </p> <p class="comment" jstca
che="0"> [PENDING: image goes here.] </p> <a name="H3-5" jstcache="0"></a><h3 id
="background" jstcache="0">The background page</h3> <p jstcache="0"> Any non-tri
vial extension can (and probably should) have a background page. The background
page is an invisible page where you put the main logic of the extension. The ext
ension's other pages should have only the code that's necessary to show the stat
e of the extension and to get input from the user.</p> <p jstcache="0"> An exten
sion's background page exists before any of the extension's other pages exist. I
t continues to exist as long as the browser is running and the extension is inst
alled, even if other pages and windows go away. </p> <p jstcache="0"> Your exten
sion's UI — its toolstrips, page actions, and so on — should be dumb views. When
the view needs some state, it should request it from the background page. When
the background page notices some state change, it should update all the views. <
/p> <p jstcache="0"> For more information, see <a href="background_pages.html" j
stcache="0">Background Pages</a>. </p> <a name="H3-6" jstcache="0"></a><h3 id="c
ontentScripts" jstcache="0">Content scripts</h3> <p jstcache="0"> If you want yo
ur extension to interact with web pages, you need a content script. Content scri
pts are JavaScript files that run in the context of web pages. By using the stan
dard Document Object Model (DOM), they can read details of the web pages the bro
wser visits, and they can make changes to the pages. </p> <p class="comment" jst
cache="0"> [PENDING: add an architectural figure here, showing the extension's p
ages, a web page, and the content script interacting with the web page. explain
the figure.] </p> <p jstcache="0"> For more information, see <a href="content_sc
ripts.html" jstcache="0">Content Scripts</a>. </p> <a name="H2-7" jstcache="0"><
/a><h2 jstcache="0">Communication </h2> <p jstcache="0"> Two kinds of communicat
ion happen within an extension: </p> <ul jstcache="0"> <li jstcache="0"> Communi
cation <b jstcache="0">between pages</b> in the extension. <br jstcache="0"> For
example, sometimes the background page needs to update all the UI pages to refl
ect 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"> Fo
r example, <span class="comment" jstcache="0">[PENDING: example goes here]</span
>. See <a href="content_scripts.html" jstcache="0">Content Scripts</a> for infor
mation about this type of communication. </li> </ul> <p jstcache="0"> Here are s
ome keys to communication between an extension's pages: </p> <ul jstcache="0"> <
li jstcache="0"> All the extension's pages execute in same process, on the same
thread. </li> <li jstcache="0"> Extension pages can use <a href="extension.html"
jstcache="0"><code jstcache="0">chrome.extension</code></a> methods such as <co
de jstcache="0">getViews()</code>, <code jstcache="0">getBackgroundPage()</code>
, and <code jstcache="0">getToolstrips()</code> to get access to the extension's
pages. </li> <li jstcache="0"> Once you have references to an extension's pages
, you can manipulate the DOM for each page. </li> <li jstcache="0"> You can also
make direct function calls to the pages, as shown in the following example. </l
i> </ul> <p jstcache="0"> Here's an example of communication between toolstrips
and the background page. </p> <pre jstcache="0">//In background_page.html: funct
ion updateUI(checked) { var toolstrips = chrome.extension.getToolstrips(); for (
var i in toolstrips) { if (toolstrips[i].enableCheckbox) toolstrips[i].enableChe
ckbox(checked); } } //In toolstrip.html: function enableCheckbox(checked) { var
cb = document.getElementById('checkbox'); cb.checked = checked; } </pre> <p jstc
ache="0"> A good summary of communication mechanisms is at <a href="http://www.c
hromeplugins.org/google/plugins-development/communication-7883.html" jstcache="0
">http://www.chromeplugins.org/google/plugins-development/communication-7883.htm
l</a>. </p> <a name="H2-8" jstcache="0"></a><h2 jstcache="0"> Summary </h2> <p j
stcache="0"> [ PENDING: wrap it up. 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 Gu
ide</a>. ] </p> </div> <!-- API PAGE --> <div class="apiPage" jsselect="apiDefin
ition" jstcache="3" style="display: none; "> <a name="apiReference" jstcache="0"
></a> <h2 jscontent="'API reference: ' + getModuleName()" jstcache="4">API refer
ence: chrome.apiname </h2> <!-- PROPERTIES --> <div jsdisplay="$this.properties"
class="apiGroup" jstcache="5"> <a name="properties" jstcache="0"></a> <h3 id="p
roperties" 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" jstc
ache="0"> <!-- Note: intentionally longer 80 columns --> <span jscontent="getMod
uleName() + '.'" jstcache="23">chrome.extension</span><span jscontent="$this.nam
e" jstcache="24">lastError</span> </div> <div transclude="valueTemplate" jstcach
e="17"> </div> </div> </div> <!-- /apiGroup --> <!-- METHODS --> <div jsdisplay=
"functions && functions.length > 0" class="apiGroup" id="methods" jst
cache="6"> <a name="methods" jstcache="0"></a> <h3 jstcache="0">Methods</h3> <!-
- iterates over all functions --> <div class="apiItem" jsselect="functions" jstc
ache="11"> <a jsvalues=".name:'method-' + name" jstcache="18"></a> <!-- method-a
nchor --> <h4 jscontent="name" jstcache="16">method name</h4> <div class="summar
y" jstcache="0"><span jsdisplay="returns" jscontent="getTypeName(returns)" jstca
che="25">void</span> <!-- Note: intentionally longer 80 columns --> <span jscont
ent="getFullyQualifiedFunctionName($this)" jstcache="26">chrome.module.methodNam
e</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="nam
e" jstcache="16"></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"> A descr
iption 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 js
Template *transclude* --> <div id="valueTemplate" jstcache="0"> <dt jstcache="0"
> <var jsdisplay="$this.name" jscontent="$this.name" jstcache="45">paramName</va
r> <em jstcache="0"> <!-- TYPE --> <div style="display:inline" jstcache="0"> ( <
span class="optional" jsdisplay="optional" jstcache="46">optional</span> <span i
d="typeTemplate" jstcache="0"> <span jsdisplay="getTypeRef($this)" jstcache="47"
> <a jsvalues=".href: getTypeRefPage($this) + '#type-' + getTypeRef($this)" jsco
ntent="getTypeRef($this)" jstcache="49"> Type</a> </span> <span jsdisplay="!getT
ypeRef($this)" jstcache="48"> <span jsdisplay="isArray($this)" jstcache="50"> ar
ray of <span jsselect="items" jstcache="52"><span transclude="typeTemplate" jstc
ache="53"></span></span> </span> <span jsdisplay="!isArray($this)" jscontent="ge
tTypeName($this)" jstcache="51">paramType</span> </span> </span> ) </div> </em>
</dt> <dd class="todo" jsdisplay="!$this.description" jstcache="38"> Undocumente
d. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.descriptio
n" jstcache="39"> Description of this parameter from the json schema. </dd> <!--
OBJECT PROPERTIES --> <dd jsdisplay="shouldExpandObject($this)" jstcache="40">
<dl jstcache="0"> <div jsselect="getPropertyListFromObject($this)" jstcache="10"
> <div transclude="valueTemplate" jstcache="17"> </div> </div> </dl> </dd> </div
> <!-- /VALUE --> </div> </dl> <!-- RETURNS --> <h4 jsdisplay="returns" jstcache
="30">Returns</h4> <dl jstcache="0"> <div jsselect="returns" jstcache="36"> <div
transclude="valueTemplate" jstcache="17"> </div> </div> </dl> <!-- CALLBACK -->
<div jsdisplay="hasCallback(parameters)" jstcache="31"> <div jsselect="
getCallbackParameters(parameters)" jstcache="37"> <h4 jstcache="0">Callback func
tion</h4> <p jstcache="0"> If you specify the <em jstcache="0">callback</em> par
ameter, it should specify a function that looks like this: </p> <!-- Note: inten
tionally longer 80 columns --> <pre jstcache="0">function(<span jscontent="getSi
gnatureString(parameters)" jstcache="32">Type param1, Type param2</span>) <span
class="subdued" jstcache="0">{...}</span>);</pre> <dl jstcache="0"> <div jsselec
t="parameters" jstcache="35"> <div transclude="valueTemplate" jstcache="17"> </d
iv> </div> </dl> </div> </div> </div> <!-- /description --> </div> <!-- /apiItem
--> </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> <!-- iterates over all events
--> <div jsselect="events" class="apiItem" jstcache="12"> <a jsvalues=".name:'ev
ent-' + name" jstcache="19"></a> <h4 jscontent="name" jstcache="16">event name</
h4> <div class="summary" jstcache="0"> <!-- Note: intentionally longer 80 column
s --> <span jscontent="getModuleName() + '.'" class="subdued" jstcache="23">chro
me.bookmarks</span><span jscontent="name" jstcache="16">onEvent</span><span clas
s="subdued" jstcache="0">.addListener</span>(function(<span jscontent="getSignat
ureString(parameters)" jstcache="32">Type param1, Type param2</span>) <span clas
s="subdued" jstcache="0">{...}</span>); </div> <div class="description" jstcache
="0"> <p class="todo" jsdisplay="!description" jstcache="28">Undocumented.</p> <
p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="29"> A des
cription 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"> </div> </div> </d
l> </div> <!-- /decription --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --
> <!-- TYPES --> <div jsdisplay="types && types.length > 0" class="ap
iGroup" jstcache="8"> <a name="types" jstcache="0"></a> <h3 id="types" jstcache=
"0">Types</h3> <!-- iterates over all types --> <div jsselect="types" class="api
Item" jstcache="13"> <a jsvalues=".name:'type-' + id" jstcache="20"></a> <h4 jsc
ontent="id" jstcache="21">type name</h4> <div transclude="valueTemplate" jstcach
e="17"> </div> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> </div> <!-- /a
piPage --> </div> <!-- /mainColumn --> </div> <!-- /pageContent --> <div id="pag
eFooter" --="" jstcache="0"> Copyright 2009. For terms of use, see the Chromium
<a href="http://src.chromium.org/viewvc/chrome/trunk/src/LICENSE" jstcache="0">l
icense</a>. </div> <!-- /pageFooter --> </div> <!-- /container --> </body></html
> |
Chromium Code Reviews
Issue 180016:
Extension API Renaming/Consistency changes (Closed)
