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.
The following subjects are covered in this document:
Related information about VTML and WIZML:
|
HomeSite and ColdFusion 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 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.
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:
|
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 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: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.
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.
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.
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.