XML Reference

From Best Toolbars

Full XML reference on Toolbar building is available here: http://www.besttoolbars.net/CUST/manual_401.pdf

Contents 1 Manual 2 <ALLOWPOPUPS> command 3 <AUTOSEARCH> 4 <BANNER> 5 <BLOCKPOPUPS> 6 <BUBBLE> 7 <BUTTON> 8 <CHANGELAYOUT> 9 <CHECKBOX> 10 <CLEARCOUNT> 11 <COMMANDS> 12 <COMMANDCHUNK> 13 <COMBO> 14 <COMBO> tag for select-type combo boxes (non-editable) 15 <DNSCATCH> 16 <EDIT> 17 <ENABLEIMAGE> 18 <ENABLEFLASH> 19 <EXTERNAL_SEARCH> 20 <HIGHLIGHT> 21 <HOMEPAGE> 22 <INCLUDE_XML> 23 <INCLUDE_CUSTOM_XML> 24 <INCLUDE_SCRIPT > 25 <LOCALHTML> command 26 <LAUNCHSCRIPT> command 27 MACRO SUBSTITUTIONS 28 <ITEM> tag 29 <ITEM> tag and Submenu Items 30 <MENU> 31 <PASSWORD> 32 <RADIOBOX> 33 <SEPARATOR> tag 34 <SHOWMENU> command 35 <SETTINGS> section 36 <SHELLEXECUTE> command 37 <SPACE> tag 38 <SWITCHCOMMAND> command 39 <TEXT> tag 40 <TOOLBAR> tag 41 <WEBJUMP> command

Manual

The toolbar configuration is stored inside .XML files. Normally, you do not edit these files directly. Since Toolbar Studio gives
you a full set of options to build your custom toolbar. However, some advanced features require you to change the XML manually. 
To start editing XML, please choose “Edit Raw XML” from the Tools menu of the ToolbarStudio.

This option will open an editor with the main basis.xml file loaded into. This file is always distributed with the toolbar package. 
Please note that additional .xml files can be referenced from the basis.xml (via INCLUDE_XML) so that the toolbar configuration is 
combined from several files. The referenced files can be located on the server to achieve Dynamic Toolbar behavior (Please look over 
the documentation for <INCLUDE_XML> tag).

The configuration file format is presented below. Please note that it always has to begin with <TOOLBAR> and end with </TOOLBAR> 
plus it is required that the toolbar configuration contains COMMANDS and SETTINGS sections enclosed between <TOOLBAR> </TOOLBAR> 
tags.
The simple format for the basis.xml:

<?xml version="1.0"?>
<TOOLBAR name="IE Toolbar Sample" icons="icons.bmp" hot_icons="icons.bmp" dllname="toolbar">

<!—Toolbar definition goes here. -->

<COMMANDS>
<!—Toolbar commands goes here. -->
</COMMANDS>

<SETTINGS scope="1">
<!—Toolbar settings goes here. -->
	<URL id="firstURL" default="http://www.yourtoolbar.com/toolbar/toolbar.asp#how?toolbar_id=%toolbar_id"/> 

</SETTINGS>
</TOOLBAR>

To make the toolbar fully dynamic you need to put your configuration file on the server and reference it from the basis.xml like:

<?xml version="1.0"?>
<TOOLBAR name="IE Toolbar Sample" icons="icons.bmp" hot_icons="icons.bmp" dllname="toolbar">

<INCLUDE_XML filename="http://www.yourtoolbar.com/toolbar/toolbar.xml"/>

<COMMANDS>
<!--Toolbar commands goes here. -->

	</COMMANDS>

<SETTINGS scope="1">
	<!--Toolbar settings goes here. -->
	<URL id="firstURL" default="http://www.yourtoolbar.com/toolbar/toolbar.asp#how?toolbar_id=%toolbar_id"/>

</SETTINGS>
</TOOLBAR>

In the above example the toolbar cofiguration is obtained from the server file http://www.yourserver.com/toolbar/toolbar.xml each 
time user opens his browser. 
Note: to minimize the traffic generated by the toolbars requesting http://www.yourserver.com/toolbar/toolbar.xml 
expire attribute could be used. This will tell the toolbars to update as frequently as specified by expire attribute. 
For example setting 
expire=”1440” tells that the toolbar will try to update itself once a day from the server (24*60=1440 minutes).

<ALLOWPOPUPS> command

<ALLOWPOPUPS> command to allow pop-ups from certain sites (White-list functionality)
Sometimes pop-ups should be allowed, as they open login window, or an address book for a webmail system. 
It is achieved by adding the site to the whitelist. Pop-ups from the sites in whitelist will not be blocked.

To use the whitelist you need to add the following commands in between <COMMANDS> </COMMANDS>:

<ALLOWPOPUPS name="popupAllow"/>

This command tells that the command named "popupAllow" will be used to add the currently visited website to the white list.

You can associate popupAllow with and menu item or button:

<BUTTON caption="Allow Popups for this site" captionp="pop-ups are allowed for this site" hint="" id="tb_btn_V" 
img="83" imgp="84" command="popupAllow"/>

When user clicks on that button the pop-ups will be allowed for the current site and the site will be added to the white list.
If the site is already in the white list clicking on that button will remove it. When visiting a site that is in a whitelist 
the button associated with popupAllow will be displayed as pressed.

You can specify the sites that need to be in the whitelist by default. This is achieved by using the below lines:
          
<ALLOWPOPUPS name="popupAllow">
                <SITE>www.mysite.com</SITE>
                <SITE>webmail.mysite.com</SITE>
                <SITE>www.webmail.mysite.com</SITE>
        </ALLOWPOPUPS>

'''NOTE:''' Files on a local hard drive and sites in the local area network are always considered to be in a whitelist. 
Plus, pop-ups evoked from the toolbar itself are never blocked. 

<AUTOSEARCH>

<AUTOSEARCH> tag to capture address bar searches
To use this feature you need to add the following code to the <SETTINGS> section of the XML file:

<AUTOSEARCH href="http://yoursite.com/search?text=%s"/>

%s will be replaced with the word being searched when user types something into the address bar.

<BANNER>

<BANNER> tag
This tag gives you much more flexibility then any other. It will allow you to create a mini webpage inside your toolbar 
with any content including animations, forms, FLASH e.t.c. This mini webpage can be refreshed periodically or while 
the user surfs the web. 
<BANNER> is perfectly suited for implementation of Ticker-tape scrolling news, flashing notifications and pop-up generation. 
You can make a <BANNER> hidden (setting it’s width to 0) and use Javascript access to the current page so that you can do 
Javascript actions transparently for the end user. 

<BANNER> tag has a following format:

<BANNER id=”id_banner_1” caption="news" href="http://www.yoursite.com/toolbar_news.html" width=”200” height=”16” 
local=”news_local.html” sync="BeforeNavigate" expire="10"/>

It has the following attributes: 
•	href is an URL of an HTML page to be displayed inside the banner.
•	local specifies a local HTML page to load if the URL specified by href attribute is inaccessible.
•	width and height specify the size of the banner in pixels.
•	urltemplate -it is used in conjunction with sync= attribute to trigger the synchronization only when 
specific pages are visited. This is useful to update toolbar appearance after the user accesses specific sites or 
specific pages on sites. You can specify web page name here or website name.
urltemplate=”specialpage.php” or urltemplate=www.specificsite.com
•	border - If 1 then border is shown around the banner. Also BANNER tag can content an HTML data inside. 
With data will be displayed in the banner instead of content from “url”. For example :
<BANNER …>
<![CDATA[
		<HTML>
			<BODY bgcolor="lightblue">
				<code><font size=2>Welcome</font></code>
			</BODY>
		</HTML>
	]]>  
</BANNER>

•	caption is a string of text that is displayed while the banner is loading.
•	Optional sync= attribute tells that the banner should be reloaded while user browses the web. It can be set to “BeforeNavigate” 
or to “OnDocumentComplete”. The first tells to refresh the banner before the main page in browser loads, 
OnDocumentComplete tells to refresh after the main page has been downloaded completely.
•	Optional expire= attribute forces the banner to reload itself in specified time periods (defined in minutes).

NOTE: If both expire= and sync= are omitted the banner will get reloaded with each new browser window open.

•	Optional autowidth=”1” attribute lets the banner to extend it’s right edge to occupy all the free space on the toolbar:

<BANNER id=”id_banner_1” href="http://www.yoursite.com/toolbar_news.html" autowidth="1" sync="BeforeNavigate" expire="10"/>

If you have any links inside the banner, they will open a page inside/outside the banner. 
You may define in_banner parameter to choose behaviour needed.


NOTE: If you use frames inside the banner, the links inside the <frameset> structure also have to have #mainwindow added to the end.

visibility - by setting this attribute="0", you can make the banner not to appear by default. 
It can be enabled by from the options page.

<BLOCKPOPUPS>

