Gmail Greasemonkey API 1.0

mihaip edited this page Dec 18, 2012 · 2 revisions

NOTE: This is only available in Gmail's new JavaScript implementation.

Greasemonkey is an integral part of the web experience for many experienced users. Google acknowledges that some people are going to change their own experience of our web applications regardless of what we do. Resistance, as they say, is futile. It would also be somewhat hypocritical. After all, a Google employee wrote Greasemonkey in the first place, another wrote these scripts to add functionality to Gmail, and a third wrote two books on the subject (and these docs).

Instead, we would like to provide a little help to make such scripts more robust. Instead of finding elements by XPath or DOM traversal, this API provides accessor methods for getting common screen elements. Instead of forcing you to monkey-patch (ahem) our internal functions, this API provides callbacks to call your functions when specific events occur.

This API is experimental. New features and code changes may still cause Greasemonkey scripts to break.

API Reference

gmonkey object

The Gmail Greasemonkey API is available through the externed object 'gmonkey'. From your Greasemonkey script, you would use unsafeWindow.gmonkey to access it.

The gmonkey object supports the following methods:

gmonkey.load

void gmonkey.load(version, callbackFunc)

Loads the module. For performance reasons, the module is not loaded until a Greasemonkey script explicitly requests it.

versionStr must be "1.0". No other strings are currently recognized. callbackFunc is a function that takes one argument, a GmailAPI object (described below). It is called as soon as the module is successfully loaded.

It is safe to call this function more than once. If you have multiple Greasemonkey scripts installed that need this API, they should each call it once.

Important: Loading the module happens asynchronously. The callbackFunc function will be called when the API is successfully loaded.

gmonkey.isLoaded

boolean gmonkey.isLoaded(versionStr)

Tests whether the module is loaded.

versionStr must be "1.0". No other strings are currently recognized.

gmonkey.info

string gmonkey.info(versionStr)

Returns a short descriptive string about the module and where to get more information.

versionStr must be "1.0". No other strings are currently recognized.

gmonkey.get

GmailAPI gmonkey.get(versionStr)

Returns a reference to the already-loaded module.

versionStr must be "1.0". No other strings are currently recognized.

Warning: Loading the module (by calling gmonkey.load) happens asynchronously. That means that this code will not always work:

unsafeWindow.gmonkey.load("1.0");
var gmail = unsafeWindow.gmonkey.get("1.0");

This will work if the module is already loaded (perhaps by another Greasemonkey script), but it will almost certainly fail if this is the first request to load the module. If you are not sure whether the module has been loaded, you should call gmonkey.load and wait for the callback function to be called.

GmailAPI object

This object is passed to the callback function called from gmonkey.load. You should save a reference to it. If you've lost your reference and you're sure the module was loaded already, you can call gmonkey.get.

The GmailAPI object supports the following methods:

gmail.getActiveViewType

string gmail.getActiveViewType()

Returns the active view type. One of "tl" (theadlist), "cv" (conversation), "co" (compose), "ct" (contacts), or "s" (settings).

gmail.registerViewChangeCallback

void gmail.registerViewChangeCallback(callbackFunc)

Registers a function that should be called every time the active view changes. For example, if the user presses Enter to view a conversation thread, callbackFunc will be called with "cv". If the user then archives the thread, callbackFunc will be called with "tl".

gmail.getNavPaneElement

Element gmail.getNavPaneElement()

Returns the root DOM node of the entire lefthand navigation pane.

gmail.getMastheadElement

Element gmail.getMastheadElement()

Returns the root DOM node of the masthead.

gmail.getFooterElement

Element gmail.getFooterElement()

Returns the root DOM node of the page footer.

gmail.getActiveViewElement

Element gmail.getActiveViewElement()

Returns the root DOM node of the active view (such as the list of messages in your inbox or the messages in a conversation thread).

gmail.getSystemLabelsElement

Element gmail.getSystemLabelsElement()

Returns the root DOM node of the Labels navigation box.

gmail.getConvRhsElement

Element gmail.getconvRhsElement()

Returns the root DOM node of the righthand pane, if the active view is a conversation. Otherwise returns null.

gmail.addNavModule

GmailNavBox gmail.addNavModule(title, opt_content, opt_color)

Adds a collapsible box to the lefthand navigation pane and returns a GmailNavBox object that represents it.

title is the displayed title of the navigation box. opt_content is an optional string for the initial content of the navigation box. It may contain HTML. opt_color is an optional string for the border color of the navigation box. It can be any valid CSS color, such as "#0f0f0f", "rgb(255,255,0)", or "PapayaWhip".

GmailNavBox object

navbox.setColor

void navbox.setColor(cssColorStr)

Sets the border color of the navigation box.

cssColorStr can be any valid CSS color.

navbox.setContent

void navbox.setContent(htmlStr)

Replaces the entire content of the box with htmlStr.

htmlStr is a string, not a DOM node.

navbox.appendChild

void navbox.appendChild(element)

Appends a DOM node to the navigation box.

element is a DOM node, possibly with its own children.

navbox.getElement

Element navbox.getElement()

Returns the root DOM node of the navigation box.

navbox.getTitleElement

Element navbox.getTitleElement()

Returns the root DOM node of the navigation box's title.

To set the title:

navbox.getTitleElement().innerHTML = titleStr;

navbox.getContentElement

Element navbox.getContentElement()

Returns the root DOM node of the navigation box's content.

The following two snippets have the same effect:

navbox.setContent(htmlStr);

and

navbox.getContentElement().innerHTML = htmlStr;

Examples

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.