Home | HTML section | VTML section
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.
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...
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!
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:
So how did I create a toolbar with different images for each? With hindsight, the principle is quite simple:
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 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:
Toolbar icons must be bitmaps (.bmp) of 18x18 pixels. Smaller is possible but you'd leave the positioning to the program.
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:
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.
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 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:
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!For some inspiration, have a look at the toolbars I'm distributing for integration with the Windows version control system CS-RCS, and of course the installation instructions for them: they contain paths to external programs and the instructions make clear they should be edited.
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.