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:

• Introduction
  
• VTML for Wizards tag reference
• Dynamic expressions in tags
• Special Parameters
• Bound Controls
• Wizard Definition Page Library (ColdFusion/JRun Studio only)
• Wizard Output Summary

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

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:

• A Wizard can check whether a required field has been given a value; if not, an error message can be displayed; with a Tag Editor the only possibility is to somehow mark which fields are required.
• A Tag Editor in edit mode can work with current attribute values of a tag and the body of a container tag. A Wizard can not read anything on the current page.
• While some built-in Wizards can be started either from the File -> New... dialog (creating a new page) or from a predefined toolbar button (inserting text into the current document at the current cursor position), it is not possible to create a toolbar button for a custom Wizard. This implies that currently custom Wizards can only generate new pages, not insert text in an open document. A Tag Editor can write to the current document, but not create a new one.
• With a Wizard, different pages can be shown or not shown dependent on user input; the same goes for the order in which pages are shown. However, this can also be severely limiting for the user, especially when many data fields need to be filled in. With a Tag editor, the fields can be organized on tab pages which the user can freely jump between to refer back to other fields, and determine the most convenient order in which to fill them: something which may be different for different users.

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.

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

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

• Static, constant text (this is not dynamic, of course):
  

  <PARAM NAME="Number" VALUE=1 REQUIRED/>
  		

• The value of a parameter:

  <TEMPLATE NAME="Custom.wml" OUTPUTFILE="MyFile.html" OUTPUTPATH=$$Location/>
  		

• An expression which can include any of the functions available from WIZML and which can reference parameter values. To be able to use user input, the input control must be bound to a Wizard parameter; the parameter name (not the control name!) can then be used in the expression:

  <WIZARD NAME="MYWIZARD" CAPTION="My Wizard">
      <PARAM NAME="FName"/>
      <PAGE TYPE="Dynamic" NAME="OutputChoice"
            CAPTION="Set output file name" IMAGE="../Images/OpenWindow.bmp">
          <PAGELAYOUT>
              <CONTROL TYPE="Label" NAME="lblFilename"
                       ANCHOR="Panel1" CORNER="SW" DOWN=20
                       CAPTION="Filename without extension:"/>
              <CONTROL TYPE="TextBox" NAME="txtFilename" WIDTH=120 LFWIDTH=144
                       ANCHOR="lblFileName" CORNER="SW" DOWN=10/>
          </PAGELAYOUT>
          <INPUT NAME="txtFilename" PARAM="FName"/>
      </PAGE>
      <TEMPLATE NAME="Mywizard.wml" OUTPUTFILE="$${ Ucase(FName) }1.html" DESCRIPTION="First page"/>
      <TEMPLATE NAME="Mywizard2.wml" OUTPUTFILE="$${ Ucase(FName) }2.html" DESCRIPTION="Second page"/>
  </WIZARD>
  		

• Combinations of all of the above

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.

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
• SafeApplicationName (CFS/JRS only)

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."/>

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:

• The file type must be BMP (.bmp); if it isn't this will result in an error message when trying to display the page; if you press OK and then the Next > button, the page with the image control will be skipped and the value of the parameter is lost.
• If the file type is correct but the file is not found, an error message will pop up when trying to display the page; if you press OK and then the Next > button, the page with the image control will be skipped and the value of the parameter is lost.
• The file path can either be an absolute or a relative path. A relative path should be relative to the location of the current Wizard profile file.

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
• SelectDataSource
• SelectTable
• SelectTables
• SelectField
• SelectFields
• SelectTableJoins

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

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>

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

Parameters needed

Exposed controls

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>

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

Exposed controls

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

Exposed controls

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

Exposed controls

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

Exposed controls

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

Exposed controls

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.

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:

• A caption: "Wizard Output Summary"
• A label: "The following files were generated by the Wizard"
• A list box with an entry for each page actually written. The entries are separated by a blank line and each entry has the following format:
  [OUTPUTFILE] - [DESCRIPTION]
  with:

  [OUTPUTFILE]

  Name of the file as defined in the OUTPUTFILE attribute of the TEMPLATE tag

  [DESCRIPTION]

  File description as supplied in the DESCRIPTION attribute of the TEMPLATE tag

  Note that the OUTPUTPATH is not displayed in this summary!

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