The Pug Automatic

Major update to the TextMate Greasemonkey bundle

Written March 5, 2007. Tagged Greasemonkey, JavaScript, OS X, TextMate.

I've made quite a few additions/changes to the Greasemonkey bundle for TextMate.

The most exciting addition is probably the ability to upload scripts straight into Userscripts.org.

Download: Greasemonkey.tmbundle.zip (96 KB)

Please comment with any bug reports or feature suggestions.

I made a screencast (7 minutes 23 seconds, 14.45 MB streaming). No audio, but feel free to put on "Greased Lightning" in the background.

Around 2:00 in the movie, I forget to update the script metadata (write to the config.xml from the script metadata block), so things don't work as I planned until I fix it around 2:50. Sorry about that - might be a bit confusing.

I'll paste the bundle documentation (available through Help in the bundle menu) below, for your pleasure:

Template (⇧⌃⌥⌘G)

Select File > New From Template > Greasemonkey > Userscript to create a new script from template. The template outputs this:

// ==UserScript==
// @name Name
// @namespace http://www.example.com
// @description Description.
// @include *
// ==/UserScript==



/* Your favorite functions go here. */

The metadata block is a snippet, with placeholders. If you set a TM_NAMESPACE shell variable in the TextMate preferences (Preferences > Advanced > Shell Variables), this will be used as the default @namespace. If you have a page currently open in Firefox, that will be the default value for the @include.

You should change the template.user.js template to include whatever functions you commonly use. The snippet can be modified in the bundle editor (File > New From Template > Edit Templates…) as snippet.user.js.

Optionally, if you create a file ~/Library/Application Support/TextMate/Bundles/Greasemonkey.tmbundle.staples.user.js, the /* Your favorite functions go here. */ comment will be substituted with its contents whenever a new script is created. This might be useful if you want to version control your staple code.

Creating a template is available in the global scope – you don’t need to be editing a Greasemonkey script to invoke the keyboard shortcut.

Snippets

Included URL and Excluded URL (i⇥ and e⇥)

Within the header block, the snippets i and e add @include and @exclude directives with http:// as a preselected value. The next tab stop puts the caret after http://.

Sadly, TextMate doesn’t support snippets-within-snippets yet, so this does not work until after you’ve broken out of the header snippet. However, Continue Header URL works fine in snippets.

Continue Header URL (⌅)

Available when writing @include and @exclude directives. Hitting ⌅ adds another of the same directive on the next line and moves the caret.

If you want to add another directive with a similar URL, consider using Bundles > Text > Duplicate Line (⌃⇧D) instead.

Strictly speaking a command, but it fits with the snippets.

GM_log (log⇥, logw⇥ and loge⇥)

log inserts GM_log("info") with "info" pre-selected. The next tab stop selects just ìnfo. Start typing directly to log a variable, or tab once and then type, to input a string.

logw and loge give warning and error level logging.

GM_setValue and GM_getValue (set⇥ and get⇥)

Inserts those function calls. The contents of the key string are pre-selected. The next two tab stops select "value" and value in that order. Start typing at the first tab stop to specify a variable, and the second to specify a string.

GM_addStyle (css⇥)

Expands to GM_addStyle("CSS"); with the string contents pre-selected.

GM_xmlhttpRequest (xhr⇥)

Inserts that function call, with a GET method (POST is messy).

Tab stops are in turn the url value, the url value string contents, the entire onload value and the body of a pre-defined onload callback function.

GM_registerMenuCommand (menu⇥)

Inserts that function call, with tab stops selecting in turn the command name string contents, the entire callback function and the body of a pre-defined function.

GM_openInTab (tab⇥)

Inserts that function call, with tab stops selecting in turn the entire URL string and the string contents.

Commands

Open Installed Script… (⌃⌥⌘G)

Displays a dialog listing every installed userscript, with the choice of alphabetical or chronological (most recently installed first) ordering. Select a script and confirm to open it.

Available in the global scope – you don’t need to be editing a Greasemonkey script to invoke it.

Install and Edit (⌘B)

If you write a new script and hit ⌘B, the script will be installed, the old file closed and the installed version opened for editing. This makes starting new scripts vastly less annoying.

