Google Toolbar API – Guide to Making Custom Buttons

What is a Custom Button?

A custom button is a push button that you can add to the Google Toolbar that can have custom navigation, search, send and update capabilities. Notably, a custom search button can use most any website’s search engine, not just Google’s.

When clicked on, a search button can perform any of the following tasks:

• Navigate the browser to a website, like a bookmark
• Navigate the browser to a website and run that website’s search engine, searching for the text the user has typed into the toolbar search box. For example, a Wikipedia button would go to wikipedia.org and search for the term you’ve entered. (It can go to any one of a number of locale-specific websites based on the toolbar’s locale.)
• Send the currently selected browser text to a service, such as to compose a new email, blog entry or text message
• Update its button icon, tooltip, and dropdown list of icons and strings from an RSS feed
• Open a gadget in a small dropdown window New!

A custom button can have the following user interface features:

• An icon representing the website it accesses or action it performs (<icon>). This icon can be updated from an RSS feed (<feed>)
• A dropdown list of icons and strings (accessed by clicking a down-arrow button) which can get updated from an RSS feed, such as headlines from a news feed (<feed>)
• A tooltip description, which appears momentarily when the mouse pointer hovers over the button (<description>)
• A title that can optionally appear next to the button (<title>)
• A dropdown gadget window (accessed by clicking a down-arrow button) (<gadget>) New!

In addition to properties for the above user interface features, a custom button can have the following properties (saved in an XML file) that perform the tasks listed above:

• A website URL to navigate the browser to when the search box is empty and button is clicked (<site>)
• A search URL pointing to a website that the browser will navigate to and search when the button is clicked with a search term in the search box (<search>)
• A send URL pointing to a website that the browser will navigate to and send the currently selected text to (<send>)
• An update URL, where updates for the button can be accessed (<update>)

The following toolbar shows examples of custom buttons for Slashdot, Wikipedia and BBC (highlighted). The BBC button is a news feed with a drop-down list of headlines (as indicated by the down arrow).

Adding a Custom Button

To add or manage custom buttons on the Google Toolbar:

• The simplest and most common way for a user to add (install) a custom button is by simply clicking a button directly on a publisher’s website and confirming that you want to add it. A list of such buttons is at Google Toolbar Button Gallery. The publisher uses a special command URL that prompts the user for permission. If the user does not have the Google toolbar installed, the command URL goes to the toolbar download page.
• The second way is Automatically Creating and Adding a Custom Search Button, where a user right-clicks on a search text-entry box.
• The third way is to edit a custom button using the Google Toolbar advanced button editor, available from Settings > Options > Custom Buttons (tab) > Edit > Use the advanced editor.
• The fourth way is Manually Creating and Installing a Custom Button.
• The fifth way is for IT administrators to publish custom buttons on Windows machines using a group policy string to a URL with an XML file, or by wrapping the installer to write a file to the “All Users” application data section of the Windows file system.

Automatically Creating and Adding a Custom Search Button

1. Open Internet Explorer to the search page you want to create a search button for.
   Example: www.wikipedia.org
2. Right-click on the search box on that page that you want to use, select “Generate Custom Search…”, then click “Add”.

Result: The custom button is installed and immediately available for use.

Behind the scenes, this procedure creates a custom button XML file with an icon, and saves it under a hashed name in:

C:Documents and SettingslarryLocal SettingsApplication DataGoogleCustom Buttons

This approach has an advantage over manually constructing a custom search button, in that it is useful for web sites that use complex POST requests or use redirections on their sites that make it difficult to determine the url-template.

Custom Button XML File

A custom button’s properties and behavior are defined in an XML file with a <custombuttons> element whose namespace is set to “http://toolbar.google.com/custombuttons/” with a nested <button> element. The simplest custom button uses <site>, which defines a link to a website. The following XML produces a button that, when clicked, opens http://www.wikipedia.org in the current browser window:

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">

  <button>
    <site>http://www.wikipedia.org</site>
  </button>
</custombuttons>

NOTE – It is okay to include newlines and spaces anywhere in URL strings in the XML file — the toolbar will strip them out when it interprets the file. This means you need to make sure that if your URL requires spaces (you don’t want them stripped out), that you replace them with “%20” (if the browser hasn’t already done that for you). Many of the following examples show the URL typed on two lines with a newline in the middle of the URL, which works just fine.

NOTE – Throughout the examples in this guide, only the portion of the XML code inside the <button> element changes.

Manually Creating and Installing a Custom Button

To install a custom button to the Google Toolbar:

1. Create a button XML file as shown in the previous (and following) sections.
2. Save the button’s XML file at:

   C:Documents and SettingsusernameLocal SettingsApplication DataGoogleCustom Buttonsfilename.xml

   where username is your Windows login name and filename is the file name you choose to give the XML file.

   In our Wikipedia example, for login name “larry”, save the button’s XML file at:

   C:Documents and SettingslarryLocal SettingsApplication DataGoogleCustom Buttonswikipedia.xml

3. Then open a new Internet Explorer window with Google Toolbar 4.0 installed. A new button appears with a question mark image, as shown in the following screenshot — clicking the question mark icon goes to Wikipedia.

   

Adding a Button Title and Tooltip

As shown next, use <title> to add a button title. The title can appear to the right of a button (Settings > Options > More > Button text labels > All text), and identifies the button in the custom button list (Settings > Options > Custom Buttons). If your button does search, the title should be unique to all your search custom button title, as it also functions as that button name in the Google Toolbar search box. (For example, the user can go to the search box with Alt-G, press the down arrow to pull down the search engine menu, then type “w” in the search box to select the “wikipedia” search engine.)

