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.
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.
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.
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 |
|
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. |
Attributes of Wizard tags can be set to a value using different methods:
<PARAM NAME="Number" VALUE=1 REQUIRED/>
<TEMPLATE NAME="Custom.wml" OUTPUTFILE="MyFile.html" OUTPUTPATH=$$Location/>
<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>
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:
<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"/>
<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:
<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).)
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.
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.
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. |
<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.
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. |
cbDataSources | This control is a drop down box for the user to select a data source from. |
<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.)
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. |
cbTables | The control is a dropdown box containing a list of tables available from the specified data source. |
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.
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. |
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. |
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"
.
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. |
cbFields | The dropdown control contains a list of fields available from the specified tables. |
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
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.)
|
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. |
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.
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. |
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.
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:
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!