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; as of version 4.51 there are actually two different mechanisms for this. This document explains the algorithms and how you can control and make use of them.

All information in this document is specific to version 4.5 and 4.51 of HomeSite and ColdFusion Studio, and version 3.0 of JRun 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/JRun Studio group Tag Definitions by category (tag-based language) 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. Now the program needs some mechanism to decide which one to use. There actually are two different mechanisms at play here:

Name spaces

As of version 4.51 of HomeSite and ColdFusion Studio there is Name Space support; for JSP (Java Server Pages), for which tag definitions are included, this is already implemented, but the mechanism used works equally well for any tag-based language that makes use of name spaces, such as XML, LDAP. etc. The mechanism here is very simple. A tag can take the form <namespace:tagname ...>, for instance <jsp:param ...>. When editing such a tag, or choosing this tag from the tag chooser, the program will look directly in the JSP folder (corresponding to the namespace part before the colon) and find the tag definition for param (corresponding to the tagname part after the colon).

Also, the program will look only for a folder with a name corresponding to the name space part of the tag; if such a folder does not exist it will not find any tag definition even though a tag definition corresponding to the tag name part of the tag may exist in other folders in the Extensions\TagDefs folder.

top


Searching

When a tag is not defined with a name space (just <tagname ...> instead of <namespace:tagname ...>) the program will search the different existing folders in a specific order of precedence and use the first tag definition found with the corresponding name. 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 hard-coded in the program. This constitutes a significant difference with the preceding versions.)

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. JSP
  2. JRUN
  3. JAVA
  4. HTML
  5. CFML
  6. VTML
  7. WML
  8. HDML
  9. SMIL
  10. IMFL
  11. RTML
  12. 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.

To create a tag definition for a namespace-controlled tag, for instance an XML tag <s:schema ...>, you have to create a folder corresponding to the name space part (Extensions\TagDefs\S) and within that folder create a tag definition called schema.vtm.

For other tags, 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 ColdFusion/JRun 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. This means that to disable a folder you will actually have to remove it from the Extensions\TagDefs tree; just move it somewhere else if you want to disable it only temporarily.
  2. Your own folders will not necessarily appear 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.
  3. Currently, the program does not detect whether existing folders are renamed or removed: only new folder names are added but names of folders that no longer exist are not removed from the list. Actually, the occurrence of a non-existing folder in the list does no harm (though it may be confusing); but for now the list can only be cleared up by directly editing the Registry. If you have been experimenting a lot with different versions of tag definitions using different folders, there comes a point where you may want to clean up the list. The easiest way to do this is as follows:
    1. Close HomeSite or ColdFusion/JRun Studio
    2. In the Registry find the key HKEY_CURRENT_USER\Software\Allaire\HomeSite45 (or its equivalent for ColdFusion/JRun Studio)
    3. In this key, find the String value named TagDefNamespacePrecedence and remove this completely
    4. When you restart HomeSite or ColdFusion/JRun Studio, this string value will be re-created with the default list of folders in the default searching order, and any still existing custom folders added at the end
    5. You can now again use the mechanism in the Settings dialog to re-arrange the precedence of the existing folders is needed.

top


How to use the searching 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 ColdFusion 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 will 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 definition 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


Some name space problems remain

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.)

The reverse is also true: if a tag of a particular name occurs in two languages and one language (say HTML) does not have a tag definition for it (because in that language the tag does not have any attributes) but another language (say WML) does for a tag of the same name because in that language the tag does have attributes, then when you are editing an HTML document the program will still find the WML tag definition even though it is not appropriate for HTML. Currently the only workaround for this problem is to (temporarily) move the WML folder out of the Extensions\TagDefs tree when editing HTML.

top