The Experiments of Gareth Andrew

This has been superceded by a new version of the GreasemonkeyImports patch. This page is for historical interest only.

GreasemonkeyImports adds the ability to import files into your greasemonkey scripts, this allows splitting your javascript into a more modular file organisation, including third party libraries, and importing extra resaources such as images, html and css. It is available as patch to greasemonkey, and as a php script.

See also: Greasemonkey Imports Service

Motivation

Greasemonkey scripts currently consist of a single javascript file. This file must contain all the data the extension requires. This means html and css must be embedded (as a string), images can only be used if they are remotely fetched or embedded as data uri's, other media can only be fetched remotely (since not all plugins support the data uri scheme). This also means all javascript has to be stored in the same file, limiting reuse to cut-and-paste techniques. This extension to greasemonkey seeks to solve these problems with the addition of import functionality.

Use Cases

1. Separation of html and stylesheets from code.
2. Embedding images
3. Embedding other media (Might not work -see #Limitations)
4. Writing modular code
5. Reusing existing javascript libraries
6. Building greasemonkey specific libraries

Usage

This extension adds a new metadata annotation @import. This annotation has two parameters, a symbolic name for the import, and a url (relative or absolute) from which the import can be downloaded eg.

// ==UserScript== // @name MyUserScript // ... // @import importName http://example.com/path/to/import
The user script can access the import by calling GM_getImport(). This function returns a GM_Import object with two acessor functions

• getContents() - this method returns the file contents.
• getDataURL(mimetype) - this method return the file contents as a data url with the specified mimetype

Limitations

Data urls are not supported by plugins (afaict), so gm_imports cannot be used to import flash, audio or video.

Security

As a security precaution scripts can only import files from http, https, or ftp url's. Scripts installed from file url's can also import files from file url's. Chrome and all other url's are forbidden.

Operation

When a new user script is installed, greasemonkey parses the user scripts metadata, and retrieves (via XMLHttpRequest) all the named imports. Each user script now has its own directory under gm_scripts, where the script is stored along with any imports. The symbolic name and local location are stored in config.xml.

Examples

Inserting and replacing HTML/CSS/Text

Any kind of text content can be inserted in the page, or used to replace an element in the page. See also: Dive Into Greasemonkey (http://www.diveintogreasemonkey.org).

var imp = GM_getImport("someText"); var contents = imp.getContents(); var div = document.createElement("div"); div.innerHTML = contents; document.body.insertBefore(div, document.body.firstChild);

Inserting Images

Images can be inserted using the getDataURL() method of GM_Import.

var imp = GM_getImport("image"); var url = imp.getDataURL("image/jpeg"); var image = document.createElement("img"); image.src = url; image.width=221; image.height=219; document.body.appendChild(image);

Script injection

Javascript can be loaded from libraries using getContents() and the eval() function. Code loaded in this manner will behave exactly as if the code had been written inline in the user script,and thus will have the same privileges (eg. access to GM_* functions) and limitations of normal greasemonkey user scripts (ie. document and window are XPCNativeWrappers)

var imp = GM_getImport("library"); var contents = imp.getContents(); eval(contents); test(); //defined in library.js

Javascript can also be injected into the document through the DOM. Javascript injected this way will run with no extra privileges and normal browser behaviour eg. No GM_* functions, and window!=XPCNativeWrapper.

var imp = GM_getImport("library"); var script = document.createElement("script"); script.type = "text/javascript"; script.text = imp.getContents(); var head = document.getElementsByTagName("head")[0]; head.appendChild(script);

Download

Download page