Home | History | Annotate | Download | only in static 
      1 <div id="pageData-name" class="pageData">Background Pages</div>
      2 <div id="pageData-showTOC" class="pageData">true</div>
      3 
      4 <p>
      5 A common need for extensions is to have
      6 a single long-running script to manage some task or state.
      7 Background pages to the rescue.
      8 </p>
      9 
     10 <p>
     11 As the <a href="overview.html#arch">architecture overview</a> explains,
     12 the background page is an HTML page that runs in the extension process.
     13 It exists for the lifetime of your extension,
     14 and only one instance of it at a time is active.
     15 </p>
     16 
     17 <p>
     18 In a typical extension with a background page,
     19 the UI &mdash;
     20 for example, the browser action or page action
     21 and any options page &mdash;
     22 is implemented by dumb views.
     23 When the view needs some state,
     24 it requests the state from the background page.
     25 When the background page notices a state change,
     26 the background page tells the views to update.
     27 </p>
     28 
     29 <h2 id="manifest">Manifest</h2>
     30 
     31 <p>
     32 Register your background page in the
     33 <a href="manifest.html">extension manifest</a>
     34 like this:
     35 </p>
     36 
     37 <pre>{
     38   "name": "My extension",
     39   ...
     40   <b>"background_page": "background.html"</b>,
     41   ...
     42 }</pre>
     43 
     44 <p>
     45 If you need the browser to start up early&mdash;so
     46 you can display notifications, for example&mdash;then
     47 you 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>
     55 You can communicate between your various pages using direct script calls,
     56 similar to how frames can communicate.
     57 The <a href="extension.html#method-getViews"><code>chrome.extension.getViews()</code></a> method
     58 returns a list of window objects
     59 for every active page belonging to your extension,
     60 and the
     61 <a href="extension.html#method-getBackgroundPage"><code>chrome.extension.getBackgroundPage()</code></a> method
     62 returns the background page.
     63 </p>
     64 
     65 <h2 id="example">Example</h2>
     66 
     67 <p>
     68 The following code snippet demonstrates
     69 how the background page
     70 can interact with other pages in the extension.
     71 It also shows how you can use
     72 the background page to handle events
     73 such as user clicks.
     74 </p>
     75 
     76 <p>
     77 The extension in this example
     78 has a background page
     79 and multiple pages created
     80 (with
     81 <a href="tabs.html#method-create"><code>chrome.tabs.create()</code></a>)
     82 from 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 &lt;html>
     89   &lt;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   &lt;/script>
    111 &lt;/html>
    112 
    113 <em>//In image.html:</em>
    114 &lt;html>
    115   &lt;script>
    116     function setImageUrl(url) {
    117       document.getElementById('target').src = url;
    118     }
    119   &lt;/script>
    120 
    121   &lt;body>
    122     &lt;p>
    123     Image here:
    124     &lt;/p>
    125 
    126     &lt;img id="target" src="white.png" width="640" height="480">
    127 
    128   &lt;/body>
    129 &lt;/html>
    130 </pre>
    131 
    132