Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

WIZML by Example - ColdFusion Studio Wizards

WIZML by Example - ColdFusion Studio Wizards

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.

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.


@ThingsExpo Stories
22nd International Cloud Expo, taking place June 5-7, 2018, at the Javits Center in New York City, NY, and co-located with the 1st DXWorld Expo will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud ...
"Cloud Academy is an enterprise training platform for the cloud, specifically public clouds. We offer guided learning experiences on AWS, Azure, Google Cloud and all the surrounding methodologies and technologies that you need to know and your teams need to know in order to leverage the full benefits of the cloud," explained Alex Brower, VP of Marketing at Cloud Academy, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clar...
In his session at 21st Cloud Expo, Carl J. Levine, Senior Technical Evangelist for NS1, will objectively discuss how DNS is used to solve Digital Transformation challenges in large SaaS applications, CDNs, AdTech platforms, and other demanding use cases. Carl J. Levine is the Senior Technical Evangelist for NS1. A veteran of the Internet Infrastructure space, he has over a decade of experience with startups, networking protocols and Internet infrastructure, combined with the unique ability to it...
"IBM is really all in on blockchain. We take a look at sort of the history of blockchain ledger technologies. It started out with bitcoin, Ethereum, and IBM evaluated these particular blockchain technologies and found they were anonymous and permissionless and that many companies were looking for permissioned blockchain," stated René Bostic, Technical VP of the IBM Cloud Unit in North America, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Conventi...
Gemini is Yahoo’s native and search advertising platform. To ensure the quality of a complex distributed system that spans multiple products and components and across various desktop websites and mobile app and web experiences – both Yahoo owned and operated and third-party syndication (supply), with complex interaction with more than a billion users and numerous advertisers globally (demand) – it becomes imperative to automate a set of end-to-end tests 24x7 to detect bugs and regression. In th...
Widespread fragmentation is stalling the growth of the IIoT and making it difficult for partners to work together. The number of software platforms, apps, hardware and connectivity standards is creating paralysis among businesses that are afraid of being locked into a solution. EdgeX Foundry is unifying the community around a common IoT edge framework and an ecosystem of interoperable components.
"MobiDev is a software development company and we do complex, custom software development for everybody from entrepreneurs to large enterprises," explained Alan Winters, U.S. Head of Business Development at MobiDev, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
Large industrial manufacturing organizations are adopting the agile principles of cloud software companies. The industrial manufacturing development process has not scaled over time. Now that design CAD teams are geographically distributed, centralizing their work is key. With large multi-gigabyte projects, outdated tools have stifled industrial team agility, time-to-market milestones, and impacted P&L stakeholders.
"Akvelon is a software development company and we also provide consultancy services to folks who are looking to scale or accelerate their engineering roadmaps," explained Jeremiah Mothersell, Marketing Manager at Akvelon, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
"Space Monkey by Vivent Smart Home is a product that is a distributed cloud-based edge storage network. Vivent Smart Home, our parent company, is a smart home provider that places a lot of hard drives across homes in North America," explained JT Olds, Director of Engineering, and Brandon Crowfeather, Product Manager, at Vivint Smart Home, in this SYS-CON.tv interview at @ThingsExpo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
Coca-Cola’s Google powered digital signage system lays the groundwork for a more valuable connection between Coke and its customers. Digital signs pair software with high-resolution displays so that a message can be changed instantly based on what the operator wants to communicate or sell. In their Day 3 Keynote at 21st Cloud Expo, Greg Chambers, Global Group Director, Digital Innovation, Coca-Cola, and Vidya Nagarajan, a Senior Product Manager at Google, discussed how from store operations and ...
"There's plenty of bandwidth out there but it's never in the right place. So what Cedexis does is uses data to work out the best pathways to get data from the origin to the person who wants to get it," explained Simon Jones, Evangelist and Head of Marketing at Cedexis, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
SYS-CON Events announced today that CrowdReviews.com has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5–7, 2018, at the Javits Center in New York City, NY. CrowdReviews.com is a transparent online platform for determining which products and services are the best based on the opinion of the crowd. The crowd consists of Internet users that have experienced products and services first-hand and have an interest in letting other potential buye...
SYS-CON Events announced today that Telecom Reseller has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5-7, 2018, at the Javits Center in New York, NY. Telecom Reseller reports on Unified Communications, UCaaS, BPaaS for enterprise and SMBs. They report extensively on both customer premises based solutions such as IP-PBX as well as cloud based and hosted platforms.
It is of utmost importance for the future success of WebRTC to ensure that interoperability is operational between web browsers and any WebRTC-compliant client. To be guaranteed as operational and effective, interoperability must be tested extensively by establishing WebRTC data and media connections between different web browsers running on different devices and operating systems. In his session at WebRTC Summit at @ThingsExpo, Dr. Alex Gouaillard, CEO and Founder of CoSMo Software, presented ...
WebRTC is great technology to build your own communication tools. It will be even more exciting experience it with advanced devices, such as a 360 Camera, 360 microphone, and a depth sensor camera. In his session at @ThingsExpo, Masashi Ganeko, a manager at INFOCOM Corporation, introduced two experimental projects from his team and what they learned from them. "Shotoku Tamago" uses the robot audition software HARK to track speakers in 360 video of a remote party. "Virtual Teleport" uses a multip...
A strange thing is happening along the way to the Internet of Things, namely far too many devices to work with and manage. It has become clear that we'll need much higher efficiency user experiences that can allow us to more easily and scalably work with the thousands of devices that will soon be in each of our lives. Enter the conversational interface revolution, combining bots we can literally talk with, gesture to, and even direct with our thoughts, with embedded artificial intelligence, whic...
SYS-CON Events announced today that Evatronix will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Evatronix SA offers comprehensive solutions in the design and implementation of electronic systems, in CAD / CAM deployment, and also is a designer and manufacturer of advanced 3D scanners for professional applications.
Leading companies, from the Global Fortune 500 to the smallest companies, are adopting hybrid cloud as the path to business advantage. Hybrid cloud depends on cloud services and on-premises infrastructure working in unison. Successful implementations require new levels of data mobility, enabled by an automated and seamless flow across on-premises and cloud resources. In his general session at 21st Cloud Expo, Greg Tevis, an IBM Storage Software Technical Strategist and Customer Solution Architec...
To get the most out of their data, successful companies are not focusing on queries and data lakes, they are actively integrating analytics into their operations with a data-first application development approach. Real-time adjustments to improve revenues, reduce costs, or mitigate risk rely on applications that minimize latency on a variety of data sources. In his session at @BigDataExpo, Jack Norris, Senior Vice President, Data and Applications at MapR Technologies, reviewed best practices to ...