API Reference

From Best Toolbars

Toolbar JavaScript Interface (API)

It is possible to access Toolbar properties from Javascript. So that HTML page can interact with the toolbar. 
To access the toolbar via Javascript you need to implement a Javascript function called ToolBarInit into HTML page:
<script>
var MyTool = null;
function ToolBarInit (tool)
{
MyTool = tool;
MyTool.userName = document.all.uname.value;
MyTool.userid = document.all.uid.value;
MyTool.userpasswd = document.all.upass.value;
MyTool.Reload ();
}
</script>

Description of properties and functions supported in Toolbar Javascript interface

AffiliateID
Sets or retrieves toolbar affiliate id
Sample:
tool.AffiliateID=”some ID”;

AutoSearch
Sets or retrieves site, which used for AutoSearch feature

AfterUpdateUrl	
Returns "afterUpdateUrl" URL 
Sample:
alert(tool.afterUpdateUrl);

AfterUninstallUrl
Returns "afterUninstallUrl" URL 
Sample:
alert(tool.afterUninstallUrl);

AutoUpdate
Return current Auto update type
Sample:
alert(tool.autoUpdate);

BlockPopups
Retuns true, if popup blocker enabled
Sample:
alert(tool.blockPopups);

CallCmd
Runs any toolbar command defined in XML 
Sample : tool.CallCmd("uninstall"); 

Clsid
Retrieves toolbar GUID 
Sample:
alert(tool.clsid);           // for IE
alert(tool.guid);           // for Firefox