<BLOCKPOPUPS> command and usage of the popup-blocker feature
Pop-up blocker will block pop-up windows when it is turned on. It can play a sound and change the cursor shape 
when the popup window is blocked. The number of pop-ups blocked can be displayed on the toolbar.
To place a popup-blocker button add a button with a command set to blockPopups:

<BUTTON id="tb_blockPopups" img=”1” caption="Block Popups" command="blockPopups"/>

Popup-blocker is a toggle-type button and it can have different text and icon when it is pressed. 
This is controlled by imgp= and captionp= attributes:

<BUTTON id="some_id" caption="Blocker disabled" captionp="#cnt# blocked" img="4" imgp="5" command="blockPopups"/>

#cnt# is a special variable that will be substituted by the total number of blocked pop-ups. You can clear 
this count using a CLEARCOUNT command.
To play a sound when the pop-up is blocked you can use optional attribute 
wave= of BLOCKPOPUPS command in <COMMANDS> section. Optional attribute 
cursor= of the BLOCKPOPUPS is used to define a cursor that will be shown for a short period of time 
when the popup is blocked.

<BLOCKPOPUPS name="blockPopups" default="0" cursor="blocked.cur" wave="click.wav"/> 

Any .WAV and .CUR file can be used. To include those files into the distributive (.CAB or .EXE) please reference 
them via LOCALHTML command in COMMANDS section of the toolbar configuration file.

<LOCALHTML name="wav" href="click.wav"/>
<LOCALHTML name="cursor" href="blocked.cur"/>

To change the message that appears in a status bar of the IE when a pop-up is blocked please change the 
appropriate MESSAGE tag in SETTINGS area:

<MESSAGE id="PopStop" default="Pop-up window blocked"/>

If you want to change image on the pop-up blocker button for a short time when a pop-up is blocked you can use
the BUTTON attribute imgf:

<BUTTON img="8" imgf="9" imgp="10" caption="Popups Allowed" captionp="#cnt# blocked" id="tb_block" command="block"/>

You can clear blocked pop-up counter any time using CLEARCOUNT command.

NOTE: To turn pop-up blocker on by default use default=”1” as an attribute of the BLOCKPOPUPS command 
in between <COMMANDS> </COMMANDS> tags.

<BLOCKPOPUPS name="blockPopups" default="1"/>

Users can temporarily disable pop-up blocking by holding the Ctrl key so if the page contains pop-up, they will be shown. 
Pop-ups evoked from the toolbar itself are never blocked. Plus the popups from the sites in whitelist are never 
blocked (See <ALLOWPOPUPS> command) 

There is one additional option for webdevelopers. Currently the pop-up blocker disables all Javascript error messages to be 
displayed when the pop-up blocker is on. This is required cause a lot of websites use Javascript to communicate with a 
pop-up window and since it is blocked the Javascript errors will be seen. 
But you can use the following inside the <SETTINGS> to allow the Javascript errors to be displayed regardless of the 
pop-up blocker on or off.
<CHECKBOX id="DebugDisable" default="0"/>

<BUBBLE>

<BUBBLE> tag
Defines minipage that opens up when the user clicks a button in a toolbar. To add the minipage you have to put the 
<BUBBLE> tag in between <BUTTON> </BUTTON> tags like it is shown in a following fragment of configuration file. 

<BUTTON ……>         
<BUBBLE type=”Split” width=”500” height=”200” local=”local_bubble.html” href=”http://www.yourtoolbar.com/tb/bubble.html” />
</BUTTON>

This defines an HTML 500x500 pixels mini webpage from http://www.yourtoolbar.com/tb/bubble.html to be shown right near the button
when the arrow on the left of the button is clicked. 

Attributes of the <BUBBLE> tag:
•	type – type of the <BUBBLE> defines whether it is displayed when the button is pressed itself (Type=”Single”  ) or 
when the arrow near the button is pressed (type=”Split”  ) the button itself can have a separate action associated.
•	width – width of the HTML mini page in pixels.
•	height – height of the HTML mini page in pixels.
•	href – URL of the html page to show in the Mini page. Can be any .html file.
•	local – name of the local file that is displayed when the one specified in the href is not accessible. 
This file needs to be provide in within the toolbar package.
The bubble will be closed automatically if you move to another button in the toolbar or switch to another page. 
To close it from HTML page, you have to provide a link with URL set to bubble:close.
<a href=”bubble:close”>Cancel</a>


Links in bubble may open inside/outside the bubble. You may define in_banner parameter to choose behaviour needed.

This is the screenshot of the toolbar bubble:

<BUTTON>

<BUTTON> tag
To add a new button into toolbar put the following command into the configuration file:

<BUTTON id="tb_button_1" caption="Home" img="5" hint="Navigate to homepage" href="http://www.yoursite.com/" command="redirect"/>

In the fragment above caption defines the text that will be shown near the button. 
img attribute contains the index of the image in icons.bmp file.

img="5" setting will reference the 5th 16 x 16 image in icons.bmp file (the one with an envelope in the above example). 
Note: The pixel in the upper left corner of the image is considered to be transparency color. 
All other pixels with the same color are displayed as transparent. 
id attribute contains identifier for the button. This identifier can be used to control visibility of that button from 
toolbar options page. Identifier has to be unique across all toolbar elements.
hint setting allows you to specify ‘tooltip’ text to show when the user rolls the mouse over the button 
(this is useful to provide some more details about the functionality of the button). 
optional image= attribute create a button with custom image (your logo for example). The image must be in a bmp format. 
The image can have a rollover effect if you specify optional hot_img= attribute pointing to an image that is displayed 
when a mouse pointer moves over the button. Image and hot image for the button must have the same width. 

<BUTTON id="logobtn" caption="MyCompaby" image="logo.bmp" hot_image="logo_h.bmp"/>

Note: The pixel in the upper left corner of the image is considered to be transparency color. 
All other pixels with the same color are displayed as transparent. 
dragimg, dragtext

If one of this attribute is specified this button supports drag&drop on it. This works as follows: 
- if dragimg is specified then if an image is dropped on it then the command which name is in the dragimg attribute 
will be launched and name of the image can be got via %image. 

- if dragtext is specified then if a text is dropped on it then the command which name is in the dragtext attribute 
will be launched and content of the text can be got via %selection (works only for text from IE).

href attribute is the URL of the page to which the user will be redirected to when they click on the button 
(this attribute is used only when the command attribute is set to “redirect”). You can use macro substitutions inside 
the URL like %url— will be replaced with the current URL the user is visiting, 
%toolbar_id – will get replaced with unique toolbar identifier. 
See the Macro substitution section of this manual for further details.
You can make the button caption to be bold or italic by using style attribute in the following way:

<BUTTON id=”btn1” caption=”Bold Button” style=”bold”/>
<BUTTON id=”btn2” caption=”Bold Italic Button” style=”bold;italic”/>

command attribute defines the action performed when the button is clicked. "redirect" means that clicking on a button 
will redirect the user to a webpage specified in href= attribute. 
The command attribute can reference any command defined in <COMMANDS> section and usually can have the following values:
•	command="Uninstall" – Uninstalls the toolbar.
•	command="Update" – Updates the toolbar.
•	command="Reload" – Reloads the toolbar .XML file(s) refreshing the toolbar.
•	command=”HideToolbar” – Hides the toolbar
•	command="Highlight" – Toggles Highlighting of the words in a search page on/off.
•	command="ZoomIn" and command="ZoomOut"  – Zooms the current HTML page.
•	command="ResetZoom" - Reset zoom to normal (100%)
•	command="ClearCookies" – Clears cookies in the browser.
•	command="ClearCache" – Clears browser cache.
•	command="ClearHistory" – Clears the list of recent searches in toolbar Search box.
•	command="BlockPopups" – Toggles Pop-up blocker on/off.
•	command="AllowPopups" – Adds currently visited website to the pop-up whitelist.
•	command="ClearCount" – Clears count of blocked pop-ups.
•	command=”EnableFlash” – Toggles on/off loading of flash animations.
•	command=”EnableImage” – Toggles on/off loading of images in the browser.
•	command=”ClearRecycleBin” – Clears the Recycle Bin.
•	command=”ClearTemp” – Clears system temporary folder.
•	command=”RemoveRecent” – Clears list of the Recent Documents in the Start menu.
•	command=”ClearClipboard” – Clears the clipboard.
•	command=”ClearAddressbar” – Clear URLs entered into the address bar.
•	command=”ClearAutoFill” – Clears browser Autofill information for HTML forms and  all passwords.
•	command=”ClearIEHistory” – Clears browser history.
By defining additional commands (<CHANGELAYOUT>, <SWITCHCOMMAND> e.t.c.) in <COMMANDS> section more sophisticated behavior 
can be added to the toolbar. For example you can define: 

<WEBJUMP name="search1" href="http://www.google.com/search?q=%combo1&hl=en"/>

