| OLD | NEW |
|---|
| (Empty) | |
| 1 <meta name="doc-family" content="apps"> |
| 2 <h1 class="page_title">Manage App Lifecycle</h1> |
| 3 <p> |
| 4 The app runtime and event page are responsible |
| 5 for managing the app lifecycle. |
| 6 The app runtime manages app installation, |
| 7 controls the event page, |
| 8 and can shutdown the app at anytime. |
| 9 The event page listens out for events from the app runtime |
| 10 and manages what gets launched and how. |
| 11 </p> |
| 12 <h2 id="lifecycle">How the lifecycle works</h2> |
| 13 <p> |
| 14 The app runtime loads the event page |
| 15 from a user's desktop and |
| 16 the <code>onLaunch()</code> event is fired. |
| 17 This event tells the event page what windows |
| 18 to launch and their dimensions. |
| 19 The lifecycle diagram here isn't the nicest to look at, |
| 20 but it's practical (and we will make it nicer soon). |
| 21 </p> |
| 22 <img src="{{static}}/images/applifecycle.png" |
| 23 width="444" |
| 24 height="329" |
| 25 alt="how app lifecycle works"> |
| 26 <p> |
| 27 When the event page has no executing JavaScript, |
| 28 no pending callbacks, and no open windows, |
| 29 the runtime unloads the event page and closes the app. |
| 30 Before unloading the event page, |
| 31 the <code>onSuspend()</code> event is fired. |
| 32 This gives the event page opportunity |
| 33 to do simple clean-up tasks |
| 34 before the app is closed. |
| 35 </p> |
| 36 <h2 id="eventpage">Create event page and windows</h2> |
| 37 <p> |
| 38 All apps must have an event page. |
| 39 This page contains the top-level logic of the application |
| 40 with none of its own UI and is responsible |
| 41 for creating the windows for all other app pages. |
| 42 </p> |
| 43 <h3>Create event page</h3> |
| 44 <p> |
| 45 To create the event page, |
| 46 include the "background" field in the app manifest |
| 47 and include the <code>background.js</code> in the scripts array. |
| 48 Any library scripts used by the event page need to be added |
| 49 to the "background" field first: |
| 50 </p> |
| 51 <pre> |
| 52 "background": { |
| 53 "scripts": [ |
| 54 "foo.js", |
| 55 "background.js" |
| 56 ] |
| 57 } |
| 58 </pre> |
| 59 <p> |
| 60 Your event page must include the <code>onLaunched()</code> function. |
| 61 This function is called |
| 62 when your application is launched in any way: |
| 63 </p> |
| 64 <pre> |
| 65 chrome.experimental.app.onLaunched.addListener(function() { |
| 66 // Tell your app what to launch and how. |
| 67 }); |
| 68 </pre> |
| 69 <h3>Create windows</h3> |
| 70 <p> |
| 71 An event page may create one or more windows at its discretion. |
| 72 By default, these windows are created with a script connection |
| 73 to the event page and are directly scriptable by the event page. |
| 74 </p> |
| 75 <p> |
| 76 Windows can either be shells or panels. |
| 77 Shell windows have no browser chrome. |
| 78 Panel windows are the same as shell windows, |
| 79 except they have different size and position restrictions, |
| 80 for example, a chat panel. |
| 81 </p> |
| 82 <p>Here's a sample <code>background.js</code> |
| 83 with a 'shell' window:</p> |
| 84 <pre> |
| 85 chrome.experimental.app.onLaunched.addListener(function() { |
| 86 chrome.app.window.create('main.html', { |
| 87 width: 800, |
| 88 height: 600, |
| 89 minWidth: 800, |
| 90 minHeight: 600, |
| 91 left: 100, |
| 92 top: 100, |
| 93 type: 'shell' |
| 94 }); |
| 95 }); |
| 96 </pre> |
| 97 <p>Here's a sample <code>background.js</code> |
| 98 with a 'panel' window: |
| 99 </p> |
| 100 <pre> |
| 101 chrome.experimental.app.onLaunched.addListener(function() { |
| 102 chrome.app.window.create('index.html', { |
| 103 width: 400, |
| 104 height: 200, |
| 105 type: 'panel' |
| 106 }); |
| 107 }); |
| 108 </pre> |
| 109 <h3>Including Launch Data</h3> |
| 110 <p> |
| 111 Depending on how your app is launched, |
| 112 you may need to include launch data |
| 113 in your event page. |
| 114 By default, there is no launch data |
| 115 when the app is started by the app launcher. |
| 116 For apps that provide intents, |
| 117 you need to include the |
| 118 <code>launchData.intent</code> parameter. |
| 119 </p> |
| 120 <p> |
| 121 Web intents can be launched by other apps invoking their intent, |
| 122 or by the runtime when apps are launched to view or edit files, |
| 123 for example from the operating system file explorer. |
| 124 To find out how to launch an app with web intents, |
| 125 see <a href="app_intents.html#launching">Launching an App with a File</a>. |
| 126 </p> |
| 127 <h2 id="runtime">Listening for app runtime events</h2> |
| 128 <p> |
| 129 The app runtime controls the app installs, updates, and uninstalls. |
| 130 You don't need to do anything to set up the app runtime, |
| 131 but your event page can listen out for the <code>onInstalled()</code> event |
| 132 to store local settings and the |
| 133 <code>onSuspend()</code> event to do simple clean-up tasks |
| 134 before the event page is unloaded. |
| 135 </p> |
| 136 <h3>Storing local settings</h3> |
| 137 <p> |
| 138 <code>chrome.runtime.onInstalled()</code> |
| 139 is called when your app has first been installed, |
| 140 or when it has been updated. |
| 141 Any time this function is called, |
| 142 the <code>onInstalled</code> event is fired. |
| 143 The event page can listen for this event and use the |
| 144 <a href="storage.html">Storage API</a> |
| 145 to store and update local settings |
| 146 (see also <a href="app_storage.html#options">Storage options</a>). |
| 147 </p> |
| 148 <pre> |
| 149 chrome.runtime.onInstalled.addListener(function() { |
| 150 chrome.storage.local.set(object items, function callback); |
| 151 }); |
| 152 </pre> |
| 153 <h3>Preventing data loss</h3> |
| 154 <p> |
| 155 Users can uninstall your app at any time. |
| 156 When uninstalled, |
| 157 no executing code or private data is left behind. |
| 158 This can lead to data loss |
| 159 since the users may be uninstalling an app |
| 160 that has locally edited, unsynchronized data. |
| 161 You should stash data to prevent data loss. |
| 162 </p> |
| 163 <p> |
| 164 At a minimum, |
| 165 you should store user settings |
| 166 so that if users reinstall your app, |
| 167 their information is still available for reuse. |
| 168 Using the Storage API |
| 169 (<a href="storage.html#property-sync">chrome.storage.sync</a>), |
| 170 user data can be automatically synced |
| 171 with Chrome sync. |
| 172 </p> |
| 173 <h3>Clean-up before app closes</h3> |
| 174 <p> |
| 175 The app runtime sends the <code>onSuspend()</code> |
| 176 event to the event page before unloading it. |
| 177 Your event page can listen out for this event and |
| 178 do clean-up tasks before the app closes. |
| 179 </p> |
| 180 <p> |
| 181 Once this event is fired, |
| 182 the app runtime starts the process of closing the app: |
| 183 all events stop firing and |
| 184 JavaScript execution is halted. |
| 185 Any asynchronous operations started |
| 186 while handling this event are not guaranteed to complete. |
| 187 Keep the clean-up tasks synchronous and simple. |
| 188 </p> |
| 189 <pre> |
| 190 chrome.runtime.onSuspend.addListener(function() { |
| 191 // Do some simple clean-up tasks. |
| 192 }); |
| 193 </pre> |
| 194 <p class="backtotop"><a href="#top">Back to top</a></p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src