Getting Started

NOKIA WAP TOOLKIT

Version 1.3

http://www.forum.nokia.com Product number: SDK-01-000-001 Version 1.3 November 1999

Getting Started
NOKIA WAP TOOLKIT Version 1.3
Product number: SDK-01-000-001

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 Nokias 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
Nokia WAP Toolkit.............................................................................................................2 User interface simulator.................................................................................................3 Editors ................................................................................................................................3 Debugger ...........................................................................................................................3 Typographical conventions.................................................................................................3 Related documents................................................................................................................4 Documents included in the Nokia WAP Toolkit...................................................4 Other references...............................................................................................................4

Installation...............................................................................................5
System requirements.............................................................................................................5 Installation procedure...........................................................................................................6 Files included in the Nokia WAP Toolkit......................................................................7 Setting the MIME types.......................................................................................................9

Overview of WAP and WML ............................................................. 11

Components of the WAP..................................................................................................11 Introduction to WML ........................................................................................................14 Deck and card.................................................................................................................14 Wireless Markup Language Script...................................................................................15 WML and WMLScript example................................................................................16

Nokia WAP Toolkit ............................................................................. 17

Using the Nokia WAP Toolkit application..................................................................17 Using views.....................................................................................................................19 Modifying WAP Toolkit preferences ......................................................................25 Using the mobile phone display................................................................................33 Handling variables ........................................................................................................35 Entering an URL ...........................................................................................................36 Opening a local file .......................................................................................................36 Creating a simple WML deck...........................................................................................38 Viewing error and status information ............................................................................40 Using bookmarks.................................................................................................................41 Using the WML and WMLScript editor .......................................................................42 Using the WBMP editor ....................................................................................................43

Index ...................................................................................................... 47

NOKIA WAP TOOLKIT

Getting Started

ii

NOKIA WAP TOOLKIT

Introduction

This guide provides information and practical examples for developers who use the Nokia WAP Toolkit tools to create services on the WAP platform. The guide helps you to install and use the Nokia WAP Toolkit software. The Nokia WAP solution brings the content of HTML applications to mobile devices. The user can access public web services and corporate information using a WAP-enabled phone. The WAP gateway transforms the information to a format suitable for mobile networks and devices. The content provider can also create WML applications specifically for the mobile environment.

Internet
WML/WMLScript WAP SDK

HTML/WML

WML/ WMLScript WAP Gateway HTML/WML Corporate Databases Private IP Networks Email, groupware Corporate Web Server

Wireless network

Wireless Application Protocol and Nokia WAP Toolkit.

The Nokia WAP Toolkit offers developers an environment for creating, testing and demonstrating WAP applications. This allows service providers to test the usability of wireless applications and services with customers. The Nokia WAP Toolkit software includes the following:
n n n n

WML and WMLScript encoders WAP simulation client with generic mobile phone user interfaces WAP application debugging support User documentation

NOKIA WAP TOOLKIT

Getting Started

Introduction