And reference it from the button as:

<BUTTON id="tb_button_search" caption="GO" img="1" hint="" command="search1"/>

so that when you click that button search will be performed on Google.com using the keywords from combo1 combobox.
The toggle-type button (like popup blocker button) can also have an attribute captionp and imgp that defines the caption 
and icon for the button in pushed state. The format for <BUTTON> in that case is following:

<BUTTON id="some_id" caption="Blocker disabled" captionp="#cnt# blocked" img="4" imgp="5" command="blockPopups"/>

visibility - by setting this attribute="0", you can make the button not to appear by default. 
It can be enabled by from the options page.

See also: controlling the elements visibility, Options page, Button with an image, defining button images as transparent, 
<COMMANDS> section

<CHANGELAYOUT>

<CHANGELAYOUT> command
The syntax for CHANGELAYOUT command is the following:

<CHANGELAYOUT name=”to_german” layout="1"/>

There are three attributes: 
name – a name of the command that can be used in button or menu item
command= attribute 
layout – defines the numeric value of the layout to switch to. See Multiple layouts section for explanations.

<CHECKBOX>

<CHECKBOX> tag
Using <CHECKBOX> you can create 2-state checkbox control on the toolbar.

<CHECKBOX name=”checkbox1” id="cb_cbs1" caption=”Allow changes?” hint=”Tick to allow your changes to be submitted”/>

Checkbox has the following attributes:
•	name - specifies the name of the checkbox. The value of the checkbox can be accessed via substitutable variable 
containing percent sign % in behind of the checkbox name like: 
http://www.yourtoolbar.com/applystatus.php?status=%checkbox1
If the checkbox is marked %checkbox1 value is 1, otherwise it is 0.
•	id attribute contains identifier for the <CHECKBOX>. This identifier can be used to control visibility of that 
checkbox from the toolbar options page. Identifier has to be unique across all the toolbar elements.
•	caption – text label to the right of the checkbox
•	hint – specifies the message that will be shown when the user rolls the mouse over the checkbox
•	visibility - by setting this attribute ="0", you can make the check box not to appear by default. 
It can be enabled by from the options page.

<CLEARCOUNT>

<CLEARCOUNT> command
This command clears the count of blocked pop-ups.

<COMMANDS>
<CLEARCOUNT name="clearcount"/>
</COMMANDS>

You can assign a menu item or button with this command.

<BUTTON id="bt_id" caption="Clear pop-up blocker cound" img="4" command="clearcount"/>

To display current blocked count use #cnt# inside the hint or caption of the pop-up blocker button.

<COMMANDS>

<COMMANDS> tag
You can define the following commands: <WEBJUMP>, <LOCALHTML>, <CHANGELAYOUT>, <SWITCHCOMMAND>, <ZOOMIN>, <ZOOMOUT>, 
<RESETZOOM>, <CLEARHISTORY>, <CLEARCACHE>, <CLEARCOOKIES>, <HIGHLIGHT>, <BLOCKPOPUPS>, <ALLOWPOPUPS>, <ENABLEFLASH>, 
<ENABLEIMAGE>, <CLEARCOUNT>, <HIDEBUTTON>, <CLEARRECYCLEBIN>, <CLEARCLIPBOARD>,  <CLEARADDRESSBAR>, <CLEARTEMP>, 
<REMOVERECENT>, <CLEARAUTOFILL>, <CLEARIEHISTORY>, <SHELLEXECUTE>, <COMMANDCHUNK>, <RELOAD>, <HIDETOOLBAR>, 
<UNINSTALL> and <UPDATE>.
The command definitions have to be placed in between <COMMANDS>  and </COMMANDS> tags in the configuration file.
If you have defined a command named newcommand1 it could be then associated with any button, menu item or 
COMBOBOX, EDIT or PASSWORD control. To associate with a button please use:

<BUTTON caption="The caption you need" img="5" hint="hint" command="newcommand1"/>

to associate with a menu item please use:

<ITEM caption=”My menu item” img="" command="newcommand1"/>

The following sample represents commands definition that is usually used in the toolbar:

<COMMANDS>

<!— Change zoom -->
<ZOOMIN name="ZoomIn"/>
<ZOOMOUT name="ZoomOut"/>

<!— Reset zoom to the original (100%) -->
<RESETZOOM name="ResetZoom"/>

<!—Clears history in combo boxes -->
<CLEARHISTORY name="clearhistory"/>

<!—Highlights combo text in document -->
<HIGHLIGHT name="Highlight"/>

<!— Reloads toolbar XML -->
<RELOAD name="reloadToolbar"/>

<!—Popup windows killer (toggle) default = 1(enable function)/0(disable function) -->
<BLOCKPOPUPS name="blockPopups" cursor="blocked.cur" wave="click.wav" default="1"/>

<!— Erases browser cookies for the current user of computer-->
<CLEARCOOKIES name="clearCookies" message="This will erase your cookies. Are you sure?"/>

<!— Erases browser cache for the current user of computer-->
<CLEARCACHE name="clearCache" message="This will erase your cache. Are you sure?"/>

<!— Uninstall the toolbar -->
<UNINSTALL name="uninstall"/>

<!— Check if update is available and perform the update -->
<UPDATE name="update"/>

<!— Enable/disable images in webpages -->
<ENABLEFLASH name="flena"/>

<!— Enable/disable flash in webpages -->
<ENABLEIMAGE name="imge"/>

<!— Hide a button -->
<HIDEBUTTON name="command_name" id="button_id"/>

<!— Clear Recycle Bin -->
<CLEARRECYCLEBIN name="command_name"/>

<!— Clear clipboard buffer -->
<CLEARCLIPBOARD name="command_name"/>

<!- Hide toolbar -->
<HIDETOOLBAR name="hidetoolbar"/>

<!- Clear address bar of the browser -->
<CLEARADDRESSBAR name=”clearaddressbar”/>

<!- Clear system TEMP folder -->
<CLEARTEMP name=”cleartemp”/>

<!- Clear the recent documents list in the start menu -->
<REMOVERECENT name=”removerecent”/>

<!- Clear saved strings entered to HTML forms and passwords in IE -->
<CLEARAUTOFILL name=”clearautofill”/>

<!- Clear browser history of visited websites -->
<CLEARIEHISTORY name=”cleariehistory”/>

</COMMANDS>

Some commands have additional attributes and described below.

<COMMANDCHUNK>

<COMMANDCHUNK> command to execute several commands at once
Sometimes it is necessary to perform more than one command at once. For example, if you’d like to bind all 
browser-cleaning commands to a single button called “Clear ALL”. To do this, you need to group all the commands inside a 
<COMMANDCHUNK> and then call this command.


<COMMANDCHUNK name="clean_browser">
	<EXEC command="clearhistory"/>
	<EXEC command="cleariehistory"/>
	<EXEC command="clearcookies"/>
<EXEC command="clearautofill"/>
<EXEC command="clearcache"/>
</COMMANDCHUNK>

<BUTTON id=”btn_clear” caption=”Clear All” command=”clean_browser”/>

<COMBO>

<COMBO> tag
You can add editable combo box search field to the toolbar. To do this you need to use <COMBO> tag. Example:

<COMBO id="se_search_text" name="se_search_text" hint="" command="musicSearch" limit="40" histmax="10" ptext=”classic” dwidth=100 >
          
</COMBO>

COMBO tag has a following set of attributes:
•	name specifies the name of the search box. Combo box text can be accessed via substitutable variable 
with a % sign preceding the combo name like this: http://www.yourtoolbar.com/search?q=%se_search_text
•	hint – specifies the “tooltip” message that will be shown when the user rolls the mouse over the Search box.
•	command specifies the WEBJUMP command to be executed when the user clicks “Enter” or just “drag-and-drops” 
text fragments into the search box. See the commands section below on how to define the WEBJUMP command.

<WEBJUMP newbrowserwindow="false" href="http://www.yourtoolbar.com/search?q=%se_search_text" name="musicSearch"/>

•	limit specifies how many characters the user can type into that Search field (maximal length of the search terms).
•	histmax - how many items to keep in Search box history.
•	id attribute contains identifier for the <COMBO>. This identifier can be used to control visibility of that 
combobox from the toolbar options page. Identifier has to be unique across all the toolbar elements.
•	dwidth - you can specify the width for that Search box in pixels. 
•	ptext – the default text that will be entered into the combobox
The combo box can display a static text that dissappears once the users starts to input. 
Several additional attributes are used for this effect:
•	text – the string of text to be displayed (will disappear when the user types something in)
•	fname – font name
•	fsize – font size
•	warning -text of this attribute is displayed if user runs search with empty combo.

<COMBO text="Enter text here" fname="Verdana" fsize="16" 
href="http://www.yourtoolbar.com/search?q=%se_search_text" name="musicSearch" />

