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:

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
<wizif Len(theImageFile) GT 0>
<img src="$${theImageFile}" border="0">
[no image set]
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
Enterprises have taken advantage of IoT to achieve important revenue and cost advantages. What is less apparent is how incumbent enterprises operating at scale have, following success with IoT, built analytic, operations management and software development capabilities - ranging from autonomous vehicles to manageable robotics installations. They have embraced these capabilities as if they were Silicon Valley startups.
The standardization of container runtimes and images has sparked the creation of an almost overwhelming number of new open source projects that build on and otherwise work with these specifications. Of course, there's Kubernetes, which orchestrates and manages collections of containers. It was one of the first and best-known examples of projects that make containers truly useful for production use. However, more recently, the container ecosystem has truly exploded. A service mesh like Istio addr...
Predicting the future has never been more challenging - not because of the lack of data but because of the flood of ungoverned and risk laden information. Microsoft states that 2.5 exabytes of data are created every day. Expectations and reliance on data are being pushed to the limits, as demands around hybrid options continue to grow.
Poor data quality and analytics drive down business value. In fact, Gartner estimated that the average financial impact of poor data quality on organizations is $9.7 million per year. But bad data is much more than a cost center. By eroding trust in information, analytics and the business decisions based on these, it is a serious impediment to digital transformation.
Business professionals no longer wonder if they'll migrate to the cloud; it's now a matter of when. The cloud environment has proved to be a major force in transitioning to an agile business model that enables quick decisions and fast implementation that solidify customer relationships. And when the cloud is combined with the power of cognitive computing, it drives innovation and transformation that achieves astounding competitive advantage.
Digital Transformation: Preparing Cloud & IoT Security for the Age of Artificial Intelligence. As automation and artificial intelligence (AI) power solution development and delivery, many businesses need to build backend cloud capabilities. Well-poised organizations, marketing smart devices with AI and BlockChain capabilities prepare to refine compliance and regulatory capabilities in 2018. Volumes of health, financial, technical and privacy data, along with tightening compliance requirements by...
As IoT continues to increase momentum, so does the associated risk. Secure Device Lifecycle Management (DLM) is ranked as one of the most important technology areas of IoT. Driving this trend is the realization that secure support for IoT devices provides companies the ability to deliver high-quality, reliable, secure offerings faster, create new revenue streams, and reduce support costs, all while building a competitive advantage in their markets. In this session, we will use customer use cases...
Andrew Keys is Co-Founder of ConsenSys Enterprise. He comes to ConsenSys Enterprise with capital markets, technology and entrepreneurial experience. Previously, he worked for UBS investment bank in equities analysis. Later, he was responsible for the creation and distribution of life settlement products to hedge funds and investment banks. After, he co-founded a revenue cycle management company where he learned about Bitcoin and eventually Ethereal. Andrew's role at ConsenSys Enterprise is a mul...
DXWorldEXPO LLC announced today that "Miami Blockchain Event by FinTechEXPO" has announced that its Call for Papers is now open. The two-day event will present 20 top Blockchain experts. All speaking inquiries which covers the following information can be submitted by email to [email protected] Financial enterprises in New York City, London, Singapore, and other world financial capitals are embracing a new generation of smart, automated FinTech that eliminates many cumbersome, slow, and expe...
DXWorldEXPO | CloudEXPO are the world's most influential, independent events where Cloud Computing was coined and where technology buyers and vendors meet to experience and discuss the big picture of Digital Transformation and all of the strategies, tactics, and tools they need to realize their goals. Sponsors of DXWorldEXPO | CloudEXPO benefit from unmatched branding, profile building and lead generation opportunities.
The best way to leverage your Cloud Expo presence as a sponsor and exhibitor is to plan your news announcements around our events. The press covering Cloud Expo and @ThingsExpo will have access to these releases and will amplify your news announcements. More than two dozen Cloud companies either set deals at our shows or have announced their mergers and acquisitions at Cloud Expo. Product announcements during our show provide your company with the most reach through our targeted audiences.
DevOpsSummit New York 2018, colocated with CloudEXPO | DXWorldEXPO New York 2018 will be held November 11-13, 2018, in New York City. Digital Transformation (DX) is a major focus with the introduction of DXWorldEXPO within the program. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of bus...
With 10 simultaneous tracks, keynotes, general sessions and targeted breakout classes, @CloudEXPO and DXWorldEXPO are two of the most important technology events of the year. Since its launch over eight years ago, @CloudEXPO and DXWorldEXPO have presented a rock star faculty as well as showcased hundreds of sponsors and exhibitors! In this blog post, we provide 7 tips on how, as part of our world-class faculty, you can deliver one of the most popular sessions at our events. But before reading...
Cloud Expo | DXWorld Expo have announced the conference tracks for Cloud Expo 2018. Cloud Expo will be held June 5-7, 2018, at the Javits Center in New York City, and November 6-8, 2018, at the Santa Clara Convention Center, Santa Clara, CA. Digital Transformation (DX) is a major focus with the introduction of DX Expo within the program. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive ov...
DXWordEXPO New York 2018, colocated with CloudEXPO New York 2018 will be held November 11-13, 2018, in New York City and will bring together Cloud Computing, FinTech and Blockchain, Digital Transformation, Big Data, Internet of Things, DevOps, AI, Machine Learning and WebRTC to one location.
DXWorldEXPO LLC announced today that ICOHOLDER named "Media Sponsor" of Miami Blockchain Event by FinTechEXPO. ICOHOLDER give you detailed information and help the community to invest in the trusty projects. Miami Blockchain Event by FinTechEXPO has opened its Call for Papers. The two-day event will present 20 top Blockchain experts. All speaking inquiries which covers the following information can be submitted by email to [email protected] Miami Blockchain Event by FinTechEXPO also offers s...
Dion Hinchcliffe is an internationally recognized digital expert, bestselling book author, frequent keynote speaker, analyst, futurist, and transformation expert based in Washington, DC. He is currently Chief Strategy Officer at the industry-leading digital strategy and online community solutions firm, 7Summits.
Digital Transformation and Disruption, Amazon Style - What You Can Learn. Chris Kocher is a co-founder of Grey Heron, a management and strategic marketing consulting firm. He has 25+ years in both strategic and hands-on operating experience helping executives and investors build revenues and shareholder value. He has consulted with over 130 companies on innovating with new business models, product strategies and monetization. Chris has held management positions at HP and Symantec in addition to ...
Cloud-enabled transformation has evolved from cost saving measure to business innovation strategy -- one that combines the cloud with cognitive capabilities to drive market disruption. Learn how you can achieve the insight and agility you need to gain a competitive advantage. Industry-acclaimed CTO and cloud expert, Shankar Kalyana presents. Only the most exceptional IBMers are appointed with the rare distinction of IBM Fellow, the highest technical honor in the company. Shankar has also receive...
With tough new regulations coming to Europe on data privacy in May 2018, Calligo will explain why in reality the effect is global and transforms how you consider critical data. EU GDPR fundamentally rewrites the rules for cloud, Big Data and IoT. In his session at 21st Cloud Expo, Adam Ryan, Vice President and General Manager EMEA at Calligo, examined the regulations and provided insight on how it affects technology, challenges the established rules and will usher in new levels of diligence arou...