Developing Gmail contextual gadgets
In my last article, we explored How to develop Gmail sidebar gadgets. In today’s article we’ll take a closer look at what is involved in creating a contextual gadget for Gmail. Gmail contextual gadgets are a good way to add additional functionality to Gmail allowing your user to perform tasks right from inside their Gmail session.
Contextual gadget components
A contextual gadget is essentially made up of the following 3 parts:
The manifest file is used to describe the structure and content of an application. The manifest file is the starting point for any contextual Gmail gadget. Our sample contextual gadget will scan the body text of an e-mail for a number of key words and return a search result from the Add-in Express forums and blog posts. Our manifest file for the sample google gadget will look like the following:
<?xml version="1.0" encoding="UTF-8" ?> <ApplicationManifest xmlns="https://schemas.google.com/ApplicationManifest/2009"> <Name>ADX Answers</Name> <Description> Answers to Add-in Express questions inside your e-mail. </Description> <Extension id="ADXExtractor" type="contextExtractor"> <Name>ADX Stuff</Name> <Url>google.com:EmailBodyExtractor</Url> <Triggers ref="ADXGadget"/> <Scope ref="emailBody"/> <Container name="mail"/> </Extension> <Extension id="ADXGadget" type="gadget"> <Name>Add-in Express Gmail contextual gadget</Name> <Url>https://www.coalitionsoft.net/context-gadget.xml</Url> <Container name="mail"/> </Extension> <Scope id="emailBody"> <Url>tag:google.com,2010:auth/contextual/extractor/BODY</Url> <Reason> This application searches the message body of each email for text related to Add-in Express products. </Reason> </Scope> </ApplicationManifest>
In the manifest file, we specified the name and description of our application. We also created a new extension called ADXExtractor which will extract content from the e-mail message body. This is accomplished by creating a <Extension> element and setting its child <Url> element’s text to google.com:EmailBodyExtractor, the <Scope> element’s ref attribute to emailBody and the <Container> element’s name attribute to mail. Next, we’ll specify another extension, which will be a reference to our gadget spec. All we need to set for the gadget extension is the <Name> element and the <Url>. The gadget should be hosted on a publicly available server. Finally, add a <Scope> element to indicate which part of the e-mail the gadget needs to access. This is also used to show the user information about the gadget when they are installing it, as illustrated below:
A contextual gadget is triggered based on text matches found in one of the following e-mail fields:
- Email message body
Matching is accomplished using an extractor. You have a choice of building your own extractor or to simply use one of Google’s pre-canned extractors. Google supplies us with 15 extractors out of the box:
|google.com:EmailAddressExtractor||Finds e-mail address in the subject and message body of the e-mail.|
|google.com:EmailBodyExtractor||Retrieves the first 1000 characters from the e-mail body.|
|google.com:EmailTimeExtractor||Retrieves the sent/receive time of the e-mail.|
|google.com:HelloWorld||Finds “Hello World” in the body and subject fields of the e-mail message (Case insensitive)|
|google.com:HttpLinkExtractor||Returns links to HTTP and HTTPS address inside the message subject and body.|
|google.com:ListExtractor||Finds the list ID and unsubscribe link/e-mail address inside the message.|
|google.com:MessageIDExtractor||Returns the Gmail internal message id|
|google.com:RawSubjectExtractor||Returns the e-mail’s subject line. It contains all annotations such as FW: and RE:|
|google.com:RecipientCCEmailExtractor||Returns all the e-mail address inside the CC fields|
|google.com:RecipientEmailExtractor||Returns all e-mail address for the e-mail, including the TO and CC fields.|
|google.com:RecipientToEmailExtractor||Only return e-mail addresses inside the TO field of the e-mail.|
|google.com:SenderEmailExtractor||Returns the sender’s e-mail address. This value is stored in the FROM field of the e-mail.|
|google.com:SubjectExtractor||Returns the subject of the e-mail with all annotations (FW, RE, etc.) removed.|
|google.com:USPhoneExtractor||Returns all US based phone numbers inside the e-mail message. The format for the phone numbers are : ((1) 800 ) 555-1234)|
|google.com:USStockTicker||Matches US stock symbols in the body and subject fields of the e-mail message.|
The code for our gadget spec follows below:
In our gadget code above, we first included references to the Bootstrap library’s CSS style sheet – we’ll use Bootstrap to style our user interface components. We have also included a reference to the jQuery library in order to make it easier to manipulate the DOM. Next, we’ve created an empty <div> element, which will contain the search results. We then called the getContentMatches function, in order to get a reference to the message body, using the following code:
matches = google.contentmatch.getContentMatches();
Using a number of regular expressions, we checked whether the message body contained a number of pre-set search strings and then passed the search query to our search function on the Add-in Express site. To request JSON data from an external server, you’ll need to use the makeRequest method and set its ContentType parameter to JSON. We’ve also specified that the callback method is called loadData and this method will receive the data back from the Add-in Express search service and add the items to the “links” <div> element.
Deploying Google contextual gadget
Before we can test our google gadget, we need to deploy it. First sign into your console at: https://code.google.com/googleapps/console/a/mydomain.com. Substituting the mydomain.com part with your own domain name. After you’re logged in, create a new project by clicking on the “Create project…” button.
When prompted, enter a name for your new project:
Next, upload the manifest file we’ve created earlier. If it is in the correct format, it should display the application name and description as illustrated below:
With the manifest file uploaded, we’re ready to deploy the application. Do this by clicking on the “Deploy Application…” button.
A new window will open, prompting you to grant data access for the application. Click on the “Grant data access” button to proceed. A confirmation message should pop up and indicate that your application was successfully installed on your domain.
Testing your Gmail contextual gadget
After you’ve deployed your application, you can log into your Gmail account and if a message contains the appropriate words, our contextual gadget will display the Add-in Express search results below the message, as illustrated in the following image:
Thank you for reading. Until next time, keep coding!