visibility - by setting this attribute ="0", you can make the combo box not to appear by default. 
It can be enabled by from the options page.

<COMBO> tag for select-type combo boxes (non-editable)

<COMBO> tag for select-type combo boxes (non-editable)
You can add non-editable combo box using <COMBO> tag and several <VALUE> tags. For example:

<COMBO id="se_search_option" name="se_search_option" hint=""
command="musicSearch">
        <WIDTH>100</WIDTH>
        <VALUE display="Artist" >Artist</VALUE>
        <VALUE display="Single" >Single</VALUE>
        <VALUE display="Album" >Album</VALUE>
</COMBO>

In that case the following attributes are supported: 
•	name specifies the name of the search box. Combo box text can be accessed via substitutable variable like this: 
http://www.yourtoolbar.com/search?type=%se_search_option. When the user selects one of the options from the list 
the value specified in display= of <VALUE> will be substituted instead of %se_search_option. 
•	hint – specifies the “tooltip” message that will be shown when the user rolls the mouse over the Search box.
•	command specifies the WEBJUMP command to be executed when the user clicks “Enter” being in that search box. 
See the commands section below on how to define the WEBJUMP command.

<WEBJUMP newbrowserwindow="false" href="http://www.yourtoolbar.com/search?q=%se_search_text" name="musicSearch"/>

•	id attribute contains identifier for the <COMBO>. This identifier can be used to control visibility of 
that combobox from the toolbar options page. Identifier has to be unique across all the toolbar elements.
•	width -using <WIDTH>100</WIDTH> you can specify the width for that Search box in pixels. You can specify several 
widths for the combo box. The default value is the first in the list. 
The other values are the values that the customer can choose from the “options page” as defined in 
<SETTINGS> section (see below).

<DNSCATCH>

<DNSCATCH> tag to catch DNS and Error 404
To use this feature you need to add the following code to the <SETTINGS> section of the XML file:

<DNSCATCH href="http://yoursite.com/search?text=%s"/>

%s will be replaced with the site URL that was not found or when the page is not available.
NOTE: When the connection fails it is sometimes hard to find out whether this is DNS error or DNS unavailable 
so the AUTOSEARCH url can be launched. We recommend that you use both AUTOSEARCH and DNSCATCH.

<EDIT>

<EDIT> tag 
You can create edit box inside the toolbar by using <EDIT> tag:

<EDIT id="edt_user" name="edt_user" hint="" command="loginuser" limit="40" ptext=”anonymous”>
         <WIDTH>100</WIDTH>
</EDIT>

Attributes of the EDIT tag are following: 
•	name specifies the name of the edit box. Edit box text can be accessed via substitutable variable like this: 
http://www.yourtoolbar.com/login.php?username=%edt_user
•	hint - specifies the message that will pop-up when the user rolls the mouse over the edit box.
•	command specifies the WEBJUMP command to be executed when the user clicks “Enter” or just “drag-and-drops” 
text fragments into the edit box. See the commands secton below on how to define the WEBJUMP command like the one below.

<WEBJUMP newbrowserwindow="false" href="http://www.yourtoolbar.com/login.php?username=%edt_user" name="loginuser"/>

•	limit specifies how many characters the user can type into the edit box (maximal length of the search terms).
•	id attribute contains identifier for the <EDIT>. This identifier can be used to control visibility of that edit box 
from the toolbar options page. Identifier has to be unique across all the toolbar elements.
•	ptext – the default text entered into the editbox
•	width - using <WIDTH>100</WIDTH> you can specify the width for that edit box in pixels. 
You can specify several widths for the edit box. The default value is the first in the list. 
The other values are the values that the customer can choose from the “options page” as defined in 
<SETTINGS> section (see below).
•	visibility - by setting this attribute ="0", you can make the edit box not to appear by default. 
It can be enabled by from the options page.

<ENABLEIMAGE>

<ENABLEIMAGE> command
You can switch on/off display of images by using the ENABLEIMAGE command. To use it you should define it in the COMMANDS 
section and assing a button or menu item to it.

<COMMANDS>
	<ENABLEIMAGE name="imge" />
</COMMANDS>
<BUTTON id="btimages" caption="Show Images" command="imge"/>

<ENABLEFLASH>

<ENABLEFLASH> command
You can switch on/off display of flash by using the ENABLFLASH command. To use it you should define it in the COMMANDS section 
and assing a button or menu item to it.

<COMMANDS>
	<ENABLEFLASH name="flena" />
</COMMANDS>
<BUTTON id="btflash" caption="Show Flash" command="flena"/>

<EXTERNAL_SEARCH>

<EXTERNAL_SEARCH> tag to catch search queries
Users can search via different search engines like Google or Yahoo. You can catch the search terms and put them into 
a search box on your toolbar so your users will have an option to get a results from your engine by simply clicking a button. 
When EXTERNAL_SEARCH setting is provided, the toolbar will parse the URL that is being accessed and will extract the keywords. 
The following example will catch searches done on Google and put keywords into a search box named combo1:

<EXTERNAL_SEARCH target="combo1" engine="http://www.google.com/search" param="q="/>

The URL can contain wildcards: * – matches any number of characters and ? – matches single character.

<EXTERNAL_SEARCH target="combo1" engine="http://*google.*/*" param="q="/>

The EXTERNAL_SEARCH tag also has encoding attribute as the WEBJUMP command does. It defines the encoding for the search string. 
See the Commands section for details on values supported for encoding= attribute:

<EXTERNAL_SEARCH target="combo1" engine="http://www.mysite.com/search" param="q=" encoding=”65001”/>

<HIGHLIGHT>

<HIGHLIGHT> command
Highlighting allows marking search keywords with different colors on a webpage. 
To place a highlight button add a button with command set to Highlight:

<COMMANDS>
<HIGHLIGHT name="Highlight"/>
</COMMANDS>
<BUTTON caption="" hint="Toggle highlighting of search terms on this page" id="tb_btn_KVasNoxV" img="99" command="Highlight"/>

The colors used for highlighting are got from <HIGHLIGHT> subsection of the <SETTINGS> in configuration file. 
The example below

<HIGHLIGHT>
	<COLOR>F6FF00</COLOR>
	<COLOR>00FFE4</COLOR>
	<COLOR>5AFF00</COLOR>
	<COLOR>0087FF</COLOR>
	<COLOR>FFCC00</COLOR>
	<COLOR>FF00F0</COLOR>
</HIGHLIGHT>

defines several different colors that will be used to highlight the search keywords within a webpage. 
The first keyword located will be highlighted with the color F6FF00 (yellow), the next will be highlighted with 00FFE4 (Cyan) 
and so on in cycle.

<HOMEPAGE>

You may add the following line to the <SETTINGS> section of the toolbar .XML file and the default homepage of the user 
will be set to the one you had defined.

<HOMEPAGE href="http://yoursite.com/"/>

<INCLUDE_XML>

INCLUDE_XML tag allows you to implement advanced and interactive toolbars. Dynamic toolbar behavior and Multiple configurations
are achieved using the INLCUDE_XML tag. With the help of this tag you can achieve server/toolbar interaction 
having dynamic menus and targeted interactive content in your toolbar. 
Being combined with macro substitutions like Toolbar ID, User ID, Username, UserPassword, current URL e.t.c. 
this allows to achieve personal appearance for the toolbar users and provide better customer interaction.
The basic format for INCLUDE_XML is the following:

<INCLUDE_XML filename="http://www.yourserver.com/toolbar/toolbar.xml"/>

This will tell the toolbar to query the file located on your server at http://www.yourserver.com/toolbar/toolbar.xml 
each time the browser with the toolbar is open. Changing this file on your server will allow dynamically change 
the toolbar appearance for all your customers. 
The following attributes are supported for INCLUDE_XML tag:
•	filename – a file to be included. It can be a local file like tb12.xml or this can be a server side file 
like http://www.yourtoolbar.com/toolbarconf.xml. 
You can also make this to contain a reference to a server side script as in the below example:

<INCLUDE_XML filename="http://yourtoolbar.com/news.php?URL=%toolbar_id"/>

•	expire – defines the period in minutes to refresh the file. The default value of 0 means that the XML file 
is refreshed when the browser starts. Setting this to non-zero value will allow to refresh XML file periodically. 
The file downloaded is being cached so that if the internet connection fails the cached version will be used 
till the connection is reestablished. You can use expire= to notify the users while they surf the internet.

<INCLUDE_XML filename="http://yourtoolbar.com/news.xml?id=%toolbar_id&user=%user_id" expire="10"/>

NOTE: Setting expire to big value will allow to minimize traffic that the toolbar generates to your server in dynamic mode.
 The cached versions of the files will be used and the server will be requested only after expiration of the cache. 

