Extensions Docs Server: Doc conversion script

chrome/common/extensions/docs/server2/templates/articles/app_lifecycle.html

+<meta name="doc-family" content="apps">
+<h1>Manage App Lifecycle</h1>
+
+
+<p>
+The app runtime and event page are responsible
+for managing the app lifecycle.
+The app runtime manages app installation,
+controls the event page,
+and can shutdown the app at anytime.
+The event page listens out for events from the app runtime
+and manages what gets launched and how.
+</p>
+
+<h2 id="lifecycle">How the lifecycle works</h2>
+
+<p>
+The app runtime loads the event page
+from a user's desktop and
+the <code>onLaunch()</code> event is fired.
+This event tells the event page what windows
+to launch and their dimensions.
+The lifecycle diagram here isn't the nicest to look at,
+but it's practical (and we will make it nicer soon).
+</p>
+
+<img src="{{static}}/images/applifecycle.png"
+     width="444"
+     height="329"
+     alt="how app lifecycle works">
+
+<p>
+When the event page has no executing JavaScript,
+no pending callbacks, and no open windows,
+the runtime unloads the event page and closes the app.
+Before unloading the event page,
+the <code>onSuspend()</code> event is fired.
+This gives the event page opportunity
+to do simple clean-up tasks
+before the app is closed.
+</p>
+
+<h2 id="eventpage">Create event page and windows</h2>
+
+<p>
+All apps must have an event page.
+This page contains the top-level logic of the application
+with none of its own UI and is responsible
+for creating the windows for all other app pages.
+</p>
+
+<h3>Create event page</h3>
+
+<p>
+To create the event page,
+include the "background" field in the app manifest
+and include the <code>background.js</code> in the scripts array.
+Any library scripts used by the event page need to be added
+to the "background" field first:
+</p>
+
+<pre>
+"background": {
+  "scripts": [
+    "foo.js",
+    "background.js"
+  ]
+}
+</pre>
+
+<p>
+Your event page must include the <code>onLaunched()</code> function.
+This function is called
+when your application is launched in any way:
+</p>
+
+<pre>
+chrome.experimental.app.onLaunched.addListener(function() { 
+  // Tell your app what to launch and how.
+});
+</pre>
+
+<h3>Create windows</h3>
+
+<p>
+An event page may create one or more windows at its discretion.
+By default, these windows are created with a script connection
+to the event page and are directly scriptable by the event page.
+</p>
+
+<p>
+Windows can either be shells or panels.
+Shell windows have no browser chrome.
+Panel windows are the same as shell windows,
+except they have different size and position restrictions,
+for example, a chat panel.
+</p>
+
+<p>Here's a sample <code>background.js</code>
+  with a 'shell' window:</p>
+
+<pre>
+chrome.experimental.app.onLaunched.addListener(function() {
+  chrome.app.window.create('main.html', {
+    width: 800,
+    height: 600,
+    minWidth: 800,
+    minHeight: 600,
+    left: 100,
+    top: 100,
+    type: 'shell'
+  });
+});
+</pre>
+
+<p>Here's a sample <code>background.js</code>
+  with a 'panel' window:
+</p>
+
+<pre>
+chrome.experimental.app.onLaunched.addListener(function() {
+  chrome.app.window.create('index.html', {
+    width: 400,
+    height: 200,
+    type: 'panel'
+  });
+});
+</pre>
+
+<h3>Including Launch Data</h3>
+
+<p>
+Depending on how your app is launched,
+you may need to include launch data
+in your event page.
+By default, there is no launch data
+when the app is started by the app launcher.
+For apps that provide intents,
+you need to include the
+<code>launchData.intent</code> parameter.
+</p>
+
+<p>
+Web intents can be launched by other apps invoking their intent, 
+or by the runtime when apps are launched to view or edit files,
+for example from the operating system file explorer.
+To find out how to launch an app with web intents,
+see <a href="app_intents.html#launching">Launching an App with a File</a>.
+</p>
+
+<h2 id="runtime">Listening for app runtime events</h2>
+
+<p>
+The app runtime controls the app installs, updates, and uninstalls.
+You don't need to do anything to set up the app runtime,
+but your event page can listen out for the <code>onInstalled()</code> event
+to store local settings and the
+<code>onSuspend()</code> event to do simple clean-up tasks
+before the event page is unloaded.
+</p>
+
+<h3>Storing local settings</h3>
+
+<p>
+<code>chrome.runtime.onInstalled()</code>
+is called when your app has first been installed,
+or when it has been updated.
+Any time this function is called,
+the <code>onInstalled</code> event is fired.
+The event page can listen for this event and use the
+<a href="storage.html">Storage API</a>
+to store and update local settings
+(see also <a href="app_storage.html#options">Storage options</a>).
+</p>
+
+<pre>
+chrome.runtime.onInstalled.addListener(function() { 
+  chrome.storage.local.set(object items, function callback);
+});
+</pre>
+
+<h3>Preventing data loss</h3>
+
+<p>
+Users can uninstall your app at any time.
+When uninstalled,
+no executing code or private data is left behind.
+This can lead to data loss
+since the users may be uninstalling an app
+that has locally edited, unsynchronized data.
+You should stash data to prevent data loss.
+</p>
+
+<p>
+At a minimum,
+you should store user settings
+so that if users reinstall your app,
+their information is still available for reuse.
+Using the Storage API
+(<a href="storage.html#property-sync">chrome.storage.sync</a>),
+user data can be automatically synced
+with Chrome sync.
+</p>
+
+<h3>Clean-up before app closes</h3>
+
+<p>
+The app runtime sends the <code>onSuspend()</code>
+event to the event page before unloading it.
+Your event page can listen out for this event and
+do clean-up tasks before the app closes.
+</p>
+
+<p>
+Once this event is fired,
+the app runtime starts the process of closing the app:
+all events stop firing and
+JavaScript execution is halted.
+Any asynchronous operations started
+while handling this event are not guaranteed to complete.
+Keep the clean-up tasks synchronous and simple.
+</p>
+
+<pre>
+chrome.runtime.onSuspend.addListener(function() { 
+  // Do some simple clean-up tasks.
+});
+</pre>
+
+<p class="backtotop"><a href="#top">Back to top</a></p>