WAP and ColdFusion

Developing WAP applications in ColdFusion means using ColdFusion's many powerful features in the creation of WML decks sent to a microbrowser. It's important to approach this chapter with a firm foundation in WML. Please be sure to read previous chapters about using WML, especially matters regarding user interface design, limited information presentation, etc.

 

For those with existing ColdFusion applications generating HTML, it's not really appropriate to expect to port these to applications generating WML. As has been said before in this book, you really need to rethink your applications when building for WML.

 

In this section, we'll learn the key to creating WML applications in ColdFusion—the CFCONTENT tag. We'll also show a basic example, as well as how to create and execute such CF code, and even how to use this approach to support different wireless programming languages.

 

Beyond that, we'll cover the detail of creating real WAP applications, including processing form submissions, performing database query and update processing, creating enhanced displays, and
much more.

The Key to the Kingdom: CFCONTENT

The key to developing WAP applications in ColdFusion comes down to a single tag, <CFCONTENT>. Just add the following CFCONTENT tag to the top of your ColdFusion template (.cfm file), coded otherwise with normal WML:

 

 

To generate WMLScript decks, use:

 

 

What these tags do is change the MIME type for the page being generated – remember this was first discussed back in Chapter 2. The <CFCONTENT> tag 'tells' the file to send its output using the appropriate MIME type. (Of course, you can still have static, non-ColdFusion WML and WMLScript pages on your server, served as .wml and .wmls files as described in previous chapters. Refer to those for more information on configuring your web server to serve those sorts of files. What we're saying here is that for .cfm files, the CFCONTENT tag indicates the type of page being sent to the browser.)

 

This will allow you to enter (or have ColdFusion generate) any valid WML (or WMLScript) code, and that code will be sent to the browser in a format that a wireless browser (or emulator) will expect. (Of course, you should cause only valid WML to be sent to the microbrowser. Some CF tags build HTML or JavaScript, and they should be avoided. See more on this matter in Techniques, Tips, And Traps.)

A Basic ColdFusion WAP Example

Let's take a quick look at a simple WML example to see how this works in practice. Enter the following code as a .cfm file called wml_hello.cfm:

 

 

When executed (as described below), this simple ColdFusion program assigns the name "Bob" to a variable we've decided to call fname, and then displays a message using a string (Hi there,) and that variable. The <CFSET> tag creates the variable to be displayed, and the <CFOUTPUT> tags surround the text that will display such variable values. Within the <CFOUTPUT> tags, we use # signs to denote ColdFusion variables to be evaluated. Because # signs have special meaning in WML – as anchors, similar to their use in HTML – you need to be careful if you plan to use one for that purpose within <CFOUTPUT>. See Techniques, Tricks, and Traps for further discussion.

 

The observant reader may have noticed that the first line of code has the <?xml> tag appearing on the same line as the CFCONTENT tag. That's not a mistake. There have been reports of some browsers and WAP servers failing to read a page as valid WML if a carriage return is sent to the browser prior to that <?xml> tag.

Saving and Calling the Sample Code

If you save the code above as wml_hello.cfm in a directory on your web server, you can then test it in any WML-compliant browser via the address: http://yourserverdomain/wml_hello.cfm.

 

Though it's not necessary, it would be best to create a new directory in your web server in which to put your WML files. It will facilitate handling errors that may arise, as discussed later in the chapter.

 

The page will be rendered and will display Hi there, Bob on the browser. We can now expand upon this by adding any ColdFusion code we'd like to generate dynamic WML.

 

If you receive an error, running this simple example, it's possible that you've tripped over one of a few other possible problems that may have to do with the configuration of your ColdFusion server to properly handle certain aspects of processing for creating WML files. We address several of these configuration issues later in Techniques, Tricks, and Traps.

Supporting Other WAP Language Variants

You may have noticed that in the example above we used WAP Forum's specification for the WML DTD. Another specification is that of Phone.com (see Chapter 2), and to use this instead, you need to code the DOCTYPE line as:

 

 

Note that the code in this chapter has been tested on the UP.Simulator and a Sprint Touchpoint phone with the UP.Browser embedded, but it worked fine with the WAP Forum DTD.

Using Other Features of ColdFusion

There are some useful features of ColdFusion that make life easier for the WAP developer, or make your applications more capable. This section will examine some of the more interesting ones.

Processing Form Submissions

Fortunately, some things in WML are very similar to HTML processing, and the ColdFusion support for these is equally straightforward. Form field (and query string) processing is a great example – that is, processing data entered by a user on a form. If you want to store it in a database, or e-mail it, or do any sort of thing on the server with that data, you'll need to pass it from the browser to the server, using either POST or GET methods. We saw how to do this with static WML back in Chapter 4.

 

The WML for creating a simple form follows:

 

 

 

The user is prompted to enter a stock symbol (i.e. a symbol representing a stock that, for example, you may have shares in). Here's what it looks like in the Phone.com UP.Browser emulator:

 

When the user enters a symbol and clicks the OK or Accept button, this page passes control (via the <go href> element) to a ColdFusion page (wml_action.cfm) that can process the form. We'll see more on that in a moment.

 

Most of the WML code should be familiar to you by now, but especially for coders more familiar with HTML form processing, some things should be pointed out. Notice first that there is no <FORM> tag as in HTML. And we are submitting the form via an HREF, not an "action". We repeat the field to be submitted, first in the <input> and then in the <formfield> elements, and there is a useful format attribute for the <input> element. WML form processing is indeed quite different. Be sure to read the previous chapters on WML programming!

 

You may also observe that this file has no ColdFusion code in it at all! We could have left out the <CFCONTENT> tag and coded the example as a plain WML file. There are two reasons not to do this:

 

q         Doing it this way makes the form extensible. We could add ColdFusion code to it very easily and would not need to change the file name and any links pointing to it. (In fact, we'll be changing it shortly to present a list of stock symbols to the user customized for them.)

q         Leaving this non-ColdFusion WML file as a ColdFusion template solves the problem of a web server that has not yet been configured to support WML files – the code will still work. (Remember, the web server is not telling the browser that the file is a WML MIME type, the CFCONTENT tag is.)

 

When the user submits the form, the form field symbol will be passed to the "action" page. In this case, wml_action.cfm will process the form. There are many things that this action page can do (which we will show in a moment). For now, let's focus on just a very simple example:

 

 

 

If the user enters the symbol ALLR (the symbol for Allaire, makers of ColdFusion), on the form, then they should see something that looks like this:

 

Let's talk about the code. The challenge in some server programming languages is that they use rather clumsy or verbose mechanisms for identifying the form data passed in to this action page. As you can see, it's quite straightforward in ColdFusion. We simply refer to the field name that was given when the form field was created on the <postfield> element, which was named symbol. More specifically, we refer to the field by its type as well, which being a form field is form and is specified as form.symbol. This is called a prefix in ColdFusion, and we'll see some more as we go along. We could have had any number of form fields passed in from the form, and they would all be accessible using the syntax form.fieldname.

 

Before moving on, there's one other way to process a form and/or pass data to a ColdFusion page, and it involves another type of variable prefix: the url prefix. This is the easy way that ColdFusion allows you to refer to data passed as a query string on a URL when calling one page from another. An example of such passing of data is:

 

 

This is just as an alternative to using the "post" method of form processing and using the <postfield> element for passing data from a form. The choice is really yours as a WML programmer.

 

The good news is that such data is just as easy to process in ColdFusion as form data. In the example given, we could (in wml_action.cfm) refer to the data passed in as #url.symbol#. In that respect, you can use it in just the same way you use form fields. (In fact, ColdFusion doesn't really even require that you specify the prefix for these two types of variables, so in the ColdFusion code in wml_action.cfm, you could refer in both examples to just #symbol#.)

 

You should be aware, however, that passing multiple variables on the query string has unique challenges in WML processing. Be sure to read the Techniques, Tricks, and Traps section for more information.

 

So far, we've seen only how to print back to the user information that they have already entered. But this is just the beginning.

Query Processing

Of course,