•	layout – this numeric attribute is used to achieve multiple toolbar configurations. The default setting for 
this attribute is 0. The toolbar parses .XML files according to the current layout specified for the toolbar 
(default is specified inside the <TOOLBAR> tag). Using the special command CHANGELAYOUT you can change the layout
used for the toolbar achieving multiple toolbar configurations. You can use multiple toolbar configurations to have 
your toolbar in several languages or have your toolbar in switchable between minimal and full configuration.   

•	sync – this optional property is used to trigger refreshing of the XML file while the user surfs the net.
The possible options are: BeforeNavigate and onDocumentComplete. An XML is refreshed each time a new document 
is opened in the browser (i.e. while user surfs the net). These values have the following difference: 
BeforeNavigate is triggered before the page is downloaded,  onDocumentComplete is triggered after the page is downloaded completely.  

<INCLUDE_XML filename=http://yourtoolbar.com/news.php?id=%toolbar_id&user=%user_id" sync="BeforeNavigate"/>

•	urltemplate – is used in conjunction with sync= attribute to trigger the synchronization only when specific 
pages are visited. This is useful to update the toolbar appearance after the user accesses specific sites or 
specific pages on these sites. You can specify web page name here or website name. urltemplate=”specialpage.php” or 
urltemplate=”www.specificsite.com” 

•	no_cache – when this attribute is set to 1, the included files will not be cached.

•	local ¬– if the file specified in the filename= attribute is unavailable (e.g. the system is offline and 
can not load an XML from the web) then the local file specified here would be loaded instead.

<INCLUDE_CUSTOM_XML>

Like <INCLUDE_XML>, this tag allows you to dynamically change contents of the toolbar, but the method is different. 
Instead of pointing to a file or URL, new content is obtained from a javascript.
Example:
This line shall be somewhere in the toolbar XML:

<INCLUDE_CUSTOM_XML name="custom_1"/>

The following HTML code will place a string with a random number in toolbar. It will be positioned where the above line is 
encountered in XML. Have a look at the Accessing toolbar properties via Javascript section to learn more about 
using JavaScript to conjunction with the toolbar.

<script language="JavaScript" type="text/javascript">
var m_TBObj = null;
function ToolBarInit(softomate_toolbar) {
	m_TBObj = softomate_toolbar;
}
function customxml () {
	if(m_TBObj) {
		var s = Math.random() * 10 + "";
		var n = s.substr(0,1);
		m_TBObj.CustomXML("custom_1") = '<toolbar><text id="12312" caption="Number is ' + n + '"/></toolbar>';
		m_TBObj.Reload();
	}
}
</script>
<button onclick="javascript:customxml();">CustomXML Demo</button>

<INCLUDE_SCRIPT >

A non-visual element which can actually effectively replace hidden banners.
Supports the following attributes:
expire – time period in minutes to reload the remote script;
sync – events(“OnDocumentComplete” or “BeforeNavigate”) on which remote script will be reloaded.
filename – name of the local or remote .js file with script
id – name of the script, can be used in the LAUNCHSCRIPT command.
As in the banner if function DocumentComplete is defined inside the script then it is called each time page is loaded in browser. 
Example:
function DocumentComplete(tool,type)
{
	if(type == “window”)	//-- IE page is reloaded
		….;
	else if(type == “toolbar”)	//-- toolbar is reloaded (tool.Reload() has been called)
		….;
}
Inside the script there is no standard object window. To access it use the following format:
MainWindow.document.parentWindow
Example to show an alert:
MainWindow.document.parentWindow.alert(‘hi bugs’);

<LOCALHTML> command

The <LOCALHTML> tag is used to reference HTML pages, and other local files that you distribute with your toolbar 
(in the toolbar download package). 
For example when you distribute an HTML page called myinfo.html and would like it to be opened in a new “modal” 
browser window you can define the following command:

<LOCALHTML name="myinfo" href="myinfo.html" newbrowserwindow="modaldialog"/>

A Modal browser window means that you have to close it prior accessing other browser windows.
The options possible for the newbrowserwindow attribute are: “true”, “false” and “modaldialog”. 
•	true means that the html page will be opened in a new window 
•	false means that it will be opened in the same browser window 
•	modaldialog means that it will be opened in a new window that has to be closed before the user can continue 
to browse (useful for dialog-box pages). 
Another attribute that is supported by LOCALHTML command is the 
•	options attribute that defines how the open the window is formatted. 

Here is an example demonstrating use of the options attribute:

<LOCALHTML href="about.html" name="about" newbrowserwindow="modaldialog"
options="status:no;help:no;dialogHeight:220px;dialogWidth:450px;scroll:no;"/>

Note: LOCALHTML is also used to put any file into the distribution package. This way you can distribute additonal 
Graphics files, HTML help pages, DLL’s or .EXE applications with your toolbar. 
Anything that is referenced using LOCALHTML get’s included into .cab. Use: 

<LOCALHTML name="myapp" href="myapp.exe" /> 

to include an .EXE named myapp.exe into your distribution.

<LAUNCHSCRIPT> command

scriptid – id of the script which to launch.

This command is used to launch a function inside an included script. This command calls Launch function inside the script. 
Example:
function Launch(tool)
{
    //your Javascript function
}

MACRO SUBSTITUTIONS

There are a lot of variables available in the toolbar that can be substituted into the url that the toolbar uses 
for BANNER, BUBBLE and INCLUDE_XML tags. These substitutions can also be put into any URL (WEBJUMP command or href 
attribute for BUTTON/MENU ITEM). The following macro substitutions are available:
%AffiliateID – If there is a file called affid.dat in the folder where the toolbar.dll is located. 
This variable simply contains the contents of that file. If the file does not exist this variable is empty. 
Refer to the Using affiliate capabilities chapter for details.

%currentlayout – current layout used for the toolbar (see CHANGELAYOUT command)
%clipboard – text in the clipboard.
%clsid –CLSID keys of the toolbar in {1BB22D38-A411-4B13-A746-C2A4F4EC7344}
%domain – current domain open in the browser.
%enclsid  - CLSID keys in the denary format
%encoding – current char set for the open page.
%guid – guid defined in the <Toolbar> tag of basis.xml
%htmlselection – current text selection with HTML formatting.
%meta – encoded meta keywords for the page.
%ie_handle - hWnd handle of IE window
%image – current image selection
%install_path  - installation path of the toolbar, for example c:\toolbar
%pagehtml – current page in HTML format
%pagetext  - current text without HTML formatting
%plain_domain – not encoded domain name, can be used in button captions.
%plain_meta – meta keywords for the page.
%plain_url –  not encoded URL, can be used in button captions.
%plain_title – page title not encoded, can be used in button captions.
%PromoCode – it has no special meaning, you can use it to store any value.
%referrer -  the URL of the previous webpage from which a  link was followed.
%reg  - registry access from the toolbar , Example :   
            %reg(HKEY_CURRENT_USER\Console\HistoryBufferSize)
%selection – current text selection without HTML formatting.
%temp_path – temporary folder of toolbar installation	
%title – encoded page title, can be used in URLs.
%toolbar_id – unique toolbar ID (generated automatically, unique for each toolbar installation, but stays the same 
after toolbar is updated or reinstalled)
%toolbar_version – toolbar version (from the version.txt file).
%url – current URL opened in the browser.
%user_name – user name (this variable is used to store the username. Value for this variable could be set via Javascript 
see the below section for details).
%user_pass – user password. (this variable is used to store a password. The value for this variable can be set via Javascript
 see the below section for details).
%user_id – user ID. (this variable contains userid and value for this variable could be set via Javascript 
see the below section for details).
%userid – user id defined in the <Toolbar> tag of basis.xml
%var1, %var2, ..., %var10 – these variables have no special meaning, you can use them to store any value and use it in macros 
and javascript. This gives you ability to extend the toolbar functionality.
%Svar1, %Svar2, ..., %Svar10 – these variables have no special meaning, you can use them to store any value and use it 
in both macros and javascript. This variables are secured. You cannot read the values in Javascript, you can only assign 
new values to them. This gives you ability to extend the toolbar functionality.

Plus, you can substitute value currently entered into any <PASSWORD>, <EDIT>, <CHECKBOX> or <COMBO> control by preceding 
the name of that control with the percent sign. Like:   %<combo_name> - will substitute text from the combo box with specified name.

Example:

<INCLUDE_XML filename="http://www.yoursite.com/getrank.asp?toolbar_id=%toolbar_id&URL=%url" sync=”OnDocumentComplete”/>

<ITEM> tag

To add new menu item to the existing menu or submenu just place the following line in between <MENU></MENU> tags:

<ITEM id=”itm_mypage1” caption="My menu item“ img="1" hint="" href="http://www.yourtoolbar.com/mypage.html" command="redirect"/>

In the above fragment the caption is the text that will be shown in the menu.
img attribute contains the index of the image in the icons.bmp file. 
 
