Editing MouseHole Scripts

Overview

A MouseHole script is fairly simple. Currently you can do 2 things in scripts:

  1. Pre-process web pages before your browsers sees them, and
  2. Add handlers for URLs inside of the MouseHole domain (e.g. http://localhost:37004/foobar)

A feature I want to see added is the ability to re-write URLs before they go out.

Example script

Anyway, the basic example script is as follows: 

MouseHole.script do
  # declaration
  name "Script Name"
  namespace "email@domain.com"
  description "A description of the script."
  # match Google's home page
  include_match %r{^https?://(www\.)?google\.com(/(index\.html)?)?$} 
  version "0.4"
  
  rewrite do |req, res|
    lucky = document.elements['//input[@name="btnI"]']
    search = document.elements['//input[@name="btnG"]']
    lucky.parent.delete(lucky)
    search.parent.insert_before(search, lucky)
  end
end

This script simply rewrites the Google index page to swap the Google Search and I'm Feeling Lucky buttons.

Method list

The methods supported by a MouseHole script are the following:

Declaration

name
Defines the script name.
namespace
Defines the script namespace.
description
Defines the script description.
version
Defines the script version.
include_match
Defines a regex to match pages for inclusion.
exclude_match
Defines a regex to match pages for exclusion.
remove_match
Removes an include or exclude match.

Note: exclusions take precedence over inclusions.

Action Callbacks

rewrite { }
Defines a block that takes two parameters, the request and the response. The requested document is available in the document attribute as an HTree. Any modifications to document will be sent to the browser.
mount( mount_point ) { |path| }
Defines a block that's called whenever mount_point is accessed on MouseHole (e.g. if mount_point is 'foobar' then http://localhost:37004/foobar/bar would call this mount). The block takes one parameter, which is the path past the mountpoint (in the example given it would be 'bar'). The result of this block is handed back to the browser.
register_uri( regexp ) { |uri| } 1.2+
URIs which match the expression regexp are allowed to be accessed via Javascript for this script. The block is optional and allows fabrication of a resource, if you like.
unregister_uri( regexp ) 1.3+
Removes a registered URI expression.
configure { }
Defines a block that's called whenever the script is configured. The result of this block should be an HTML snippet that can be inserted into the configuration page. Saving values will require having a mount point to send requests to. You can use the JavaScript sndReq(url) function to send an HTTP request to the server and ignore any results.

Accessors

mousehole_uri 1.3+
Returns the URI pointing to the MouseHole doorway.
install_uri
Returns the URI where the script was originally installed from. If script was installed by hand, returns nil.
token
A 32-character unique token for this script.

Utility Methods

document
When called from within a rewrite block, returns an REXML Element of the current document. For this reason, response.body is empty inside the rewrite block.
request
The request object.
response
The response object.
reg( uri )
Translate a URI into the registered URI within MouseHole, safe to use in rewrites on matching domains.
self[]
Fetch a stored value from the script's object database.
self[]=
Store a value in the MouseHole script database.
read_xhtml_from( uri )
Reads the document referenced by <tt>uri</tt> and returns it as a REXML Element.
read_xhtml( str ) 1.2+
Reads the document inside string <tt>str</tt> and returns it as a REXML Element.
xhtmlize( str ) 1.2+
Takes a string of HTML and builds a new XHTML string for it. Since all additions and transformations to the document need to be valid.
debug( msg ) 1.2+
Log a debug message, if the user's debugging is turned on.

Using Your Script

To test your user script, copy it into your userScripts directory.

  • On Windows, this directory is found at C:/Documents and Settings/Your Username/Application Data/MouseHole.
  • On other systems, look in $HOME/.mouseHole.

Make sure it is named your-script.user.rb otherwise MouseHole won't load it!

The first time you copy the script into the directory, you'll need to restart MouseHole to have it loaded. From then on, as you edit the script, MouseHole will automatically reload it.

To release a version of your script, place it up on the web and add it to our list: UserScripts.