Feature

This article is the third in a series on customizing the CF Studio IDE. If you haven't read the first two about VTML, see "VTML by Example, Parts 1 and 2" (CFDJ, Vol. 3, issues 6 and 7) for an introduction to the CF Studio extensions, and learn how to use the Visual Tools Markup Language (VTML) to develop the user interfaces for CF Studio extensions. This article demonstrates how to design CF Studio Wizards using the Wizard Markup Language (WIZML).

What Are Custom Wizards?
Custom wizards are step-based dialogs inside CF Studio that ask for user data and solve special tasks based on this data. Put simply, CF Studio Wizards are a series of dialogs that the user goes through sequentially, and when finished generates a new template. Select "New..." from the File menu for a list of installed wizards to choose from (many helpful wizards are available).

The Wizard Markup Language
WIZML, a tag-based markup language, makes custom wizards possible by adding flow control and input processing to VTML-based dialogs.

A wizard consists of a single wizard definition (also known as a wizard profile) file (named .vtm) that defines all pages, user input controls, output parameters, and one or more wizard output template files (named .wml) that use these parameters to generate code. Basically, you have to write a .VTM file that controls the user interface, input parameters, and logical flow of the wizard's steps. Then you define the resulting output pages the wizard generates after the user finishes inputting all data. Each output template file must be named .WML (for Wizard Markup Language) and contain the code the wizard should generate.

These .WML files are like templates in the sense that you can output all WIZML variables using the $${VariableName} notation. But more on this later. Keep in mind that you'll need to develop two types of files: a .VTM file for controlling the user interface and logical flow of the wizard, as well as at least one .WML file that's used as an output template.

You can deploy a custom-made wizard by placing its .VTM and .WML files in CF Studio's \Wizards\Custom folder, or create your own folder under the \Wizards directory. From now on you can use the freshly deployed wizard by choosing "New..." from the "File" menu.

The Wizard Definition File (.VTM)
An outline of a wizard .VTM file is shown in Listing 1. As you can see, each wizard .VTM file has the <wizard> tag as its root tag. Inside it holds a declarative section (all the <param> tags at the beginning) where you can set up the WIZML variables you'll output in the resulting template. This declarative section is followed by <page></page> blocks that define each wizard page by describing the page's layout inside the <pagelayout> tag and binding the input controls (e.g., textboxes, etc.) to WIZML variables using the <input> tag. Define each wizard step that way, so you'll end up with multiple <page> sections. At the end of the .VTM file you'll notice at least one <template> tag that simply assigns which output .wml templates to process after the wizard's steps are completed by the user.

Now we'll discuss the details of developing a wizard .VTM file. I'll guide you through the source code of a real-world wizard I developed. This wizard helps developers who don't have the in-depth knowledge of WDDX and JavaScript to create cool, dynamically synchronized select boxes for a parent-child relation, such as browsing a set of items within a set of categories. To understand how the wizard is built, read on. To understand what the wizard actually does (creating the WDDX and JavaScript code for the synchronized select boxes) read my article "WDDX with JavaScript" in CFDJ (Vol. 3, issue 2).

Let's assume you're primarily interested in how to build such a wizard, so I'll leave the explanation of WDDX and JavaScript aside. As you can see from Figures 1-4 the wizard prompts for some data, such as the data source, the tables, and columns to populate the synchronized select boxes to make them dynamic.

Looking at the File in Detail
Let's start looking at the code. The Wizard Definition File (syncSelect.VTM) is available on the CFDJ Web site (www.sys-con.com/coldfusion/sourcec.cfm).

At first the root tag <wizard> needs a name, a caption, as well as (optionally) an image to display (see Figures 1-4). You can create your own images and distribute them with your wizard (they must be saved in the \wizards\images directory in BMP format and be 138x293 pixels). A nice pool of preshipped images is available with any CF Studio installation (see existing images in the wizard\images directory).

Next define all WIZML parameters that will be populated from the wizard definition file into the output templates (.wml) and are invoked after the user has completed the steps of the wizard. You can define them using the tags similar to the following:

<PARAM name="theCategoryTitle" value="" required="true">

As you can see, aside from initializing them with default values, you can set them as required or as optional parameters.

After you've defined all your WIZML variables, set up the logical flow by defining the wizard's pages. This is done by placing blocks of <page> tags in the .VTM wizard definition file. Basically, you have two types of pages available: custom-made pages where you directly place the input controls on the page, or predefined pages taken from CF Studio's library of predefined wizard pages. These predefined wizard pages come in many flavors such as data-source choosing dialogs, and table and column selection pages.

First let's look at the custom-made pages and discuss the different predefined flavors later on. To prefix these two sections, both types of pages need a name as an attribute as well as a caption and an optional image reference. Custom-made pages consist of both a page layout and a variable binding section.

Custom Page Layout
All custom-made pages have the attribute type="DYNAMIC" in the <page> tag to define it as a custom page.

To design such a page place input controls (e.g., labels, text fields, select boxes, etc.) on the wizard page inside the <pagelayout> block. For details on which input controls VTML offers and how to place them inside the <pagelayout> block, consult Part 1 of this series about VTML. Using VTML controls in TagEditors is the same as in wizards, so this article should shed some light there.