The toolbar supports 16 x 16 pixels bitmaps on the toolbar buttons. 
The img="1" setting will reference the first 16 x 16 image in the icons.bmp file. (It is the picture with a smiling sun 
in this example). 
id attribute contains identifier for the menu item. This identifier can be used to control visibility of that item from 
the toolbar options page. The identifier has to be unique across all the toolbar elements.
hint setting allows you to specify the text that will be shown in the browser status line when the customer rolls 
the mouse over the menu item.
You can make the menu item caption to be bold or italic by using style attribute in the following manner:

<MENU>
<ITEM id=”mn1” caption=”Bold Item” style=”bold”/>
<ITEM id=”mn2” caption=”Bold Italic Item” style=”bold;italic”/>
</MENU>

href attribute is the URL of the page to which the user will be redirected when they chose the item from the menu 
(this will be used only if the attribute command is rset to “redirect”). 
command attribute defines the action for the menu item when it is chosen. command="redirect" means that choosing 
this menu item will redirect the user to another location on the web specified by href attribute. 
By defining additional commands you can add sophisticated behavior to the menus.
The command can also be:
•	command="uninstall" – uninstalls the toolbar.
•	command="update" – update the toolbar.
•	command="reload" – reloads the toolbar .XML file.
•	command="Highlight" – toggles Highlghing of the words in a search page on/off.
•	command="ZoomIn" and command="ZoomOut" zooms the current HTML page.
•	command="ResetZoom" - Reset zoom to normal (100%)
•	command="ClearCookies" - Clears cookies in the user browser.
•	command="ClearCache" - Clears browser cache.
•	command="ClearHistory" - Clears search history.
•	command="BlockPopups" – Toggles Pop-up blocker on/off. 
•	command="AllowPopups" – Adds currently visited website to the pop-up whitelist.
•	And so on for all commands existing in the <COMMANDS> section.
You can also define custom additional commands in <COMMANDS> section of the configuration file like <CHANGELAYOUT>, 
<SWITCHCOMMAND> or <WEBJUMP>.
By setting the visibility="0" attribute, you can make the menu item not to appear by default. 
It can be enabled by from the options page.
shortcut attribute - last symbol is the letter which launch, before it any of the modificators in any order: 
ctrl, alt, shift. Example: “ctrl+shift+a”

<ITEM> tag and Submenu Items

Adding submenu items is done in the same way as adding new menu items. The only difference is that you have to 
put the <ITEM> tag in between of two another <ITEM> tags.  The following fragment of configuration file demonstrates this. 
(It defines 2 submenu items called “History” and “Science” under a menu item called “Books”. 
The menu itself is shown when the user clicks the “Order” button):

<BUTTON caption="Order" img="18" hint="" href="http://www.yourtoolbar.com/shop” command="redirect">
<MENU type="Split">
   <ITEM caption="Books" img="1" hint="" href="" command="redirect">
<ITEM caption="History"  img="1" hint="" href="http://www.yourtoolbar.com/shop/category.asp?a=history" command="redirect" />
<ITEM caption="Science" img="1" hint=""  href="http://www.yourtoolbar.com/shop/category.asp?a=Science" command="redirect"/>
   </ITEM>
</MENU>
</BUTTON>

You can have unlimited number of menu items and submenu items you can also define sub-sub and sub-sub sub items 
as you need without any limits. 

<MENU>

You can make a menu apearing when the button is clicked.  If you have the following button in your toolbar: 

<BUTTON caption="The caption you need" img="5" hint="hint" command="redirect" href="http://www.yourtoolbar.com/somepage.com"/>

you can easily add the menu to be displayed when the button is clicked by inserting <MENU></MENU> tags shown below:

<BUTTON caption="The caption you need" img="5" hint="hint"  href="http://www.yourtoolbar.com/somepage.com" command="redirect">
<MENU type="Single">
<ITEM caption="Login" img="1" hint="" href=http://www.yourtoolbar.com/login.asp command="redirect"/>
<ITEM caption="Forgot password?" img="4" hint=""  href="http://www.yourtoolbar.com/forgotpassword.asp" command="redirect"/>
	</MENU>
</BUTTON>

Please note that the <BUTTON … /> split to <BUTTON> … </BUTTON>	
In the example above the menu will pop-up when the button is clicked. The menu can have 2 diffeent types: 
type=”Single”  and  type=”Split” . 
In the latest case the button itself will redirect the user to one location while clicking on a small button with arrow 
will show the menu. 
By img= attribute you can specify the image to be displayed on the toolbar button that triggers this menu. 
This setting is similar to setting image= attribute for the <BUTTON>.

…
<MENU img=”your_button.bmp" hot_img=”hot_button.bmp" type="Split">
…

See also: <ITEM> tag, <BUTTON> tag.

<PASSWORD>

You can create password box (that hides all input characters with *) using <PASSWORD> tag:

<PASSWORD id="pwd_user" name="pwd_user" hint="" command="loginuser" limit="40">
         <WIDTH>100</WIDTH>
</PASSWORD>

Attributes of the <PASSWORD> tag are the same as for <EDIT> tag. The text from the password box can be accessed 
via substitutable variable containing percent sign % in behind of the password box name like: 
http://www.yourtoolbar.com/login.php?username=admin&pwd=%pwd_user
By setting the visibility="0" attribute, you can make the password box not to appear by default. 
It can be enabled by from the options page.

<RADIOBOX>

Radiobox has the following attributes:
 
•	name – name of this particular radio box;

•	group – name of the group of radios which is substituted to the URLs;

•	default – 0 or 1 enabled by default in the group.

Example: %groupname will be replaced with name of the currently selected radio box from this group

<SEPARATOR> tag

This tag inserts a horizontal or vertical separator line between menu or submenu items or between buttons. 
The separator is useful to divide the items that are logically different.

<ITEM caption="Login" img="1" hint="" href=”http://www.yourtoolbar.com/login.asp” command="redirect"/>
<SEPARATOR/>
<ITEM caption="Uninstall" img="4" hint="" href="" command="uninstall"/>

In the above fragment <SEPARATOR/> will insert the line in between “login” and “Uninstall” menu items.

===<SETHOMEPAGE> command

href – link to the home page.

This command sets default home page.

<SHOWMENU> command

Shows the menu for the current button and can be used only in buttons. Ex.:

<BUTTON command=”showmenu”>
   <MENU type=”none”>
…
    </MENU>
</BUTTON>
<COMMANDS>
	<SHOWMENU name=”showmenu”/>
</COMMANDS>

This command usually used to create a button with menu but without arrow.

<SETTINGS> section

contains all the configuration details including URL’s used for the toolbar update, install and uninstall.
It also contains messages tests displayed by the toolbar (change them to localize the toolbar), 
default settings for the toolbar and item definitions for Options.html page. <SETTINGS> section usually looks like this:


<SETTINGS scope=”10” regkey="YourCompany\\ToolbarNavigator">

<MESSAGE id="corruptedMsg" default="One of the XML files is corrupted or invalid. Press OK to uninstall."/>
<MESSAGE id="uninstallMsg" default="This will remove the Toolbar from your computer! Are you sure?"/>
<MESSAGE id="updateMsg" default="This will try to update the Toolbar from the server. Continue?"/>
<MESSAGE id="autoUpdateMsg" default="New version of Toolbar is available. Would you like to download and install new version?"/>
<MESSAGE id="connectionError" default="Can't establish a connection."/>
<MESSAGE id="lastVersionMsg" default="You have the latest version of the Toolbar."/>
<MESSAGE id="contextMenuItemName" default="Toolbar search"/>
<MESSAGE id="closeAllWindowsForUpdate" default="All running IE Windows will be closed before updating the Toolbar. Continue?"/>
<MESSAGE id="UpdateError" default="Unable to update toolbar"/>
<MESSAGE id="AlertMsg" default="Alert"/>
<MESSAGE id="ErrorMsg" default="Error"/>
<MESSAGE id="FindWord" default="Find next word in context"/>
<MESSAGE id="closeAllWindowsForUninstall" default="Close all opened IE windows?"/>

<URL id="firstURL" default="http://www.yourtoolbar.com/toolbar/toolbar.asp#how?toolbar_id=%toolbar_id"/>
<URL id="serverpath" default="http://www.yourtoolbar.com/toolbar/"/>
<URL id="updateUrl"	default="http://www.yourtoolbar.com/toolbar/toolbar.cab"/>
<URL id="urlAfterUpdate" default="http://www.yourtoolbar.com/toolbar/toolbar_update.asp?toolbar=update"/>
<URL id="urlAfterUninstall" default="http://www.yourtoolbar.com/toolbar/toolbar_update.asp?toolbar=uninstall"/>
<URL id="contextSearch"default="http://www.yourtoolbar.com/q_a/qa_search_results.asp?SearchType=All&question=%combo1"/>

<SIDESEARCH href=”http://www.yoursearch.com/”/>

<CONFIGALLOW>www.yoursite.com</CONFIGALLOW>
<CONFIGALLOW>www.sitename.com</CONFIGALLOW>

