In version 4 and above, tag definition files can be grouped by purpose or by language into separate subfolders below the Extensions\TagDefs folder.
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. How then does it find a specific tag definition? In both cases, it 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 applies to version 4.5 and higher and to JRun Studio 3 and higher.
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. Reconciling possible name conflicts relies on two different mechanisms:
Namespace
The namespace support provided for Java Server Pages (JSP) works equally well for any tag-based language that makes use of namespaces, such as XML and LDAP.
A tag can take the form <namespace:tagname ...>
.
For example, if you select the <jsp:param ...>
tag in the Tag Chooser or if you are editing it, the program looks for it in the JSP
folder, which corresponds to the namespace, that is, the part before the colon. It then looks for the param
tag definition in that folder, based on the the tagname, the part after the colon.
If, however, a folder with a name corresponding to the namespace part of the tag is not found, then no tag definition will be found, even if a tag definition corresponding to the tagname (in our example, param
) exists in another Extensions\TagDefs folder.
When a tag is not identified with a namespace, for example, <tagname ...>
instead of <namespace:tagname ...>
, then the program searches the entire Extensions\TagDefs directory for it. The first tag definition with the corresponding name that is found is the one that is used. So, the order of precedence for the search is critical in locating the correct tag definition where there are multiple tags with the same name.
The program comes with a default precedence list for searching the installed folders. The list is in Options > Settings > Tag Definitions Library.
You can add your own folders to the Extensions\TagDefs folder. If the program detects a new folder on startup, the folder information is stored in the Registry and the new folder is added at the bottom of the precedence list.
Caution: You should be aware of the following behaviors: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 namespace part (Extensions\TagDefs\S
) and within that folder create a tag definition called schema.vtm
.
You cannot disable a particular definition by renaming the folder in which it is placed or moving it in the precedence list because the entire Extensions\TagDefs folder is searched in the specified order.
If you move a folder outside the scope of the searching mechanism, the tag definitions in that folder are immediately disabled. If a tag definition of the same name is available in another folder, it is selected. The same is true if you move a tag definition file outside the search scope. Folders and files are immediately available when that are moved back. Clearing the cache (Ctrl+Alt+Shift+C) is only necessary if you change a tag definition and keep it in in the same folder.
This methods give a simple way to switch 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.
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 multiple tag definitions with the same name, only one of them will be found. There is no simple solution for such this namespace ambiguity, so 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; that is, create a single definition file
that supports both languages, in this case, HTML and VTML. A pre-existing tag definition with the same name, located in a different folder, may still have to be
disabled, however, even when support for different languages is combined in a single tab definition in this way. You can edit the Extensions/MarkUpTags.vtm file to pre-select 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 pre-selected.
(To read more about the technique for preselecting a tab, see the Tips and Techniques:
Tag Chooser page.
If a tag with the same name occurs in two languages and one of the languages does not have a tag definition for it but another language does, the program will find the tag definition even if you are selecting or editing the tag that does not have a tag definition. The only workaround for this problem is to move the folder containing the tag definiton out of the Extensions\TagDefs tree.