VTML for WizardsVTML 2

This document explains how to use VTML to build custom Wizards. This capability was introduced in the 4.0 release.

The following subjects are treated in this document:


See the Customizing the Development Environment section of Using HomeSite, Using ColdFusion Studio, or Using JRun Studio for implementation information.

Introduction

A Wizard consists of a single Wizard profile file which defines all pages, user input controls and output parameters, and one or more Wizard template files which use these parameters to generate code.

Both Tag Editors and Wizards can be used to create code based on user input. There are a number of important differences between the two, however. Both have their own advantages and limitations, for instance:

The choice between Wizard or Tag Editor should be carefully made. Of course, if you are using ColdFusion/JRun Studio and need the Wizard Definition Page Library, there is no choice: these can be used in Wizards only. And if you need to update an existing document that is opened in the editor, you can only use a Tag Editor for that.

VTML for Wizards tag reference

All of these tags have their own reference page; the tag names in the summary table below link to these pages. They provide the complete VTML syntax for writing Wizard profile files. Where this is useful, Usage Notes complement the reference.

VTML for Wizards Tags

Tag Description
WIZARD The enclosing tag for the entire file; it defines the new Wizard with a name, caption and default image.
PAGE Defines a wizard page.
PARAM
Used as a sub-tag of the WIZARD tag:
Defines a parameter that the Wizard uses to generate its output. These parameters are then available for use with wizard output templates.
Used as a sub-tag of the PAGE tag:
Passes a parameter to a page class: a pre-defined page. This is useful for standard pages from a library (like the Wizard Definition Page Library) which are intended to be re-used across multiple Wizards.
INPUT Declares an input control on a Wizard page. By matching the NAME attribute of the INPUT control with the name of a control on the wizard page and matching the PARAM attribute with the name of a PARAM defined within the WIZARD tag, the control is automatically 'bound' to the underlying parameter without requiring any explicit code.
PAGELAYOUT Equivalent to EDITORLAYOUT for Tag Editors: container for containers and controls.
NEXTPAGE Allows for complex routing between pages based on the value of conditional expressions.
TEMPLATE Defines an output template and identifies the file used for text output.

Dynamic expressions in tags

Attributes of Wizard tags can be set to a value using different methods:

You can, for example, set the REQUIRED attribute of a parameter based on whether another value was set:

<PARAM NAME="RowsPerPage" VALUE=10 REQUIRED="$${ ParameterExists('Customize')}"./>

The ParameterExists() function returns either True or False: the correct type for the REQUIRED attribute.

Note: These mechanisms for setting a value for an attribute based on the value of a parameter are available only for Wizard tags. This means that no attribute of a container or a control can be set this way. Only the "value" of a control itself can be (pre)set - and then only using the mechanism of bound controls; directly referencing a parameter value will not work.

Special Parameters

So far, we've seen two kinds of parameters: PARAMs defined inside the WIZARD tag which declare the output from the Wizard to the .wml template(s), and the PARAMs defined inside a page from the Wizard Page Definition Library which set the page's defined properties. Both are output parameters of a kind: they communicate something from the Wizard profile file to its environment.

There is a third type of parameter which we'll call special parameters. They are input parameters: you cannot assign a value to them but they provide a value that you can use. Also, unlike WIZARD and PAGE parameters they do not need to be declared (!) but can be bound to a control which is then initialized with the value of the parameter, or it can be used in a dynamic expression.

Special parameters are:

Location
The value of this parameter is equal to the folder selected in Local tab of the Resource panel. To use the value this parameter must be bound to a control (which is then initialized to its value); the parameter value cannot be used directly. Example:
<PAGE NAME="DocAttribs" TYPE="Dynamic" CAPTION="HTML Document Attributes">
    <PAGELAYOUT>
        <CONTROL TYPE="Label" NAME="lblLocation" DOWN=10
                 CAPTION="Output location:"/>
        <CONTROL TYPE="TextBox" NAME="editLocation"
                 ANCHOR="lblLocation" CORNER="NE"
                 RIGHT=10/>
    </PAGELAYOUT>
    <INPUT NAME="editLocation" PARAM="Location" REQUIRED/>
</PAGE>

It can then be used in the TEMPLATE tag:

