Toolbar Tips

On this page:

Introduction
Toolbar images
Distributing toolbars

• Different versions
• Images
• External programs
• Tag Editors
• Archives

Here are some tips for creating custom toolbars that you will not find in the program documentation. I found these techniques by simple experimentation. Since they're useful, I'm sharing them with you.

Images

When you create a toolbar button for an external application in HomeSite or ColdFusion Studio, the easiest way to do that from the Customize dialog is to browse to the executable file to include the full path for it; then in the next entry field you can add any command-line parameters. The special symbol %CURRENT% is handy for running applications that support a file name as (a part of) a command-line parameter. The program will then display the program icon it finds in the executable as a toolbar button. Great idea.

But I found it's not always as simple as that. The first topic on this page will teach you how to control which link images appear on the toolbar when the ones that appear automatically just won't do. Using some undocumented features...

Distribution

The second topic on this page contains a whole number of tips for when you don't just create toolbars for yourself, but want to distribute them to fellow developers as well. With more undocumented features!

Code

Since most of these techniques somehow involve editing the text file that defines a toolbar, there are some code examples; if your browser supports JavaScript 1.2 (both version 4 browsers do), you can see them in side-by-side popup windows: two windows for each example since the code for HomeSite and ColdFusion Studio 3.x is different from that for the 4.0 versions of these programs. This works best if your screen resolution is set to at least 600x800. The windows can be left open; other examples will then show up in the same windows. They can be resized and repositioned.

If you are using Internet Explorer, size and position of the windows will be retained as long as you leave them open. The link on the right is for pre-sizing the windows, if you like; if you don't see a link here, your browser doesn't support JavaScript 1.2 or it's disabled.

In case you can't use these popups, all code examples have also been gathered on this page.

Images and executables

When creating the RCS toolbars I ran into a problem: almost all commands are for the same executable: they differed only in the command-line argument. My first attempt at creating this toolbar ended looking something like this:

Of course, that was not exactly what I intended: you'd have to rely on the tooltips to find out which button is for what. I tried adding image files in the toolbar definition files, but HomeSite showed the program icons regardless. The separators I added help a little to remember what function is where, but the whole idea of having icons is easy recognition.

So how did I create a toolbar with different images for each? With hindsight, the principle is quite simple:

• HomeSite needs the full path to an executable to find it to display its program icon.
• Windows (like DOS) does not really need the extension: when the extension is not defined (or the path is not defined) it has a searching mechanism to locate the executable command or program.
• By simply leaving off the .exe extension, HomeSite cannot find the program to display its icon, but Windows can still find it to execute.
• When HomeSite cannot find the program icon, it will display the Windows default icon - unless an image file is specified in the toolbar definition file! Then that image is used on the toolbar. This works with both HomeSite 3.01 and HomeSite 4.0 - and of course in the corresponding versions of ColdFusion Studio.

So: I simply left off the .exe extension of csrcs.exe and supplied my own function icons. I did the same for DocumentManager.exe: it did have a different program icon but that didn't scale very well to the 18x18 format needed for toolbars; so I substituted my own. All image colors are carefully matched, too so they really look like they belong together. The result (latest version) looks like this:

If an image is not located in the Toolbar directory, supply the full path, otherwise all you need is the image name.

If you want to apply this technique for your own custom toolbars, start by creating the toolbar from the normal interface. Since you cannot specify an image there, the next step is to edit the .tbr file you created with a text editor (not HomeSite or ColdFusion Studio!) and make the necessary changes. Note that for 3.x the image only needs to be filled in while for 4.0 the whole line must be added.

Images and non-program files

No wait... there's more. If you look at the screen shots of the toolbar above, you'll also see a little 'Help' icon. Which is cause for another toolbar image tip.

The 'Help' icon appeared because I simply put the .hlp file on the toolbar. Now HomeSite or ColdFusion Studio does what Windows does (or, more likely, they let Windows do it for them): it goes and finds the application that is associated with the file type, and displays the program icon for that associated program.

While that's nice for a single 'Help' icon, what if you want to put a a whole bunch of (say) .pdf files on a toolbar? You'd be back with the same problem we had above: all the same icons.

