Greasemonkey Hacks

Hack #2. Provide a Default Configuration

User scripts can be self-describing; they can contain information about what they do and where they should run by default.

Every user script has a section of metadata, which tells Greasemonkey about the script itself, where it came from, and when to run it. You can use this to provide users with information about your script, such as its name and a brief description of what the script does. You can also provide a default configuration for where the script should run: one page, one site, or a selection of multiple sites.

The Code

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

	Example: Hello World metadata

	// ==UserScript==
	// @name		Hello World
	// @namespace	http://www.oreilly.com/catalog/greasemonkeyhcks/
	// @description	example script to alert "Hello world!" on every page
	// @include		*
	// @exclude		http://oreilly.com/*
	// @exclude		http://www.oreilly.com/*
	// ==/UserScript==

	alert('Hello world!');

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

Wrapper

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

	// ==UserScript==
	//
	// ==/UserScript==

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.

Name

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

	// @name	Hello World

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.

@name 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.

Namespace

Next comes the namespace:

	// @namespace	http://www.oreilly.com/catalog/greasemonkeyhcks/

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 tag: URI.

Tip

Learn more about tag: URIs at http://www.taguri.org.

@namespace 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.

Tip

You can specify the items of your user script metadata in any order. I like @name, @namespace, @description, @include, and finally @exclude, but there is nothing special about this order.

Description

Next comes the description:

	// @description		example script to alert "Hello world!" on every page

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.

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

Tip

Though @description is not mandatory, don't forget to include it. Even if you are writing user scripts only for yourself, you will eventually end up with dozens of them, and administering them all in the Manage User Scripts dialog will be much more difficult if you don't include a description.

URL Directives

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

	// @include		*
	// @exclude		http://oreilly.com/*
	// @exclude		http://www.oreilly.com/*

The @include and @exclude 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 @include * (all sites), but it would be excluded because it also matches @exclude http://oreilly.com/*.

@include and @exclude 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 @include *).