<TEMPLATE NAME="Custom.wml" OUTPUTPATH="$$Location" OUTPUTFILE="MyFile.html"/>
SafeApplicationName
This parameter is available only in ColdFusion/JRun Studio since it's used in conjunction with the Wizard Definition Page Library. When on the SelectNameAndLocation page the user has entered a value for editApplicationName, this value is also copied to SafeApplicationName, which has all characters that cannot be used in a file name stripped out. The result can be used to construct a file name for the TEMPLATE tag:
<TEMPLATE NAME="DrillDown_AppendCriteria.wml"
          OUTPUTFILE="$${SafeApplicationName}_AppendCriteria.cfm"
          OUTPUTPATH="$${Location}"
          DESCRIPTION="Custom tag template, which generates the search query criteria string."/>

Bound Controls

One of the most powerful capabilities of Wizard pages are bound controls. The mechanism is provided by the INPUT tag.

The 'Data binding' provided by the INPUT tag works as follows: the NAME attribute of the INPUT tag identifies a control with a matching NAME attribute. The PARAM attribute of the INPUT tag should correspond to the NAME attribute of a Wizard PARAM; if omitted, it defaults to the value of the NAME attribute but this should still correspond to a Wizard PARAM. The current value of the Wizard then becomes available to the control and any new value entered by the user will be passed back to the PARAM. Largely, this works exactly as you would expect for different types of controls. Still, for a few types of control some details are noteworthy:

Label
The parameter value is passed to the CAPTION attribute of the control: the label will display the value of the parameter. This can be useful for instance for showing a final page with a summary of user input, or for showing the actual color value next to a ColorPicker control. There's a snag, however: If on one page an input control is used to let the user enter a value, and on a subsequent page this value is bound only to a label, then on leaving that page the value will be lost! In other words, a control and a parameter will retain the (bound) value only if it's bound to an input control. There is a workaround for this though, as shown in the next example.
 
Wizard parameter:
<PARAM NAME="Testparam" VALUE="">
Here's where the user can enter a value:
<PAGE TYPE="Dynamic" NAME="1" CAPTION="User input">
    <PAGELAYOUT>
        <CONTROL TYPE="Label" NAME="lblInput"
                 WIDTH="MAXIMUM" MAXWIDTHPADDING=10 DOWN=10 CAPTION="Input:"/>
        <CONTROL TYPE="TextBox" NAME="txtLabel"
                 WIDTH="MAXIMUM" MAXWIDTHPADDING=0
                 ANCHOR="lblInput" CORNER="SW" DOWN=5/>
    </PAGELAYOUT>
    <INPUT NAME="txtLabel" PARAM="Testparam"/>
</PAGE>
On a subsequent page we show the value in a label but also in a 'hidden' control:
<PAGE TYPE="Dynamic" NAME="2" CAPTION="Display result">
    <PAGELAYOUT>
        <CONTROL TYPE="Label" NAME="lblResult"
                 WIDTH="MAXIMUM" MAXWIDTHPADDING=10 DOWN=10
                 CAPTION="Result of your input:"/>
        <CONTROL TYPE="Label" NAME="lblLabel"
                 WIDTH="MAXIMUM" MAXWIDTHPADDING=0
                 ANCHOR="lblResult" CORNER="SW" DOWN=5/>
        <CONTROL TYPE="TextBox" NAME="txtLabel"
                 WIDTH=1 LFWIDTH=1 RIGHT=-1 DOWN=-1/>
    </PAGELAYOUT>
    <!-- note: this displays the label but ... -->
    <INPUT NAME="lblLabel" PARAM="Testparam"/>
    <!-- ... the hidden *input* control will retain its value: -->
    <INPUT NAME="txtLabel" PARAM="Testparam"/>
</PAGE>
Now, when the user leaves this page (in either direction) the value will be retained because it's still bound to an input control. (Read more about hidden controls and their uses: "Was that value changed?" (on-line).)
Note: Order is important! The INPUT tag binding the parameter to the input control must be defined after the INPUT tag binding the parameter to the label.
 
TextBox, StyleTextBox
The parameter value is passed to the VALUE attribute of the control which will show this as its initial value.
 
TextArea, StyleTextArea, SQLTextArea
These controls do not have an attribute to which its "value" can be assigned. They can get a value from a parameter all the same. It is, however, not possible to to predefine a multi-line value in the Wizard parameter.
Note: A '\n' to include a newline in the string would seem logical but this will be shown as a non-displayable character in the control.
 
