Guide to Making Custom Buttons for Google Toolbar 4 for Internet Explorer

Table of Contents

Introduction

What is a Custom Button?

A custom button is a push button that you can add to the Google Toolbar and which can have custom navigation, search, send as well as update capabilities. Notably, a custom search button can use 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 that the user has typed into the toolbar search box. For example, a Wikipedia button would go to wikipedia.org and search for the term that you have 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 drop-down list of icons and strings from an RSS feed

A custom button can have the following user interface features:

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

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 the 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 entered 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 clicking on a button directly on a publisher's website and confirming that he/she wants to add it. A list of such buttons is available in 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 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.

How to Make Custom Buttons

Automatically Creating and Adding a Custom Search Button

1. Open Internet Explorer to the search page for which you want to create a search button.
   Example: www.wikipedia.org

2. Right-click on the search box that you want to use on that page, select "Generate Custom Search...", then click "Add".

Result: The custom button is installed and is 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 Settings\larry\Local Settings\Application Data\Google\Custom Buttons\

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

Custom Button XML File

A custom button's properties and behaviour 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 on, 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 - You can 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 that you need to make sure that if your URL requires spaces (you do not want them stripped out), you replace them with "%20" (if the browser has not 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 Settings\username\Local Settings\Application Data\Google\Custom Buttons\filename.xml

   where username is your Windows login name and filename is the file name that 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 Settings\larry\Local Settings\Application Data\Google\Custom Buttons\wikipedia.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 can be used for search, the title should be unique to all your search custom button titles, 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 any website's search engine using the term typed by the user 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 query. 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. However, to search for the term that 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 website to use form-encoded data instead of url-encoded data. However, 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 that 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 only offer 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 indicate 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 specify 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 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 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 that the browser displays in 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 website, 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 is 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 that it had no effect on older toolbars:

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

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

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

If not, then:

<site>http://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://google.com/{locale??hl={domain?{domain}:{query}}}</site>

It should also be noted that any time an escape which is used is not recognised, 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 be reset to an empty string.

How to Create Good-Looking Icons

Most icons that are used as favicons can also be used as custom button icons. These include 16x16 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 Google Mail 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 16x16 but the toolbar will scale them down to 16x16; 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 colour (RGB) and 8 bits of alpha and saved as XP-style RGBA icons. You can save the icon as a 16x16 PNG with alpha transparency and convert that into an XP-style 16x16 icon (using a programme like IconWorkshop) and then base64-encode that. PNG files are not directly supported 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 colour is going to be the same grey, silver or beige that yours is set to. Windows XP allows users to customise their colour scheme, including toolbar backgrounds. You could get around this by making a square icon that does not have any transparent parts. However, they do not look as interesting. Single colour alpha channels, such as 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 that 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.

Using a Feed to Update the Button Icon/Tooltip

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>

Note that it specifies menu="false" to indicate that this feed is used only to update the icon and tooltip, not to populate a drop-down 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, specify:

<gtb:icon> icon-base64-code </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' 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 Drop-Down Menu Icons

