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

Side by Side Diff: chrome/common/extensions/docs/static/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 unified diff | Download patch | Annotate | Revision Log

OLD	NEW
(Empty)
	1 <div id="pageData-name" class="pageData">Content Settings</div>

	2
	kathyw 2011/12/13 02:47:32 I see no methods in the staged version of this pag I see no methods in the staged version of this page. Do they have "nodoc" or something? For example, there's no getResourceIdentifier() method.
	3 <!-- BEGIN AUTHORED CONTENT -->

	4 <p>

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

	6 websites can use features such as cookies, Javascript, and plug-ins.
	kathyw 2011/12/13 02:47:32 Javascript -> JavaScript Javascript -> JavaScript
	7 More generally speaking, content settings allow you to customize Chrome's

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

	9 <p>

	10 </p>

	11

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

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

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

	15 For example:</p>

	16 <pre>{

	17 "name": "My extension",

	18 ...

	19 <b>"permissions": [

	20 "contentSettings"

	21 ]</b>,

	22 ...

	23 }</pre>

	24

	25

	26 <h2 id="patterns">Content Setting Patterns</h2>
	kathyw 2011/12/13 02:47:32 We use Sentence caps for sections (Title Caps for We use Sentence caps for sections (Title Caps for page names), so: Content Setting Patterns -> Content setting patterns
	27 <p>

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

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

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

	31 <a href="match_patterns.html">Match Pattern documentation</a>.</p>
	kathyw 2011/12/13 02:47:32 I like Mike's suggestion, but I'd tweak it a bit t I like Mike's suggestion, but I'd tweak it a bit to avoid passive voice and make the example a little clearer. Maybe: You can use patterns to specify the websites that each content setting affects. For example, 'http://*.youtube.com/' specifies youtube.com and all of its subdomains. The syntax for content setting patterns is the same as for <a href="match_patterns.html">match patterns</a>, with a few differences:
	32 <p>

	33 Note that there are some differences between patterns for content settings and
	kathyw 2011/12/13 02:47:32 No need for a separate paragraph, I think. The pre No need for a separate paragraph, I think. The previous paragraph made me think that content setting patterns were match patterns. I rewrote to make clearer that there are some differences.
	34 match patterns:

	35 <ul><li>For <code>http</code>,

	36 <code>https</code>, and <code>ftp</code> URLs the path has to be a wildcard
	kathyw 2011/12/13 02:47:32 URLs the -> URLs, the has to be -> must be (use " URLs the -> URLs, the has to be -> must be (use "must" whenever something's absolute -- it's clearer that way)
	37 (<code>/*</code>). For <code>file</code> URLs, the path has to be completely
	kathyw 2011/12/13 02:47:32 has to be -> must be has to be -> must be
	38 specified and is <strong>not</strong> allowed to contain wildcards.</li>
	kathyw 2011/12/13 02:47:32 is not allowed to -> <strong>must not</strong. is not allowed to -> <strong>must not</strong.
	39 <li>In contrast to match patterns, content setting patterns can specify a port

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

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

	42 </li>

	43 </ul>

	44 </p>

	45

	46 <h3 id="pattern-precedence">Pattern Precedence</h3>
	kathyw 2011/12/13 02:47:32 Pattern Precedence -> Pattern precedence Pattern Precedence -> Pattern precedence
	47 <p>

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

	49 the more specific pattern takes precedence.

	50 </p>

	51 <p>For example, the following patterns are ordered by precedence:
	kathyw 2011/12/13 02:47:32 Add </p> at the end Add </p> at the end
	52 <ul>
	kathyw 2011/12/13 02:47:32 Use a <ol> instead of <ul> here, since the order m Use a <ol> instead of <ul> here, since the order matters. (bullets imply that order is unimportant)
	53 <li><code>http://www.example.com/*</code></li>

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

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

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

	57 </ul>

	58 There are three ways in which one pattern can be more specific than another
	kathyw 2011/12/13 02:47:32 Add <p> tag; rewrite to be more precise and avoid Add <p> tag; rewrite to be more precise and avoid "There are". Maybe: <p> Three kinds of wildcards affect how specific a pattern is: </p>
	59 pattern:

	60 <ul>

	61 <li>Wildcards in the port (like <code>http://www.example.com:/</code>)</li>
	kathyw 2011/12/13 02:47:32 like -> for example, (in this and the following 2 like -> for example, (in this and the following 2 items)
	62 <li>Wildcards in the scheme (like <code>://www.example.com:123/</code>)</li>

	63 <li>Wildcards in the hostname (like

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

	65 </ul>

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

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

	68 hostname, scheme, port. That means that for example the list of URLs above is
	kathyw 2011/12/13 02:47:32 That means that for example -> For example, "the That means that for example -> For example, "the list of URLs above..." is imprecise -- I didn't know whether you means the first list in the section or the second. Change the rest of the paragraph to be more precise. Maybe: For example, the following URLs are ordered by precedence: <ol> <li> http://www.example.com:/ <br> Specifies the hostname and scheme </li> <li> :/www.example.com:123/ <br> Not as high, because although it specifies the hostname, it doesn't specify the scheme </li> <li> http://.example.com:123/ <br> Lower because although it specifies the port and scheme, it has a wildcard in the hostname </li>
	69 ordered by precedence (the first pattern is more specific in the scheme than the

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

	71 one).

	72 </p>

	73

	74 <h2 id="primary-secondary">Primary and Secondary Patterns</h2>
	kathyw 2011/12/13 02:47:32 Primary and Secondary Patterns -> Primary and seco Primary and Secondary Patterns -> Primary and secondary patterns
	75 <p>

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

	77 on the content type. For example, for

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

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

	80 <p>

	81 Some content types also can take additional URLs into account. For example,
	kathyw 2011/12/13 02:47:32 delete "also" (redundant") delete "also" (redundant")
	82 whether a site is allowed to set a

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

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

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

	86 </p>

	87 <p>

	88 If there are multiple rules with primary and secondary patterns, the rule with
	kathyw 2011/12/13 02:47:32 Rewrite to avoid "there are" and be clearer. Maybe Rewrite to avoid "there are" and be clearer. Maybe: If there are multiple rules with -> If multiple rules have
	89 the more specific primary pattern takes precedence. If there are multiple rules
	kathyw 2011/12/13 02:47:32 If there are multiple rules with -> If multiple r If there are multiple rules with -> If multiple rules have
	90 with the same primary pattern, the rule with the more specific secondary pattern

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

	92 pairs is ordered by precedence:
	kathyw 2011/12/13 02:47:32 Add </p> at the end of this paragraph. Add </p> at the end of this paragraph.
	93 <table>
	kathyw 2011/12/13 02:47:32 Add a table header. Perhaps also add a column for Add a table header. Perhaps also add a column for the order, to match the <ol>s above and make the precedence crystal clear: <tr><th>Precedence</th><th>Primary pattern</th><th>Secondary pattern</th> <tr><td>1</td><td>...
	94 <tr>

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

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

	97 </tr><tr>

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

	99 <td><code><all_urls></code></td>

	100 </tr><tr>

	101 <td><code><all_urls></code>, </td>

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

	103 </tr><tr>

	104 <td><code><all_urls></code>, </td>

	105 <td><code><all_urls></code></td>

	106 </tr>

	107 </table>

	108 </p>

	109

	110 <h2 id="resource-identifiers">Resource Identifiers</h2>
	kathyw 2011/12/13 02:47:32 Resource Identifiers -> Resource identifiers Resource Identifiers -> Resource identifiers
	111 <p>

	112 Resource identifiers allow you to specify content settings for specific

	113 sub-types of a content type. Currently, the only content type that supports
	kathyw 2011/12/13 02:47:32 GLOBAL: sub-type -> subtype GLOBAL: sub-type -> subtype
	114 resource identifiers is <a href="#property-plugins"><code>plugins</code></a>,

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

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

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

	118 plug-ins are checked.

	119 </p>

	120 <p>

	121 For example, if there is a content setting rule with the resource identifier
	kathyw 2011/12/13 02:47:32 there is a content setting rule with the -> a cont there is a content setting rule with the -> a content setting rule has the
	122 <code>adobe-flash-player</code> and the pattern <code><all_urls></code>,

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

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

	125 </p>

	126 <p>

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

	128 <a href=""><code>getResourceIdentifiers</code></a> method. The returned list can
	kathyw 2011/12/13 02:47:32 Add "()" after method names. E.g.: <code>getResou Add "()" after method names. E.g.: <code>getResourceIdentifiers()</code> kathyw 2011/12/13 02:47:32 What should this link to? What should this link to?
	129 change with the set of installed plug-ins on the user's machine, but Chrome

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

	131 </p>

	132

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

	134
	kathyw 2011/12/13 02:47:32 It'd be nice to have a brief example of using the It'd be nice to have a brief example of using the content settings API here, in a <pre> section. and actually... I can't find any examples in the Samples page. I mean, there are 3 samples that use contentSettings, but no .js files are listed there.
	135 <p>

	136 You can find samples of this API on the

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

	138 </p>

	139

	140 <!-- END AUTHORED CONTENT -->

OLD	NEW