Developer's Guide - Nokia WAP Toolkit. Version 1.2
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Developer’s Guide
NOKIA WAP TOOLKIT
Version 1.2
http://www.forum.nokia.com
Product number: SDK-01-000-002
Version 1.2 September 1999Developer’s Guide
NOKIA 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 Finland
P.O. Box 226,
FIN-00045 NOKIA GROUP
Tel. +358 9 180 71
Fax. +358 9 656 388
Internet mail address:
wap.sw.developer@nokia.com
http://www.forum.nokia.com
This document is part of the Nokia Wireless Application Protocol Toolkit. Reproduction, distribution
or transmission of part or all of this documentation in any form without the prior written permission of
Nokia 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 Sun
Microsystems, 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 Web
Consortium and are copyrighted by the World Wide Web Consortium (Massachusetts Institute of
Technology, Institut National de Recherche en Informatique et en Automatique, Keio University).
©1999. Nokia Corporation. Nokia is a registered trademark of Nokia Corporation.Contents
Introduction.................................................................................. 1
Wireless Application Protocol............................................................................. 1
Nokia WAP Toolkit ............................................................................................ 4
Typographical conventions.................................................................................. 5
Related documents............................................................................................... 5
Documents included in the Nokia WAP Toolkit .......................................... 5
Other references ............................................................................................. 6
Overview of WML......................................................................... 7
Introduction to WML syntax .............................................................................. 7
Overview of WML syntax.............................................................................. 8
Entities.......................................................................................................... 8
Tags .............................................................................................................. 8
Elements ....................................................................................................... 8
Attributes ................................................................................................... 10
Comments .................................................................................................. 10
Variables ..................................................................................................... 10
Case sensitivity........................................................................................... 11
WML structure........................................................................................... 11
Working with WML elements .................................................... 13
WML elements................................................................................................... 13
Deck and cards ............................................................................................. 13
card element ............................................................................................... 14
Events ........................................................................................................... 16
do element .................................................................................................. 16
Task elements ............................................................................................... 17
go task ........................................................................................................ 18
prev task ..................................................................................................... 19
refresh task ................................................................................................. 19
noop task .................................................................................................... 19
Variables ....................................................................................................... 19
User input..................................................................................................... 20
Anchors, images, and timers......................................................................... 20
Text formatting............................................................................................. 21
Example deck................................................................................................ 21
Multiple cards in multiple decks........................................................................ 23
Using the template element .......................................................................... 24
History stack...................................................................................................... 26
NOKIA WAP TOOLKIT iDeveloper’s Guide
Variables and dynamic interfaces....................................................................... 27
Naming variables .......................................................................................... 27
Setting variables ............................................................................................ 28
Substituting variables.................................................................................... 29
Variable example........................................................................................... 29
User input .......................................................................................................... 31
input element ................................................................................................ 31
Specifying the character format.................................................................. 34
select element................................................................................................ 35
Single-choice list......................................................................................... 37
Multiple-choice list .................................................................................... 38
Using links ......................................................................................................... 39
Link example ................................................................................................ 40
Using timer ........................................................................................................ 40
Intrinsic events................................................................................................... 41
Displaying text................................................................................................... 43
Emphasis....................................................................................................... 43
Text format example .................................................................................. 44
Line breaks ................................................................................................... 44
Text wrapping and alignment....................................................................... 44
table element................................................................................................. 45
Special characters .......................................................................................... 47
WMLScript .................................................................................. 49
Overview of WMLScript ................................................................................... 49
WMLScript standard libraries ...................................................................... 50
WMLScript non-standard libraries .............................................................. 50
WML and WMLScript example ................................................................... 50
Security ...................................................................................... 53
Access element ................................................................................................... 53
Access control example ................................................................................ 54
Writing secure WML ......................................................................................... 55
Web server ................................................................................. 57
MIME types....................................................................................................... 57
HTTP headers included in the server ................................................................ 58
Character sets..................................................................................................... 59
Example applications ................................................................ 61
Currency converter............................................................................................ 61
Mortgage payment calculator ............................................................................ 66
Glossary ..................................................................................... 69
Index ........................................................................................... 77
ii NOKIA WAP TOOLKITIntroduction
This guide provides information and practical examples for developers using the
Nokia 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 mobile
phones access to a wide variety of wireless services over the Internet. It offers
developers an environment for creating, testing and demonstrating WAP
applications, allowing service providers to evaluate the usability of wireless
applications and services with their end user organizations.
The Nokia WAP Toolkit includes a simulator client for Windows NT, Windows
95, and Windows 98, as well as content encoders and practical Wireless Markup
Language (WML) examples.
The Nokia WAP Toolkit 1.2 simulates a generic WAP mobile phone (you have
your choice models), later referred to as user agent. A WAP user agent is similar to
a web browser with the distinction that in the WAP environment Uniform
Resource Locators (URLs) are requested over conventional cellular networks. The
URL request is sent to a web server containing WML services. These services
respond to the requests using WML. WML is based on the Extensible Markup
Language (XML) and was developed by the WAP Forum for specifying the content
and user interface for narrowband devices such as mobile phones.
The Nokia WAP Toolkit 1.2 also includes an XML library that you can use to
construct valid WML documents for use by server-side components or for general
use.
Wireless Application Protocol
Digital wireless user agents such as mobile phones have become very popular in
recent years. Technically speaking, mobile phones are no longer just phones; they
are communication devices capable of running applications and communicating
with other devices and applications over a wireless network.
The WAP standard specifies two essential elements of wireless communication: an
end-to-end application protocol and an application environment based on a
browser. The application protocol is a layered communication protocol that is
embedded in each WAP-enabled user agent. The network side includes a server
component implementing the other end of the protocol that is capable of
communicating with any WAP user agent. Often the server component takes the
role of a gateway routing the requests from the user agent to an application server.
NOKIA WAP TOOLKIT 1Developer’s Guide Introduction
The gateway can be physically located in a telecom network or in a computer
network, building a bridge between the two networks. The following picture
illustrates the WAP network structure.
WAP GATEWAY
COMPUTER
NETWORK
IP
WAP
WIRELESS NETWORK
WIRELESS APPLICATION
TERMINAL SERVER
WAP network structure.
A WAP application consists of a server application and a client application that the
gateway downloads from the application server to the user agent for execution. A
standard application environment is needed for running the same client application
on different mobile user agents. WAP provides such a standard, consisting of a
browser and a script interpreter. The browser is very similar to a web browser and
can handle content described in WML. The browser also contains a built-in script
interpreter for running applications in the user agent. These applications are written
in a script language called WMLScript. In addition to the programming language
itself, the script interpreter also implements a set of libraries that allow the
application to access certain services of the user agent. WML and WMLScript are
designed for use in wireless, narrowband networks, and they are both binary
encoded 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, the
picture also contains a typical Internet protocol stack.
2 NOKIA WAP TOOLKITIntroduction Developer’s Guide
Internet Wireless Application Protocol
HTML Wireless Application Other Services
JavaScriptTM Environment (WAE) and
Applications
HTTP 1 Wireless Session Layer (WSP)
2 Wireless Transaction Protocol (WTP)
TLS - SSL 3 Wireless Transport Layer Security (WTLS)
4 Wireless Datagram Protocol (WDP)
TCP/IP
UDP/IP Bearers:
SMS USSD CSD IS-136 CDMA CDPD PDC-P Etc..
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 be
HTML. Some gateways are capable of translating HTML into WML.
In WAP, the content and the applications are addressed with an URL, in the same
way as in other Internet protocols. The following picture illustrates this.
7 4
Client Web Server
WAP Gateway
with WMLScript
WML
WML Decks
6 WML Encoder 5 CGI
WML- Scripts
WAP WMLScript
HTTP etc.
Script
1 2 Encoder 3
Etc.
Protocol Adapters Content
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 WAP
protocol.
3 The WAP gateway create an conventional HTTP request for the specified URL
and sends it to the web server.
NOKIA WAP TOOLKIT 3Developer’s Guide Introduction
4 The HTTP request is processed by the web server. The URL may refer to a
static file or to a CGI or other script application. In the first case, the web
server fetches the file and adds an HTTP header to it. If the URL specifies a
script application, the web server runs the application.
5 The web server returns the WML deck with the added HTTP header or the
WML output from the CGI or other script application.
6 The WAP gateway verifies the HTTP header and the WML content and
encodes them to binary form. The gateway then creates a WAP response
containing the WML and sends it to the user agent.
7 The user agent receives the WAP response. It processes the WML response and
displays the first card of the WML deck to the user.
For more information on the WAP, refer to the guides listed in “Related
documents” 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, and
Windows 98. The Toolkit simulates the behavior of WML and WMLScript and
allows you to create, edit, and debug WML and WMLScript services. The
simulation 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 by
server-side components, or for general use. The library only allows you to
create valid content, as validated by the standard DTD for WML1.1.
Additional validation may be performed, specific to WML and beyond the
scope 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 tree
model that may be traversed and edited.
n User documentation in Adobe PDF format, including this Developer’s Guide
and WML and WMLScript language references.
4 NOKIA WAP TOOLKITIntroduction Developer’s Guide
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, function
names.
Courier Bold WML tags, URLs.
Courier Italic Parameter values (for example, type="options"),
variables in commands and other types of specialized
language.
Italic References to other guides and documents, new
terminology.
Bold Names of Windows menus, commands, buttons and
icons.
| Separates alternative items. For example,
means that the image can be aligned left, center or
right.
The following convention is used when referring to the installation directory of the
Nokia WAP Toolkit:
By default, the Nokia WAP Toolkit installation directory is
C:\Program Files\Nokia\WAPToolkit.
Related documents
The following documents contain additional information on the Nokia WAP
Toolkit and the WAP. The web address provided after each document specifies the
Internet 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 the
WML, and provides instructions on installing and using the product.
NOKIA WAP TOOLKIT 5Developer’s Guide Introduction
n WML Reference
This guide provides reference information on the WML. It introduces the
WML syntax and provides code examples.
n WMLScript Reference
This guide provides reference information on the WMLScript language. It
introduces 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
6 NOKIA WAP TOOLKITOverview of WML
This chapter gives an overview of the WML syntax and provides examples of how
you 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 detailed
presentation on WML, refer to the WML Reference guide provided with the Nokia
WAP Toolkit.
WML is an XML language inheriting the XML document character set. In WML, a
document character set is the set of all logical characters that a document type may
contain, for example the letter ‘T’ and a fixed integer identifying that letter. A
WML or XML document is simply a sequence of these integer tokens, which taken
together form a document.
The basic unit of WML is the card, which specifies a single interaction between the
user 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 typically
activates the first card in the deck unless directed to a different card as specified by
the requesting URL in its reference section.
Deck
Card Card
Card Card
Card Card
Card Card
NOKIA WAP TOOLKIT 7Developer’s Guide Overview of WML
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 examples
contained 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 information
on the syntactical issues of XML, refer to the XML Specification.
Entities
WML text can contain numeric or named character entities that specify specific
characters in the document character set. Entities are used to specify characters in
the document character set which must either be escaped in WML or which may be
difficult to enter in a text editor. For example, the ampersand (&) is represented by
the named entity &. All entities begin with an ampersand and end with a
semicolon.
Tags
A tag is a language element descriptor. A tag describes an element and contains an
element type name and a unique identifier. A tag could also include attributes
describing other properties.
WML consists of content surrounded by formatting tags, each enclosed in a pair of
angle brackets, < and >.
This starts an element. The start tag can contain attributes.
This ends an element.
This is an empty element, for example , indicating a line break.
Elements
Elements specify all markup and structural information for a WML deck. Elements
may contain a start tag, content, other elements, and an end tag. Elements have one
of two structures:
content
- or-
Elements containing content and other elements are identified by a start tag
and an end tag . An empty-element tag identifies elements with no
content.
8 NOKIA WAP TOOLKITOverview of WML Developer’s Guide
The following table lists the WML tags supported in Nokia WAP Toolkit 1.2, by
general category. Most of the elements are discussed later in this guide. For details
on all elements, refer to the WML Reference.
Category WML elements
Deck and cards wml
card
template
head
access
meta
Events do
ontimer
onenterforward
onenterbackward
onpick
onevent
postfield
Tasks go
prev
refresh
noop
Variables setvar
User input input
select
option
optgroup
fieldset
Anchors, images, and timers a
anchor
img
timer
Text formatting br
p
table
tr
td
NOKIA WAP TOOLKIT 9Developer’s Guide Overview of WML
Attributes
Many WML elements allow you to include attributes in them. Attributes specify
additional information for an element. You always specify attributes in the start tag
of an element, using the following syntax:
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 quotation
marks (").
Note that attribute names must be lowercase.
Some attributes are mandatory. For example, the go element requires the href
attribute:
Other attributes are optional and may have default values. For example, the align
attribute 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 Reference
included 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 to
the 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 a
variable 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 variable
syntax is legal, an unescaped ‘$’ character indicates a variable substitution. Variable
references are legal in any PCDATA and in any attribute value identified by the vdata
entity type.
10 NOKIA WAP TOOLKITOverview of WML Developer’s Guide
Case sensitivity
XML is a case-sensitive language, and WML has inherited this characteristic. No
case folding is performed when parsing a WML deck. This implies that all WML
tags, attributes and contents are case sensitive. In addition, any enumerated
attribute 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 XML
declaration and a document type declaration:
A WML deck begins and ends with the wml element, and all other elements come in
between these start and end tags:
...all other elements...
The following is a simple WML deck containing a single card. Note that the line
numbers are used for reference purposes only and are not part of the actual code.
The first WML example
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 to
make accessing it faster. The Nokia WAP Toolkit includes the DTD file
wml.xml, found in the directory \dtd.
NOKIA WAP TOOLKIT 11Developer’s Guide Overview of WML
4 The fourth line is the root element of the XML document of which there may
only be only one and it must match the root element name as indicated in the
first argument of the document type. All WML documents must begin with a
tag.
5 The following lines define a card containing a start and an end tag and text to
be displayed to the user.
! Note: The id attribute values cannot contain spaces.
10 All WML decks must end with a tag.
When a user agent loads the deck, it is displayed as shown below.
A WML deck with a single card.
12 NOKIA WAP TOOLKITWorking with WML
elements
This chapter discusses working with the different WML elements to build simple
cards and decks.
As explained in the previous chapter, the basic unit of WML is the card and cards
are grouped together into decks. A single WML card can contain a large amount of
information. 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 WML
elements you’ll need to know about to follow the examples. For more details on the
elements discussed here, refer to the WML Reference.
Refer to the Glossary on page 69 for definitions of new terms used in this chapter.
WML elements
You use WML elements to create the various components of a card. You might
have a component that creates a connection between one document and another, or
between one part of a document to another part. This type of component is called a
link. 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 within
a deck.
Element Explanation
wml Defines a deck and encloses all the information
and cards in the deck.
card Indicates the general layout and user schemes in
NOKIA WAP TOOLKIT 13Developer’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 a
whole, including meta-data and access control
elements.
access Specifies access control information for the entire
deck.
meta Contains generic meta information relating the
deck.
card element
The following is a simple card element example:
Text containing information .
Component Explanation
The start tag of a card. One WML deck can
contain several cards.
id="card_name" Specifies a name that allows you to navigate to the
card from other cards in the same deck.
title="title" Specifies advisory information on the card.
Specifies a paragraph.
Specifies italic text emphasis.
14 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
The following table lists other attributes of the card element. For more detailed
information on the attributes of the card element and how to use it, refer to the
WML Reference included in the Nokia WAP Toolkit.
Attributes Explanation
newcontext="false" If you set this attribute to true, the browser
context is re-initialized upon entry to this card.
The browser context is used to manage all
parameters and user agent states, including
variables, the navigation history and other
implementation-dependent information related to
the current state of the user agent.
ordered=boolean Gives an indication to the user agent about how
the card content is organized.
onenterforward="href" Navigates to the location specified by href.
Occurs when the user navigates into a card using a
go task.
onenterbackward="href" Navigates to the location specified by href.
Occurs when the user navigates into a card using a
prev task.
ontimer="href" Navigates to the location specified by href after a
specified amount of time.
xml:lang Specifies the natural or formal language in which
the document is written.
id Provides an element with a unique name within a
single deck.
class Affiliates an element with one or more classes.
! Note: The Nokia WAP Toolkit 1.2 software does not support the
ordered="boolean" attribute.
NOKIA WAP TOOLKIT 15Developer’s Guide Working with WML elements
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 for
performing actions on the current card.
ontimer Specifies an intrinsic event that occurs
when a timer expires.
onenterforward Specifies an intrinsic event that occurs
when the user enters a card under
specific circumstances.
onenterbackward Specifies an intrinsic event that occurs
when the user navigates into a card by
using an URI retrieved from the history
stack (see “History stack” on page 26).
onpick Specifies an intrinsic event that occurs
when the user selects or deselects an
item in which the event is specified.
onevent Binds a task to a particular intrinsic
event.
postfield Specifies a field name and value for
transmission to an origin server during
an URI request.
do element
A card element can contain do elements that assign a task to a certain key. For a
description of the available task elements, see “Task elements” on page 17. The
following is a simple example of how to use the do element:
Component Explanation
The start tag of the do element. Do elements may
appear inside a card and template. Note that you
may 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
16 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
Component Explanation
returns to the previous card. For a complete list of
the 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 may
ignore this element.
See also “Example deck” on page 21. For more detailed information on the
attributes 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 the
user 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 following
table. For more information on WML tasks and how to use them, refer to the
WML Reference.
Task Explanation
go Indicates navigation to a location specified by
href. If the href names a WML card or deck, it is
displayed.
prev Indicates navigation to the previous URI in the
history stack (see “History stack” on page 26).
refresh Indicates an update of the user agent context as
specified by the setvar tags (see “Variables ” on
page 19).
noop Indicates that nothing should be done.
NOKIA WAP TOOLKIT 17Developer’s Guide Working with WML elements
go task
The go task indicates navigation to location specified by an href. If the href names
a WML card or deck, it is displayed. The following is a simple example of how to
use the go element.
Component Explanation
Start tag of a go element, indicating navigation to a
href.
href="href" Specifies the destination, for example, the location
of the card to display. This attribute is required.
The following table lists other attributes of the go element. For more detailed
information on the attributes of the go task and how to use it, refer to the WML
Reference.
Attribute Explanation
sendreferer=boolean If you set this attribute to true, the user agent
includes the deck URL in the HTTP request.
method="post|get" Specifies the HTTP submission method.
Currently, the values of get and post are accepted
and cause the user agent to perform an HTTP get
or post respectively.
accept-charset="chset" Specifies the list of character encodings for data
that the web server must accept when processing
input. The default value is unknown. The user
agent uses the character encoding that was used to
transmit the WML deck containing this attribute.
id Provides an element with a unique name within a
single deck.
class Affiliates an element with one or more classes.
18 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
prev task
The prev element declares a prev task, indicating navigation to the previous URI
on 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 detailed
information on the attributes of the prev task and how to use it, refer to the WML
Reference.
Attribute Explanation
id Provides an element with a unique name within a
single deck.
class Affiliates an element with one or more classes.
refresh task
The refresh element declares a refresh task, indicating an update of the user
agent context as specified by the setvar element (see “Setting variables” on page
28). Side effects of the state changes that are visible to the user (for example, a
change 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 to
the 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 the
WML Reference.
Variables
Parameters can be set for all WML content, giving you a great deal of flexibility in
creating cards dynamically change display content and navigation based on user
input. WML variables can be used instead of strings; their current value is
substituted at runtime.
You use the setvar element to specify a variable. See “Variables and dynamic
interfaces” on page 27.
NOKIA WAP TOOLKIT 19Developer’s Guide Working with WML elements
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 of
options. WML supports both single-
choice and multiple-choice lists.
option Specifies a single choice option in a
select element.
optgroup Lets you group related option elements
in a hierarchy to facilitate layout and
presentation 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 connection
between one document and another, or
between one part of a document and
another part of the same document. See
“Using links” on page 39.
a Provides a short form of the anchor
element. See “Using links” on page 39.
img Places images into the text flow.
timer Implements a card time that can be used
to process inactivity or idle time. See
“Using timer” on page 40.
20 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
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 “Displaying
text” on page 43 for more information.
Element Use
br Establishes the beginning of a new line.
p Establishes both the line wrap and
alignment parameters for a paragraph.
table Creates sets of aligned columns of text
and images in a card.
tr Used with the table element, indicates
a container to hold a single table row.
td Used with the table element, indicates
a container to hold a single table cell
data within a table row.
In addition, you can use the emphasis tags to specify text emphasis markup
information, as explained in “Emphasis” on page 43.
Example deck
The following WML illustrates a deck containing two cards. When the user presses
the ACCEPT soft key labeled “Next,” the user agent navigates to the second card
of the deck and displays its content.
Note that the line numbers are used for reference purposes only and are not part of
the actual code.
Select Next to display the next card.
NOKIA WAP TOOLKIT 21Developer’s Guide Working with WML elements
This card contains the following:...
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 be
included at the beginning of every WML deck, that is, before every tag.
4 The fourth line is the top-most element of the WML deck. All WML decks
must begin with a tag and end with a 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, and .
Most WML elements allow you to specify attributes. Attributes are entered in
the form attribute=value, where attribute is the attribute name and
value is an alphabetic or numeric value that you specify.
6 The sixth line defines an action, which specifies what the user agent should do
when the user presses a specified function key. The type attribute identifies the
key (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 href
attribute identifies the target href destination, for example, the card named
card2.
22 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
Multiple cards in multiple decks
You are not required to put all the cards used by one of your services in a single
deck. It is recommended that you limit the size your decks, since different user
agents have different memory restrictions. Contact your vendor to find out what
the limitations of your user agent are, and take them into consideration when
creating your own WML decks.
For example, the deck2a.wml and deck2b.wml files provided with the Nokia
WAP Toolkit demonstrate dividing content onto multiple decks and cards.
Deck2a.wml contains a template that defines a backward navigating task. In card1
the template task is overridden with a no-operation task. The third card includes a
go task that specifies the URL of the deck2b.wml. When the user activates the go
task, the user agent navigates to the deck and displays its content.
Note that this example uses the template element. See “Using the template
element” on page 24 for more information about this element.
Card 1 ...
NOKIA WAP TOOLKIT 23Developer’s Guide Working with WML elements
Card 2 ...
Card 3 ...
Using the template element
You can define do elements at several levels in WML. The examples in the previous
sections define them at the card level. However, you can also define them at the
deck level by using the template element. A do element’s scope covers the wml
element in which it is defined. If you define it in a deck’s template, it applies to the
whole 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 the
narrower 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 should
execute on receipt of a particular user action.
n The first card inherits the do element specified in the template and will display
the do to the user.
24 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
n The second card overrides the deck-level do element with a noop. The user
agent 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 a
different name attribute.
Card 1
...
Card 2
...
Card 3
...
NOKIA WAP TOOLKIT 25Developer’s Guide Working with WML elements
History stack
You can view the history stack of the Nokia WAP Toolkit by clicking the History
tab at the bottom of the simulator application window. The following figure shows
an 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 a
new 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. Each
time 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 can
change this size under the General tab of the Preference window (see Getting
Started 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.
26 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
Variables and dynamic interfaces
This section discusses how you can set variables explicitly and substitute variables
into WML.
Naming variables
WML variable names consist of an US-ASCII letter or underscore followed by a
zero or more letters, digits or underscores. Any other characters are illegal. Note
also that variable names are case-sensitive. Parentheses are required anywhere the
end of a variable cannot be inferred from the surrounding context, for example, if
the variable ends with an illegal character such as a white space. The following
examples 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 with
a 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 by
using 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-escaped
form %24.
! Note: Variable names are case sensitive. This means that variable1,
Variable1 and varIABle1 are all different variables.
NOKIA WAP TOOLKIT 27Developer’s Guide Working with WML elements
Setting variables
There are a number of ways to set the value of a variable. When a variable is set and
already defined in the browser context, the current value is updated.
The setvar element allows you to set the variable state as a side effect of
navigation. 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 any
information 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 the
chosen option element.
Note that the user input is written to variables when the user commits the input to
the input or select element.
The VAR element specifies a variable name and value, for example:
The variable name specified in the name attribute (for example, location) is set as a
side effect of navigation.
Note the following when setting variables:
n You can change variable values set with WML using WMLScript and vice
versa, 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 the
current browser context.
28 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
Substituting variables
Variable values can be substituted into formatted text, option values and URL
attributes in WML elements. However, note that only textual information can be
substituted, that is, no substitution of elements or attributes is possible. The
substitution of variable values happens at runtime in the user agent. As the
substitution is merely a string substitution operation, it does not affect the current
value of the variable. If an undefined variable is referenced, it results in the
substitution of the empty string.
The following table describes how you can substitute variable values.
Variable reference Explanation
$var or Value of var is substituted using the conversion
$(var) format appropriate for the context.
$(var:e) or Value of var is substituted using URL-escaping.
$(var:escape)
$(var:unesc) Value of var is substituted using URL-unescaping.
$(var:N) or Value of var is substituted without changing the
$(var:noesc) value of the variable.
Note that the use of a conversion during variable substitution does not affect the
actual value of the variable.
If no conversion is specified, the variable is substituted using the conversion format
appropriate for the context. The onenterbackward, onenterforward, href and
src 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 the
WML Specification.
Variable example
The following example demonstrates the use of tasks and variables in WML decks
and cards. Note that the variables will not be set until the user navigates to the
second card of the deck.
Card 1 Contents...
card1 var1 = $(card1_var1)
card2 var1 = $(card2_var1)
NOKIA WAP TOOLKIT 29Developer’s Guide Working with WML elements
Card 2 Contents...
card1 var1 = $(card1_var1)
card2 var1 = $(card2_var1)
When you navigate to the first card of the deck, the following user interface is
displayed:
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 variable
card1_var1 is set.
n Upon entry to the second card, the variable card2_var1 is set and the browser
context is refreshed. Now the user agent displays the following user interface:
Variables with values.
30 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
User input
WML includes two interactive card elements: input and select. The following
sections describe how you can use them to prompt the user for input and how to
handle the input. For more information on text input and select lists, refer to the
WML Reference.
input element
The input element specifies a text entry object. You can determine the format of
the 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:
Entry:
Component Explanation
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 the
result of the user’s text input. This attribute is
required.
default="default" Specifies the default that appears in the entry field.
format="fmt" Specifies an input mask for user input entries. The
default format allows the user to enter any
character. For detailed information on the
available format control characters, see “Specifying
the character format” on page 34.
emptyok="boolean" If you set emptyok to true, the input element
accepts empty input although a format string that
is not empty has been specified. The default is
false.
size="input_size" Specifies the width, in characters, of the text input
area.
maxlength="max_char" Specifies the maximum number of characters that
the user can enter in the text entry area. The
default is unlimited.
tabindex="number" Specifies the tabbing position of the input field.
The tabbing position indicates the relative order in
which elements are traversed when tabbing within
a single WML card.
NOKIA WAP TOOLKIT 31Developer’s Guide Working with WML elements
The following table lists other attributes of the input element. For more detailed
information on the attributes of the input element and how to use it, refer to the
WML Reference.
Attribute Explanation
value="value" Specifies the value of the variable named in the
name attribute. The default and value attributes
are identical in their behavior and syntax.
type="input_type" Specifies the type of the text input area. The
allowed values are text and password. In text
type, input is displayed to the user in a readable
form. In password type, input of each character is
echoed in an obscured form. Note that password
input is insecure and critical application should
not be dependent on it. The default type is text.
title="title" Specifies a title for the input element. The title
may be used in the presentation of this object.
xml:lang Specifies the natural or formal language in which
the document is written.
id Provides an element with a unique name within a
single deck.
class Affiliates an element with one or more classes.
The following deck defines a card requesting the user to enter a name and a card
displaying the name entered.
Enter your name:
Hello $(username)!
32 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
This deck generates the following interface in the user agent (as shown on a 6150
model phone):
Text entry card.
The deck operates as follows:
1 When you navigate to the card, the prompt asks you to enter your name. Press
Options to see the selections. Press Select to go to input card.
2 In the input card that appears, enter your name by using your computer
keyboard or the keypads of the simulator phone. When you are done, press
OK.
3 The first card appears again, with the name you entered. Press OK to go to the
second card of the deck.
The name attribute specifies a variable name to which the phone stores the text that
the user enters in the text entry field. To substitute a variable value at runtime, you
must add a dollar sign ($) in front of the variable name.
NOKIA WAP TOOLKIT 33Developer’s Guide Working with WML elements
Specifying the character format
With the format attribute you can specify the character format in which the user
can enter text input. The following special characters are available:
Character Explanation
A Allows any upper-case alphabetic or punctuation
character, that is, upper-case non-numeric
character.
a Allows any lower-case alphabetic or punctuation
character, that is, lower-case non-numeric
character.
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 choose
to assume that the character is upper-case for the
purposes of simple data entry, but must allow
entry of any character. This is the default format.
m Allows any character. The user agent may choose
to assume that the character is lower-case for the
purposes of simple data entry, but must allow
entry of any character.
*f Allows any number of characters; f is one of the
above format codes and specifies what kind of
characters can be entered. Note that this format
can only be specified once and must appear at the
end of the format string.
nf Allows n characters where n is a number from 1 to
9; f is one of the above format codes and specifies
what kind of characters can be entered. Note that
this format can only be specified once and must
appear at the end of the format string.
34 NOKIA WAP TOOLKITWorking with WML elements Developer’s Guide
Character Explanation
\c Displays the next character, c, in the entry field.
Allows quoting of the format codes so they can be
displayed in the entry area.
For example, let us suppose that you use the
format specifier \(3N\). This instructs the user
agent to automatically insert a left parenthesis
before the user has entered anything, and a right
parenthesis after the user has entered three digits.
The following example is a card that prompts the user for a first name, last name
and age. Note that in the Age field the user can enter a two-digit number.
First name:
Last name:
Age:
select element
A select list specifies a list of options that the user can choose from. WML supports
both single-choice and multiple-choice lists.
The following is a simple example of how to use the select element:
Amount:
German Mark
French Franc
Finnish Markka
US Dollar
German Mark
French Franc
Finnish Markka
US Dollar
= $(conversion)
NOKIA WAP TOOLKIT 35You can also read
