Searching for tag definitions

With the introduction of HomeSite 4.0 and ColdFusion Studio 4.0, VTML saw some useful extensions (see other documentation). Tag definition files can now be grouped by purpose or language into separate subfolders below the Extensions\TagDefs folder.

But then how does the environment find a specific tag definition? Tag Chooser does not allow picking a specific folder for a Tag Editor, and when editing a tag, the environment just finds a tag definition without giving you a choice while you're working. In both cases, the program finds a tag definition by name, searching the folders in a specific order. Starting with version 4.5 of HomeSite and ColdFusion Studio you have specific control over the order in which the folders are searched; this order is no longer hardcoded in the program. This constitutes a significant difference with the preceding versions. This document explains the searching algorithm and how you can control and make use of it.

All information in this document is specific to version 4.5 of HomeSite and ColdFusion Studio.

The following subjects are covered in this document:


Related information about VTML and WIZML:

Tutorial
The Visual Tool Markup Language (VTML)
Reference
VTML reference - overview

top

How a tag definition is found

HomeSite and ColdFusion Studio group Tag Definitions by category into different folders below the Extensions\TagDefs folder. This makes it possible for different Tag Definitions of the same name (but different content) to exist in different folders. The program needs some mechanism to decide which one to use: it searches the different folders in a specific order of precedence and uses the first one found.

The program comes with a default set of folders installed which have a default precedence list for searching as listed below:

The default precedence list for the default folders:

  1. CFML
  2. HTML
  3. VTML
  4. WML
  5. HDML
  6. SMIL
  7. CUSTOM

top


Customization

You can add your own folders to the Extensions\TagDefs folder. Each time one or more new folders are added here, the program will detect these on startup and add them (alphabetically) at the bottom of the precedence list.

But the precedence list can now be customized via the Setup dialog (F8 or Options->Settings...). There is a Tag Definitions Library pane. The dialog shows the known folders in the current precedence order and allows this order to be changed with simple Up and Down buttons. This information is stored in the Registry.

Caution: Each time you add new folders before reopening HomeSite or Studio, the new folders will be added at the bottom of the list. And "new" is any folder which doesn't occur yet in the list as stored in the registry. This means:
  1. You cannot disable a folder simply by removing it from the list in the Registry: the next time the program is started, the "new" folder will be found and added to the list again.
  2. Your own folders are not necessarily in alphabetical order, unless you specifically move them in that order using the Setup dialog. You should always check the Setup after adding new folders and make sure the precedence list is as you intend for your folders.

top


How to use this mechanism

Changing the precedence list

It is of course possible to have (or create) folders, each with tag definitions, and several of these tag definitions can have the same name. You'll need to decide which of the tag definitions with the same name should be used. Since the precedence list can now be customized (as of version 4.5 of HomeSite and Studio), it is no longer necessary to rename folders in order to control which one of like-named tag definitions will be found first. Simply go to the Setup dialog and move the folder with the preferred tag definitions before the other one(s).

By using the precedence list customization, you can force the environment to pick either one or another set of tag definitions.

top


Disabling tag definitions

The searching algorithm has another implication, however: What you cannot do with this mechanism, is disable a particular definition by renaming the folder in which it is placed or moving it in the precedence list: the environment will simply search all subfolders of the Extensions\TagDefs folder in the specified (detected) order.

By only temporarily  moving a tag definition or the folder it's in outside the scope of the searching mechanism, you can disable them and still be able to restore them at a later time.

top


Switching between sets of tag definitions

The new searching mechanism as of version 4.5 has an extra advantage: when you move a folder outside the scope of the searching mechanism, the environment notices this immediately: the tag definitions in that folder are immediately disabled without having to clear the cache with the key combination Shift+Ctrl+Alt+C. If a tag definition of the same name is available in another folder that one wil now become available. The same is true when you move a single tag definition outside of the search scope. And they become immediately available again when moved back. Clearing the cache is necessary only if you change a tag defintion while it stays in the same folder.

What this amounts to is a simple way of switching between sets of tag definitions not only by moving folders up and down in the precedence list, but also by moving tags or folders outside of the search scope. This can be extremely useful, especially when testing other's (replacement) tag definitions or developing new ones of your own.

top


Name space problem remains

Even with customization of the precedence order, one problem remains: different languages can have a tag of the same name but with different sets of required and possible attributes. No matter how you name or sort your subfolders, if you have two different tag definitions for different purposes or languages, the environment will always still find only one of them. But when you work with both languages, you will need both. There is no simple solution for such "name space ambiguity" and when developing your own tag definitions you should be aware not only of the precedence list but also which tag definitions are already present.

If you need to support two languages, you may follow the example of the PARAM tag definition: Create a single definition file which supports both languages, in this case HTML and VTML. (A pre-existing tag definition, located in a different folder, may still have to be disabled, though!) When support for different languages is combined in a single tab definition in this way, MarkUpTags.vtm (Tag Chooser) allows pre-selection of the appropriate tabs in the PARAM Tag Editor. An entry can be created for each language in an appropriate category in Tag Chooser, each with its own tab preselected. (Read more about the technique for preselecting a tab on the Tips and Techniques: Tag Chooser page on-line.)

top