212 Chapter 5 • Wireless Development Kits pane shows the current project files and lets you navigate through various ele- ments of the WML deck you are currently working with.The bottom-left pane shows information about the current element you have selected: card titles, the WML version of the deck, and so on.The right pane shows the source of the current WML deck. Finally, the bottom pane shows you status messages about the WapIDE, such as validation errors in WML decks. Accessing and Editing Local Files Let’s create a new project and add our hello.wml file. From the main window, choose the File | New | New Project menu item.You will be asked if you want to save the changes to the current project; unless you have already been working on a project that you wish to save, click No.You will then be prompted with the dialog box to fill in information about your project.We set ours up as shown in Figure 5.23. You can use three different methods to accomplish most tasks in the WapIDE: menu choices, the toolbar, and keyboard shortcuts. Let’s focus on the menu choices, and you can explore the other two options on your own.To add a new WML file to the project, select File | New | New WML Deck from the menu bar. Now, you can edit the WML deck to contain the text you want.You can edit the file in the right pane. Go to the spot after the open <p> element and insert the text “Hello World!” into the file.Also add the ID and title attributes to the card so that the hello.wml file looks like this: <?xml version="1.0"?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd"> www.syngress.com Figure 5.23 Creating a New Project in the Ericsson WapIDE 159_wi_wg_05 10/22/01 4:35 PM Page 212 Wireless Development Kits • Chapter 5 213 <wml> <card id="hello" title="Hello World"> <p>Hello World! </p> </card> </wml> The editor will not show you updated information about the WML deck until you validate it.You can validate the file by selecting the Tools | Validate “hello.wml” menu option. Once you validate your document, the left panes will be updated with the information you just typed in, as shown in Figure 5.24. We can now view the document in a WAP device by selecting the Tools | Test “hello.wml” menu option This will launch the WapIDE browser in a new window with the hello.wml file we just created. Figure 5.25 shows the R520m with our new deck in it. www.syngress.com Figure 5.24 Updated WML Deck Information in the Ericsson WapIDE 159_wi_wg_05 10/22/01 4:35 PM Page 213 214 Chapter 5 • Wireless Development Kits Notice that a Back button is not included by default. Ericsson browsers require you to explicitly put in WML to perform backward navigation if you want it to be available to the user. Each card from which the user can navigate backwards requires the following piece of code: <do label="Back" type="prev"><prev/></do> Not all browsers require this, but be careful not to omit it because you could end up with areas of your WAP site that users cannot get out of. If the browser provides a Back button by default, it will simply ignore this portion of WML code. Accessing Files through a Gateway The browser component can retrieve files locally on your file system or on the network through a gateway.The default behavior is to use the public gateway Ericsson has set up for Developer Zone members, but you can use any gateway you have access to. Ericsson provides information on their Web site for down- loading and installing their gateway on your local machine.We add the Ericsson gateway to our configuration even though it is included by default, just to run you through the steps required. Select the View | Settings menu option from your browser window.You will see a configuration dialog box with multiple tabs across the top. Select the Gateway tab then click Add to create a new gateway entry. Fill out the name as DevZone and enter the IP address 195.58.110.201.The gateway that Ericsson provides does not require a username or password, so leave those fields empty. When you click OK, you will be taken back to the gateway selection screen. www.syngress.com Figure 5.25 Ericsson R520 Emulator Viewing hello.wml 159_wi_wg_05 10/22/01 4:35 PM Page 214 Wireless Development Kits • Chapter 5 215 From the pull-down list, select the DevZone entry and then click OK at the bottom of the dialog box to save your changes. Now, whenever you request a document from a network address using HTTP, it will request the file from the gateway, and the gateway will actually retrieve the document before sending it back to you. Debugging Techniques The WapIDE provides good error messages that help you debug your application. Let’s take our simple WML file and remove the </p> element, so that our para- graph line looks like this: <p>Hello World! When we validate this file, we get some error messages in the bottom pane, as shown in Figure 5.26. This is pretty good information.We know that we opened a paragraph ele- ment and did not close it.The line numbers and columns that are reported match up with the next tag it encountered, but the message is clear and points outs the www.syngress.com Figure 5.26 Ericsson WapIDE with Error Messages 159_wi_wg_05 10/22/01 4:35 PM Page 215 216 Chapter 5 • Wireless Development Kits problem quite well—even if it does miss the location a bit. If we correct the problem and revalidate, we get a comforting message indicating that no errors were found. The WapIDE does not provide information such as cache status, variable values, or compiled WML size.This is unfortunate because the rest of the envi- ronment is nice for building and testing applications.You can open the Trace window to view information about the current status of the emulator, which can be helpful when you are trying to track down a network problem. The WapIDE allows you to clear the device cache or disable caching alto- gether.This is handy during repetitive testing, but be sure to test your application with caching on once you believe it is working.You can reach the cache setup by selecting View | Settings from the browser window and going to the Cache tab, as shown in Figure 5.27. The Yospace SmartPhone Emulator 2.0 The Yospace SmartPhone Emulator Developer Edition is the only SDK in our lineup that isn’t developed by a browser manufacturer.This Yospace SmartPhone Emulator is designed to emulate browsers from multiple vendors simultaneously, thus speeding up your development.The SmartPhone Emulator is written entirely in Java; you can run it on any platform that has a Java 1.1.8 compatible VM installed (this includes Java2 VMs).This is the only SDK we’ve looked at that is truly cross-platform. Linux,Apple MacOS, Sun Solaris, and Microsoft Windows are all known to work well with the SmartPhone Emulator. www.syngress.com Figure 5.27 Cache Settings for the WAP Browser in the Ericsson WapIDE 159_wi_wg_05 10/22/01 4:35 PM Page 216 Wireless Development Kits • Chapter 5 217 Installing the Yospace SmartPhone Emulator Many versions of the SmartPhone Emulator are available from Yospace.The Developer Edition is for use on your local machine to access files both remotely or on your local file system and is the one that we installed.The Web Site Edition allows you to demo your WAP application to people who visit your site with a regular Web browser.You can use the JavaBean Edition to build your own appli- cation that can access WAP services by emulating popular handsets. We cover only installing the Windows version of the SmartPhone Emulator Developer Edition.The instructions for other platforms are documented on the Yospace Web site at www.yospace.com.We go step-by-step through the system requirements, downloading the SmartPhone Emulator, and installing it on your computer. System Requirements for the Yospace SmartPhone Emulator The Yospace SmartPhone Emulator is written entirely in Java and can therefore be run on any computer system that has a Java 1.1.8 or compatible VM installed.As mentioned earlier,Yospace has packaged the SmartPhone Emulator in installation programs for Microsoft Windows,Apple MacOS, Solaris, and Linux/other UNIX platforms. If you download the Windows or MacOS version, you can choose to download it without the JVM if you already have one installed on your system. Yospace gives no specific processor or memory requirements because the software can run on such a wide variety of machines. If you find the program doesn’t run fast enough perhaps you should get a faster processor or add more memory.With that said, the Windows install program that we used is a Win32 application, so you must have Windows 9x, Me, NT, or 2000 to install the software. Obtaining the Yospace SmartPhone Emulator You can download the SmartPhone Emulator from the Yospace Web site at www.yospace.com in the Products section.Yospace requires you to register in order to download the software. Once you download the software,Yospace will e-mail you a license that is good for five days.After this license expires, you will need to purchase a license from Yospace to continue using the software. www.syngress.com 159_wi_wg_05 10/22/01 4:35 PM Page 217 218 Chapter 5 • Wireless Development Kits Installing the Yospace SmartPhone Emulator You will download a file called SPEDE2_0.zip, which contains one file, from the Yospace Web site. Unzip it with a zip extractor such as WinZip (www.winzip.com) or Aladdin StuffIt Expander (www.aladdinsys.com). Run the spede2_0.exe appli- cation (which is the file that you extract) and, after some initial splash screens, you will be greeted with a dialog box requiring you to accept the license agreement for the SmartPhone Emulator. If you agree with the terms of the license, click Ye s and then click Next to continue the installation process.You can accept the default installation location on the next screen and then click Install to start the actual copying of files to your computer.The software will be installed while a dialog box like the one shown in Figure 5.28 updates you on the status of the installation. Once the installation completes, click Done, and the software is installed. Developing with the Yospace SmartPhone Emulator You can now start the SmartPhone Emulator by choosing Programs | SmartPhone Emulator | SmartPhone Emulator 2.0 from the Start menu. The first dialog box you see will ask you for your name, e-mail address, and license key.These must match the registration info you gave to Yospace.You will only be asked for this information when you first run the program or the license expires.The license screen is shown in Figure 5.29. You can choose what mode you would like to run the program in from this screen: Development Mode or Display Mode. Display Mode shows just one emu- lator in its own window so that you can demo your WAP application without www.syngress.com Figure 5.28 The Yospace Installation Screen 159_wi_wg_05 10/22/01 4:35 PM Page 218 Wireless Development Kits • Chapter 5 219 having a complete development environment cluttering the screen. Development Mode is where we spend most of our time. It allows you to view multiple emu- lators at the same time, load a file or location into multiple emulators with one command, and view variable names and values and other status information. The initial window may seem intimidating at first, but figuring it out is quite easy. Figure 5.30 shows the default workspace when you start in Development Mode. www.syngress.com Figure 5.29 Yospace SmartPhone Emulator License Screen Figure 5.30 Default Development Mode Workspace 159_wi_wg_05 10/22/01 4:35 PM Page 219 220 Chapter 5 • Wireless Development Kits The windows in the main part of the screen are emulators for various mobile phones.The SmartPhone Emulator allows you to create and save groups of emu- lators as workspaces.You can have one workspace per manufacturer, per browser type (UP.Browser, Nokia Browser, and so on), or any other scheme you can come up with.You can save these workspaces and recall them later when you need to test the same combination of devices again. The default workspace includes an Ericsson R380, Ericsson R320, Nokia 6210, and Motorola Timeport. Because it includes multiple devices, you must tell the SmartPhone Emulator which emulator you want to work with.You can select the emulator window or its corresponding name from the list in the top- right pane. If you select the Workspace, everything you do will apply to all the emulators. Select the Workspace as shown in Figure 5.30 before we start loading files in the next section. Accessing and Editing Local Files You will have to use a separate text editor to create WML and WMLScript files. The Yospace SmartPhone Emulator does not include text-editing capabilities.We use the same file we created in other examples and saved as c:\wap\hello.wml. If you haven’t already created it, save the following WML deck to that location: <?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="hello" title="Hello World!"> <p> Hello World! </p> </card> </wml> Load this file into all the emulators at once by selecting the File | Open File menu option.This will bring up a dialog box asking what file to load. Find and select our file (c:\wap\hello.wml) and click Open to load the file in all the emulators.You can see how easily you can view your WAP application on mul- tiple devices with the SmartPhone Emulator. Accessing Files through a Gateway The Yospace SmartPhone Emulator does not allow you to change the gateway used to access WAP content.The gateway functionality is encapsulated in the www.syngress.com 159_wi_wg_05 10/22/01 4:35 PM Page 220 Wireless Development Kits • Chapter 5 221 emulators.This is unfortunate because testing through multiple gateways is a good way to find many problems. Debugging Techniques The Yospace SmartPhone Emulator provides very precise debugging information. Let’s break the hello.wml file so that it does not close the paragraph element.The resulting file looks like this: <?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="hello" title="Hello World!"> <p> Hello World! </card> </wml> We have to empty the cache before we reload the file by selecting the Workspace | Empty Cache menu option.Then we can load our file the same way we did before.This time, every emulator will give you an error message. These error messages are exactly what each individual phone would show you if you were holding it in your hand—not very informative. However, a new mes- sage appears in the status bar along the bottom of the window:“! Last Error: 502.” Click on this message and a dialog box (shown in Figure 5.31) will appear giving you more detailed information about the problem. The error message tells us that the paragraph tag on line 6 does not have a corresponding close tag.This is the most descriptive error message from any of the SDKs we’ve looked at.Although the error message is clear, it is somewhat difficult to find inside the variety of HTTP status messages.This is especially confusing because we were loading a local file.The extraneous error messages are www.syngress.com Figure 5.31 Yospace SmartPhone Emulator Invalid WML Error Dialog Box 159_wi_wg_05 10/22/01 4:35 PM Page 221 . file to the project, select File | New | New WML Deck from the menu bar. Now, you can edit the WML deck to contain the text you want.You can edit the file in the right pane. Go to the spot after the. you to accept the license agreement for the SmartPhone Emulator. If you agree with the terms of the license, click Ye s and then click Next to continue the installation process.You can accept the. Chapter 5 • Wireless Development Kits The windows in the main part of the screen are emulators for various mobile phones .The SmartPhone Emulator allows you to create and save groups of emu- lators as