Tampermonkey download file name and location change

Here’s how to install Butler from the context menu:

If all went well, Greasemonkey will display the following alert: “Success! Refresh page to see changes.”

Now, search for something in Google. In the search results page, there is a line at the top of the results that says “Try your search on: Yahoo, Ask Jeeves, AlltheWeb…” as shown in Figure 1-4. There is also a banner along the top that says “Enhanced by Butler.” All of these options were added by the Butler user script.

My Butler user script has a home page, but not all scripts do. Sometimes the author posts only the script itself. You can still install such scripts, even if there are no links to right-click.

Visit http://diveintomark.org/projects/butler/butler.user.js. You will see the Butler source code displayed in your browser. From the Tools menu, select Install User Script…. Greasemonkey will pop up the Install User Script dialog, and the rest of the installation is the same as described in the previous section.

Like most Firefox browser extensions, Greasemonkey stores its configuration files in your Firefox profile directory. You can install a user script manually by placing it in the right directory and editing the Greasemonkey configuration file with a text editor.

First you’ll need to find your Firefox profile directory, which is harder than it sounds. The following list, from Nigel MacFarlane’s excellent Firefox Hacks (O’Reilly), shows where to find this directory on your particular system:

Within your Firefox directory is your Profiles directory, and within that is a randomly named directory (for security reasons). Within that is a series of subdirectories: extensions/{e4a8a97b-f2ed-450b-b12d-ee082ba24781}/chrome/greasemonkey/content/scripts/. This final scripts directory contains all your installed user scripts, as well as a configuration file named config.xml. Here’s a sample config.xml file:

