|
|
GmailGreasemonkey10API
API reference for version 1.0 of the experimental Gmail Greasemonkey API
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
Sign in to add a comment
Awesome.
Hallelujah! Although I still need to re-work my old Gmail GreaseMonkey? scripts, this should make things MUCH easier!
Truly incredible, forward thinking.
awesome.
AFAICT, gmail.getSystemLabelsElement returns a reference to the DOM element that encloses the topmost navigation box in the left pane, not the green box of user-created Labels. I may have misunderstood the documentation, but it could be clearer which behaviour it's supposed to be.
I'm going to start sending links to this documentation to developers of scripts I used in the old version of Gmail to see if it'll help them update to the new UI. Nice work, Mihai, Dan, and whoever else worked on these!
Okay, here's a really simple one that just moves the Label/Chat boxes up to the top of the left column. If you're like me, you use a to:me label instead of the Inbox, and filter all mailing lists directly:
http://sandbox.mikepurvis.com/js/gm/gmaillabelsfirst.user.js
Really cool!
The idea of the API is just awesome!
Any hint on an easy way to add new labels to the navigation box? Like the GMail + Google Reader script did for the old GMail?
Say, would it be possible to add Google gadgets (ie weather, date/time, ect.) in a sideframe in gmail. For example, make an option to add whatever gadgets the user wanted in on the right side of the inbox page? I think this would be really cool, but dont know how to go about doing it. :-(
1) The docs of ViewChangeCallback? say: "callbackFunc will be called with "cv", but it seems it is not called with any argument, and the current view needs to be read using getActiveViewType()
2)shouldn't compose mode be entered when composing a Reply? It is only active for new mails it seems
3)minor: description of gmonkey.load has version in the code but versionStr mentioned in the docs
Please correct the typo "Element gmail.getconvRhsElement()" should be "Element gmail.getConvRhsElement()" (Upper case 'C')
Looks like a method named getCanvasElement is not documented :(
Would it be possible to add to the API a callback when the message list is updated? (Or, more generally whenever an update occurs, particularly for those not related to the user clicking.)
I'm currently putting together a script for label colors with the new version of Gmail, and without such a callback it will require ugly periodic polling...
Also, labels seem to be in spans with the class "C5uTre?" in my tests so far. Is this the kind of thing we can rely on staying the same? Are these likely to be documented? If not, it seems that we will still need to use some hacks to obtain some (limited) "robustness" in order to do any significant customization. (Of course the situation is still better than if there was no API at all!)
I've found the same problems related by rd1rd2 when I was trying to implement the "Fixed font view/edit" script with this API.
I hope that Google provides more "getElement" methods in API...
Message Reading Pane using Greasemonkey and the API
I have been hooked on greasemonkey for almost a year. One of the scripts that would make a lot of sense to me is to have a message reading pane on the right (like desktop email clients). I'm not a programmer, but can this be done.
The ViewChangeCallback? seems to have broken. The callback is fired is called when entering threadlist(tl) from conversation(cv) but not vise-a-versa. I've attached the call stack below.
invalid 'in' operand a $GOk$P$GRa$("Permission denied to create wrapper for object of class UnnamedClass?", undefined)mail (line 355) $GOk$P$Guh$("Permission denied to create wrapper for object of class UnnamedClass?", undefined)mail (line 356) $G9g$("Permission denied to create wrapper for object of class UnnamedClass?", undefined)mail (line 350) $a$protected$()mail (line 146) $CRm$(aa jb=Object G8=Object Jg=la Fy=Object Gua=Object YC=tc, "navigate", false, Object type=navigate target=p currentTarget=aa wB=Object)mail (line 76) $COm$(p jb=Object G8=Object Jg=la Fy=Object Gua=Object, Object type=navigate target=p currentTarget=aa wB=Object)mail (line 77) C3m(Object type=navigate target=p currentTarget=aa wB=Object)mail (line 79) $p$P$U9$(false)mail (line 689) $p$P$T9$(Object type=mousedown target=span#1f8v)mail (line 687) $CHm$P$B7$(Object type=mousedown target=span#1f8v)mail (line 67) $CQm$(Object CE=true src=div.XoqCub? type=mousedown capture=false, Object type=mousedown target=span#1f8v)mail (line 76) $a$protected$()mail (line 146) $CWm$(186, mousedown clientX=0, clientY=0)mail (line 79) $a$(mousedown clientX=0, clientY=0)mail (line 69) on this error? H=" other errors\n\n",Ha="stack",Hb="---\n",Hc="\n\n";GOk[P].GRa=function $GOk$...
I'll take a look at the problems reported here. Let me know what other methods would be particularly useful and I'll add them to our wishlist.
@mr.ruiz: Is the example "Gmail View Watcher" above working for you, it uses the viewChangeCallback and works for me.
@rd1rd2: The classnames are shortened using a deterministic algorithm, so this approach will work unless the structure of the labels HTML and unshortened class names change due to new features.
@dan.pupius the "Gmail View Watcher" successfully makes all switches except tl->cv. The "View Monitor" does not change to "Conversation" in this case.
@dan.pupius some of my buggy code might have been causing the issue(not sure). However, suspicious things occur when errors or exceptions are thrown from the callback function in gmail.load(version, callback). It prevented subsequent gmail.load calls in other scripts from firing their respective callbacks.
Poetry...
Poetry...
I wanted to have a list of people who are online in my gmail chat at any given time. Is there any way, other than traversing the entire length of DOM till the <div> of the chat_box and then take individual divs to get the online users names.
I guess this is not supported for GreaseKit?/Safari, which is a shame. I have a script:
window.addEventListener('load', function() {
});However, no alerts are ever shown. I don't get anything in my JavaScript? console and nothing in Console.app related to GreaseKit?. Any idea if GreaseKit?/Safari support can be worked in too?
God, I'm an idiot. Well, I changed it to unsafeWindow.gmonkey.load('1.0', ...), reloaded all user scripts, but still no go. Any ideas?
This is veru cool API.. keep on coming.
I can't get it to work. I copied the example exactly as above and Greasemonkey reports that unsafeWindow.gmonkey is undefined. I get an alert for unsafeWindow, but not for unsafeWindow.gmonkey. Any ideas?
I was able to get the GMonkey API working from a Firefox Toolbar, after jumping through a few hoops.
I described the approach in the page below, if someone knows a better approach please let me know:
http://thebogles.com/blog/2007/12/using-gmails-greasemonkey-api-from-a-firefox-extension/
Is there an API to manipulate / get hold of the chat frame?
Just to clarify, I'm talking about what used to be the iframes that contained chat conversations.
...respect.
I've looked at the API and example and I can't see how to do the one thing I most want to do: display and compose mail in a different font. Any pointers...?
Just one word.... GRAAACIASSS!!!!!!
is there any API to Work with GMAIL Settings?
Note that a recent Greasemonkey security update may affect your scripts. See http://wiki.greasespot.net/0.7.20080121.0_compatibility
This seems to be WebKit?/Safari only: I noticed that the gmonkey object has been removed from the window object. (It happened about two days ago). It can now be found on the 'js' frame. I checked Firefox and there it is still on window object. For GreaseKit? users it would be great if the object could be found at same place as in Firefox, this makes porting scripts much easier. Thanks!
How can I add a function\event for the time after gmail refreshes?
Hello, how can I use the opener-object with Gmail and the API? Please, i need a example for/with a popup?
How do i update?
Hello, is possible insert my "gmail chat state" in my personal website? Thanks!
To get it to work in Safari/WebKit?/MailPlane? with GreaseKit?, you can employ the loader trick used in http://userscripts.org/scripts/show/23408 instead of the above, as GreaseKit? has no unsafeWindow.
"Resistance, as they say, is futile. It would also be somewhat hypocritical."
one of the many reasons I not only love Google, but also respect its creators.
<3
nanci0830@gmail.com i wanted to be able to contact someone who can tell me how to reduce the amount of spam. I receive over 560 spams in one day, I'm going to delete my acct cas it's too aggrevating. 802-273-3831 home
I have used the following...
var compose = gmail.getActiveViewElement(); var divs = compose.getElementsByTagName('div'); divs7?.innerHTML = "smart attach";
but it seems that I cannot actually impact the innerHTML of div7?... any ideas? I tried setting a timeout and had no luck either
rjonesx@gmail.com
The getFooterElement method is buggy. Simply calling it makes the entire API crash, and any other scripts that use the API also stop working.