Write docs for options_ui

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

Index: chrome/common/extensions/docs/templates/articles/options2.html
diff --git a/chrome/common/extensions/docs/templates/articles/options2.html b/chrome/common/extensions/docs/templates/articles/options2.html
new file mode 100644
index 0000000000000000000000000000000000000000..a6303a530987cfc63c3370f66bb291cb946e243b
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/articles/options2.html
@@ -0,0 +1,226 @@
+<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">

[mkearney1, 2014/10/31 20:48:24]

image name is options-ui.png, so image isn't showing itself.

[not at google - send to devlin, 2014/10/31 21:51:39]

Oops. That's so weird, works on my mac. Fixed.

+
+<p>
+Note: Always use the $(ref:storage.sync) API to persist your options. This will

[mkearney1, 2014/10/31 20:48:24]

I'd be inclined to drop the "Note:". Just assert... "Always use...".

[not at google - send to devlin, 2014/10/31 21:51:39]

Done.

+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 is an example options page:

[mkearney1, 2014/10/31 20:48:24]

Slight rewrite: 

Here's an example, including an options page and JavaScript to persist the
options.

[not at google - send to devlin, 2014/10/31 21:51:40]

Done. With or without the : at the end?

+</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 that should be considered while writing them, mostly caused by not

[mkearney1, 2014/10/31 20:48:24]

Replace 'that should be considered' with 'you should consider' for brevity sake.

[not at google - send to devlin, 2014/10/31 21:51:40]

Done.

+being hosted inside their own tabs.
+</p>
+
+<h3 id="tabs-api">Tabs API</h3>
+<p>
+Options page code cannot assume that they are hosted inside a tab, and this may

[mkearney1, 2014/10/31 20:48:24]

'that they are' better as 'that it's'.

[not at google - send to devlin, 2014/10/31 21:51:40]

Done.

+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, we recommend that you provide fixed minimum dimensions for

[mkearney1, 2014/10/31 20:48:23]

Can you drop 'we recommend that you' and go with 'provide' straight up?

[not at google - send to devlin, 2014/10/31 21:51:40]

Done.

+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 version of Chrome will only recognize <code>options_page</code>,

[mkearney1, 2014/10/31 20:48:24]

Nit: 'Older version' should be 'Older versions'.

[not at google - send to devlin, 2014/10/31 21:51:40]

Done.

+and only open in tabs. Chrome 40 and onwards will prefer to use the

[mkearney1, 2014/10/31 20:48:24]

'will prefer' better as 'prefers'.

[not at google - send to devlin, 2014/10/31 21:51:39]

Done.

+<code>options_ui</code> field if it's specified.
+<br><br>
+You can use this to provide separate options pages for compatibility.

[mkearney1, 2014/10/31 20:48:23]

Do you need line 190? Seems redundant.

[not at google - send to devlin, 2014/10/31 21:51:40]

I think it's redundant in a way, though pointing out something that may not be
clear.

It's actually in reaction to a bug somebody filed where they wanted some way to
tell, programmatically, whether their options page was in a tab vs a dialogue.
My answer was that we shouldn't add that because it's temporary anyway; instead,
use both options_page and options_ui together and provide different options
pages.

This sentence was my attempt to express that. Maybe it's already evident in this
article anyway? Should I update somewhere in this article to imply that more
strongly, and delete this paragraph? Change this paragraph? Neither?

+</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

[mkearney1, 2014/10/31 20:48:24]

Nit: comma after "In a future version of Chrome".

[not at google - send to devlin, 2014/10/31 21:51:39]

Done.

+<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>