Use <description> to add a tooltip.

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <site>http://www.wikipedia.org</site>

    <title>Wikipedia</title>
    <description>The Free Encyclopedia</description>
  </button>
</custombuttons>

Custom Search Button

The Google Toolbar also enables you to create a button to execute most any website’s search engine using the term the user types into the toolbar search box. The next two examples include a button to search the wikipedia.org using the Wikipedia search engine, and another button to search the Internet using the Google search engine.

To do this, add a search element in the form <search> url-template </search> to the button’s XML file. Include a search query URL using the {query} variable, as shown in the following examples. Both GET and POST queries are possible (specified using the method attribute) — GET is the default. The URL must be http: or https: based — javascript: is not allowed. Three characters in url-template must be escaped: less-than (<), greater-than (>), and ampersand (&).

NOTE – A <search> element must contain a {query} variable or the button will fail to display.

Custom Button for Wikipedia Search

For example, to create a button to search wikipedia.com using the Wikipedia search engine, start with the simplest Wikipedia query for any term, such as “dog”: http://en.wikipedia.org/wiki/Special:Search?search=dog&fulltext=Search. To instead search for the term the user types into the toolbar search box, replace “dog” with “{query}” and escape the ampersand (&) as follows:

<search>http://en.wikipedia.org/wiki/Special:Search?
    search={query}&amp;fulltext=Search</search>

Adding this search element to the previous button, we get:

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <site>http://www.wikipedia.org</site>

    <title>Wikipedia</title>
    <description>The Free Encyclopedia</description>
    <search>http://en.wikipedia.org/wiki/Special:Search?
        search={query}&amp;fulltext=Search</search>

  </button>
</custombuttons>

Notice that the ampersand (&) in the URL is escaped as “&“. Strings in XML files need ampersand (&), less-than (<) and greater-than (>) characters escaped.

Custom Button for Google Search

To create a button to search the Internet using the Google search engine, start with the simplest Google query for any term, such as “dog”: http://www.google.com/search?q=dog. Then replace “dog” with “{query}” as follows:

<search>http://www.google.com/search?q={query}</search>

Here is an example:

Slashdot Search

<search>http://slashdot.org/search.pl?query={query}</search>

Send Search Action as POST

To send search actions as POST instead of GET, include a method="post" attribute in the search element. Everything after the last question mark ‘?’ will be sent as www-urlencoded form postdata. It is possible for a web site to use form-encoded data instead of url-encoded data, and we do not currently support that. Also, it is possible to send CGI parameters and post data at the same time — to do this, use two question mark ‘?’ symbols.

The Onion Search

This example uses a post method to send postdata (highlighted):

<search method="post">http://www.theonion.com/content/search/node
        ?edit%5Bkeys%5D={query}</search>

Updating a Custom Button

The download URL you use to host the XML file for the button becomes the button’s unique ID for updating the button. If a second attempt is made to download a button from the same URL, the toolbar will offer only to replace the old one, not add a new one.

Of the five ways to add a button, the first and last ways automatically know where the button updates should come from, and any <update> value written into the XML file is ignored. For the middle three ways, you can specify the <update> element in the XML file to specify where the button should look for its updates.

<update>http://buttons.com/updated_button.xml</update>

Button Options

A button may specify a locally defined option string using the <option> tag that the user can easily change in the toolbar settings dialog box. This is useful, for example, in the case of a weather button to specify a zip code or a stock button to specifiy a ticker symbol. For example:

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <title>Weather</title>
    <option>

      <title>Zip code</title>
      <description>Enter a US zip code.  For example, 94043 is Mountain View, CA</description>
      <default>94043</default>
    </option>

    <site>http://www.google.com/search?q=weather+{option1}</site>
  </button>
</custombuttons>

The option title is required. The default and description are not. Use the variable {option1} inside of any url template specification to insert the user’s text.

There is no validating or whitespace trimming of the input at this time, and the {option1} variable will escape whatever the user typed in using charset encoding (utf-8) and cgi parameter escaping, just as a text edit box on a form submit would.

Including the Current URL

Besides sending the search query, you can also specify the current URL the browser displays three different ways: {url} with encoding, {url.noescape} without encoding, or {url.host} just the website.

This example uses {url.noescape} to send the current URL to archive.org to look for an older version of the current page — archive.org requires the unescaped URL:

<site>http://web.archive.org/web/*/{url.noescape}*</site>

The following example will do the same archive.org search but using {url}:

<site method="post">http://www.archive.org/searchresults.php?
search={url}&amp;mediatype=mediatype&amp;Submit=Submit</site>

And if you want to use the Google search engine to search within the current web site, use {url.host} — this is a powerful shortcut, one not possible from the Google website.

<search>http://www.google.com/search?q=site:{url.host}+{query}</search>

Including the Google Domain Suffix

Google Toolbar has a variable {domain} for getting the domain, such as com or co.uk.
The search domain can be found in the Google Toolbar at Settings > Options > Search tab > Use Google site — it’s the string following the “google.” term.

You should use variable {domain} instead of hard-coding the domain string. So a Google search should really be written as:

<search>http://www.google.{domain}/search?q={query}</search>

Sending User Selected Text

You can also allow a custom button to send a piece of plain text that might be selected on the web page by the user. This could be useful for a translation service, or maybe a blogging or messaging application. A small text icon appears on the custom button icon when text is selected.

This operation requires the <send> element. The URL target of the <send> operation can be different from the target of <search>. The <send> tag should include the variable {selection}, which resolves to the plain text currently selected in the browser:

