Write docs for options_ui

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

Index: chrome/common/extensions/docs/templates/articles/optionsV2.html
diff --git a/chrome/common/extensions/docs/templates/articles/optionsV2.html b/chrome/common/extensions/docs/templates/articles/optionsV2.html
new file mode 100644
index 0000000000000000000000000000000000000000..249f798fd3564b11f9b60fe6102e52bb15d7c07f
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/articles/optionsV2.html
@@ -0,0 +1,225 @@
+<h1>Options</h1>
+
+<p class="warning">
+This new way of writing options is only supported from Chrome 40 onwards.
+<a href="options">See the old documentation</a>.
+</p>
+
+<p>
+To allow users to customize the behavior of your extension, you may wish to
+provide an options page.
+
+<p>
+If you do, an Options link will be shown on the extensions management page at
+<em>chrome://extensions</em> which opens a dialogue containing your options
+page:
+</p>
+
+<img src="{{static}}/images/options-ui.png" alt="Options UI screenshot">
+
+<p>
+Always use the $(ref:storage.sync) API to persist your options. This will
+make them accessible from script within your extension, on all of your user's
+devices.
+</p>
+
+<h2 id="step-1">Step 1: Declare your options page in the manifest</h2>
+
+<p>
+Use the <code>options_ui</code> manifest field to declare the options page and
+how it should be displayed:
+</p>
+
+<pre data-filename="manifest.json">
+{
+  "name": "My extension",
+  ...
+  <b>"options_ui"</b>: {
+    // Required.
+    <b>"page": "options.html"</b>,
+    // Recommended.
+    <b>"chrome_style": true,</b>
+    // Not recommended; only provided for backwards compatibility,
+    // and will be unsupported in a future version of Chrome (TBD).
+    <b>//"open_in_tab": true</b>
+  },
+  ...
+}
+</pre>
+
+{{+partials.manifest_type
+  type:apis.extensions.extensionsManifestTypes.byName.OptionsUI /}}
+
+<h2 id="step-2">Step 2: Write your options page</h2>
+
+<p>
+Here's an example, including an options page and JavaScript to persist the
+options:
+</p>
+
+<pre data-filename="options.html">
+&lt;!DOCTYPE html&gt;
+&lt;html&gt;
+&lt;head&gt;
+  &lt;title&gt;My Test Extension Options&lt;/title&gt;
+  &lt;style&gt;
+    body: { padding: 10px; }
+  &lt;/style&gt;
+&lt;/head&gt;
+
+&lt;body&gt;
+  Favorite color:
+  &lt;select id="color"&gt;
+   &lt;option value="red"&gt;red&lt;/option&gt;
+   &lt;option value="green"&gt;green&lt;/option&gt;
+   &lt;option value="blue"&gt;blue&lt;/option&gt;
+   &lt;option value="yellow"&gt;yellow&lt;/option&gt;
+  &lt;/select&gt;
+
+  &lt;label&gt;
+    &lt;input type="checkbox" id="like"&gt;
+    I like colors.
+  &lt;/label&gt;
+
+  &lt;div id="status"&gt;&lt;/div&gt;
+  &lt;button id="save"&gt;Save&lt;/button&gt;
+
+  &lt;script src="options.js"&gt;&lt;/script&gt;
+&lt;/body&gt;
+&lt;/html&gt;
+</pre>
+
+<pre data-filename="options.js">
+// Saves options to chrome.storage.sync.
+function save_options() {
+  var color = document.getElementById('color').value;
+  var likesColor = document.getElementById('like').checked;
+  chrome.storage.sync.set({
+    favoriteColor: color,
+    likesColor: likesColor
+  }, function() {
+    // Update status to let user know options were saved.
+    var status = document.getElementById('status');
+    status.textContent = 'Options saved.';
+    setTimeout(function() {
+      status.textContent = '';
+    }, 750);
+  });
+}
+
+// Restores select box and checkbox state using the preferences
+// stored in chrome.storage.
+function restore_options() {
+  // Use default value color = 'red' and likesColor = true.
+  chrome.storage.sync.get({
+    favoriteColor: 'red',
+    likesColor: true
+  }, function(items) {
+    document.getElementById('color').value = items.favoriteColor;
+    document.getElementById('like').checked = items.likesColor;
+  });
+}
+document.addEventListener('DOMContentLoaded', restore_options);
+document.getElementById('save').addEventListener('click',
+    save_options);
+</pre>
+
+<h2 id="considerations">Considerations</h2>
+
+<p>
+Options pages embedded inside <em>chrome://extensions</em> have some subtle
+behavior you should consider while writing them, mostly caused by not being
+hosted inside their own tabs.
+</p>
+
+<h3 id="tabs-api">Tabs API</h3>
+<p>
+Options page code cannot assume that it's hosted inside a tab, and this may
+affect how the $(ref:tabs Tabs API) can be used. For example,
+<ul>
+  <li>$(ref:tabs.query) will never find a tab with your extension's options
+  page URL.</li>
+  <li>$(ref:tabs.onCreated) will not fire when your options page is
+  opened.</li>
+  <li>$(ref:tabs.onUpdated) will not fire when your options page load state
+  changes.</li>
+  <li>You cannot use $(ref:tabs.connect) or $(ref:tabs.sendMessage) to
+  communicate with your options page.</li>
+</ul>
+</p>
+<p>
+It is easy to work around these issues or use alternative APIs. Generally
+speaking you shouldn't need to manipulate the tab containing your extensions
+options page.
+</p>
+<p>
+You can use $(ref:runtime.connect) and $(ref:runtime.sendMessage) because your
+options page is an extension page.
+</p>
+
+<h3 id="messaging-api">Messaging APIs</h3>
+<p>
+If your options page sends a message using $(ref:runtime.connect) or
+$(ref:runtime.sendMessage) then the $(ref:runtime.MessageSender.tab Tab's) URL
+and $(ref:runtime.MessageSender.url MessageSender's URL) properties won't agree
+- the tab URL will be of <em>chrome://settings</em> while the URL will be your
+options page URL.
+</p>
+
+<h3 id="sizing">Sizing</h3>
+<p>
+The embedded dialogue should automatically determine its own size based on the
+options page content. However, the dialogue may not find a good size for some
+types of options pages. This problem is most common for options pages that
+adjust their size based on window size.
+</p>
+<p>
+If this is an issue, provide fixed minimum dimensions for the options page to
+ensure that the dialogue will find an appropriate size.
+</p>
+
+<h2 id="migration">Migrating from old options pages</h2>
+<p class="warning">
+At least until Chrome 40 is stable, you should specify <strong>both</strong>
+the <code>options_ui</code> <strong>and</strong> the <code>options_page</code>
+fields.
+<br><br>
+Older versions of Chrome will only recognize <code>options_page</code>, and
+only open in tabs. Chrome 40 and onwards prefers to use the
+<code>options_ui</code> field if it's specified.
+</p>
+
+The <code>options_ui</code> manifest field and embedded extension options
+were introduced in Chrome 40. Prior to these changes, options pages were always
+displayed in new tabs and were declared using the <code>options_page</code>
+field:
+</p>
+
+<pre data-filename="manifest.json">
+{
+  "name": "My extension",
+  ...
+  "options_page": "options.html"
+  ...
+}
+</pre>
+<p>
+See <a href="options">this document</a> for full details.
+</p>
+
+<p>
+Chrome will continue to support extensions that use the legacy
+<code>options_page</code> manifest field, but new and existing extensions
+should use the <code>options_ui</code> manifest field to ensure that their
+options pages are displayed as intended.
+</p>
+<p>
+If you specify both, Chrome 40 and onwards will ignore the value of
+<code>options_page</code>.
+</p>
+<p>
+In a future version of Chrome, any extension which specifies
+<code>options_page</code> will change to match the <code>options_ui</code>
+behavior - most importantly, they will always be embedded in
+<em>chrome://extensions</em> - so migrate as soon as possible.
+</p>