Learning WML - Navigation, User Input, and Graphics, Page 3
Accepting User Input
Although the forms capability of WML isn't as robust as standard HTML, the <input> element is very flexible and allows a variety of data to be accepted from the user.
The <input> element has the following minimal form:
<input name="variable_name" />
In this form, the element accepts user input and stores it in the variable specified. The input is freeform; that is, it is not constrained to any particular format (numeric, alphanumeric, etc.) or length--although most mobile browsers impose a length limit of 256 characters.
Note: A full discussion of WML variables is outside the scope of this article, but will be provided in the next article. For this exercise it is important to know that variables exist and can be set by <input> and <setvar> elements, among others. A variable can then be referenced by prefixing its name with a dollar sign ("$"), or using the preferred method of enclosing the name in parentheses and prefixing the whole structure with a dollar sign. For example, the variable "firstname" can be referenced as "$firstname" or "$(firstname)". When the variable is referenced, WML will substitute the variable's value for its reference.
The <input> element also supports the optional parameters shown in the following table.
|title||Supplies a title for the element. Some devices display this title in the default Accept soft key label; others display it as "tooltip" text while the element is selected.|
|type||Set to "text" or "password," this parameter controls whether the text is displayed as it is entered or displayed in the browser's password character(s) (usually "*").|
|value||The default value for the element. Note that if the variable specified in the "name" parameter already has a value, or if the value specified with this parameter doesn't conform to the specified "format" parameter, the value is ignored.|
|accesskey||Displays the specified number (0-9) next to the element. The key can be used to quickly select the element.|
|format||Specifies the format mask of the input. See the format section below for details on masking.|
|emptyok||Controls whether the element can be left empty. The valid values for this parameter are "true" (the default) or "false."|
|maxlength||Maximum length of the input, in characters.|
Note: The "accesskey" parameter allows you to create a form of several input fields where the user can easily navigate between the fields. However, as the Openwave applications point out (http://developer.openwave.com), wizards that display card-sized chunks of data entry fields are much better received and make a better application design.
The "format" parameter's value is composed of a series of characters that provide a mask for the input. The following table describes the valid instructional characters for the format mask:
|A||Any symbol or uppercase alpha character (no numbers).|
|a||Any symbol or lowercase alpha character (no numbers).|
|N||Any number (no symbols or alphabetic characters).|
|X||Any symbol, number, or uppercase alpha character (cannot be changed to lowercase alpha).|
|x||Any symbol, number, or lowercase alpha character (cannot be changed to uppercase alpha).|
|M||Any symbol, number, or alpha character; by default, the first character is uppercase.|
|m||Any symbol, number, or alpha character; by default, the first character is lowercase.|
The format mask can also include symbols, which will be displayed in their appropriate position in the input.
For example, to accept a phone number, including the area code, you could use this format mask:
format = "(NNN) NNN-NNNN"
When using the same character multiple times in a row, you can prefix the character with a number indicating how many times it repeats. Using this method, our phone number mask could be written like this:
format = "(3N) 3N-4N"
However, this format isn't as recognizable as a phone number mask.
Note: To specify an unlimited number of the same character, prefix the character with an asterisk (*).
A simple deck to accept a person's first name (up to 25 characters) and then greet the person by name would resemble the following listing:
<?xml version="1.0"?><!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml"> <wml><card id="GetName" title="Get Name"><do type="accept"> <go href="#Hello"/> </do> <p>What is your first name?<input name="name" format="*M" maxlength="25" /></p></card><card id="Hello" title="Hello"><p>Hello, $(name)!</p></card></wml>
Notice that the <input> element uses the "M" format mask, supplying an uppercase letter as the default first character. The "maxlength" parameter constrains the input's length, despite the "*" in the mask.
The deck navigation in this example is controlled by a <do> element linked to the Accept key. In some devices the user will have to press the Accept key twice--once to exit the input element and another to trigger the navigation.
There are many useful things you can do with user-supplied input besides echo it back in other cards. The next article in this series will discuss several other uses for user input.