The Nokia WAP Toolkit simulates a generic WAP mobile phone (you can choose from three 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 Wireless Markup Language (WML) and Wireless Markup Language Script (WMLScript) services. These services respond to the requests using WML and WMLScript. WML is based on the Extensible Markup Language (XML) and was developed by the Wireless Application Protocol (WAP) Forum for specifying content and the user interface for narrowband devices such as mobile phones. WMLScript can be used to add client side procedural logic to WML cards and decks. The language is based on ECMAScript, but has been modified to better support low bandwidth devices such as mobile phones. You can use WMLScript along with WML to provide intelligence to the client, or you can use it as a standalone tool.

Nokia WAP Toolkit

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

The Nokia WAP Toolkit application for Windows NT 4.0, Windows 95, and Windows 98, which 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 WAP phone user interface simulation module WML and WMLScript encoders WML, WMLScript, and WBMP editors WAP Protocol Stack, HTTP and file access modules Debugging views

An installation utility and practical WML example applications and source code. You can use these samples as a starting point for creating your own services. 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. User documentation in Adobe PDF format, including a Developers Guide and WML and WMLScript language references.

The components of the Nokia WAP Toolkit software can be divided into three main categories, discussed below.

NOKIA WAP TOOLKIT

Introduction

Getting Started

User interface simulator

The simulator application reads the WML or WMLScript and shows the application in the user interface simulation window, simulating the look and feel of a mobile phone user interface.

Editors
WAP applications are created in WML and WMLScript. The Nokia WAP Toolkit includes a text editor for writing WML and WMLScript code. The application data is loaded from a local file. The Nokia WAP Toolkit also includes an editor for creating and modifying WBMP files.

Debugger
The Nokia WAP Toolkit includes a tool that displays useful debugging information such as variable values. The WML browser logic component decodes bytecode and maintains Wireless Application Environment state information such as history and variables.

Typographical conventions
The following typographical conventions are used in this guide:
Notation Courier Explanation

Text that you enter and that appears onscreen, program code, file and directory names, function names. Uniform Resource Locators and commands to be typed exactly as shown. References to other guides and documents, new terminology. Names of Windows menus, commands, buttons and icons.

Courier Bold

Italic

Bold

NOKIA WAP TOOLKIT

Getting Started

Introduction

Related documents
The following documents contain additional information on the Nokia WAP Toolkit and the Wireless Application Protocol. 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 Developers Guide This guide provides information on the Nokia WAP Toolkit and the Wireless Markup Language for developers who want to create their own wireless services on the WAP platform.

WML Reference This guide provides reference information on the Wireless Markup Language (WML). It introduces the WML syntax and provides code examples.

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/ WMLScript Specification. WAP Forum, 16-June-1999. http://www.wapforum.org/ Wireless Application Environment Specification. WAP Forum, 16-June-1999. http://www.wapforum.org/ Wireless Application Protocol Architecture Specification. WAP Forum, 16-June-1999. http://www.wapforum.org/ Wireless Session Protocol Specification. WAP Forum, 16-June-1999. http://www.wapforum.org/

NOKIA WAP TOOLKIT

Installation

This chapter describes the system requirements and installation procedure of the Nokia WAP Toolkit.

System requirements
Before installing the Nokia WAP Toolkit, check that your system meets the following hardware and software requirements.
n

To run the WAP Toolkit application, you need a computer with the following: Windows NT 4.0 with Service Pack 3 running on Intel hardware, or Windows 95, or Windows 98. 266 MHz Pentium or faster processor. 20 MB hard disk space. 64 MB of RAM or more. Display capable of showing 65.000 colors or more. Java Runtime Environment 1.2.2 or later must be installed. You can download it from the Sun Microsystems web site at
http://www.javasoft.com/products/jdk/1.2/jre/index.html

n n

To test services available on the Internet, you need an Internet connection. To test your own services, you need an HTTP 1.1-compliant web server. Note that you can also load the services directly from a local file.

NOKIA WAP TOOLKIT

Getting Started

Installation

Installation procedure
To install the Nokia WAP Toolkit: 1 Make sure you have the most recent copy of the Nokia WAP Toolkit. You can download the most recent copy from the Nokia web site at
http://www.forum.nokia.com

The Nokia WAP Toolkit file that you can download from the web site is a single executable installation file setupex.exe . 2 Run setupex.exe. Choose Run from the Windows Start menu. In the Run dialog box that appears, enter the path of the setupex.exe file and click OK. OR Using the Windows Explorer, browse to the directory where the Nokia WAP Toolkit installation file setupex.exe is located. Double-click the file setupex.exe. 3 Follow the onscreen instructions. Setup has the following buttons at the bottom of the dialogs: Next: Click this to accept the current input and continue with setup. Back: Click this to return to the previous dialog. Cancel: Click this to exit setup. During the Nokia WAP Toolkit installation, the following actions are performed: The Nokia WAP Toolkit files are copied to the specified directory. The default location is C:\Program Files\Nokia\Nokia WAP Toolkit A Nokia WAP Toolkit menu is added to the Programs section of the Start menu. With setup you can also specify another program group.

NOKIA WAP TOOLKIT

Installation

Getting Started

To uninstall the Nokia WAP Toolkit: 1 From the Start menu, select Settings - Control Panel. The Control Panel appears. 2 Double-click the Add/Remove Programs icon. The Add/Remove Programs dialog appears. 3 In the scrolling list, select Nokia WAP Toolkit and click Add/Remove. Confirm that you want to uninstall the Toolkit. The Nokia WAP Toolkit files and registry entries are removed from your computer.

Note: You cannot uninstall the Nokia WAP Toolkit completely by manually deleting the Toolkit files and directories.

Files included in the Nokia WAP Toolkit

The following table gives you an overview of the files and directories in a typical installation of the Nokia WAP Toolkit. The default installation directory is
C:\Program Files\Nokia\Nokia WAP Toolkit

File or directory name _deisreg.isr DelsL1.isu license.txt rel_note.txt

Description

Installation utility. Installation utility. The Nokia WAP Toolkit license agreement. Release Notes for the Nokia WAP Toolkit, provides instructions on using the software and other essential last-minute information on it. The Nokia WAP Toolkit application file. The application can be started from this file; it checks that you have Java Runtime Environment 1.2.2 or later installed and then launches the Nokia WAP Toolkit.

Toolkit.exe

NOKIA WAP TOOLKIT

Getting Started

Installation

File or directory name w3c-http.jar wapsdk.ini wapsdk.jar

Description

World Wide Web Consortiums HTTP Java libraries. Configuration file of the Nokia WAP Toolkit. Executable Java file of the Nokia WAP Toolkit. The application can be started from this file. Contains the server library. WML content encoder Java libraries. Executable Java file of the WMLScript content encoder. WML Document Type Definition file. The documentation of the Nokia WAP Toolkit in Adobe Acrobat format. The directory contains the following files:
devguide.pdf gs.pdf wml_ref.pdf wmls_ref.pdf

waptools.jar wmlencoder.jar WMLScriptEncoder.jar

DTD\wml_1.1.xml docs\

This directory also includes the apidocs.zip file, which contains an api description of the server library.
samples\

Example applications created using WML and WMLScript. The directory contains the following example files:
cloudy.wbmp currency.wml currency.wmlc currency.wmls deck1.wml deck2a.wml deck2b.wml deck3.wml getCapital.wmls mortgage.wml mortgage.wmls MultiCard.wml partcldy.wbmp rainy.wbmp readme.wml sunny.wbmp weather.wml weather.wmlc Welcome1.wml Welcome2.wml Welcome3.wml windex.wml windex.wmls

Server Samples

Contains GenerateWML.java, a simple example showing how to use waptools.jar. See ReadMe.txt for more information.

NOKIA WAP TOOLKIT

Installation

Getting Started

Setting the MIME types

Before creating your own WML services, make sure that your web server supports the following MIME types:
Content MIME type text/vnd.wap.wml image/vnd.wap.wbmp application/vnd.wap.wmlc text/vnd.wap.wmlscript application/vnd.wap.wmlscriptc Extension wml wbmp wmlc wmls wmlsc

WML source Wireless bitmaps Compiled WML WMLScript source Compiled WMLScript

To find out how to set the MIME types for your web server, contact your server vendor.

NOKIA WAP TOOLKIT

Getting Started

Installation

10

NOKIA WAP TOOLKIT

Overview of WAP and WML

This chapter introduces the Nokia WAP Toolkit components and describes how they work together. In addition, the chapter shortly discusses the characteristics of WML and WMLScript.

Components of the WAP

The Wireless Application Protocol 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. The gateway can be physically located in a telecom network or a computer network, building a bridge between the two networks. The following picture illustrates the WAP network structure.

WAP GATEWAY COMPUTER NETWORK IP WIRELESS NETWORK WIRELESS TERMINAL APPLICATION SERVER

WAP

WAP network structure.

NOKIA WAP TOOLKIT

11

Getting Started

Overview of WAP and WML

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 so that the same client application can be run 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 Wireless Markup Language. The browser also has 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:
n n n n

Session layer Transaction layer Security layer Datagram layer

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

Wireless Application Protocol

Wireless Application Environment (WAE) Other Services and Applications

HTTP

Wireless Session Layer (WSP)

2 Wireless Transaction Protocol (WTP) TLS - SSL TCP/IP UDP/IP 3 Wireless Transport Layer Security (WTLS) 4
SMS

Wireless Datagram Protocol (WDP)

Bearers:

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.

12

NOKIA WAP TOOLKIT

Overview of WAP and WML

Getting Started

7 Client
WML WMLScript Etc.

4 WAP Gateway 6
WAP
WML Encoder
WMLScript Encoder

Web Server 5
HTTP
CGI Scripts etc.
Content

Protocol Adapters

WAP network protocol structure.

The WAP is similar to a Web model, and operates as follows: 1 2 The user presses a phone key that has an URL request assigned to it. The user agent sends an URL request to a WAP gateway using the WAP protocol. The WAP gateway creates an conventional HTTP request for the specified URL and sends it to the web server. 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. The web server returns the WML deck with the added HTTP header or the WML output from the CGI or other script application. 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. The user agent receives the WAP response. It parses the WML response and displays the first card of the WML deck to the user.

For more information on the WAP protocol, refer to the guides listed in the section Related documents on page 4.

WML Decks with WMLScript

NOKIA WAP TOOLKIT

13

Getting Started

Overview of WAP and WML

Introduction to WML
The Wireless Markup Language is a page description language that describes how WAP content is presented to the user. With WML you can display information on a mobile phone, give the user input options, and specify how the user agent should respond when the user activates a user interface function or presses a key. For a more comprehensive presentation on the WML language, refer to the WML Reference, included in the Nokia WAP Toolkit.

Deck and card

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 topmost 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

WML deck and cards.

The first example

The following is a simple WML deck containing a single card:
<?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> <!-- 1 --> <!-<!-<!-<!-<!-<!-<!-<!-2 3 4 5 6 7 8 9 --> --> --> --> --> --> --> -->

1 2

The first line is a standard XML instruction required by all XML documents. The second line is the XML document type declaration, also required by all XML documents that use external document types, as does WML.

14

NOKIA WAP TOOLKIT

Overview of WAP and WML

Getting Started

The third 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 <wml> tag and end with a </wml> tag. The following lines define a card containing a start tag and an end tag and text to be displayed to the user.

Note: The id attribute values cannot contain spaces.

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

A WML deck with a single card.

For more information on the WML elements, refer to the WML Reference and Developers Guide.

Wireless Markup Language Script

The Wireless Application Protocol (WAP) includes WMLScript, a scripting language that you can use together with Wireless Markup Language to provide intelligence to the client services. WMLScript can also be used as a stand-alone tool. WMLScript is part of the WAP application layer, and you can use it to add client side procedural logic to WML cards and decks. The language is based on ECMAScript, but it has been modified to better support low bandwidth devices such as mobile phones. With WMLScript, you can overcome the following restrictions of WML:
n n

Check the validity of user input. Access facilities of the user agent. For example, on a mobile phone, allow the programmer to make phone calls, send messages, add phone numbers to the address book or access the SIM card. Generate messages and dialogs locally, thus allowing alerts, error messages, confirmations etc to be seen faster by the user.

Allow extensions to the user agent software and configure a user agent after it has been deployed. For a detailed presentation of the WMLScript, refer to the WMLScript Reference.
n

NOKIA WAP TOOLKIT

15

Getting Started

Overview of WAP and WML

WML and WMLScript example

The next example illustrates a WML deck containing two cards and a WMLScript:
n

The first card (card1 ) calls the WML script random.wmls and requests the function getRandom that generates a random number. The second card ( card2 ) shows the result of the WMLScript operation. The script file random.wmls generates a random number and returns the result to the second card of the WML deck.

n n

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

WML code
<!-- random.wml --> <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 stored in the variable r. Sets the variable RESULT with the random value r . Sends the result to card2 of the WML file random.wml and refreshes its variable values.

n n

extern function getRandom() { var r = Lang.random(100); WMLBrowser.setVar("RESULT", r); WMLBrowser.go("random.wml#card2"); }

16

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

This chapter provides a brief introduction to the Nokia WAP Toolkit application and explains how you can use the Nokia WAP Toolkit to work with simple static WML decks.

Using the Nokia WAP Toolkit application

The Nokia WAP Toolkit application allows you to view WML services just as they would be presented to an actual user with a WAP mobile phone. You can choose to view different mobile phone models, as explained in Modifying WAP Toolkit preferences on page 25. Note that the 6110 and 6150 mobile phones are not real products, but the 7110 mobile phone is. The Nokia WAP Toolkit includes system-wide Undo, Redo, Cut, Copy, and Paste functionality in all editors and text-viewers. You can use the Undo and Redo functions for up to 100 operations in both the text editor and the WBMP editor.

To start the Nokia WAP Toolkit: 1 Connect your computer to the Internet. You can view local WML and WMLScript files with the WAP Toolkit application. To use resources outside your local network, you must have an Internet connection. 2 3 Make sure you have installed Java Runtime Environment 1.2.2 or later. From the Start menu, select Programs -> Nokia Wap Toolkit -> Toolkit. OR If you are running on Windows NT, go to the command line, switch to the Nokia WAP Toolkit installation directory and type the following command:
java -jar wapsdk.jar

NOKIA WAP TOOLKIT

17

Getting Started

Nokia WAP Toolkit

Note: Windows NT sets the PATH variable in a different area than Windows 95 and Windows 98. If you are running the Nokia WAP Toolkit on a Windows 95 or Windows 98 system and want to start from command line, you must set the java.exe in your PATH variable.

The Nokia WAP Toolkit window appears as shown in the picture below. The Nokia phone displays a short welcome message.

Location toolbar

6150 mobile phone

Navigation keys

Keys for text entry Debug level control Simulator view tabs
The Nokia WAP Toolkit application with the 6150 mobile phone.

18

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Using views
The Nokia WAP Toolkit application contains six tabbed views that you can open by clicking the tab at the bottom of the application window. If you cannot see the tabs, select Show on the Toolkit menu and check that the tabbed views are checked as follows:

To make a view active, click its name. An active view is indicated by a check mark in front of the view name.

Messages
The Messages view contains the error and status log, allowing you to view any errors that occur in the WML and WMLScript compilation. You can also define the logging level.

Variables
The Variables view shows all the variables that are set in the active WML or WMLScript. For example, when you open the mortgage.wml file delivered with the Nokia WAP Toolkit and accept the default values, the application generates the Variables view as follows:

The Variables view allows you to add, edit, and clear variables with the utilities at the bottom of the view.

NOKIA WAP TOOLKIT

19

Getting Started

Nokia WAP Toolkit

History
The History view displays the history stack of the current browser context, that is, all the cards you have visited in the current browser context. The view also contains buttons for navigating to a selected URL and clearing the history stack. Assume that you visit the following decks in the following order: 1 2
Currency.wml MultiCard.wml. Note that this deck contains two cards that are activated

through a timer. Now the history stack would look as follows:

The stack puts the URL of the last card visited at the top of the stack. Card3 and card2 of MultiCard.wml were activated by a timer without the user having to navigate to them. Note that the size limit is indicated near the bottom of the view. You can set this size limit in the General tab of the Preferences dialog (see Modifying WAP Toolkit preferences on page 25 for more information). If the number of URLs visited exceeds the size limit, the oldest URL is dropped from the list.

20

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

WML Deck
The WML Deck view shows the code and size of the active WML or WMLScript. For example, when you open the file currency.wml provided with the Nokia WAP Toolkit, the deck code will be displayed in the WML Deck view as follows:

The WMLDeck view contains a drop down menu that allows you to select different views of the deck:
n n

The decoded deck. The original source. If the original sources is not available (for instance, when a binary WML file is loaded), the decoded deck displays in this view. The undecoded bytecode.

For example, the following figure shows the original view of the currency.wml file.

NOKIA WAP TOOLKIT

21

Getting Started

Nokia WAP Toolkit

Original source.

The next figure shows the undecoded bytecode view of the same deck.

22

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Undecoded bytecode view.

Bookmarks
The Bookmarks view contains your browser bookmarks. The view allows you to create and delete bookmarks and to navigate to a selected bookmark.

NOKIA WAP TOOLKIT

23

Getting Started

Nokia WAP Toolkit

Editor
The Editor view allows you to edit existing WML and WMLScript files and to create new files. When you choose to edit a source file or to create a new file, a new tabbed view appears at the bottom of the Nokia WAP Toolkit application window. The view is labeled Editor, or if you are editing an existing file, it is named after the file. In this view you can edit and compile WML and WMLScript code and update the phone display to view the compiled code. For example, when you open mortgage.wml , the code is displayed as follows:

24

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Session
The Session view contains a table with three columns:
n n n

URL lists the URL that was loaded. MIME-Type lists the URL's MIME-type. Size lists the number of bytes loaded.

Each time a new location is laded, an entry is added to the table. The Total Size number in the lower right corner is the sum of the Size column. The Reset button clears the table and the Total Size value.

Modifying WAP Toolkit preferences

The Nokia WAP Toolkit preferences allow you specify various details of the software, for example, the URL of your HTTP proxy.

To open the Nokia WAP Toolkit preferences:

n

From the Toolkit menu, select Preferences.

The Preferences dialog has three tabs:

n n n

Communication Encoding General

NOKIA WAP TOOLKIT

25

Getting Started

Nokia WAP Toolkit

On the Communications tab you can choose whether the Nokia WAP Toolkit uses HTTP directly to access URLs from the network, or uses WSP protocols to communicate through a WAP Gateway, which fetches URLs from the network on the Toolkits behalf and then returns the encoded response. The first method is simpler and more direct. The second method more closely simulates the actual transmission path of a WAP-enabled phone. Note, also, that if the Nokia WAP Toolkit is running phone software directly that uses an imbedded protocol stack, you must use Gateway mode. Each communication mode, HTTP and Gateway, has a set of parameters you must specify.

26

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

If you choose HTTP, the Nokia WAP Toolkit issues HTTP requests directly. There are three optional HTTP client features you may turn on or off:
n

To enable use of HTTP cookies, check the appropriate box. Any Set-Cookie headers received with HTTP responses will be saved, and future HTTP responses that qualify (i.e., are in the same realm) will include an appropriate Cookie header. Note that you must restart the Nokia WAP Toolkit for this change to take effect. To enable the HTTP cache, check the appropriate box. This enables a (nonpersistent) cache that obeys the standard HTTP caching rules. Caching reduces the need to decode files on each access, and makes navigating backwards faster. Note that you must restart the Nokia WAP Toolkit for this change to take effect. To use HTTP Authentication, check the appropriate box. This causes the Nokia WAP Toolkit to follow the HTTP Basic authentication protocol, prompting (through the phone interface) for a user ID and password when it receives an Unauthenticated error from a request. To have the Toolkit go through an HTTP proxy, check the appropriate box. You also must enter the URL of the proxy server in the HTTP Proxy URL field.

If you choose WAP Gateway, all requests are WSP-encoded and sent, using WSP Protocols, to a WAP Gateway. If you use this mode, you must specify the server address, the connection mode, and the port on which the Gateway is listening. In the Gateway Settings box:
n n

Enter the IP address of the host on which the gateway is running. Choose either Connectionless mode or Connection-oriented mode by checking the appropriate box. Connectionless mode is a simple, unreliable protocol. Connection-mode is a reliable, more heavy-weight protocol (see the WAP WSP Specification for more details.) The WAP Gateway supports both types of connections (both are unsecure). The Nokia WAP Toolkit does not currently support either secure Connectionless or secure Connection-oriented mode.

Enter the port number for the selected connection mode. The default ports are 9200 for Connectionless and 9201 for Connection mode. You will need to get the correct port number from your WAP Gateway administrator.

For more information on the WAP Gateway, see Nokia WAP Server Getting Started. On the Encoding tab, you can choose to use fast encoding and pick a character set.

NOKIA WAP TOOLKIT

27

Getting Started

Nokia WAP Toolkit

To use fast encoding, check the box. While using fast encoding, you will see only limited error messages. To see all error messages, do not use fast encoding. From the Character Set list box, select a character set used in the Nokia WAP Toolkit if the HTTP header does not specify any character set. Note that the editor uses the specified character set when you compile it.

On the General tab, you specify WML access element, history size limit, and model of mobile phone.

28

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

To enable the use of the WML access element, check the appropriate box. Enabling the access element may cause difficulties when testing services with access elements. Therefore we suggest that you do not enable the use of access elements when testing such services. To set the size number of entries that display in the History view, enter a number in the WML History Size box. From the Phone Model list box, select a model of the mobile phone to display in the Nokia WAP Toolkit application window.

Note: If the mobile phone does not display, select Show from the Toolkit menu and click WAP Device

You can choose to view different phone models. Note that the 6110 and 6150 mobile phones are not real products, but the 7110 mobile phone is. If you choose the 7110 mobile phone, you should note the following:

NOKIA WAP TOOLKIT

29

Getting Started

Nokia WAP Toolkit

The 7110 model is not available with Nokia WAP Toolkit versions prior to 1.3. When the 7110 model is active, certain Nokia WAP Toolkit features are disabled, such as the WML Deck and Session tabs. To use the 7110 model mobile phone so that it can access WML cards from the WAP Gateway, see the Setting Up Nokia 7110 Phone document for instructions. The following figures show the display for each mobile phone model.

Scroll up

Scroll down

Soft keys

6110 model mobile phone.

30

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Soft keys

Scroll up Select Scroll down

6150 model mobile phone.

NOKIA WAP TOOLKIT

31

Getting Started

Nokia WAP Toolkit

Power button

Soft keys

Roller

7110 model mobile phone.

32

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Using the mobile phone display

You use the soft keys and number pad on the mobile phone display to:
n n n n

Choose from menus Navigate backwards through the card history Navigate to the home deck Enter text and numbers

Navigating to the home deck

The Nokia WAP Toolkit provides a way to navigate to the home deck specified in the WAP Toolkit Preferences.

To navigate to the home deck:

n

From the Go menu, select Home.

Navigating backwards
The Nokia WAP Toolkit provides several ways to navigate backwards through the card history.

To navigate backward to the card visited previously:

n

Click the Back button on the WAP phone simulator to return to the card you visited last. From the Go menu, select Back to return to the card you visited last. Click the drop-down arrow on the location toolbar to open a list of previously visited decks. From the list, select a deck you visited previously. Click the History tab at the bottom of the application window. In the view, select the URL that you want to navigate back to and click Go. Note that the history stack only contains the decks that you have visited in the current browser context.

n n

NOKIA WAP TOOLKIT

33

Getting Started

Nokia WAP Toolkit

Using menus
To choose an item from the options menu: 1 2 Click the button with the up and down arrows to highlight the item you want. Click the Options button to the left of the arrows button. The options menu opens, where you select further actions. Note that if you have specified only one soft key action, the soft key is directly available, and the Options button is not displayed.

Entering characters in the phone display

To enter text and numbers in the phone display, click the mouse on the phone number keys, or use your computer keyboard. With the phone number keys, you can enter both numbers and letters depending on the entry format allowed. A label in the upper left corner of the phone display indicates the entry format. For example, if you are allowed to enter only numbers, the label is [123].

To enter text with the phone number keys:

n

To type a K, click on the number key 5 rapidly until the letter K appears.

The following table shows the characters that you can enter with each key. 1 .,?!2 ABC 5 JKL 3 DEF 6 MNO 9 WXYZ #

4 GHI 7 PQRS

8 TUV 0_ SPACE

*+

To change between uppercase and lower-case characters, press #.

34

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Handling variables
The Nokia WAP Toolkit allows you to handle variables in the Variables view. In this view you can set, edit and clear variables.

To set a variable: 1 2 3 4 In the Name field, type a name for the variable to set. In the Value field, type a value for the variable. Click Set. The variable appears in the variable list. From the Go menu, select Refresh Card. This updates the variable values of the current deck.

To edit a variable: 1 2 3 4 In the variable list, click the variable you want to edit. Edit the Name and Value fields. Click Set. From the Go menu, select Refresh Card. This updates the variable values of the current deck.

To clear all variable values:

n

Click Clear all. Note that this clears the values of the current browser context only.

NOKIA WAP TOOLKIT

35

Getting Started

Nokia WAP Toolkit

Entering an URL
The Nokia WAP Toolkit provides two ways to enter URLs.

To request a specific URL:

n

Type the URL in the Location field and press Enter on your computer keyboard. For example, http://www.acme.com. From the Go menu, select Load location. The following dialog appears:

In this dialog, enter the URL and click Open.

Opening a local file

The Nokia WAP Toolkit provides two ways to open a local WML or WMLScript file.

To open a local WML or WMLScript file:

n

Type the URL of the file in the Location field and press Enter on your computer keyboard. For example, file:///d:\WMLExamples\myfile.wml .

36

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

n

Getting Started

From the Go menu, select Load file. The following dialog appears:

By default, the dialog displays the contents of the samples directory under the WAP Toolkit installation directory. Select a file and click Open. If the file that you want to open is stored at another location, click the dropdown arrow in the Look in field and browse to the desired location.

NOKIA WAP TOOLKIT

37

Getting Started

Nokia WAP Toolkit

Creating a simple WML deck

This section describes the steps you must follow to create and test a static WML deck. 1 From the File menu, select New. Select WML Deck. The following interface appears:

Note that the WAP phone display does not show the deck until you update the display by clicking Show. 2 Create the WML. For example, create a file wmltest.wml containing the following WML:
<wml> <card id="First_Card" title="First Card"> <p> The first WML example </p>

38

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

</card> </wml>

Getting Started

The section The first example on page 14 provides a line-by-line description of this deck. 3 From the File menu, select Save to save the deck. In the dialog that appears, specify a name for the WML file, for example wmltest.wml .

Note: Make sure you save the file as a text-only file and that you save it to a filename ending with the extension .wml.

Update the WAP phone display by compiling the deck (click COMPILE) and then clicking Show. After the update, the phone displays the WML file as follows:

Note: If the WAP phone simulator does not display the card correctly, there may be an error in the WML. See the following section for instructions on checking error messages.

In the Editor view you can also compile the WML code into binary format.

NOKIA WAP TOOLKIT

39

Getting Started

Nokia WAP Toolkit

Viewing error and status information

The Nokia WAP Toolkit application views status and WML error messages in the Messages view of the simulation window. To open the view, simply click on the Messages tab at the bottom of the window. If the Messages tab is unavailable, select the Show on the Toolkit menu and click on Messages to activate the Messages view. An active page is indicated by a tick mark in front of the view name.

To select the error message level: 1 2 Click the Messages tab to open the Messages view. Click the drop-down button in the Message Level box. This opens a dropdown selection list containing six message levels: Detail this generates the most detailed log. Debug Normal Warning Error Critical this generates only the most important messages. 3 Choose a level by clicking on its name in the drop-down list.

To clear the browser message log:

n

Click Clear at the bottom of the Messages view.

40

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Using bookmarks
With the Nokia WAP Toolkit, you can add and edit bookmarks.

To add a bookmark:
n

From the Toolkit menu, select Add Bookmark. This adds the current URL to your bookmarks.

To edit bookmarks: 1 Click the Bookmarks tab at the bottom of the application window. This opens the Bookmarks view, allowing you to edit your bookmarks.

In the above example, the bookmarks already include two decks. 2 Click the bookmark field that you want to edit and write the new value directly to the field. To add a new bookmark, click New. This adds a new blank bookmark at the end of the bookmark list. To navigate to the selected bookmark, click Go. To delete the selected bookmark, click Delete.

NOKIA WAP TOOLKIT

41

Getting Started

Nokia WAP Toolkit

Using the WML and WMLScript editor

With the WML and WMLScript editor provided with the Nokia WAP Toolkit you can create new services and edit existing ones.

To edit an existing file: 1 From the File menu, select Open. The Open dialog appears. 2 Browse to the file that you want to edit, select the file, and click Open. The file opens in the WML and WMLScript editor. 3 4 Edit the file and save it by selecting Save on the File menu. Click Compile to convert the code into binary format. The compiled file appears in the same directory where the current file is located. The extensions of the compiled files are the following: wmlc compiled WML. wmlsc compiled WMLScript. 5 Click Show to update the WAP phone display to view the code you edited.

To create a new file: 1 From the File menu, select New. Select WML Deck if you are creating a WML file. Select WMLScript if you are creating a WMLScript file. 2 Follow the instructions on creating a new static WML file described in Creating a simple WML deck on page 38.

Note: Make sure you save the file as a text-only file and that you save it to a filename ending with the appropriate extension: wml for WML files, wmls for WMLScript files.

42

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

Using the WBMP editor

The WAP standard specifies an image format called WBMP. The Nokia WAP Toolkit includes a WBMP editor that you can use to:
n n n n

Create new WBMP images of any size. Open existing WBMP images in the editor and modify them, as necessary. Import GIF and JPEG images and convert them into WBMP. Draw pixels, straight lines, boxes and ellipses with outlines in black or white of variable thickness and with a choice of fill-in patterns. Zoom in and out of the image in the editor. Cut, copy, and paste selected regions of the image. Write the finished WBMP images to file.

n n n

You can use the WBMP images in your WAP services. For example, the weather.wml file uses bitmaps as shown in the following display:

To create a new bitmap file: 1 2 From the File menu, select New. Select WBMP Image. A dialog box displays, in which you indicate the dimensions of the new bitmap.

Enter the width and height, in pixels.

NOKIA WAP TOOLKIT

43

Getting Started

Nokia WAP Toolkit

3 Undo

The WBMP editor interface appears. Redo Copy Select a region Draw a line Line color Fill pattern

Cut

Paste

Draw a pixel

Draw a box

Draw an ellipse

Line width

Zoom control box 4 5

X and Y coordinates of cursor

Use the various tools to create your bitmap image. To save the image, on the File menu, select Save.

Note: Make sure you save the file to a filename ending with the extension .wbmp.

44

NOKIA WAP TOOLKIT

Nokia WAP Toolkit

Getting Started

To edit an existing bitmap image: 1 From the File menu, select Open. The Open dialog appears. 2 Browse to the file that you want to edit, select the file, and click Open. The file opens in the WBMP editor. 3 Edit the image and save it by selecting Save on the File menu.

NOKIA WAP TOOLKIT

45

Getting Started

Nokia WAP Toolkit

46

NOKIA WAP TOOLKIT

Index

6
6110 mobile phone, 30 6150 mobile phone, 31

G
Gateway settings, 26

H
History view, 20 Home deck, 33 HTTP settings, 26

7
7110 mobile phone, 29, 32

B
Backwards navigation, 33 bitmap images, 43 Bookmarks, 41 Bookmarks view, 23

I
image editing, 43 Installing WAP Toolkit, 6 Introduction to WML, 14

C
Card, 14 card element, 14 Character map, 34 Creating WML, 38

L
Letters, 34 Local file, 36 Logging, 40

M
Messages view, 19 mobile phone display, 33 mobile phone, model 6110, 30 mobile phone, model 6150, 31 mobile phone, model 7110, 29, 32

D
Deck, 14

E
editing bitmap images, 43 editing images, 43 Editor view, 24 Entering characters, 34 Error information, 40

N
Navigating backwards, 33 to a local file, 36 to an URL, 36 to the home deck, 33 Numbers, 34

F
Files of WAP Toolkit, 7

NOKIA WAP TOOLKIT

47

Getting Started

Index

O
Opening local file, 36 URL, 36 Option item, 34

Views Bookmarks, 23 Editor, 24 History, 20 Messages, 19 Session, 25 Variables, 19 WML Deck, 21

P
Preferences, 25

W
WAP Toolkit components, 2 files included, 7 installation, 6 installing, 5 preferences, 25 system requirements, 5 uninstalling, 7 using, 17 WAP TOOLKIT user interface, 11 WBMP editor, 43 Wireless Markup Language, 2 Wireless Markup Language Script, 2, 15 WML. See Wireless Markup Language card, 14 card element, 14 creating, 38 deck, 14 testing, 38 wml element, 14 WML Deck view, 21 wml element, 14 WMLScript. See Wireless Markup Language Script

R
Related documents, 4

S
Session view, 25 Starting the Nokia WAP Toolkit, 17 Status information, 40 System requirements for WAP Toolkit, 5

T
Testing WML, 38 Text, 34 Typographical conventions, 3

U
Uninstalling WAP Toolkit, 7 URL, 36 User interface, 11 Using bookmarks, 41 Using menus, 34 using the WBMP editor, 43

V
Variables view, 19

48

NOKIA WAP TOOLKIT