loading...

Please wait...
Tampermonkey
by Jan Biniok
Home
Support
Changes
Donate
About
This section describes how the Tampermonkey API can be used and what is different to Geasemonkey.
Content
Userscript Header

@name

The name of the script.

@namespace

The namespace of the script.

@version

The script version. This is used for the update check, in case the script is not installed from userscript.org or TM has problems to retrieve the scripts meta data.

@author

The scripts author.

@contributor

One ore more contributors. Multiple tag instances are allowed.

@description

A short pregnant description.

@homepage, @homepageURL, @website and @source

The authors homepage that is used at the options page to link from the scripts name to the given page. Please note that if the @namespace tag starts with 'http://' its content will be used for this too.

@icon, @iconURL and @defaulticon

The script icon in low res.

@icon64 and @icon64URL

This scripts icon in 64x64 pixels. If this tag, but @icon is given the @icon image will be scaled at some places at the options page.

@updateURL

An update URL for the userscript.
Note: the script must either use the @version tag or the server adds a 'uso:hash' key to the update check data.

@downloadURL

Defines the URL where the script will be downloaded from when a update was detected.

@include

The pages on that a script should run. Multiple tag instances are allowed.
Please note that @include doesn't support the URL hash parameter. Please visit this forum thread for more information: click.
Code:
// @include http://tampermonkey.net/*
// @include http://*
// @include https://*
// @include *

@match

More or less equal to the @include tag. You can get more information here .
Note: the '<all_urls>' statement is not yet supported and the scheme part also accepts 'http*://'.

Multiple tag instances are allowed.

@exclude

Exclude URLs even it they are included by @include or @match .

Multiple tag instances are allowed.

@require

Points to a javascript file that is loaded and executed before the script itself starts running.

Multiple tag instances are allowed.

@resource

Preloads resource that can by accessed by GM_getResourceURL and GM_getResourceText by the script.
Code:
// @resource icon1 http://tampermonkey.net/favicon.ico
// @resource icon2 /images/icon.png
// @resource html http://tampermonkey.net/index.html
// @resource xml http://tampermonkey.net/crx/tampermonkey.xml
Multiple tag instances are allowed.

@run-at

Defines the moment the script is injected. In opposition to other script handlers, @run-at defines the first possible moment a script wants to run. This means it may happen, that a script that uses the @require tag may be executed after the document is already loaded, cause fetching the required script took that long. Anyhow, all DOMNodeInserted and DOMContentLoaded events that happended after the given injection moment are cached and delivered to the script when it is injected.
Code:
// @run-at document-start
The script will be injected as fast as possible.
Code:
// @run-at document-body
The script will be injected if the body element exists.
Code:
// @run-at document-end
The script will be injected after the DOMContentLoaded event was dispatched.

@grant

@grant is used to whitelist GM_* functions and the unsafeWindow object. If no @grant tag is given TM guesses the scripts needs.
Code:
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_setClipboard
// @grant unsafeWindow
Note: multiple instances are allowed.

If @grant is followed by 'none' the sandbox is disabled and the script will run directly at the page context. In this mode no GM_* function but the GM_info property will be available.
Code:
// @grant none

@user-agent

Overrides the user agent header string to the given value at all requests that are defined by @match , @include and @exclude statements.
You can get user agent strings here: http://www.useragentstring.com/pages/useragentstring.php

@noframes

This tag makes the script running on the main pages, but not at iframes.

@unwrap

This tag is ignored because, it is not needed at Google Chrome/Chromium.

@nocompat

At the moment TM tries to detect whether a script was written in knowledge of Google Chrome/Chromium by looking for the @match tag, but not every script uses it. That's why TM supports this tag to disable all optimizations that might be necessary to run scripts written for Firefox/Greasemonkey. To keep this tag extensible you can to add the browser name that can be handled by the script.
Code:
// @nocompat Chrome
Application Programming Interface

unsafeWindow

The unsafeWindow object provides full access to the pages javascript functions and variables.

DOMAttrModified

Chrome/Chromium does not have native DOMAttrModified support, but in TM statements like
Code:
var foo = document.getElementById('whatever');
foo.addEventListener("DOMAttrModified", function (e) {console.log(e); }), false);
are working as usual for any attribute change of "foo".
Event handlers that catch bubbled events like this:
Code:
document.addEventListener("DOMAttrModified", function (e) {console.log(e); }), false);
are working too, but will only be notified of changes of objects that are "registered" for DOMAttrModified like the element "foo" is.

wrappedJSObject

Although this is not needed in Chrome/Chromium some scripts need that object to be part of HTML elements to run successfully. That's why TM adds this property to every HTMLElement to return the (never wrapped) element.

GM_addStyle(css)

Adds the given style to the document.

GM_deleteValue(name)

Deletes 'name' from storage.

GM_listValues()

List all names of the storage.

GM_addValueChangeListener(name, function(name, old_value, new_value, remote) {})