<DRAGCURSOR cursor="somefile.cur"/>

<USERAGENT name="additional str"/>

<CHECKBOX id="OpenNew" default="0"/>
<CHECKBOX id="AutoComplete"	default="1"/>
<CHECKBOX id="KeepHistory" default="1"/>
<CHECKBOX id="RunSearchAutomatically" default="1"/>
<CHECKBOX id="RunSearchDragAutomatically" default="1"/>
<CHECKBOX id="DescriptiveText" default="1"/>
<CHECKBOX id="ShowHighlightButton" default="1"/>
<CHECKBOX id="ShowFindButtons" default="0"/>
<CHECKBOX id="UpdateAutomatically" default="0"/>
<CHECKBOX id="PopUpSound" default="1"/>
<CHECKBOX id="PopUpCursor" default="1"/>
<CHECKBOX id="DebugDisable" default="1"/>

<COMBO id="EditWidthcombo1" default="1"/>

<COMBO id="EditWidthcombo2" default="2"/>


<RADIO name="EditWidthcombo1" default="1">
	<id>Widthcombo10</id>
	<id>Widthcombo11</id>
	<id>Widthcombo12</id>
</RADIO>

<RADIO name="EditWidthcombo2" default="2">
	<id>Widthcombo20</id>
	<id>Widthcombo21</id>
	<id>Widthcombo22</id>
</RADIO>

<FONT name="Tahoma" size="13"/>

<HIGHLIGHT>
	<COLOR>F6FF00</COLOR>
	<COLOR>00FFE4</COLOR>
	<COLOR>5AFF00</COLOR>
	<COLOR>0087FF</COLOR>
	<COLOR>FFCC00</COLOR>
	<COLOR>FF00F0</COLOR>
</HIGHLIGHT>

<COLOR_SCHEMA>

	<!-- Toolbar skin image -->
	<TOOLBAR_SKIN></TOOLBAR_SKIN>
			
	<!-- Toolbar color -->
	<TOOLBAR_FACE>235,233,217</TOOLBAR_FACE>

	<!-- Menu background color -->
	<MENU>235,233,217</MENU>

	<!-- Selected menu background color -->
	<SELECTED_MENU_ITEM>170, 0, 0</SELECTED_MENU_ITEM>

	<!-- Text color -->
	<TEXT></TEXT>

	<!-- Text of item(s) selected in a menu -->
	<HIGHLIGHT_TEXT></HIGHLIGHT_TEXT>

	<!-- Grayed (disabled) text in a menu -->
	<GRAY_TEXT></GRAY_TEXT>

	<!-- Highlight color for three-dimensional display elements (for edges facing the light source.) -->
	<HIGHLIGHT3D></HIGHLIGHT3D>

	<!-- Shadow for three-dimensional display elements. -->
	<SHADOW3D></SHADOW3D>		

</COLOR_SCHEMA>

<EXTERNAL_SEARCH target="combo1" engine="http://www.yourtoolbar.com/q_a/qa_search_results.asp" param="question="/>
<EXTERNAL_SEARCH target="combo1" engine="http://www.yourtoolbar.com/research/rr_search_results.asp" param="SearchCriteria="/>
<EXTERNAL_SEARCH target="combo1" engine="http://www.yourtoolbar.com/articles/articles_search_results.asp" param="SearchCriteria="/>
<EXTERNAL_SEARCH target="combo1" engine="http://www.google.com/search" param="q="/>
<EXTERNAL_SEARCH target="combo1" engine="http://search.microsoft.com/default.asp" param="qu="/>

</SETTINGS>

The firstURL  definition is required since it is used to display the page right after installation. 
All other settings are optional and you can omit them. 

The <SETTINGS> tag has 3 attributes: scope, regkey and remote_cfg.
The scope attribute defines a time-out interval (in hours) which the toolbar uses to check for updates 
when it works in auto-update mode (see below).
The optional regkey attribute specifies a registry key to store toolbar configuration in the registry.
In case of optional remote_cfg="false", any remote configuration will be disabled,
this value forces <CONFIGALLOW> option.

WARNING: this option is not potentially new, it's equal to specifying an empty <CONFIGALLOW> tag. 
It has been implemented only to ease development of security safe toolbars.
The first few items in between <SETTINGS> and </SETTINGS> are <MESSAGE/> tags. 
Those tags are used to define the message texts the toolbar uses. Change them to localize your toolbar.
The next few items are the URLs used for the toolbar update, auto-update and install/uninstall.
<URL id="firstURL" default="http://… "/> - REQUIRED. this contains the URL of the page that is shown right after user 
have installed the toolbar. You can put any URL you like (it can be your “member center” page, “thank you” page or 
just entry page of your website).
<URL id="serverpath" default="http://… /toolbarinstfolder/"/> - this has to contain the path to the folder 
where the toolbar installation files are stored. This folder is used to store .cab file with all the contents of the toolbar 
package. It is necessary that version.txt file is located in that folder also.
<URL id="updateUrl" default=" http://… /toolbarinstfolder/toolbar.cab"/> - this URL is used to download the newer 
toolbar package when the customer chooses an “update toolbar” option. The update will only happen if the version.txt 
on the server contains a version number greater than the one that is already installed.
<URL id="urlAfterUpdate" default=" http://… /afterupdate.html"/> - this page is shown after successful update of the toolbar. 

<URL id="urlAfterUninstall" default=" http://… /afteruninstall.html"/> - this page is shown after uninstalling of the toolbar. 
<URL id="contextSearch"	default="http://…?q=%combo1"/> - this URL is used to search selected text and links from the current 
HTML document via IE context menu (right-click search).
<CONFIGALLOW></CONFIGALLOW> tags are used to restrict the sites that are allowed to access the toolbar via Javascript. This 
protects your toolbar properties from unauthorized access and modification.
<SIDESEARCH> tag allows to redefine the URL that is opened in the sidebar search. And you can redefine it to open your site 
instead of the standard IE search panel.
<DRAGCURSOR> allows you to change shape of the mouse pointer when the drag-and-drop operation if performed. The cursor attribute 
name of a cursor image.
<USERAGENT> appends a custom text to the USER_AGENT string that is reported to webservers as a part of any HTTP GET/POST request 
the browser sends. This line will be stored in web server log files and thus you can track who is using your toolbar and who do 
not. Adding a custom content (like your website name) you can easily identify who is using your toolbar through the weblogs.
The next few lines contain default values for the items that are shown on the user “options page”. The default values could 
be adjusted to make the options default to on or off.
<CHECKBOX id="OpenNew" default="0"/> - Open a new browser window each time the user clicks search? (0-no, 1 -yes) 
<CHECKBOX id="AutoComplete" default="1"/> - Use the auto-completion feature of the search box (it suggests an afore typed 
search request if it’s beginning matches with what is typed into the search box). (0-no, 1 -yes)
<CHECKBOX id="KeepHistory" default="1"/> - Keep the history of the searches? (0-no, 1 -yes) 
<CHECKBOX id="RunSearchAutomatically" default="1"/> - Execute the search automatically after a text string was picked from 
the history? (0-no, 1 -yes) 
<CHECKBOX id="RunSearchDragAutomatically" default="1"/> - Execute the search automatically after “drag-n-drop” into search box? 
(0-no, 1 -yes) 
<CHECKBOX id="DescriptiveText" default="1"/> - Show only icons in toolbar (=0) or show the full text descriptions of the buttons 
(=1).
<CHECKBOX id="ShowHighlightButton" default="1"/> - The highlight feature is turned on if that value is 1 and it is off when 0.
<CHECKBOX id="ShowFindButtons" default="0"/> - Word find feature is turned on if 1 and off if that is 0.
<CHECKBOX id="UpdateAutomatically" default="0"/> - Perform auto-update automatically each time the browser is open? 
(0-no, 1 - ask user before updating, 2 – update silently).
<CHECKBOX id="PopUpSound" default="1"/> - Enable playing of sound when a popup is blocked.
<CHECKBOX id="PopUpCursor" default="1"/> - Enable effect of temporary mouse cursor change when a popup is blocked.

<COMBO id="EditWidthcombo1" default="1"/>
<COMBO id="EditWidthcombo2" default="2"/>

<CHECKBOX id="EnableSubMenuVisibility" default="1"/> - enables submenu visibility via Options page.

- Default widths for combo boxes. The “default” number is shown by dwidth attribute from <COMBO> definition. 
The next few lines are used to customize the appearance/colors used in buttons and menus. 
<FONT name="Tahoma" size="13"/> - specifies what font will be used for text captions and menu items.
Subsecion:

<HIGHLIGHT>
	<COLOR>F6FF00</COLOR>
	<COLOR>00FFE4</COLOR>
	<COLOR>5AFF00</COLOR>
	<COLOR>0087FF</COLOR>
	<COLOR>FFCC00</COLOR>
	<COLOR>FF00F0</COLOR> 		
