How to create Gmail sidebar gadgets
Google Mail or Gmail provides developers with an extensibility model in the form of Gmail gadgets. Gmail gadgets come in two flavors: Sidebar gadgets and contextual gadgets.
Sidebar gadgets are shown on the left hand side of the Gmail user interface, just underneath the list of folders – this can be compared to setting your Add-in Express Advanced Task pane’s ExplorerLayout property to BottomNavigationPane.
Contextual gadgets are gadgets that run when certain clues are detected in Gmail. This can be a based on text in the subject or in the message body. For example the translate gadget in Gmail is automatically shown when a foreign language is detected.
- Creating the Gmail sidebar gadget
- Specifying the Google gadget preferences
- Specifying the sidebar gadget content
- Adding the Google sidebar gadget to Gmail
- Testing your custom Gmail gadget
How to create the Gmail sidebar gadget
In this article, we’ll create our own Gmail gadget that will display the latest Add-in Express blog posts in a sidebar gadget. A Google sidebar gadget is essentially a page, which can contain HTML, CSS or JavaScript, that runs inside an iframe inside the Gmail UI.
A sidebar gadget is made up of a spec that is used to specify various properties of the gadget and also contains all the code. You have a choice between two content types, which is either html or url. Setting the spec’s content type to url means the gadget resides on a remote web page and you cannot add any CSS, HTML or JavaScript to the spec itself.
Whereas, setting the content type to html means the gadget spec contains everything the Google gadget needs to run, including all its CSS, HTML and JavaScript. Html is also the preferred content type for sidebar gadgets.
A basic google sidebar gadget is made up of standard XML, which contains three elements:
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs /> <Content type="html"> <![CDATA[ Content goes here ]]> </Content> </Module>
Specifying the Google gadget preferences
The ModulePrefs element contains various settings and preferences for your gadget and the Content element contains all the code that makes up the Gmail sidebar gadget. It is important that all your CSS, HTML and JavaScript that make up the gadget are contained inside a CDATA tag. This will ensure that the markup for the gadget is not interpreted as XML.
In the following example, we’ll set the title, description, author and thumbnail image for our Add-in Express Blogs sidebar gadget:
<ModulePrefs title="Add-in Express Blogs" description="Lists the latest Add-in Express Blog posts." title_url="//www.add-in-express.com/" author="Add-in Express Ltd" thumbnail="https://www.coalitionsoft.net/gadgetthumb.png"/>
There is nothing too complicated with the above ModulePrefs element. Take note, though, the thumbnail image needs to be hosted on a server that is accessible via the internet – pointing it to an image on your hard drive will not work!
Specifying the sidebar gadget content
As I’ve mentioned, the content element contains everything that makes up your Gmail sidebar gadget. You can build the gadget content as you would any HTML page – although the gadget content should not include either the <html>, <head> or <body> tags.
We’ll use the jQuery library to assist us with manipulating the page DOM, so we’ll first add a reference to it inside the content element’s CDATA element:
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js" />
Next, we need to add a <div> HTML element which will contain an unordered list element. We’ll add the latest Add-in Express blog post titles to this list. The mark-up will look as follows:
<div> <ul id="news" style="list-style-type: none; margin: 0; padding: 0; font-size: small;"></ul> </div>
You’ll notice we’re using inline CSS to style the elements. This is not necessary as you can include a reference to CSS style sheets in the sidebar gadget in a similar fashion as we’ve included a reference to the jQuery library.
Next, add a <script> tag to the content element. We’ll write two JavaScript functions, one to fetch the latest blog posts from the Add-in Express blog RSS feed and another to read the returned data and load it into the unordered list element. The function to fetch the data is called fetchData, and its code is listed below:
function fetchData() { $('#info').html('Fetching Data'); var params = {}; params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.FEED; var url = "//www.add-in-express.com/creating-addins-blog/feed/"; gadgets.io.makeRequest(url, loadData, params); };
In the above code, we first indicated to the user that our Google gadget is busy fetching the data. We then added a new parameter to the params collection to indicate that the Gmail gadget is fetching a RSS feed by setting the content type to gadgets.io.ContentType.FEED. This is a nice feature from the Google Gadgets API, as it will return the RSS feed items in JSON format, making it much easier to parse using JavaScript. To retrieve the data we called the makeRequest function and passed in the url, callback function name and the parameters.
The callback function will receive the returned data and process it. In our example this function is called loadData, and its code looks like the following:
function loadData(obj) { var items = obj.data.Entry; for (var i = 0; i < items.length; i++) { var item = items[i]; $("#news").append('<li class="list-group-item"><a style="text-decoration: none;" href="' + item.Link + '" target="_blank">' + item.Title + '</a></li>'); } $('#info').remove(); };
The loadData function, iterates over the items returned by the makeRequest function and adds it to the <ul> element whose id is “news”. You’ll notice that we used the item’s Link and Title property, this is contained in the JSON data we received. A visual representation of this data follows below:
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Add-in Express Blogs" description="Lists the latest Add-in Express Blog posts." title_url="//www.add-in-express.com/" author="Add-in Express Ltd" author_email="//www.add-in-express.com/" thumbnail="https://www.coalitionsoft.net/gadgetthumb.png" /> <Content type="html"> <![CDATA[ <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script> <div> <ul id="news" style="list-style-type: none; margin: 0; padding: 0; font-size: small;"></ul> </div> <script type="text/javascript"> function fetchData() { $('#info').html('Fetching Data'); var params = {}; params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.FEED; var url = "//www.add-in-express.com/creating-addins-blog/feed/"; gadgets.io.makeRequest(url, loadData, params); }; function loadData(obj) { var items = obj.data.Entry; for (var i = 0; i < items.length; i++) { var item = items[i]; $("#news").append('<li class="list-group-item"><a href="' + item.Link + '" target="_blank" style="text-decoration: none;">' + item.Title + '</a></li><hr/>'); } $('#info').remove(); }; gadgets.util.registerOnLoadHandler(fetchData); </script> ]]> </Content> </Module>
Adding the custom sidebar gadget to Gmail
Before we can use our sidebar gadget we need to enable the gadget in Gmail. To do this, sign in to your Gmail account and click on the Labs link. Enable the “Add any gadget by URL” lab by clicking Enable radio button:
This will add a new Gadget link at the top of your Gmail window. Click on this new link and paste the url to your custom google gadget in the “Add a gadget by its URL” textbox. Make sure the newly created Gmail gadget is on a server that is accessible via the internet or else it will not work.
Testing your custom Gmail gadget
As soon as you’ve added your own google sidebar gadget you will notice it appeared on the left hand side of the Gmail UI:
And now you can get updates of the latest Add-in Express blog posts right inside your Gmail!
Thank you for reading. Until next time, keep coding!
2 Comments
It’s a shame that the ‘Add any Gadget by Url’ lab has been deprecated. It’s almost par for the course as far as Google terminating useful services.
I can’t understand Google minding with this…
Why do they break this great tool ?
Shame and pitiful.