<send>http://www.google.com/search?hl=en&amp;lr=&amp;q=define%3A+{selection}</send>

Custom buttons with send operations will also appear on the right-mouse-button context menu of the browser when text is selected.

Testing If a Variable Exists or Not

As the toolbar evolves, more URL variables may be implemented. In order to provide forward and backward compatibility with these new variables, the {a?b:c} syntax will be available in all custom button aware parsers, with the following semantics:

{param_to_be_tested?use this text if the param is implemented:use this text if not}

Put simply, it allows the author of an advanced custom button to safely use a new feature, and allow for backward compatibility with old parsers that do not know about the new feature. For example, pretend that the {locale} variable was just introduced. A URL template like this could be used to make sure it had no effect on older toolbars:

<site>http://www.google.com/{locale??hl={locale}}</site>

If the toolbar supports the {locale} variable, this would expand to:

<site>http://www.google.com/?hl=en</site>

If not, then:

<site>http://www.google.com/</site>

You can nest {a?b:c} expressions up to 10 levels deep as long as the nesting happens after the “?”. This is OK:

<site>http://www.google.com/{locale??hl={domain?{domain}:{query}}}</site>

It should also be noted that any time an escape is used that is not recognized, the parser will substitute an empty string. So Hell{blah}o World. will just come out as Hello World. And if there is an unbalanced number of curly brace ‘{‘ or ‘}’ characters, or any other parse problem, the whole URL will just get reset to an empty string.

How to Make Good-Looking Icons

Most icons that are used as favicons can also be used as custom button icons. These include 16×16 BMP, ICO, GIF, and JPEG images. You just need to encode them into ASCII text using base64 encoding. There are several sites on the Internet that will do the encoding for you — for instance, this one. On that site, use the “Browse…” button to select the file you want to encode, then click the “Convert the source data” button to start the encoding. Javascript and PHP also have single line commands for base64 encoding.

Here is a Gmail icon in base64 — use an <icon> element:

    <icon mode="base64" type="image/x-icon">
AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAQAQAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4ONr/ODja/6en+f+np/n/p6f5/6en+f+np/n/p6f5
/6en+f+np/n/p6f5/6en+f+np/n/p6f5/zg42v84ONr/ODja/zg42v/i4v//////////////////
/////////////////////////////////////+Li//84ONr/ODja/zg42v84ONr/p6f5/+Li////
/////////////////////////////////////////+Li//+np/n/ODja/zg42v84ONr/ODja/+Li
//+np/n/4uL/////////////gYHy/4GB8v///////////+Li//+np/n/4uL//zg42v84ONr/ODja
/zg42v//////4uL//6en+f+2tv//gYHy/1pa6f9aWun/gYHy/7a2//+np/n/4uL///////84ONr/
ODja/zg42v84ONr///////////+2tv//gYHy/1pa6f84ONr/ODja/1pa6f+BgfL/trb/////////
////ODja/zg42v84ONr/ODja////////////gYHy/1pa6f84ONr/trb//7a2//84ONr/Wlrp/4GB
8v///////////zg42v84ONr/ODja/zg42v//////gYHy/1pa6f84ONr/trb/////////////trb/
/zg42v9aWun/gYHy//////84ONr/ODja/zg42v84ONr/gYHy/1pa6f84ONr/trb/////////////
//////////+2tv//ODja/1pa6f+BgfL/ODja/zg42v84ONr/ODja/zg42v84ONr/trb/////////
/////////////////////////7a2//84ONr/ODja/zg42v84ONr/ODja/zg42v84ONr/gYHy/6en
+f+np/n/p6f5/6en+f+np/n/p6f5/6en+f+np/n/gYHy/zg42v84ONr/ODja/wAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAA//8AAP//AAD//wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAD//wAA//8AAA==
    </icon>

Custom button icons can be larger than 16×16, but the toolbar will scale them down to 16×16, so besides being larger than necessary, they will not look nearly as good as if you scaled them using a high quality image editor.

The best looking icons are those that are made using 24 bits of color (RGB) and 8 bits of alpha, and saved as XP-style RGBA icons. You can save the icon as a 16×16 PNG with alpha transparency, and then convert that into an XP-style 16×16 icon (using a program like IconWorkshop), and then base64-encode that. PNG files are not supported directly since Windows does not natively support PNG files without linking in a lot of extra stuff.

The reason you need to use an alpha channel is because not everyone’s toolbar background color is going to be the same gray, silver or beige that yours is set to. Windows XP allows users to customize their color scheme, including toolbar backgrounds. You could get around this by making a square icon that doesn’t have any transparent parts, but they don’t look as interesting. Single color alpha channels, like GIF images, will have grainy-looking rounded exterior edges compared to a properly built alpha-blended icon, such as the ones on the Google Toolbar or Internet Explorer itself.

Auto-Updating Icons and Tooltips

One of the more interesting things a custom button can do is update its own button image and tooltip from a remote server at specific intervals. It uses an RSS feed to do the updating. This allows a button to be used as a notification device, or as a status icon (for example, the weather, or whatever you can imagine). A button can also have a drop-down menu with individual items with text or icons. Each menu item can have its own dynamic URL to launch when clicked on.
Examples of these are given in the next section.

Adding an RSS Feed

RSS feeds use the <feed> element. Here is an example of a CNN news feed:

<feed refresh-interval="1800">http://rss.cnn.com/rss/cnn_topstories.rss</feed>

The protocol for getting these update feeds is either Atom 1.0, Atom 0.3, RSS 2.0, or RSS 1.0. Standard feeds will usually work.

