Extending ColdFusion Studio

Tag Editors: The Hidden Power of ColdFusion Studio

ColdFusion Studio and its sibling HomeSite give developers a toolbox that feels almost second nature. Every line of code is a quick visual cue, every error message a clear pointer, and every custom tag can be edited through a familiar dialog. That dialog is what the industry calls a “tag editor.” A tag editor is the visual window that appears when you right‑click a tag and choose Edit Tag (or hit Ctrl‑F4). The editor does more than just display the tag’s attributes; it reads the tag’s definition from a file, builds the dialog on the fly, and, when you click Apply, writes a clean, correctly formatted tag back into your source.

The beauty of this system is that the editors are not baked into the IDE. Every dialog is constructed from a lightweight XML file that lives in the TagDefs folder. That means you can add new dialogs, tweak existing ones, or completely overhaul the way a tag appears - all without touching the IDE’s binaries. If you’ve ever wondered why the <cfquery> dialog feels just right, or how the <cffile> dialog knows to display a file picker, the answer lies in these definition files.

Beyond the convenience, tag editors are a powerful extension point. By supplying a custom definition you give developers a guided experience for your custom tags, making them as user‑friendly as the native ColdFusion tags. You can enforce attribute names, provide drop‑down lists, attach help text, or even conditionally show fields based on other attributes. All of this is possible in a single XML file that the IDE reads at runtime. In short, tag editors are a lightweight, declarative way to make your tags feel native to the ColdFusion developer ecosystem.

When you first open a tag editor you might notice a clean layout: fields neatly aligned, labels to the left, and a “Apply” button at the bottom. Behind the scenes the IDE parses the definition file, creates the controls, and binds each control to an attribute. If the tag already contains attributes, the editor pre‑populates the fields, allowing the developer to adjust values without having to rewrite the tag from scratch. This tight integration between source and dialog is what makes ColdFusion Studio a favorite for rapid prototyping and maintenance alike.

Because the definition files are ordinary text, you can edit them with any editor you like, then drop them into the TagDefs folder. The next section explains how to locate that folder, install a new definition, and verify that your new tag editor appears in the IDE. If you’ve ever downloaded a custom tag from a community site, you’ve probably seen the accompanying .VTM file. Understanding how to install those files is the first step to extending your IDE’s capabilities.

Installing Tag Editors: From File to Dialog

Custom tag editors arrive in the form of .VTM files - a small, XML‑based document that describes the editor’s layout, controls, and attribute mapping. The first thing you need is the folder that houses all tag definitions. On Windows, the default path for ColdFusion Studio 4.5 looks like this:

Inside TagDefs you’ll often find subfolders for HTML, CFML, and WML tags. For your custom tags, create a folder called Custom if one does not already exist. Placing your .VTM files in this folder keeps them organized and separate from the built‑in definitions.

Once you have your .VTM file ready, copying it to the appropriate folder is all that’s needed. When the IDE starts, or when you press Ctrl‑Alt‑Shift‑C to clear its cache (available in Studio 4.0.1 and newer), it scans the entire TagDefs tree for .VTM files. The file name determines the tag it will apply to: the tag <cfquery> uses CFQUERY.VTM, and the tag <table> uses TABLE.VTM. Because the name of the tag editor file matches the tag name (ignoring case), Studio automatically pairs them. If a tag in your source does not have a matching file, the Edit Tag menu option is disabled.

It’s helpful to keep a few notes when working with tag editors:

• All .VTM files are case‑insensitive, but the convention is to use uppercase file names that match the tag name exactly.
• If you update an existing .VTM file, you must clear the IDE cache or restart Studio for the changes to take effect.
• When adding a new tag, also add the tag definition itself to the ColdFusion application (for example, a cfoutputredirect.cfc component) so that developers can actually use the tag.

  After installation, right‑click a tag that matches your new definition. The Edit Tag option should be active, and the dialog should appear as defined. At this point you have full control over how the tag appears in the editor. You can change the layout, add help text, or introduce advanced controls. The next section dives into the language used to create these definition files - the Visual Tool Markup Language (VTML). Understanding VTML is essential if you want to tweak or extend the dialog beyond the basics.

  VTML Basics: Designing Dialogs with XML

  VTML, or Visual Tool Markup Language, is a lightweight, XML‑based syntax that ColdFusion Studio uses to generate tag editor dialogs. Think of VTML as a recipe: you list the ingredients (controls, containers, and attributes) and the IDE cooks the dialog for you. Because it’s XML, you can edit a file with a simple text editor, and the IDE interprets it exactly as written.

  A VTML file starts with a <TAG> element that encloses the entire definition. Inside that, three sub‑elements are mandatory: <EDITORLAYOUT>, <ATTRIBUTES>, and <TAGLAYOUT>. Each serves a distinct purpose.

  • <EDITORLAYOUT> defines the visual arrangement of controls - labels, text boxes, file pickers, and more. It sets the dialog’s size and contains containers that group controls.
  • <ATTRIBUTES> links tag attributes to the controls you defined. When a developer opens the editor, the IDE uses this mapping to preload attribute values.
  • <TAGLAYOUT> describes how the editor’s data is stitched together into a valid ColdFusion tag. This section is where you specify whether the tag should be output in upper or lower case, whether attributes appear on a single line or multiple lines, and how to include optional attributes only when needed.

    Because VTML is declarative, you don’t write procedural code. Instead, you describe the UI structure and let the IDE handle rendering. The language offers a variety of control types: Label, TextBox, FileBrowser, ColorSelector, SQLBuilder, and more. Each control has a set of attributes - like CAPTION for text labels, WIDTH for sizing, and positioning attributes such as LEFT, RIGHT, TOP, BOTTOM. Positioning is relative, not absolute; you specify a control’s anchor and a corner to place it in relation to another control. This approach keeps dialogs flexible across different screen resolutions.

    Containers organize controls into logical groups. The most common container types are TabDialog (a dialog with tabs), TabPage (the content of a single tab), and Panel (a simple grouping box). Containers can contain other containers, allowing you to nest tabs within panels or panels within tabs.

    When you first create a .VTM file, you typically start with an empty <TAG> element and then add the three required sections. The IDE’s own tag editor can help you write these sections; you can right‑click a control or container and choose Edit Tag to open its VTML editor. However, a text‑based approach gives you full control over whitespace and ensures that you’re not missing any required elements.

    Once you have a working VTML file, test it by installing it in the TagDefs folder and opening a tag that matches. If you see the dialog you designed, you’ve successfully written VTML. From here, you can experiment with adding optional attributes, dynamic controls, or even custom validation logic. The next section walks through a concrete example: building a tag editor for a custom <CF_OutputRedirect> tag that can send output to email, a file, or a variable.

    Building a Tag Editor for CF_OutputRedirect: A Step‑by‑Step VTML Example

    Imagine you’ve written a ColdFusion component that captures all output inside a tag and redirects it to one of three destinations: an email, a file, or a ColdFusion variable. Developers will want a convenient editor that lets them pick the destination and specify the relevant details. Below is a full VTML definition that accomplishes this. The definition is broken into the three mandatory sections, and each section is annotated to explain what it does.

    First, create a file named CF_OUTPUTREDIRECT.VTM inside TagDefs\Custom. Make sure the file is empty before pasting the code; any default text will cause errors. The root element declares the tag name and opens the definition:

    Prompt

    <TAG NAME="CF_OutputRedirect"></p> <p> <EDITORLAYOUT HEIGHT="160" WIDTH="420"></p> <p> <CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH="MAXIMUM" HEIGHT="MAXIMUM"></p> <p> <CONTAINER TYPE="TabPage" NAME="EMAIL" CAPTION="Email"></p> <p> <CONTROL TYPE="Label" NAME="lblFrom" CAPTION="From:" LEFT="10" TOP="10"/></p> <p> <CONTROL TYPE="TextBox" NAME="txtFrom" LEFT="80" TOP="10" WIDTH="MAXIMUM" ANCHOR="lblFrom" CORNER="NE"/></p> <p> <CONTROL TYPE="Label" NAME="lblTo" CAPTION="To:" LEFT="10" TOP="40"/></p> <p> <CONTROL TYPE="TextBox" NAME="txtTo" LEFT="80" TOP="40" WIDTH="MAXIMUM" ANCHOR="lblTo" CORNER="NE"/></p> <p> <CONTROL TYPE="Label" NAME="lblSubject" CAPTION="Subject:" LEFT="10" TOP="70"/></p> <p> <CONTROL TYPE="TextBox" NAME="txtSubject" LEFT="80" TOP="70" WIDTH="MAXIMUM" ANCHOR="lblSubject" CORNER="NE"/></p> <p> </CONTAINER></p> <p> <CONTAINER TYPE="TabPage" NAME="FILE" CAPTION="File"></p> <p> <CONTROL TYPE="Label" NAME="lblFile" CAPTION="File:" LEFT="10" TOP="10"/></p> <p> <CONTROL TYPE="FileBrowser" NAME="txtFile" LEFT="80" TOP="10" WIDTH="MAXIMUM" ANCHOR="lblFile" CORNER="NE"/></p> <p> <CONTAINER TYPE="TabPage" NAME="VARIABLE" CAPTION="Variable"></p> <p> <CONTROL TYPE="Label" NAME="lblVariable" CAPTION="Variable:" LEFT="10" TOP="10"/></p> <p> <CONTROL TYPE="TextBox" NAME="txtVariable" LEFT="80" TOP="10" WIDTH="MAXIMUM" ANCHOR="lblVariable" CORNER="NE"/></p> <p> </CONTAINER></p> <p> </EDITORLAYOUT></p> <p> <ATTRIBUTES></p> <p> <ATTRIB NAME="OUTPUT" CONTROL="MainTabDialog"></p> <p> <ATTRIBOPTION VALUE="EMAIL"/></p> <p> <ATTRIBOPTION VALUE="FILE"/></p> <p> <ATTRIBOPTION VALUE="VARIABLE"/></p> <p> </ATTRIB></p> <p> <ATTRIB NAME="FROM" CONTROL="txtFrom"/></p> <p> <ATTRIB NAME="TO" CONTROL="txtTo"/></p> <p> <ATTRIB NAME="SUBJECT" CONTROL="txtSubject"/></p> <p> <ATTRIB NAME="FILE" CONTROL="txtFile"/></p> <p> <ATTRIB NAME="VARIABLE" CONTROL="txtVariable"/></p> <p> </ATTRIBUTES></p> <p> <TAGLAYOUT></p> <p> <WIZIF OPTIONLowerCaseTags EQ 'true'></p> <p> <WIZSET TAGNAME="cf_outputredirect"></p> <p> <WIZSET FILE="file"></p> <p> <WIZSET FROM="from"></p> <p> <WIZSET OUTPUT="output"></p> <p> <WIZSET SUBJECT="subject"></p> <p> <WIZSET TO="to"></p> <p> <WIZSET VARIABLE="variable"></p> <p> <WIZELSE></p> <p> <WIZSET TAGNAME="CF_OUTPUTREDIRECT"></p> <p> <WIZSET FILE="FILE"></p> <p> <WIZSET FROM="FROM"></p> <p> <WIZSET OUTPUT="OUTPUT"></p> <p> <WIZSET SUBJECT="SUBJECT"></p> <p> <WIZSET TO="TO"></p> <p> <WIZSET VARIABLE="VARIABLE"></p> <p> </WIZIF></p> <p> <WIZIF OPTIONLinearLayout EQ 'true'></p> <p> <WIZSET SpacingGap=" "></p> <p> <WIZELSE></p> <p> <WIZSET SpacingGap="&#13; "></p> <p> </WIZIF></p> <p> <WIZIF MainTabDialog EQ 'EMAIL'></p> <p> <$${TAGNAME} $${OUTPUT}="$${MainTabDialog}"$${SpacingGap}$${TO}="$${txtTo}"$${SpacingGap}$${FROM}="$${txtFrom}"$${SpacingGap}$${SUBJECT}="$${txtSubject}"></p> <p> </WIZIF></p> <p> <WIZIF MainTabDialog EQ 'FILE'></p> <p> <$${TAGNAME} $${OUTPUT}="$${MainTabDialog}"$${SpacingGap}$${FILE}="$${txtFile}"></p> <p> </WIZIF></p> <p> <WIZIF MainTabDialog EQ 'VARIABLE'></p> <p> <$${TAGNAME} $${OUTPUT}="$${MainTabDialog}"$${SpacingGap}$${VARIABLE}="$${txtVariable}"></p> <p> </WIZIF></p> <p> </TAGLAYOUT></p> <p></TAG>

    Let’s walk through the critical parts:

    1. EDITORLAYOUT – The top‑level container is a TabDialog that holds three TabPage containers. Each tab holds controls that match the output destination. Labels and controls are anchored so they stay aligned as the dialog resizes.
    2. ATTRIBUTES – The OUTPUT attribute is linked to the tab container so the editor remembers which tab was last used. Each destination attribute is linked to its corresponding control. When a developer opens the editor, the IDE pulls existing values from the tag and populates the fields.
    3. TAGLAYOUT – This section contains three WIZIF blocks that control how the tag is written back. The first block decides whether tag names and attributes should appear in upper or lower case, depending on the IDE setting OPTIONLowerCaseTags. The second block sets spacing between attributes, honoring OPTIONLinearLayout. The final three blocks write the actual tag, but only include the attributes that belong to the selected tab. If the Email tab is chosen, TO, FROM, and SUBJECT are written; if the File tab is chosen, only FILE appears; and so on.

       After saving this file, clear the IDE cache or restart ColdFusion Studio. Right‑click the <CF_OutputRedirect> tag in your source code, choose Edit Tag, and the editor will open exactly as defined. Switching between tabs will load the appropriate fields, and clicking Apply will output a correctly formatted tag, respecting the IDE’s case and layout preferences.

       Because VTML is declarative, you can extend the editor further. Add a CHECKBOX to toggle whether the email should be sent immediately, or a ColorSelector to choose a background color for the output file. Each new control is just another line in the EDITORLAYOUT section, linked via ATTRIB to the tag’s attribute. By following the same pattern you can create editors for any custom tag, making your components as user‑friendly as the core ColdFusion tags.