| <h1>Background Pages</h1> |
| |
| |
| <p id="eventPageWarning" class="warning"> |
| <em>Caution:</em> Consider using event pages instead. |
| <a href="event_pages.html">Learn more</a>. |
| </p> |
| |
| <p> |
| A common need for extensions is to have |
| a single long-running script to manage some task or state. |
| Background pages to the rescue. |
| </p> |
| |
| <p> |
| As the <a href="overview.html#arch">architecture overview</a> explains, |
| the background page is an HTML page that runs in the extension process. |
| It exists for the lifetime of your extension, |
| and only one instance of it at a time is active. (Exception: if your |
| extension uses <a href="manifest/incognito.html">incognito</a> |
| "split" mode, a second instance is created for incognito windows.) |
| </p> |
| |
| <p> |
| In a typical extension with a background page, |
| the UI — |
| for example, the browser action or page action |
| and any options page — |
| is implemented by dumb views. |
| When the view needs some state, |
| it requests the state from the background page. |
| When the background page notices a state change, |
| the background page tells the views to update. |
| </p> |
| |
| <h2 id="manifest">Manifest</h2> |
| |
| <p> |
| Register your background page in the |
| <a href="manifest.html">extension manifest</a>. |
| In the common case, a background page |
| does not require any HTML markup. |
| These kind of background pages can be |
| implemented using JavaScript files alone, |
| like this: |
| </p> |
| |
| <pre>{ |
| "name": "My extension", |
| ... |
| <b>"background": { |
| "scripts": ["background.js"] |
| }</b>, |
| ... |
| }</pre> |
| |
| <p> |
| A background page will be generated |
| by the extension system |
| that includes each of the files listed |
| in the <code>scripts</code> property. |
| </p> |
| |
| <p> |
| If you need to specify HTML |
| in your background page, you can |
| do that using the <code>page</code> |
| property instead: |
| </p> |
| |
| <pre>{ |
| "name": "My extension", |
| ... |
| <b>"background": { |
| "page": "background.html" |
| }</b>, |
| ... |
| }</pre> |
| |
| <p> |
| If you need the browser to start up early—so |
| you can display notifications, for example—then |
| you might also want to specify the |
| <a href="declare_permissions.html#background">"background" permission</a>. |
| </p> |
| |
| |
| <h2 id="details">Details</h2> |
| |
| <p> |
| You can communicate between your various pages using direct script calls, |
| similar to how frames can communicate. |
| The $ref:extension.getViews method |
| returns a list of window objects |
| for every active page belonging to your extension, |
| and the |
| $ref:extension.getBackgroundPage method |
| returns the background page. |
| </p> |
| |
| <h2 id="example">Example</h2> |
| |
| <p> |
| The following code snippet demonstrates |
| how the background page |
| can interact with other pages in the extension. |
| It also shows how you can use |
| the background page to handle events |
| such as user clicks. |
| </p> |
| |
| <p> |
| The extension in this example |
| has a background page |
| and multiple pages created |
| (with |
| $ref:tabs.create) |
| from a file named <code>image.html</code>. |
| |
| </p> |
| |
| <pre> |
| <em>//In background.js:</em> |
| // React when a browser action's icon is clicked. |
| chrome.browserAction.onClicked.addListener(function(tab) { |
| var viewTabUrl = chrome.extension.getURL('image.html'); |
| var imageUrl = <em>/* an image's URL */</em>; |
| |
| // Look through all the pages in this extension to find one we can use. |
| var views = chrome.extension.getViews(); |
| for (var i = 0; i < views.length; i++) { |
| var view = views[i]; |
| |
| // If this view has the right URL and hasn't been used yet... |
| if (view.location.href == viewTabUrl && !view.imageAlreadySet) { |
| |
| // ...call one of its functions and set a property. |
| view.setImageUrl(imageUrl); |
| view.imageAlreadySet = true; |
| break; // we're done |
| } |
| } |
| }); |
| |
| <em>//In image.html:</em> |
| <html> |
| <script> |
| function setImageUrl(url) { |
| document.getElementById('target').src = url; |
| } |
| </script> |
| |
| <body> |
| <p> |
| Image here: |
| </p> |
| |
| <img id="target" src="white.png" width="640" height="480"> |
| |
| </body> |
| </html> |
| </pre> |