To update the icon on the toolbar, or its tooltip description, from a feed, you
need to add a toolbar-specific extension to RSS or ATOM using a
namespace. Here is an example of a mood ring button that pulls from a
feed:

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <title>Mood ring</title>
    <description>Your virtual mood ring</description>

    <site>http://www.google.com/search?q=mood+ring</site>
    <feed menu="false" refresh-interval="900">
          http://www.example.com/custombuttons/samples/feeds/mood</feed>
  </button>
</custombuttons>

Notice it specifies menu="false" to indicate that this feed is used only to update the icon and tooltip, not to populate a dropdown menu of subitems.

If this were set up on an actual server, the feed output would look like this:

<?xml version='1.0'?>
<feed xmlns='http://www.w3.org/2005/Atom' 
    xmlns:gtb='http://toolbar.google.com/custombuttons/'>
<id>http://www.example.com/custombuttons/samples/feeds/mood</id>

<title>Mood</title>
<link href='http://www.google.com/search?q=+ring' />
<link rel='self' 
    href='http://www.example.com/custombuttons/samples/feeds/mood' />
<gtb:description>Bluegreen:
Inner emotions charged, somewhat relaxed</gtb:description>
<gtb:icon mode="base64" type="image/x-icon">
AAAAAAMAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAAwAAAAMAA
AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAQAQAAAAAAAAAAAAAAAAA
AAAAAAAAAAAGAAAAHAAAAEAAAABhAAAAcwAAAHQAAABpAAAAVQAAAD4AAAApAAAAGAAAAAoAAAAD
AAAAAQAAAAAAAAAAAAAAESZIXl4zdJvAXbHS8m3C3f9LnrrLFUtsmwILEX4AAABzAAAAYQAAAEcA
AAAqAAAAEwAAAAcAAAACAAAAACs9RTNOjrDtW6nS/53u/f+n/P//hej//2bP/P9Fq93wHGaNrxEv
O4kAAAB6AAAAXwAAADwAAAAfAAAADAAAAANihaWST6XK/0h/kcAdKCyWKTtAgVJ/kIhytNKse873
9E+w6v9RuN39SXuJpgQHCIoAAAB2AAAAUQAAACsAAAAPb6nU7mK65v9jqs76KkNPqAUICJoAAACE
AAAAaxUgJWBkrMiwsvv+//D+/v+y1NniIj1FnAAAAIgAAABcAAAALHS74PV1zPn/c835/1Oezv9N
iq7vNVRjrxUiJ5kBAgORAQICh3uLjZz3+vr1+f///4PL5/wvVmusAAAAigAAAFNyu+TPdtL8/0Cp
7v8ng8X/CFOH/ytpjv86gJ//R46z+Th6jsovVmCsd56pxNf2/f9TuPH/W7fs/ypGV6UAAAByf77Y
r02y7P9Zwfb/puH3/y+AtP8jZ5f/KWKH/0p7hP+ZrVr/zcUt/9vMKf/bzSz/tsBP/3OzrP9kl7Pp
AAAAgHGdpThatuT/0fn+//b///+V0uv/NICu/4mvfP/czjL/3M0v/9rMKP/dzzT/3c83/9vNLf/b
zS//nrWA/gAAAIMAMzMFbrrd2d/+///5////t+n6/4q6nf/czzX/3tA+/97QPf/czjP/3dA7/97R
Qv/czjD/3M4z/9DHLPoAAAB/AAAAAWShtUix5+//5v7+/5Hf7//Bvjn/3M0v/9/SSP/g1FL/39RR
/+DVWv/e0kf/3tFA/9zNL//bzCj/AAAAbwAAAAAAAAADcq7Fmpzo8f9rsL3/2ssl/93POf/f0kj/
49pu/+ffhP/q45b/49pp/97SSv/czS//yb0q4wAAAE8AAAAAAAAAAF54hhNrq77BXpCj/7+7Of/c
zjH/3tFH/+bdeP/w7cv/9PLa/+zlnf/g1VP/1so5/mBfJHsAAAArAAAAAAAAAAAAAAABa5GgIHWs
t/dymG3/3tE//9/UUv/o4Ij/9PHT//v67P/v6a3/08xY/3uMX6UAAAAuAAAAEAAAAAAAAAAAAAAA
AAAAAAKSvb9YSoWa+WyagP+wv2X/4NRO/+ngfv/m4Zf/rLeB+lpubIkAAAAlAAAADgAAAAMAAAAA
AAAAAAAAAAAAAAAAAAAAAoqvuDxkkp2gYo+c51mHkv9lk5v/Y4eNtlBfaEgAAAAWAAAACQAAAAIA
AAAAAAMAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAAwAAAAMAA
AADgAAAA8AEAAA==
</gtb:icon>

</feed>

The above example is an Atom 1.0 feed, with the Google custom buttons namespace specified as:

xmlns:gtb='http://toolbar.google.com/custombuttons/'

To override the tooltip that came with the button, specify:

<gtb:description> new-description </gtb:description>

To override the icon that came with the button, specifiy:

<gtb:icon> icon-base64-code </gtb:icon>

Icons embedded in feeds may also be specified by http or https urls to ico, jpg, gif, or bmp images: New!

<gtb:icon> http://your icon </gtb:icon>

The PHP script that powers this complex “mood” analysis system looks like:

<?php

header('Content-type: text/xml');

