Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Unstable
Test strings containing URLs against simple patterns.
Usage
Specifying Patterns
There are three ways you can specify patterns:
- as an exact match string
- using a wildcard in a string
- using a regular expression
Exact Matches
A URL matches only that URL. The URL must start with a scheme, end with a slash, and contain no wildcards.
| Example pattern | Example matching URLs | Example non-matching URLs |
|---|---|---|
"http://example.com/" |
http://example.com/ |
http://example.comhttp://example.com/foohttps://example.com/http://foo.example.com/ |
Wildcards
A single asterisk matches any URL with an http, https, or ftp scheme. For other schemes like file, resource, or data, use a scheme followed by an asterisk, as below.
| Example pattern | Example matching URLs | Example non-matching URLs |
|---|---|---|
"*" |
http://example.com/https://example.com/ftp://example.com/http://bar.com/foo.jshttp://foo.com/ |
file://example.jsresource://me/my-addon/data/file.htmldata:text/html,Hi there |
A domain name prefixed with an asterisk and dot matches any URL of that domain or a subdomain, using any of http, https, ftp.
| Example pattern | Example matching URLs | Example non-matching URLs |
|---|---|---|
"*.example.com" |
http://example.com/http://foo.example.com/https://example.com/http://example.com/fooftp://foo.example.com/ |
ldap://example.comhttp://example.foo.com/ |
A URL followed by an asterisk matches that URL and any URL prefixed with the pattern.
| Example pattern | Example matching URLs | Example non-matching URLs |
|---|---|---|
"https://foo.com/*" |
https://foo.com/https://foo.com/bar |
http://foo.com/https://foo.comhttps://bar.foo.com/ |
A scheme followed by an asterisk matches all URLs with that scheme. To match local files, use file://*, and to match files loaded from your add-on's data directory, use resource://.
| Example pattern | Example matching URLs |
|---|---|
"file://*" |
file://C:/file.htmlfile:///home/file.png |
"resource://*" |
resource://my-addon-at-me-dot-org/my-addon/data/file.html |
"data:*" |
data:text/html,Hi there |
Regular Expressions
You can specify patterns using a regular expression:
var { MatchPattern } = require("sdk/util/match-pattern");
var pattern = new MatchPattern(/.*example.*/);
The regular expression is subject to restrictions based on those applied to the HTML5 pattern attribute. In particular:
-
The pattern must match the entire value, not just any subset. For example, the pattern
/moz.*/will not match the URLhttp://mozilla.org. -
The expression is compiled with the
global,ignoreCase, andmultilineflags disabled. TheMatchPatternconstructor will throw an exception if you try to set any of these flags.
| Example pattern | Example matching URLs | Example non-matching URLs |
|---|---|---|
/.*moz.*/ |
http://foo.mozilla.org/http://mozilla.orghttps://mozilla.orghttp://foo.com/mozillahttp://hemozoon.orgmozscheme://foo.org |
http://foo.org |
/https:\/\/www\.moz.*/ |
https://www.mozilla.orghttps://www.mozzarella.com |
http://www.mozilla.orghttps://foo.mozilla.org/https://foo.com/moz |
/http.*moz.*/ |
http://foo.mozilla.org/http://mozilla.orghttp://hemozoon.org/https://anydomain.com/foomozbar/ |
ftp://http/mozilla.org |
/[^:/]+:\/\/[^/]*mozilla\.org\/.*/ |
ftp://foo.mozilla.org/http://www.mozilla.org/https://developer.mozilla.org/any |
ftp://http/mozilla.orghttp://anydomain.com/mozilla.org/ |
Examples
var { MatchPattern } = require("sdk/util/match-pattern");
var pattern = new MatchPattern("http://example.com/*");
console.log(pattern.test("http://example.com/")); // true
console.log(pattern.test("http://example.com/foo")); // true
console.log(pattern.test("http://foo.com/")); // false!
Globals
Constructors
MatchPattern(pattern)
This constructor creates match pattern objects that can be used to test URLs.
Parameters
pattern : string
The pattern to use. See Patterns above.
MatchPattern
Methods
test(url)
Tests a URL against the match pattern.
Parameters
url : string
The URL to test.
Returns
boolean : True if the URL matches the pattern and false otherwise.