DropDown
If one of the items of a DropDown control has the flag SELECTED, then normally this value will be shown when the control is displayed. When a parameter value is bound to a DropDown which has a different value that the one SELECTED, then the parameter value overrules the setting of the control itself - if that value occurs in the item list or the DropDown is editable. Note that for a preselect the parameter value will be shown, not the corresponding CAPTION! If the DropDown is not editable and the parameter value does not occur in the list, then that value will not be shown; normal display rules apply: the item with the the attribute SELECTED will be shown, or if none has that flag, the first item.
 
ListBox
This will probably behave as a non-editable DropDown: only if a parameter value actually occurs in the list can it be selected. If the ListBox has the MULTISELECT flag, multiple items can be preselected by setting the parameter to a comma-delimited list of values.
Note: Currently a ListBox control does not work as documented.
 
Image
The parameter value is passed to the FILEPATH attribute of the control: the selected image will be displayed. As with labels, binding a parameter value to an image control will lead to errors. In this case, the value will not be "forgotten" but it will be "re-interpreted" as an image path with often strange and always incorrect results. The workaround is the same as that for a label: bind the parameter to a 'hidden' input control as well and put the INPUT statement for this after the one for the image control.
 
A few more notes about displaying a (bound) image control on a Wizard page:

Wizard Definition Page Library

The Wizard Definition Page Library is available in ColdFusion/JRun Studio only. These pre-defined Wizard pages assist in building wizards which use RDS servers to get information on data sources, tables, and their fields. The following sections give a brief overview of how each page is used, what parameters make it work, and what controls you have access to. The names for these pages should be used in the TYPE attribute for the PAGE tag. You may want to look at the Drill-Down Wizard which comes with Studio for good examples of how to declare and use the pages.

SelectNameAndLocation

This page is useful as the first page in your Wizard and is required if you are going to use any of the other page definitions. It prompts the user for the name of their application and the location to store the application files. This page does not require any parameters to be passed.

Exposed controls

editApplicationName The text box in which the user types in the application name. The value in this text box is also copied to the special parameter SafeApplicationName, which has all characters that cannot be used in a file name stripped out.
editLocation A simple browse file text box for the destination location of the application. By binding this control to the LOCATION special parameter it will initialized to the folder selected in Studio on the local tab of the resource pane.

Example

<PAGE NAME="Page1" CAPTION="Admin Form Application"
      IMAGE="../images/Main.bmp" TYPE="SelectNameAndLocation">
    <INPUT NAME="editApplicationName" PARAM="ApplicationName" REQUIRED="true"
           VALIDATIONMSG="You cannot leave the Application Name field blank"/>
    <INPUT name="editLocation" PARAM="Location" REQUIRED="true"
           VALIDATIONMSG="You cannot leave the Location field blank"/>
</PAGE>

SelectDataSource

This page lets a user connect to an RDS server and select a datasource to use from that server.

Parameters needed

ListBoxLabel Caption to show next to the select data source dropdown box.
ListBoxDescription More room to better explain what data source to choose and why.
ResetParams
RemoveParams
These are params that need to have their values removed/reset in case the data source is changed from this specific page. For example, tables that were selected on the following page from one data source should be removed so that new tables can be selected. Both take a comma-delimited list as their value.

Exposed controls

cbDataSources This control is a drop down box for the user to select a data source from.

Example

<PAGE NAME="Page2" CAPTION="Data Source"
      IMAGE="../images/SelectData.bmp" TYPE="SelectDataSource">
    <PARAM NAME="ListBoxLabel" VALUE="Select data source:"/>
    <PARAM NAME="ListBoxDescription"
           VALUE="Choose the data source, which contains the table you wish to insert the data into.\n\nIf your database is not registered as ODBC data source, open the ODBC administrator in Control Panel and add system data source for this database."/>
    <PARAM NAME="RemoveParams" VALUE="Table,EntryFields,KeyFields"/>
    <INPUT NAME="cbDataSources" PARAM="DataSource" REQUIRED
           VALIDATIONMSG="You did not select the data source. Please select one before proceeding."/>
</PAGE>

SelectTable

This page gives you the option to select a single table from the data source. (SelectTables gives you the option to select multiple tables.)

Parameters needed

DataSource Required. Name of the data source to list the tables of. Usually use the variable set from the SelectDataSource page.
ListBoxLabel Short caption for the table list control.
ListBoxDescription Long description for giving explicit instructions for which table to select.
ResetParams
RemoveParams
These are params that need to have their values removed/reset in case the table selected is changed from this specific page.