switch(rand(1, 7)) {
  case 1:
    $icon = "amber.ico";
    $desc = "Amber:nNervous, on edge, uncertain";
    break;

  case 2:
    $icon = "black.ico";
    $desc = "Black:nTense, stressed, working too hard";
    break;

  case 3:
    $icon = "blue.ico";
    $desc = "Blue:nComfortable, breeze, at rest, loveable";
    break;

  case 4:
    $icon = "bluegreen.ico";
    $desc = "Bluegreen:nHeightened inner emotional state, moderately relaxed";
    break;

  case 5:
    $icon = "gray.ico";
    $desc = "Gray:nAnxious, ill at ease, strained";
    break;

  case 6:
    $icon = "green.ico";
    $desc = "Green:nSteady, stable, no emotional turmoil";
    brea;

  case 7:
    $icon = "purple.ico";
    $desc = "Dark Blue:nImpassioned, delighted, whiff of romance";
    break;
}

$icon = base64_encode(file_get_contents($icon));

echo "<?xml version='1.0'?>";
echo "n<feed xmlns='http://www.w3.org/2005/Atom'";
echo " xmlns:gtb='http://toolbar.google.com/custombuttons/'>";
echo "n<id>http://www.example.com/custombuttons/samples/feeds/mood</id>";
echo "n<title>Mood</title>";
echo "n<link href='http://www.google.com/search?q=$mood+ring' />";
echo "n<link rel='self' href='http://www.example.com/custombuttons/samples/feeds/mood' />";
echo "n<gtb:description>$desc</gtb:description>";
echo "n<gtb:icon mode='base64' type='image/x-icon'>$icon</gtb:icon>";
echo "n</feed>";

?>

The icons should be in the same folder as the script.

Using a Feed to Update the Button and Dropdown Menu Icons

You can also add custom server-based icons to the individual items on the feed dropdown menu.
Here is an example of a weather button that has a feed with a dropdown menu (the default)
but also specifies refresh-menuitem="false" to hide the refresh menu item any time
a successful connection is made to the server. This provides a cleaner look.

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <title>Weather 94043</title>
    <description>Weather updates for Mountain View, CA</description>

    <site>http://www.google.com/search?q=weather+94043&num=1</site>
    <feed refresh-interval="3600" refresh-menuitem="false">
        http://www.example.com/custombuttons/samples/feeds/weather?zip=94043</feed>
  </button>

</custombuttons>

Following is a sample of what the weather feed looks like, with a custom icon next to each menu item in the dropdown (with most of the icon base64 stuff removed for clarity). Given the above example, this would be visible at: http://www.example.com/custombuttons/samples/feeds/weather?zip=94043

<?xml version='1.0'?>
<feed xmlns='http://www.w3.org/2005/Atom' 
    xmlns:gtb='http://toolbar.google.com/custombuttons/'>
<id>http://www.example.com/custombuttons/samples/feeds/weather</id>

<title>Weather Mountain View, CA</title>
<link href='http://www.google.com/search?q=weather+94043/' />
<link rel='self'
    href='http://www.example.com/custombuttons/samples/feeds/weather' />
<gtb:description>Mountain View, CA
63F Mostly Cloudy
Humidity: 48%
Wind: NW at 8 mph</gtb:description>
<gtb:icon mode='base64' type='image/x-icon'>
R0lGODlhKAAoANUAAEuc/Pz8/Fik/Ii00k9daZGPivLy8tbW1k2R0uvr6wZj3HSq0f/QMMfHx7a2
tj2F0fu0EePj4yx81neUp4J/eKanphJq3IJtOGB3iI3C5BFt5B5XnWis7H2346jO5/6+IWKo8923
... and so on...
</gtb:icon>

<entry>
<title>Today: Mostly Cloudy 65 | 50</title>

<link href='http://www.google.com/search?q=weather+94043/' />
<id>http://www.example.com/custombuttons/samples/feeds/weather/0</id>
<gtb:icon mode='base64' type='image/x-icon'>
R0lGODlhKAAoANUAAEuc/Pz8/Fik/Ii00k9daZGPivLy8tbW1k2R0uvr6wZj3HSq0f/QMMfHx7a2
tj2F0fu0EePj4yx81neUp4J/eKanphJq3IJtOGB3iI3C5BFt5B5XnWis7H2346jO5/6+IWKo8923
... and so on...
</entry>

<entry>
<title>Thu:  66 | 51</title>
<link href='http://www.google.com/search?q=weather+94043/' />
<id>http://www.example.com/custombuttons/samples/feeds/weather/1</id>
<gtb:icon mode='base64' type='image/x-icon'>
R0lGODlhKAAoAPcAAAAAAP///4WOwPT1+tDT3unr8sHG1ff5/6Wy0mZ8rGqAr3mJrJakxa+zvHSK
tcDBw1R2slBql110njBXjztmqS9OfjtekTZWhGeJuoqctklLTgJYyQJQtQ9hzhRr3BZlzBVRoS1S
... and so on...
</gtb:icon>

</entry>

<entry>
<title>Fri:  67 | 51</title>
<link href='http://www.google.com/search?q=weather+94043/' />
<id>http://www.example.com/custombuttons/samples/feeds/weather/2</id>
<gtb:icon mode='base64' type='image/x-icon'>

R0lGODlhKAAoANUAAObm52ms7k2Q0Uuc/Fmk+v2zDoS01HOp0avP5tvb26CPXQZj3DqG14yLh05Y
Yf/IKv/VN3mCiMPDw6SkpCt82GhxePz8/JG+2pd5NRZu3hBq3fb29rCAFrm5uSN549OWE4WltqHI
... and so on...
</gtb:icon>
</entry>
<entry>
<title>Sat:  67 | 50</title>
<link href='http://www.google.com/search?q=weather+94043/' />

<id>http://www.example.com/custombuttons/samples/feeds/weather/3</id>

