Nokia WAP Toolkit - GeNeura Teamgeneura.ugr.es/~victor/cursillos/wmlscript/devguide.pdfWML output from the CGI or other script application. 6 The WAP gateway verifies the HTTP header

http://www.forum.nokia.comProduct number: SDK-01-000-002Version 1.2 September 1999

Developer’s GuideNOKIA WAP TOOLKIT

Version 1.2

©1999. Nokia Corporation. Nokia is a registered trademark of Nokia Corporation.

Developer’s GuideNOKIA WAP TOOLKIT

Version 1.2

Product number: SDK-01-000-002

Copyright © Nokia Corporation 1999. All rights reserved.

We welcome and consider all comments and suggestions. Please send them to:

Nokia Group FinlandP.O. Box 226,FIN-00045 NOKIA GROUP

Tel. +358 9 180 71Fax. +358 9 656 388

Internet mail address:[email protected]

http://www.forum.nokia.com

This document is part of the Nokia Wireless Application Protocol Toolkit. Reproduction, distributionor transmission of part or all of this documentation in any form without the prior written permission ofNokia is prohibited.

The content of this documentation may be changed without prior notice.

“Nokia,” the arrows symbol and Nokia’s product names are trademarks of Nokia.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems, Inc. in the United States and other countries.

Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation.

Portions of the Nokia WAP Toolkit contain technology used under license from the World Wide WebConsortium and are copyrighted by the World Wide Web Consortium (Massachusetts Institute ofTechnology, Institut National de Recherche en Informatique et en Automatique, Keio University).

http://www.forum.nokia.com/

NOKIA WAP TOOLKIT i

Contents

Introduction..................................................................................1Wireless Application Protocol............................................................................. 1Nokia WAP Toolkit ............................................................................................ 4Typographical conventions.................................................................................. 5Related documents............................................................................................... 5

Documents included in the Nokia WAP Toolkit .......................................... 5Other references ............................................................................................. 6

Overview of WML.........................................................................7Introduction to WML syntax .............................................................................. 7

Overview of WML syntax.............................................................................. 8Entities.......................................................................................................... 8Tags .............................................................................................................. 8Elements ....................................................................................................... 8Attributes ................................................................................................... 10Comments .................................................................................................. 10Variables ..................................................................................................... 10Case sensitivity........................................................................................... 11WML structure........................................................................................... 11

Working with WML elements ....................................................13WML elements................................................................................................... 13

Deck and cards ............................................................................................. 13card element ............................................................................................... 14

Events ........................................................................................................... 16do element .................................................................................................. 16

Task elements ............................................................................................... 17go task ........................................................................................................ 18prev task ..................................................................................................... 19refresh task ................................................................................................. 19noop task .................................................................................................... 19

Variables ....................................................................................................... 19User input..................................................................................................... 20Anchors, images, and timers......................................................................... 20Text formatting............................................................................................. 21Example deck................................................................................................ 21

Multiple cards in multiple decks........................................................................ 23Using the template element .......................................................................... 24

History stack...................................................................................................... 26

Developer’s Guide

ii NOKIA WAP TOOLKIT

Variables and dynamic interfaces....................................................................... 27Naming variables .......................................................................................... 27Setting variables ............................................................................................ 28Substituting variables.................................................................................... 29Variable example........................................................................................... 29

User input .......................................................................................................... 31input element ................................................................................................ 31

Specifying the character format.................................................................. 34select element................................................................................................ 35

Single-choice list......................................................................................... 37Multiple-choice list .................................................................................... 38

Using links ......................................................................................................... 39Link example ................................................................................................ 40

Using timer ........................................................................................................ 40Intrinsic events................................................................................................... 41Displaying text................................................................................................... 43

Emphasis....................................................................................................... 43Text format example .................................................................................. 44

Line breaks ................................................................................................... 44Text wrapping and alignment....................................................................... 44table element................................................................................................. 45Special characters .......................................................................................... 47

WMLScript ..................................................................................49Overview of WMLScript ................................................................................... 49

WMLScript standard libraries ...................................................................... 50WMLScript non-standard libraries .............................................................. 50WML and WMLScript example ................................................................... 50

Security ......................................................................................53Access element ................................................................................................... 53

Access control example ................................................................................ 54Writing secure WML ......................................................................................... 55

Web server .................................................................................57MIME types....................................................................................................... 57HTTP headers included in the server ................................................................ 58Character sets..................................................................................................... 59

Example applications ................................................................61Currency converter............................................................................................ 61Mortgage payment calculator ............................................................................ 66

Glossary .....................................................................................69

Index ...........................................................................................77

NOKIA WAP TOOLKIT 1

Introduction

This guide provides information and practical examples for developers using theNokia WAP Toolkit tools to create services on the Wireless Application Protocol(WAP) platform.

The Nokia WAP Toolkit gives owners of small handheld devices such as mobilephones access to a wide variety of wireless services over the Internet. It offersdevelopers an environment for creating, testing and demonstrating WAPapplications, allowing service providers to evaluate the usability of wirelessapplications and services with their end user organizations.

The Nokia WAP Toolkit includes a simulator client for Windows NT, Windows95, and Windows 98, as well as content encoders and practical Wireless MarkupLanguage (WML) examples.

The Nokia WAP Toolkit 1.2 simulates a generic WAP mobile phone (you haveyour choice models), later referred to as user agent. A WAP user agent is similar toa web browser with the distinction that in the WAP environment UniformResource Locators (URLs) are requested over conventional cellular networks. TheURL request is sent to a web server containing WML services. These servicesrespond to the requests using WML. WML is based on the Extensible MarkupLanguage (XML) and was developed by the WAP Forum for specifying the contentand user interface for narrowband devices such as mobile phones.

The Nokia WAP Toolkit 1.2 also includes an XML library that you can use toconstruct valid WML documents for use by server-side components or for generaluse.

Wireless Application Protocol

Digital wireless user agents such as mobile phones have become very popular inrecent years. Technically speaking, mobile phones are no longer just phones; theyare communication devices capable of running applications and communicatingwith other devices and applications over a wireless network.

The WAP standard specifies two essential elements of wireless communication: anend-to-end application protocol and an application environment based on abrowser. The application protocol is a layered communication protocol that isembedded in each WAP-enabled user agent. The network side includes a servercomponent implementing the other end of the protocol that is capable ofcommunicating with any WAP user agent. Often the server component takes therole of a gateway routing the requests from the user agent to an application server.

Developer’s Guide Introduction

2 NOKIA WAP TOOLKIT

The gateway can be physically located in a telecom network or in a computernetwork, building a bridge between the two networks. The following pictureillustrates the WAP network structure.

WIRELESS NETWORK

COMPUTERNETWORK

WAPIP

WAP GATEWAY

WIRELESSTERMINAL

APPLICATIONSERVER

WAP network structure.

A WAP application consists of a server application and a client application that thegateway downloads from the application server to the user agent for execution. Astandard application environment is needed for running the same client applicationon different mobile user agents. WAP provides such a standard, consisting of abrowser and a script interpreter. The browser is very similar to a web browser andcan handle content described in WML. The browser also contains a built-in scriptinterpreter for running applications in the user agent. These applications are writtenin a script language called WMLScript. In addition to the programming languageitself, the script interpreter also implements a set of libraries that allow theapplication to access certain services of the user agent. WML and WMLScript aredesigned for use in wireless, narrowband networks, and they are both binaryencoded for optimum transmission efficiency.

The WAP protocol has four layers:

1 Session layer

2 Transaction layer

3 Security layer

4 Datagram layer

The following picture illustrates the WAP protocol architecture. For reference, thepicture also contains a typical Internet protocol stack.

Introduction Developer’s Guide

NOKIA WAP TOOLKIT 3

Internet

HTMLJavaScriptTM

HTTP

TLS - SSL

TCP/IPUDP/IP

SMS USSD CSD IS-136 CDMA CDPD PDC-P Etc..

Bearers:

Wireless Application Protocol

Wireless ApplicationEnvironment (WAE)

Wireless Session Layer (WSP)

Wireless Transport Layer Security (WTLS)

Wireless Datagram Protocol (WDP)

Other Services and

Applications

Wireless Transaction Protocol (WTP)

1

2

3

4

WAP and Internet protocol stacks.

In most cases, the actual application or other content is located on a web server.The content can be native WAP, created with WML and WMLScript, or it can beHTML. Some gateways are capable of translating HTML into WML.

In WAP, the content and the applications are addressed with an URL, in the sameway as in other Internet protocols. The following picture illustrates this.

Web Server

Content

CGIScripts

etc.W

ML

Dec

ksw

ith

WM

LSc

ript

WAP Gateway

WML Encoder

WMLScriptEncoder

Protocol Adapters

Client

WML

WML-Script

Etc.

HTTPWAP

1 2 3

4

56

7

WAP network protocol structure.

The WAP is similar to a Web model, and operates as follows:

1 The user presses a phone key that has an URL request assigned to it.

2 The user agent sends an URL request to a WAP gateway using the WAPprotocol.

3 The WAP gateway create an conventional HTTP request for the specified URLand sends it to the web server.


4 NOKIA WAP TOOLKIT

4 The HTTP request is processed by the web server. The URL may refer to astatic file or to a CGI or other script application. In the first case, the webserver fetches the file and adds an HTTP header to it. If the URL specifies ascript application, the web server runs the application.

5 The web server returns the WML deck with the added HTTP header or theWML output from the CGI or other script application.

6 The WAP gateway verifies the HTTP header and the WML content andencodes them to binary form. The gateway then creates a WAP responsecontaining the WML and sends it to the user agent.

7 The user agent receives the WAP response. It processes the WML response anddisplays the first card of the WML deck to the user.

For more information on the WAP, refer to the guides listed in “Relateddocuments” on page 5.

Nokia WAP Toolkit

The Nokia WAP Toolkit provides tools for creating services on the WAP platform.It includes the following components:

n Nokia WAP Toolkit application for Windows NT 4.0, Windows 95, andWindows 98. The Toolkit simulates the behavior of WML and WMLScript andallows you to create, edit, and debug WML and WMLScript services. Thesimulation client includes the following components:

— WML browser, including WMLScript interpreter and WMLScript libraries

— WML and WMLScript encoders

— WAP Protocol Stack, HTTP and file access modules

— debugging views

— generic WAP phone user interface simulation module (choice of models)

— WML and WMLScript editor

n Installation utility and practical WML example applications and source code.You can use these examples as a starting point for creating your own services.

