In a regular HTML page when you refer the external object or window.external you access a set of tools offered by Microsoft Internet Explore. In the DHTML page that implements the toolbar UI the external object directly represents your toolbar script.

What this means? From any script in the toolbar UI HTML page you can call external.FunctionName and the FunctionName can be any function or Sub you have implemented in the toolbar script. Furthermore you can access also the global variables of the toolbar script the same way, but they will look like read/write properties. Lets take an example:

If you have in the toolbar script this funny function:

Function ReplaceLinks(sLink)
  Dim lnks, I
  Set lnks = Browser.document.links
  For Each I In lnks
    I.href = str
  Next
End Function

which  enumerates all the links in the page currently viewed by the user in the browser work area and makes all the links in point the same URL (which is passed as parameter).

You can call it from the toolbar UI page like this:

<INPUT TYPE="BUTTON" VALUE="Replace links" onClick="external.ReplaceLinks('http://www.yahoo.com')">

Some developers will ask why not do everything in the toolbar UI page itself, but call a function implemented in the toolbar script? The answer of this question is complex - there are several reasons:

• The toolbar UI page is able in theory to access the browser work area, but this will be forbidden sometimes depending on the user's security settings.
• The access is only through the toolbar script e.g. like this: external.Browser.document.<membed_of_document_object>
  This will work when the toolbar script is a script, but if you decide to use a COM object instead (written in C or VB for instance) it wont work.
• The toolbar UI obeys some security restrictions that concern the object creation and usage. Although they are not so high as in the regular pages they may prevent you from using all the objects you will need.
• And the most important reason is the internal state. Your toolbar application will use certain objects to access a database, to keep in-memory data, may be some files and so on. Their life cycle depends only on your decision and very often will be kept throughout the entire life cycle of the browser window. In the toolbar script they are kept in variables you access directly. If you want to do more complicated work in the toolbar UI you will need to access them which will make the expressions longer and if you are using more than one different pages for toolbar UI (reloading them from time to time) you will need to duplicate your efforts. No need to mention that certain operations will be invoked from both events and user actions in the toolbar work area - in such case you will need to duplicate your code in the both toolbar UI and toolbar script, which can be easily avoided by implementing the operations in the toolbar script and simply invoking them from the UI.

Thus the best way is to implement everything that is more than a simple visual effect, independent of the main work in the toolbar script and invoke it through the external object.

The reverse - accessing toolbar UI from the toolbar script.

The toolbar UI is just a DHTML page shown in the toolbar. Thus the statements that deal with it look like any other script that works with  DHTML, but preceded with "Toolbar.":

Toolbar.document.all("myimage").style.display = "none"
hides an image in the toolbar UI

Toolbar.document.all("myeditbox").value = "Some text"
sets the text in a text field in the toolbar UI

Thus the toolbar script has the full range of capabilities to access and fiddle with the toolbar UI as with a regular DHTML page. This makes it convenient to implement visual tasks in the toolbar script. This is especially useful when these tasks require some data or routines from the toolbar script itself. For example you may need to access a database in order to obtain the information you are going to show somewhere in the toolbar UI.