Caveat: “Enable access for assistive devices” must be toggled on in the Universal Access prefpane, otherwise closing the old file will not work.

When the old file is closed, any unsaved changes are discarded.

Update Metadata (⌘D)

Hit ⌘D (conveniently next to the S of saving fame) to update the config.xml metadata from the values in the script file.

Greasemonkey writes the @name, @include, @exclude values and friends to config.xml when a script is installed. After that time, these values are not updated as the script file changes but must be changed in the “Manage User Scripts” window – or with this command.

Caveats: The command replaces the metadata values with the script values. This means that if you’ve e.g. changed @includes in “Manage User Scripts” but not in the script itself, your modifications are lost.

Greasemonkey uses the @name and @namespace to uniquely identify a script. If you change these values in config.xml, it will be considered a different script than before – so if you later install a script with the old name, that script will not replace the one you have.

Also, it will not recognize any values defined with GM_set() using another script name.

Uninstall Script

Uninstalls the currently open script and moves it to Trash, then closes the buffer. Prompts for confirmation first.

No keyboard shortcut by default.

Caveat: Doesn’t remove any data set by the script using GM_setValue.

Upload to Userscripts.org (⌘U)

Sends the currently open script to Userscripts.org, as a new contribution or as an update.

You will be prompted for your log-in details the first time you run this command. After that, you are prompted only if a log-in fails.

If the name of the script matches the name of a single remote script, an update will be performed automatically. If there are no remote scripts, the script will automatically be posted as new. In all other cases – if there is no remote script with this name, or multiple remote scripts with this name – you will be prompted whether to add as new or update, with the most probable option pre-selected.

The list of remote scripts to update is sorted by increasing minimum edit distance – how similar the name is to that of the currently open script.

Caveats: Your username and password are stored in plain text as ~/Library/Preferences/com.macromates.textmate.gmbundle.plist, which is not the best of security.

There is currently no interface to reset or change valid log-in details. If you want to do those things, delete or modify the preference file manually, or trigger a failed log-in by temporarily changing your Userscripts.org password.

Reload Firefox (⌘R)

Hit ⌘R to activate Firefox and reload the current page, typically after making changes to a script. The file is saved automatically before reloading.

Caveats: Either “Enable access for assistive devices” must be on, or Firefox should not be configured to open URLs from external applications in new tabs. If neither is true, the command will not be able to reload Firefox.

Reload Firefox and Return (⇧⌘R)

Activates Firefox and reloads the current page, then returns focus to TextMate after 5 seconds. Useful to check the result of script changes that aren’t about lengthy interaction.

Modify the command with the bundle editor (Bundles > Bundle Editor > Edit Commands…) to change the delay.

Caveats: Same as for Reload Firefox.

Manage GM_Values

Opens about:config in Firefox and filters by the script being edited, exposing any GM_setValue() values to view and edit.

Caveats: “Enable access for assistive devices” must be toggled on in the Universal Access prefpane, otherwise filtering will not work.

Does not handle all weird characters properly.

Comment/Uncomment GM_logs

In the selection or else the entire document, all GM_log() function calls are commented out if any were uncommented; otherwise all GM_log() function calls are uncommented.

Remove GM_logs

Removes all GM_log() function calls in the selection or else the entire document.

Documentation for Word / Selection (⌃H)

Opens a web window with documentation for the currently focused or selected word.

This is an extended version of the command from the JavaScript bundle, but with support for Greasemonkey constructs.

Resources (⌃⌥⌘H)

Invoking ⌃⌥⌘H opens a menu where you can choose a help resource by clicking or pressing the listed number.

The resources are

  1. Gecko DOM Element
  2. XPath
  3. GreaseSpot Wiki
  4. Forum: US.O Script Development
  5. IRC: #javascript@Freenode

The Userscripts.org forum opens in your default browser, and the IRC link in your IRC client, if you have one. The other pages open in a web window.

Help

This document in a web window.

Credits

Originally by Adam Vandenberg, who wrote most of the grammar and a few snippets.

The Documentation for Word / Selection command is originally by Thomas Aylott, I think.

Improved by and currently maintained by Henrik Nyh who added a bit of everything.

Any part of the bundle is free to modify and redistribute with due credit unless otherwise noted.