n XML library that you can use to construct valid WML documents for use byserver-side components, or for general use. The library only allows you tocreate valid content, as validated by the standard DTD for WML1.1.Additional validation may be performed, specific to WML and beyond thescope of that which is possible with the DTD alone. Output is canonical XML,encoded as UTF-8 only. In addition, the library exposes a document treemodel that may be traversed and edited.

n User documentation in Adobe PDF format, including this Developer’s Guideand WML and WMLScript language references.

Introduction Developer’s Guide

NOKIA WAP TOOLKIT 5

Typographical conventions

The following conventions are used throughout this guide.

Notation Explanation

Courier Text that you enter and that appears onscreen,program code, file and directory names, functionnames.

Courier Bold WML tags, URLs.

Courier Italic Parameter values (for example, type="options"),variables in commands and other types of specializedlanguage.

Italic References to other guides and documents, newterminology.

Bold Names of Windows menus, commands, buttons andicons.

| Separates alternative items. For example,<img align="left|right|center">means that the image can be aligned left, center orright.

The following convention is used when referring to the installation directory of theNokia WAP Toolkit:

<installation directory>

By default, the Nokia WAP Toolkit installation directory isC:\Program Files\Nokia\WAPToolkit.

Related documents

The following documents contain additional information on the Nokia WAPToolkit and the WAP. The web address provided after each document specifies theInternet location where the document can be obtained.

Documents included in the Nokia WAP Toolkit

n Nokia WAP Toolkit Getting Started

This guide provides basic information on the Nokia WAP Toolkit and theWML, and provides instructions on installing and using the product.


6 NOKIA WAP TOOLKIT

n WML Reference

This guide provides reference information on the WML. It introduces theWML syntax and provides code examples.

n WMLScript Reference

This guide provides reference information on the WMLScript language. Itintroduces the WMLScript and its standard libraries.

Other references

n Wireless Markup Language Specification.WAP Forum, 16-June-1999.http://www.wapforum.org/

n WMLScript Specification.WAP Forum, 16-June-1999.http://www.wapforum.org/

n Wireless Application Environment Specification.WAP Forum, 16-June-1999.http://www.wapforum.org/

n Wireless Application Protocol Architecture Specification.WAP Forum, 16-June-1999.http://www.wapforum.org/

n Wireless Session Protocol Specification.WAP Forum, 16-June-1999.http://www.wapforum.org/

n Extensible Markup Language (XML).W3C Proposed Recommendation, 10-February-1998, REC-xml-19980210.http://www.w3.org/TR/REC-xml

http://www.wapforum.org/docs/technical.htm

http://www.wapforum.org/

http://www.wapforum.org/docs/technical.htm




http://www.w3.org/TR/REC-xml

NOKIA WAP TOOLKIT 7

Overview of WML

This chapter gives an overview of the WML syntax and provides examples of howyou can build simple WML services.

Refer to the Glossary on page 69 for definitions of new terms used in this chapter.

Introduction to WML syntax

This section provides an overview of the basic WML syntax. For a more detailedpresentation on WML, refer to the WML Reference guide provided with the NokiaWAP Toolkit.

WML is an XML language inheriting the XML document character set. In WML, adocument character set is the set of all logical characters that a document type maycontain, for example the letter ‘T’ and a fixed integer identifying that letter. AWML or XML document is simply a sequence of these integer tokens, which takentogether form a document.

The basic unit of WML is the card, which specifies a single interaction between theuser agent and the user. Cards are grouped together into decks. A deck is the top-most element of a WML document. When a user agent receives a deck, it typicallyactivates the first card in the deck unless directed to a different card as specified bythe requesting URL in its reference section.

Deck

CardCard

CardCard

CardCard

CardCard

Developer’s Guide Overview of WML

8 NOKIA WAP TOOLKIT

Overview of WML syntax

WML is a case-sensitive language, that is, Speed and speed are different entities.WML also converts tabs and spaces to a single space. To make the examplescontained here easier to follow, we have formatted them with newlines and tabs.However, note that this formatting is not required for WML to be valid.

WML inherits most of its syntactic constructs from XML. For detailed informationon the syntactical issues of XML, refer to the XML Specification.

Entities

WML text can contain numeric or named character entities that specify specificcharacters in the document character set. Entities are used to specify characters inthe document character set which must either be escaped in WML or which may bedifficult to enter in a text editor. For example, the ampersand (&) is represented bythe named entity &. All entities begin with an ampersand and end with asemicolon.

Tags

A tag is a language element descriptor. A tag describes an element and contains anelement type name and a unique identifier. A tag could also include attributesdescribing other properties.

WML consists of content surrounded by formatting tags, each enclosed in a pair ofangle brackets, < and >.

<tag> This starts an element. The start tag can contain attributes.

</tag> This ends an element.

<tag/> This is an empty element, for example <br/>, indicating a line break.

Elements

Elements specify all markup and structural information for a WML deck. Elementsmay contain a start tag, content, other elements, and an end tag. Elements have oneof two structures:

<tag> content </tag>

- or-

<tag/>

Elements containing content and other elements are identified by a start tag <tag>and an end tag </tag>. An empty-element tag <tag/> identifies elements with nocontent.

Overview of WML Developer’s Guide

NOKIA WAP TOOLKIT 9

The following table lists the WML tags supported in Nokia WAP Toolkit 1.2, bygeneral category. Most of the elements are discussed later in this guide. For detailson all elements, refer to the WML Reference.

Category WML elements

Deck and cards wmlcardtemplateheadaccessmeta

Events doontimeronenterforwardonenterbackwardonpickoneventpostfield

Tasks goprevrefreshnoop

Variables setvar

User input inputselectoptionoptgroupfieldset

Anchors, images, and timers aanchorimgtimer

Text formatting brptabletrtd


10 NOKIA WAP TOOLKIT

Attributes

Many WML elements allow you to include attributes in them. Attributes specifyadditional information for an element. You always specify attributes in the start tagof an element, using the following syntax:

<tag attribute1="value1" attribute2="value2" attribute3="value3"...>

