242 Chapter 6 • Web Clipping Obtaining ROM Images from Palm Developers must register with the Palm Alliance Program in order to gain access to ROM images of the Palm OS. Registration is free, and there is no fee to download ROM images.There are several levels of membership with varying degrees of support available. Details on the program, including information on how to join, can be found at www.palmos.com/dev/. U.S. developers may download ROM images from the ROM Image Clickwrap Area of the Resource Pavilion as soon as their electronic registration is completed. However, developers from outside the United States must send a signed agreement to Palm Inc. in order to gain access to ROM images. Once you have obtained a ROM image, we suggest that you save it in the same directory as your POSE for ease of installation. Starting the Emulator To start the emulator, execute the program named Emulator.exe or Emulator, which will be located where you extracted the downloaded archive.There are several options that allow you to start the emulator with different versions of the Palm Operating system, different Palm hardware models, and different amounts of Random Access Memory (RAM). Connecting the POSE to the Internet The Palm VII uses the device’s wireless antenna to connect to the Palm.net net- work via radio waves. Given that the POSE cannot mimic the radio waves emitted and received by the actual device, how do you configure the emulator to connect to Palm.net? In order for the Palm OS emulator to connect to the Internet, you must configure the software so that it may take advantage of the network interface of your desktop computer to connect to a Palm.net proxy server.This will allow the device to use your desktop’s Internet connection to communicate with Palm.net. There are two main steps to setting this up: configuring the device to utilize your Internet connection, and configuring the device to use a Palm.net Proxy Server. 1. Right-click on the emulator window and select Settings and then Properties… (if you are using the Mac OS, use the Preferences item from the Edit menu). www.syngress.com 159_wg_wi_06 10/22/01 4:37 PM Page 242 Web Clipping • Chapter 6 243 2. Check the box Redirect NetLib calls to host TCP/IP (this allows applications to use your desktop network interface rather than the hand- held’s internal library). 3. Reset the emulator. 4. In the emulator, click on the Prefs icon and select Wireless from the selector in the upper-right corner of the emulator’s screen. 5. Make sure the proxy server address is set to either 206.112.114.82 or 206.112.114.83. NOTE The IP addresses of the Palm.net development proxy servers are some- times changed by Palm. You can always find the latest proxy IP addresses and status at www.palmos.com/dev/tech/webclipping/status.html. Palm also hosts a read-only mailing list called Web Clipping Announcements. By subscribing to this list, you will receive e-mail updates containing information pertinent to WCA development. Creating a Web Clipping Project with the WCA Builder Since Web clipping relies on a subset of HTML 3.2, it is possible to build and test your WCA using tools that will already be familiar to you as a Webmaster: a text editor and a Web browser. Remember that there are some differences between how the browsers handle the HTML that will be covered in detail later in this chapter. It should be fairly easy for you to get your feet wet and begin building WCAs, especially if you typically code your HTML by hand. The WCA Builder has three main options from the File menu (see Figure 6.6): Open Index, Rescan HTML, and Create PQA.The Open Index function will open up an HTML page and import it into the WCA Builder.When the WCA Builder opens your index file, it will scan your HTML and automatically include any files that you have linked to into the WCA Builder. Likewise, the WCA Builder will automatically include any images that are referenced in your application. www.syngress.com 159_wg_wi_06 10/22/01 4:37 PM Page 243 244 Chapter 6 • Web Clipping NOTE The Web Clipping Application Builder (WCA Builder) may be downloaded from www.palmos.com/dev/tech/webclipping/gettingstarted.html. Versions are available for both Windows (.zip) and Macintosh Platforms (.sit). A UNIX version is not available. To install, you will need to extract the contents to a folder on your system and run the file called WCABuild.exe (Windows) or WCA Builder (Macintosh). Realistically, once you’ve authored your HTML and saved it to a file, using the WCA Builder is quite simple.All you need to do is drag your index page (containing links to other pages) into the WCA Builder window.The WCA Builder will scan your HTML and will import any pages that you have linked to and add them to your WCA. It will also check your HTML for errors and notify you if there are any bugs in your code. For example, if you omit the action ele- ment of a form tag, or do not use an absolute reference (www.yoursite.com/ cgi-bin/script.cgi), you will be informed of this error when the WCA Builder scans your HTML. The WCA Builder does not validate your code, however, because CML does not require that all elements be closed, properly nested, or even valid HTML ele- ments.The error-checking done by the WCA Builder is minimal and attempts to ensure that your application will function correctly on the handheld device. It will check your code and alert you if it cannot find an image file specified, or if you have an anchor tag without a filename. It will not, however, detect if your href attribute is valid. It is also important to note that a WCA can contain one and only one file with a given filename. Say, for example, that you build the HTML for your WCA using two subdirectories, each containing an HTML page called index.html.This www.syngress.com Figure 6.6 WCA Builder Main Options 159_wg_wi_06 10/22/01 4:37 PM Page 244 Web Clipping • Chapter 6 245 is a fairly common practice, and intuitively it would seem like you would be able to do this in a WCA.The index page we will use to test this contains the following code: <html> <head> <title>Error Test</title> </head> <body> <a href="one/index.html">Untitled</a> <a href="two/index.html">Untitled</a> </body> </html> When you load this file into the WCA Builder, you will receive the error alert shown in Figure 6.7 if directories one and two exist, and if they both con- tain a file called index.html. However, in the event that you do not have these directories created, or that the files do not exist, you will not receive an error from the WCA Builder, but your WCA will not function as expected. This simple example shows that although the WCA Builder can help to reduce the errors in your code, it cannot eliminate them entirely. It is possible to build a WCA that contains bugs even with the code scanning, so be sure to test all of the links and image references in your application. Chances are you are familiar with automated tools that can validate your links, often within your HTML editor (such as BBEdit for the Macintosh, or HomeSite for the PC). Xenu’s link sleuth (http://home.snafu.de/tilman/xenulink.html) is free software that can validate HTML links on local files or Web sites. While the Application Builder program is running, you can make changes to your index page (or other pages), and simply rescan the HTML by pressing F5 or www.syngress.com Figure 6.7 Error for Duplicating Filenames in a WCA 159_wg_wi_06 10/22/01 4:37 PM Page 245 246 Chapter 6 • Web Clipping selecting Rescan HTML from the File menu. Changes on all pages will be implemented into the WCA Builder. When you are satisfied with your HTML, press Control-B or select Build PQA from the File menu, and the WCA Builder will create a file (with exten- sion .pqa) that can be transferred to the handheld device and accessed by Clipper. Now, we will walk through the creation of our first WCA with a Hello, world! program. Hello, World! Traditionally, the first program or page built by programmers in any environment is the familiar and trusty “Hello, world!” program. In this section, we will cover the basics of authoring your first Web clipping application (see Figure 6.8).The purpose of this exercise is to make sure that your WCA Builder is installed prop- erly, and that you are able to install your WCA onto the POSE. Figure 6.8 hello.html <!DOCTYPE HTML PUBLIC "-//POS//DTD WCA HTML 1.1//EN" "http://www.palm.com/dev/webclipping-html-dtd-11.dtd"> <html> <head> <title>Hello, world!</title> </head> <body> <h1>Hello, world!</h1> <p>This web clipping application has been successfully installed!</p> </body> </html> Including the Document Type Definition (DTD) at the top of the document is not required, but it is a good idea to validate your HTML code against the DTD in order to ensure that your code is valid.As the Web (both wired and wireless) moves towards a more standardized environment containing well- formed and valid markup such as XHTML (and subsets), best practices dictate that an appropriate DTD be included with every document. The rest of the code in Figure 6.8 is very straightforward and will generate a page containing a title and a paragraph, shown in a desktop browser in Figure 6.9. www.syngress.com 159_wg_wi_06 10/22/01 4:37 PM Page 246 Web Clipping • Chapter 6 247 Scanning the HTML To have the WCA Builder scan your code and prepare it for compilation into a .pqa file, drag the icon for your file into the WCA Builder window (or select Open Index from the File menu). Figure 6.10 illustrates what hello.html of Figure 6.8 looks like in the WCA Builder. If you make changes to your original HTML file, you can press F5 to rescan the code and update the changes within the WCA Builder. You will notice in that the file sizes of the HTML and of the compressed WCA are displayed in the lower left of the application window.You can tell the size of your application before installing it on the device, a very useful feature. Creating the .pqa File To create your Web clipping application that you want installed on the device, press Control-B or select File | Build PQA from within the WCA Builder. Upon selecting this action, you are presented with a dialog that allows you to save your .pqa file to a directory on your computer (see Figure 6.11). www.syngress.com Figure 6.9 hello.html in a Web Browser Figure 6.10 hello.html in the WCA Builder 159_wg_wi_06 10/22/01 4:37 PM Page 247 248 Chapter 6 • Web Clipping There are several options in the Build PQA dialog box. In addition to Build and Cancel, you have the option of specifying an icon that will be displayed on the device by clicking the Large and Small icon buttons. Should you create custom icons for your application, ensure that the small icon is 15 pixels wide and 9 pixels tall, and that the large icon is 32 pixels wide and 22 pixels tall. You can specify the version of your WCA by changing the value in PQA version.Also, you are able to specify the maximum bit depth that will be used to render the images in your application.The display of images within a WCA is limited by two factors: the display depth of the device, and the bit depth of the images in the application.This feature allows you to ensure consistent presenta- tion of your application on devices with varying display depths by setting the dis- play depth of your application to a lowest common denominator. Installing and Uninstalling the Web Clipping Application on the POSE The easiest way to install an application onto the POSE is to drag the icon for the .pqa onto the window of the emulator program. Also, you can select Install Application or Database from the File menu on the Macintosh and by right- clicking on the emulator window on a Windows PC. To install a WCA on a handheld device, use the HotSync utility as follows: www.syngress.com Figure 6.11 Building the .pqa 159_wg_wi_06 10/22/01 4:37 PM Page 248 Web Clipping • Chapter 6 249 1. Save your WCA to the directory on your desktop that will be used by the HotSync operation. 2. Open the Palm Desktop program on your desktop. 3. Click on Install on the Palm Desktop program.The Install Tool window will pop up. Locate your WCA and Add it.Then click Done. 4. Put your device into its cradle and perform the HotSync operation. 5. Your WCA icon should now appear on your handheld. NOTE If you have the Palm Desktop software installed on your computer, you can install directly to your device by selecting the Install to User option when you build your WCA. To uninstall a WCA that you no longer wish to use from either the POSE or a handheld device: 1. Choose Delete from the App menu. 2. Select your WCA, then select Delete. 3. At the confirmation box, select Ye s. 4. Select Done to return to the application launcher and confirm that the application no longer appears. Viewing the Web Clipping Application Once your application has been installed on the device, you can view it by clicking on its icon. By default,WCAs are placed within the main launcher window and also are included under the Palm.net screen. Figure 6.12 shows the default icon and title for our first application. We can launch the application by clicking on it, which starts the Clipper application and displays our HTML code, as shown in Figure 6.13. www.syngress.com 159_wg_wi_06 10/22/01 4:37 PM Page 249 250 Chapter 6 • Web Clipping Adding Images and Additional Pages to Your WCA It is possible for your WCA to include multiple pages and images.To add an image to your application, you can use the same image syntax as you do for desktop browsers. For example, to add an image to our Hello, world! application, we can create an image in a graphics program such as Adobe PhotoShop or Paint.We then add the following line of code to our page, just as we would for a desktop browser: <img src="myimage.gif"> Figure 6.14 shows what the WCA Builder will look like once we save our changes to hello.html and tell the WCA Builder to rescan the HTML. It is not necessary to drag your images into the WCA Builder to have them included in your WCA.As the HTML of your page is scanned, any images automatically are imported into the WCA Builder. www.syngress.com Figure 6.12 Launching the WCA Figure 6.13 Hello, world! in Clipper 159_wg_wi_06 10/22/01 4:37 PM Page 250 Web Clipping • Chapter 6 251 NOTE You can use images in .gif or .jpg format. The WCA Builder can handle converting either type during the final creation of your WCA. It is not necessary to create images at lower color depths to be able to include them in your application, but there are instances where you may want to optimize the color depth of your images by hand instead of letting the WCA Builder convert them automatically. Likewise, to add additional pages to your WCA, you simply need to link to them in your index page. For example, if we were to add links to two more pages to our WCA, we simply need to create the pages and add links to them using the anchor tag (<a>): <a href="page2.html">Page 2</a><br> <a href="page3.html">Page 3</a> Once we save our changes to hello.html and press F5 in the WCA Builder to rescan our HTML, we will see that the pages have been imported automatically into the WCA Builder, as shown in Figure 6.15. www.syngress.com Figure 6.14 Image Added to the WCA Builder Figure 6.15 Pages Added to the WCA Builder 159_wg_wi_06 10/22/01 4:37 PM Page 251 . (RAM). Connecting the POSE to the Internet The Palm VII uses the device’s wireless antenna to connect to the Palm.net net- work via radio waves. Given that the POSE cannot mimic the radio waves emitted. waves emitted and received by the actual device, how do you configure the emulator to connect to Palm.net? In order for the Palm OS emulator to connect to the Internet, you must configure the software so that. WCA to the directory on your desktop that will be used by the HotSync operation. 2. Open the Palm Desktop program on your desktop. 3. Click on Install on the Palm Desktop program .The Install Tool window