#summary API reference for version 1.0 of the experimental Gmail Greasemonkey API #labels Featured NOTE: This is only available in [http://gmailblog.blogspot.com/2007/10/code-changes-to-prepare-gmail-for.html Gmail's new JavaScript implementation]. [http://www.greasespot.net/ 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 = * [ArticleGmailViewWatcher Case study: Gmail View Watcher]