<gtb:icon mode='base64' type='image/x-icon'>
R0lGODlhKAAoANUAAObm52ms7k2Q0Uuc/Fmk+v2zDoS01HOp0avP5tvb26CPXQZj3DqG14yLh05Y
Yf/IKv/VN3mCiMPDw6SkpCt82GhxePz8/JG+2pd5NRZu3hBq3fb29rCAFrm5uSN549OWE4WltqHI
... and so on...
</gtb:icon>
</entry>
</feed>

You can use the same ‘http://toolbar.google.com/custombuttons/’
namespace and description or icon tags in RSS 1.0, RSS 2.0, Atom 1.0
and Atom 0.3 feeds for the toolbar feeds as well.

You can display a small amount of status text next to the title of a toolbar button
using a toolbar-specific namespace extension to RSS or ATOM. If the user has button
text turned off, the status text will still show next to the button. Here is an example of a
mail feed that will display the number of unread items next to the button title:

<?xml version='1.0'?>
<feed xmlns='http://www.w3.org/2005/Atom' 
    xmlns:gtb='http://toolbar.google.com/custombuttons/'>
<gtb:status>14</gtb:status>
</feed>

You can alert the user to an event using a toolbar-specific namespace extension to RSS or ATOM.
The alert will blink the button’s icon and show a tooltip below the icon. If the toolbar is not
the foreground window, it will flash the title bar of the browser. Here is an example of a
calendar notifier that alerts a user of an upcoming meeting:

<?xml version='1.0'?>
<feed xmlns='http://www.w3.org/2005/Atom' 
    xmlns:gtb='http://toolbar.google.com/custombuttons/'>
<gtb:alert>You have a meeting&lt;br&gt;at 12:00PM</gtb:alert>
</feed>

If the title of a feed item contains all — characters, a menu separator will be used in place of a clickable menu item.

Custom Buttons can now open a gadget in place of a menu drop down. The gadget can be any
new or existing Google universal gadget, however inlined iGoogle gadgets or Google Desktop
gadgets are not supported. The gadget does not have to be in the Gallery or hosted on a
Google server for the gadget to work inside a custom button, but it does need to be publicly
visible from the Internet.

For example, suppose you want a button that shows the current time and date. In the new button API, you can add a link to a date gadget. A gadget mini-window will open when the user clicks on the drop down arrow:

<?xml version="1.0"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <title>Date and Time</title>
    <site>http://www.time.gov/</site>
    <gadget height="136">http://www.google.com/ig/modules/datetime.xml</gadget>
  </button>
</custombuttons>

The toolbar button template can specify the initial width and height of the gadget window as attributes on the <gadget> tag. If they are omitted, the default is 240×280 pixels. For example:

<gadget width="300" height="180">

A toolbar gadget can dynamically update its window height using the Dynamic Height API.

Plus, the user may resize the gadget at any time by dragging the lower-right corner. This preference is saved between sessions. It will also be synced across toolbars if sync is enabled.

A gadget spec has to be hosted from a publicly available web site, and by its nature, is not private. All of the data in the gadget runs through google’s gmodules.com hosting service, which provides supporting libraries and caching. A gadget may perform complex logic inside of javascript or flash movies, and may display anything a web page can. Gadgets are services that may be updated at any time, and do not require user updates. Gadgets require a working Internet connection to function. There are ways of making a gadget redirect to a private page when it opens, but the gadget spec itself needs to be public.

A custom button may be hosted publicly or privately. In fact, it doesn’t need to be hosted at all, as the file can be installed directly. The data of the custom button stays on the local computer, and it may make direct connections to services inside a firewall, whereas a typical gadget cannot. A custom button is a simple template that tells the browser what page to open when it is clicked on or what feed to fetch; it does not perform logic. A custom button does not update itself, therefore whatever it does when it it first installs is what it will always do. A custom button can contain the address of a gadget spec to open when it is clicked and will manage the preferences and size information for the gadget.

Think of gadgets as mini web pages, and custom buttons as multi-function bookmarks. The simplest way to get an existing universal gadget on to your toolbar is to use a gadget-to-custom button conversion script like this one:

Gadget Url:

Add this universal gadget to my toolbar

After adding the gadget, you may wish to open the advanced button editor and tweak the title, description and site tags. You may even wish to add a search template or a custom 16×16 icon.

Many gadgets contain user preferences, such as a city name or an astrological sign. If a button points to a gadget that contains preferences, those preferences can be set alongside the other button preferences in the settings dialog box. In the Google Toolbar 5, button settings may be quickly accessed using the right-click context menu on the button itself.

Toolbar gadgets can update their own preferences dynamically using the SetPrefs API. Gadget preferences are saved between sessions. They will also be synced to other toolbars if toolbar sync is enabled.

Another way to save state information between sessions would be using cookies. One way to access cookies from your own domain is to use content-url to redirect the gadget rendering to your own site. For example, this gadget spec will redirect to www.example.com:

<-- This is a gadget spec, NOT a custom button xml file -->
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Redirect to www.example.com"/>
  <Content type="url"
    href="http://www.example.com/"/>
</Module>

Gadgets can have default preferences, or required preferences that must be set by the user. On top of this, the custom button template may specify initial values for gadget options when the button is first installed. These defaults are of the form of CGI arguments, where each user preference begins with “up_”, and the separator character “&” needs to be escaped in the xml file. For example:

<gadget default-options="up_zipCode=94040&amp;up_units=0">

One of the gadget’s preference variables may be synced to the button’s option1 string variable to eliminate the need for the user to enter it twice. This is useful if, for example, you have a weather button that uses a feed to update status, but it also opens a gadget that already has a zipcode preference variable:

