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 mechanism. 2) The <body> tag *must* retain id="body" 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a browser, it will be re-generated from the template, json schema and authored overview content. 4) The <body>.innerHTML is also generated by an offline step so that this page may easily be indexed by search engines. TODO(rafaelw): Abstract this into a "pageshell" that becomes the single version of page template shell and the "instance" pages (bookmarks.html, etc...) can be generated with a build step. --><!-- <html> must retain id="template --><html xmlns="http://www.w3.org/1999/xhtml" jstcache="0"><!-- <head> data is significant and loads the needed libraries and styles --><head jstcache="0"> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" jstcache="0"> <title jscontent="pageTitle" jstcache="1">[object HTMLDivElement]</title> <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css" jstcache="0"> <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js" jstcache="0"> </script> <script type="text/javascript" src="js/api_page_generator.js" jstcache="0"></script> <script type="text/javascript" src="js/bootstrap.js" jstcache="0"></script> </head><!-- <body> content is completely generated. Do not edit, as it will be and rewritten. --><body jstcache="0"> <div id="container" jstcache="0"> <a name="top" jstcache="0"> </a> <!-- API HEADER --> <div id="pageHeader" jstcache="0"> <div id="searchbox" jstcache="0"> <form action="http://www.google.com/cse" id="cse-search-box" jstcache="0"> <div jstcache="0"> <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno" jstcache="0"> <input type="hidden" name="ie" value="UTF-8" jstcache="0"> <input type="text" name="q" size="31" jstcache="0"> <input type="submit" name="sa" value="Search" jstcache="0"> </div> </form> <script type="text/javascript" src="http://www.google.com/jsapi" jstcache="0"></script> <script type="text/javascript" jstcache="0">google.load("elements", "1", {packages: "transliteration"});</script> <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse-search-box&t13n_langs=en" jstcache="0"></script> <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse-search-box&lang=en" jstcache="0"></script> </div> <div id="pageTitle" jstcache="0"> <h1 jscontent="getPageTitle()" jstcache="2">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">Get Started</a></li> <li jstcache="0"> <a href="overview.html" jstcache="0">Overview</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="pageActions.html" jstcache="0">Page Actions</a></li> <li jstcache="0"><a href="background_pages.html" jstcache="0">Background Pages</a></li> <li jstcache="0" class="leftNavSelected">Content Scripts</li> <li jstcache="0"><a href="tabs.html" jstcache="0">Tabs</a></li> <li jstcache="0"><a href="windows.html" jstcache="0">Windows</a></li> <li jstcache="0"><a href="bookmarks.html" jstcache="0">Bookmarks</a></li> <li jstcache="0"><a href="extension.html" jstcache="0">Extension</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></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">[sample 1]</li> <li jstcache="0">[sample 2]</li> </ul> </li> </ul> </div> <div id="mainColumn" jstcache="0"> <!-- TABLE OF CONTENTS --> <div id="toc" jsdisplay="showPageTOC()" jstcache="3"> <p jstcache="0">Contents</p> <ol jstcache="0"> <li jsselect="getStaticTOC()" jstcache="8" jsinstance="0"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12" href="#H2-0">Registration</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache="19" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12">h3Name</a> </li> </ol> </li><li jsselect="getStaticTOC()" jstcache="8" jsinstance="1"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12" href="#H2-1">Match patterns</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache="19" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12">h3Name</a> </li> </ol> </li><li jsselect="getStaticTOC()" jstcache="8" jsinstance="2"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12" href="#H2-2">Execution environment</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache="19" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12">h3Name</a> </li> </ol> </li><li jsselect="getStaticTOC()" jstcache="8" jsinstance="3"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12" href="#H2-3">Messaging</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache="19" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12">h3Name</a> </li> </ol> </li><li jsselect="getStaticTOC()" jstcache="8" jsinstance="*4"> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12" href="#H2-4">Communication with the embedding page</a> <ol jstcache="0"> <li jsselect="$this.children" jstcache="19" jsinstance="*0" style="display: none; "> <a jscontent="name" jsvalues=".href:'#' + href" jstcache="12">h3Name</a> </li> </ol> </li> <div jsselect="apiDefinition" jstcache="4" style="display: none; "> <li jsdisplay="functions && functions.length > 0" jstcache="5"> <a href="#methods" jstcache="0">Methods</a> <ol jstcache="0"> <li jsselect="functions" jstcache="9"> <a jscontent="name" jsvalues=".href:'#method-' + name" href="#method-anchor" jstcache="33">methodName</a> </li> </ol> </li> <li jsdisplay="events && events.length > 0" jstcache="6"> <a href="#events" jstcache="0">Events</a> <ol jstcache="0"> <li jsselect="events" jstcache="10"> <a jscontent="name" jsvalues=".href:'#event-' + name" href="#event-anchor" jstcache="34">eventName</a> </li> </ol> </li> <li jsdisplay="types && types.length > 0" jstcache="7"> <a href="#types" jstcache="0">Types</a> <ol jstcache="0"> <li jsselect="types" jstcache="11"> <a jscontent="id" jsvalues=".href:'#type-' + id" href="#id-anchor" jstcache="35">id</a> </li> </ol> </li> </div> </ol> </div> <!-- /TABLE OF CONTENTS --> <!-- STATIC CONTENT PLACEHOLDER --> <div id="static" jstcache="0"><div id="pageData-title" class="pageData" jstcache="0">Content Scripts</div> <div id="pageData-showTOC" class="pageData" jstcache="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/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 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 legible </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">Registration</h2> <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", "version": "1.0", "description": "The first extension that I made.", <span style="background:yellow; font-weight:bold;" jstcache="0"> "content_scripts": [ { "matches": ["http://www.google.com/*"], "css": ["mystyles.css"], "js": ["jquery.js", "myscript.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 controls when the content script will run. </p><p jstcache="0">Each content script 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 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 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 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 are injected in the order they appear in this array, before any DOM is constructed 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 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 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 injected 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="match_patterns" jstcache="0">Match patterns</h2> <p class="comment" jstcache="0">TODO</p> <a name="H2-2" jstcache="0"></a><h2 id="execution_environment" jstcache="0">Execution environment</h2> <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 functions 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> 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.html: </p><pre jstcache="0">contentscript.js ================== console.log(greeting); // undefined console.log(sayGreeting); // undefined 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 its JavaScript environment without 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 JQuery 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 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-3" 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> 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 to a content 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 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 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 class="comment" jstcache="0">[TODO: Complete this]</p> <a name="H2-4" jstcache="0"></a><h2 id="hostPageCommuncation" jstcache="0">Communication with the embedding page</h2> <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 page'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/example.html ================================ var customEvent = document.createEvent('Event'); customEvent.initEvent('myCustomEvent', true, true); function fireCustomEvent(data) { hidenDiv = document.getElementById('myCustomEventDiv'); hidenDiv.innerHTML = data hidenDiv.dispatchEvent(customEvent); }</pre> <pre jstcache="0">contentscript.js ===================== var port = chrome.extension.connect(); document.getElementById('myCustomEventDiv').addEventListener('myCustomEvent', function() { var eventData = document.getElementById('myCustomEventDiv').innerHTML; port.postMessage({message: "myCustomEvent", values: eventData}); });</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 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 establishes a line of communication to the extension. The reverse is possible through similar means.</p> </div> <!-- API PAGE --> <div class="apiPage" jsselect="apiDefinition" jstcache="4" style="display: none; "> <!-- METHODS --> <div jsdisplay="functions && functions.length > 0" class="apiGroup" id="methods" jstcache="5"> <a name="#methods" jstcache="0"></a> <h2 jstcache="0">Methods</h2> <!-- iterates over all functions --> <div class="apiItem" jsselect="functions" jstcache="9"> <a jsvalues=".name:'method-' + name" jstcache="13"></a> <!-- method-anchor --> <h3 jscontent="name" jstcache="14">method name</h3> <div class="summary" jstcache="0"><span jsdisplay="returns" jscontent="getTypeName(returns)" jstcache="20">void</span> <!-- Note: intentionally longer 80 columns --> <span jscontent="getFullyQualifiedFunctionName($this)" jstcache="21">chrome.module.methodName</span>(<span jsselect="parameters" jsvalues="class:optional ? 'optional' : ''" jstcache="22"><span jsdisplay="$index" jstcache="28">, </span><span jscontent="getTypeName($this)" jstcache="29"></span> <var jstcache="0"><span jscontent="name" jstcache="14"></span></var></span>)</div> <div class="description" jstcache="0"> <p class="todo" jsdisplay="!description" jstcache="23">Undocumented.</p> <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="24"> A description from the json schema def of the function goes here. </p> <!-- PARAMETERS --> <h4 jstcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="parameters" jstcache="30"> <!-- VALUE: This is a subtemplate that is used elsewhere via jsTemplate *transclude* --> <div id="valueTemplate" jstcache="0"> <dt jstcache="0"> <var jsdisplay="$this.name" jscontent="$this.name" jstcache="39">paramName</var> <em jstcache="0"> <!-- TYPE --> <div style="display:inline" jstcache="0"> ( <span class="optional" jsdisplay="optional" jstcache="41">optional</span> <span id="typeTemplate" jstcache="0"> <span jsdisplay="getTypeRef($this)" jstcache="42"> <a jsvalues=".href: getTypeRefPage($this) + '#type-' + getTypeRef($this)" jscontent="getTypeRef($this)" jstcache="44"> Type</a> </span> <span jsdisplay="!getTypeRef($this)" jstcache="43"> <span jsdisplay="isArray($this)" jstcache="45"> array of <span jsselect="items" jstcache="47"><span transclude="typeTemplate" jstcache="48"></span></span> </span> <span jsdisplay="!isArray($this)" jscontent="getTypeName($this)" jstcache="46">paramType</span> </span> </span> ) </div> </em> </dt> <dd class="todo" jsdisplay="!$this.description" jstcache="36"> Undocumented. </dd> <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description" jstcache="37"> Description of this parameter from the json schema. </dd> <!-- OBJECT PROPERTIES --> <dd jsdisplay="shouldExpandObject($this)" jstcache="38"> <dl jstcache="0"> <div jsselect="getPropertyListFromObject($this)" jstcache="40"> <div transclude="valueTemplate" jstcache="18"> </div> </div> </dl> </dd> </div> <!-- /VALUE --> </div> </dl> <!-- RETURNS --> <h4 jsdisplay="returns" jstcache="25">Returns</h4> <dl jstcache="0"> <div jsselect="returns" jstcache="31"> <div transclude="valueTemplate" jstcache="18"> </div> </div> </dl> <!-- CALLBACK --> <div jsdisplay="hasCallback(parameters)" jstcache="26"> <div jsselect="getCallbackParameters(parameters)" jstcache="32"> <h4 jstcache="0">Callback function</h4> <p jstcache="0"> If you specify the <em jstcache="0">callback</em> parameter, it should specify a function that looks like this: </p> <!-- Note: intentionally longer 80 columns --> <pre jstcache="0">function(<span jscontent="getSignatureString(parameters)" jstcache="27">Type param1, Type param2</span>) <span class="subdued" jstcache="0">{...}</span>);</pre> <dl jstcache="0"> <div jsselect="parameters" jstcache="30"> <div transclude="valueTemplate" jstcache="18"> </div> </div> </dl> </div> </div> </div> <!-- /description --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- EVENTS --> <div jsdisplay="events && events.length > 0" class="apiGroup" jstcache="6"> <a name="#events" jstcache="0"></a> <h2 id="events" jstcache="0">Events</h2> <!-- iterates over all events --> <div jsselect="events" class="apiItem" jstcache="10"> <a jsvalues=".name:'event-' + name" jstcache="15"></a> <h3 jscontent="name" jstcache="14">event name</h3> <div class="summary" jstcache="0"> <!-- Note: intentionally longer 80 columns --> <span class="subdued" jstcache="0">chrome.bookmarks.</span><span jscontent="name" jstcache="14">onEvent</span><span class="subdued" jstcache="0">.addListener</span>(function(<span jscontent="getSignatureString(parameters)" jstcache="27">Type param1, Type param2</span>) <span class="subdued" jstcache="0">{...}</span>); </div> <div class="description" jstcache="0"> <p class="todo" jsdisplay="!description" jstcache="23">Undocumented.</p> <p jsdisplay="description" jsvalues=".innerHTML:description" jstcache="24"> A description from the json schema def of the event goes here. </p> <!-- PARAMETERS --> <h4 jstcache="0">Parameters</h4> <dl jstcache="0"> <div jsselect="parameters" jstcache="30"> <div transclude="valueTemplate" jstcache="18"> </div> </div> </dl> </div> <!-- /decription --> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> <!-- TYPES --> <div jsdisplay="types && types.length > 0" class="apiGroup" jstcache="7"> <a name="#types" jstcache="0"></a> <h2 id="types" jstcache="0">Types</h2> <!-- iterates over all types --> <div jsselect="types" class="apiItem" jstcache="11"> <a jsvalues=".name:'type-' + id" jstcache="16"></a> <h3 jscontent="id" jstcache="17">type name</h3> <div transclude="valueTemplate" jstcache="18"> </div> </div> <!-- /apiItem --> </div> <!-- /apiGroup --> </div> <!-- /apiPage --> </div> <!-- /mainColumn --> </div> <!-- /pageContent --> <div id="pageFooter" --="" jstcache="0"> Copyright 2009. For terms of use, see the Chromium <a href="http://src.chromium.org/viewvc/chrome/trunk/src/LICENSE" jstcache="0">license</a>. </div> <!-- /pageFooter --> </div> <!-- /container --> </body></html>
|