Adds a change listener to the storage and returns the listener ID.
'name' is the name of the observed variable.
The 'remote' argument of the callback function shows whether this value was modified from the instance of another tab (true) or within this script instance (false).
Therefore this functionality can be used by scripts of different browser tabs to communicate with each other.

GM_removeValueChangeListener(listener_id)

Removes a change listener by its ID.

GM_setValue(name, value)

Set the value of 'name' to the storage.

GM_getValue(name, defaultValue)

Get the value of 'name' from storage.

GM_log(message)

Log a message to the console.

GM_getResourceText(name)

Get the content of a predefined @resource tag at the script header.

GM_getResourceURL(name)

Get the base64 encoded URI of a predefined @resource tag at the script header.

GM_registerMenuCommand(name, fn, accessKey)

Register a menu to be displayed at the Tampermonkey menu at pages where this script runs and returns a menu command ID.

GM_unregisterMenuCommand(menuCmdId)

Unregister a menu command that was previously registered by GM_registerMenuCommand with the given menu command ID.

GM_openInTab(url, options)

Open a new tab with this url. The options object can have two properties: 'active' decides whether the new tab should be focused and 'insert' that inserts the new tab after the current one. Otherwise the new tab is just appended. The function returns an object with the function 'close', the listener 'onclosed' and a flag called 'closed'.

GM_xmlhttpRequest(details)

Make an xmlhttpRequest. Supports:
- cross domain requests
- headers (user-agent, referer, ...) needs build nr. 2656 or greater
- Note: the synchronous flag at the details is not supported

GM_download(details), GM_download(url, name)

Downloads a given URL to the local disk.

details can have the following attributes:
  • url - the URL from where the data should be downloaded
  • name - the filename - for security reasons the file extension needs to be whitelisted at the Tampermonkey options page
  • headers - see GM_xmlhttpRequest for more details
  • saveAs - boolean value, show a saveAs dialog
  • onload - function() {} - callback function that is called when the download has finished
  • onerror - function(download) {} - callback function that is called when there was an error
The download argument of the onerror callback can have the following attributes:
  • error - error reason
    • not_enabled - the download feature isn't enabled by the user
    • not_whitelisted - the requested file extension is not whitelisted
    • not_permitted - the user enabled the download feature, but did not give the downloads permission
    • not_supported - the download feature isn't supported by the browser/version
    • not_succeeded - the download wasn't started or failed, the details attribute may provide more information
  • details - detail about that error

GM_getTab(cb)

Get a object that is persistent as long as this tab is open.

GM_saveTab(tab)

Save the tab object to reopen it after a page unload.

GM_getTabs(cb)

Get all tab objects in an array to communicate with other scrips instances.

GM_notification(msg, title, callback, { onclose: function() {}, timeout: 5000 /* ms */ })

Shows a notification that will be hidden after a timeout (0 = disabled), the callback is called in case the user clicks the notification and onclose is called when the notification is closed no matter if this was triggered by a timeout or a click.

GM_setClipboard(data, info)

Copies data into the clipboard. The parameter 'info' can be an object like "{ type: 'text', mimetype: 'text/plain'}" or just a string expressing the type ("text" or "html").

GM_installScript(url, callback)

Install a userscript to Tampermonkey. The callback gets an object like "{ found: true, installed: true }" that shows whether the script was found and the user installed it.

GM_info

Get some info about the script and TM. The object might look like this:
Code:
Object+
---> script: Object+
------> author: ""
------>copyright: "2012+, You"
------>description: "enter something useful"
------>excludes: Array[0]
------>homepage: null
------>icon: null
------>icon64: null
------>includes: Array[2]
------>lastUpdated: 1338465932430
------>matches: Array[2]
------>name: "Local File Test"
------>namespace: "http://use.i.E.your.homepage/"
------>options: Object+
--------->awareOfChrome: true
--------->compat_arrayleft: false
--------->compat_foreach: false
--------->compat_forvarin: false
--------->compat_metadata: false
--------->compat_prototypes: false
--------->compat_uW_gmonkey: false
--------->noframes: false
--------->override: Object+
------------>excludes: false
------------>includes: false
------------>orig_excludes: Array[0]
------------>orig_includes: Array[2]
------------>use_excludes: Array[0]
------------>use_includes: Array[0]
--------->run_at: "document-end"
------>position: 1
------>resources: Array[0]
------>run-at: "document-end"
------>system: false
------>unwrap: false
------>version: "0.1"
---> scriptMetaStr: undefined
---> scriptSource: "// ==UserScript==\n// @name       Local File Test\n ...."
---> scriptUpdateURL: undefined
---> scriptWillUpdate: false
---> scriptHandler: "Tampermonkey"
---> version: "2.4.2716"

<><![CDATA[blubber]]></>

Tampermonkey supports this way of storing meta data. TM tries to automatically detect whether a script needs this option to be enabled.

for each (var k in arr)

Tampermonkey replaces "for each" statements by chrome compatible code. TM tries to automatically detect whether a script needs this option to be enabled.