Learning WML, and WMLScript

The <input> Element

Let’s start our exploration of WML’s mechanisms for user interaction with the <input> element, since we’ve just seen it in action.

This element is used whenever the user needs to enter a string or some other piece of text. Usually, this should be kept as short as possible, since many WAP users use cell phone keypads to enter these. Entering the letter S on a computer keyboard is easy, but this requires four keypresses on most cell phones. Symbols are even worse: with the exception of a few, such as . and +, symbols are very time-consuming to enter.

The <input> element can also be used to enter passwords or other sensitive information. In these cases, the element can be configured to not display the text as it’s being entered. (In the case of cell phones, most display each character for a short time but then replace it with a * or other symbol.)

This element is also used for entering numbers. In cases like this, where the range of characters is restricted, it’s possible to set a format for the string, which may speed up input. To do so, set the format to allow only digits; a cell phone knows that the keys don’t need to cycle through all the letters before offering a digit (the digits are accessed with a single keypress instead of four or more).

This element (as with all user interaction elements) may be put anywhere in normal paragraph text (namely, inside a <p> element). It takes nine^[9] attributes, most of which are optional.

Attributes of the <input> Element

name (required name)

Gives the name of the variable that gets the text from this element. When the element is displayed, it’s initialized to the contents of this variable if it’s set. If it isn’t, the element is initialized to the value of the value attribute if present; otherwise it’s initially empty.

type (optional string; default text)

If omitted or set to text, indicates that this element doesn’t receive sensitive data, and that the text should be displayed as normal. If set to password, specifies that the text should be obscured in some way. This is normally done by replacing all the characters with some fixed character when displaying the contents. Any other value is illegal.

value (optional variable string; default empty)

Gives an optional initial value for the text in the element. This default is used only when the variable given by the name attribute isn’t set. If that variable contains a value, its value initializes the element instead.

format (optional string; default *M)

Gives an optional format for the value. This format can display static text in the input area and can restrict the range of characters that may be entered. A smart browser uses this attribute to speed user input. A format attribute containing illegal codes is ignored. The legal codes are:

A

Any uppercase letter or symbol (not a digit).

a

Any lowercase letter or symbol (not a digit).

N

Any numeric character (digit or decimal points).

X

Any uppercase character.

x

Any lowercase character.

M

Any character: uppercase characters may be offered first, but anything is permitted.

m

Any character: lowercase characters may be offered first, but anything is permitted.

* f

Any number of characters (zero or more) matching format code f (where f is one of the previous format codes: A, a, N, X, x, M, or m). This may be specified only once and must be at the end of the string.

nf

Entry of exactly n characters (where n is a digit from 1 to 9), each matching format code f. This may be specified only once and must be at the end of the string. This is equivalent to using n occurrences of code f.

\ c

Forces character c to be displayed in the text entry field. This character is displayed within the field and is passed through into the value.

For example, the format code NNN\-NNNN matches local North American telephone numbers (such as 555-1234).

Warning

Beware, however, of working too many assumptions such as this into your WAP decks, as different countries have different formats for things such as telephone numbers.

emptyok (optional boolean; default false)

If set to true, specifies that an empty string is a valid input, even if the format attribute otherwise prevents this. If the format string allows an empty input, that takes precedence, and emptyok is ignored. Since the default value for format allows empty input anyway, this attribute has no effect if no format attribute is given.

size (optional number)

Provides a hint as to how many characters wide the text input should be drawn, if the browser supports it (if it doesn’t, this is ignored). This value doesn’t limit the number of characters that can be entered into the element; for that, see the maxlength attribute.

maxlength (optional number; default unlimited)

Specifies the maximum number of characters that may be entered into this element.

title (optional variable string)

Gives a title to this element, which some browsers may use in its presentation.

tabindex (optional number)

Provides a hint to the browser about the order in which the user should be allowed to cycle through the elements. This attribute is described fully in Section 4.10 in this chapter.

Examples of the <input> Element

Example 4.1 shows how a typical login page asking for a username and password can be constructed. The username is forced to consist entirely of lowercase letters, and the password is obscured when it’s entered. Then there is a <do> element (explained later in this chapter), containing a <go> task. The effect of these last two is to add a button or similar control to the card, which sends the browser to the URL from the href attribute of the go task when it’s activated .

Example 4-1. A Login Page

<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC
    "-//WAPFORUM//DTD WML 1.1//EN"
    "http://www.wapforum.org/DTD/wml_1.1.xml">

<wml>
    <card title="Login">
        <p>Username:
            <input name="user" format="*x"/></p>
        <p>Password:
            <input name="pass" type="password"/></p>
        <do type="accept" title="Log In">
            <go href="login?u=$(user:e)&amp;p=$(pass:e)"/>
        </do>
    </card>
</wml>

---

^[9] Strictly speaking, all WML elements may have three standard attributes, id, class, and xml:lang. Apart from one special use of the id attribute on the <card> element, the id and class attributes are intended for use in server-side applications, are ignored by the browser, and won’t be mentioned again. The xml:lang attribute specifies “the natural or formal language” (to quote from the WML specification) of the element: its content is an abbreviation for a particular language (such as en for generic English). This is supposed to influence the display of the elements contained within (for example, certain languages are written right to left rather than left to right), but it’s not implemented by any current browsers, and hence won’t be mentioned again. If this all sounds confusing, just forget it: everyone else does.