The Anatomy of a User Script

Hopefully I've piqued your interest. But how does this all work? It's surprisingly simple. Let's crack open the Butler user script and see how it works.

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 it 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 metadata section of the Butler user script looks like this:

// ==UserScript==
// @name        Butler
// @namespace   http://diveintomark.org/projects/butler/
// @description Link to competitors from Google search results
// @include     http://*.google.*/*
// ==/UserScript==

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:

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.

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.

Name

// @name        Butler

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, the default is the filename of the user script, minus the .user.js extension.

Namespace

// @namespace   http://diveintomark.org/projects/butler/

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.

@namespace is optional. If present, it can appear only once. If not present, the default is the domain from which the user downloaded the user script.

Description

// @description Link to competitors from Google search results

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, the default is an empty string.

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 without descriptions.

Include

The @include directive lists the URLs and wildcards that tell Greasemonkey where to run this user script:

// @include     http://*.google.*/*

There is also an @exclude directive, which shares the same syntax. The @include and @exclude directive can each 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 Butler script on all Google sites in all countries, all subdomains (such as http://froogle.google.com/), and on all pages within any of those Google properties. Everywhere Google is, we want to be there.

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

var href = window.location.href;

// Google web search
if (href.match(/^http:\/\/www\.google\.[\w\.]+\/search/i)) {
  Butler.addLogo();
  Butler.removeSponsoredLinks();
  Butler.addOtherWebSearches();
  Butler.addOtherInlineMovieReviews();
  Butler.addOtherInlineNewsResults();
  Butler.addOtherInlineForecasts();
  Butler.addOtherInlineProductSearches();
}