The solution is similar to the first tip:

• Use Windows Explorer or the Registry editor to find the program that is associated with the files you want to put on the toolbar
• Put that program's full path as the program on the toolbar, and define the file to be displayed as its command-line parameter
• Now again leave off the .exe from the executable program, and supply your own toolbar image.

Image format

Toolbar icons must be bitmaps (.bmp) of 18x18 pixels. Smaller is possible but you'd leave the positioning to the program.

If you create your own, remember that the lower left pixel color is always taken as the transparent color.

There was a question on the HomeSite Conference recently that went something like this: "I've downloaded a toolbar; now how do I install it?". There was really only one answer I could give: "It depends.... Ask whoever distributed the toolbar..."

There are a few things you should keep in mind if you want to prepare toolbars for distribution to fellow users. I'm still learning how to do it better; meanwhile I'll pass on the tricks I've learned so far:

Different versions

• First of all: The format of the text files that that define toolbars has changed from version 3.x of HomeSite/ColdFusion Studio to version 4.0 of those programs. They are not compatible. While there may be good reasons for this change, it does mean two things: You should be aware of the difference and you should make sure your (potential) users are aware of the difference:

  • The very least you can do is make very clear which version of the programs the toolbar has been developed for; make the version clear somehow before people download your toolbar rather than only in a file included with a downloadable archive;
  • If at all possible, develop two versions of your toolbar: one for each program version (and study the differences in their definition files before distributing anything!).
  • If the toolbar was prepared before the versions 4.0 of the programs were released: update your information to make it clear for which version the toolbar was developed; or create an additional version for version 4.0!
  
  

• Second: always have installation instructions (on-line or included in an archive: as long as they're there!); some people may be interested in using your toolbar but have no clue about what to put where and how to proceed from there. And the process is different for version 4.0 from that needed for version 3.x.

Images

The best way to include toolbar images is to have them installed in the Toolbars directory and refer to them from the toolbar definition with just the file name. Remember: both versions of the programs have a Toolbars directory; it's just located in different places in the directory tree for each. Include the toolbar images in the archive you're making available.

External programs

Do not ever make any assumptions about the user's installation path of a program: it may be on a different drive letter and under a different directory than yours. There's a number of things you can do about this - regardless of program version:

• When creating a toolbar button the path to an external program will always show up as a fully-qualified path, complete with drive letter. Include something in your installation instructions about what needs to be changed where to correspond to user's own installation path to that same program.
• If your users will need to edit the toolbar definition file(s), make sure it's as readable as possible for humans: the programs don't care about white space but for humans it can help divide the information into chunks: use empty lines to separate the definitions of each button.

Tag Editors

When creating a toolbar button for a Tag Editor (.vtm) both versions of the programs will also write the complete file path to the .vtm file. Previously, I suggested you eliminate the path to leave only a path relative to the program's installation directory. However, due to a bug in older versions of the programs, this will only work until the user activates the browse tab: after that, the program "forgets" where it is installed and the relative path will no longer work - until you close and reopen the program.

This problem is fixed as of beta 4 of the 4.01 maintenance release for HomeSite and ColdFusion Studio. Alas, this also means that you'll have to tell your users to edit the paths for all older versions. I'd suggest the following strategy for distribution:

HomeSite 3.01 or ColdFusion Studio 3.11

[full path]\Whatever.vtm
Tell your users to edit the path with their own installation path.

HomeSite 4.0x or ColdFusion Studio 4.0x

Edit the toolbar definition file to show only the path relative to the program's installation directory:
Extensions\TagDefs\Whatever.vtm
Tell your users to add the installation path if they have not yet upgraded to the 4.01 maintenance release.

Distribution archives

Make sure the archive you distribute does not itself contain any path names to the toolbar files: only that way it can be installed in wherever the Toolbars directory is for the program version(s) you developed it for without making assumptions about the user's installation paths or directory trees.

The basic principle: You already know what to do with that toolbar; make sure your users do as well!

The toolbar included with my HTML Tag Definitions is another example: it contains file paths to the Tag Definition files that are relative to the program installation path: with the latest program versions (maintenance release 4.01) they will always work regardless of where or on what drive the user installed the program.