chrome/common/extensions/docs/contentSettings.html - Issue 8352042: Update contentSettings extension API docs.

Unified Diff: chrome/common/extensions/docs/contentSettings.html

Issue 8352042: Update contentSettings extension API docs. (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: review Created 9 years, 2 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

« no previous file with comments | « chrome/common/extensions/api/extension_api.json ('k') | chrome/common/extensions/docs/experimental.contentSettings.html » ('j') | chrome/common/extensions/docs/static/contentSettings.html » ('J')
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

Index: chrome/common/extensions/docs/contentSettings.html

diff --git a/chrome/common/extensions/docs/contentSettings.html b/chrome/common/extensions/docs/contentSettings.html

index 0a71540ecf97ea82f0ac503a6b007d7019693d03..d7fdc6f4b152b6213c7a26bc09ee88ee37e96b92 100644

--- a/chrome/common/extensions/docs/contentSettings.html

+++ b/chrome/common/extensions/docs/contentSettings.html

@@ -16,7 +16,7 @@

- <title>chrome.contentSettings - Google Chrome Extensions - Google Code</title></head>

+ <title>Content Settings - Google Chrome Extensions - Google Code</title></head>

You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.

@@ -251,16 +251,44 @@

- <h1 class="page_title">chrome.contentSettings</h1>

+ <h1 class="page_title">Content Settings</h1>

</div>

<h2>Contents</h2>

<ol>

- <li style="display: none; ">

- <a>h2Name</a>

+ <li>

+ <a href="#manifest">Manifest</a>

+ <ol>

+ <li style="display: none; ">

+ <a>h3Name</a>

+ </li>

+ </ol>

+ </li><li>

+ <a href="#patterns">Content Setting Patterns</a>

<ol>

<li>

+ <a href="#pattern-precedence">Pattern Precedence</a>

+ </li>

+ </ol>

+ </li><li>

+ <a href="#primary-secondary">Primary and Secondary Patterns</a>

+ <ol>

+ <li style="display: none; ">

+ <a>h3Name</a>

+ </li>

+ </ol>

+ </li><li>

+ <a href="#resource-identifiers">Resource Identifiers</a>

+ <ol>

+ <li style="display: none; ">

+ <a>h3Name</a>

+ </li>

+ </ol>

+ </li><li>

+ <a href="#examples">Examples</a>

+ <ol>

+ <li style="display: none; ">

</li>

</ol>

@@ -324,7 +352,147 @@

</p>

- <div id="static"></div>

+ <div id="static"><div id="pageData-name" class="pageData">Content Settings</div>

+

+<p>

+The content settings module allows you to change settings that control whether

+websites can use features such as cookies, Javascript, and plug-ins.

+More generally speaking, content settings allow you to customize Chrome's

+behavior on a per-site basis instead of globally.</p>

+<p>

+</p>

+<h2 id="manifest">Manifest</h2>

+<p>You must declare the "contentSettings" permission

+in your extension's manifest to use the API.

+For example:</p>

+<pre>{

+ "name": "My extension",

+ ...

+ <b>"permissions": [

+ "contentSettings"

+ ]</b>,

+ ...

+}</pre>

+<h2 id="patterns">Content Setting Patterns</h2>

+<p>

+Content settings are applied to specific websites via patterns that define which

+sites they apply to. <code>http://*.youtube.com/*</code> matches youtube.com and

+all its subdomains, for example. For further details, see the

+<a href="match_patterns.html">Match Pattern documentation</a>.</p>

+<p>

+Note that there are some differences between patterns for content settings and

+match patterns:

+</p><ul><li>For <code>http</code>,

+<code>https</code>, and <code>ftp</code> URLs the path has to be a wildcard

+(<code>/*</code>). For <code>file</code> URLs, the path has to be completely

+specified and is <strong>not</strong> allowed to contain wildcards.</li>

+<li>In contrast to match patterns, content setting patterns can specify a port

+number. If a port number is specified, the pattern only matches websites with

+that port. If no port number is specified, the pattern matches all ports.

+</li>

+</ul>

+<p></p>

+<h3 id="pattern-precedence">Pattern Precedence</h3>

+<p>

+When more than one content setting rule applies for a given site, the rule with

+the more specific pattern takes precedence.

+</p>

+<p>For example, the following patterns are ordered by precedence:

+</p><ul>

+<li><code>http://www.example.com/*</code></li>

+<li><code>http://*.example.com/*</code> (matching

+example.com and all subdomains)</li>

+<li><code><all_urls></code> (matching every URL)</li>

+</ul>

+There are three ways in which one pattern can be more specific than another

+pattern:

+<ul>

+<li>Wildcards in the port (like <code>http://www.example.com:*/*</code>)</li>

+<li>Wildcards in the scheme (like <code>*://www.example.com:123/*</code>)</li>

+<li>Wildcards in the hostname (like

+ <code>http://*.example.com:123/*</code>)</li>

+</ul>

+If a pattern is more specific than another pattern in one part but less specific

+in another part, the different parts are checked in the following order:

+hostname, scheme, port. That means that for example the list of URLs above is

+ordered by precedence (the first pattern is more specific in the scheme than the

+second one, and the second one is more specific in the hostname than the third

+one).

+<p></p>

+<h2 id="primary-secondary">Primary and Secondary Patterns</h2>

+<p>

+The URL taken into account when deciding which content setting to apply depends

+on the content type. For example, for

+<a href="#property-notifications">notifications</a> settings are

+based on the URL shown in the omnibox. This URL is called the "primary" URL.</p>

+<p>

+Some content types also can take additional URLs into account. For example,

+whether a site is allowed to set a

+<a href="#property-cookies">cookie</a> is decided based on the URL

+of the HTTP request (which is the primary URL in this case) as well as the URL

+shown in the omnibox (which is called the "secondary" URL).

+</p>

+<p>

+If there are multiple rules with primary and secondary patterns, the rule with

+the more specific primary pattern takes precedence. If there are multiple rules

+with the same primary pattern, the rule with the more specific secondary pattern

+takes precedence. For example, the following list of primary/secondary pattern

+pairs is ordered by precedence:

+</p><table>

+<tbody><tr>

+ <td><code>http://www.moose.com/*</code>, </td>

+ <td><code>http://www.wombat.com/*</code></td>

+</tr><tr>

+ <td><code>http://www.moose.com/*</code>, </td>

+ <td><code><all_urls></code></td>

+</tr><tr>

+ <td><code><all_urls></code>, </td>

+ <td><code>http://www.wombat.com/*</code></td>

+</tr><tr>

+ <td><code><all_urls></code>, </td>

+ <td><code><all_urls></code></td>

+</tr>

+</tbody></table>

+<p></p>

+<h2 id="resource-identifiers">Resource Identifiers</h2>

+<p>

+Resource identifiers allow you to specify content settings for specific

+sub-types of a content type. Currently, the only content type that supports

+resource identifiers is <a href="#property-plugins"><code>plugins</code></a>,

+where a resource identifier identifies a specific plug-in. When applying content

+settings, first the settings for the specific plug-in are checked. If there are

+no settings found for the specific plug-in, the general content settings for

+plug-ins are checked.

+</p>

+<p>

+For example, if there is a content setting rule with the resource identifier

+<code>adobe-flash-player</code> and the pattern <code><all_urls></code>,

+it takes precedence over a rule without a resource identifier and the pattern

+<code>http://www.example.com/*</code>, even if that pattern is more specific.

+</p>

+<p>

+You can get a list of resource identifiers for a content type by calling the

+<a href=""><code>getResourceIdentifiers</code></a> method. The returned list can

+change with the set of installed plug-ins on the user's machine, but Chrome

+tries to keep the identifiers stable across plug-in updates.

+</p>

+<h2 id="examples">Examples</h2>

+<p>

+You can find samples of this API on the

+<a href="samples.html#contentSettings">sample page</a>.

+</p>

+

+</div>

@@ -373,7 +541,7 @@

Undocumented.

</dd>

- <dd>Whether to allow cookies and other local data to be set by websites. One of<br><var>allow</var>: Accept cookies,<br><var>block</var>: Block cookies,<br><var>session_only</var>: Accept cookies only for the current session. Default is <var>allow</var>.<br>The primary URL is the URL representing the cookie origin. The secondary URL is the URL of the top-level frame.</dd>

+ <dd>Whether to allow cookies and other local data to be set by websites. One of<br><var>allow</var>: Accept cookies,<br><var>block</var>: Block cookies,<br><var>session_only</var>: Accept cookies only for the current session. <br>Default is <var>allow</var>.<br>The primary URL is the URL representing the cookie origin. The secondary URL is the URL of the top-level frame.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -447,7 +615,7 @@

Undocumented.

</dd>

- <dd>Whether to show images. One of<br><var>allow</var>: Show images,<br><var>block</var>: Don't show images. Default is <var>allow</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

+ <dd>Whether to show images. One of<br><var>allow</var>: Show images,<br><var>block</var>: Don't show images. <br>Default is <var>allow</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -521,7 +689,7 @@

Undocumented.

</dd>

- <dd>Whether to run Javascript. One of<br><var>allow</var>: Run Javascript,<br><var>block</var>: Don't run Javascript. Default is <var>allow</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

+ <dd>Whether to run JavaScript. One of<br><var>allow</var>: Run JavaScript,<br><var>block</var>: Don't run JavaScript. <br>Default is <var>allow</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -595,7 +763,7 @@

Undocumented.

</dd>

- <dd>Whether to run plug-ins. One of<br><var>allow</var>: Run plug-ins automatically,<br><var>block</var>: Don't run plug-ins automatically. Default is <var>allow</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

+ <dd>Whether to run plug-ins. One of<br><var>allow</var>: Run plug-ins automatically,<br><var>block</var>: Don't run plug-ins automatically. <br>Default is <var>allow</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -669,7 +837,7 @@

Undocumented.

</dd>

- <dd>Whether to allow sites to show pop-ups. One of<br><var>allow</var>: Allow sites to show pop-ups,<br><var>block</var>: Don't allow sites to show pop-ups. Default is <var>block</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

+ <dd>Whether to allow sites to show pop-ups. One of<br><var>allow</var>: Allow sites to show pop-ups,<br><var>block</var>: Don't allow sites to show pop-ups. <br>Default is <var>block</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -743,7 +911,7 @@

Undocumented.

</dd>

- <dd>Whether to allow sites to show desktop notifications. One of<br><var>allow</var>: Allow sites to show desktop notifications,<br><var>block</var>: Don't allow sites to show desktop notifications,<br><var>ask</var>: Ask when a site wants to show desktop notifications. Default is <var>ask</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

+ <dd>Whether to allow sites to show desktop notifications. One of<br><var>allow</var>: Allow sites to show desktop notifications,<br><var>block</var>: Don't allow sites to show desktop notifications,<br><var>ask</var>: Ask when a site wants to show desktop notifications. <br>Default is <var>ask</var>.<br>The primary URL is the main-frame URL. The secondary URL is not used.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -956,7 +1124,7 @@

Undocumented.

</dd>

- <dd>The only content type using resource identifiers is <var>plugins</var>. Using a resource identifier allows an extension to specify content settings applying only to a specific plug-in. If no rule for the specific plug-in is found, the rules without resource identifiers are applied.</dd>

+ <dd>The only content type using resource identifiers is <a href="contentSettings.html#property-plugins"><var>plugins</var></a>. For more information, see <a href="contentSettings.html#resource-identifiers">Resource Identifiers</a>.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -2365,7 +2533,7 @@

Undocumented.

</dd>

- <dd>The pattern for the primary URL. For details on the format of a pattern, see <a href="match_patterns.html">Match Patterns</a>.</dd>

+ <dd>The pattern for the primary URL. For details on the format of a pattern, see <a href="contentSettings.html#patterns">Content Setting Patterns</a>.</dd>

This parameter was added in version

<b><span></span></b>.

@@ -2433,7 +2601,7 @@

Undocumented.

</dd>

- <dd>The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see <a href="match_patterns.html">Match Patterns</a>.</dd>

+ <dd>The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see <a href="contentSettings.html#patterns">Content Setting Patterns</a>.</dd>

This parameter was added in version

<b><span></span></b>.