You separate each option-value pair by white space, which may be a tab, newline,carriage return, or space character. You must enclose the value in double quotationmarks (").

Note that attribute names must be lowercase.

Some attributes are mandatory. For example, the go element requires the hrefattribute:

<go href="http://www.acme.com"/>

Other attributes are optional and may have default values. For example, the alignattribute is optional for the img element. If you do not specify the align attribute,its value defaults to bottom.

For more detailed information on the WML attributes, refer to the WML Referenceincluded in the Nokia WAP Toolkit.

Comments

WML comments follow the XML commenting style and have the following syntax:



Comments are intended to be used by the WML author and are not displayed tothe user by the user agent. Note that WML comments cannot be nested.

Variables

Parameters can be set for WML cards and decks using variables. To substitute avariable into a card or deck, the following syntaxes are used:

$identifier$(identifier)$(identifier:conversion)

Parentheses are required if white space does not indicate the end of a variable.Variable syntax has the highest priority in WML, that is, anywhere the variablesyntax is legal, an unescaped ‘$’ character indicates a variable substitution. Variablereferences are legal in any PCDATA and in any attribute value identified by the vdataentity type.

Overview of WML Developer’s Guide

NOKIA WAP TOOLKIT 11

Case sensitivity

XML is a case-sensitive language, and WML has inherited this characteristic. Nocase folding is performed when parsing a WML deck. This implies that all WMLtags, attributes and contents are case sensitive. In addition, any enumeratedattribute values are case sensitive.

For example, the following attribute values are all different:

n id="Card1"

n id="card1"

n id="CARD1"

WML structure

A valid WML deck is a valid XML document and therefore must contain an XMLdeclaration and a document type declaration:

<?xml version="1.0"?>

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

A WML deck begins and ends with the wml element, and all other elements come inbetween these start and end tags:

<wml>

...all other elements...</wml>

The following is a simple WML deck containing a single card. Note that the linenumbers are used for reference purposes only and are not part of the actual code.

<?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="First_Card" title="First Card"> 

<p> 

The first WML example 

</p> 

</card> </wml> 

The following is a line-by-line explanation of this example:

8 The first line specifies the XML version number.

9 The second line specifies the SGML public document identifier.

10 The third line specifies the location of the WML document type definition(DTD). The DTD can be located in the network, or you can store it locally tomake accessing it faster. The Nokia WAP Toolkit includes the DTD filewml.xml, found in the directory <installation directory>\dtd.



4 The fourth line is the root element of the XML document of which there mayonly be only one and it must match the root element name as indicated in thefirst argument of the document type. All WML documents must begin with a<wml> tag.

5 The following lines define a card containing a start and an end tag and text tobe displayed to the user.

! Note: The id attribute values cannot contain spaces.

10 All WML decks must end with a </wml> tag.

When a user agent loads the deck, it is displayed as shown below.

A WML deck with a single card.


Working with WMLelements

This chapter discusses working with the different WML elements to build simplecards and decks.

As explained in the previous chapter, the basic unit of WML is the card and cardsare grouped together into decks. A single WML card can contain a large amount ofinformation. In this case, the user must scroll down to see the missing lines.However, we recommend that you divide the information into multiple cards.

This chapter explains how to handle multiple cards and discusses specific WMLelements you’ll need to know about to follow the examples. For more details on theelements discussed here, refer to the WML Reference.


WML elements

You use WML elements to create the various components of a card. You mighthave a component that creates a connection between one document and another, orbetween one part of a document to another part. This type of component is called alink. Or, you might need a component that is simply part of getting a job done.This type of component is called a task.

WML elements fall into different categories to handle these different components,as explained in the following sections.

Deck and cards

The following table briefly explains the elements you use to define the cards withina deck.

Element Explanation

wml Defines a deck and encloses all the informationand cards in the deck.

card Indicates the general layout and user schemes in

Developer’s Guide Working with WML elements


Element Explanation

the user agent. (See “card element” on page 14.)

template Declares a template for cards in the deck. (See“Using the template element” on page 24.)

head Contains information relating to the deck as awhole, including meta-data and access controlelements.

access Specifies access control information for the entiredeck.

meta Contains generic meta information relating thedeck.

card element

The following is a simple card element example:

<card id="card_name" title="title">

<p>

Text containing <i> information </i>.

</p>

</card>

Component Explanation

<card> The start tag of a card. One WML deck cancontain several cards.

id="card_name" Specifies a name that allows you to navigate to thecard from other cards in the same deck.

title="title" Specifies advisory information on the card.

<p> Specifies a paragraph.

<i> Specifies italic text emphasis.

Working with WML elements Developer’s Guide


The following table lists other attributes of the card element. For more detailedinformation on the attributes of the card element and how to use it, refer to theWML Reference included in the Nokia WAP Toolkit.

Attributes Explanation

newcontext="false" If you set this attribute to true, the browsercontext is re-initialized upon entry to this card.The browser context is used to manage allparameters and user agent states, includingvariables, the navigation history and otherimplementation-dependent information related tothe current state of the user agent.

ordered=boolean Gives an indication to the user agent about howthe card content is organized.

onenterforward="href" Navigates to the location specified by href.Occurs when the user navigates into a card using ago task.

onenterbackward="href" Navigates to the location specified by href.Occurs when the user navigates into a card using aprev task.

ontimer="href" Navigates to the location specified by href after aspecified amount of time.

xml:lang Specifies the natural or formal language in whichthe document is written.

id Provides an element with a unique name within asingle deck.

class Affiliates an element with one or more classes.

! Note: The Nokia WAP Toolkit 1.2 software does not support theordered="boolean" attribute.



Events

You use the events elements to handle navigation and functions.

The following table briefly explains when you use these elements.

Element Explanation

do Provides a general mechanism forperforming actions on the current card.

ontimer Specifies an intrinsic event that occurswhen a timer expires.

onenterforward Specifies an intrinsic event that occurswhen the user enters a card underspecific circumstances.

onenterbackward Specifies an intrinsic event that occurswhen the user navigates into a card byusing an URI retrieved from the historystack (see “History stack” on page 26).

onpick Specifies an intrinsic event that occurswhen the user selects or deselects anitem in which the event is specified.

onevent Binds a task to a particular intrinsicevent.

postfield Specifies a field name and value fortransmission to an origin server duringan URI request.

do element

A card element can contain do elements that assign a task to a certain key. For adescription of the available task elements, see “Task elements” on page 17. Thefollowing is a simple example of how to use the do element:

<do type="tasktype" label="label" name="name" optional="false">


<do> The start tag of the do element. Do elements mayappear inside a card and template. Note that youmay specify only one task for one do element.

type="tasktype" Specifies the type of task to execute. For example,accept navigates to the next card, and prev




returns to the previous card. For a complete list ofthe available types, refer to the WML Reference.

The type attribute is required.

label="label" Specifies the label for the soft key.

name="name" Specifies the name of the do task binding.

optional="false" If you set this attribute to true, the user agent mayignore this element.

See also “Example deck” on page 21. For more detailed information on theattributes of the do element and how to use it, refer to the WML Reference.

Task elements

A do element can contain tasks that specify what the user agent is to do when theuser activates a task by pressing a key or navigating to a card or deck, for example.The go, prev, noop and refresh tasks of WML are described in the followingtable. For more information on WML tasks and how to use them, refer to theWML Reference.

Task Explanation

go Indicates navigation to a location specified byhref. If the href names a WML card or deck, it isdisplayed.

prev Indicates navigation to the previous URI in thehistory stack (see “History stack” on page 26).

refresh Indicates an update of the user agent context asspecified by the setvar tags (see “Variables ” onpage 19).

noop Indicates that nothing should be done.



go task

The go task indicates navigation to location specified by an href. If the href namesa WML card or deck, it is displayed. The following is a simple example of how touse the go element.

<go href="#card2"/>


<go> Start tag of a go element, indicating navigation to ahref.

href="href" Specifies the destination, for example, the locationof the card to display. This attribute is required.

The following table lists other attributes of the go element. For more detailedinformation on the attributes of the go task and how to use it, refer to the WMLReference.

Attribute Explanation

sendreferer=boolean If you set this attribute to true, the user agentincludes the deck URL in the HTTP request.

method="post|get" Specifies the HTTP submission method.Currently, the values of get and post are acceptedand cause the user agent to perform an HTTP getor post respectively.

accept-charset="chset" Specifies the list of character encodings for datathat the web server must accept when processinginput. The default value is unknown. The useragent uses the character encoding that was used totransmit the WML deck containing this attribute.





prev task

The prev element declares a prev task, indicating navigation to the previous URIon the history stack. A prev performs a pop operation on the history stack (see“History stack” on page 26).

The following table lists attributes of the prev element. For more detailedinformation on the attributes of the prev task and how to use it, refer to the WMLReference.




refresh task

The refresh element declares a refresh task, indicating an update of the useragent context as specified by the setvar element (see “Setting variables” on page28). Side effects of the state changes that are visible to the user (for example, achange in the screen display) occur during the processing of the refresh task.

For more detailed information on the the refresh task and how to use it, refer tothe WML Reference.

noop task

The noop element specifies that nothing should be done, that is, “no operation”.You will find this a useful element when you want to override template action (see“Using the template element” on page 24).

For more detailed information on the noop task and how to use it, refer to theWML Reference.

Variables

Parameters can be set for all WML content, giving you a great deal of flexibility increating cards dynamically change display content and navigation based on userinput. WML variables can be used instead of strings; their current value issubstituted at runtime.

You use the setvar element to specify a variable. See “Variables and dynamicinterfaces” on page 27.



User input

You use the user input elements to handle user input in WML.

The following table briefly explains when you use these elements. See “User input”on page 31 for more information.

Element Use

input Specifies a text entry obect.

select Allows the user to choose from a list ofoptions. WML supports both single-choice and multiple-choice lists.

option Specifies a single choice option in aselect element.

optgroup Lets you group related option elementsin a hierarchy to facilitate layout andpresentation by the user agent.

fieldset Lets you group related fields and text.

Anchors, images, and timers

The following table briefly explains when you use the elements in this category.

Element Use

anchor Specifies the beginning of a connectionbetween one document and another, orbetween one part of a document andanother part of the same document. See“Using links” on page 39.

a Provides a short form of the anchorelement. See “Using links” on page 39.

img Places images into the text flow.

timer Implements a card time that can be usedto process inactivity or idle time. See“Using timer” on page 40.



Text formatting

You use the text formatting elements to format any text in the card.

The following table briefly explains when you use these elements. See “Displayingtext” on page 43 for more information.

Element Use

br Establishes the beginning of a new line.

p Establishes both the line wrap andalignment parameters for a paragraph.

table Creates sets of aligned columns of textand images in a card.

tr Used with the table element, indicatesa container to hold a single table row.

td Used with the table element, indicatesa container to hold a single table celldata within a table row.

In addition, you can use the emphasis tags to specify text emphasis markupinformation, as explained in “Emphasis” on page 43.

Example deck

The following WML illustrates a deck containing two cards. When the user pressesthe ACCEPT soft key labeled “Next,” the user agent navigates to the second cardof the deck and displays its content.

Note that the line numbers are used for reference purposes only and are not part ofthe actual code.

<?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="First_Card"> 

<do type="accept" label="Next"> 

<go href="#Second_Card"/> 

</do> 

<p> 

Select <b>Next</b> to display the next card. 

</p> </card> 



<card id="Second_Card"> 

<p> 

This card contains the following:... 

</p> 

</card> 

</wml> 

In the user agent, the above WML generates the following interface:

A deck containing two cards.

The following is a line-by-line explanation of this example:

1 The first three lines identify the XML subset. This identification must beincluded at the beginning of every WML deck, that is, before every <wml> tag.

4 The fourth line is the top-most element of the WML deck. All WML decksmust begin with a <wml> tag and end with a </wml> tag.

5 The fifth line of the deck is the top-most element of the first card. Like decks,cards require begin and end tags, for example, <card> and </card>.

Most WML elements allow you to specify attributes. Attributes are entered inthe form attribute=value, where attribute is the attribute name andvalue is an alphabetic or numeric value that you specify.

6 The sixth line defines an action, which specifies what the user agent should dowhen the user presses a specified function key. The type attribute identifies thekey (accept) and the label attribute a label name (Next) for the specified key.

7 The seventh line specifies the action related to the specified key. The hrefattribute identifies the target href destination, for example, the card namedcard2.



Multiple cards in multiple decks

You are not required to put all the cards used by one of your services in a singledeck. It is recommended that you limit the size your decks, since different useragents have different memory restrictions. Contact your vendor to find out whatthe limitations of your user agent are, and take them into consideration whencreating your own WML decks.

For example, the deck2a.wml and deck2b.wml files provided with the NokiaWAP Toolkit demonstrate dividing content onto multiple decks and cards.

Deck2a.wml contains a template that defines a backward navigating task. In card1the template task is overridden with a no-operation task. The third card includes ago task that specifies the URL of the deck2b.wml. When the user activates the gotask, the user agent navigates to the deck and displays its content.

Note that this example uses the template element. See “Using the templateelement” on page 24 for more information about this element.


<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"

"http://www.wapforum.org/DTD/wml_1.1.xml">

<wml>

<template>

<do type="prev" name="Previous" label="Previous">

<prev/>

</do></template>

<card id="card1" title="First Card" newcontext="true">

<p>

Card 1 ... <br/>

<do type="accept" label="Next Card">

<go href="#card2"/></do>



<do type="prev" name="Previous">

<noop/></do>

</p>

</card>

<card id="card2" title="Second Card">

<p>



Card 2 ... <br/>

<do type="accept" label="Next Card">

<go href="#card3"/></do>

</p>

</card>

<card id="card3" title="Third Card">

<p>

Card 3 ... <br/>



<do type="accept" label="Next Deck">

<go href="deck2b.wml"/></do>

</p>

</card>

</wml>

Using the template element

You can define do elements at several levels in WML. The examples in the previoussections define them at the card level. However, you can also define them at thedeck level by using the template element. A do element’s scope covers the wmlelement in which it is defined. If you define it in a deck’s template, it applies to thewhole deck—if you define it in a card, it applies only to that individual card.

Note that when a do element appears inside another element, the element with thenarrower scope takes precedence.

You can include the following elements in a template:

n do

n onevent

n onenterforward

n onenterbackward

n ontimer

In the following example, a deck-level do element indicates that a prev task shouldexecute on receipt of a particular user action.

n The first card inherits the do element specified in the template and will displaythe do to the user.



n The second card overrides the deck-level do element with a noop. The useragent will not display the do element when displaying the second card.

n The third card does not override the deck-level do element because it uses adifferent name attribute.

<wml>

<template>

<do type="options" name="Prev" label="Previous">

<prev/>

</do>

</template>

<card id="First_Card">

<do type="accept" name="Next" label="Next">

<go href="#Second_Card"/>

</do>



<p>

Card 1



...

</p>

</card>

<card id="Second_Card">

<do type="accept" name="Next" label="Next">

<go href="#Third_Card"/>

</do>



<do type="options" name="Prev">

<noop/>

</do>

<p>

Card 2


...</p> </card>

<card id="Third_Card">



<do type="options" name="do1" label="options">

<go href="/options"/>

</do>

<p>

Card 3


...

</p>

</card>

</wml>



History stack

You can view the history stack of the Nokia WAP Toolkit by clicking the Historytab at the bottom of the simulator application window. The following figure showsan example of a history stack.

Example of a history stack.

Note the following:

n The last card visited appears at the top of the stack. When you navigate to anew card, the URL of that card appears at the top of the stack.

n This view shows the history stack of the current browser context only. Eachtime the browser context is re-initialized, the history stack is cleared.

n The size limit indicates the history stack size. This is a preference and you canchange this size under the General tab of the Preference window (see GettingStarted for more information on Preferences).

n You can clear the history stack manually by clicking Clear.

n You can navigate to the selected card by clicking Go.



Variables and dynamic interfaces

This section discusses how you can set variables explicitly and substitute variablesinto WML.

Naming variables

WML variable names consist of an US-ASCII letter or underscore followed by azero or more letters, digits or underscores. Any other characters are illegal. Notealso that variable names are case-sensitive. Parentheses are required anywhere theend of a variable cannot be inferred from the surrounding context, for example, ifthe variable ends with an illegal character such as a white space. The followingexamples demonstrate legal variables:

This is a $var

This is another $(var).

This is an escaped $(var:e).

Long form of escaped $(var:escape).

Long form of unescape $(var:unesc).

Short form of no-escape $(var:N).Other legal variable forms: $_X $X32 $Test_9A

A side effect of the parsing rules is that the literal dollar sign must be encoded witha pair of dollar sign entities. A single dollar sign entity, even when specified as$, results in a variable substitution.

In order to include a $ character in a WML deck, it must be explicitly escaped byusing the following syntax:

$$

Two dollar signs in a row are replaced by a single $ character. For example:

This is a $$ character.

would be displayed as:

This is a $ character.

To include the $ character in URL-escaped strings, specify it with the URL-escapedform %24.

! Note: Variable names are case sensitive. This means that variable1,Variable1 and varIABle1 are all different variables.



Setting variables

There are a number of ways to set the value of a variable. When a variable is set andalready defined in the browser context, the current value is updated.

The setvar element allows you to set the variable state as a side effect ofnavigation. VAR may be specified in the following task elements:

n go

n prev

n refresh

Variables can also be set in the following situations:

n Input elements set the variable identified by the name attribute to anyinformation entered by the user.

— The input element assigns the entered text to the variable.

— The select element assigns the value present in the value attribute of thechosen option element.

Note that the user input is written to variables when the user commits the input tothe input or select element.

The VAR element specifies a variable name and value, for example:

<setvar name="location" value="$(X)"/>

The variable name specified in the name attribute (for example, location) is set as aside effect of navigation.

Note the following when setting variables:

n You can change variable values set with WML using WMLScript and viceversa, meaning that WML and WMLScript use the same variables.

n You can set and edit variables in the Nokia WAP Toolkit Variables view.

n You can use the newcontext attribute to clear all the variable values of thecurrent browser context.



Substituting variables

Variable values can be substituted into formatted text, option values and URLattributes in WML elements. However, note that only textual information can besubstituted, that is, no substitution of elements or attributes is possible. Thesubstitution of variable values happens at runtime in the user agent. As thesubstitution is merely a string substitution operation, it does not affect the currentvalue of the variable. If an undefined variable is referenced, it results in thesubstitution of the empty string.

The following table describes how you can substitute variable values.

Variable reference Explanation

$var or$(var)

Value of var is substituted using the conversionformat appropriate for the context.

$(var:e) or$(var:escape)

Value of var is substituted using URL-escaping.

$(var:unesc) Value of var is substituted using URL-unescaping.

$(var:N) or$(var:noesc)

Value of var is substituted without changing thevalue of the variable.

Note that the use of a conversion during variable substitution does not affect theactual value of the variable.

If no conversion is specified, the variable is substituted using the conversion formatappropriate for the context. The onenterbackward, onenterforward, href andsrc attributes default to escape conversion; elsewhere, no conversion is done.Specifying the noesc conversion disables context-sensitive escaping of a variable.

For more detailed information on the variable substitution syntax, refer to theWML Specification.

Variable example

The following example demonstrates the use of tasks and variables in WML decksand cards. Note that the variables will not be set until the user navigates to thesecond card of the deck.

<wml>

<card id="card1" title="First Card" newcontext="true">

<p>

Card 1 Contents... <br/>



card1 var1 = $(card1_var1) <br/>


</p>



<do type="accept" label="Next">

<go href="#card2">

<setvar name="card1_var1" value="val_1"/>

</go>

</do>

</card>

<card id="card2" title="Second Card">

<onevent type="onenterforward">

<refresh>

<setvar name="card2_var1" value="val_2"/>

</refresh>

</onevent>

<p>

Card 2 Contents... <br/>


card2 var1 = $(card2_var1) <br/></p>

<do type="prev" label="Previous">

<prev/>

</do>

</card>

</wml>

When you navigate to the first card of the deck, the following user interface isdisplayed:

Variables with no values.

n Note that the variables have not yet been set.

n When you press Options to navigate to the second card, the variablecard1_var1 is set.

n Upon entry to the second card, the variable card2_var1 is set and the browsercontext is refreshed. Now the user agent displays the following user interface:

Variables with values.



User input

WML includes two interactive card elements: input and select. The followingsections describe how you can use them to prompt the user for input and how tohandle the input. For more information on text input and select lists, refer to theWML Reference.

input element

The input element specifies a text entry object. You can determine the format ofthe string the user enters and place default text in the entry field.

The following is a simple example of how to use the input element:

<card>

Entry: <input name="varname" default="default" format="fmt"

emptyok="boolean" size="input_size" maxlength="max_char"/></card>


<input> The start tag of the input element.

Entry The prompt text the card displays to the user.

name="varname" Specifies the name of the variable to set with theresult of the user’s text input. This attribute isrequired.

default="default" Specifies the default that appears in the entry field.

format="fmt" Specifies an input mask for user input entries. Thedefault format allows the user to enter anycharacter. For detailed information on theavailable format control characters, see “Specifyingthe character format” on page 34.

emptyok="boolean" If you set emptyok to true, the input elementaccepts empty input although a format string thatis not empty has been specified. The default isfalse.

size="input_size" Specifies the width, in characters, of the text inputarea.

maxlength="max_char" Specifies the maximum number of characters thatthe user can enter in the text entry area. Thedefault is unlimited.

tabindex="number" Specifies the tabbing position of the input field.The tabbing position indicates the relative order inwhich elements are traversed when tabbing withina single WML card.



The following table lists other attributes of the input element. For more detailedinformation on the attributes of the input element and how to use it, refer to theWML Reference.


value="value" Specifies the value of the variable named in thename attribute. The default and value attributesare identical in their behavior and syntax.

type="input_type" Specifies the type of the text input area. Theallowed values are text and password. In texttype, input is displayed to the user in a readableform. In password type, input of each character isechoed in an obscured form. Note that passwordinput is insecure and critical application shouldnot be dependent on it. The default type is text.

title="title" Specifies a title for the input element. The titlemay be used in the presentation of this object.




The following deck defines a card requesting the user to enter a name and a carddisplaying the name entered.

<wml>

<card id="Card_1" title="Card 1">

<do type="accept">

<go href="#Card_2"/>

</do>

<p>

Enter your name: <input name="username"/>

</p>

</card>

<card id="Card_2" title="Card 2">

<p>

Hello $(username)!

</p>

</card>

</wml>



This deck generates the following interface in the user agent (as shown on a 6150model phone):

Text entry card.

The deck operates as follows:

1 When you navigate to the card, the prompt asks you to enter your name. PressOptions to see the selections. Press Select to go to input card.

2 In the input card that appears, enter your name by using your computerkeyboard or the keypads of the simulator phone. When you are done, pressOK.

3 The first card appears again, with the name you entered. Press OK to go to thesecond card of the deck.

The name attribute specifies a variable name to which the phone stores the text thatthe user enters in the text entry field. To substitute a variable value at runtime, youmust add a dollar sign ($) in front of the variable name.



Specifying the character format

With the format attribute you can specify the character format in which the usercan enter text input. The following special characters are available:

Character Explanation

A Allows any upper-case alphabetic or punctuationcharacter, that is, upper-case non-numericcharacter.

a Allows any lower-case alphabetic or punctuationcharacter, that is, lower-case non-numericcharacter.

N Allows any numeric character.

X Allows any upper-case character.

x Allows any lower-case character.

M Allows any character. The user agent may chooseto assume that the character is upper-case for thepurposes of simple data entry, but must allowentry of any character. This is the default format.

m Allows any character. The user agent may chooseto assume that the character is lower-case for thepurposes of simple data entry, but must allowentry of any character.

*f Allows any number of characters; f is one of theabove format codes and specifies what kind ofcharacters can be entered. Note that this formatcan only be specified once and must appear at theend of the format string.

nf Allows n characters where n is a number from 1 to9; f is one of the above format codes and specifieswhat kind of characters can be entered. Note thatthis format can only be specified once and mustappear at the end of the format string.



Character Explanation

\c Displays the next character, c, in the entry field.Allows quoting of the format codes so they can bedisplayed in the entry area.

For example, let us suppose that you use theformat specifier $3N$. This instructs the useragent to automatically insert a left parenthesisbefore the user has entered anything, and a rightparenthesis after the user has entered three digits.

The following example is a card that prompts the user for a first name, last nameand age. Note that in the Age field the user can enter a two-digit number.

<card>

<p>

First name: <input type="TEXT" name="first"/><br/>

Last name: <input type="TEXT" name="last"/><BR/>

Age: <input type="TEXT" key="age" format="NN"/>

</p>

</card>

select element

A select list specifies a list of options that the user can choose from. WML supportsboth single-choice and multiple-choice lists.

The following is a simple example of how to use the select element:

<card id="card1" title="Currency" newcontext="true">

<p>

Amount: <input format="*N" name="amount" title="Amount:"/>

<select name="from" value="USD" title="From:">

<option value="DEM">German Mark</option>

<option value="FRF">French Franc</option>

<option value="FIM">Finnish Markka</option>

<option value="USD">US Dollar</option></select>

<select name="to" value="FIM" title="To:">




<option value="USD">US Dollar</option>

</select>

<br/>= <u>$(conversion)</u>

<do type="accept" label="Calculate">

<go href="currency.wmls#convert(’conversion’,

’$(from)’,’$(to)’,$(amount))"/></do>



<do type="help" label="Help">

<go href="#card1_help"/>

</do>

</p>

</card>


<select> Start tag of the select element.

multiple="boolean" If you set this attribute to true, the select listaccepts multiple selections. When the attribute isnot set, the select list accepts only a single selectedoption. The default value is false.

name="varname" The name of the variable that receives the value ofthe chosen item.

default="default" The default value of the variable specified by thename attribute. If the name variable alreadycontains a value, the name attribute is ignored.

title="title" A title for the select element, which can be usedin the presentation of this object.

The following table lists other attributes of the select element. For more detailedinformation on the attributes of the select element and how to use it, refer to theWML Reference.


iname="varname" The name of the variable that is set with the indexresult of the user selection. When the user selectsan item, the user agent sets the variable specifiedby iname to the number of the chosen item. Thenumber 1 specifies the first item, the number 2 thesecond item, and so on. The number 0 indicatesthat no option is selected.

ivalue="default" The index of the option element selected bydefault. If the variable specified by the inameattribute is not set when the card is displayed, it isassigned the entry selected by default. If thevariable already contains a value, the ivalueattribute is ignored.

tabindex="number" Specifies the tabbing position of the input field.The tabbing position indicates the relative order inwhich elements are traversed when tabbing withina single WML card.







Single-choice list

The following example illustrates a simple single-choice list with a default value.Note the following:

n The “dog” option would be pre-selected if the “I” variable had not beenpreviously set.

n If the user were to choose the “cat” option, the variable “I” would be set to avalue of “2”.

<wml>

<card>

<p>

Please choose your favorite animal:

<select iname="I" ivalue="1">

<option value="D">Dog</option>

<option value="C">Cat</option>

</select>

</p>

</card>

</wml>


A card with a single-choice list.



Multiple-choice list

The following example specifies a multiple-choice list. Note the following:

n The “dog” and “cat” options would be pre-selected if the variable “I” had notbeen previously set.

n If the user were to choose the “cat” and “horse” options, the variable “X”would be set to “C;H” and the variable “I” would be set to “2;3”.

<wml>

<card>

<p>

Please choose <i>all</i> of your favorite animals:

<select name="X" iname="I" ivalue="1;2" multiple="true">

<option value="D">Dog</option>

<option value="C">Cat</option>

<option value="H">Horse</option>

</select>

</p>

</card>

</wml>


A card with a multiple-choice list.



Using links

The anchor and a elements specify the head of a link. The tail of a link is specifiedas part of other elements, for example, a card name attribute. Note that it is a WMLsyntax error to nest anchored links.

You can use anchors anywhere formatted text is legal, except for option elements.

An anchored link must have an associated task that specifies the behavior when theanchor is selected. You must anchor one of the following task elements to a link:

n go

n prev

n refresh

Note that it is a WML syntax error to specify more than one task in either ananchor or a element.

The following is a simple example of how to use the anchor element:

<card id="name" title="title">

<p>

Normal text and a

<anchor title="link_title">link!

<go href="url"/>

</anchor>

</p>

</card>


<anchor> Specifies the head of a link.

<go> Specifies a task binding to the link.

title="link_title" Specifies a brief text string identifying the link.For it to work well with a broad range of useragents, keep your labels under 6 characters.

For more detailed information on the anchor and a elements and how to use them,refer to the WML Reference.



Link example

The following WML deck includes a link to the file.wml. When the user activatesthe link, the user agent navigates to the file.wml and sets the specified variable.

<wml>

<card id="links" title="Links">

<p>

This is normat text, but here is a

<anchor title="LINK">link!

<go href="dir/file.wml">

<setvar name="var_name" value="var_value"/>

</go>

</anchor>

</p>

</card></wml>

The deck generates the following user interface in the user agent:

A card containing a link.

Using timer

The timer element implements a card timer, which can be used to processinactivity or idle time. The timer is initialized and started at card entry and stoppedwhen the card is exited. The value of a timer will decrement from the initial value,triggering the delivery of an ontimer event when the timer reaches the value zero.It is a WML syntax error to have more than one timer in a card.

The timeout value is specified in units of one-tenth (1/10) of a second. However,note that you should not expect a particular timer resolution.

The following is a simple example of how to use the timer element:

<card id="cardname" ontimer="/next">

<timer name="key" value="50"/><p>

Hello World!

</p>

</card>


<timer> Start tag of the timer element.




ontimer="/next" Specifies an intrinsic event that instructs the useragent to go to the URL /next after the timer hasexpired.

name="name" Specifies the name of the variable to be set withthe value of the timer. The variable named by thename attribute will be set with the current timervalue when the card is exited or when the timerexpires.

value="50" Specifies the timeout value in units of one-tenth ofa second. This attribute indicates the default valueof the variable named in the name attribute. Thisattribute is required.

Note the following:

n Each time the card of the example above is entered, the timer is reset to thevalue of the variable key.

n If name is not set, the timer is set to a value of 5 seconds.

n The text “Hello World!” is displayed for five seconds, after which the useragent goes to the URL /next.

For more detailed information on the attributes of the timer element and how touse it, refer to the WML Reference.

Intrinsic events

Several WML elements can generate events when the user interacts with them.These intrinsic events indicate state transitions inside the user agent. WML includesfour intrinsic events described in the following table.

Event Element(s) Description

ontimer card,template

The ontimer event occurs when a timerexpires. You can specify a timer using thetimer element.



Event Element(s) Description

onenterforward card,template

The ontenterforward event occurs whenthe user enters a card using a go task or anymethod with identical semantics.

The ontenterforward intrinsic event maybe specified at both the card-level and deck-level. Event bindings specified in thetemplate apply to all cards in the deck andcan be overridden.

onenterbackward card,template

The onenterbackward event occurs whenthe user navigates into a card using a prevtask or any method with identicalsemantics. In other words, theonenterbackward event occurs when theuser navigates into a card by using an URLretrieved from the history stack.

The onenterbackward intrinsic event maybe specified at both the card-level and deck-level. Event bindings specified in thetemplate apply to all cards in the deck andcan be overridden.

onpick options The onpick event occurs when the userselects or deselects this item.

You can specify that certain tasks are to be executed when an intrinsic event occursin two ways.

First, you can specify an URL to be navigated to when the event occurs. This eventbinding is specified in a well-defined element-specific attribute, which is theequivalent of a go task. For example:

<card onenterforward="/url"> Hello </card>

Second, you can use an expanded version of the method above, which gives youmore control over user agent behavior. An onevent element is implemented withina parent element, specifying the full event binding for a particular intrinsic event.For example, the following is identical to the previous example:

<card>


<go href="/url"/>

</onevent>

<p>

Hello

</p>

</card>



However, the user agent treats the attribute syntax as an abbreviated form of theonevent element where the attribute name is mapped to the onevent type.

Displaying text

The following sections introduce the text formatting elements of WML.

Emphasis

The emphasis tags specify text emphasis markup information. The emphasis tags areexplained in the following table.

Tag Explanation

em Render with emphasis.

strong Render with strong emphasis.

i Render with an italic font.

b Render with a bold font.

u Render with underline.

big Render with a large font.

small Render with a small font.

Use the strong and em tags where possible. It is not recommended to use the b, iand u tags except where explicit control over text presentation is required.



Text format example

The following WML illustrates the use of text emphasis tags.

<wml>

<card id="card1">

<p>

<em>

A

<u>

Demonstration

</u>

of Nokia’s

<i>

<strong> Wireless Application Protocol<br/> </strong>

</i>

<b> Toolkit</b>

</em>

</p>

</card>

</wml>

When displayed, this card generates the following user interface:

Card with text formatting.

Note that the user agent can only display a few lines at a time and so you mustscroll down through the display to see the last lines of the card.

Line breaks

To start a new line in display text, simply insert a <br/> tag where you want tostart the line. Note that adding a carriage return or line feed has no effect: the WMLcompiler treats it as a single space.

Text wrapping and alignment

The p element establishes both the line wrap and alignment parameters for aparagraph. WML has two line-wrapping modes for visual user agents: breaking (orwrapping) and non-breaking (or non-wrapping). The current line wrap modecontrols how lines too long to fit on the screen are treated.

n If mode="wrap" is specified, the line is word-wrapped onto multiple lines. Inthis breaking mode, line breaks should be inserted into a text flow asappropriate for presentation on an individual device, and any space betweenwords is a legal line breaking point.



n If mode="nowrap" is specified, the line is not automatically wrap. In this non-breaking mode, the user agent must provide a mechanism to view entire non-wrapped lines (horizontal scrolling, for example, or some other user-agent-specific mechanism.

Any space between words is a legal line break point. The non-breaking space entity( or ) indicates that the user agent must not treat the space as a spacebetween words. It is recommended that you use to prevent unwanted linebreaks. The soft-hyphen character entity ( or &#173) indicates a location thatmay be used by the user agent for a line break. If a line break occurs at a soft-hyphen, the user agent inserts a hyphen character (-) at the end of the line. Inall other operations, the soft-hyphen entity is ignored. Note also that a user agentmay ignore soft-hyphens when formatting text lines.

The p tag establishes both the new wrap and alignment parameters for a paragraph.If the wrap mode is not specified, it is identical to the line–wrap mode of theprevious paragraph in the current card. If the text alignment is not specified, itdefaults to left.

Empty paragraphs, such as an empty element or an element with only insignificantwhite space, should be considered as insignificant and ignored by visual user agents.Insignificant paragraphs do not impact line-wrap mode. If the p element in a carddoes not specify a line-wrap or alignment mode, that mode defaults to the initialmode for the card. The user agent must insert a line break into the text flowbetween significant p elements.

table element

You can use the table element, with the tr and td elements, to create sets ofaligned columns of text and images in a card. The table elements determine thestructure of the columns. The elements separate content into columns, but do notspecify column or intercolumn widths. The user agent does its best effort to presentthe information of the table in a manner appropriate to the device. Note that youcannot nest table elements.

The alignment of the text and images within a column is specified by the alignattribute. You can align the contents of a column center, left, or right. The alignattribute value is interpreted as a list of alignment designations, one for eachcolumn. You specify center alignment with the value “C”, left alignment with thevalue “L”, and right alignment with the value “R”. The first designator in the listapplies to the first column, the second designator to the second column, and so on.The default alignment is applied for any column for which an alignment designationis omitted. For left-to-right languages, the default alignment is left. For right-to-leftlanguages, the default alignment is right.

You must use the columns attribute to specify the number of columns for the rowset. The user agent must create a row set with exactly the number of columnsspecified by the columns attribute value. If the actual number of columns in a rowis less than the value specified in the columns attribute, the row must be effectivelypadded with empty columns. The orientation of the table depends on the language:for left-to-right languages, the leftmost column is the first column in the table.



Columns are added to the right side of a row to pad left-to right tables. Columnsare added to the left side of a row to pad right-to left tables.

If the actual number of columns in a row is greater than the value specified by thecolumns attribute, the extra columns of the row must be aggregated into the lastcolumn, such that the row contains exactly the number of columns specified. Asingle inter-word space must be inserted between two cells that are beingaggregated.

Depending on the display characteristics, the user agent may create aligned columnsfor each table, or may use a single set of aligned columns for all tables in a card. Toensure the narrowest display width, the user agent should determine the width ofeach column from the maximum width of the text and images in that column. Anon-zero width gutter must be used to separate each non-empty column.

The following example contains a card with a single column group, containing twocolumns and three rows.

<wml>

<card>

<p>

<table columns="2" align="L">

<tr><td>One </td><td> Two </td></tr>



<tr><td>1</tr>



<tr><td/><td>B</td>C<br>D</td></tr>

</table>

</p>

</card>

</wml>


<table> The start tag of the table element.

<tr> Specifies a container to hold a single table row.Table rows may be empty (for example, all thecells in the row are empty). Empty rows aresignificant and must not be ignored.

<td> Specifies a container to hold a single table cell datawithin a table row. Table data cells may be empty.Empty cells are significant, and must not beignored. The user agent should do a best efrort todeal with multiple line data cells that may resultfrom using images or line breaks.

columns="2" Specifies the number of columns for the row set.

align="L" Specifies the layout of text and images within thecolumns of a row set.



For more detailed information on the table, tr, and td elements and how to usethem, refer to the WML Reference.

Special characters

WML supports both named and numeric character entities. Note that all numericcharacter entities are referenced with respect to the document character set(Unicode) and not to the current document encoding (charset). This means that thenotation { always refers to the same logical character, independent of thecurrent character encoding.

WML supports the following character entity formats:

n Named character entities, such as & and <

n Decimal numeric character entities, such as {

n Hexadecimal numeric character entities, such as

The following table illustrates the seven named character entities that areparticularly important in the processing of WML.

Entity Notation Explanation

quot " quotation mark

amp & ampersand

apos ' apostrophe

lt < less than

gt > greater than

nbsp non-breaking space

shy soft hyphen (discretionary hyphen)

To include a special character, simply use the escaped notation described in thetable above. For example, the following code includes a less than character (<) in theescaped form &#60.

<wml>

<card id="Card_1">

<p>

Numerically 5 < 10

</p>

</card></wml>



This would generate the following user interface:

Use of special characters.


WMLScript

This chapter discusses the features of the Wireless Markup Language Script(WMLScript) language and how to use them.

WMLScript is part of the WAP application layer, and you can use it to add clientside procedural logic to WML cards and decks. The language is based onECMAScript, but it has been modified to better support low bandwidth devicessuch as mobile phones.


Overview of WMLScript

The Wireless Application Protocol (WAP) includes WMLScript, a scriptinglanguage that you can use with Wireless Markup Language to provide intelligenceto the client services. WMLScript can also be used as a standalone tool.

With WMLScript, you can overcome the following limitations of WML:

n You can check the validity of user input.

n You can access facilities of the user agent. For example, on a mobile phone,allowing the programmer to make phone calls, send messages, add phonenumbers to the address book or access the SIM card.

n You can generate messages and dialogs locally, thus allowing alerts, errormessages, confirmations etc to be seen faster by the user.

n You can build extensions to the user agent software and configure a user agentafter it has been deployed.

For a detailed presentation of WMLScript, refer to the WMLScript Reference. Seealso the currency converter and mortgage calculation examples in the section“Example applications” on page 61.

Developer’s Guide WMLScript


WMLScript standard libraries

The following table briefly describes the WMLScript standard libraries. For moreinformation, refer to the WMLScript Reference.

Library Description

Float This library contains a set of typical arithmeticalfloating-point functions that are frequently usedby applications.

String This library contains a set of string functions.

URL This library contains a set of functions forhandling absolute URLs and relative URLs.

WMLBrowser This library contains functions that WMLScriptuses to access the associated WML context.

Dialogs This library contains a set of typical user interfacefunctions.

WMLScript non-standard libraries

WMLScript contains the non-standard debug library that contains a set ofdebugging functions. These functions help you debug script applications. For moreinformation, refer to the WMLScript Reference.

WML and WMLScript example

The next example illustrates a WML deck containing two cards and a separateWMLScript file:

n The first card (card1) calls the WML script random.wmls and requests thefunction getRandom that generates a random number.

n The second card (card2) shows the result of the WMLScript operation.

n The script file random.wmls generates a random number and returns the resultto the second card of the WML deck.

For more information on the WML elements and WMLScript functions of thisexample, refer to the WML Reference and WMLScript Reference.

WMLScript Developer’s Guide


WML code



<wml>

<card id="card1" title="Random Example">

<p align="center">

Select Random

</p>

<do type="accept" label="Random">

<go href="random.wmls#getRandom()"/>

</do>

</card>

<card id="card2" title="Random Result">

<p>

Result: $(RESULT)

</p></card>

</wml>

WMLScript code

The script does the following:

n Generates a random number between 0 and 100. The random number is storedin the variable r.

n Sets the variable RESULT with the random value r.

n Sends the result to card2 of the WML file random.wml and refreshes itsvariable values.

extern function getRandom () {

var r = Lang.random(100);

WMLBrowser.setVar("RESULT", r);

WMLBrowser.go("random.wml#card2");}

Developer’s Guide WMLScript



Security

This chapter discusses the security issues of WML services, and provides anoverview of how to create WML services so that security risks are minimized.


Access element

When you specify an URL, you gain access to all the variables it uses. To give youcontrol over this potential security risk, WML supports access control performedwith the access element.

You can use the access element in the deck header to specify access control for theentire deck.

The following is a simple example of how to use the access element:

<wml>

<head>

<access domain="domain" path="path"/>

</head>

<card id="card1">

<p>

Card content

</p>

</card></wml>


<head> Start tag of a head element. A head element cancontain an access and a meta element.

<access> Start tag of an access element.

domain="domain"path="path"

A deck’s domain and path attributes specify theother decks that can access it.

Developer’s Guide Security


n For example, given the following access control attributes:domain="acmecorp.com"path="/pub"

— The following decks would be allowed to access this deck:acmecorp.com/pub/stocks.cgiwww.acmecorp.com/pub/demos/packages.cgi

— The following decks would not be allowed to access this deck:www.test.net/pubwww.acmecorp.com/internal/foo.wml

n The default access control settings let you access any URLs in the samedomain. The WAP user agent uses the domain and path attributes to determinewhich URLs can access the deck. The user agent uses a prefix match tocompare the URLs of decks trying to access your deck with the attribute valuesyou define.

The following table lists the elements that let you navigate between decks and theassociated access settings the target deck must specify.

Element Access requirements

prev None.

go href="href" The deck located at the specified href must specifydomain and/or path attributes that match theURL of the requesting deck.

For more information on the access element and how to use it, refer to the WMLReference.

Access control example

In the following example, the access element is used to restrict access to the deckcontaining this element. Only decks in the network location“mycompany.com/WML” are allowed access to this deck.

<head>



<access domain="mycompany.com" path="/WML"/>

</head>

Security Developer’s Guide


Writing secure WML

The following WML elements and attributes help to reduce security risks whencreating WML services.

Element Attribute Explanation

access domain

path

Enables access to specified decks. A deck’sdomain and path attributes specify the otherdecks that can access it.

go sendreferer Specifies whether the user agent should providethe URL of the current deck when requesting thespecified URL. Setting sendreferer="true"causes the device to specify the deck URL in theHTTP_REFERER request header.

! Note: The Nokia WAP Toolkit 1.2 does not support HTTP-S addresses orSecure Socket Layers (SSL).

Developer’s Guide Security



Web server

This chapter provides information on how to configure your web server for WMLand WMLScript services.


MIME types

Before creating your own WML and WMLScript services, configure your webserver to support the following MIME types:

Content MIME type Extension

WML source text/vnd.wap.wml wml

Wireless bitmaps image/vnd.wap.wbmp wbmp

Compiled WML application/vnd.wap.wmlc wmlc

WMLScript source text/vnd.wap.wmlscript wmls

Compiled WMLScript application/vnd.wap.wmlscriptc wmlsc

To find out how to configure the MIME types of your web server, contact yourserver vendor.

Developer’s Guide Web server


HTTP headers included in the server

To generate HTTP responses that a web server will accept, your service must havethe correct HTTP headers. The following table lists the HTTP headers you shoulduse when communicating with a web server.

HTTP header Usage

Content-type The Content-type header is required. It canspecify any of the following MIME types:text/vnd.wap.wmlapplication/vnd.wap.wml-wbxmltext/vnd.wap.wmlscriptapplication/vnd.wap.wmlscriptc

These types are described above in “MIMEtypes”.

charset The charset header specifies the documentcharacter set. For example,Content-type: text/vnd.wap.wml;charset=UTF-8

Content-length The Content-length header is optional. TheNokia WAP Toolkit 1.2 ignores this header.

Content-encoding The Content-encoding header is optional. TheNokia WAP Toolkit 1.2 ignores this header.

Cache-Control The Cache-Control header controls how the datais cached to the Nokia WAP Toolkit. Forexample,

Cache-Control: no-cache

specifies that the data is not cached at all.

Web server Developer’s Guide


Character sets

By default, the web server transcodes data for your application according to theHTTP headers specified by your application. For example, if you provide a deckcontaining an entry card and the HTTP header for the deck specifies the ISO-8859-1 character set, the web server returns the text the user enters in the deck in ISO-8859-1 characters. To determine which character set your application expects, theweb server also looks at the accept-charset attribute of the go element returningthe data. If the HTTP header of the deck does not specify a character set, the webserver uses the accept-charset attribute to determine the character set. Youshould set the accept-charset attribute for all go elements that return data.

For example, if your service uses the ISO-8859-1 character set, it could be specifiedin a do task as follows:

<card>

<do type="accept">

<go href="http://acme.com/stats.cgi" method="post"

accept-charset="ISO-8859-1" />

</do>

<p>

Enter your company name: <input name="company"/>

</p></card>

The Nokia WAP Toolkit supports the following character set names that you canspecify for the charset parameter in HTTP headers and the go element’s accept-charset attribute. Use the names shown below to ensure that the character set ishandled correctly.

n ISO-8859-1

n UTF-8

n ISO-10646-UCS-2

Developer’s Guide Web server



Example applications

This section contains two simple “real-life” applications of WML and WMLScript,one for converting currency values, the other for calculating mortgage payments.

You can find both of these examples in the \samples directory under the NokiaWAP Toolkit installation directory (by default, C:\ProgramFiles\Nokia\WAPToolkit).

Currency converter

The following WML and WMLScript example demonstrates an application thatconverts currency values between US dollars, German Marks, French Francs andthe Finnish Markka. The currency exchange rates are according to the FederalReserve Bank of America’s published rates of October 29th 1998.

This example code is also provided as the currency.wml and currency.wmls filesin the Nokia WAP Toolkit.

WML code


<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"

"http://www.wapforum.org/DTD/wml_1.1.xml">

<wml>

<card id="card1" title="Currency" newcontext="true">

<p>

Amount: <input format="*N" name="amount" title="Amount:"/>

<select name="from" value="USD" title="From:">





<select name="to" value="FIM" title="To:">





Developer’s Guide Example applications


<br/>= <u>$(conversion)</u>


<go

href="currency.wmls#convert(’conversion’,’$(from)’,’$(to)’,$(amount))"/></do>


<go href="#card1_help"/>

</do>

</p>

</card>

<card id="card1_help" title="Help">


<go href="currency.wmls#getInfoDate(’date’)"/>

</onevent>

<p>

The currency rates were obtained from the FederalReserve Bank of New York on $(date).

<do type="prev" label="Back">

<prev/>

</do>

</p></card>

</wml>

WMLScript code

/*

* Return the date when the data was generated.

*

*@param varName - the variable to store the results

*/extern function getInfoDate(varName) {

WMLBrowser.setVar(varName,"October 29 1998");

WMLBrowser.refresh();

}

/*

* Calculate the exchange rate

*

*@param varName - the variable to store the results

*@param amount - the amount to convert

*@param from - the original currency

*@param to - the currency to convert to

*@return a string containing the converted amount; or an error

* if "from" and/or "to" is not supported.

*/extern function convert(varName,from,to,amount) {

var multiplier = 0.0;

var returnString = "Not Available";

var result;

Example applications Developer’s Guide


if (from == "DEM") {

/*

* German Mark

*/

var DEM_FIM = 0.328728;

var DEM_FRF = 0.298331;

var DEM_USD = 1.653500;

if (to == "DEM")

multiplier = 1.0;

else if (to == "FIM")

multiplier = DEM_FIM;

else if (to == "FRF")

multiplier = DEM_FRF;

else if (to == "USD")

multiplier = DEM_USD;

} else if (from == "FIM") {

/*

* Finnish Markka

*/

var FIM_DEM = 3.042032;

var FIM_FRF = 0.907533;var FIM_USD = 5.030000;

if (to == "FIM")

multiplier = 1.0;

else if (to == "DEM")

multiplier = FIM_DEM;


multiplier = FIM_FRF;


multiplier = FIM_USD;

} else if (from == "FRF") {

/*

* French Franc

*/

var FRF_DEM = 3.351981;

var FRF_FIM = 1.101889;

var FRF_USD = 5.542500;

if (to == "FRF")

multiplier = 1.0;


multiplier = FRF_FIM;


multiplier = FRF_DEM;


multiplier = FRF_USD;

} else if (from == "USD") {

/*

* US Dollar

*/

var USD_DEM = 0.604778;

var USD_FIM = 0.198807;var USD_FRF = 0.180424;



if (to == "USD")

multiplier = 1.0;


multiplier = USD_FIM;


multiplier = USD_FRF;


multiplier = USD_DEM;

}

if (multiplier != 0.0) {

/*

* Make the calcualtion

*/

result = amount / multiplier;

returnString = String.toString(result);

returnString = String.format("%.2f", returnString);}

/*

* Return the results to the browser

*/

WMLBrowser.setVar(varName,returnString);


}

Explanation

When you navigate to the deck, the WML encoder will generate the following userinterface (as shown on a 6110 model phone):

Press the Options button.

Press Select to choose Edit Amount.

In the card that appears, enter the currency amount by using your computerkeyboard or the keypad of the simulator phone. The default value is 0. You candelete the last digit entered by pressing Clear.

Note that you can enter only numbers. The interface now looks like:



Press OK to return back to the first card.

Next, select from which currency you want to convert the specified amount.

n Press the button with the up and down arrow to scroll down through thedisplay and move the cursor to the currency from which you want to convert.

n Press Options, select Select List Item, and press Select.

n The button in front of the currency is now checked and the display looks like:

Next, select the currency to which you want to convert the specified value.

n Press the button with the up and down arrow to scroll down through thedisplay and move the cursor to the currency to which you want to convert.

n Press Options to select the item. select the currency. The button in front of thecurrency is now checked and the display looks like:

Finally, calculate the converted value:

n Press Options to go to the option menu.

n In the option menu, select Calculate and press Select.

n You are brought back to the currency card. Scroll down through the display tosee the last line. The display now looks like:



The last line shows the result of the calculation.

Mortgage payment calculator

The following WML and WMLScript example demonstrates a simple applicationfor calculating mortgage payments. This example code is also provided as themortgage.wml and mortgage.wmls files in the Nokia WAP Toolkit.

WML code


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

<wml>

<card id="card1" title="Mortgage Calc" newcontext="true">

<p>

Principal: <input format="*N" name="principal" title="Principal:"

value="150000"/><br/>

Interest: <input format="*N" name="interest" title="Interest:"

value="8.00"/>

<br/>

Num payments:<input format="*N" name="num_payments" title="Num.

payments:" value="360"/><br/>

Payment = <u>$(payment)</u>


<go

href="mortgage.wmls#payment(’payment’,’$(principal)’,’$(interest)’,’$(num_

payments)’)"/>

</do>


<go href="#help"/></do>

</p>

</card>

<card id="help" title="Help">

<p>



<u>Principal</u> - $$ amount<br/>

<u>Interest</u> - e.g. 7.5<br/>

<u>Payments</u> - e.g. 360 for 30 years<br/>

<do type="prev" label="Back">

<prev/>

</do>

</p>

</card></wml>

WMLScript code

/*

* Calculate a mortgage’s payment

*

*@param varname the variable name to store the result

*@param principal the principal

*@param interest the interest rate

*@param num_payments the number of payments

*@return the payment

*/

extern function payment(varname, principal, interest, num_payments) {

/*

* Interest formulae:

*

* If (i != 0), then:

* pmt = principal * [i * (1+i)^n / ((1+i)^n - 1)]

*

* If (i == 0), then:

* pmt = principal / n

*/

var mi = interest/1200; // monthly interest from annual percentage

var payment = 0;

if (mi != 0) {

var tmp = Float.pow((1 + mi), num_payments);

payment = principal * (mi * tmp / (tmp - 1));

} else {

if (num_payments != 0)

payment = principal / num_payments;

}

var s;

if (payment != 0)

s = String.format("$%6.2f", payment);

else

s = "Missing data";

/*

* Send the result to the browser

*/ WMLBrowser.setVar(varname, s);



/*

* Make sure the browser updates its current card

*/


};

Explanation

When you navigate to the deck, the WML encoder will generate the following userinterface (as shown on a 6150 model phone):

This card displays the default values for principal, interest and number of payments.

To change the value of a field, go to the value line by pressing the button with theup and down arrow, and press Options. From the Options screen, choose to editthe value and press Select. The following interface appears:

In this display, enter the new value:

n Empty the display by pressing Clear.

n Enter the new value by using your computer keyboard or the keypad of thesimulator phone. Note that you can enter only numbers.

n When you are done, press OK to return to the first card. You can delete the lastdigit entered by pressing Clear.

Set the values similarly for all the fields.

After entering all the values, press OK to return to the first card and scroll downthrough the display to see the last line.

The last line shows the monthly mortgage payment.


Glossary

The following terms and conventions are used throughout this document.

American Standard Code for Information Interchange (ASCII)

ASCII is a standard developed by the American National Standards Institute(ANSI) to define computer-intelligible values for characters used in text. TheASCII set of 128 characters includes upper-case and lower-case letters of theEnglish alphabet, numbers, punctuation, and 33 control codes (such as tab, bell,carriage return). ASCII uses 7 bits to represent each character. You may seeASCII characters identified by a decimal number from 0 to 127.

The standard ASCII character set uses just 7 bits for each character,consequently one bit of each octet is not used. Larger character sets, known asextended ASCII or high ASCII, use all 8 bits, allowing as many as 128additional characters to be defined. Numerous extensions to ASCII have beendevised and quite a few have become national or international standards.Notable among them is a family of international standards, ISO-8859, thatdefines extensions appropriate to certain language groups which ASCII alonecannot support. The most important member of this group is ISO-8859-1,known as ISO Latin-1, which provides for the languages of western Europe.

Attribute

A syntactical component of a WML element which is often used to specify acharacteristic quality of an element, other than type or content.

Author

An author is a person or program that writes or generates WML, WMLScriptor other content.

Bandwidth

Bandwidth is the capacity that a telecommunications medium has for carryingdata. For analog or voice communication, bandwidth is measured in thedifference between the upper and lower transmission frequencies expressed incycles per second, or hertz (Hz). For digital communication, bandwidth andtransmission speed are usually treated as synonyms and measured in bits per

Developer’s Guide Glossary


second. The actual speed or transmission time of any message or file fromorigin to destination depends on a number of factors. Most Internettransmissions travel at very high speed on fiber optic lines most of the way.Switching en route, lower bandwidths on local loops at both ends, and serverprocessing time add to the overall transmission time.

Byte

A sequence of consecutive bits treated as a unit. On almost all moderncomputers, a byte is comprised of 8 bits, though other numbers were formerlyencountered. To avoid ambiguity, the term octet is used in the language ofinternational standards to refer to an 8-bit unit.

Large amounts of memory are indicated in terms of kilobytes (1,024 bytes),megabytes (1,048,576 bytes), and gigabytes (approximately 1 billion bytes). Adisk that can hold 1.44 megabytes, for example, is capable of storingapproximately 1.4 million ASCII characters, or about 3,000 pages ofinformation.

Bytecode

Content encoding where the content is typically a set of low-level opcodes,that is, instructions, and operands for a targeted piece of hardware or virtualmachine.

Card

A single WML navigational and user interface unit. A card may containinformation to present to the user or instructions for gathering user input, forexample.

Character Encoding

When used as a verb, character encoding refers to conversion between sequenceof characters and a sequence of bytes. When used as a noun, character encodingrefers to a method for converting a sequence of bytes to a a sequence ofcharacters. Typically, WML document character encoding is captured intransport headers attributes, meta information placed within a document, orthe XML declaration defined by the XML specification.

Client

A device or application that initiates a request for connection with a server.

Glossary Developer’s Guide


Common Gateway Interface (CGI)

A programming language that enables you to use forms on your web site.

Concatenation

Concatenating two strings means sticking them together, one after another, tomake a new string. For example, the string “foo” concatenated with the string“bar” gives the string “foobar”.

Content

Subject matter stored or generated at a web server. Content is typicallydisplayed or interpreted by a user agent in response to a user request.

Content encoding

When used as a verb, content encoding indicates the act of converting contentfrom one format to another. Typically the resulting format requires lessphysical space than the original, is easier to process or store and/or isencrypted. When used as a noun, content encoding specifies a particular formator encoding standard or process.

Content format

Actual representation of content.

Deck

A collection of WML cards. A WML deck is also an XML document.

Device

A network entity that is capable of sending and receiving packets ofinformation and has a unique device address. A device can act as both a clientor a server within a given context or across multiple contexts. For example, adevice can service a number of clients as a server while being a client to anotherserver.



Document Type Definition (DTD)

The document type definition states which elements can be nested withinothers. A DTD defines:

— The names and contents of all elements that are permissible in a certaindocument.

— How often an element may appear.

— The order in which the elements must appear.

— Whether the start or end tag may be omitted.

— The contents of all elements, that is, the names of the other genericidentifiers that are allowed to appear inside them.

— The attributes and their default values.

— The names of the reference symbols that may be used.

Element

Elements specify all the markup and structural information for a WML deck.Elements may contain a start tag, content and an end tag.

Extensible Markup Language (XML)

The Extensible Markup Language is a World Wide Web Consortium (W3C)standard for Internet markup languages, of which WML is one such language.XML is a restricted subset of SGML.

Hypertext transfer protocol (HTTP)

HTTP is the underlying protocol used by the World Wide Web. HTTP defineshow messages are formatted and transmitted, and what actions web servers andbrowsers should take in response to various commands. For example, whenyou enter an URL in your browser, an HTTP command is sent to the webserver directing it to retrieve and transmit the requested web page.

JavaScript™

A de facto standard language that can be used to add dynamic behaviour toHTML documents.



Markup

Text added to the data of a document to convey information on it. There arefour different kinds of markup: descriptive markup (tags), references, markupdeclarations, and processing instructions.

Rendering

Formatting and presenting information.

Resource

A network data object or service that can be identified by an URL. Resourcesmay be available in multiple representations (for example, multiple languages,data formats, size and resolutions) or vary in other ways.

Server

A device or application that passively waits for connection requests from oneor more clients. A server may accept or reject a connection request from aclient.

Standardized Generalized Markup Language (SGML)

The Standardized Generalized Markup Language is a general-purpose languagefor domain-specific markup languages. SGML is defined in the ISO8879standard.

Tag

A tag is a generic term for a language element descriptor. WML consists ofcontent surrounded by formatting tags. Each tag is enclosed in a pair of anglebrackets: < and >. Tags are generally used in pairs, one to start the element andone to end it.

Terminal

A device providing the user with user agent capabilities, including the ability torequest and receive information. Also called a mobile terminal or mobilestation.

Transcode

The act of converting from one character set to another, for example,conversion from UCS-2 to UTF-8.



Unicode

An encoding scheme for written characters and text. Unlike ASCII, which uses7 bits for each character, Unicode uses 16 bits, which means that it canrepresent more than 65,000 unique characters, a huge increase over ASCII’scode capacity of 128 characters. Unicode was authored and is maintained bythe Unicode Consortium, a group comprised of major corporations andinstitutions involved in international computing. The character repertory andthe codes assigned in Unicode are identical to those specified by ISO 10646, theinternational Universal Character Set (UCS) standard.

The Unicode Standard, Version 2.0 defines codes for characters used in everymajor language written today. In all, the Unicode standard currently definescodes for nearly 39,000 characters from the world’s alphabetic, ideographic andsyllabic scripts and symbol collections. The Unicode repertory was derivedfrom many pre-existing character set standards to which previouslyunstandardized characters have been added. In particular, the first 256 codevalues are identical to those of ISO 8859-1 extended to 16 bits. Unicode valuesare displayed as four hex digits preceded by U+. For example, U+0041 is Latinupper case A.

Uniform Resouce Identifier (URI)

Uniform Resource Identifiers (URI) identify resources in the web: documents,images, downloadable files, services, electronic mailboxes, and other resources.A URI can refer to an Uniform Resource Locator (URL) or an UniformResource Name (URN).

Uniform Resource Locator (URL)

URL stands for Uniform Resource Locator and is an address referring to adocument on the Internet. The syntax of an URL consists of three elements:

— The protocol, or the communication language, that the URL uses.

— The domain name, or the exclusive name that identifies a web site.

— The pathname of the file to be retrieved.

User

A user is a person who interacts with a user agent to view, hear, or otherwiseuse a resource.

User agent

A user agent is any piece of software or physical device that interprets WML,WMLScript, WTAI or other resources. They may include textual browsers,voice browsers and search engines, for example.



Web server

The server on which a given resource resides or is to be created. Often referredto as an origin server or an HTTP server.

Wireless Application Environment (WAE)

The Wireless Application Environment specifies a general-purpose applicationenvironment based fundamentally on World Wide Web technologies andphilosophies. WAE specifies an environment that allows operators and serviceproviders to build applications and services that can reach a wide variety ofdifferent platforms. WAE is part of the Wireless Application Protocol.

Wireless Application Protocol (WAP)

The Wireless Application Protocol specifies an application framework andnetwork protocols for wireless devices such as mobile phones, pagers, andpersonal digital assistants (PDAs). The WAP specifications extend mobilenetworking technologies (such as digital data networking standards) andInternet technologies (such as XML, URLs, scripting, and various contentformats).

Wireless Markup Language (WML)

The Wireless Markup Language is a markup language based on XML and isintended for use in specifying content and user interface for narrowbanddevices, including mobile phones and pagers.

Wireless Markup Language Script (WMLScript)

A scripting language used to program the mobile device. WMLScript is anextended subset of the JavaScript™ scripting language.

Wireless Session Protocol (WSP)

The Wireless Session Protocol provides the upper-level application layer ofWAP with a consistent interface for two session services. The first isconnection-mode service that operates above a transaction layer protocol, andthe second is a connectionless service that operates above a secure or non-secure datagram transport service.




Index

Aa element, 20, 39

Access control, 53

access element, 14, 53

Alignment, 44

amp character, 47

Ampersand character, 47

anchor element, 20, 39

Anchors, 20

apos character, 47

Apostrophe character, 47

Attributes, 10

Bbr element, 21

CCache-Control, 58

Card, 7

multiple, 23

card element, 13, 14

Case sensitivity, 11

Character entities

decimal numeric, 47hexadecimal numeric, 47named, 47

Character format, 34

Character sets, 59

charset, 58

Commenting code, 10

Components of Nokia WAP Toolkit, 4

Configuring MIME types, 57

Content-encoding, 58

Content-length, 58

Content-type, 58

DDecimal numeric character entities, 47

Deck, 7

multiple, 23

do element, 16

Document type declaration (DTD), 11

Dollar sign character, 27

EElements, 8

Emphasis, 43

Entities, 8

Events, 16

Example applications, 61

Extensible Markup Language, 1

Ffieldset element, 20

Formatting text, 43

alignment, 44emphasis, 43line breaks, 44line wrapping, 44special characters, 47table element, 45tables, 45td element, 46tr element, 46

Developer’s Guide Index


GGlossary, 69

go element, 17, 18

Greater than character, 47

gt character, 47

Hhead element, 14

Header, 11

Hexadecimal numeric character entities,47

History stack, 26

HTTP headers, 58

IImages, 20

img element, 20

input element, 20, 31

Intrinsic events, 41

Introduction to WML, 7

LLess than character, 47

Line breaks, 44

Line wrapping, 44

Links, 13, 39

lt character, 47

Mmeta element, 14

MIME types, 57

Minimizing security risks, 55

Modes

line wrapping, 44

Multiple

cards, 23decks, 23

NNamed character entities, 47

nbsp character, 47

Nokia WAP Toolkit

components, 4

Non-breaking space character, 47

noop element, 17, 19

Oonenterbackward element, 16, 42

onenterforward element, 16, 42

onevent element, 16

onpick element, 16, 42

ontenterforward element, 42

ontimer element, 16, 41

optgroup element, 20

option element, 20

Pp element, 21

postfield element, 16

prev element, 17, 19

Qquot character, 47

Quotation mark character, 47

Rrefresh element, 17, 19

Related documents, 5

SSamples, 61

Security, 53, 55

select element, 20, 35

Select lists, 35

shy character, 47

Soft hyphen character, 47

Special characters, 47

Special characters of WML, 47

Ttable element, 21, 45

Index Developer’s Guide


Tables, 45

Tag, 8

Task elements, 17

Tasks

go, 18noop, 19prev, 19refresh, 19

td element, 21, 46

template element, 14, 24

Text formatting, 21

alignment, 44emphasis, 43line breaks, 44special characters, 47table element, 45td element, 46text wrapping, 44tr element, 46

Text input, 31

Text wrapping, 44

timer element, 20, 40

Timers, 20, 40

tr element, 21, 46

Typographical conventions, 5

UUser input, 20, 31

VVariables, 10, 19, 27

naming, 27setting, 28substituting, 29

WWeb server, 57

Wireless Application Protocol (WAP), 1

Wireless Markup Language, 1

WML. See Wireless Markup Language

a element, 20, 39access control, 53access element, 14, 53

anchor element, 20, 39br element, 21card element, 13, 14deck, 7do element, 16elements, 13fieldset element, 20formatting text, 43go element, 17, 18head element, 14header, 11img element, 20input element, 20, 31intrinsic events, 41introduction, 7meta element, 14noop element, 17, 19onenterbackward element, 16, 42onenterforward element, 16, 42onevent element, 16onpick, 42onpick element, 16, 42ontimer element, 16, 41optgroup element, 20option element, 20p element, 21postfield element, 16prev element, 17, 19refresh element, 17, 19security, 53select element, 20, 35special characters, 47structure, 11table element, 21tasks, 17td element, 21template element, 14, 24text formatting, 43timer element, 20, 40tr element, 21variables, 27wml element, 11, 13

wml element, 13

WML syntax

attributes, 10case sensitivity, 11comments, 10elements, 8

Developer’s Guide Index


entities, 8tags, 8variables, 10

WMLScript, 49

non-standard libraries, 50standard libraries, 50

XXML. See Extensible Markup Language

declaration, 11version number, 11