You can also add custom server-based icons to the individual items on the feed drop-down menu. Here is an example of a weather button that has a feed with a drop-down menu (the default) but also specifies refresh-menuitem="false" to hide the refresh menu item each 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 drop-down menu (with most of the icon base64 items 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>

The PHP code that does this uses the weather forecast reply format.

<?php

// Script to convert Google xml weather interface to custom buttons AtomFeed 1.0
// Sample input at http://www.google.com/ig/api?weather=94043
// To see sample output, run this script with ?zip=94043

$zip = $_GET['zip'];

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

// http://www.google.com/ig/api?weather=94043
$dom= domxml_open_file("http://www.google.com/ig/api?weather=$zip");

$xpath = xpath_new_context($dom);
// $params = $dom->documentElement->firstChild->getElementsByTagName('param');

$temp = $xpath->xpath_eval('//city/@data');
$city = $temp->nodeset[0]->value;

$icons = $xpath->xpath_eval('//current_conditions/icon/@data');
$icon_url = $icons->nodeset[0]->value;
$icon = base64_encode(file_get_contents("http://www.google.com$icon_url"));

$conditions = $xpath->xpath_eval('//current_conditions/condition/@data');
$condition = $conditions->nodeset[0]->value;

$temp = $xpath->xpath_eval('//current_conditions/temp_f/@data');
$tempf = $temp->nodeset[0]->value;

$temp = $xpath->xpath_eval('//current_conditions/humidity/@data');
$humidity = $temp->nodeset[0]->value;

$temp = $xpath->xpath_eval('//current_conditions/wind_condition/@data');
$wind = $temp->nodeset[0]->value;

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/weather</id>";
echo "\n<title>Weather $city</title>";
echo "\n<link href='http://www.google.com/search?q=weather+$zip/' />";
echo "\n<link rel='self' href='http://www.example.com/custombuttons/";
echo     "samples/feeds/weather' />";
echo "\n<gtb:description>$city\n$tempfF $condition\n$humidity\n$wind";
echo   "</gtb:description>";
echo "\n<gtb:icon mode='base64' type='image/x-icon'>$icon</gtb:icon>";

$days = $xpath->xpath_eval('//forecast_conditions/day_of_week/@data');
$conditions = $xpath->xpath_eval('//forecast_conditions/condition/@data');
$icons = $xpath->xpath_eval('//forecast_conditions/icon/@data');
$highs = $xpath->xpath_eval('//forecast_conditions/high/@data');
$lows = $xpath->xpath_eval('//forecast_conditions/low/@data');

for ($i = 0; $i < count($conditions->nodeset); $i++) {
  $day_of_week = $days->nodeset[$i]->value;
  $condition = $conditions->nodeset[$i]->value;
  $high = $highs->nodeset[$i]->value;
  $low = $lows->nodeset[$i]->value;
  echo "\n<entry>";
  echo "\n<title>$day_of_week: $condition $high | $low</title>";
  echo "\n<link href='http://www.google.com/search?q=weather+$zip/' />";
  echo "\n<id>http://www.example.com/custombuttons/samples/feeds/weather/$i</id>";
  $icon_url = $icons->nodeset[$i]->value;
  $icon = base64_encode(file_get_contents("http://www.google.com$icon_url"));
  echo "\n<gtb:icon mode='base64' type='image/x-icon'>$icon</gtb:icon>";
  echo "\n</entry>";
}

echo "\n</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.

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 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 which Google Toolbar does not yet support. For example, as of this writing, while Wikipedia has a Polish version (http://pl.wikipedia.org), Polish (pl) is not a native toolbar locale, so Polish users would not be able to access 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:

ISO Locale	Language
en	English
da	Danish
de	German
es	Spanish
fi	Finnish
fr	French
it	Italian
ja	Japanese
ko	Korean
nl	Dutch
no	Norwegian
pt-BR	Brazilian Portuguese
ru	Russian
sv	Swedish
zh-CN	Chinese (Simplified)
zh-TW	Chinese (Traditional)

Hosting a Custom Button

Where to Host Your Button

The download URL that 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 only offer 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 have created a button for a site that 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 for users to find the official button for your site.

Once you have 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, he/she will be prompted to install your button. If the user does not 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 his/her Google Toolbar.

The Google URL above is basically a trigger for the toolbar to install any custom button. If the user does not have a compatible version of the toolbar, he/she will be prompted to install it. Once 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 should not point its feed to a low bandwidth server if you have reason to believe that it will become popular and have heavy traffic. The server can be overloaded with refresh requests.

The custom button has its own refresh-interval attribute for feeds. The toolbar complies with 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 is 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

Reference

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.

<title> text </title>

The title of the custom search button that the user can see in the list of custom buttons (Settings > Options > Custom Buttons) or optionally next to the button. This value should be unique, since it will also function as the default keyword if it appears a search type.

This element supports the same locale attribute as <search> below.

See <title> example.

<description> tooltip </description>

The tooltip text of the custom search that the user will see if he/she hovers over it with a mouse. This is also the description that the user sees after downloading the button from a website.

This element supports the same locale attribute as <search> below.

See <description> example.

<site> url </site>

Optional URL to navigate to when there is no new text in the search box. The protocol is restricted to http: and https: for security. The following variables within this URL will be expanded: {domain}, {url}, {url.noescape}, {url.host} and {locale}.

The <site> element supports the same method and locale attributes as <search> below.

See <site> example.

<search> url-template </search>

The URL that the browser will navigate to and search when the button is clicked with a "new" search term in the search box. ("New" means that the search box has focus.) The URL must be http: or https: based -- javascript: is not allowed. The variable {query} is required in the search template (and is not allowed in other URL templates). This element is optional and may be omitted if this button should not be in the search button list.

The search element may specify these attributes:

method="post"|"get"

Default is "get". Set to "post" to use post instead of get when sending URL encoded form data. The encoding method must be application/x-www-form-urlencoded. When a search is performed, all text after the final question mark '?' will be sent as postdata.

locale="en"|"da"|"de"|"es"|"fi"|"fr"|"it"|"ja"|"ko"|"nl"|"no"|"pt-BR"|"ru"|"sv"|"zh-CN"|"zh-TW"

Specifies a locale for which this element can supply an alternate URL. Include the ISO locale name, such as locale="fr". Typically, you would specify multiple elements, each with its own locale attribute and alternate URL. (When this attribute is used with other XML elements, it can specify a different icon or text.) See locale examples and ISO locale table

See <search> example.

<send> url-template </send>

Optional URL the browser navigates to when there is no text in the search box and the user has selected text in the browser window. The variable {selection} is required in the send template (and is not allowed in other URLs).

The <send> element supports the same method, charset and locale attributes as <search> above.

See <send> example.

<icon> base64-encoding </icon>

The actual bits of a Windows-style .ico file, preferably an XP-style 16x16 32-bit RGBA image, which many sites use as their favicon.ico file. Since this is a binary value, it must be base64 encoded. If no icon is present, a default will be chosen. 16x16 XP-style alpha blended .ico images are the preferred format, but there is also support for regular ICO, JPG, BMP and GIF of arbitrary sizes that will be scaled to 16x16. The XP RGBA icon will work on all operating systems that the Google Toolbar works on, so there is no need to create a 256-colour or 16-colour alternate. PNG is not supported.

The mode and type attributes are not necessary, but might make it easier to edit in a XML editor that interprets them:

mode="base64"

The icon encoding.

type="image/x-icon"

The type of image.

This element supports the same locale attribute as <search> above.

See <icon> example.

<feed> url </feed>

Specify a URL to an RSS 2.0 or Atom Feed 0.3/1.0 XML file. This element adds the ability to open a drop-down menu with RSS feed titles, descriptions and links, similar to Firefox RSS bookmarks, which are automatically updated (not user-initiated). This element is optional and will not be used by most custom searches. The {domain} and {locale} variables may also be used in the feed.

This element takes these attributes:

menu="true"|"false"

Set this to false to hide the drop-down menu of entries from the feed. The default is true.

refresh-interval="secs"

Number of seconds to wait before reloading the feed. The default is 3600 (1 hour). The toolbar will not update more than once per minute even if this value is less than 60.

refresh-onclick="true"|"false"

Set this to true to force a reload every time the user clicks on the button. The default is false.

google-service="true"|"false"

Set to true if this is a Google accounts service, which means it is only available when a user has signed into Google. A refresh happens when sign-in is detected and sign-out clears the menu items.

This element supports the same locale attribute as <search> above.

See <feed> example.

<feed-icon> base64-encoding </feed-icon>

An alternate icon to display when the feed has new items (same format as <icon>). When a user clicks on a button, the icon will revert back to the normal icon until the next feed. A feed server may specify an icon directly in the Atom Feed or RSS 2.0 response, in which case <feed-icon> or <icon> will get second priority.

This element supports the same locale attribute as <search> above.

(No <feed-icon> example is included, but it would be similar to the <icon> example.)

<feed-description> tooltip </feed-description>

An alternate description to display in the tooltip when the feed has new items. When a user clicks on a button, the description will revert back to the normal description until the next feed.

This element supports the same locale attribute as <search> above.

(No <feed-description> example is included, but it would be similar to the <description> example.)

<update> url </update>

The URL from which this button definition was downloaded and from which the update button will get a replacement XML file if the user clicks on the link to update (Settings > Options > Custom Buttons > select button > Edit > Download latest version). This URL will be overwritten with the actual URL from which the button was downloaded on web installs that do not come from google.com. This is the only element in the custom button that cannot have a locale attribute.

See <update> example.

<option> subelements </option>

Specifies a locally defined option string that the user can easily change in the toolbar settings dialog box. The value is returned in the {option1} variable. This element can have three subelements, the first of which is required:

<title>

The name of the option. The user sees this name in the toolbar settings dialog box. This subelement is required.

<description>

A description of this option. The user sees this description. Each option can have multiple descriptions. This subelement is optional.

<default>

The default value of the {option1} tag. This value is used if the user enters no value. This subelement is optional.

See <option> example.