Exposed controls

cbTables The control is a dropdown box containing a list of tables available from the specified data source.

SelectTables

This page gives you the option to select multiple tables, like the name suggests. But it is possible to have SelectTables behave just like SelectTable.

Parameters needed

DataSource Required. Name of the data source to list the tables of. Usually use the variable set from the SelectDataSource page.
ListBoxLabel Short caption for the table list control.
ListBoxDescription Long description for giving explicit instructions for which table(s) to select.
MultiSelect Whether or not to allow multiple tables selected. If set to No, SelectTables page will act just like SelectTable page.
ResetParams
RemoveParams
These are params that need to have their values removed/reset in case the table selected is changed from this specific page.

Exposed controls

lstTables The control is a list box containing a list of tables available from the specified data source. If the PARAM MultiSelect is set to Yes, multiple selection from the list box is possible.

SelectField

This page is used to select a single field from the specified table(s) from the specified data source.

The format in which the fields are outputted is "table.fieldname=type;size;required".

Type
Possible types are: BIT, CHAR, MEMO, INT, FLOAT, and DATETIME.
Size
The size of the field in bytes.
Required
Specifies whether or not the field can contain a null value. If required is YES, then the field cannot have a null value.

Parameters needed

DataSource Required. The name of the data source containing the tables.
Tables Required. The list of table(s) from which to show available fields.
ListBoxLabel Short caption next to the list box showing the fields.
ListBoxDescription Long description for explaining what field(s) can be chosen and what they will be used for.

Exposed controls

cbFields The dropdown control contains a list of fields available from the specified tables.

SelectFields

This page is used to select field(s) from the specified table(s) from the specified data source. The output format is the same as that for SelectField

Parameters needed

DataSource Required. The name of the data source containing the tables.
Tables Required. The list of table(s) from which to show available fields.
ListBoxLabel Short caption next to the list box showing the fields.
ListBoxDescription Long description for explaining what field(s) can be chosen and what they will be used for.
MultiSelect Whether the user should be able to select more than one field. If set to No, SelectFields will act just like SelectField. When allowed to select multiple fields, each field will be listed in the format specified above and the field specifications will be separated by commas. (e.g., table1.field1=type1;size1;required1, table2.field2=type2;size2;required2, ... etc.)

Exposed controls

lstFields The listbox control contains a list of fields available from the specified tables. If the PARAM MultiSelect is set to Yes, multiple selection from the list box is possible.

SelectTableJoins

This page lets the user select fields to be joined from the specified tables. You may preset some initial joins. Fields used in joins do not need to be selected in as fields in a SelectField or SelectFields page.

Parameters needed

DataSource Required. Data source where the tables are located.
Tables Required. Tables used to list fields on which to allow possible joins.
ListContent Values to appear in the list of joins. Recommended.

Exposed controls

lstJoins This is a list box showing the joins the user has selected. The value of this field will be comma-separated list with each item in the format of: "table1.field1=table2.field2".

Note: there are two more controls on this page: two drop down boxes to select fields from. But these are not "exposed" in that you cannot bind any parameter values to them. They make use of the values defined in the DataSource and Tables parameters.

Usage Notes

ListContent
While the parameter is not actually required (unlike the printed documentation suggests), its usage is highly recommended especially when SelectTableJoins is not the last page in a Wizard. You might want to set your Joins parameter to a blank string and put it in for this PARAM like this:

<PARAM NAME="ListContent" VALUE="$${Joins}"/>

This way, if someone moves on and then decides to come back to this page, the Joins list will still be there.

Wizard Output Summary

This is a pre-defined page that can neither be declared nor suppressed. Since it can't be declared, you also cannot define an IMAGE for it: it will use the default defined in the WIZARD tag. That's why it's highly recommended to define a default bitmap in the WIZARD tag!

Once the user presses the Finish button, the .wml templates defined in the Wizard profile file start doing their work. As soon as they all have finished without any errors (whether producing actual output or not), the Wizard Output Summary page will appear. It consists of:

On this page, the Finish button is replaced by a Close button (the < Back button remains active)); when the user presses this button, the Wizard is closed and all pages that were written will be opened in the editor.
Note: if a relative OUTPUTPATH was used (interpreted as relative to the program installation path), the file is written and mentioned in the summary, but a blank, untitled document will be opened instead of the generated document!

top