Related Topics: ColdFusion on Ulitzer

CFDJ: Article

VTML by Example

VTML by Example

This article demonstrates how to customize and extend ColdFusion Studio's capabilities. Allaire has built lots of nice widgets into the Studio Integrated Development Environment (IDE) to help developers wherever they can. And they did a good job, as you can see.

Starting at the customization level we can define our own color-coding schemes, code templates, keyboard shortcuts, icons, toolbars, and more. Most of this can be customized inside Studio's Options dialog (press F8 to open it directly). At the extension level there are efficient techniques available, including Tag Completion, Tag Insight, Tag Editors, and custom Wizards.

In this article I demonstrate how to extend ColdFusion Studio by using VTML to integrate your custom tags into the Studio IDE.

What are Tag Editors, Tag Insight, and custom Wizards? I suppose most of you working with Studio are using the Tag Insight feature (can be enabled from the Options dialog) quite often while typing HTML and CFML tags. This handy pop-up box lists all possible attributes of the tag you're currently typing so you can choose the attributes you want (see Figure 1).

In addition, the Tag Insight, available at the left-handed resource tab labeled "Tag Inspector," lists all possible attributes with their values grouped together. Tag Editors are dialog boxes in which you enter tag attributes into a GUI (with some basic validation possible) that can be activated by right-clicking a tag and choosing "Edit tag..." from the context menu (see Figure 2 for a tag editor in action).

Custom Wizards are step-based dialogs that ask information and complete special tasks based on what the user has entered. Put simply, ColdFusion Studio Wizards are a series of dialogs that the user has to go through sequentially that results in a new template being generated. When choosing "New..." from the File menu you have a list of all installed wizards (there are many helpful wizards being shipped with your Studio installation) to choose from (see Figure 3 for the first step of Studio's LDAP wizard). Now let's see how to develop the features that extend CF Studio.

The Visual Tool Markup Language (VTML)
VTML is a family of markup languages used to extend the IDE of HomeSite and ColdFusion Studio. Using VTML you can define your own Tag Insight and Tag Editors, which is very helpful when developing your own custom tags, since you can simply put the VTML files inside your distribution, enabling your custom tags to tightly integrate into the ColdFusion Studio IDE. As the name (Markup Language) might suggest, VTML is a tag-based language (CFML is also tag-based) and therefore easy to learn.

The Wizard Markup Language
WIZML is also a tag-based markup language that extends VTML, making custom Wizards possible through the combination of VTML for the user interface and WIZML under the hood for flow control and input processing. The use of VTML is the main topic of this article's tutorial; how to use WIZML to develop custom Wizards will be the topic of a future article.

Beginning with Easy VTML Now let's jump into some practical examples of VTML, since this article aims to be an example-based tutorial. The easiest (and also fastest) way to enhance your custom tags with VTML is to use the visual Tag Definitions Editor. As you can see from Figure 4, the visual VTML editor for the Tag Insight can be called from the Resource Tab's Tag Inspector (click on the red-marked icon representing a gear). All you've got to do in the VTML editor to generate a Tag Insight for your custom tag is the following:

  1. Click on the "Add Tag..." button and enter the custom tag's name
  2. Click the "Add..." button on the right tab to add attributes to your custom tag
  3. Define the type of each attribute by choosing the appropriate type from the "Edit Type" drop-down listbox:
  • Text: For attributes taking strings as their value
  • Enumerated: For attributes taking one value out of a list of pre- defined values
  • Color: For attributes representing a color value
  • Font: For attributes representing a font definition
  • FileName: For attributes holding a file name
  • FilePath: For attributes holding a file path
  • Directory: For attributes holding a directory name
  • RelativePath: For attributes holding a relative path
  • Style: For attributes holding a stylesheet definition
  • Flag: For attributes acting as flags without having values
  • Queryname: For ColdFusion recordsets
  • Expression: For a ColdFusion expression
  1. Optionally, you can add categories to organize your attributes into different types (for example, mandatory and optional) under the Attribute Categories tab.
    The logical grouping of attributes into categories is outlined in the Tag Inspector when you've selected a tag (see the left-sided attribute list in Figure 1).
  1. To add documentation to your tag simply enter a filename of an HTML file that documents your tag at the Documentation tab of the Tag Definitions Editor.
  2. Finally, click the "Done" button and restart ColdFusion Studio to let the changes take effect.
  3. Open a new template and start typing your custom tag. Voilà! Tag Insight is working for your tag.
This editor is a good starting point for getting the basic VTML for the Tag Insight feature done quickly. Starting here, look at the VTML code generated by the Tag Definitions Editor. After using the VTML editor you can find this file on your workstation, depending on where you installed ColdFusion Studio. Just look at the subdirectories of C:\Program Files\Allaire\ ColdFusion Studio\Extensions\Tag- Defs\. As a custom tags developer you can distribute this VTML file along with your custom tag to seamlessly integrate it into CF Studio for developers using your tag. All your clients have to do is copy the custom tag you distributed into their Custom Tag Directory and the .VTM file inside the subdirectories of C:\Program Files\Allaire\ ColdFusionStudio\Extensions\ Tag-Defs\, and restart ColdFusion Studio.

Providing Help Files
To provide your custom tags with the help feature (every CFML tag has a help feature - press F1 when the cursor is selecting a tag), just write the docs in a simple HTML file and name it like your Custom Tag. For example, if your custom tag is , its source file would be named myOwn-customtag.cfm, the source file for the VTML code would be named cf_myOwnCustomTag.vtm, and the help file would be cf_ myOwn-customtag.htm and placed inside the directory C:\Program Files\ Allaire\ ColdFusionStudio\Extensions\Docs\ CFMLTags\. See Listing 1 for a sample help file.

VTML Syntax
Now let's look at how it was done by analyzing the results that were automatically generated for you. An outlined VTML file has the following structure:

<TAG> <ATTRIBUTES>
... Defines tag attribute properties and behavior
</ATTRIBUTES>

<ATTRIBCATEGORIES>
... Defines logical grouping for tag attributes
</ATTRIBCATEGORIES>

<EDITORLAYOUT>
... Defines the layout of a tag editor
</EDITORLAYOUT>

<TAGLAYOUT>
... Defines the tag generation template
</TAGLAYOUT>
<TAGDESCRIPTION>
... HTML-based documentation for the tag
</TAGDESCRIPTION>
</TAG>

The Tag Definitions Editor helps us by generating the <ATTRIBUTES>, <ATTRIBCATEGORIES>, and <TAG-DESCRIPTION> sections, which is enough to provide your custom tags with Tag Inspector, Tag Help, and Tag Insight features inside Studio. However, if you wish to have Tag Editor dialogs working for your custom tags you'll have to dig a little deeper into the VTML syntax and code the user interface of the dialogs by hand. You might think it sounds difficult, but it'll be much easier than you might expect.

Part 2 of this article will cover TagEditor dialogs. Meanwhile, you should work with the VTML you've seen in this article in order to get a feeling for how this customization of CF Studio helps developers.

More Stories By Christian Schneider

Christian Schneider is an Allaire Certified ColdFusion and Web site developer. He has over four years of intensive experience developing CF-based intranet applications for banks and logistic corporations.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.