<gadget option1="zipcode">

The dropdown functionality is often more useful than the site or search functionality, especially when it has a gadget. Button authors may choose to make the entire button a dropdown by specifying whole-dropdown="true" in the gadget or feed attributes. For a feed, <site> action will be moved to the first menu item followed by a line separator, unless site-menuitem="false" is used. For a gadget, this will effectively make the <site> action unavailable, but the <search> and <send> actions can take over the dropdown action when the toolbar is in search or send mode. The <site> action still needs to point to a valid url to be backwards compatible with older toolbars.

<gadget width="300" height="180" whole-dropdown="true">
  http://www.calculatorcat.com/gmodules/current_moon.xml
</gadget>

And there is one more thing… If whole-dropdown is set to true, buttons can perform search or send operations using gadgets! See the next section.

If a gadget has whole-dropdown set to true, it is eligible to perform the search or send actions using the gadget itself. For example, suppose you wanted a button that would open a google map gadget based on an address the user has selected on the page or entered into the query box:

<-- "loc" is the gadget preference for the location. -->
<gadget width="400" height="300" whole-dropdown="true" query="loc" selection="loc">
  http://ralph.feedback.googlepages.com/googlemap.xml
</gadget>

To keep gadgets consistent, we recommend you use the reserved gadget preference name of rawquery when using the query, or selectedtext when using the selection.

The current url or host name can be used by a gadget when it opens via a user preference variable. For example, suppose you wanted a button that would tell you the trustworthiness of a currently opened merchant web site:

<-- "page_host" is a gadget preference to receive the current host,
    such as www.example.com -->
<gadget host="page_host">
  http://example.com/gadgets/trustworthiness.xml
</gadget>

To keep gadgets consistent, we recommend you use the reserved gadget preference name of page_url when using the full url, or page_host when just the host name is needed.

This example demonstrates all of the communication between a gadget and a toolbar button at the same time. By the way, another way to create a button is to go directly to the advanced button editor, paste your button source over the top of the sample, and save to the toolbar.

Here is the button source:

<?xml version="1.0"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <site>http://www.google.com/</site>
    <title>Gadget Test</title>
    <description>Test toolbar gadget communication</description>
    <option>
      <title>My Option</title>
      <default>My Default</default>
    </option>
    <gadget width="300" height="140" whole-dropdown="true"
            url="page_url"
            host="page_host"
            query="rawquery"
            selection="selectedtext"
            option1="option1">
      http://www.google.com/ig/modules/toolbar/tbtest/tbtest.xml
    </gadget>
    <icon>
AAABAAEAEBAQAAEABAAoAQAAFgAAACgAAAAQAAAAIAAAAAEABAAAAAAAgAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAACAAACAAAAAgIAAgAAAAIAAgACAgAAAgICAAMDAwAAAAP8AAP8AAAD//wD/AAAA
/wD/AP//AAD///8AiP+Hdwd/+Pf3h4+ACPd/f/94//B4+HeP94eP9w+Hh3/3+Pj3f3d4f3//h4d3
AI/3eI//h3B///dwcHd3d3d3cHB3d3dwd3d3eI+HBwj//4d/+AB3f3j/9/eHcPd/+I9/93h493+P
eH+Pd4/3f/j3iPeHf4d493h/f4+HcHd4+PcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    </icon>    
  </button>
</custombuttons>

And here is the gadget source:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Toolbar Test"
    description="Test toolbar gadget communication."
    title_url="http://toolbar.google.com/buttons/apis/"
    screenshot="/ig/modules/toolbar/tbtest-thm.png"
    thumbnail="/ig/modules/toolbar/tbtest.png"
    author="Tom Wuttke"
    author_email="[email protected]"
    author_affiliation="Google Inc."
    author_location="Mountain View, CA"
    width="300"
    height="140"
    scaling="false"/>
  <UserPref name="page_url" datatype="hidden" />
  <UserPref name="page_host" datatype="hidden" />
  <UserPref name="rawquery" datatype="hidden" />
  <UserPref name="selectedtext" datatype="hidden" />
  <UserPref name="option1" display_name="Option1" />
  <Content type="html">
  <![CDATA[ 
    page_url: <input value="__UP_page_url__"><br>
    page_host: <input value="__UP_page_host__"><br>
    rawquery: <input value="__UP_rawquery__"><br>
    selectedtext: <input value="__UP_selectedtext__"><br>
    option1: <input value="__UP_option1__"><br>
  ]]> 
  </Content>
</Module>

Charset Encoding

Starting with toolbar version 4.0.1019.9238, a button can encode
variables,
inside urls using charsets other than utf-8. The
“charset” attribute can be included on
<search>,
<site>,
<send>,
and <feed> elements.

Generating a custom search by right-clicking on a form
automaticaly adds the correct charset value inside
the

In the following example, the {query} param will be expanded using euc-jp instead of utf-8

<search charset="euc-jp">http://japan.example.com/search?p={query}</search>

Another example:

<search charset="gb2312">http://china.example.com/s?wd={query}</search>

Charset values sometimes have alternate names, and are always case insensitive.
The complete list of charset values depends on the windows registry
keys under HKEY_CLASSES_ROOTMIMEDatabaseCharset.
Those installed on Windows XP typically include:

Multiple Languages

A custom button can handle alternate URLs, icons and text for specific toolbar locales. The two ways to do this are listed below — the first method is recommended.

Using locale Attribute