To install a new script, simply copy it to this scripts directory and add a entry like the other ones in config.xml. The element has five attributes: , and . Within the element you can have multiple and elements, as defined in “Provide a Default Configuration” [Hack #2].

For example, to manually install the Butler user script, copy the butler.user.js file into your scripts directory, and then add this XML snippet to config.xml, just before :

Provide a Default Configuration

Save the following user script as helloworld.user.js:

There are five separate pieces of metadata here, wrapped in a set of Greasemonkey-specific comments.

Let’s take them in order, starting with the wrapper:

These comments are significant and must match this pattern exactly. Greasemonkey uses them to signal the start and end of a user script’s metadata section. This section can be defined anywhere in your script, but it’s usually near the top.

Within the metadata section, the first item is the name:

This is the name of your user script. It is displayed in the install dialog when you first install the script and later in the Manage User Scripts dialog. It should be short and to the point.

is optional. If present, it can appear only once. If not present, it defaults to the filename of the user script, minus the .user.js extension.

Next comes the namespace:

This is a URL, which Greasemonkey uses to distinguish user scripts that have the same name but are written by different authors. If you have a domain name, you can use it (or a subdirectory) as your namespace. Otherwise, you can use a : URI.

is optional. If present, it can appear only once. If not present, it defaults to the domain from which the user downloaded the user script.

Next comes the description:

This is a human-readable description of what the user script does. It is displayed in the install dialog when you first install the script and later in the Manage User Scripts dialog. It should be no longer than two sentences.

is optional. If present, it can appear only once. If not present, it defaults to an empty string.

The next three lines are the most important items (from Greasemonkey’s perspective). The and directives give a series of URLs and wildcards that tell Greasemonkey where to run this user script:

The and directives share the same syntax. They can be a URL, a URL with the * character as a simple wildcard for part of the domain name or path, or simply the * wildcard character by itself. In this case, we are telling Greasemonkey to execute the Hello World script on all sites except http://oreilly.com and http://www.oreilly.com. Excludes take precedence over includes, so if you went to http://www.oreilly.com/catalog/, the user script would not run. The URL http://oreilly.com/catalog/ matches the * (all sites), but it would be excluded because it also matches http://oreilly.com/*.

and are optional. You can specify as many included and excluded URLs as you like, but you must specify each on its own line. If neither is specified, Greasemonkey will execute your user script on all sites (as if you had specified *).

Master the @include and @exclude Directives

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 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.comand http://www.example.com, you need to declare both variations, as shown in this example:

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, , that matches all the top-level domains, as shown in the following example:

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 wildcard to include each of them.

One final note, before we put the and 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:

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 line differently, like this:

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:

Prevent a User Script from Executing

The easiest way to disable a user script is in the Manage User Scripts dialog. Assuming you installed the Butler user script [Hack #1], you can disable it with just a few clicks:

Now, Butler is installed, but inactive. You can verify this by searching for something on Google. It should no longer say “Enhanced by Butler” along the top. You can reenable the Butler user script by repeating the procedure and reselecting the Enabled checkbox in the Manage User Scripts dialog.

While Greasemonkey is installed, it displays a little smiling monkey icon in the status bar, as shown in Figure 1-5.

Clicking the Greasemonkey icon in the status bar disables Greasemonkey entirely; any user scripts you have installed will no longer execute. The Greasemonkey icon will frown and turn gray to indicate that Greasemonkey is currently disabled, as shown in Figure 1-6.

Clicking the icon again reenables Greasemonkey and any enabled user scripts.

As shown in “Master the @include and @exclude Directives” [Hack #3], user scripts contain two sections: a list of pages to run the script and a list of pages not to run the script. Another way to prevent a user script from executing is to remove all the pages on which it runs:

Yet another way to disable a user script is to add a wildcard to exclude it from all pages:

Now, Butler is still installed and technically still active. But because excluded pages take precedence over included pages, Butler will never actually be executed, because you have told Greasemonkey to exclude it from all pages.

As shown in “Install a User Script” [Hack #1], Greasemonkey stores the list of installed scripts in a configuration file, config.xml, deep within your Firefox profile directory:

You can manually edit this file to disable a user script. To disable Butler, find its element in config.xml, and then set the attribute to .

Finally, you can remove a user script entirely by uninstalling it:

Butler is now uninstalled completely.

As described in “Provide a Default Configuration” [Hack #2], user scripts contain a section that describes what the script is and where it should run. Editing the and lines in this section is the first and easiest way to configure a user script, because the configuration travels with the script code. If you copy the file to someone else’s computer or publish it online, other people will pick up the default configuration.

Another good time to alter a script’s metadata is during installation. Remember in “Install a User Script” [Hack #1] when you first installed the Butler user script? Immediately after you select the Install User Script…menu item, Greasemonkey displays a dialog box titled Install User Script, which contains lists of the included and excluded pages, as shown in Figure 1-7.

The two lists are populated with the defaults that are defined in the script’s metadata section (specifically, the and lines), but you can change them to anything you like before you install the script. Let’s say, for example, that you like Butler, but you have no use for it on Froogle, Google’s cleverly named product comparison site. Before you install the script, you can modify the configuration to exclude that site but still let the script work on other Google sites.

To ensure that Butler doesn’t alter Froogle, click the Add…button under “Excluded pages” and type the wildcard URL for Froogle, as shown in Figure 1-8.

You can also reconfigure a script’s included and excluded pages after the script is installed. Assuming you previously excluded Froogle from Butler’s configuration (as described in the previous section), let’s now change the configuration to include Froogle again:

Now, search for a product on Froogle to verify that Butler is once again being executed.

The last way to reconfigure a user script is to manually edit the config.xml file, which is located within your Firefox profile directory. (See “Install a User Script” [Hack #1] for the location.) The graphical dialogs Greasemonkey provides are just friendly ways of editing config.xml without knowing it.

Each installed user script is represented by a element, as shown in the following example:

You can make any changes you like to the config.xml file. You can add, remove, or edit the and elements to change where the script runs. You can change the enabled attribute to to disable the script. You can even uninstall the script by deleting the entire element.

Add or Remove Content on a Page

The following code adds a new element to the end of the page. The element will appear at the bottom of the page, unless you style it with CSS to position it somewhere else [Hack #7]:

You can also remove elements from a page. Removed elements disappear from the page (obviously), and any content after them collapses to fill the space the elements occupied. The following code finds the element with and removes it:

Many user scripts insert content into a page, rather than appending it to the end of the page. The following code creates a link to http://www.example.com and inserts it immediately before the element with :

You can also insert content after an existing element, by using the property:

You can replace entire chunks of a page in one shot by using the method. The following code replaces the element with with content that we create on the fly:

As you can see from the previous few examples, the process of creating new content can be arduous. Create an element, append some text, set individual attributes…bah. There is an easier way. It’s not a W3C-approved DOM property, but all major browsers support the property for getting or setting HTML content as a string. The following code accomplishes the same thing as the previous example:

The HTML you set with the property can be as complex as you like. Firefox will parse it and insert it into the DOM tree, just as if you had created each element and inserted it with standard DOM methods.

Modifying a single attribute is simple. Each element is an object in JavaScript, and each attribute is reflected by a corresponding property. The following code finds the link with and changes its property to link to a different URL:

You can accomplish the same thing with the method:

This is occasionally useful, if you are setting an attribute whose name you don’t know in advance.

You can also remove an attribute entirely with the method:

If you remove the attribute from a link, it will still be an element, but it will cease to be a link. If the link has an or attribute, it will still be a page anchor, but you will no longer be able to click it to follow the link.

Here is a simple function that I reuse in most cases in which I need to add arbitrary styles to a page. It takes a single parameter, a string containing any number of CSS rules:

As you see in the previous example, Firefox maintains a list of the stylesheets in use on the page, in (note the capitalization!). Each item in this collection is an object, representing a single stylesheet. Each stylesheet object has a collection of rules, and methods to add new rules or remove existing rules.

The method takes two parameters. The first is the CSS rule to insert, and the second is the positional index of the rule before which to insert the new rule:

You can also delete individual rules by using the method. It takes a single parameter, the positional index of the rule to remove. The following code will remove the first rule, which we just inserted with :

You can also modify the style of a single element by setting properties on the element’s attribute. The following code finds the element with and sets its background color to :

There is no easy way to set multiple properties at once. In regular JavaScript, you can set multiple styles by calling the method to the attribute to a string:

However, as explained in “Avoid Common Pitfalls” [Hack #12], this does not work within Greasemonkey scripts.

To execute an XPath query, use the function. Here’s the basic syntax:

The function takes five parameters:

The function returns a snapshot, which is a static array of DOM nodes. You can iterate through the snapshot or access its items in any order. The snapshot is static, which means it will never change, no matter what you do to the page. You can even delete DOM nodes as you move through the snapshot.

A snapshot is not an array, and it doesn’t support the standard array properties or accessors. To get the number of items in the snapshot, use . To access a particular item, you need to call . Here is the skeleton of a script that executes an XPath query and loops through the results:

The following XPath query finds all the elements on a page with :

The // means “search for things anywhere below the root node, including nested elements.” The * matches any element, and restricts the search to elements with a class of .

You can use XPath to search for specific elements. The following query finds all elements. (This example is taken from “Show Hidden Form Fields” [Hack #30].)

You can also test for the presence of an attribute, regardless of its value. The following query finds all elements with an attribute. (This example is taken from “Add an Access Bar with Keyboard Shortcuts” [Hack #68].)

Not impressed yet? Here’s a query that finds images whose URL contains the string "“. (This example is taken from “Make Amazon Product Images Larger” [Hack #25].)

You can also do combinations of attributes. This query finds all images with a width of 36 and a height of 14. (This query is taken from “Zap Ugly XML Buttons” [Hack #86].)

But wait, there’s more! By using more advanced XPath syntax, you can actually find elements that are contained within other elements. This code finds all the links that are contained in a paragraph whose class is . (This example is taken from “Refine Your Google Search” [Hack #96].)

Finally, you can find a specific element by passing in the third parameter. This line of code finds the first link whose class is "“. (This example is taken from “Prefetch Yahoo! Search Results” [Hack #52].)

If you weren’t brain-fried by now, I’d be very surprised. XPath is, quite literally, a language all its own. Like regular expressions, XPath can make your life easier, or it can make your life a living hell. Remember, you can always get what you need (eventually) with standard DOM functions such as or . XPath’s a good tool to have in your tool chest, but it’s not always the right tool for the job.

Develop a User Script “Live”

Before you can take advantage of live editing, you need to set up file associations on your system, so that double-clicking a .user.js script opens the file in your text editor instead of trying to execute it or viewing it in a web browser.

Switch back to Firefox and select Tools → Manage User Scripts. Select a script from the pane on the left and click Edit. If your file associations are set up correctly, this should open the user script in your text editor.

The first time you do this on Windows, you will get a warning message, explaining that you need to set up your file associations, as shown in Figure 1-9. You’re one step ahead of the game, since you’ve already done this.

Once the user script opens in your text editor, you can make any changes you like to the code. You’re editing the copy of the user script within your Firefox profile directory—the copy that Greasemonkey uses. As soon as you make a change and save it, you can switch back to Firefox and refresh your test page to see the effect of your change. Switch to your editor, make another change, switch back to Firefox, and refresh. It’s that simple.

When you’re satisfied with your user script, switch back to your editor one last time and save a copy to another directory.

If your user script doesn’t appear to be running properly, the first place to check is JavaScript Console, which lists all script-related errors, including those specific to user scripts. Select Tools → JavaScript Console to open the JavaScript Console window. You will probably see a long list of all the script errors on all the pages you’ve visited since you opened Firefox. (You’d be surprised how many high-profile sites have scripts that crash regularly.)

In the JavaScript Console window, click Clear to remove the old errors from the list. Now, refresh the page you’re using to test your user script. If your user script is crashing or otherwise misbehaving, you will see the exception displayed in JavaScript Console.

If you don’t see any errors printed in JavaScript Console, you might have a configuration problem. Go to Tools → Manage User Scripts and double-check that your script is installed and enabled and that your current test page is listed in the Included Pages list.

OK, so your script is definitely running, but it isn’t working properly. What next? You can litter your script with alert calls, but that’s annoying. Instead, Greasemonkey provides a logging function, , that allows you to write messages to JavaScript Console. Such messages should be taken out before release, but they are enormously helpful in debugging. Plus, watching the console pile up with log messages is much more satisfying than clicking OK over and over to dismiss multiple alerts.

takes one argument, the string to be logged. After logging to JavaScript Console, the user script will continue executing normally.

Save the following user script as testlog.user.js:

If you install this user script and visit http://www.oreilly.com, these two lines will appear in JavaScript Console:

Greasemonkey dumps the namespace and script name, taken from the user script’s metadata section, then the message that was passed as an argument to .

If you visit somewhere other than http://www.oreilly.com, these two lines will appear in JavaScript Console:

Messages logged in Javascript Console are not limited to 255 characters. Plus, lines in JavaScript Console wrap properly, so you can always scroll down to see the rest of your log message. Go nuts with logging!

DOM Inspector allows you to explore the parsed Document Object Model (DOM) of any page. You can get details on each HTML element, attribute, and text node. You can see all the CSS rules from each page’s stylesheets. You can explore all the scriptable properties of an object. It’s extremely powerful.

DOM Inspector is included with the Firefox installation program, but depending on your platform, it might not installed by default. If you don’t see a DOM Inspector item in the Tools menu, you will need to reinstall Firefox and choose Custom Install, then select Developer Tools. (Don’t worry; this will not affect your existing bookmarks, preferences, extensions, or user scripts.)

A nice addition to DOM Inspector is the Inspect Element extension. It allows you to right-click on any element—a link, a paragraph, even the page itself—and open DOM Inspector with that element selected. From there, you can inspect its properties, or see exactly where it fits within the hierarchy of other elements on the page.

One last note: DOM Inspector does not follow you as you browse. If you open DOM Inspector and then navigate somewhere else in the original window, DOM Inspector will get confused. It’s best to go where you want to go, inspect what you want to inspect, then close DOM Inspector before doing anything else.

JavaScript Shell is a bookmarklet that allows you to evaluate arbitrary JavaScript expressions in the context of the current page. You install it simply by dragging it to your links toolbar. Then you can visit a web page you want to work on, and click the JavaScript Shell bookmarklet in your toolbar. The JavaScript Shell window will open in the background.

JavaScript Shell offers you the same power as DOM Inspector but in a free-form environment. Think of it as a command line for the DOM. You can enter any JavaScript expressions or commands, and you will see the output immediately. You can even make changes to the page, such as creating a new element and adding to the page with . Your changes are reflected in the original page.

One feature of JavaScript Shell that is worth special mention is the function. Visit http://www.oreilly.com, open JavaScript Shell, and then type the following two lines:

JavaScript Shell spews out a long list of properties:

What’s this all about? It’s a list of all the properties and methods of that element that are available to you in JavaScript, grouped by levels in the DOM object hierarchy. Methods and properties that are specific to link elements (such as the and methods, and the and properties) are listed first, followed by methods and properties shared by all types of nodes (such as the method).

Again, this is the same information that is available in DOM Inspector—but with more typing and experimenting, and less pointing and clicking.

Embed Graphics in a User Script

This user script runs on all pages. It uses an XPath query to find web bugs: 1 x 1-pixel elements that advertisers use to track your movement online. The script filters this list of potential web bugs to include only those images that point to a third-party site, since many sites use 1 x 1-pixel images for spacing in table-based layouts.

There is no way for Greasemonkey to eliminate web bugs altogether; by the time a user script executes, the image has already been fetched. But we can make them more visible by changing the attribute of the element after the fact. The image data is embedded in the script itself.

Save the following user script as webbugs.user.js: