Rendering

One final issue to understand when creating output for a WML browser is what the text you create in the source code will look like when it reaches the device's display. The two main things to be concerned with are how non-alphanumeric characters will be displayed and what character set the browser requires.

Special Characters

When constructing text for the browser, you must avoid embedding characters in the raw text that are reserved by WML. I've already shown that you cannot place the dollar sign ($) character in text because the browser will attempt to dereference a variable there; this section covers the other characters that are special to WML.

Any text that you embed in the deck must not interfere with the parser's separation of markup from content. That is, if you want to deliver a string such as "Use <b> to create bold text," you must keep the parser from recognizing the first <b> tag as the place to begin the bold formatting:

Use <b> to create <b>bold</b> text.

To make this happen, XML provides you with named and numeric entities. These entity markups tell the parser to replace them with the character you desire to display after the parsing is complete. For example, the entity markup &lt; represents the less-than angle bracket whereas &gt; represents the greater-than angle bracket; to place the sentence on the display, you can use the following code:

Use &lt;b&gt; to create <b>bold</b> text.

This avoids the parser confusion but creates less-readable source code for you. Since the entity markup uses the ampersand (&), you must also avoid placing ampersands in your text. Table 5.3 shows you a list of entities that you will use frequently in your WML text.

I discussed both the &nbsp; and &shy; entities earlier in this chapter. You will need to use the quote and apostrophe entities in attribute values when you use the " and 'to wrap those values in the tag. Listing 5.12 shows you all these entities in action on a single card.

Listing 5.12 Special WML Character Entities

<?xml version="1.0"?>
<!-- listing0512.wml -->

<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN"
    "http://www.wapforum.org/DTD/wml12.dtd">
<wml>
    <!-- demonstrate standard entity markups -->
    <card title="Parser Friendly">

        <!-- setup some tricky variables -->
        <onevent type="onenterforward">
            <refresh>

                <!--when using the ('') to denote attribute -->
                <!-- data, must use &quot; escapement       -->
                <setvar name="Quote"
                    value="&quot;Ask not what...&quot;" />

                <!-- when using the (') to denote attribute -->
                <!-- data, must use &apos; escapement       -->
                <setvar name="Apos"
                    value='This is Charles&apos;s day'/>
            </refresh>
        </onevent> 

        <p mode='wrap'>
            <!-- avoid single ($), they start variables -->
            $$ begins a variable<br/>

            <!-- avoid single (&), they start entities -->
            &amp; begins an entity<br/>

            <!-- don't use (<) or (>), they mark tags  -->
            &lt;b&gt; starts <b>bold</b><br/>

            <!-- you can avoid line breaking  -->
            &amp;nbsp;&nbsp;avoids&nbsp;line&nbsp;breaks<br/>

            <!-- you can suggest places to break lines  -->
            anti&shy;dis&shy;establish&shy;ment&shy;arian&shy;ism
            <br/>

            <!-- display the quote and the apostrophe vars -->
            $(Quote)<br/>
            $(Apos)<br/>
        </p>
    </card>
</wml>

Although the card in Listing 5.12 looks quite contrived, it's likely that you will run into each of those situations in your application construction. The deck first assigns variable values that have a quote or an apostrophe and, since you can use either in XML to wrap attribute data, you must escape them.

Next, the deck in Listing 5.12 displays a properly escaped dollar sign and a properly escaped ampersand. The deck goes on to incorporate the bold tag example from earlier and then creates a very long line that it does not want to have broken on word boundaries. The card wraps up with a long word that suggests the locations on which the browser can break lines and the values of the variables from the beginning. You can see the results of all this escapement in Figure 5.10.

In addition to the named values for the entities, you can use numeric values in either decimal or hexadecimal. Decimal entities are created with &#dd; where dd is the two or more digit value and hexadecimal entities are created with &#xhh; where hh is the two or more digit value. For example, you can create an ampersand with &amp;, &#38;, and &#x26;. Table 5.3 lists the decimal entity values along with the named entities for your convenience.

Internationalization

Character sets and fonts are often a source of confusion when creating applications, and since WAP is an international specification, you should be familiar with the basics of internationalization. The first thing you must recognize is that the character set of the document is distinct and might be different from the character set the browser will use to display the contents of the document.

All WML documents are written in the character set specified by "XML: Universal Character Set of ISO/IEC-10646 (ISO10646)." This character set is identical to Unicode 2.0, which allows the use of subsets such as US-ASCII, UTF-8, and ISO-8859-1. The XML parser assumes that UTF-8 or UTF-16 is used for every WML document, unless the enctype attribute is supplied in the <?xml> processing directive that begins every instance.

When you create your WAP application, if you use a character set other than UTF-8, you must send along the character set specification in the HTTP headers for the deck. By placing this information on the header, you allow the WAP gateway to translate whatever the original character set is to a character set that the browser can understand. To do this, you must alter the Content-type HTTP header, either statically or dynamically. For example, the following HTTP header specifies that the WML document is written in ISO-8859-1:

Content-type: text/vnd.wap.wml; charset=ISO-8859-1

Further, to allow the proper translation of any returned data from the browser, you should design your input cards such that they place the data in <postfield> tags rather than in URLs. You should also set the accept-charset attribute of the <go> tag to indicate the destination set. This allows the WAP gateway to make the character set translation again as data passes from the browser to your application.

▸ See Chapter 7 for more details on passing data from the browser to WAP applications using the <go> and <postfield> tags.

Now that the character set of the WML document itself is set, let's look at the language that the browser uses to display your deck. Your WAP application will receive a set of HTTP request headers each time a browser wants a new deck. One of the standard headers sent will be HTTP_ACCEPT_LANGUAGE. Your application should use this to decide whether it can produce a deck that the browser can understand.

The HTTP/1.1 specification, RFC 2068, defines the format of the HTTP_ACCEPT_LANGUAGE header value. It is a comma-separated, ordered list of language preferences. Each language preference is a formed with a primary type and, if desired, a subtype. Primary language types are two-letter abbreviations from ISO 639; for example, en stands for English and da stands for Danish. The language subtype can be more complicated; if it is a two-letter code, it must be a country code from ISO 3166; for example, US stands for United States. The type and subtype are separated by a hyphen and they are not case sensitive; some examples:

en, en-US, en-cockney, i-cherokee, x-pig-latin

Whenever your application encounters a language type that the browser accepts and it can fulfill, it should. When your application cannot generate any of the languages acceptable to the browser, you can choose to generate the response in the default language, or return an HTTP error 412 (Precondition Failed).