1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 2 1) The <head> information in this page is significant, should be uniform 3 across api docs and should be edited only with knowledge of the 4 templating mechanism. 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 6 browser, it will be re-generated from the template, json schema and 7 authored overview content. 8 4) The <body>.innerHTML is also generated by an offline step so that this 9 page may easily be indexed by search engines. 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 14 <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> 15 </script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script> 19 <title>Match Patterns - Google Chrome Extensions - Google Code</title></head> 20 <body> <div id="gc-container" class="labs"> 21 <div id="devModeWarning"> 22 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. 23 </div> 24 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 25 <!-- In particular, sub-templates that recurse, must be used by allowing 26 jstemplate to make a copy of the template in this section which 27 are not operated on by way of the jsskip="true" --> 28 <div style="display:none"> 29 30 <!-- VALUE --> 31 <div id="valueTemplate"> 32 <dt> 33 <var>paramName</var> 34 <em> 35 36 <!-- TYPE --> 37 <div style="display:inline"> 38 ( 39 <span class="optional">optional</span> 40 <span class="enum">enumerated</span> 41 <span id="typeTemplate"> 42 <span> 43 <a> Type</a> 44 </span> 45 <span> 46 <span> 47 array of <span><span></span></span> 48 </span> 49 <span>paramType</span> 50 <span></span> 51 </span> 52 </span> 53 ) 54 </div> 55 56 </em> 57 </dt> 58 <dd class="todo"> 59 Undocumented. 60 </dd> 61 <dd> 62 Description of this parameter from the json schema. 63 </dd> 64 <dd> 65 This parameter was added in version 66 <b><span></span></b>. 67 You must omit this parameter in earlier versions, 68 and you may omit it in any version. If you require this 69 parameter, the manifest key 70 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 71 can ensure that your extension won't be run in an earlier browser version. 72 </dd> 73 74 <!-- OBJECT PROPERTIES --> 75 <dd> 76 <dl> 77 <div> 78 <div> 79 </div> 80 </div> 81 </dl> 82 </dd> 83 84 <!-- OBJECT METHODS --> 85 <dd> 86 <div></div> 87 </dd> 88 89 <!-- OBJECT EVENT FIELDS --> 90 <dd> 91 <div></div> 92 </dd> 93 94 <!-- FUNCTION PARAMETERS --> 95 <dd> 96 <div></div> 97 </dd> 98 99 </div> <!-- /VALUE --> 100 101 <div id="functionParametersTemplate"> 102 <h5>Parameters</h5> 103 <dl> 104 <div> 105 <div> 106 </div> 107 </div> 108 </dl> 109 </div> 110 </div> <!-- /SUBTEMPLATES --> 111 112 <a id="top"></a> 113 <div id="skipto"> 114 <a href="#gc-pagecontent">Skip to page content</a> 115 <a href="#gc-toc">Skip to main navigation</a> 116 </div> 117 <!-- API HEADER --> 118 <table id="header" width="100%" cellspacing="0" border="0"> 119 <tbody><tr> 120 <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> 121 <td valign="middle" width="100%" style="padding-left:0.6em;"> 122 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 123 <div id="gsc-search-box"> 124 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 125 <input type="hidden" name="ie" value="UTF-8"> 126 <input type="text" name="q" value="" size="55"> 127 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 128 <br> 129 <span class="greytext">e.g. "page action" or "tabs"</span> 130 </div> 131 </form> 132 133 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 134 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 135 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 136 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 137 </td> 138 </tr> 139 </tbody></table> 140 141 <div id="codesiteContent" class=""> 142 143 <a id="gc-topnav-anchor"></a> 144 <div id="gc-topnav"> 145 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 146 <ul id="home" class="gc-topnav-tabs"> 147 <li id="home_link"> 148 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 149 </li> 150 <li id="docs_link"> 151 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 152 </li> 153 <li id="faq_link"> 154 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 155 </li> 156 <li id="samples_link"> 157 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 158 </li> 159 <li id="group_link"> 160 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 161 </li> 162 </ul> 163 </div> <!-- end gc-topnav --> 164 165 <div class="g-section g-tpl-170"> 166 <!-- SIDENAV --> 167 <div class="g-unit g-first" id="gc-toc"> 168 <ul> 169 <li><a href="getstarted.html">Getting Started</a></li> 170 <li><a href="overview.html">Overview</a></li> 171 <li><a href="whats_new.html">What's New?</a></li> 172 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 173 <ul> 174 <li>Browser UI 175 <ul> 176 <li><a href="browserAction.html">Browser Actions</a></li> 177 <li><a href="contextMenus.html">Context Menus</a></li> 178 <li><a href="notifications.html">Desktop Notifications</a></li> 179 <li><a href="omnibox.html">Omnibox</a></li> 180 <li><a href="options.html">Options Pages</a></li> 181 <li><a href="override.html">Override Pages</a></li> 182 <li><a href="pageAction.html">Page Actions</a></li> 183 </ul> 184 </li> 185 <li>Browser Interaction 186 <ul> 187 <li><a href="bookmarks.html">Bookmarks</a></li> 188 <li><a href="cookies.html">Cookies</a></li> 189 <li><a href="events.html">Events</a></li> 190 <li><a href="history.html">History</a></li> 191 <li><a href="management.html">Management</a></li> 192 <li><a href="tabs.html">Tabs</a></li> 193 <li><a href="windows.html">Windows</a></li> 194 </ul> 195 </li> 196 <li>Implementation 197 <ul> 198 <li><a href="a11y.html">Accessibility</a></li> 199 <li><a href="background_pages.html">Background Pages</a></li> 200 <li><a href="content_scripts.html">Content Scripts</a></li> 201 <li><a href="xhr.html">Cross-Origin XHR</a></li> 202 <li><a href="idle.html">Idle</a></li> 203 <li><a href="i18n.html">Internationalization</a></li> 204 <li><a href="messaging.html">Message Passing</a></li> 205 <li><a href="npapi.html">NPAPI Plugins</a></li> 206 </ul> 207 </li> 208 <li>Finishing 209 <ul> 210 <li><a href="hosting.html">Hosting</a></li> 211 <li><a href="external_extensions.html">Other Deployment Options</a></li> 212 </ul> 213 </li> 214 </ul> 215 </li> 216 <li><h2><a href="apps.html">Packaged Apps</a></h2></li> 217 <li><h2><a href="tutorials.html">Tutorials</a></h2> 218 <ul> 219 <li><a href="tut_debugging.html">Debugging</a></li> 220 <li><a href="tut_analytics.html">Google Analytics</a></li> 221 <li><a href="tut_oauth.html">OAuth</a></li> 222 </ul> 223 </li> 224 <li><h2>Reference</h2> 225 <ul> 226 <li>Formats 227 <ul> 228 <li><a href="manifest.html">Manifest Files</a></li> 229 <li class="leftNavSelected">Match Patterns</li> 230 </ul> 231 </li> 232 <li><a href="permission_warnings.html">Permission Warnings</a></li> 233 <li><a href="api_index.html">chrome.* APIs</a></li> 234 <li><a href="api_other.html">Other APIs</a></li> 235 </ul> 236 </li> 237 <li><h2><a href="samples.html">Samples</a></h2></li> 238 <div class="line"> </div> 239 <li><h2>More</h2> 240 <ul> 241 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 242 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> 243 <li><a href="themes.html">Themes</a></li> 244 </ul> 245 </li> 246 </ul> 247 </div> 248 <script> 249 initToggles(); 250 </script> 251 252 <div class="g-unit" id="gc-pagecontent"> 253 <div id="pageTitle"> 254 <h1 class="page_title">Match Patterns</h1> 255 </div> 256 <!-- TABLE OF CONTENTS --> 257 <div id="toc" style="display: none; "> 258 <h2>Contents</h2> 259 <ol> 260 <li> 261 <a>h2Name</a> 262 <ol> 263 <li> 264 <a>h3Name</a> 265 </li> 266 </ol> 267 </li> 268 <li> 269 <a href="#apiReference">API reference</a> 270 <ol> 271 <li> 272 <a href="#properties">Properties</a> 273 <ol> 274 <li> 275 <a href="#property-anchor">propertyName</a> 276 </li> 277 </ol> 278 </li> 279 <li> 280 <a>Methods</a> 281 <ol> 282 <li> 283 <a href="#method-anchor">methodName</a> 284 </li> 285 </ol> 286 </li> 287 <li> 288 <a>Events</a> 289 <ol> 290 <li> 291 <a href="#event-anchor">eventName</a> 292 </li> 293 </ol> 294 </li> 295 <li> 296 <a href="#types">Types</a> 297 <ol> 298 <li> 299 <a href="#id-anchor">id</a> 300 </li> 301 </ol> 302 </li> 303 </ol> 304 </li> 305 </ol> 306 </div> 307 <!-- /TABLE OF CONTENTS --> 308 309 <!-- Standard content lead-in for experimental API pages --> 310 <p id="classSummary" style="display: none; "> 311 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 312 </p> 313 314 <!-- STATIC CONTENT PLACEHOLDER --> 315 <div id="static"><div id="pageData-name" class="pageData">Match Patterns</div> 316 317 <p> 318 <a href="content_scripts.html">Content scripts</a> operate on 319 a set of URLs defined by match patterns. 320 You can put one or more match patterns 321 in the <code>"matches"</code> part of 322 a content script's section of the manifest. 323 This page describes the match pattern syntax 324 the rules you need to follow when you specify 325 which URLs your content script affects. 326 </p> 327 328 <p> 329 A match pattern is essentially a URL 330 that begins with a permitted scheme (<code>http</code>, 331 <code>https</code>, <code>file</code>, or <code>ftp</code>), 332 and that can contain '<code>*</code>' characters. 333 The special pattern 334 <code><all_urls></code> matches any URL 335 that starts with a permitted scheme. 336 Each match pattern has 3 parts:</p> 337 <p></p> 338 339 <ul> 340 <li> <em>scheme</em> 341 for example, <code>http</code> or <code>file</code> 342 or <code>*</code> 343 <p class="note"> 344 <b>Note:</b> 345 Access to <code>file</code> URLs isn't automatic. 346 The user must visit the extensions management page 347 and opt in to <code>file</code> access for each extension that requests it. 348 </p> 349 </li> 350 <li> <em>host</em> 351 for example, <code>www.google.com</code> 352 or <code>*.google.com</code> 353 or <code>*</code>; 354 if the scheme is <code>file</code>, 355 there is no <em>host</em> part 356 </li> 357 <li> <em>path</em> 358 for example, <code>/*</code>, <code>/foo* </code>, 359 or <code>/foo/bar </code> 360 </li> 361 </ul> 362 363 <p>Here's the basic syntax:</p> 364 365 <pre><em><url-pattern></em> := <em><scheme></em>://<em><host></em><em><path></em> 366 <em><scheme></em> := '*' | 'http' | 'https' | 'file' | 'ftp' 367 <em><host></em> := '*' | '*.' <em><any char except '/' and '*'></em>+ 368 <em><path></em> := '/' <em><any chars></em> 369 </pre> 370 371 <p> 372 The meaning of '<code>*</code>' depends on whether 373 it's in the <em>scheme</em>, <em>host</em>, or <em>path</em> part. 374 If the <em>scheme</em> is <code>*</code>, 375 then it matches either <code>http</code> or <code>https</code>. 376 If the <em>host</em> is just <code>*</code>, 377 then it matches any host. 378 If the <em>host</em> is <code>*.<em>hostname</em></code>, 379 then it matches the specified host or any of its subdomains. 380 In the <em>path</em> section, 381 each '<code>*</code>' matches 0 or more characters. 382 The following table shows some valid patterns. 383 </p> 384 385 <table class="columns"> 386 <tbody> 387 <tr> 388 <th style="margin-left:0; padding-left:0">Pattern</th> 389 <th style="margin-left:0; padding-left:0">What it does</th> 390 <th style="margin-left:0; padding-left:0">Examples of matching URLs</th> 391 </tr> 392 393 <tr> 394 <td> 395 <code>http://*/*</code> 396 </td> 397 398 <td>Matches any URL that uses the <code>http</code> scheme</td> 399 400 <td> 401 http://www.google.com/<br> 402 http://example.org/foo/bar.html 403 </td> 404 </tr> 405 406 <tr> 407 <td> 408 <code>http://*/foo*</code> 409 </td> 410 411 <td> 412 Matches any URL that uses the <code>http</code> scheme, on any host, 413 as long as the path starts with <code>/foo</code> 414 </td> 415 416 <td> 417 http://example.com/foo/bar.html<br> 418 http://www.google.com/foo<b></b> 419 </td> 420 </tr> 421 422 <tr> 423 <td> 424 <code>https://*.google.com/foo*bar </code> 425 </td> 426 427 <td> 428 Matches any URL that uses the <code>https</code> scheme, 429 is on a google.com host 430 (such as www.google.com, docs.google.com, or google.com), 431 as long as the path starts with <code>/foo</code> 432 and ends with <code>bar</code> 433 </td> 434 435 <td> 436 http://www.google.com/foo/baz/bar<br> 437 http://docs.google.com/foobar 438 </td> 439 </tr> 440 441 <tr> 442 <td> 443 <code>http://example.org/foo/bar.html </code> 444 </td> 445 446 <td>Matches the specified URL</td> 447 448 <td> 449 http://example.org/foo/bar.html 450 </td> 451 </tr> 452 453 <tr> 454 <td> 455 <code>file:///foo*</code> 456 </td> 457 458 <td>Matches any local file whose path starts with <code>/foo</code> 459 </td> 460 461 <td> 462 file:///foo/bar.html<br> 463 file:///foo 464 </td> 465 </tr> 466 467 <tr> 468 <td> 469 <code>http://127.0.0.1/*</code> 470 </td> 471 472 <td> 473 Matches any URL that uses the <code>http</code> scheme 474 and is on the host 127.0.0.1 475 </td> 476 <td> 477 http://127.0.0.1/<br> 478 http://127.0.0.1/foo/bar.html 479 </td> 480 </tr> 481 482 <tr> 483 <td> 484 <code>*://mail.google.com/* </code> 485 </td> 486 487 <td> 488 Matches any URL that starts with 489 <code>http://mail.google.com</code> or 490 <code>https://mail.google.com</code>. 491 </td> 492 493 <td> 494 http://mail.google.com/foo/baz/bar<br> 495 https://mail.google.com/foobar 496 </td> 497 </tr> 498 499 <tr> 500 <td> 501 <code><all_urls></code> 502 </td> 503 504 <td> 505 Matches any URL that uses a permitted scheme. 506 (See the beginning of this section for the list of permitted 507 schemes.) 508 </td> 509 <td> 510 http://example.org/foo/bar.html<br> 511 file:///bar/baz.html 512 </td> 513 </tr> 514 </tbody> 515 </table> 516 517 <p> 518 Here are some examples of <em>invalid</em> pattern matches: 519 </p> 520 521 <table class="columns"> 522 <tbody> 523 <tr> 524 <th style="margin-left:0; padding-left:0">Bad pattern</th> 525 <th style="margin-left:0; padding-left:0">Why it's bad</th> 526 </tr> 527 528 <tr> 529 <td><code>http://www.google.com</code></td> 530 <td>No <em>path</em></td> 531 </tr> 532 533 <tr> 534 <td><code>http://*foo/bar</code></td> 535 <td>'*' in the <em>host</em> can be followed only by a '.' or '/'</td> 536 </tr> 537 538 <tr> 539 <td><code>http://foo.*.bar/baz ; </code></td> 540 <td>If '*' is in the <em>host</em>, it must be the first character</td> 541 </tr> 542 543 <tr> 544 <td><code>http:/bar</code></td> 545 <td>Missing <em>scheme</em> separator ("/" should be "//")</td> 546 </tr> 547 548 <tr> 549 <td><code>foo://*</code></td> 550 <td>Invalid <em>scheme</em></td> 551 </tr> 552 </tbody> 553 </table> 554 555 </div> 556 557 <!-- API PAGE --> 558 <div class="apiPage" style="display: none; "> 559 <a name="apiReference"></a> 560 <h2>API reference: chrome.apiname </h2> 561 562 <!-- PROPERTIES --> 563 <div class="apiGroup"> 564 <a name="properties"></a> 565 <h3 id="properties">Properties</h3> 566 567 <div> 568 <a></a> 569 <h4>getLastError</h4> 570 <div class="summary"> 571 <!-- Note: intentionally longer 80 columns --> 572 <span>chrome.extension</span><span>lastError</span> 573 </div> 574 <div> 575 </div> 576 </div> 577 578 </div> <!-- /apiGroup --> 579 580 <!-- METHODS --> 581 <div id="methodsTemplate" class="apiGroup"> 582 <a></a> 583 <h3>Methods</h3> 584 585 <!-- iterates over all functions --> 586 <div class="apiItem"> 587 <a></a> <!-- method-anchor --> 588 <h4>method name</h4> 589 590 <div class="summary"><span>void</span> 591 <!-- Note: intentionally longer 80 columns --> 592 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 593 <var><span></span></var></span>)</div> 594 595 <div class="description"> 596 <p class="todo">Undocumented.</p> 597 <p> 598 A description from the json schema def of the function goes here. 599 </p> 600 601 <!-- PARAMETERS --> 602 <h4>Parameters</h4> 603 <dl> 604 <div> 605 <div> 606 </div> 607 </div> 608 </dl> 609 610 <!-- RETURNS --> 611 <h4>Returns</h4> 612 <dl> 613 <div> 614 <div> 615 </div> 616 </div> 617 </dl> 618 619 <!-- CALLBACK --> 620 <div> 621 <div> 622 <h4>Callback function</h4> 623 <p> 624 The callback <em>parameter</em> should specify a function 625 that looks like this: 626 </p> 627 <p> 628 If you specify the <em>callback</em> parameter, it should 629 specify a function that looks like this: 630 </p> 631 632 <!-- Note: intentionally longer 80 columns --> 633 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 634 <dl> 635 <div> 636 <div> 637 </div> 638 </div> 639 </dl> 640 </div> 641 </div> 642 643 <!-- MIN_VERSION --> 644 <p> 645 This function was added in version <b><span></span></b>. 646 If you require this function, the manifest key 647 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 648 can ensure that your extension won't be run in an earlier browser version. 649 </p> 650 </div> <!-- /description --> 651 652 </div> <!-- /apiItem --> 653 654 </div> <!-- /apiGroup --> 655 656 <!-- EVENTS --> 657 <div id="eventsTemplate" class="apiGroup"> 658 <a></a> 659 <h3>Events</h3> 660 <!-- iterates over all events --> 661 <div class="apiItem"> 662 <a></a> 663 <h4>event name</h4> 664 665 <div class="summary"> 666 <!-- Note: intentionally longer 80 columns --> 667 <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); 668 </div> 669 670 <div class="description"> 671 <p class="todo">Undocumented.</p> 672 <p> 673 A description from the json schema def of the event goes here. 674 </p> 675 676 <!-- PARAMETERS --> 677 <div> 678 <h4>Parameters</h4> 679 <dl> 680 <div> 681 <div> 682 </div> 683 </div> 684 </dl> 685 </div> 686 </div> <!-- /decription --> 687 688 </div> <!-- /apiItem --> 689 690 </div> <!-- /apiGroup --> 691 692 <!-- TYPES --> 693 <div class="apiGroup"> 694 <a name="types"></a> 695 <h3 id="types">Types</h3> 696 697 <!-- iterates over all types --> 698 <div class="apiItem"> 699 <a></a> 700 <h4>type name</h4> 701 702 <div> 703 </div> 704 705 </div> <!-- /apiItem --> 706 707 </div> <!-- /apiGroup --> 708 709 </div> <!-- /apiPage --> 710 </div> <!-- /gc-pagecontent --> 711 </div> <!-- /g-section --> 712 </div> <!-- /codesiteContent --> 713 <div id="gc-footer" --=""> 714 <div class="text"> 715 <p> 716 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 717 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 718 Attribution 3.0 License</a>, and code samples are licensed under the 719 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 720 </p> 721 <p> 722 2011 Google 723 </p> 724 725 <!-- begin analytics --> 726 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 727 <script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 728 729 <script type="text/javascript"> 730 // chrome doc tracking 731 try { 732 var engdocs = _gat._getTracker("YT-10763712-2"); 733 engdocs._trackPageview(); 734 } catch(err) {} 735 736 // code.google.com site-wide tracking 737 try { 738 _uacct="UA-18071-1"; 739 _uanchor=1; 740 _uff=0; 741 urchinTracker(); 742 } 743 catch(e) {/* urchinTracker not available. */} 744 </script> 745 <!-- end analytics --> 746 </div> 747 </div> <!-- /gc-footer --> 748 </div> <!-- /gc-container --> 749 </body></html> 750
