Skip to content

GitLab

T
tangled
Commit 8b174472 authored by kalman's avatar kalman Committed by Commit bot
Browse files
Options

Write a second set of documentation for extension options now that 

options_ui is available.

For now this will be hosted on a new page options2.html since the
new options aren't stable yet. When they are, I'll switch over the
URLs.

R=mkearney@chromium.org
BUG=406890

Review URL: https://codereview.chromium.org/691283003

Cr-Commit-Position: refs/heads/master@{#302357}
parent 42c03079
Hide whitespace changes
Inline Side-by-side
Showing with 254 additions and 15 deletions
chrome/common/extensions/docs/examples/extensions/buildbot/manifest.json
View file @ 8b174472
......@@ -23,6 +23,9 @@
"default_popup": "popup.html"
},
"options_page": "options.html",
"options_ui": {
"chrome_style": true,
"page": "options.html"
},
"manifest_version": 2
}
chrome/common/extensions/docs/examples/extensions/buildbot/options.html
View file @ 8b174472
......@@ -2,10 +2,13 @@
<html>
<head>
<title>Chromium Buildbot Monitor Options</title>
<style>
body {
padding: 10px;
}
</style>
</head>
<body>
<h2>Options for Chromium Buildbot Monitor</h2>
<br>
<label>
Use desktop notifications:
<input id="notifications" type="checkbox">
......
chrome/common/extensions/docs/templates/articles/options.html
View file @ 8b174472
<h1>Options</h1>
<p class="note">
There is a new way to write your options pages, starting from Chrome 40.
<a href="optionsV2">Learn more</a>, and try it out!
</p>
<p>To allow users to customize the behavior of your extension, you may wish to provide an options page. If you do, a link to it will be provided from the extensions management page at chrome://extensions. Clicking the Options link opens a new tab pointing at your options page.</p>
<p>Use the $(ref:storage) API to persist these preferences. These values will then become accessible in any script within your extension.</p>
<p>Use the $(ref:storage.sync) API to persist these preferences. These values will then become accessible in any script within your extension, on all your user's devices.</p>
<h2 id="step_1">Step 1: Declare your options page in the manifest</h2>
......@@ -80,8 +85,3 @@ document.addEventListener('DOMContentLoaded', restore_options);
document.getElementById('save').addEventListener('click',
save_options);
</pre>
<h2 id="important_notes">Important notes</h2>
<ul>
<li>We plan on providing some default css styles to encourage a consistent look across different extensions' options pages. You can star <a href="http://crbug.com/25317">crbug.com/25317</a> to be notified of updates.</li>
</ul>
chrome/common/extensions/docs/templates/articles/optionsV2.html 0 → 100644
View file @ 8b174472
<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>
chrome/common/extensions/docs/templates/articles/ui_override.html
View file @ 8b174472
......@@ -54,5 +54,5 @@ bookmarks user interface overrides.</p>
An extension can override one or more of the following properties in the
manifest:
</p>
{{+partials.manifest_type
{{+partials.manifest_type
type:apis.extensions.manifestTypes.byName.ChromeUIOverrides /}}
chrome/common/extensions/docs/templates/json/manifest.json
View file @ 8b174472
......@@ -131,7 +131,14 @@
},
"options_page": {
"documentation": "options.html",
"example": "aFile.html"
"example": "options.html"
},
"options_ui": {
"documentation": "optionsV2.html",
"example": {
"page": "options.html",
"chrome_style": true
}
},
"page_action": {
"documentation": "pageAction.html",
......
chrome/common/extensions/docs/templates/public/extensions/options.html
View file @ 8b174472
{{+partials.standard_extensions_article article:articles.options/}}
{{+partials.standard_extensions_article article:articles.options /}}
chrome/common/extensions/docs/templates/public/extensions/optionsV2.html 0 → 100644
View file @ 8b174472
{{+partials.standard_extensions_article article:articles.optionsV2 /}}
extensions/common/api/extensions_manifest_types.json
View file @ 8b174472
......@@ -44,16 +44,16 @@
"description": "The <code>options_ui</code> manifest property declares how the options page should be displayed.",
"properties": {
"page": {
"description": "The path to your options page.",
"description": "The path to your options page, relative to your extension's root.",
"type": "string"
},
"chrome_style": {
"description": "If <code>true</code>, a Chrome user agent stylesheet will be applied to your options page. The default value is <code>false</code>.",
"description": "If <code>true</code>, a Chrome user agent stylesheet will be applied to your options page. The default value is <code>false</code>, but we recommend you enable it for a consistent UI with Chrome.",
"optional": true,
"type": "boolean"
},
"open_in_tab": {
"description": "If <code>true</code>, the options page will be opened in a new tab instead of in an embedded popup in chrome://extensions. The default value is <code>false</code>.",
"description": "<p>If <code>true</code>, your extension's options page will be opened in a new tab rather than embedded in <em>chrome://extensions</em>. The default is <code>false</code>, and we recommend that you don't change it.</p><p><strong>This is only useful to delay the inevitable deprecation of the old options UI!</strong> It will be removed soon, so try not to use it. It will break.</p>",
"optional": true,
"type": "boolean"
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment