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

   1 <h1>Match Patterns</h1>
   2
   3 <p>
   4 <a href="declare_permissions.html#host-permissions">Host
   5 permissions</a> and <a href="content_scripts.html">content
   6 script</a> matching are based on a set of URLs defined by
   7 <dfn>match patterns</dfn>.  A match pattern is essentially a
   8 URL that begins with a permitted scheme (<code>http</code>,
   9 <code>https</code>, <code>file</code>, <code>ftp</code>, or
  10 <code>chrome-extension</code>),
  11 and that can contain '<code>*</code>' characters.
  12 The special pattern
  13 <code>&lt;all_urls&gt;</code> matches any URL
  14 that starts with a permitted scheme.
  15 Each match pattern has 3 parts:</p>
  16 </p>
  17
  18 <ul>
  19   <li> <em>scheme</em> &mdash;
  20     for example, <code>http</code> or <code>file</code>
  21     or <code>*</code>
  22     <p class="note">
  23     <b>Note:</b>
  24     Access to <code>file</code> URLs isn't automatic.
  25     The user must visit the extensions management page
  26     and opt in to <code>file</code> access for each extension that requests it.
  27     </p>
  28   </li>
  29   <li> <em>host</em> &mdash;
  30     for example, <code>www.google.com</code>
  31     or <code>*.google.com</code>
  32     or <code>*</code>;
  33     if the scheme is <code>file</code>,
  34     there is no <em>host</em> part
  35   </li>
  36   <li> <em>path</em> &mdash;
  37     for example, <code>/*</code>, <code>/foo*</code>,
  38     or <code>/foo/bar</code>. The path must be present in a
  39     host permission, but is always treated
  40     as <code>/*</code>.
  41   </li>
  42 </ul>
  43
  44 <p>Here's the basic syntax:</p>
  45
  46 <pre>
  47 <em>&lt;url-pattern&gt;</em> := <em>&lt;scheme&gt;</em>://<em>&lt;host&gt;</em><em>&lt;path&gt;</em>
  48 <em>&lt;scheme&gt;</em> := '*' | 'http' | 'https' | 'file' | 'ftp' | 'chrome-extension'
  49 <em>&lt;host&gt;</em> := '*' | '*.' <em>&lt;any char except '/' and '*'&gt;</em>+
  50 <em>&lt;path&gt;</em> := '/' <em>&lt;any chars&gt;</em>
  51 </pre>
  52
  53 <p>
  54 The meaning of '<code>*</code>' depends on whether
  55 it's in the <em>scheme</em>, <em>host</em>, or <em>path</em> part.
  56 If the <em>scheme</em> is <code>*</code>,
  57 then it matches either <code>http</code> or <code>https</code>,
  58 and <strong>not</strong> <code>file</code>, <code>ftp</code>,
  59 or <code>chrome-extension</code>.
  60 If the <em>host</em> is just <code>*</code>,
  61 then it matches any host.
  62 If the <em>host</em> is <code>*.<em>hostname</em></code>,
  63 then it matches the specified host or any of its subdomains.
  64 In the <em>path</em> section,
  65 each '<code>*</code>' matches 0 or more characters.
  66 The following table shows some valid patterns.
  67 </p>
  68
  69 <table class="simple">
  70 <tbody>
  71 <tr>
  72   <th style="margin-left:0; padding-left:0">Pattern</th>
  73   <th style="margin-left:0; padding-left:0">What it does</th>
  74   <th style="margin-left:0; padding-left:0">Examples of matching URLs</th>
  75 </tr>
  76
  77 <tr>
  78   <td>
  79     <code>http://*/*</code>
  80   </td>
  81
  82   <td>Matches any URL that uses the <code>http</code> scheme</td>
  83
  84   <td>
  85     http://www.google.com/<br>
  86     http://example.org/foo/bar.html
  87   </td>
  88 </tr>
  89
  90 <tr>
  91   <td>
  92     <code>http://*/foo*</code>
  93   </td>
  94
  95   <td>
  96     Matches any URL that uses the <code>http</code> scheme, on any host,
  97     as long as the path starts with <code>/foo</code>
  98   </td>
  99
 100   <td>
 101     http://example.com/foo/bar.html<br>
 102     http://www.google.com/foo<b></b>
 103   </td>
 104 </tr>
 105
 106 <tr>
 107   <td>
 108     <code>https://*.google.com/foo*bar </code>
 109   </td>
 110
 111   <td>
 112     Matches any URL that uses the <code>https</code> scheme,
 113     is on a google.com host
 114     (such as www.google.com, docs.google.com, or google.com),
 115     as long as the path starts with <code>/foo</code>
 116     and ends with <code>bar</code>
 117   </td>
 118
 119   <td>
 120     http://www.google.com/foo/baz/bar<br>
 121     http://docs.google.com/foobar
 122   </td>
 123 </tr>
 124
 125 <tr>
 126   <td>
 127     <code>http://example.org/foo/bar.html </code>
 128   </td>
 129
 130   <td>Matches the specified URL</td>
 131
 132   <td>
 133     http://example.org/foo/bar.html
 134   </td>
 135 </tr>
 136
 137 <tr>
 138   <td>
 139     <code>file:///foo*</code>
 140   </td>
 141
 142   <td>Matches any local file whose path starts with <code>/foo</code>
 143   </td>
 144
 145   <td>
 146     file:///foo/bar.html<br>
 147     file:///foo
 148   </td>
 149 </tr>
 150
 151 <tr>
 152   <td>
 153     <code>http://127.0.0.1/*</code>
 154   </td>
 155
 156   <td>
 157     Matches any URL that uses the <code>http</code> scheme
 158     and is on the host 127.0.0.1
 159   </td>
 160   <td>
 161     http://127.0.0.1/<br>
 162     http://127.0.0.1/foo/bar.html
 163   </td>
 164 </tr>
 165
 166 <tr>
 167   <td>
 168     <code>*://mail.google.com/* </code>
 169   </td>
 170
 171   <td>
 172     Matches any URL that starts with
 173     <code>http://mail.google.com</code> or
 174     <code>https://mail.google.com</code>.
 175   </td>
 176
 177   <td>
 178     http://mail.google.com/foo/baz/bar<br>
 179     https://mail.google.com/foobar
 180   </td>
 181 </tr>
 182
 183 <tr>
 184   <td>
 185     <code>chrome-extension://*/* </code>
 186   </td>
 187
 188   <td>
 189     Matches any URL pointing to an extension (the first <code>*</code>
 190     represents a filter for extension IDs, the second for paths).
 191   </td>
 192
 193   <td>
 194     chrome-extension://askla...asdf/options.html
 195   </td>
 196 </tr>
 197
 198 <tr>
 199   <td>
 200     <code>&lt;all_urls&gt;</code>
 201   </td>
 202
 203   <td>
 204     Matches any URL that uses a permitted scheme.
 205     (See the beginning of this section for the list of permitted
 206     schemes.)
 207   </td>
 208   <td>
 209     http://example.org/foo/bar.html<br>
 210     file:///bar/baz.html
 211   </td>
 212 </tr>
 213 </tbody>
 214 </table>
 215
 216 <p>
 217 Here are some examples of <em>invalid</em> pattern matches:
 218 </p>
 219
 220 <table class="simple">
 221 <tbody>
 222 <tr>
 223   <th style="margin-left:0; padding-left:0">Bad pattern</th>
 224   <th style="margin-left:0; padding-left:0">Why it's bad</th>
 225 </tr>
 226
 227 <tr>
 228   <td><code>http://www.google.com</code></td>
 229   <td>No <em>path</em></td>
 230 </tr>
 231
 232 <tr>
 233   <td><code>http://*foo/bar</code></td>
 234   <td>'*' in the <em>host</em> can be followed only by a '.' or '/'</td>
 235 </tr>
 236
 237 <tr>
 238   <td><code>http://foo.*.bar/baz&nbsp; </code></td>
 239   <td>If '*' is in the <em>host</em>, it must be the first character</td>
 240   </tr>
 241
 242 <tr>
 243   <td><code>http:/bar</code></td>
 244   <td>Missing <em>scheme</em> separator ("/" should be "//")</td>
 245 </tr>
 246
 247 <tr>
 248   <td><code>foo://*</code></td>
 249   <td>Invalid <em>scheme</em></td>
 250 </tr>
 251 </tbody>
 252 </table>
 253
 254 <p>
 255 Some schemes are not supported in all contexts.
 256 </p>