The recommended method is to create a list of XML tags, each using a locale="iso-name" attribute with the iso-name for the locale of interest. Here is an example of a button with alternate French and Spanish URLs and descriptions:

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">
  <button>
    <title>Wikipedia</title>
    <site>http://www.wikipedia.org</site>

    <site locale="fr">http://fr.wikipedia.org</site>
    <site locale="es">http://es.wikipedia.org</site>
    <description>The Free Encyclopedia</description>

    <description locale="fr">L'encyclopdie libre</description>
    <description locale="es">La enciclopedia libre</description>
  </button>
</custombuttons>

If the locale of the current toolbar language cannot be found in the
XML tag directly, the first tag in the above list is used as the default.

Using {locale} Variable

The alternate method is to use the {locale} variable embedded in a URL, such as http://{locale}/wikipedia.org. This method works great if the set of locales it evaluates to maps exactly to the different websites available (which is the case for Google.com). However, for most users, this will not be the case. A website might exist for a particular locale that Google toolbar does not yet support. For example, as of this writing, while Wikipedia has a Polish version (http://pl.wikipedia.org), but Polish (pl) is not a native toolbar locale, so Polish users would not be able to get to that website. Conversely, the toolbar is available for the Brazilian Portuguese (pt-BR) locale, but Wikipedia has no site for that particular locale. Also, you can mix statements with the locale attribute and statements with the {locale} variable if that is suitable for you — in that case, the first attribute would still be the default.

ISO Locale Table

The currently supported toolbar locales are:

Where to Host Your Button

Which download URL you use to host the XML file for the button is fairly important, because that URL becomes the button’s unique ID for updating the button. If a second attempt is made to download a button from the same URL, the toolbar will offer only to replace the old one, not add a new one. For more information, see Updating a Custom Button.

Adding Your Button to Google’s Button Gallery

Adding your button to Google’s Button Gallery is a great way to let the world know about your new button. Your XML file must already be hosted somewhere (the Button Gallery will link directly to the file) and the button must comply with our Editorial Guidelines.

If you’ve created a button for a site you own, you should host your XML file on the same domain as your site. Buttons in Google’s Button Gallery are marked as “official” if they are hosted on the same domain that the button accesses. This makes it easier users to find the official button for your site.

Once you’ve done all this, fill out the Button Gallery submission form to let Google know about your button.

Linking to Your Button From Your Site

You can make your button available on your own site by creating an installation link. When a Google Toolbar 4 user clicks on the link, they’ll be prompted to install your button. If the user doesn’t have a compatible version of the Toolbar, the link will go to the Google Toolbar download page instead.

A developer can create an installation link by using the following URL syntax:

http://toolbar.google.com/buttons/add?url=url

where url points to the custom button XML file. For example, here is a link that would install a Slashdot.com button:

<a href=
"http://toolbar.google.com/buttons/add?url=http://www.slashdot.org/slashdot_button.xml"
>Add</a>

This link’s label is Add. When a user clicks on this link, the Slashdot.com button is installed in their Google toolbar.

The Google URL above is basically a trigger for the toolbar to install any custom button. If the user doesn’t have a compatible version of the toolbar, they’ll be prompted to install it. Once the the toolbar has been installed, the custom button will automatically be added.

Managing Your Feed Traffic

Web traffic with feeds can be a concern. A button shouldn’t point its feed to a low bandwidth server if you have reason to believe it will become popular and have heavy traffic. The server can get overloaded with refresh requests.

The custom button has its own refresh-interval attribute for feeds. The toolbar honors the “Expires” time that the server provides in the HTTP header. This setting overrides the button’s refresh-interval. If your server is overloaded, you could increase the “Expires” time to reduce the load. For example, if a button is set to refresh each hour, the “Expires” time can be set to refresh every day, which would drastically reduce the traffic (though perhaps limiting the freshness of the button).

Here’s a sample PHP script to set the Expires time one week into the future:

<?php
$expires = gmdate("D, d M Y H:i:s", time() + 3600 * 24 * 7) . " GMT";
Header("Expires: " . $expires);
?>

Example HTTP response from server :

HTTP/1.1 200 OK
Date: Thu, 05 Jan 2006 23:39:54 GMT
Server: Apache/2.0.47 (Red Hat Linux)
Accept-Ranges: bytes
X-Powered-By: PHP/4.3.2
Expires: Thu, 12 Jan 2006 23:39:54 GMT
Transfer-Encoding: chunked
Content-Type: text/html

XML Reference

A custom button XML file has the following structure:

<?xml version="1.0" encoding="utf-8"?>
<custombuttons xmlns="http://toolbar.google.com/custombuttons/">

  <button>
    <!-- XML elements -->
  </button>
</custombuttons>

The following XML elements can appear within a <button> element. Any element (except <update>) can appear more than once, as long as each is assigned to a different locale.

Escaping Characters

Strings in XML files (and HTML files) need the following three characters escaped as the HTML entities shown:

Variables Reference

NOTE – A conditional {a?b:c} syntax exists for variables that provide forward and backward compatibility. For more information, see Testing If a Variable Exists or Not.

The following variables, or escape parameters, are used in elements listed in the specified scope.
For example, {query} can only be used in the <search> element.

Feed Reference

Custom buttons work with the following Feed types:

• RSS 1.0
• RSS 2.0
• Atom 0.3
• Atom 1.0
• Some other variants

Google Custom Buttons recognize an extended XML namespace that allow a feed author to insert extra items into a feed that do not break compatibility with other feed readers. For the rest of this section, assume that gtb: prefixes the google namespace defined by xmlns:gtb='http://toolbar.google.com/custombuttons/'

The following elements will be recognized inside the root node of the feed: