| 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="pageTitle" jstcache="1">Content_scripts</title> <link href
="css/ApiRefStyles.css" rel="stylesheet" type="text/css" jstcache="0"> <script t
ype="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.j
s" jstcache="0"> </script> <script type="text/javascript" src="js/api_page_gener
ator.js" jstcache="0"></script> <script type="text/javascript" src="js/bootstrap
.js" jstcache="0"></script> </head><!-- <body> content is completely generated.
Do not edit, as it will be and rewritten. --><body jstcache="0"> <div id="contai
ner" jstcache="0"> <a name="top" jstcache="0"> </a> <!-- API HEADER --> <div id=
"pageHeader" jstcache="0"> <!-- BREADCRUMB --> <!-- TODO: Fix these hrefs --> <d
iv id="breadcrumbs" jstcache="0"> <a href="index.html" jstcache="0">Google Chrom
e Extensions</a> > <a href="reference_index.html" jstcache="0">Reference</a>
> <a href="api_index.html" jstcache="0">chrome.* APIs</a> > <span jsconten
t="h1Header" jstcache="2">Content_scripts</span> </div> <div id="searchbox" jstc
ache="0"> <form action="http://www.google.com/cse" id="cse-search-box" jstcache=
"0"> <div jstcache="0"> <input type="hidden" name="cx" value="002967670403910741
006:61_cvzfqtno" jstcache="0"> <input type="hidden" name="ie" value="UTF-8" jstc
ache="0"> <input type="text" name="q" size="31" jstcache="0"> <input type="submi
t" name="sa" value="Search" jstcache="0"> </div> </form> <script type="text/java
script" src="http://www.google.com/jsapi" jstcache="0"></script> <script type="t
ext/javascript" jstcache="0">google.load("elements", "1", {packages: "transliter
ation"});</script> <script type="text/javascript" src="http://www.google.com/coo
p/cse/t13n?form=cse-search-box&t13n_langs=en" jstcache="0"></script> <script
type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-searc
h-box&lang=en" jstcache="0"></script> </div> <div id="pageTitle" jstcache="0
"> <h1 jscontent="h1Header" jstcache="2">Content_scripts</h1> </div> </div> <!--
/pageHeader --> <div id="pageContent" jstcache="0"> <!-- SIDENAV --> <div id="l
eftNav" jstcache="0"> <ul jstcache="0"> <li jstcache="0"> <a href="index.html" j
stcache="0">Home</a></li> <li jstcache="0"> <a href="getstarted.html" jstcache="
0">Get Started</a></li> <li jstcache="0"> <a href="overview.html" jstcache="0">O
verview</a></li> <li jstcache="0">Reference <ul jstcache="0"> <li jstcache="0"><
a href="manifest.html" jstcache="0">Manifest</a> </li><li jstcache="0"><a href="
toolstrip.html" jstcache="0">Toolstrips</a> </li><li jstcache="0"><a href="pageA
ctions.html" jstcache="0">Page actions</a> </li><li jstcache="0"><a href="backgr
ound_pages.html" jstcache="0">Background pages</a> </li><li jstcache="0"><a href
="content_scripts.html" jstcache="0">Content scripts</a> </li><li jstcache="0"><
a href="tabs.html" jstcache="0">Tabs</a> </li><li jstcache="0"><a href="windows.
html" jstcache="0">Windows</a> </li><li jstcache="0"><a href="self.html" jstcach
e="0">Self</a> </li><li jstcache="0"><a href="npapi.html" jstcache="0">NPAPI Plu
gins</a> </li><li jstcache="0"><a href="packaging.html" jstcache="0">Packaging</
a> </li><li jstcache="0"><a href="autoupdate.html" jstcache="0">Autoupdate</a> <
/li></ul> </li><li jstcache="0">Samples <ul jstcache="0"> <li jstcache="0">[samp
le 1] </li><li jstcache="0">[sample 2] </li></ul> </li></ul> </div> <div id="mai
nColumn" jstcache="0"> <!-- TABLE OF CONTENTS --> <div id="toc" jsselect="apiDef
inition" jstcache="3" style="display: none; "> <p jstcache="0">Contents</p> <ol
jstcache="0"> <li jstcache="0"> <a href="#overview" jstcache="0">Description</a>
<ol jstcache="0"> <li jstcache="0"><a href="#overview-properties" jstcache="0">
Properties</a></li> <li jstcache="0"><a href="#overview-examples" jstcache="0">E
xamples</a></li> </ol> </li> <li jstcache="0"> <a href="#methods" jstcache="0">M
ethods</a> <ol jstcache="0"> <li jsselect="functions" jstcache="4"> <a jscontent
="name" jsvalues=".href:'#method-' + name" href="#method-anchor" jstcache="17">m
ethodName</a> </li> </ol> </li> <li jstcache="0"> <a href="#events" jstcache="0"
>Events</a> <ol jstcache="0"> <li jsselect="events" jstcache="5"> <a jscontent="
name" jsvalues=".href:'#event-' + name" href="#event-anchor" jstcache="18">event
Name</a> </li> </ol> </li> <!-- TODO: What do we do about structs/types? --> <li
jstcache="0"> <a href="#structs" jstcache="0">TODO: Structs</a> <ol jstcache="0
"> <li jstcache="0"><a href="#struct-BookmarkTreeNode" jstcache="0"></a></li> </
ol> </li> </ol> [PENDING: links to all h2s and h3s should go here -- would it be
possible to link to overview h3s, as well? if so, how should we create their an
chor/id values?] </div> <!-- /TABLE OF CONTENTS --> <!-- STATIC CONTENT PLACEHOL
DER --> <div id="static" jstcache="0"><p jstcache="0">Content Scripts are JavaSc
ript 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. </p><p jstcache="0">Some examples of things that content scripts can d
o include: </p><ul jstcache="0"> <li jstcache="0">Find unlinked URLs in web page
s and convert them into hyperlinks </li><li jstcache="0">Increase the font size
to make text more legible </li><li jstcache="0">Find and process <a href="http:/
/microformats.org/" jstcache="0">microformat</a> data in the DOM </li></ul> <h3
id="registration" jstcache="0">Registration</h3> <p jstcache="0">Content 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 Extension", "v
ersion": "1.0", "description": "The first extension that I made.", <span style="
background:yellow; font-weight:bold;" jstcache="0"> "content_scripts": [ { "matc
hes": ["http://www.google.com/*"], "css": ["mystyles.css"], "js": ["jquery.js",
"myscript.js"] } ]</span> }</pre> <p jstcache="0">An extension can contain any n
umber of content scripts, and a content script can consist of any number of Java
Script 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 content scr
ipt registered in the manifest can specify the following properties:</p> <table
jstcache="0"> <tbody jstcache="0"><tr jstcache="0"> <th jstcache="0">Name</th> <
th jstcache="0">Type</th> <th jstcache="0">Description</th> </tr> <tr jstcache="
0"> <td jstcache="0">matches</td> <td jstcache="0">array of strings</td> <td jst
cache="0">Required. Controls the pages this content script will be injected into
. See <a href="#match_patterns" jstcache="0">Match Patterns</a> for more details
on the syntax of these strins.</td> </tr> <tr jstcache="0"> <td jstcache="0">js
</td> <td jstcache="0"><nobr jstcache="0">array of strings</nobr></td> <td jstca
che="0">Optional. The list of JavaScript files to be injected into matching page
s. These are injected in the order they appear in this array.</td> </tr> <tr jst
cache="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 are injected in the order they appear in this array, before any DOM is co
nstructed or displayed for the page.</td> </tr> <tr jstcache="0"> <td jstcache="
0">run_at</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 jstcac
he="0">"document_start"</code> or <code jstcache="0">"document_end"</code>. Defa
ults to <code jstcache="0">"document_end"</code>. In the case of <code jstcache=
"0">"document_start"</code>, the files are injected after any files from <code j
stcache="0">"css"</code>, but before any other DOM is constructed or any other s
cript is run. In the case of <code jstcache="0">"document_end"</code>, the files
are injected after the DOM is complete, but before subresources like images and
frames have necessarily loaded.</td> </tr> </tbody></table> <h3 id="match_patte
rns" jstcache="0">Match Patterns</h3> <p jstcache="0">TODO</p> <h3 id="execution
_environment" jstcache="0">Execution Environment</h3> <p jstcache="0">Content sc
ripts execute in a special environment called an <em jstcache="0">isolated world
</em>. They have access to the DOM of the page they are injected into, but not t
o any JavaScript variables or functions created by the page. It looks to each co
ntent script as if there is no other JavaScript executing on the page it is runn
ing on. The same is true in reverse: JavaScript running on the page cannot call
any functions or access any variables defined by content scripts. </p><p jstcach
e="0">For example, consider this simple page: </p><pre jstcache="0">hello.html =
========== <html> <button id="button">click me</button> <sc
ript> var greeting = "hello!"; function sayGreeting() { alert(greeting); } do
cument.getElementById("button").onclick = sayGreeting; </script> </html
></pre> <p jstcache="0">Now, suppose this content script was injected into he
llo.html: </p><pre jstcache="0">contentscript.js ================== console.log(
greeting); // undefined console.log(sayGreeting); // undefined console.log(docum
ent.getElementById("button").onclick); // still undefined document.getElementByI
d("button").onclick = function() { alert("hola!"); }</pre> <p jstcache="0">Now,
if the button is pressed, you will see both greetings. </p><p jstcache="0">Isola
ted worlds allow each content script to make changes to its JavaScript environme
nt without worrying about conflicting with the page or with other contnet script
s. For example, a content script could include JQuery v1 and the page could incl
ude JQuery v2, and they wouldn't conflict with each other. </p><p jstcache="0">A
nother important benefit of isolated worlds is that they completely separate the
JavaScript on the page from the JavaScript in extensions. This allows us to off
er extra functionality to content scripts that should not be accessible from web
pages without worrying about web pages accessing it. </p><h3 id="messaging" jst
cache="0">Messaging</h3> <p jstcache="0">Content scripts can communicate with th
eir parent extension using message passing. The content script opens a channel t
o the extension using the <a href="extension.html#connect" jstcache="0">chrome.e
xtension.connect()</a> method and then sends messages back and forth to it. The
messages can contain any valid JSON object (null, boolean, number, string, array
, or object). </p><p jstcache="0">The parent extension can also open a channel t
o a content script in a given tab by calling <a href="tabs.html#connect" jstcach
e="0">chrome.tabs.connect(tabId)</a>. </p><p jstcache="0">When a channel is open
ed from a content script to an extension, the <a href="extension.html#onConnect"
jstcache="0">onConnect</a> event is fired in all views in the extension. Any vi
ew can receive the event. The event contains a <a href="extension.html#port" jst
cache="0">Port</a> object, which can be used by the extension view to communicat
e back to the content script. </p><p jstcache="0">[TODO: Complete this] </p><h3
id="hostPageCommuncation" jstcache="0">Communication with the embedding page</h3
> <p jstcache="0">Although the execution environments of content scripts and the
pages that host them are isolated from each other, they share access to the pag
e's DOM. If the page wishes to communicate with the content script (or with the
extension via the content script), it must do so through the shared DOM.</p> <p
jstcache="0">An example can be accomplished using custom DOM events and storing
data in a known location. Consider: </p> <pre jstcache="0">http://foo.com/exampl
e.html ================================ var customEvent = document.createEvent('
Event'); customEvent.initEvent('myCustomEvent', true, true); function fireCustom
Event(data) { hidenDiv = document.getElementById('myCustomEventDiv'); hidenDiv.i
nnerHTML = data hidenDiv.dispatchEvent(customEvent); }</pre> <pre jstcache="0">c
ontentscript.js ===================== var port = chrome.extension.connect(); doc
ument.getElementById('myCustomEventDiv').addEventListener('myCustomEvent', funct
ion() { var eventData = document.getElementById('myCustomEventDiv').innerHTML; p
ort.postMessage({message: "myCustomEvent", values: eventData}); });</pre> <p jst
cache="0">In the above example, example.html (which is not a part of the extensi
on) 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 dispatching the custom event.
The content script listens for the name of the custom event on the known elemen
t and handles the event by inspecting the data of the element, and turning aroun
d to post the message to the extension process. In this way the page establishes
a line of communication to the extension. The reverse is possible through simil
ar means.</p> </div> <!-- API PAGE --> <div class="apiPage" jsselect="apiDefinit
ion" jstcache="3" style="display: none; "> <!-- METHODS --> <div class="apiGroup
" id="methods" jstcache="0"> <a name="#methods" jstcache="0"></a> <h2 jstcache="
0">Methods</h2> <!-- iterates over all functions --> <div class="apiItem" jssele
ct="functions" jstcache="4"> <a jsvalues=".name:'method-' + name" jstcache="6"><
/a> <!-- method-anchor --> <h3 jscontent="name" jstcache="7">method name</h3> <d
iv class="summary" jstcache="0"><span jsdisplay="returns" jscontent="returns.typ
eName" jstcache="9">void</span> <!-- Note: intentionally longer 80 columns --> <
span jscontent="fullName" jstcache="10">chrome.module.methodName</span>(<span js
select="parameters" jsvalues="class:optional ? 'optional' : ''" jstcache="11"><s
pan jsdisplay="$index" jstcache="19">, </span><span jscontent="typeName" jstcach
e="20"></span> <var jstcache="0"><span jscontent="name" jstcache="7"></span></va
r></span>)</div> <div class="description" jstcache="0"> <p class="todo" jsdispla
y="!description" jstcache="12">Undocumented.</p> <p jsdisplay="description" jsva
lues=".innerHTML:description" jstcache="13"> A description from the json schema
def of the function goes here. </p> <!-- PARAMETERS --> <h4 jstcache="0">Paramet
ers</h4> <dl jstcache="0"> <div jsselect="parameters" jstcache="21"> <dt jstcach
e="0"> <!-- Note: intentionally longer 80 columns --> <var jscontent="name" jstc
ache="7">paramName</var><em jstcache="0"> (<span class="optional" jsdisplay="opt
ional" jstcache="28">optional </span><span jscontent="typeName" jstcache="20">pa
ramType</span>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstca
che="23"> Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".inner
HTML:$this.description" jstcache="24"> Description of this parameter from the js
on schema. </dd> <!-- OBJECT PROPERTIES --> <dd jsdisplay="_propertyList" jstcac
he="25"> <dl jstcache="0"> <div jsselect="_propertyList" jstcache="29"> <dt jstc
ache="0"> <!-- Note: intentionally longer 80 columns --> <var jscontent="name" j
stcache="7">paramName</var><em jstcache="0"> (<span class="optional" jsdisplay="
optional" jstcache="28">optional </span><span jscontent="typeName" jstcache="20"
>paramType</span>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" js
tcache="23"> Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".in
nerHTML:$this.description" jstcache="24"> Description of this parameter from the
json schema. </dd> </div> </dl> </dd> </div> </dl> <!-- RETURNS --> <h4 jsdispl
ay="returns" jstcache="14">Returns</h4> <dl jstcache="0"> <div jsselect="returns
" jstcache="22"> <dt jstcache="0"> <!-- Note: intentionally longer 80 columns --
> <var jscontent="name" jstcache="7">paramName</var> <em jstcache="0">(<span jsc
ontent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo" js
display="!$this.description" jstcache="23"> Undocumented. </dd> <dd jsdisplay="$
this.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Descrip
tion of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <d
d jsdisplay="_propertyList" jstcache="25"> <dl jstcache="0"> <div jsselect="_pro
pertyList" jstcache="29"> <dt jstcache="0"> <!-- Note: intentionally longer 80 c
olumns --> <var jscontent="name" jstcache="7">paramName</var><em jstcache="0"> (
<span class="optional" jsdisplay="optional" jstcache="28">optional </span><span
jscontent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo"
jsdisplay="!$this.description" jstcache="23"> Undocumented. </dd> <dd jsdisplay
="$this.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Desc
ription of this parameter from the json schema. </dd> </div> </dl> </dd> </div>
</dl> <!-- CALLBACK --> <div jsdisplay="callbackParameters" jstcache="15"> <h4
jstcache="0">Callback function</h4> <p jstcache="0"> If you specify the <em jstc
ache="0">callback</em> parameter, it should specify a function that looks like t
his: </p> <!-- Note: intentionally longer 80 columns --> <pre jstcache="0">funct
ion(<span jscontent="callbackSignature" jstcache="26">Type param1, Type param2</
span>) <span class="subdued" jstcache="0">{...}</span>);</pre> <dl jstcache="0">
<div jsselect="callbackParameters" jstcache="27"> <dt jstcache="0"> <!-- Note:
intentionally longer 80 columns --> <var jscontent="name" jstcache="7">paramName
</var><em jstcache="0"> (<span jscontent="typeName" jstcache="20">paramType</spa
n>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="23"> Un
documented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.d
escription" jstcache="24"> Description of this parameter from the json schema. <
/dd> <!-- OBJECT PROPERTIES --> <dd jsdisplay="_propertyList" jstcache="25"> <dl
jstcache="0"> <div jsselect="_propertyList" jstcache="29"> <dt jstcache="0"> <!
-- Note: intentionally longer 80 columns --> <var jscontent="name" jstcache="7">
paramName</var><em jstcache="0"> (<span class="optional" jsdisplay="optional" js
tcache="28">optional </span><span jscontent="typeName" jstcache="20">paramType</
span>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="23">
Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$thi
s.description" jstcache="24"> Description of this parameter from the json schema
. </dd> </div> </dl> </dd> </div> </dl> </div> </div> <!-- /description --> </di
v> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- EVENTS --> <div class="apiGr
oup" id="events" jstcache="0"> <a name="#events" jstcache="0"></a> <h2 id="event
s" jstcache="0">Events</h2> <!-- iterates over all events --> <div jsselect="eve
nts" class="apiItem" jstcache="5"> <a jsvalues=".name:'event-' + name" jstcache=
"8"></a> <h3 jscontent="name" jstcache="7">event name</h3> <div class="summary"
jstcache="0"> <!-- Note: intentionally longer 80 columns --> <span class="subdue
d" jstcache="0">chrome.bookmarks.</span><span jscontent="name" jstcache="7">onEv
ent</span><span class="subdued" jstcache="0">.addListener</span>(function(<span
jscontent="callSignature" jstcache="16">Type param1, Type param2</span>) <span c
lass="subdued" jstcache="0">{...}</span>); </div> <div class="description" jstca
che="0"> <p class="todo" jsdisplay="!description" jstcache="12">Undocumented.</p
> <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="13"> A
description from the json schema def of the event goes here. </p> <!-- PARAMETER
S --> <h4 jstcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="paramete
rs" jstcache="21"> <dt jstcache="0"> <!-- Note: intentionally longer 80 columns
--> <var jscontent="name" jstcache="7">paramName</var><em jstcache="0"> (<span j
scontent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo"
jsdisplay="!$this.description" jstcache="23">Undocumented.</dd> <dd jsdisplay="$
this.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Descrip
tion of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <d
d jsdisplay="_propertyList" jstcache="25"> <dl jstcache="0"> <div jsselect="_pro
pertyList" jstcache="29"> <dt jstcache="0"> <!-- Note: intentionally longer 80 c
olumns --> <var jscontent="name" jstcache="7">paramName</var><em jstcache="0"> (
<span class="optional" jsdisplay="optional" jstcache="28">optional </span><span
jscontent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo"
jsdisplay="!$this.description" jstcache="23"> Undocumented. </dd> <dd jsdisplay
="$this.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Desc
ription of this parameter from the json schema. </dd> </div> </dl> </dd> </div>
</dl> </div> <!-- /decription --> </div> <!-- /apiItem --> </div> <!-- /apiGroup
--> </div> <!-- /apiPage --> </div> <!-- /mainColumn --> </div> <!-- /pageConte
nt --> <div id="pageFooter" --="" jstcache="0"> Copyright 2009 <br jstcache="0">
TBD: copyright/license should be automatically included here </div> <!-- /pageF
ooter --> </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="pageTitle" jstcache="1">Content_scripts</title> <link href
="css/ApiRefStyles.css" rel="stylesheet" type="text/css" jstcache="0"> <script t
ype="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.j
s" jstcache="0"> </script> <script type="text/javascript" src="js/api_page_gener
ator.js" jstcache="0"></script> <script type="text/javascript" src="js/bootstrap
.js" jstcache="0"></script> </head><!-- <body> content is completely generated.
Do not edit, as it will be and rewritten. --><body jstcache="0"> <div id="contai
ner" jstcache="0"> <a name="top" jstcache="0"> </a> <!-- API HEADER --> <div id=
"pageHeader" jstcache="0"> <!-- BREADCRUMB --> <!-- TODO: Fix these hrefs --> <d
iv id="breadcrumbs" jstcache="0"> <a href="index.html" jstcache="0">Google Chrom
e Extensions</a> > <a href="reference_index.html" jstcache="0">Reference</a>
> <a href="api_index.html" jstcache="0">chrome.* APIs</a> > <span jsconten
t="h1Header" jstcache="2">Content_scripts</span> </div> <div id="searchbox" jstc
ache="0"> <form action="http://www.google.com/cse" id="cse-search-box" jstcache=
"0"> <div jstcache="0"> <input type="hidden" name="cx" value="002967670403910741
006:61_cvzfqtno" jstcache="0"> <input type="hidden" name="ie" value="UTF-8" jstc
ache="0"> <input type="text" name="q" size="31" jstcache="0"> <input type="submi
t" name="sa" value="Search" jstcache="0"> </div> </form> <script type="text/java
script" src="http://www.google.com/jsapi" jstcache="0"></script> <script type="t
ext/javascript" jstcache="0">google.load("elements", "1", {packages: "transliter
ation"});</script> <script type="text/javascript" src="http://www.google.com/coo
p/cse/t13n?form=cse-search-box&t13n_langs=en" jstcache="0"></script> <script
type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-searc
h-box&lang=en" jstcache="0"></script> </div> <div id="pageTitle" jstcache="0
"> <h1 jscontent="h1Header" jstcache="2">Content_scripts</h1> </div> </div> <!--
/pageHeader --> <div id="pageContent" jstcache="0"> <!-- SIDENAV --> <div id="l
eftNav" jstcache="0"> <ul jstcache="0"> <li jstcache="0"> <a href="index.html" j
stcache="0">Home</a></li> <li jstcache="0"> <a href="getstarted.html" jstcache="
0">Get Started</a></li> <li jstcache="0"> <a href="overview.html" jstcache="0">O
verview</a></li> <li jstcache="0">Reference <ul jstcache="0"> <li jstcache="0"><
a href="manifest.html" jstcache="0">Manifest</a> </li><li jstcache="0"><a href="
toolstrip.html" jstcache="0">Toolstrips</a> </li><li jstcache="0"><a href="pageA
ctions.html" jstcache="0">Page actions</a> </li><li jstcache="0"><a href="backgr
ound_pages.html" jstcache="0">Background pages</a> </li><li jstcache="0"><a href
="content_scripts.html" jstcache="0">Content scripts</a> </li><li jstcache="0"><
a href="extension.html" jstcache="0">Extension</a> </li><li jstcache="0"><a href
="tabs.html" jstcache="0">Tabs</a> </li><li jstcache="0"><a href="windows.html"
jstcache="0">Windows</a> </li><li jstcache="0"><a href="self.html" jstcache="0">
Self</a> </li><li jstcache="0"><a href="npapi.html" jstcache="0">NPAPI Plugins</
a> </li><li jstcache="0"><a href="packaging.html" jstcache="0">Packaging</a> </l
i><li jstcache="0"><a href="autoupdate.html" jstcache="0">Autoupdate</a> </li></
ul> </li><li jstcache="0">Samples <ul jstcache="0"> <li jstcache="0">[sample 1]
</li><li jstcache="0">[sample 2] </li></ul> </li></ul> </div> <div id="mainColum
n" jstcache="0"> <!-- TABLE OF CONTENTS --> <div id="toc" jsselect="apiDefinitio
n" jstcache="3" style="display: none; "> <p jstcache="0">Contents</p> <ol jstcac
he="0"> <li jstcache="0"> <a href="#overview" jstcache="0">Description</a> <ol j
stcache="0"> <li jstcache="0"><a href="#overview-properties" jstcache="0">Proper
ties</a></li> <li jstcache="0"><a href="#overview-examples" jstcache="0">Example
s</a></li> </ol> </li> <li jstcache="0"> <a href="#methods" jstcache="0">Methods
</a> <ol jstcache="0"> <li jsselect="functions" jstcache="4"> <a jscontent="name
" jsvalues=".href:'#method-' + name" href="#method-anchor" jstcache="17">methodN
ame</a> </li> </ol> </li> <li jstcache="0"> <a href="#events" jstcache="0">Event
s</a> <ol jstcache="0"> <li jsselect="events" jstcache="5"> <a jscontent="name"
jsvalues=".href:'#event-' + name" href="#event-anchor" jstcache="18">eventName</
a> </li> </ol> </li> <!-- TODO: What do we do about structs/types? --> <li jstca
che="0"> <a href="#structs" jstcache="0">TODO: Structs</a> <ol jstcache="0"> <li
jstcache="0"><a href="#struct-BookmarkTreeNode" jstcache="0"></a></li> </ol> </
li> </ol> [PENDING: links to all h2s and h3s should go here -- would it be possi
ble to link to overview h3s, as well? if so, how should we create their anchor/i
d values?] </div> <!-- /TABLE OF CONTENTS --> <!-- STATIC CONTENT PLACEHOLDER --
> <div id="static" jstcache="0"><p jstcache="0">Content Scripts are JavaScript f
iles 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 th
em. </p><p jstcache="0">Some examples of things that content scripts can do incl
ude: </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 mak
e text more legible </li><li jstcache="0">Find and process <a href="http://micro
formats.org/" jstcache="0">microformat</a> data in the DOM </li></ul> <h3 id="re
gistration" jstcache="0">Registration</h3> <p jstcache="0">Content scripts are r
egistered in an extension's <a href="manifest.html" jstcache="0">manifest.json</
a> file, like so: </p><pre jstcache="0">{ "name": "My First Extension", "version
": "1.0", "description": "The first extension that I made.", <span style="backgr
ound:yellow; font-weight:bold;" jstcache="0"> "content_scripts": [ { "matches":
["http://www.google.com/*"], "css": ["mystyles.css"], "js": ["jquery.js", "myscr
ipt.js"] } ]</span> }</pre> <p jstcache="0">An extension can contain any number
of content scripts, and a content script can consist of any number of JavaScript
or CSS files. The value of the <code jstcache="0">matches</code> property contr
ols when the content script will run. </p><p jstcache="0">Each content script re
gistered in the manifest can specify the following properties:</p> <table jstcac
he="0"> <tbody jstcache="0"><tr jstcache="0"> <th jstcache="0">Name</th> <th jst
cache="0">Type</th> <th jstcache="0">Description</th> </tr> <tr jstcache="0"> <t
d jstcache="0">matches</td> <td jstcache="0">array of strings</td> <td jstcache=
"0">Required. Controls the pages this content script will be injected into. See
<a href="#match_patterns" jstcache="0">Match Patterns</a> for more details on th
e syntax of these strins.</td> </tr> <tr jstcache="0"> <td jstcache="0">js</td>
<td 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. The
se 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 jstcac
he="0">Optional. The list of CSS files to be injected into matching pages. These
are injected in the order they appear in this array, before any DOM is construc
ted or displayed for the page.</td> </tr> <tr jstcache="0"> <td jstcache="0">run
_at</td> <td jstcache="0">string</td> <td jstcache="0">Optional. Controls when t
he 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 t
o <code jstcache="0">"document_end"</code>. In the case of <code jstcache="0">"d
ocument_start"</code>, the files are injected after any files from <code jstcach
e="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 i
njected after the DOM is complete, but before subresources like images and frame
s have necessarily loaded.</td> </tr> </tbody></table> <h3 id="match_patterns" j
stcache="0">Match Patterns</h3> <p jstcache="0">TODO</p> <h3 id="execution_envir
onment" jstcache="0">Execution Environment</h3> <p jstcache="0">Content scripts
execute in a special environment called an <em jstcache="0">isolated world</em>.
They have access to the DOM of the page they are 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 executing on the page it is running on
. The same is true in reverse: JavaScript running on the page cannot call any fu
nctions or access any variables defined by content scripts. </p><p jstcache="0">
For example, consider this simple page: </p><pre jstcache="0">hello.html =======
==== <html> <button id="button">click me</button> <script&g
t; var greeting = "hello!"; function sayGreeting() { alert(greeting); } document
.getElementById("button").onclick = sayGreeting; </script> </html></
pre> <p jstcache="0">Now, suppose this content script was injected into hello.ht
ml: </p><pre jstcache="0">contentscript.js ================== console.log(greeti
ng); // undefined console.log(sayGreeting); // undefined console.log(document.ge
tElementById("button").onclick); // still undefined document.getElementById("but
ton").onclick = function() { alert("hola!"); }</pre> <p jstcache="0">Now, if the
button is pressed, you will see both greetings. </p><p jstcache="0">Isolated wo
rlds allow each content script to make changes to its JavaScript environment wit
hout worrying about conflicting with the page or with other contnet scripts. For
example, a content script could include JQuery v1 and the page could include JQ
uery v2, and they wouldn't conflict with each other. </p><p jstcache="0">Another
important benefit of isolated worlds is that they completely separate the JavaS
cript on the page from the JavaScript in extensions. This allows us to offer ext
ra functionality to content scripts that should not be accessible from web pages
without worrying about web pages accessing it. </p><h3 id="messaging" jstcache=
"0">Messaging</h3> <p jstcache="0">Content scripts can communicate with their pa
rent extension using message passing. The content script opens a channel to the
extension using the <a href="extension.html#connect" jstcache="0">chrome.extensi
on.connect()</a> method and then sends messages back and forth to it. The messag
es can contain any valid JSON object (null, boolean, number, string, array, or o
bject). </p><p jstcache="0">The parent extension can also open a channel to a co
ntent script in a given tab by calling <a href="tabs.html#connect" jstcache="0">
chrome.tabs.connect(tabId)</a>. </p><p jstcache="0">When a channel is opened fro
m a content script to an extension, the <a href="extension.html#onConnect" jstca
che="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 script. </p><p jstcache="0">[TODO: Complete this] </p><h3 id="ho
stPageCommuncation" jstcache="0">Communication with the embedding page</h3> <p j
stcache="0">Although the execution environments of content scripts and the pages
that host them are isolated from each other, they share access to the page's DO
M. If the page wishes to communicate with the content script (or with the extens
ion via the content script), it must do so through the shared DOM.</p> <p jstcac
he="0">An example can be accomplished using custom DOM events and storing data i
n 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('myCustomEventDiv'); hidenDiv.innerHT
ML = data hidenDiv.dispatchEvent(customEvent); }</pre> <pre jstcache="0">content
script.js ===================== var port = chrome.extension.connect(); document.
getElementById('myCustomEventDiv').addEventListener('myCustomEvent', function()
{ var eventData = document.getElementById('myCustomEventDiv').innerHTML; port.po
stMessage({message: "myCustomEvent", values: eventData}); });</pre> <p jstcache=
"0">In the above example, example.html (which is not a part of the extension) cr
eates 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 dispatching the custom event. The c
ontent 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 p
ost the message to the extension process. In this way the page establishes a lin
e of communication to the extension. The reverse is possible through similar mea
ns.</p> </div> <!-- API PAGE --> <div class="apiPage" jsselect="apiDefinition" j
stcache="3" style="display: none; "> <!-- METHODS --> <div class="apiGroup" id="
methods" jstcache="0"> <a name="#methods" jstcache="0"></a> <h2 jstcache="0">Met
hods</h2> <!-- iterates over all functions --> <div class="apiItem" jsselect="fu
nctions" jstcache="4"> <a jsvalues=".name:'method-' + name" jstcache="6"></a> <!
-- method-anchor --> <h3 jscontent="name" jstcache="7">method name</h3> <div cla
ss="summary" jstcache="0"><span jsdisplay="returns" jscontent="returns.typeName"
jstcache="9">void</span> <!-- Note: intentionally longer 80 columns --> <span j
scontent="fullName" jstcache="10">chrome.module.methodName</span>(<span jsselect
="parameters" jsvalues="class:optional ? 'optional' : ''" jstcache="11"><span js
display="$index" jstcache="19">, </span><span jscontent="typeName" jstcache="20"
></span> <var jstcache="0"><span jscontent="name" jstcache="7"></span></var></sp
an>)</div> <div class="description" jstcache="0"> <p class="todo" jsdisplay="!de
scription" jstcache="12">Undocumented.</p> <p jsdisplay="description" jsvalues="
.innerHTML:description" jstcache="13"> A description from the json schema def of
the function goes here. </p> <!-- PARAMETERS --> <h4 jstcache="0">Parameters</h
4> <dl jstcache="0"> <div jsselect="parameters" jstcache="21"> <dt jstcache="0">
<!-- Note: intentionally longer 80 columns --> <var jscontent="name" jstcache="
7">paramName</var><em jstcache="0"> (<span class="optional" jsdisplay="optional"
jstcache="28">optional </span><span jscontent="typeName" jstcache="20">paramTyp
e</span>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="2
3"> Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$
this.description" jstcache="24"> Description of this parameter from the json sch
ema. </dd> <!-- OBJECT PROPERTIES --> <dd jsdisplay="_propertyList" jstcache="25
"> <dl jstcache="0"> <div jsselect="_propertyList" jstcache="29"> <dt jstcache="
0"> <!-- Note: intentionally longer 80 columns --> <var jscontent="name" jstcach
e="7">paramName</var><em jstcache="0"> (<span class="optional" jsdisplay="option
al" jstcache="28">optional </span><span jscontent="typeName" jstcache="20">param
Type</span>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache
="23"> Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTM
L:$this.description" jstcache="24"> Description of this parameter from the json
schema. </dd> </div> </dl> </dd> </div> </dl> <!-- RETURNS --> <h4 jsdisplay="re
turns" jstcache="14">Returns</h4> <dl jstcache="0"> <div jsselect="returns" jstc
ache="22"> <dt jstcache="0"> <!-- Note: intentionally longer 80 columns --> <var
jscontent="name" jstcache="7">paramName</var> <em jstcache="0">(<span jscontent
="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo" jsdispla
y="!$this.description" jstcache="23"> Undocumented. </dd> <dd jsdisplay="$this.d
escription" jsvalues=".innerHTML:$this.description" jstcache="24"> Description o
f this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd jsdi
splay="_propertyList" jstcache="25"> <dl jstcache="0"> <div jsselect="_propertyL
ist" jstcache="29"> <dt jstcache="0"> <!-- Note: intentionally longer 80 columns
--> <var jscontent="name" jstcache="7">paramName</var><em jstcache="0"> (<span
class="optional" jsdisplay="optional" jstcache="28">optional </span><span jscont
ent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo" jsdis
play="!$this.description" jstcache="23"> Undocumented. </dd> <dd jsdisplay="$thi
s.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Descriptio
n of this parameter from the json schema. </dd> </div> </dl> </dd> </div> </dl>
<!-- CALLBACK --> <div jsdisplay="callbackParameters" jstcache="15"> <h4
jstcache="0">Callback function</h4> <p jstcache="0"> If you specify the <em jstc
ache="0">callback</em> parameter, it should specify a function that looks like t
his: </p> <!-- Note: intentionally longer 80 columns --> <pre jstcache="0">funct
ion(<span jscontent="callbackSignature" jstcache="26">Type param1, Type param2</
span>) <span class="subdued" jstcache="0">{...}</span>);</pre> <dl jstcache="0">
<div jsselect="callbackParameters" jstcache="27"> <dt jstcache="0"> <!-- Note:
intentionally longer 80 columns --> <var jscontent="name" jstcache="7">paramName
</var><em jstcache="0"> (<span jscontent="typeName" jstcache="20">paramType</spa
n>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="23"> Un
documented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.d
escription" jstcache="24"> Description of this parameter from the json schema. <
/dd> <!-- OBJECT PROPERTIES --> <dd jsdisplay="_propertyList" jstcache="25"> <dl
jstcache="0"> <div jsselect="_propertyList" jstcache="29"> <dt jstcache="0"> <!
-- Note: intentionally longer 80 columns --> <var jscontent="name" jstcache="7">
paramName</var><em jstcache="0"> (<span class="optional" jsdisplay="optional" js
tcache="28">optional </span><span jscontent="typeName" jstcache="20">paramType</
span>)</em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="23">
Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$thi
s.description" jstcache="24"> Description of this parameter from the json schema
. </dd> </div> </dl> </dd> </div> </dl> </div> </div> <!-- /description --> </di
v> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- EVENTS --> <div class="apiGr
oup" id="events" jstcache="0"> <a name="#events" jstcache="0"></a> <h2 id="event
s" jstcache="0">Events</h2> <!-- iterates over all events --> <div jsselect="eve
nts" class="apiItem" jstcache="5"> <a jsvalues=".name:'event-' + name" jstcache=
"8"></a> <h3 jscontent="name" jstcache="7">event name</h3> <div class="summary"
jstcache="0"> <!-- Note: intentionally longer 80 columns --> <span class="subdue
d" jstcache="0">chrome.bookmarks.</span><span jscontent="name" jstcache="7">onEv
ent</span><span class="subdued" jstcache="0">.addListener</span>(function(<span
jscontent="callSignature" jstcache="16">Type param1, Type param2</span>) <span c
lass="subdued" jstcache="0">{...}</span>); </div> <div class="description" jstca
che="0"> <p class="todo" jsdisplay="!description" jstcache="12">Undocumented.</p
> <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="13"> A
description from the json schema def of the event goes here. </p> <!-- PARAMETER
S --> <h4 jstcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="paramete
rs" jstcache="21"> <dt jstcache="0"> <!-- Note: intentionally longer 80 columns
--> <var jscontent="name" jstcache="7">paramName</var><em jstcache="0"> (<span j
scontent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo"
jsdisplay="!$this.description" jstcache="23">Undocumented.</dd> <dd jsdisplay="$
this.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Descrip
tion of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <d
d jsdisplay="_propertyList" jstcache="25"> <dl jstcache="0"> <div jsselect="_pro
pertyList" jstcache="29"> <dt jstcache="0"> <!-- Note: intentionally longer 80 c
olumns --> <var jscontent="name" jstcache="7">paramName</var><em jstcache="0"> (
<span class="optional" jsdisplay="optional" jstcache="28">optional </span><span
jscontent="typeName" jstcache="20">paramType</span>)</em> </dt> <dd class="todo"
jsdisplay="!$this.description" jstcache="23"> Undocumented. </dd> <dd jsdisplay
="$this.description" jsvalues=".innerHTML:$this.description" jstcache="24"> Desc
ription of this parameter from the json schema. </dd> </div> </dl> </dd> </div>
</dl> </div> <!-- /decription --> </div> <!-- /apiItem --> </div> <!-- /apiGroup
--> </div> <!-- /apiPage --> </div> <!-- /mainColumn --> </div> <!-- /pageConte
nt --> <div id="pageFooter" --="" jstcache="0"> Copyright 2009 <br jstcache="0">
TBD: copyright/license should be automatically included here </div> <!-- /pageF
ooter --> </div> <!-- /container --> </body></html> |
Chromium Code Reviews
Issue 165323:
Add chrome.extension to extension_api.json and docs (Closed)
