1<div id="pageData-name" class="pageData">Background Pages</div> 2<div id="pageData-showTOC" class="pageData">true</div> 3 4<p> 5A common need for extensions is to have 6a single long-running script to manage some task or state. 7Background pages to the rescue. 8</p> 9 10<p> 11As the <a href="overview.html#arch">architecture overview</a> explains, 12the background page is an HTML page that runs in the extension process. 13It exists for the lifetime of your extension, 14and only one instance of it at a time is active. 15</p> 16 17<p> 18In a typical extension with a background page, 19the UI — 20for example, the browser action or page action 21and any options page — 22is implemented by dumb views. 23When the view needs some state, 24it requests the state from the background page. 25When the background page notices a state change, 26the background page tells the views to update. 27</p> 28 29<h2 id="manifest">Manifest</h2> 30 31<p> 32Register your background page in the 33<a href="manifest.html">extension manifest</a> 34like this: 35</p> 36 37<pre>{ 38 "name": "My extension", 39 ... 40 <b>"background_page": "background.html"</b>, 41 ... 42}</pre> 43 44<p> 45If you need the browser to start up early—so 46you can display notifications, for example—then 47you might also want to specify the 48<a href="manifest.html#permissions">"background" permission</a>. 49</p> 50 51 52<h2>Details</h2> 53 54<p> 55You can communicate between your various pages using direct script calls, 56similar to how frames can communicate. 57The <a href="extension.html#method-getViews"><code>chrome.extension.getViews()</code></a> method 58returns a list of window objects 59for every active page belonging to your extension, 60and the 61<a href="extension.html#method-getBackgroundPage"><code>chrome.extension.getBackgroundPage()</code></a> method 62returns the background page. 63</p> 64 65<h2 id="example">Example</h2> 66 67<p> 68The following code snippet demonstrates 69how the background page 70can interact with other pages in the extension. 71It also shows how you can use 72the background page to handle events 73such as user clicks. 74</p> 75 76<p> 77The extension in this example 78has a background page 79and multiple pages created 80(with 81<a href="tabs.html#method-create"><code>chrome.tabs.create()</code></a>) 82from a file named <code>image.html</code>. 83<!-- [PENDING: Once we have our set of samples, we should point to the example this is from and to other relevant examples. This is currently untested code derived from the screenshot sample.] --> 84</p> 85 86<pre> 87<em>//In the background page:</em> 88<html> 89 <script> 90 //React when a browser action's icon is clicked. 91 chrome.browserAction.onClicked.addListener(function(tab) { 92 var viewTabUrl = chrome.extension.getURL('image.html'); 93 var imageUrl = <em>/* an image's URL */</em>; 94 95 //Look through all the pages in this extension to find one we can use. 96 var views = chrome.extension.getViews(); 97 for (var i = 0; i < views.length; i++) { 98 var view = views[i]; 99 100 //If this view has the right URL and hasn't been used yet... 101 if (view.location.href == viewTabUrl && !view.imageAlreadySet) { 102 103 //...call one of its functions and set a property. 104 view.setImageUrl(imageUrl); 105 view.imageAlreadySet = true; 106 break; //we're done 107 } 108 } 109 }); 110 </script> 111</html> 112 113<em>//In image.html:</em> 114<html> 115 <script> 116 function setImageUrl(url) { 117 document.getElementById('target').src = url; 118 } 119 </script> 120 121 <body> 122 <p> 123 Image here: 124 </p> 125 126 <img id="target" src="white.png" width="640" height="480"> 127 128 </body> 129</html> 130</pre> 131 132
