Table of Contents
Guide to Making Custom Buttons for Google Toolbar 5
This document describes how to make custom buttons. Custom buttons currently work only on Internet Explorer.
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
- Open Internet Explorer to the search page you want to create a search button for.
Example: www.wikipedia.org - 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:
- Create a button XML file as shown in the previous (and following) sections.
- 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
- 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}
&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}
&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}
&mediatype=mediatype&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&lr=&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<br>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:
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&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:
ASMO-708 | Big5 | euc-jp | euc-kr | GB2312 |
hz-gb-2312 | ibm852 | ibm866 | iso-2022-jp | iso-2022-kr |
iso-8859-1 | iso-8859-2 | iso-8859-3 | iso-8859-4 | iso-8859-5 |
iso-8859-6 | iso-8859-7 | iso-8859-8 | iso-8859-8-i | iso-8859-9 |
koi8-r | koi8-ru | ks_c_5601-1987 | shift_jis | utf-7 |
utf-8 | windows-1250 | windows-1251 | windows-1252 | windows-1253 |
windows-1255 | windows-1256 | windows-1257 | windows-1258 |
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:
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) |
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.
- <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. - This element supports the same
- <description> tooltip </description>
- The tooltip text of the custom search that the user will see if they hover over it with a mouse. This is also the description that the user sees after downloading the button from a web site.
- This element supports the same
locale
attribute as<search>
below.- See
<description>
example. - This element supports the same
- <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 samemethod
,charset
andlocale
attributes as<search>
below.- See
<site>
example. - The
- <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:
orhttps:
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:
- See
<search>
example. - The search element may specify these attributes:
- <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 samemethod
,charset
andlocale
attributes as<search>
above.- See
<send>
example. - The
- <icon> base64-encoding </icon>
- The actual bits of a Windows-style .ico file, preferably an XP-style 16×16 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. 16×16 XP-style alpha blended .ico images are the recommended format, but there is also support for regular ICO, JPG, BMP, and GIF of arbitrary sizes that will be scaled to 16×16. 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 color or 16 color alternate. PNG is not supported.
- The
mode
andtype
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. - The
- <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 dropdown 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 dropdown 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 every 20 seconds even if this value is less than 20. New! Older toolbars would not update more than once every 60 seconds.
- refresh-onclick=”true”|”false”
- Set this to true to force a reload every time the user clicks 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.
- refresh-menuitem=”true”|”false”
- Set this to true to always append a refresh item at the bottom of the feed. Clicking on this will re-fetch the feed data, bypassing the browser cache. This item also shows the time of the last fetch or an error message. A failed fetch always displays a refresh item at the bottom, regardless of this setting. The default is false.
- whole-dropdown=”true”|”false” New!
- Set this to true to make the whole button open the dropdown menu. <site> will be accessible as the first menuitem. <search> and <send> will be available from the main button during search or send mode. The default is false, which keeps the split button behavior.
- site-menuitem=”true”|”false” New!
- In the case of a whole dropdown, set site-menuitem to false to take site off of the top of the menu.<site> will not be accessible, but must be specified as a valid http: url to maintain compatibility. The default is true.
- allow-alerts=”true”|”false” New!
- Set this to true to allow the feed to alert the user to events. The default is false.
- This element supports the same
locale
andcharset
attribute as<search>
above.- See
<feed>
example. - This element takes these attributes:
- <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.) - This element supports the same
- <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.) - This element supports the same
- <gadget> url </gadget> New!
- Specify a URL to a universal gadget XML spec. This element adds the ability to open a dropdown gadget window instead of a feed menu. This element is optional, and will not be used by most custom searches.
- This element takes these attributes:
- width=”pixels”
- Specify the desired initial width of the gadget window. The user may resize the window with the sizing handle at any time.
- height=”pixels”
- Specify the desired initial height of the gadget window. The user may resize the window with the sizing handle at any time.
- default-options=”user preference assignment string”
- Use this to override one or more gadget user preference defaults. This attribute is optional and is useful mainly when the gadget does not provide its own defaults.
- Each param is prefixed with
up_
and set equal to a value that needs to be escaped twice, once for being a URI component (See the javascript encodeURIComponent function for details) and again to be in the xml file ( & < > ). Multiple parameter assignments are separated with&
- For example, if the gadget’s preferences are foo and bar, the default options string might look like this:
<gadget default-options="up_foo=hello&up_bar=world">
- Each param is prefixed with
- whole-dropdown=”true”|”false”
- Set this to true to make the whole button open the dropdown gadget window and to allow gadgets to perform search and send operations. <site> will not be accessible, but <search> and <send> will. The default is false, which keeps the split button behavior and prevents queries or selected text from ever going to a gadget.
- url=”gadget user preference name”
- Use this to send the current page url to the gadget as a user preference. For example, url might look like
http://www.google.com/about.html
. The recommended user preference name to receive the url ispage_url
. By usingpage_url
, your gadget will be compatible with future container functionality. - host=”gadget user preference name”
- Use this to send the current page host to the gadget as a user preference. For example, host might look like
www.google.com
. The recommended user preference name to receive the host ispage_host
. By usingpage_host
, your gadget will be compatible with future container functionality. - query=”gadget user preference name”
- Use this in combination with
whole-dropdown="true"
to let the gadget perform search functionality. It will send the current query from the search box to the gadget as a user preference when the toolbar is in search mode. For example, query might look likecute kittens
. The recommended user preference name to receive the query israwquery
. By usingrawquery
, your gadget will be compatible with future container functionality. - selection=”gadget user preference name”
- Use this in combination with
whole-dropdown="true"
to let the gadget perform send functionality on the user’s currently selected text on the page. It will send the current text selection from the browser to the gadget as a user preference when the toolbar is in send mode. For example, selection might look likeFour score and seven years ago
. The recommended user preference name to receive the selection isselectedtext
. By usingselectedtext
, your gadget will be compatible with future container functionality. - option1=”gadget user preference name”
- If your button needs to share a preference between the gadget and the other button actions, one way is to associate option1 with a gadget preference, and let the toolbar keep them in sync. This also makes it possible to stay backwards compatible with toolbars that don’t support gadgets yet.
- This element takes these attributes:
- <update> url </update>
- The URL where this button definition was downloaded from, and where the update button will get a replacement XML file from if the user clicks on the link to update (Settings > Options > Custom Buttons > select button > Edit > Download latest version). This URL will get overwritten with the actual URL the button was downloaded from 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
. - See
- <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
.
Escaping Characters
Strings in XML files (and HTML files) need the following three characters escaped as the HTML entities shown:
Character | Escape String |
---|---|
& |
& |
> |
> |
< |
< |
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:
- <gtb:description> Dynamic tooltip text of button </gtb:description>
- The tooltip text, or button description, may be dynamically updated with plain text or html. The markup that is currently recognized includes html entities and <p> or <br> tags.
- See <gtb:description> example.
- This element supports the same
locale
attribute as<search>
. - See <gtb:description> example.
- <gtb:icon> Dynamic button icon </gtb:icon>
- The icon of the button may be dynamically updated from base64 text. It should be a small ico, bmp, jpg, or gif image.
- See <gtb:icon> button example. Also see how to make icons.
- A http: or https: url to a small ico, jpg, bmp, or gif image may be used instead of base64 text. New!
- See <gtb:icon> button example. Also see how to make icons.
- <gtb:status> Text to append to button </gtb:status> New!
- A small amount of status text may be dynamically displayed next to the button in square brackets, even when the user has button text disabled.
- See <gtb:status> example.
- This element supports the same
locale
attribute as<search>
. - See <gtb:status> example.
- <gtb:alert> Text to alert user </gtb:alert> New!
- A small amount of alert text may be dynamically displayed in a tooltip underneath the flashing button. If the toolbar window is not in focus, the title bar of IE will flash for a few minutes. To minimize abuse of this feature, the button’s feed element must have the
allow-alerts
attribute set to true.- This element takes one optional attribute:
- id=”unique string”
- If this string changes, it signals to the toolbar that a new event has occurred. Otherwise, a new event is assumed to begin whenever the text in
<gtb:alert>
changes.
- See <gtb:alert> example.
- This element supports the same
locale
attribute as<search>
. - This element takes one optional attribute:
- <item> subelements </item> or <entry> subelements </entry>
- A feed may contain zero or more
<item>
(RSS Feeds) or<entry>
(Atom Feeds) elements to define menu items. Only the first 100 items will be used by the button reader.- These subelements are recognized, the first of which is required:
- <title> text </title>
- This determines the text of the menu entry of the item. This subelement is required.
- If this text contains only a line of dashes (—), a menu separator is used. New!
- <description> text </description> or <summary> text </summary>
- Each item may have a
<description>
(RSS Feeds) or<summary>
(Atom Feeds) that contain plain text or html. The markup that is recognized currently include html entities and <p> or <br> tags. This text is displayed as a tool tip when the user hovers over the menu item. This subelement is optional. - <link> url </link>
- This is where the browser will navigate if the menu item is clicked on. This subelement is optional.
- <gtb:icon> base64-encoding </gtb:icon>
- The menu item may specify an icon from base64 text. It should be a small ico, bmp, jpg, or gif image. This subelement is optional.
- See <gtb:icon> menu example. Also see how to make icons.
- A http: or https: url to a small ico, jpg, bmp, or gif image may be used instead of base64 text. New!
- See <gtb:icon> menu example. Also see how to make icons.
- These subelements are recognized, the first of which is required: