| OLD | NEW |
|---|
| 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">Content Scripts</title> <link
href="css/ApiRefStyles.css" rel="stylesheet" type="text/css" jstcache="0"> <scr
ipt type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compi
led.js" jstcache="0"> </script> <script type="text/javascript" src="js/api_page_
generator.js" jstcache="0"></script> <script type="text/javascript" src="js/boot
strap.js" jstcache="0"></script> </head><!-- <body> content is completely genera
ted. Do not edit, as it will be and rewritten. --><body jstcache="0"> <div id="c
ontainer" jstcache="0"> <a name="top" jstcache="0"> </a> <!-- API HEADER --> <di
v 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" jstcach
e="0"> <input type="hidden" name="ie" value="UTF-8" jstcache="0"> <input type="t
ext" name="q" size="31" jstcache="0"> <input type="submit" name="sa" value="Sear
ch" jstcache="0"> </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> <scri
pt type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-sear
ch-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" jstca
che="0"></script> </div> <div id="pageTitle" jstcache="0"> <h1 jscontent="getPag
eTitle()" jstcache="1">Content Scripts</h1> </div> </div> <!-- /pageHeader --> <
div id="pageContent" jstcache="0"> <!-- 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"> <a href="overview.html" jstcache="0">Overview</a></l
i> <li jstcache="0"> <a href="devguide.html" jstcache="0"><div jstcache="0">Deve
loper's Guide</div></a> <ul jstcache="0"> <li jstcache="0"><a href="toolstrip.ht
ml" 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.h
tml" jstcache="0">Background Pages</a></li> <li jstcache="0" class="leftNavSelec
ted">Content Scripts</li> <li jstcache="0">Events</li> <li jstcache="0"><a href=
"tabs.html" jstcache="0">Tabs</a></li> <li jstcache="0"><a href="windows.html" j
stcache="0">Windows</a></li> <li jstcache="0"><a href="bookmarks.html" jstcache=
"0">Bookmarks</a></li> <li jstcache="0">Themes</li> <li jstcache="0"><a href="np
api.html" jstcache="0">NPAPI Plugins</a></li> <li jstcache="0"><a href="packagin
g.html" jstcache="0">Packaging</a></li> <li jstcache="0">Autoupdate</li> </ul> <
/li> <li jstcache="0"><a href="tutorials.html" jstcache="0"><div jstcache="0">Tu
torials</div></a> <ul jstcache="0"> <li jstcache="0"><a href="tut_debugging.html
" jstcache="0">Debugging</a></li> </ul> </li> <li jstcache="0">Reference <ul jst
cache="0"> <li jstcache="0"> Formats <ul jstcache="0"> <li jstcache="0"><a href=
"manifest.html" jstcache="0">Manifest Files</a></li> <li jstcache="0">Match Patt
erns</li> <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 jstcach
e="0"><a href="http://dev.chromium.org/developers/design-documents/extensions/sa
mples" 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(
)" jstcache="9" jsinstance="0"> <a jscontent="name" jsvalues=".href:'#' + href"
jstcache="14" href="#H2-0">Manifest</a> <ol jstcache="0"> <li jsselect="$this.ch
ildren" jstcache="22" jsinstance="*0" style="display: none; "> <a jscontent="nam
e" jsvalues=".href:'#' + href" jstcache="14">h3Name</a> </li> </ol> </li><li jss
elect="getStaticTOC()" jstcache="9" jsinstance="1"> <a jscontent="name" jsvalues
=".href:'#' + href" jstcache="14" href="#H2-1">Execution environment</a> <ol jst
cache="0"> <li jsselect="$this.children" jstcache="22" jsinstance="*0" style="di
splay: none; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">h3
Name</a> </li> </ol> </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance=
"2"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H2-2">
Messaging</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache="22" jsin
stance="*0" style="display: none; "> <a jscontent="name" jsvalues=".href:'#' + h
ref" jstcache="14">h3Name</a> </li> </ol> </li><li jsselect="getStaticTOC()" jst
cache="9" jsinstance="3"> <a jscontent="name" jsvalues=".href:'#' + href" jstcac
he="14" href="#H2-3">Communication with the embedding page</a> <ol jstcache="0">
<li jsselect="$this.children" jstcache="22" jsinstance="*0" style="display: non
e; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">h3Name</a> <
/li> </ol> </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="*4"> <a j
scontent="name" jsvalues=".href:'#' + href" jstcache="14" href="#H2-4">Referring
to extension files</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache
="22" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues=".hr
ef:'#' + href" jstcache="14">h3Name</a> </li> </ol> </li> <div jsselect="apiDefi
nition" jstcache="3" style="display: none; "> <li jstcache="0"> <a href="#apiRef
erence" jscontent="'API reference: ' + getModuleName()" jstcache="4">API referen
ce</a> <ol jstcache="0"> <li jsdisplay="$this.properties" jstcache="5"> <a href=
"#properties" jstcache="0">Properties</a> <ol jstcache="0"> <li jsselect="getPro
pertyListFromObject($this)" jstcache="10"> <a jscontent="name" jsvalues=".href:'
#property-' + name" href="#property-anchor" jstcache="41">propertyName</a> </li>
</ol> </li> <li jsdisplay="functions && functions.length > 0" jstcac
he="6"> <a href="#methods" jstcache="0">Methods</a> <ol jstcache="0"> <li jssele
ct="functions" jstcache="11"> <a jscontent="name" jsvalues=".href:'#method-' + n
ame" href="#method-anchor" jstcache="42">methodName</a> </li> </ol> </li> <li js
display="events && events.length > 0" jstcache="7"> <a href="#events"
jstcache="0">Events</a> <ol jstcache="0"> <li jsselect="events" jstcache="12">
<a jscontent="name" jsvalues=".href:'#event-' + name" href="#event-anchor" jstca
che="43">eventName</a> </li> </ol> </li> <li jsdisplay="types && types.l
ength > 0" jstcache="8"> <a href="#types" jstcache="0">Types</a> <ol jstcache
="0"> <li jsselect="types" jstcache="13"> <a jscontent="id" jsvalues=".href:'#ty
pe-' + id" href="#id-anchor" jstcache="44">id</a> </li> </ol> </li> </ol> </li>
</div> </ol> </div> <!-- /TABLE OF CONTENTS --> <!-- STATIC CONTENT PLACEHOLDER
--> <div id="static" jstcache="0"><div id="pageData-title" class="pageData" jstc
ache="0">Content Scripts</div> <div id="pageData-showTOC" class="pageData" jstca
che="0">true</div> <p jstcache="0">Content Scripts are JavaScript files that run
in the context of web pages. By using the standard <a href="http://www.w3.org/T
R/DOM-Level-2-HTML/" jstcache="0">Document Object Model</a> (DOM), they can read
details of the web pages the browser visits, or make changes to them. </p><p js
tcache="0">Some examples of things that content scripts can do include: </p><ul
jstcache="0"> <li jstcache="0">Find unlinked URLs in web pages and convert them
into hyperlinks </li><li jstcache="0">Increase the font size to make text more l
egible </li><li jstcache="0">Find and process <a href="http://microformats.org/"
jstcache="0">microformat</a> data in the DOM </li></ul> <a name="H2-0" jstcache
="0"></a><h2 id="registration" jstcache="0">Manifest</h2> <p jstcache="0">Conten
t scripts are registered in an extension's <a href="manifest.html" jstcache="0">
manifest.json</a> file, like so: </p><pre jstcache="0">{ "name": "My First Exten
sion", "version": "1.0", "description": "The first extension that I made.", <spa
n style="background:yellow; font-weight:bold;" jstcache="0"> "content_scripts":
[ { "matches": ["http://www.google.com/*"], "css": ["mystyles.css"], "js": ["jqu
ery.js", "myscript.js"] } ]</span> }</pre> <p jstcache="0">An extension can cont
ain any number of content scripts, and a content script can consist of any numbe
r of JavaScript or CSS files. The value of the <code jstcache="0">matches</code>
property controls when the content script will run. </p><p jstcache="0">Each co
ntent script registered in the manifest can specify the following properties:</p
> <table jstcache="0"> <tbody jstcache="0"><tr jstcache="0"> <th jstcache="0">Na
me</th> <th jstcache="0">Type</th> <th jstcache="0">Description</th> </tr> <tr j
stcache="0"> <td jstcache="0">matches</td> <td jstcache="0">array of strings</td
> <td jstcache="0">Required. Controls the pages this content script will be inje
cted into. See <a href="http://dev.chromium.org/developers/design-documents/exte
nsions/match-patterns" jstcache="0">Match patterns</a> for more details on the s
yntax of these strings.</td> </tr> <tr jstcache="0"> <td jstcache="0">js</td> <t
d jstcache="0"><nobr jstcache="0">array of strings</nobr></td> <td jstcache="0">
Optional. The list of JavaScript files to be injected into matching pages. These
are injected in the order they appear in this array.</td> </tr> <tr jstcache="0
"> <td jstcache="0">css</td> <td jstcache="0">array of strings</td> <td jstcache
="0">Optional. The list of CSS files to be injected into matching pages. These a
re injected in the order they appear in this array, before any DOM is constructe
d or displayed for the page.</td> </tr> <tr jstcache="0"> <td jstcache="0">run_a
t</td> <td jstcache="0">string</td> <td jstcache="0">Optional. Controls when the
files in <code jstcache="0">js</code> are injected. Can be <code jstcache="0">"
document_start"</code> or <code jstcache="0">"document_end"</code>. Defaults to
<code jstcache="0">"document_end"</code>. In the case of <code jstcache="0">"doc
ument_start"</code>, the files are injected after any files from <code jstcache=
"0">"css"</code>, but before any other DOM is constructed or any other script is
run. In the case of <code jstcache="0">"document_end"</code>, the files are inj
ected after the DOM is complete, but before subresources like images and frames
have necessarily loaded.</td> </tr> </tbody></table> <a name="H2-1" jstcache="0"
></a><h2 id="execution_environment" jstcache="0">Execution environment</h2> <p j
stcache="0">Content scripts execute in a special environment called an <em jstca
che="0">isolated world</em>. They have access to the DOM of the page they are in
jected into, but not to any JavaScript variables or functions created by the pag
e. It looks to each content script as if there is no other JavaScript executing
on the page it is running on. The same is true in reverse: JavaScript running on
the page cannot call any functions or access any variables defined by content s
cripts. </p><p jstcache="0">For example, consider this simple page: </p><pre jst
cache="0">hello.html =========== <html> <button id="button">click me
</button> <script> var greeting = "hello!"; function sayGreeting() {
alert(greeting); } document.getElementById("button").onclick = sayGreeting; <
;/script> </html></pre> <p jstcache="0">Now, suppose this content scrip
t was injected into hello.html: </p><pre jstcache="0">contentscript.js =========
========= console.log(greeting); // undefined console.log(sayGreeting); // undef
ined console.log(document.getElementById("button").onclick); // still undefined
document.getElementById("button").onclick = function() { alert("hola!"); }</pre>
<p jstcache="0">Now, if the button is pressed, you will see both greetings. </p
><p jstcache="0">Isolated worlds allow each content script to make changes to it
s JavaScript environment without worrying about conflicting with the page or wit
h other contnet scripts. For example, a content script could include JQuery v1 a
nd the page could include JQuery v2, and they wouldn't conflict with each other.
</p><p jstcache="0">Another important benefit of isolated worlds is that they c
ompletely separate the JavaScript on the page from the JavaScript in extensions.
This allows us to offer extra functionality to content scripts that should not
be accessible from web pages without worrying about web pages accessing it. </p>
<a name="H2-2" jstcache="0"></a><h2 id="messaging" jstcache="0">Messaging</h2> <
p jstcache="0">Content scripts can communicate with their parent extension using
message passing. The content script opens a channel to the extension using the
<a href="extension.html#connect" jstcache="0">chrome.extension.connect()</a> met
hod and then sends messages back and forth to it. The messages can contain any v
alid JSON object (null, boolean, number, string, array, or object). </p><p jstca
che="0">The parent extension can also open a channel to a content script in a gi
ven tab by calling <a href="tabs.html#connect" jstcache="0">chrome.tabs.connect(
tabId)</a>. </p><p jstcache="0">When a channel is opened from a content script t
o an extension, the <a href="extension.html#onConnect" jstcache="0">onConnect</a
> event is fired in all views in the extension. Any view can receive the event.
The event contains a <a href="extension.html#port" jstcache="0">Port</a> object,
which can be used by the extension view to communicate back to the content scri
pt. </p><p class="comment" jstcache="0">[TODO: Complete this]</p> <a name="H2-3"
jstcache="0"></a><h2 id="hostPageCommuncation" jstcache="0">Communication with
the embedding page</h2> <p jstcache="0">Although the execution environments of c
ontent scripts and the pages that host them are isolated from each other, they s
hare access to the page's DOM. If the page wishes to communicate with the conten
t script (or with the extension via the content script), it must do so through t
he shared DOM.</p> <p jstcache="0">An example can be accomplished using custom D
OM events and storing data in a known location. Consider: </p> <pre jstcache="0"
>http://foo.com/example.html ================================ var customEvent =
document.createEvent('Event'); customEvent.initEvent('myCustomEvent', true, true
); function fireCustomEvent(data) { hidenDiv = document.getElementById('myCustom
EventDiv'); hidenDiv.innerHTML = data hidenDiv.dispatchEvent(customEvent); }</pr
e> <pre jstcache="0">contentscript.js ===================== var port = chrome.ex
tension.connect(); document.getElementById('myCustomEventDiv').addEventListener(
'myCustomEvent', function() { var eventData = document.getElementById('myCustomE
ventDiv').innerHTML; port.postMessage({message: "myCustomEvent", values: eventDa
ta}); });</pre> <p jstcache="0">In the above example, example.html (which is not
a part of the extension) creates a custom event and then can decide to fire the
event by setting the event data to a known location in the DOM and then dispatc
hing the custom event. The content script listens for the name of the custom eve
nt on the known element and handles the event by inspecting the data of the elem
ent, and turning around to post the message to the extension process. In this wa
y the page establishes a line of communication to the extension. The reverse is
possible through similar means.</p> <a name="H2-4" jstcache="0"></a><h2 id="exte
nsionFiles" jstcache="0">Referring to extension files</h2> <p jstcache="0"> Get
the URL of an extension's file using <code jstcache="0">chrome.extension.getURL(
)</code>. You can use the result just like you would any other URL, as the follo
wing code shows. </p> <pre jstcache="0"><em jstcache="0">//Code for displaying &
lt;extensionDir>/images/myimage.png:</em> var imgURL = <b jstcache="0">chrome
.extension.getURL("images/myimage.png")</b>; document.getElementById("someImage"
).src = imgURL; </pre> </div> <!-- API PAGE --> <div class="apiPage" jsselect="a
piDefinition" jstcache="3" style="display: none; "> <a name="apiReference" jstca
che="0"></a> <h2 jscontent="'API reference: ' + getModuleName()" jstcache="4">AP
I reference: chrome.apiname </h2> <!-- PROPERTIES --> <div jsdisplay="$this.prop
erties" class="apiGroup" jstcache="5"> <a name="properties" jstcache="0"></a> <h
3 id="properties" jstcache="0">Properties</h3> <div jsselect="getPropertyListFro
mObject($this)" jstcache="10"> <a jsvalues=".name:'property-' + name" jstcache="
15"></a> <h4 jscontent="name" jstcache="16">getLastError</h4> <div class="summar
y" jstcache="0"> <!-- Note: intentionally longer 80 columns --> <span jscontent=
"getModuleName() + '.'" jstcache="23">chrome.extension</span><span jscontent="$t
his.name" jstcache="24">lastError</span> </div> <div transclude="valueTemplate"
jstcache="17"> </div> </div> </div> <!-- /apiGroup --> <!-- METHODS --> <div jsd
isplay="functions && functions.length > 0" class="apiGroup" id="metho
ds" jstcache="6"> <a name="methods" jstcache="0"></a> <h3 jstcache="0">Methods</
h3> <!-- iterates over all functions --> <div class="apiItem" jsselect="function
s" jstcache="11"> <a jsvalues=".name:'method-' + name" jstcache="18"></a> <!-- m
ethod-anchor --> <h4 jscontent="name" jstcache="16">method name</h4> <div class=
"summary" jstcache="0"><span jsdisplay="returns" jscontent="getTypeName(returns)
" jstcache="25">void</span> <!-- Note: intentionally longer 80 columns --> <span
jscontent="getFullyQualifiedFunctionName($this)" jstcache="26">chrome.module.me
thodName</span>(<span jsselect="parameters" jsvalues="class:optional ? 'optional
' : ''" jstcache="27"><span jsdisplay="$index" jstcache="33">, </span><span jsco
ntent="getTypeName($this)" jstcache="34"></span> <var jstcache="0"><span jsconte
nt="name" jstcache="16"></span></var></span>)</div> <div class="description" jst
cache="0"> <p class="todo" jsdisplay="!description" jstcache="28">Undocumented.<
/p> <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="29">
A description from the json schema def of the function goes here. </p> <!-- PARA
METERS --> <h4 jstcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="par
ameters" jstcache="35"> <!-- VALUE: This is a subtemplate that is used elsewhere
via jsTemplate *transclude* --> <div id="valueTemplate" jstcache="0"> <dt jstca
che="0"> <var jsdisplay="$this.name" jscontent="$this.name" jstcache="45">paramN
ame</var> <em jstcache="0"> <!-- TYPE --> <div style="display:inline" jstcache="
0"> ( <span class="optional" jsdisplay="optional" jstcache="46">optional</span>
<span id="typeTemplate" jstcache="0"> <span jsdisplay="getTypeRef($this)" jstcac
he="47"> <a jsvalues=".href: getTypeRefPage($this) + '#type-' + getTypeRef($this
)" jscontent="getTypeRef($this)" jstcache="49"> Type</a> </span> <span jsdisplay
="!getTypeRef($this)" jstcache="48"> <span jsdisplay="isArray($this)" jstcache="
50"> array of <span jsselect="items" jstcache="52"><span transclude="typeTemplat
e" jstcache="53"></span></span> </span> <span jsdisplay="!isArray($this)" jscont
ent="getTypeName($this)" jstcache="51">paramType</span> </span> </span> ) </div>
</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="38"> Undo
cumented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.des
cription" jstcache="39"> Description of this parameter from the json schema. </d
d> <!-- OBJECT PROPERTIES --> <dd jsdisplay="shouldExpandObject($this)" jstcache
="40"> <dl jstcache="0"> <div jsselect="getPropertyListFromObject($this)" jstcac
he="10"> <div transclude="valueTemplate" jstcache="17"> </div> </div> </dl> </dd
> </div> <!-- /VALUE --> </div> </dl> <!-- RETURNS --> <h4 jsdisplay="returns" j
stcache="30">Returns</h4> <dl jstcache="0"> <div jsselect="returns" jstcache="36
"> <div transclude="valueTemplate" jstcache="17"> </div> </div> </dl> <!-- CALLB
ACK --> <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"> <p jstcache="0"> Except as otherwise <a href="http:
//code.google.com/policies.html#restrictions" jstcache="0">noted</a>, the conten
t of this page is licensed under the <a rel="license" href="http://creativecommo
ns.org/licenses/by/3.0/" jstcache="0">Creative Commons Attribution 3.0 License</
a>, and code samples are licensed under the <a rel="license" href="http://code.g
oogle.com/google_bsd_license.html" jstcache="0">BSD License</a>. </p> <p jstcach
e="0"> ©2009 Google </p> </div> <!-- /pageFooter --> </div> <!-- /container -->
</body></html> | 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 |
| 3 across api docs and should be edited only with knowledge of the |
| 4 templating mechanism. |
| 5 2) The <body> tag *must* retain id="body" |
| 6 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a |
| 7 browser, it will be re-generated from the template, json schema and |
| 8 authored overview content. |
| 9 4) The <body>.innerHTML is also generated by an offline step so that this |
| 10 page may easily be indexed by search engines. |
| 11 |
| 12 TODO(rafaelw): Abstract this into a "pageshell" that becomes the single |
| 13 version of page template shell and the "instance" pages (bookmarks.html, |
| 14 etc...) can be generated with a build step. |
| 15 --><!-- <html> must retain id="template --><html xmlns="http://www.w3.org/1999/x
html" jstcache="0"><!-- <head> data is significant and loads the needed librarie
s and styles --><head jstcache="0"> |
| 16 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" jstcache=
"0"> |
| 17 <title jscontent="getPageTitle()" jstcache="1">Content Scripts</title> |
| 18 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css" jstcache=
"0"> |
| 19 <script type="text/javascript" src="../../../third_party/jstemplate/jstempla
te_compiled.js" jstcache="0"> |
| 20 </script> |
| 21 <script type="text/javascript" src="js/api_page_generator.js" jstcache="0"><
/script> |
| 22 <script type="text/javascript" src="js/bootstrap.js" jstcache="0"></script> |
| 23 </head><!-- <body> content is completely generated. Do not edit, as it will be |
| 24 and rewritten. --><body jstcache="0"> <div id="container" jstcache="0"> |
| 25 <a name="top" jstcache="0"> </a> |
| 26 <!-- API HEADER --> |
| 27 <div id="pageHeader" jstcache="0"> |
| 28 <div id="searchbox" jstcache="0"> |
| 29 <form action="http://www.google.com/cse" id="cse-search-box" jstcache="0
"> |
| 30 <div jstcache="0"> |
| 31 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfq
tno" jstcache="0"> |
| 32 <input type="hidden" name="ie" value="UTF-8" jstcache="0"> |
| 33 <input type="text" name="q" size="31" jstcache="0"> |
| 34 <input type="submit" name="sa" value="Search" jstcache="0"> |
| 35 </div> |
| 36 </form> |
| 37 |
| 38 <script type="text/javascript" src="http://www.google.com/jsapi" jstcach
e="0"></script> |
| 39 <script type="text/javascript" jstcache="0">google.load("elements", "1",
{packages: "transliteration"});</script> |
| 40 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?
form=cse-search-box&t13n_langs=en" jstcache="0"></script> |
| 41 <script type="text/javascript" src="http://www.google.com/coop/cse/brand
?form=cse-search-box&lang=en" jstcache="0"></script> |
| 42 </div> |
| 43 <div id="pageTitle" jstcache="0"> |
| 44 <h1 jscontent="getPageTitle()" jstcache="1">Content Scripts</h1> |
| 45 </div> |
| 46 </div> <!-- /pageHeader --> |
| 47 |
| 48 <div id="pageContent" jstcache="0"> |
| 49 <!-- SIDENAV --> |
| 50 <div id="leftNav" jstcache="0"> |
| 51 <ul jstcache="0"> |
| 52 <li jstcache="0"> <a href="index.html" jstcache="0">Home</a></li> |
| 53 <li jstcache="0"> <a href="getstarted.html" jstcache="0">Getting Start
ed</a></li> |
| 54 <li jstcache="0"> <a href="overview.html" jstcache="0">Overview</a></l
i> |
| 55 <li jstcache="0"> <a href="devguide.html" jstcache="0"><div jstcache="
0">Developer's Guide</div></a> |
| 56 <ul jstcache="0"> |
| 57 <li jstcache="0"><a href="toolstrip.html" jstcache="0">Toolstrips<
/a></li> |
| 58 <li jstcache="0"><a href="pageActions.html" jstcache="0">Page Acti
ons</a></li> |
| 59 <li jstcache="0"><a href="background_pages.html" jstcache="0">Back
ground Pages</a></li> |
| 60 <li jstcache="0" class="leftNavSelected">Content Scripts</li> |
| 61 <li jstcache="0"><a href="events.html" jstcache="0">Events</a></li
> |
| 62 <li jstcache="0"><a href="tabs.html" jstcache="0">Tabs</a></li> |
| 63 <li jstcache="0"><a href="windows.html" jstcache="0">Windows</a></
li> |
| 64 <li jstcache="0"><a href="bookmarks.html" jstcache="0">Bookmarks</
a></li> |
| 65 <li jstcache="0"><a href="themes.html" jstcache="0">Themes</a></li
> |
| 66 <li jstcache="0"><a href="npapi.html" jstcache="0">NPAPI Plugins</
a></li> |
| 67 <li jstcache="0"><a href="packaging.html" jstcache="0">Packaging</
a></li> |
| 68 <li jstcache="0">Autoupdate</li> |
| 69 </ul> |
| 70 </li> |
| 71 <li jstcache="0"><a href="tutorials.html" jstcache="0"><div jstcache="
0">Tutorials</div></a> |
| 72 <ul jstcache="0"> |
| 73 <li jstcache="0"><a href="tut_debugging.html" jstcache="0">Debuggi
ng</a></li> |
| 74 </ul> |
| 75 </li> |
| 76 <li jstcache="0">Reference |
| 77 <ul jstcache="0"> |
| 78 <li jstcache="0"> Formats |
| 79 <ul jstcache="0"> |
| 80 <li jstcache="0"><a href="manifest.html" jstcache="0">Manifest
Files</a></li> |
| 81 <li jstcache="0"><a href="match_patterns.html" jstcache="0">Ma
tch Patterns</a></li> |
| 82 <li jstcache="0">Packages (.crx)</li> |
| 83 </ul> |
| 84 </li> |
| 85 <li jstcache="0"> <a href="api_index.html" jstcache="0">chrome.* A
PIs</a> </li> |
| 86 <li jstcache="0"> <a href="api_other.html" jstcache="0">Other APIs
</a> </li> |
| 87 </ul> |
| 88 </li> |
| 89 <li jstcache="0"><a href="http://dev.chromium.org/developers/design-doc
uments/extensions/samples" jstcache="0">Samples</a></li> |
| 90 </ul> |
| 91 </div> |
| 92 |
| 93 <div id="mainColumn" jstcache="0"> |
| 94 <!-- TABLE OF CONTENTS --> |
| 95 <div id="toc" jsdisplay="showPageTOC()" jstcache="2"> |
| 96 <p jstcache="0">Contents</p> |
| 97 <ol jstcache="0"> |
| 98 <li jsselect="getStaticTOC()" jstcache="9" jsinstance="0"> |
| 99 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href
="#registration">Manifest</a> |
| 100 <ol jstcache="0"> |
| 101 <li jsselect="$this.children" jstcache="22" jsinstance="*0" styl
e="display: none; "> |
| 102 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">
h3Name</a> |
| 103 </li> |
| 104 </ol> |
| 105 </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="1"> |
| 106 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href
="#execution_environment">Execution environment</a> |
| 107 <ol jstcache="0"> |
| 108 <li jsselect="$this.children" jstcache="22" jsinstance="*0" styl
e="display: none; "> |
| 109 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">
h3Name</a> |
| 110 </li> |
| 111 </ol> |
| 112 </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="2"> |
| 113 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href
="#messaging">Messaging</a> |
| 114 <ol jstcache="0"> |
| 115 <li jsselect="$this.children" jstcache="22" jsinstance="*0" styl
e="display: none; "> |
| 116 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">
h3Name</a> |
| 117 </li> |
| 118 </ol> |
| 119 </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="3"> |
| 120 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href
="#hostPageCommuncation">Communication with the embedding page</a> |
| 121 <ol jstcache="0"> |
| 122 <li jsselect="$this.children" jstcache="22" jsinstance="*0" styl
e="display: none; "> |
| 123 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">
h3Name</a> |
| 124 </li> |
| 125 </ol> |
| 126 </li><li jsselect="getStaticTOC()" jstcache="9" jsinstance="*4"> |
| 127 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14" href
="#extensionFiles">Referring to extension files</a> |
| 128 <ol jstcache="0"> |
| 129 <li jsselect="$this.children" jstcache="22" jsinstance="*0" styl
e="display: none; "> |
| 130 <a jscontent="name" jsvalues=".href:'#' + href" jstcache="14">
h3Name</a> |
| 131 </li> |
| 132 </ol> |
| 133 </li> |
| 134 <div jsselect="apiDefinition" jstcache="3" style="display: none; "> |
| 135 <li jstcache="0"> |
| 136 <a href="#apiReference" jscontent="'API reference: ' + getModule
Name()" jstcache="4">API reference</a> |
| 137 <ol jstcache="0"> |
| 138 <li jsdisplay="$this.properties" jstcache="5"> |
| 139 <a href="#properties" jstcache="0">Properties</a> |
| 140 <ol jstcache="0"> |
| 141 <li jsselect="getPropertyListFromObject($this)" jstcache="
10"> |
| 142 <a jscontent="name" jsvalues=".href:'#property-' + name"
href="#property-anchor" jstcache="42">propertyName</a> |
| 143 </li> |
| 144 </ol> |
| 145 </li> |
| 146 <li jsdisplay="functions && functions.length > 0" j
stcache="6"> |
| 147 <a href="#methods" jstcache="0">Methods</a> |
| 148 <ol jstcache="0"> |
| 149 <li jsselect="functions.sort(sortByName)" jstcache="11"> |
| 150 <a jscontent="name" jsvalues=".href:'#method-' + name" h
ref="#method-anchor" jstcache="43">methodName</a> |
| 151 </li> |
| 152 </ol> |
| 153 </li> |
| 154 <li jsdisplay="events && events.length > 0" jstcach
e="7"> |
| 155 <a href="#events" jstcache="0">Events</a> |
| 156 <ol jstcache="0"> |
| 157 <li jsselect="events.sort(sortByName)" jstcache="12"> |
| 158 <a jscontent="name" jsvalues=".href:'#event-' + name" hr
ef="#event-anchor" jstcache="44">eventName</a> |
| 159 </li> |
| 160 </ol> |
| 161 </li> |
| 162 <li jsdisplay="types && types.length > 0" jstcache=
"8"> |
| 163 <a href="#types" jstcache="0">Types</a> |
| 164 <ol jstcache="0"> |
| 165 <li jsselect="types.sort(sortByName)" jstcache="38"> |
| 166 <a jscontent="id" jsvalues=".href:'#type-' + id" href="#
id-anchor" jstcache="45">id</a> |
| 167 </li> |
| 168 </ol> |
| 169 </li> |
| 170 </ol> |
| 171 </li> |
| 172 </div> |
| 173 </ol> |
| 174 </div> |
| 175 <!-- /TABLE OF CONTENTS --> |
| 176 |
| 177 <!-- STATIC CONTENT PLACEHOLDER --> |
| 178 <div id="static" jstcache="0"><div id="pageData-title" class="pageData"
jstcache="0">Content Scripts</div> |
| 179 <div id="pageData-showTOC" class="pageData" jstcache="0">true</div> |
| 180 |
| 181 <p jstcache="0">Content Scripts are JavaScript files that run in the context of
web pages. By using the standard <a href="http://www.w3.org/TR/DOM-Level-2-HTML/
" jstcache="0">Document Object Model</a> (DOM), they can read details of the web
pages the browser visits, or make changes to them. |
| 182 |
| 183 </p><p jstcache="0">Some examples of things that content scripts can do include: |
| 184 |
| 185 </p><ul jstcache="0"> |
| 186 <li jstcache="0">Find unlinked URLs in web pages and convert them into hyperli
nks |
| 187 </li><li jstcache="0">Increase the font size to make text more legible |
| 188 </li><li jstcache="0">Find and process <a href="http://microformats.org/" jstc
ache="0">microformat</a> data in the DOM |
| 189 </li></ul> |
| 190 |
| 191 <h2 id="registration" jstcache="0">Manifest</h2> |
| 192 |
| 193 <p jstcache="0">Content scripts are registered in an extension's <a href="manife
st.html" jstcache="0">manifest.json</a> file, like so: |
| 194 |
| 195 </p><pre jstcache="0">{ |
| 196 "name": "My First Extension", |
| 197 "version": "1.0", |
| 198 "description": "The first extension that I made.", |
| 199 <span style="background:yellow; font-weight:bold;" jstcache="0"> "content_scrip
ts": [ |
| 200 { |
| 201 "matches": ["http://www.google.com/*"], |
| 202 "css": ["mystyles.css"], |
| 203 "js": ["jquery.js", "myscript.js"] |
| 204 } |
| 205 ]</span> |
| 206 }</pre> |
| 207 |
| 208 <p jstcache="0">An extension can contain any number of content scripts, and a co
ntent script can consist of any number of JavaScript or CSS files. The value of
the <code jstcache="0">matches</code> property controls when the content script
will run. |
| 209 |
| 210 </p><p jstcache="0">Each content script registered in the manifest can specify t
he following properties:</p> |
| 211 |
| 212 <table jstcache="0"> |
| 213 <tbody jstcache="0"><tr jstcache="0"> |
| 214 <th jstcache="0">Name</th> |
| 215 <th jstcache="0">Type</th> |
| 216 <th jstcache="0">Description</th> |
| 217 </tr> |
| 218 <tr jstcache="0"> |
| 219 <td jstcache="0">matches</td> |
| 220 <td jstcache="0">array of strings</td> |
| 221 <td jstcache="0">Required. Controls the pages this content script will be in
jected into. |
| 222 See <a href="match_patterns.html" jstcache="0">Match Patterns</a> |
| 223 for more details on the syntax of these strings.</td> |
| 224 </tr> |
| 225 <tr jstcache="0"> |
| 226 <td jstcache="0">js</td> |
| 227 <td jstcache="0"><nobr jstcache="0">array of strings</nobr></td> |
| 228 <td jstcache="0">Optional. The list of JavaScript files to be injected into
matching pages. These are injected in the order they appear in this array.</td> |
| 229 </tr> |
| 230 <tr jstcache="0"> |
| 231 <td jstcache="0">css</td> |
| 232 <td jstcache="0">array of strings</td> |
| 233 <td jstcache="0">Optional. The list of CSS files to be injected into matchin
g pages. These are injected in the order they appear in this array, before any D
OM is constructed or displayed for the page.</td> |
| 234 </tr> |
| 235 <tr jstcache="0"> |
| 236 <td jstcache="0">run_at</td> |
| 237 <td jstcache="0">string</td> |
| 238 <td jstcache="0">Optional. Controls when the files in <code jstcache="0">js<
/code> are injected. Can be <code jstcache="0">"document_start"</code> or <code
jstcache="0">"document_end"</code>. Defaults to <code jstcache="0">"document_end
"</code>. In the case of <code jstcache="0">"document_start"</code>, the files a
re injected after any files from <code jstcache="0">"css"</code>, but before any
other DOM is constructed or any other script is run. In the case of <code jstca
che="0">"document_end"</code>, the files are injected after the DOM is complete,
but before subresources like images and frames have necessarily loaded.</td> |
| 239 </tr> |
| 240 </tbody></table> |
| 241 |
| 242 |
| 243 <h2 id="execution_environment" jstcache="0">Execution environment</h2> |
| 244 |
| 245 <p jstcache="0">Content scripts execute in a special environment called an <em j
stcache="0">isolated world</em>. They have access to the DOM of the page they ar
e injected into, but not to any JavaScript variables or functions created by the
page. It looks to each content script as if there is no other JavaScript execut
ing on the page it is running on. The same is true in reverse: JavaScript runnin
g on the page cannot call any functions or access any variables defined by conte
nt scripts. |
| 246 |
| 247 </p><p jstcache="0">For example, consider this simple page: |
| 248 |
| 249 </p><pre jstcache="0">hello.html |
| 250 =========== |
| 251 <html> |
| 252 <button id="button">click me</button> |
| 253 <script> |
| 254 var greeting = "hello!"; |
| 255 function sayGreeting() { |
| 256 alert(greeting); |
| 257 } |
| 258 document.getElementById("button").onclick = sayGreeting; |
| 259 </script> |
| 260 </html></pre> |
| 261 |
| 262 <p jstcache="0">Now, suppose this content script was injected into hello.html: |
| 263 |
| 264 </p><pre jstcache="0">contentscript.js |
| 265 ================== |
| 266 console.log(greeting); // undefined |
| 267 console.log(sayGreeting); // undefined |
| 268 console.log(document.getElementById("button").onclick); // still undefined |
| 269 document.getElementById("button").onclick = function() { |
| 270 alert("hola!"); |
| 271 }</pre> |
| 272 |
| 273 <p jstcache="0">Now, if the button is pressed, you will see both greetings. |
| 274 |
| 275 </p><p jstcache="0">Isolated worlds allow each content script to make changes to
its JavaScript environment without worrying about conflicting with the page or
with other contnet scripts. For example, a content script could include JQuery v
1 and the page could include JQuery v2, and they wouldn't conflict with each oth
er. |
| 276 |
| 277 </p><p jstcache="0">Another important benefit of isolated worlds is that they co
mpletely separate the JavaScript on the page from the JavaScript in extensions.
This allows us to offer extra functionality to content scripts that should not b
e accessible from web pages without worrying about web pages accessing it. |
| 278 |
| 279 </p><h2 id="messaging" jstcache="0">Messaging</h2> |
| 280 |
| 281 <p jstcache="0">Content scripts can communicate with their parent extension usin
g message passing. A message channel can be opened by either the content script
or an extension page. Each side of the channel has a <a href="extension.html#por
t" jstcache="0">Port</a> object which can be used to send messages to the other
side. The messages can contain any valid JSON object (null, boolean, number, str
ing, array, or object). |
| 282 |
| 283 </p><p jstcache="0">The content script opens a channel to the extension using th
e <a href="extension.html#connect" jstcache="0">chrome.extension.connect()</a> m
ethod. The parent extension can also open a channel to a content script in a giv
en tab by calling <a href="tabs.html#connect" jstcache="0">chrome.tabs.connect(t
abId)</a>. In either case, the <a href="extension.html#onConnect" jstcache="0">o
nConnect</a> event is fired in the targeted page(s), and a connection is establi
shed. |
| 284 |
| 285 </p><p jstcache="0">When a channel is opened from a content script to an extensi
on, the event is |
| 286 fired in all views in the extension. Any view can receive the event. |
| 287 |
| 288 </p><p jstcache="0">For example, suppose you want to write a simple login manage
r. You want a toolstrip button that lights up when a content script detects a "l
ogin" element in a page, and fills in the login info when you press the button. |
| 289 |
| 290 </p><p jstcache="0">Your content script would look like this: |
| 291 |
| 292 </p><pre jstcache="0">contentscript.js |
| 293 ================ |
| 294 var e = document.getElementById("login"); |
| 295 |
| 296 // Create a short-lived named channel to the extension and send a single |
| 297 // message through it. |
| 298 var port = chrome.extension.connect({name: "notifyChannel"}); |
| 299 port.postMessage({found: (e != undefined)}); |
| 300 |
| 301 // Also listen for new channels from the extension for when the button is |
| 302 // pressed. |
| 303 chrome.extension.onConnect.addListener(function(port, name) { |
| 304 console.assert(name == "buttonClickedChannel"); |
| 305 port.onMessage.addListener(function(msg) { |
| 306 if (msg.buttonClicked) { |
| 307 e.value = msg.passwordValue; |
| 308 } |
| 309 }); |
| 310 }); |
| 311 </pre> |
| 312 |
| 313 <p jstcache="0">with a toolstrip that looks like: |
| 314 |
| 315 </p><pre jstcache="0">toolstrip.html |
| 316 ============== |
| 317 <div class="toolstrip-button" id="btn" onclick="onClick()"> |
| 318 Fill Password |
| 319 </div> |
| 320 <script> |
| 321 // Listen for notifications from the content script. |
| 322 chrome.extension.onConnect.addListener(function(port, name) { |
| 323 console.assert(name == "notifyChannel"); |
| 324 port.onMessage.addListener(function(msg) { |
| 325 // Color our button based on whether a login element was found. |
| 326 var color = msg.found ? "blue" : "grey"; |
| 327 document.getElementById("btn").style.backgroundColor = color; |
| 328 }); |
| 329 }); |
| 330 function onClick() { |
| 331 // Send our password to the current tab when clicked. |
| 332 chrome.tabs.getSelected(null, function(tab) { |
| 333 var port = chrome.tabs.connect(tab.id, {name: "buttonClickedChannel"}); |
| 334 port.postMessage({buttonClicked: true}); |
| 335 }); |
| 336 } |
| 337 </script> |
| 338 </pre> |
| 339 |
| 340 <h2 id="hostPageCommuncation" jstcache="0">Communication with the embedding page
</h2> |
| 341 |
| 342 <p jstcache="0">Although the execution environments of content scripts and the p
ages that host them are isolated from each other, they share access to the page'
s DOM. If the page wishes to communicate with the content script (or with the ex
tension via the content script), it must do so through the shared DOM.</p> |
| 343 |
| 344 <p jstcache="0">An example can be accomplished using custom DOM events and stori
ng data in a known location. Consider: </p> |
| 345 |
| 346 <pre jstcache="0">http://foo.com/example.html |
| 347 ================================ |
| 348 var customEvent = document.createEvent('Event'); |
| 349 customEvent.initEvent('myCustomEvent', true, true); |
| 350 |
| 351 function fireCustomEvent(data) { |
| 352 hidenDiv = document.getElementById('myCustomEventDiv'); |
| 353 hidenDiv.innerHTML = data |
| 354 hidenDiv.dispatchEvent(customEvent); |
| 355 }</pre> |
| 356 |
| 357 <pre jstcache="0">contentscript.js |
| 358 ===================== |
| 359 var port = chrome.extension.connect(); |
| 360 |
| 361 document.getElementById('myCustomEventDiv').addEventListener('myCustomEvent', fu
nction() { |
| 362 var eventData = document.getElementById('myCustomEventDiv').innerHTML; |
| 363 port.postMessage({message: "myCustomEvent", values: eventData}); |
| 364 });</pre> |
| 365 |
| 366 <p jstcache="0">In the above example, example.html (which is not a part of the e
xtension) creates a custom event and then can decide to fire the event by settin
g the event data to a known location in the DOM and then dispatching the custom
event. The content script listens for the name of the custom event on the known
element and handles the event by inspecting the data of the element, and turning
around to post the message to the extension process. In this way the page estab
lishes a line of communication to the extension. The reverse is possible through
similar means.</p> |
| 367 |
| 368 <h2 id="extensionFiles" jstcache="0">Referring to extension files</h2> |
| 369 |
| 370 <p jstcache="0"> |
| 371 Get the URL of an extension's file using |
| 372 <code jstcache="0">chrome.extension.getURL()</code>. |
| 373 You can use the result |
| 374 just like you would any other URL, |
| 375 as the following code shows. |
| 376 </p> |
| 377 |
| 378 |
| 379 <pre jstcache="0"><em jstcache="0">//Code for displaying <extensionDir>/im
ages/myimage.png:</em> |
| 380 var imgURL = <b jstcache="0">chrome.extension.getURL("images/myimage.png")</b>; |
| 381 document.getElementById("someImage").src = imgURL; |
| 382 </pre> |
| 383 </div> |
| 384 |
| 385 <!-- API PAGE --> |
| 386 <div class="apiPage" jsselect="apiDefinition" jstcache="3" style="displa
y: none; "> |
| 387 <a name="apiReference" jstcache="0"></a> |
| 388 <h2 jscontent="'API reference: ' + getModuleName()" jstcache="4">API ref
erence: chrome.apiname </h2> |
| 389 |
| 390 <!-- PROPERTIES --> |
| 391 <div jsdisplay="$this.properties" class="apiGroup" jstcache="5"> |
| 392 <a name="properties" jstcache="0"></a> |
| 393 <h3 id="properties" jstcache="0">Properties</h3> |
| 394 |
| 395 <div jsselect="getPropertyListFromObject($this)" jstcache="10"> |
| 396 <a jsvalues=".name:'property-' + name" jstcache="15"></a> |
| 397 <h4 jscontent="name" jstcache="16">getLastError</h4> |
| 398 <div class="summary" jstcache="0"> |
| 399 <!-- Note: intentionally longer 80 columns --> |
| 400 <span jscontent="getModuleName() + '.'" jstcache="23">chrome.ext
ension</span><span jscontent="$this.name" jstcache="24">lastError</span> |
| 401 </div> |
| 402 <div transclude="valueTemplate" jstcache="17"> |
| 403 </div> |
| 404 </div> |
| 405 |
| 406 </div> <!-- /apiGroup --> |
| 407 |
| 408 <!-- METHODS --> |
| 409 <div jsdisplay="functions && functions.length > 0" class="a
piGroup" id="methods" jstcache="6"> |
| 410 <a name="methods" jstcache="0"></a> |
| 411 <h3 jstcache="0">Methods</h3> |
| 412 |
| 413 <!-- iterates over all functions --> |
| 414 <div class="apiItem" jsselect="functions.sort(sortByName)" jstcache=
"11"> |
| 415 <a jsvalues=".name:'method-' + name" jstcache="18"></a> <!-- metho
d-anchor --> |
| 416 <h4 jscontent="name" jstcache="16">method name</h4> |
| 417 |
| 418 <div class="summary" jstcache="0"><span jsdisplay="returns" jscont
ent="getTypeName(returns)" jstcache="25">void</span> |
| 419 <!-- Note: intentionally longer 80 columns --> |
| 420 <span jscontent="getFullyQualifiedFunctionName($this)" jstcach
e="26">chrome.module.methodName</span>(<span jsselect="parameters" jsvalues="cla
ss:optional ? 'optional' : ''" jstcache="27"><span jsdisplay="$index" jstcache="
33">, </span><span jscontent="getTypeName($this)" jstcache="34"></span> |
| 421 <var jstcache="0"><span jscontent="name" jstcache="16"></s
pan></var></span>)</div> |
| 422 |
| 423 <div class="description" jstcache="0"> |
| 424 <p class="todo" jsdisplay="!description" jstcache="28">Undocumen
ted.</p> |
| 425 <p jsdisplay="description" jsvalues=".innerHTML:description" jst
cache="29"> |
| 426 A description from the json schema def of the function goes he
re. |
| 427 </p> |
| 428 |
| 429 <!-- PARAMETERS --> |
| 430 <h4 jstcache="0">Parameters</h4> |
| 431 <dl jstcache="0"> |
| 432 <div jsselect="parameters" jstcache="35"> |
| 433 |
| 434 <!-- VALUE: This is a subtemplate that is used elsewhere |
| 435 via jsTemplate *transclude* --> |
| 436 <div id="valueTemplate" jstcache="0"> |
| 437 <dt jstcache="0"> |
| 438 <var jsdisplay="$this.name" jscontent="$this.name" jstca
che="46">paramName</var> |
| 439 <em jstcache="0"> |
| 440 |
| 441 <!-- TYPE --> |
| 442 <div style="display:inline" jstcache="0"> |
| 443 ( |
| 444 <span class="optional" jsdisplay="optional" jstc
ache="47">optional</span> |
| 445 <span id="typeTemplate" jstcache="0"> |
| 446 <span jsdisplay="getTypeRef($this)" jstcache="
48"> |
| 447 <a jsvalues=".href: getTypeRefPage($this) +
'#type-' + getTypeRef($this)" jscontent="getTypeRef($this)" jstcache="50"> Type<
/a> |
| 448 </span> |
| 449 <span jsdisplay="!getTypeRef($this)" jstcache=
"49"> |
| 450 <span jsdisplay="isArray($this)" jstcache="5
1"> |
| 451 array of <span jsselect="items" jstcache="
53"><span transclude="typeTemplate" jstcache="54"></span></span> |
| 452 </span> |
| 453 <span jsdisplay="!isArray($this)" jscontent=
"getTypeName($this)" jstcache="52">paramType</span> |
| 454 </span> |
| 455 </span> |
| 456 ) |
| 457 </div> |
| 458 |
| 459 </em> |
| 460 </dt> |
| 461 <dd class="todo" jsdisplay="!$this.description" jstcache="
39"> |
| 462 Undocumented. |
| 463 </dd> |
| 464 <dd jsdisplay="$this.description" jsvalues=".innerHTML:$th
is.description" jstcache="40"> |
| 465 Description of this parameter from the json schema. |
| 466 </dd> |
| 467 |
| 468 <!-- OBJECT PROPERTIES --> |
| 469 <dd jsdisplay="shouldExpandObject($this)" jstcache="41"> |
| 470 <dl jstcache="0"> |
| 471 <div jsselect="getPropertyListFromObject($this)" jstca
che="10"> |
| 472 <div transclude="valueTemplate" jstcache="17"> |
| 473 </div> |
| 474 </div> |
| 475 </dl> |
| 476 </dd> |
| 477 </div> <!-- /VALUE --> |
| 478 |
| 479 </div> |
| 480 </dl> |
| 481 |
| 482 <!-- RETURNS --> |
| 483 <h4 jsdisplay="returns" jstcache="30">Returns</h4> |
| 484 <dl jstcache="0"> |
| 485 <div jsselect="returns" jstcache="36"> |
| 486 <div transclude="valueTemplate" jstcache="17"> |
| 487 </div> |
| 488 </div> |
| 489 </dl> |
| 490 |
| 491 <!-- CALLBACK --> |
| 492 <div jsdisplay="hasCallback(parameters)" jstcache="31"> |
| 493 <div jsselect="getCallbackParameters(parameters)" jstcache="37
"> |
| 494 <h4 jstcache="0">Callback function</h4> |
| 495 <p jstcache="0"> |
| 496 If you specify the <em jstcache="0">callback</em> parameter, |
| 497 it should specify a function that looks like this: |
| 498 </p> |
| 499 |
| 500 <!-- Note: intentionally longer 80 columns --> |
| 501 <pre jstcache="0">function(<span jscontent="getSignatureString
(parameters)" jstcache="32">Type param1, Type param2</span>) <span class="subdue
d" jstcache="0">{...}</span>);</pre> |
| 502 <dl jstcache="0"> |
| 503 <div jsselect="parameters" jstcache="35"> |
| 504 <div transclude="valueTemplate" jstcache="17"> |
| 505 </div> |
| 506 </div> |
| 507 </dl> |
| 508 </div> |
| 509 </div> |
| 510 |
| 511 </div> <!-- /description --> |
| 512 |
| 513 </div> <!-- /apiItem --> |
| 514 |
| 515 </div> <!-- /apiGroup --> |
| 516 |
| 517 <!-- EVENTS --> |
| 518 <div jsdisplay="events && events.length > 0" class="apiGrou
p" jstcache="7"> |
| 519 <a name="events" jstcache="0"></a> |
| 520 <h3 id="events" jstcache="0">Events</h3> |
| 521 |
| 522 <!-- iterates over all events --> |
| 523 <div jsselect="events.sort(sortByName)" class="apiItem" jstcache="12
"> |
| 524 <a jsvalues=".name:'event-' + name" jstcache="19"></a> |
| 525 <h4 jscontent="name" jstcache="16">event name</h4> |
| 526 |
| 527 <div class="summary" jstcache="0"> |
| 528 <!-- Note: intentionally longer 80 columns --> |
| 529 <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>); |
| 530 </div> |
| 531 |
| 532 <div class="description" jstcache="0"> |
| 533 <p class="todo" jsdisplay="!description" jstcache="28">Undocumen
ted.</p> |
| 534 <p jsdisplay="description" jsvalues=".innerHTML:description" jst
cache="29"> |
| 535 A description from the json schema def of the event goes here. |
| 536 </p> |
| 537 |
| 538 <!-- PARAMETERS --> |
| 539 <h4 jstcache="0">Parameters</h4> |
| 540 <dl jstcache="0"> |
| 541 <div jsselect="parameters" jstcache="35"> |
| 542 <div transclude="valueTemplate" jstcache="17"> |
| 543 </div> |
| 544 </div> |
| 545 </dl> |
| 546 |
| 547 </div> <!-- /decription --> |
| 548 |
| 549 </div> <!-- /apiItem --> |
| 550 |
| 551 </div> <!-- /apiGroup --> |
| 552 |
| 553 <!-- TYPES --> |
| 554 <div jsdisplay="types && types.length > 0" class="apiGroup"
jstcache="8"> |
| 555 <a name="types.sort(sortByName)" jstcache="0"></a> |
| 556 <h3 id="types" jstcache="0">Types</h3> |
| 557 |
| 558 <!-- iterates over all types --> |
| 559 <div jsselect="types" class="apiItem" jstcache="13"> |
| 560 <a jsvalues=".name:'type-' + id" jstcache="20"></a> |
| 561 <h4 jscontent="id" jstcache="21">type name</h4> |
| 562 |
| 563 <div transclude="valueTemplate" jstcache="17"> |
| 564 </div> |
| 565 |
| 566 </div> <!-- /apiItem --> |
| 567 |
| 568 </div> <!-- /apiGroup --> |
| 569 |
| 570 </div> <!-- /apiPage --> |
| 571 </div> <!-- /mainColumn --> |
| 572 </div> <!-- /pageContent --> |
| 573 <div id="pageFooter" --="" jstcache="0"> |
| 574 <p jstcache="0"> |
| 575 Except as otherwise <a href="http://code.google.com/policies.html#restrictions
" jstcache="0">noted</a>, |
| 576 the content of this page is licensed under the <a rel="license" href="http://c
reativecommons.org/licenses/by/3.0/" jstcache="0">Creative Commons |
| 577 Attribution 3.0 License</a>, and code samples are licensed under the |
| 578 <a rel="license" href="http://code.google.com/google_bsd_license.html" jstcach
e="0">BSD License</a>. |
| 579 </p> |
| 580 <p jstcache="0"> |
| 581 ©2009 Google |
| 582 </p> |
| 583 </div> <!-- /pageFooter --> |
| 584 </div> <!-- /container --> |
| 585 </body></html> |
| 586 #EOF |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 179068:
Extension Doc Changes (no building or testable changes): minor changes for tab & windows doc (Closed)
