Greasemonkey Hacks

Hack #1. Install a User Script

Greasemonkey won't do anything until you start installing user scripts to customize specific web pages.

A Greasemonkey user script is a single file, written in JavaScript, that customizes one or more web pages. So, before Greasemonkey can start working for you, you need to install a user script.

Tip

Many user scripts are available at the Greasemonkey script repository: http://userscripts.org.

This hack shows three ways to install user scripts. The first user script I ever wrote was called Butler. It adds functionality to Google search results.

Installing from the Context Menu

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

1. Visit the Butler home page (http://diveintomark.org/projects/butler/) to see a brief description of the functionality that Butler offers.

2. Right-click (Control-click on a Mac) the link titled "Download version…" (at the time of this writing, Version 0.3 is the latest release).

3. From the context menu, select Install User Script….

4. A dialog titled Install User Script will pop up, displaying the name of the script you are about to install (Butler, in this case), a brief description of what the script does, and a list of included and excluded pages. All of this information is taken from the script itself [Hack #2] .

5. Click OK to install the user script.

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.

Figure 1-4. Butler-enhanced search results

Installing from the Tools Menu

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.

Editing Greasemonkey's Configuration Files

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:

Single-user Windows 95/98/ME

C:\Windows\Application Data\Mozilla\Firefox

Multiuser Windows 95/98/ME

C:\Windows\Profiles\%USERNAME%\Application Data\Mozilla\Firefox

Windows NT 4.x

C:\Winnt\Profiles\%USERNAME%\Application Data\Mozilla\Firefox

Windows 2000 and XP

C:\Documents and Settings\%USERNAME%\Application Data\Mozilla\Firefox

Unix and Linux

~/.mozilla/firefox

Mac OS X

~/Library/Application Support/Firefox

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:

	<UserScriptConfig>
		<Script filename="bloglinesautoloader.user.js"
				name="Bloglines Autoloader"
				namespace="http://diveintomark.org/projects/greasemonkey/"
				description="Auto-display all new items in Bloglines (the
				 equivalent of clicking the root level of your
				 subscriptions)"
				enabled="true">

				<Include>http://bloglines.com/myblogs*</Include>
				<Include>http://www.bloglines.com/myblogs*</Include>
			</Script>
			<Script filename="googlesearchkeys.user.js"
				name="Google Searchkeys"
				namespace="http://www.imperialviolet.org"
				description="Adds one-press access keys to Google search
				 results"
				enabled="true">
			<Include>http://www.google.*/search*</Include>
		</Script>
		<Script filename="mailtocomposeingmail.user.js"
				name="Mailto Compose In GMail"
				namespace="http://blog.monstuff.com/archives/000238.html"
				description="Rewrites &quot;mailto:&quot; links to GMail
				 compose links"
				enabled="true">
			<Include>*</Include>
			<Exclude>http://gmail.google.com</Exclude>
		</Script>
	</UserScriptConfig>

To install a new script, simply copy it to this scripts directory and add a <Script> entry like the other ones in config.xml. The <Script> element has five attributes: filename, name, namespace, description, and enabled. Within the <Script> element you can have multiple <Include> and <Exclude> 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 </UserScriptConfig>:

	<Script filename="butler.user.js"
			name="Butler"
			namespace="http://diveintomark.org/projects/butler/"
			description="Link to competitors in Google search results"
			enabled="true">
		<Include>*</Include>
		<Exclude>http://*.google.*/*</Exclude>
	</Script>

Tip

A user script's filename must end in .user.js. If you've gotten the file extension wrong, you won't be able to right-click the script's link and select Install User Script…from the context menu. You won't even be able to visit the script itself and select Install User Script…from the Tools menu.