1<h1>Background Pages</h1> 2 3 4<p id="eventPageWarning" class="warning"> 5 <em>Caution:</em> Consider using event pages instead. 6 <a href="event_pages">Learn more</a>. 7</p> 8 9<p> 10A common need for extensions is to have 11a single long-running script to manage some task or state. 12Background pages to the rescue. 13</p> 14 15<p> 16As the <a href="overview#arch">architecture overview</a> explains, 17the background page is an HTML page that runs in the extension process. 18It exists for the lifetime of your extension, 19and only one instance of it at a time is active. (Exception: if your 20extension uses <a href="manifest/incognito">incognito</a> 21"split" mode, a second instance is created for incognito windows.) 22</p> 23 24<p> 25In a typical extension with a background page, 26the UI — 27for example, the browser action or page action 28and any options page — 29is implemented by dumb views. 30When the view needs some state, 31it requests the state from the background page. 32When the background page notices a state change, 33the background page tells the views to update. 34</p> 35 36<h2 id="manifest">Manifest</h2> 37 38<p> 39Register your background page in the 40<a href="manifest">extension manifest</a>. 41In the common case, a background page 42does not require any HTML markup. 43These kind of background pages can be 44implemented using JavaScript files alone, 45like this: 46</p> 47 48<pre data-filename="manifest.json"> 49{ 50 "name": "My extension", 51 ... 52 <b>"background": { 53 "scripts": ["background.js"] 54 }</b>, 55 ... 56}</pre> 57 58<p> 59A background page will be generated 60by the extension system 61that includes each of the files listed 62in the <code>scripts</code> property. 63</p> 64 65<p> 66If you need to specify HTML 67in your background page, you can 68do that using the <code>page</code> 69property instead: 70</p> 71 72<pre data-filename="manifest.json"> 73{ 74 "name": "My extension", 75 ... 76 <b>"background": { 77 "page": "background.html" 78 }</b>, 79 ... 80}</pre> 81 82<p> 83If you need the browser to start up early—so 84you can display notifications, for example—then 85you might also want to specify the 86<a href="declare_permissions#background">"background" permission</a>. 87</p> 88 89 90<h2 id="details">Details</h2> 91 92<p> 93You can communicate between your various pages using direct script calls, 94similar to how frames can communicate. 95The $(ref:extension.getViews) method 96returns a list of window objects 97for every active page belonging to your extension, 98and the 99$(ref:extension.getBackgroundPage) method 100returns the background page. 101</p> 102 103<h2 id="example">Example</h2> 104 105<p> 106The following code snippet demonstrates 107how the background page 108can interact with other pages in the extension. 109It also shows how you can use 110the background page to handle events 111such as user clicks. 112</p> 113 114<p> 115The extension in this example 116has a background page 117and multiple pages created 118(with 119$(ref:tabs.create)) 120from a file named <code>image.html</code>. 121 122</p> 123 124<pre data-filename="background.js"> 125// React when a browser action's icon is clicked. 126chrome.browserAction.onClicked.addListener(function(tab) { 127 var viewTabUrl = chrome.extension.getURL('image.html'); 128 var imageUrl = <em>/* an image's URL */</em>; 129 130 // Look through all the pages in this extension to find one we can use. 131 var views = chrome.extension.getViews(); 132 for (var i = 0; i < views.length; i++) { 133 var view = views[i]; 134 135 // If this view has the right URL and hasn't been used yet... 136 if (view.location.href == viewTabUrl && !view.imageAlreadySet) { 137 138 // ...call one of its functions and set a property. 139 view.setImageUrl(imageUrl); 140 view.imageAlreadySet = true; 141 break; // we're done 142 } 143 } 144}); 145</pre> 146<pre data-filename="image.html"> 147<html> 148 <script> 149 function setImageUrl(url) { 150 document.getElementById('target').src = url; 151 } 152 </script> 153 154 <body> 155 <p> 156 Image here: 157 </p> 158 159 <img id="target" src="white.png" width="640" height="480"> 160 161 </body> 162</html> 163</pre> 164