Variable Binding
To use data that was entered in a VTML input field within the .wml output template, bind the VTML input control to a WIZML variable in the wizard definition file. This is done at the end of each wizard <page> block using the VTML tag <input>. In the WIZML code snippet (see Listing 2) is a simple wizard page with a label and a text box that's bound to the WIZML variable, theUsername.

As you can see, the text field is rendered using the <control> tag inside the <pagelayout> block, and it's bound to a WIZML variable using the <input> tag. Also the variable is made mandatory by setting the "required" flag to "yes," and a validation error message is provided that pops up when the user wants to proceed with the next wizard step and no text was entered in that variable. That way you can ensure that all required fields will be entered by the wizard's users. To make use of this type of page design you should read Part 1 or at least look at the Help System of the CF Studio IDE regarding the VTML layout.

Predefined Wizard Pages
Let's look at which prebuilt wizard pages CF Studio has available for our use. For the many common tasks of a wizard page, CF Studio has prebuilt pages that we can use without worrying about the VTML layout of this page. The predefined wizard pages we can use are:

• SelectNameAndLocation
• SelectDataSource
• SelectTable
• SelectTables
• SelectField
• SelectFields
• SelectTableJoins

Except for the first one, all predefined wizard pages solve common tasks when databases come into play, such as choosing data sources from the remote CF server, and selecting tables, fields, and even joins from live data. Compared to custom-made wizard pages, you can invoke these predefined ones quite easily (see Listing 3).

Set the <page>'s "type" attribute correctly and fill the predefined parameters with your own text using the <param> tag; for example, customizing the prebuilt page. Then bind the resulting values to WIZML variables using the <input> tags as described earlier. For a complete list of all prebuilt wizard pages and their use consult the CF Studio Help.

Logical Page Flow
By default, all pages are shown in the order in which they're defined in the wizard definition file using the <page> blocks. If you'd like to change this order, append the attribute nextpage="name OfNextPage" on the <page> tag to specify the next page to show. You can even go further and define a Boolean condition (that evaluates as true or false) to put into the <page>'s condition attribute, for example, condition="some-Variable EQ 23". If the <page> tag has such a condition assigned, this page is displayed only if the condition evaluates to true, otherwise the next page will be shown.

Output Templates (.WML)
We've successfully built a wizard definition file (.VTM) to render the wizard's user interface and logical flow. But this alone does not make a wizard, since the data entered by the users should be processed in a way to generate output files. Basically this is very easy, since the output files of a wizard are named .wml and registered at the end of the wizard definition file using the <template> tags:

<TEMPLATE
name="syncSelect.wml"
outputfile="$${theFilename}.cfm"
description="Synchronized Select-Boxes"/>

This tag defines a .wml output file to be processed (syncSelect.wml) and saved into a .cfm file after the wizard has finished its processing. The "outputfile" attribute of this tag names the resulting file that should be generated. Though I'm using a WIZML parameter to let the user determine the exact filename, you could also code the name directly into the outputfile attribute.

Output templates are processed by the CF Studio wizard engine and saved in the specified .cfm filenames. Upon processing, the CF Studio wizard engine understands WIZML syntax, so you can output all WIZML variables from the wizard definition file inside the output template. This is done using the $${VariableName} notation. There's even a set of WIZML tags and functions available for use in an output template. A simple output template (.wml) file would look like this:

<b>Hello $${theUserName} it's now
<cfoutput>#DateFormat(Now())#</cfoutput><b>
<wizif Len(theImageFile) GT 0>
<img src="$${theImageFile}" border="0">
<wizelse>
[no image set]
</wizif>

Here you see the two WIZML variables "theUserName" and "theImageFile" being used, as well as a WIZML tag for conditional processing (<wizif>) and the WIZML string function Len(). As you can see, WIZML has tags that allow decision-making logic, looping, variable assignment, file including, and more to be coded inside a .wml template. For a detailed reference description of these WIZML tags as well as the available WIZML functions for string processing see the CF Studio Help.

In the .wml wizard output template (syncSelect.WML) of this article's wizard (available on the CFDJ Web site) there's a block of code in which WIZML string functions are used. This is often necessary when using the results from prebuilt wizard pages, since they return their values in strings that often need to be parsed. In the .wml wizard output template the results from our table-choosing wizard dialogs are parsed to get the table name.

All WIZML tags and WIZML functions are processed by CF Studio's wizard output generator, and the rest (which may, of course, include CFML tags) is simply written into the resulting page. You can enable WIZML to work with CFML the same way CFML works with HTML: using CFML you can dynamically create HTML code. While using WIZML you can dynamically (i.e., created by a wizard) generate CFML/HTML pages.

VTML and WIZML provide developers with tools to extend the IDE's functionality using <tags>. For further information on VTML and WIZML see the chapter "Customizing the Development Environment" on CF Studio's Help. This chapter also has a nice VTML/WIZML reference section available.

Add Your Feedback

In order to post a comment you need to be registered and logged in.

Register | Log in

Please wait while we process your request...