</HIGHLIGHT>

defines the colors used for highlighting search keywords inside the document. 
The below section is optional and it defines colors and fonts to be used.

<COLOR_SCHEMA>
	<!-- Toolbar skin image -->
	<TOOLBAR_SKIN>skin.bmp</TOOLBAR_SKIN>

	<!-- Toolbar color -->
	<TOOLBAR_FACE>235,233,217</TOOLBAR_FACE>

	<!-- Menu background color -->
	<MENU>235,233,217</MENU>

	<!-- Selected menu background color -->
	<SELECTED_MENU_ITEM>170, 0, 0</SELECTED_MENU_ITEM>

	<!-- Text color -->
	<TEXT></TEXT>

	<!-- Text of item(s) selected in a menu -->
	<HIGHLIGHT_TEXT></HIGHLIGHT_TEXT>

	<!-- Grayed (disabled) text in a menu -->
	<GRAY_TEXT></GRAY_TEXT>

	<!-- Highlight color for three-dimensional display elements
	(for edges facing the light source.) -->
	<HIGHLIGHT3D></HIGHLIGHT3D>

	<!-- Shadow for three-dimensional display elements. -->
	<SHADOW3D></SHADOW3D>

</COLOR_SCHEMA>

Here you can define background color that the toolbar uses, skin for the toolbar, and background image for the toolbar and 
foreground color for the toolbar. The windows bitmap (.bmp) files for skin or background of the toolbar can have arbitrary 
dimensions. If you do not define the colors or simple remove the section <COLOR_SCHEMA></COLOR_SCHEMA> from the configuration 
file the default windows colors will be used for the toolbar appearance.
The colors are defined in RGB format so light red is “255,0,0” and green is “0,255,0” and so on.
There is one additional option for webdevelopers. Currently the pop-up blocker disables all Javascript error messages to be 
displayed when the pop-up blocker is on. This is required cause a lot of websites use Javascript to communicate with a 
pop-up window and since it is blocked the Javascript errors will be seen. But you can use the following inside the 
<SETTINGS> to allow the Javascript errors to be displayed regardless of the pop-up blocker on or off.
<CHECKBOX id="DebugDisable" default="0"/>

<SHELLEXECUTE> command

This command is used to launch all kinds of external applications. The command attribute specifies file name of an .exe file to launch. The options attribute can be used to pass options to it. If launch fails, a message box will open and display text specified in the not_found attribute.

<SHELLEXECUTE name="Prog" command="progname.exe" options="/s %combo1" not_found="Can't open Prog application..."/>

<SPACE> tag

Adds a horizontal space with given width:

<SPACE width="60" />

<SWITCHCOMMAND> command

SWITCHCOMMAND has the following syntax:

<SWITCHCOMMAND name="thisswitchname" target="target_combobox" command="New_command_Name"/>

It can be used to switch the search engines on the fly by using a code like the following:

<BUTTON id="swbtn" caption="MyCompaby" img=”8” command="swtch"/>
<COMMANDS>
<WEBJUMP href="http://www.yoursite.com/search?q=%search" name="keMdXGRo"/>
<WEBJUMP href="http://www.anotheryoursite.com/?q=%search" name="redir2"/>
<SWITCHCOMMAND name="swtch" target="keMdXGRo" command="redir2"/>
</COMMANDS>

Additionaly, the SWITCHCOMMAND can change a button text and icon if used like below:

<SWITCHCOMMAND name="swtch" target="keMdXGRo" command="redir2" switchbutton="buttn" switchtext="New label" switchicon=”3” />

Where 
switchbutton is a name of the button being changed;
switchtext is the new label on the button and 
switchicon specifies a new icon for it. 
If the button uses an image tag insted of img, the switchbmp should be used instead of switchicon. 

Here is an example of 3 search engines switching:
<COMMANDS>
<WEBJUMP name="searchGoogle" href="http://www.google.com/search?q=%search"/>
<WEBJUMP name="searchYahoo" href="http://search.yahoo.com/search?p=%search"/>
<WEBJUMP name="searchMSN" href="http://search.msn.com/results.aspx?q=%search"/>
<SWITCHCOMMAND name="sw_google" command="searchGoogle" target="searchGoogle"
switchbutton="btn_search" switchicon="20" switchtext="Google search"/>
<SWITCHCOMMAND name="sw_yahoo" command="searchYahoo" target="searchGoogle"
switchbutton="btn_search" switchicon="23" switchtext="Yahoo! search"/>
<SWITCHCOMMAND name="sw_msn" command="searchMSN" target="searchGoogle"
switchbutton="btn_search" switchtext="MSN search" switchicon="19"/>
<COMMANDS>
<COMBO id="tbs_combo_001441" command="searchGoogle" fname="Tahoma" fsize="13" limit="40"
histmax="10" name="search" dwidth="150" kind="editable">
<WIDTH>150</WIDTH>
</COMBO>
<BUTTON id="btn_search" caption="Google Search" img="14" command="searchGoogle">
<MENU id="tbs_button_002740" type="Split">
<ITEM id="tbs_item_013989" img="20" caption="Google" command="sw_google"/>
<ITEM id="tbs_item_018781" img="23" caption="Yahoo!" command="sw_yahoo"/>
<ITEM id="tbs_item_018141" img="15" caption="MSN" command="sw_msn"/>
</MENU>
</BUTTON>
Note: button command must be the same as combo-box command, othewise button label
and icon will not be changed.

<TEXT> tag

You can create a text label with any text by using <TEXT> tag:

<TEXT id="tb_text" hint="Some hint" caption="Some text"/>

In the fragment above the caption attribute contains the text to be shown. 
id attribute contains identifier for the text label. This identifier can be used to control visibility of that combobox from the toolbar options page. Identifier has to be unique across all the toolbar elements
hint setting allows you to specify ‘tooltip’ text to show when the user rolls the mouse over the button.
optional img attribute specifies index of the icon in the icons.bmp file. This icon will be shown on the left from the text label.
visibility - by setting this attribute ="0", you can make the text not to appear by default. It can be enabled by from the options page.

<TOOLBAR> tag

<TOOLBAR> tag has the following format:

<TOOLBAR name="IE Toolbar Sample" icons="icons.bmp" hot_icons="icons.bmp" dllname="toolbar" layout=”0”>

Attributes of the <TOOLBAR> tag:
•	name – the name of the toolbar displayed in the view->toolbars of the IE menu. It also displays as an item in the Start->Control Panel->Software
•	icons – Bitmap file containing icons for the toolbar. This file is a Windows bitmap file that has to be like the following: 

toolbar supports 16 x 16 pixels icons
•	hot_icons – Bitmap file containing hot icons for toolbar (used for rollover effect)
•	dllname – name of the DLL file with the toolbar. (usually toolbar.dll)
•	layout – if you are using several layouts you can specify the default layout here
•	height ¬– the optional attribute to change toolbar height (default is 22 pixels)
See also: SETTINGS section, COMMANDS section, INCLUDE_XML tag

<WEBJUMP> command

The WEBJUMP command has the following syntax:

<WEBJUMP name="newcommand1" href=”http://yourtoolbar/somepage.html” newbrowserwindow="false" />

The attributes supported are:
-	newbrowserwindow
-	options
-	post
-	encoding
-	parse_events
-	target
newbrowserwindow= attribute can be set to “true”, “false” or “modaldialog”. 
true means that the html page will be opened in a new window
false means that it will be opened in the same browser window 
modaldialog means that it will be opened in a new window that has to be closed before the user can continue to browse (useful for dialog-box pages). 
options= attribute defines how the window is formatted. Here is an example demonstrating use of the options attribute:

<LOCALHTML href="about.html" name="about" newbrowserwindow="modaldialog"
options="status:no;help:no;dialogHeight:220px;dialogWidth:450px;scroll:no;" />

post= attribute is used to submit a data via HTTP POST request (submitting a form) instead of HTTP GET.

<WEBJUMP name="newcommand1" post=”var1=%combo1&var2=%domain” href=”http://yourtoolbar/formpost.php”/>


encoding= attribute specifies a codepage (or encoding) that will be used inside the URL to convert %<variable name> substitutions. For example, if the server accepts search queries in the UTF-8 (unicode) format. The encoding has to be set to unicode (65001). Then the text inputs into search fileds will get converted to UTF-8 (unicode), so the server could understand them. You can find a table with standard codepage numbers in the appendix Standard Code Pages.

<WEBJUMP newbrowserwindow="false" href="http://www.yoursite.com/search?sq=%search" name="keMdXGRo" encoding="65001" />

The default encoding is 1252 (Western European). In case you need to omit encoding and pass the texts typed as is you can use special value for the encoding tag: encoding=”-1”
parse_events= allows to change toolbar options from page where the command leads to.
target = specify here name of the frame where the page will be loaded.