Hack 3. Master the include and exclude Directives

 < Day Day Up > 

Hack 3. Master the @include and @exclude Directives

Describing exactly where you want your user script to execute can be tricky.

As described in "Provide a Default Configuration" [Hack #2], Greasemonkey executes a user script based on @include and @exclude parameters: URLs with * wildcards that match any number of characters. This might seem like a simple syntax, but combining wildcards to match exactly the set of pages you want is trickier than you think.

1.4.1. Matching with or Without the www. Prefix

Here's a common scenario: a site is available at http://example.com and http://www.example.com. The site is the same in both cases, but neither URL redirects to the other. If you type example.com in the location bar, you get the site at http://example.com. If you visit www.example.com, you get exactly the same site, but the location bar reads http://www.example.com.

Let's say you want to write a user script that runs in both cases. Greasemonkey makes no assumptions about URLs that an end user might consider equivalent. If a site responds on both http://example.com and http://www.example.com, you need to declare both variations, as shown in this example:

 @include http://example.com/* @include http://www.example.com/* 

1.4.2. Matching All Subdomains of a Site

Here's a slightly more complicated scenario. Slashdot is a popular technical news and discussion site. It has a home page, which is available at both http://slashdot.org and http://www.slashdot.org. But it also has specialized subdomains, such as http://apache.slashdot.org/, http://apple.slashdot.org/, and so forth.

Say you want to write a user script that runs on all these sites. You can use a wildcard within the URL itself to match all the subdomains, like this:

 @include http://slashdot.org/* @include http://*.slashdot.org/* 

The first line matches when you visit http://slashdot.org. The second line matches when you visit http://www.slashdot.org (the * wildcard matches www). The second line also matches when you visit http://apache.slashdot.org/ or http://apple.slashdot.org/; the * wildcard matches apache and apple, respectively.

1.4.3. Matching Different Top-Level Domains of a Site

Now things get really tricky. Amazon is available in the United States at http://www.amazon.com. (Because http://amazon.com visibly redirects you to http://www.amazon.com, we won't need to worry about matching both.) But Amazon also has country-specific sites, such as http://www.amazon.co.uk/ in England, http://www.amazon.co.jp/ in Japan, and so forth.

If you want to write a user script that runs on all of Amazon's country-specific sites, there is a special type of wildcard, .tld, that matches all the top-level domains, as shown in the following example:

 @include http://www.amazon.tld/* 

This special syntax matches any top-level domain: .com, .org, .net, or a country-specific domain, such as .co.uk or .co.jp. Greasemonkey keeps a list of all the registered top-level domains in the world and expands the .tld wildcard to include each of them.

You can find out more about the available top-level domains at http://www.icann.org/tlds/.


1.4.4. Deciding Between * and http://*

One final note, before we put the @include and @exclude issue to bed. If you're writing a user script that applies to all pages, there are two subtly different ways to do that. Here's the first way:

 @include * 

This means that the user script should execute absolutely everywhere. If you visit a web site, the script will execute. If you visit a secure site (one with an https:// address), the script will execute. If you open an HTML file from your local hard drive, the script will execute. If you open a blank new window, the script will execute (since technically the "location" of a blank window is about:blank).

This might not be what you want. If you want the script to execute only on actual remote web pages "out there" on the Internet, you should specify the @include line differently, like this:

 @include http://* 

This means that the user script will execute only on remote web sites, whose address starts with http://. This will not include secure web sites, such as your bank's online bill payment site, because that address starts with https://. If you want the script to run on both secure and standard web sites, you'll need to explicitly specify both, like so:

 @include http://* @include https://* 

     < Day Day Up > 


    Greasemonkey Hacks
    Greasemonkey Hacks: Tips & Tools for Remixing the Web with Firefox
    ISBN: 0596101651
    EAN: 2147483647
    Year: 2005
    Pages: 168
    Authors: Mark Pilgrim

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net