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