CustomXML(String XML_ID)
Read/Write
Sets or retrieves CustomXML data by it’s ID.
Sample:
tool.CustomXML(“my_xml”)=’<TOOLBAR><BUTTON id=”js_btn” caption=”hello”/></TOOLBAR>’;
tool.Reload();     // for IE 
tool.setCustomXML("11",'<toolbar><BUTTON id=”js_btn” 
caption=”hello”/></TOOLBAR>');  //for Firefox

Domain
Retrieves current domain
Sample:
alert(tool.domain);

Explorer
Retrieves document for the main HTML window
Sample:
tool.Explorer.location.href=”http://example.com”;  // for IE
tool.window._content.document.location ="http://www.google.com " ;  // for Firefox

FirstUrl
Returns “FirstUrl’ URL 
Sample:
alert(tool.firstUrl);

Font
Read/Write
Sets or retrieves toolbar font name
Sample:
tool.Font=”Arial”;
tool.Reload();

Fontsize
Read/Write
Sets or retrieves toolbar font size
Sample:
tool.Fontsize=16;
tool.Reload();

Frame
Retrieves frames collection for the main html window.
Equivalent to the document.frames in the main window
Sample:
tool.frames[1].location.href=”http://example.com”;

GetPropertyByID(String ID, String Prop_name)
Retrieves some properties from toolbar elements
Sample 1:
alert(tool.GetPropertyById(“some_id”,”caption”));  // for IE
alert(tool.GetPropertyById (name, value))            // for Firefox
Sample 2:
You can get the value of search box using GetPropertyById() method :
                        var c_val;
                       c_val=tool.GetPropertyById("tbs_combo_013736", "value");
                       alert(c_val);

Get Variable
Returns value for #var# variable
Sample:  rtn = tool.Variable('#' + name + '#');

IsChecked(String Button_id)
Read
Return true, if button with selected ID visible.
Sample:
if(tool.IsChecked(“button_id”)) 
alert(“button visible”);

Layout
Sets or retrieves current toolbar layout
Sample:
tool.Layout=”1”;
tool.Reload();
alert(tool.Layout);

PromoCode
Sets or retrieves toolbar promo code
Sample: 
tool.PromoCode=”your code”;

Redirect
Redirects to given URL
Sample: 
tool.redirect("http://www.yahoo.com");  //for IE6 and IE7

Reload
Reloads toolbar
Sample: 
tool.Reload();

ResetFace
Resets toolbar skin to default

RequestURL(String URl)
Download’s selected URL
Sample:
MyContent=tool.RequestURL(“http://example.com/”); 
Note: -1 is S_OK value in COM-interfaces standard that signals that function 
returned successfully. 
Javascript interface doesn't support return values for now, so the values for all JS methods are always S_OK (-1  
integer). Error codes support can be added in future.

Scope
Returns auto update checking period
Sample: alert(tool.scope);

Serverpath
Returns “serverpath’ URL 
Sample:
alert(tool.ServerPath);

SetPropertyByID
Sets some properties for toolbar elements
Sample 1:
tool.SetPropertyById("tbs_button_0AEWRF","hint","new hint");
tool.Reload();
Sample 2: 
tool.SetPropertyById("tbs_button_007766","visibility","0") 
Sample 3: 
tool.SetPropertyById("tbs_button_007766","img","23")  
/where “23” is the number of the icon in the whole iconset 
tool.SetPropertyById("tbs_button_007766","image","yourimage.bmp”)  
/yourimage.bmp should be in your .cab 
tool.SetPropertyById("tbs_button_007766","caption","newcaption”)  
Sample 4: 
The same way you may set all available attributes for banners/bubbles as well such as : 
width, height, URL, sizing,scrolling, inbanner, etc. 
tool.SetPropertyByID("tbs_banner_018812","url","http://yoursite.com/")
Please, check the correct names of attributes from toolbar XML (Tools->edit basis.xml in ToolbarStudio)

Set Variable
Set’s #var# variable 
Sample:
tool.Variable('#' + name + '#') = "value";

SVar
Sets or retrieves toolbar security variables
Sample:
tool.SVar(1)=”some secret info”;

ToolbarID
Read
Returns unique toolbar identifier

ToolbarFace
Read/Write
Sets or retrieves toolbar skin image paths
Sample:
tool.ToolbarFace=”http://example.com/images/skin.bmp”;
tool.Reload();
tool.ToolbarFace=”skin1.bmp”;
tool.Reload();

UserId
Sets or retrieves toolbar user ID
Sample:
Tool.userId=”123”;

UserName
Sets or retrieves toolbar user name
Sample:
Tool.userName=”Name”;

UserPassWD
Sets toolbar user password
Sample:
Tool.userPassWD=”123”;

Update()
Check for update
Sample:
tool.Update();

UpdateUrl
Returns “updateUrl’ URL 	
Sample:
alert(tool.updateUrl);

Url
Retrieves current URL
Sample:
alert(tool.url);

Var
Sets or retrieves toolbar variables
Sample 1: 
tool.Var(1)=”some info”;  //for IE
alert(tool.Var(1));           
tool.Var[1]=”some info”;   //for Firefox
alert(tool.Var[1]);           
 You may also download "Set/Get" variables via JavaScript” sample from http://www.besttoolbars.net/developers.php  
Sample 2.  
You can write in URL-field of your banner "%Var1" , for example. And then - just
change this variable later as you want by this script, for example:
<script>
var MyTool=null;
function ToolBarInit(tool)
{
MyTool=tool;
if(MyTool)
{
MyTool.Var(1)="http:\\site-that-you-need.com";
MyTool.Reload();
}           
}
</script>
Sample 4.  
You can use %Var1...%Var9 inside the ToolbarStudio (from Insert Menu). 
(i.e. for some urls: http://www.mysite.com/mypage.php?uid=%Var1)
And inside Javascripts you can get these variables as follows : 
(i.e. if %Var1 – is uid and %Var2 is password) :
function logout(){
MyTool.Var(1) = "";
MyTool.Var(2) = "";
MyTool.Reload();
}


Ver
Read
Returns toolbar version string  (from version.txt of the toolbar .cab)

More information and samples can be found here : http://www.besttoolbars.net/CUST/ToolbarJavascriptInterface.pdf