| <h1>Match Patterns</h1> |
| |
| <p> |
| <a href="declare_permissions#host-permissions">Host |
| permissions</a> |
| {{^is_apps}} |
| and <a href="content_scripts">content script</a> |
| {{/is_apps}} |
| matching {{^is_apps}}are{{:}}is{{/is_apps}} based on a set of URLs defined by |
| <dfn>match patterns</dfn>. A match pattern is essentially a |
| URL that begins with a permitted scheme (<code>http</code>, |
| <code>https</code>, <code>file</code>, <code>ftp</code>, or |
| <code>chrome-extension</code>), |
| and that can contain '<code>*</code>' characters. |
| The special pattern |
| <code><all_urls></code> matches any URL |
| that starts with a permitted scheme. |
| Each match pattern has 3 parts:</p> |
| </p> |
| |
| <ul> |
| <li> <em>scheme</em> — |
| for example, <code>http</code> or <code>file</code> |
| or <code>*</code> |
| <p class="note"> |
| <b>Note:</b> |
| Access to <code>file</code> URLs isn't automatic. |
| The user must visit the extensions management page |
| and opt in to <code>file</code> access for each extension that requests it. |
| </p> |
| </li> |
| <li> <em>host</em> — |
| for example, <code>www.google.com</code> |
| or <code>*.google.com</code> |
| or <code>*</code>; |
| if the scheme is <code>file</code>, |
| there is no <em>host</em> part |
| </li> |
| <li> <em>path</em> — |
| for example, <code>/*</code>, <code>/foo*</code>, |
| or <code>/foo/bar</code>. The path must be present in a |
| host permission, but is always treated |
| as <code>/*</code>. |
| </li> |
| </ul> |
| |
| <p>Here's the basic syntax:</p> |
| |
| <pre> |
| <em><url-pattern></em> := <em><scheme></em>://<em><host></em><em><path></em> |
| <em><scheme></em> := '*' | 'http' | 'https' | 'file' | 'ftp' | 'chrome-extension' |
| <em><host></em> := '*' | '*.' <em><any char except '/' and '*'></em>+ |
| <em><path></em> := '/' <em><any chars></em> |
| </pre> |
| |
| <p> |
| The meaning of '<code>*</code>' depends on whether |
| it's in the <em>scheme</em>, <em>host</em>, or <em>path</em> part. |
| If the <em>scheme</em> is <code>*</code>, |
| then it matches either <code>http</code> or <code>https</code>, |
| and <strong>not</strong> <code>file</code>, <code>ftp</code>, |
| or <code>chrome-extension</code>. |
| If the <em>host</em> is just <code>*</code>, |
| then it matches any host. |
| If the <em>host</em> is <code>*.<em>hostname</em></code>, |
| then it matches the specified host or any of its subdomains. |
| In the <em>path</em> section, |
| each '<code>*</code>' matches 0 or more characters. |
| The following table shows some valid patterns. |
| </p> |
| |
| <table class="simple"> |
| <tbody> |
| <tr> |
| <th style="margin-left:0; padding-left:0">Pattern</th> |
| <th style="margin-left:0; padding-left:0">What it does</th> |
| <th style="margin-left:0; padding-left:0">Examples of matching URLs</th> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>http://*/*</code> |
| </td> |
| |
| <td>Matches any URL that uses the <code>http</code> scheme</td> |
| |
| <td> |
| http://www.google.com/<br> |
| http://example.org/foo/bar.html |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>http://*/foo*</code> |
| </td> |
| |
| <td> |
| Matches any URL that uses the <code>http</code> scheme, on any host, |
| as long as the path starts with <code>/foo</code> |
| </td> |
| |
| <td> |
| http://example.com/foo/bar.html<br> |
| http://www.google.com/foo<b></b> |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>https://*.google.com/foo*bar </code> |
| </td> |
| |
| <td> |
| Matches any URL that uses the <code>https</code> scheme, |
| is on a google.com host |
| (such as www.google.com, docs.google.com, or google.com), |
| as long as the path starts with <code>/foo</code> |
| and ends with <code>bar</code> |
| </td> |
| |
| <td> |
| http://www.google.com/foo/baz/bar<br> |
| http://docs.google.com/foobar |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>http://example.org/foo/bar.html </code> |
| </td> |
| |
| <td>Matches the specified URL</td> |
| |
| <td> |
| http://example.org/foo/bar.html |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>file:///foo*</code> |
| </td> |
| |
| <td>Matches any local file whose path starts with <code>/foo</code> |
| </td> |
| |
| <td> |
| file:///foo/bar.html<br> |
| file:///foo |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>http://127.0.0.1/*</code> |
| </td> |
| |
| <td> |
| Matches any URL that uses the <code>http</code> scheme |
| and is on the host 127.0.0.1 |
| </td> |
| <td> |
| http://127.0.0.1/<br> |
| http://127.0.0.1/foo/bar.html |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>*://mail.google.com/* </code> |
| </td> |
| |
| <td> |
| Matches any URL that starts with |
| <code>http://mail.google.com</code> or |
| <code>https://mail.google.com</code>. |
| </td> |
| |
| <td> |
| http://mail.google.com/foo/baz/bar<br> |
| https://mail.google.com/foobar |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code>chrome-extension://*/* </code> |
| </td> |
| |
| <td> |
| Matches any URL pointing to an extension (the first <code>*</code> |
| represents a filter for extension IDs, the second for paths). |
| </td> |
| |
| <td> |
| chrome-extension://askla...asdf/options.html |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <code><all_urls></code> |
| </td> |
| |
| <td> |
| Matches any URL that uses a permitted scheme. |
| (See the beginning of this section for the list of permitted |
| schemes.) |
| </td> |
| <td> |
| http://example.org/foo/bar.html<br> |
| file:///bar/baz.html |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p> |
| Here are some examples of <em>invalid</em> pattern matches: |
| </p> |
| |
| <table class="simple"> |
| <tbody> |
| <tr> |
| <th style="margin-left:0; padding-left:0">Bad pattern</th> |
| <th style="margin-left:0; padding-left:0">Why it's bad</th> |
| </tr> |
| |
| <tr> |
| <td><code>http://www.google.com</code></td> |
| <td>No <em>path</em></td> |
| </tr> |
| |
| <tr> |
| <td><code>http://*foo/bar</code></td> |
| <td>'*' in the <em>host</em> can be followed only by a '.' or '/'</td> |
| </tr> |
| |
| <tr> |
| <td><code>http://foo.*.bar/baz </code></td> |
| <td>If '*' is in the <em>host</em>, it must be the first character</td> |
| </tr> |
| |
| <tr> |
| <td><code>http:/bar</code></td> |
| <td>Missing <em>scheme</em> separator ("/" should be "//")</td> |
| </tr> |
| |
| <tr> |
| <td><code>foo://*</code></td> |
| <td>Invalid <em>scheme</em></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p> |
| Some schemes are not supported in all contexts. |
| </p> |