chrome/common/extensions/docs/templates/articles/background_pages.html

   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>
  10 A common need for extensions is to have
  11 a single long-running script to manage some task or state.
  12 Background pages to the rescue.
  13 </p>
  14
  15 <p>
  16 As the <a href="overview#arch">architecture overview</a> explains,
  17 the background page is an HTML page that runs in the extension process.
  18 It exists for the lifetime of your extension,
  19 and only one instance of it at a time is active. (Exception: if your
  20 extension uses <a href="manifest/incognito">incognito</a>
  21 "split" mode, a second instance is created for incognito windows.)
  22 </p>
  23
  24 <p>
  25 In a typical extension with a background page,
  26 the UI &mdash;
  27 for example, the browser action or page action
  28 and any options page &mdash;
  29 is implemented by dumb views.
  30 When the view needs some state,
  31 it requests the state from the background page.
  32 When the background page notices a state change,
  33 the background page tells the views to update.
  34 </p>
  35
  36 <h2 id="manifest">Manifest</h2>
  37
  38 <p>
  39 Register your background page in the
  40 <a href="manifest">extension manifest</a>.
  41 In the common case, a background page
  42 does not require any HTML markup.
  43 These kind of background pages can be
  44 implemented using JavaScript files alone,
  45 like 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>
  59 A background page will be generated
  60 by the extension system
  61 that includes each of the files listed
  62 in the <code>scripts</code> property.
  63 </p>
  64
  65 <p>
  66 If you need to specify HTML
  67 in your background page, you can
  68 do that using the <code>page</code>
  69 property 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>
  83 If you need the browser to start up early&mdash;so
  84 you can display notifications, for example&mdash;then
  85 you 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>
  93 You can communicate between your various pages using direct script calls,
  94 similar to how frames can communicate.
  95 The $(ref:extension.getViews) method
  96 returns a list of window objects
  97 for every active page belonging to your extension,
  98 and the
  99 $(ref:extension.getBackgroundPage) method
 100 returns the background page.
 101 </p>
 102
 103 <h2 id="example">Example</h2>
 104
 105 <p>
 106 The following code snippet demonstrates
 107 how the background page
 108 can interact with other pages in the extension.
 109 It also shows how you can use
 110 the background page to handle events
 111 such as user clicks.
 112 </p>
 113
 114 <p>
 115 The extension in this example
 116 has a background page
 117 and multiple pages created
 118 (with
 119 $(ref:tabs.create))
 120 from 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.
 126 chrome.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 &lt;html>
 148   &lt;script>
 149     function setImageUrl(url) {
 150       document.getElementById('target').src = url;
 151     }
 152   &lt;/script>
 153
 154   &lt;body>
 155     &lt;p>
 156     Image here:
 157     &lt;/p>
 158
 159     &lt;img id="target" src="white.png" width="640" height="480">
 160
 161   &lt;/body>
 162 &lt;/html>
 163 </pre>