How to Build Your Own Web Clipping

You've heard the hype: By the end of this year, practically every inanimate object—from your refrigerator to your shoes—will be connected via the Wireless Web. Most have already experienced the Wireless Web in the form of a 1-inch square WAP phone or a portable device, like a Palm handheld organizer. But, apart from services like AvantGo, there's no way to access online information with your Palm once it's removed from its cradle. Enter the Palm Connected Organizer.

When Palm introduced the wireless Palm VII in October 1999, they needed something besides email to jump-start market demand. What they came up with was Web Clipping.

What Is Web Clipping?

Web Clipping is a proprietary method of providing access to online resources from a Palm OS device—including the Palm VII or Palm V with OmniSky modem. It's built around the concept of "Application Partitioning," so part of the application resides locally on the device, which saves on bandwidth and response time. A suitable application would be one where a very specific query is sent to a Web server, and a concise response received. For example, the Palm VII comes with a UPS package tracking application pre-installed, as well as stock quote and weather apps. Typically, the portion of the application residing on the device is used to construct the query from several available options before any connection is made. A good Web Clipping application will also pre-load any graphics required on the Palm, so they don't need to be broadcast over the air.

3Com would like us to use the term Web Clipping Application (WCA) for the portion of the code that lives on your Palm, but many sites that offer their own WCAs for download prefer to call them PQAs (Palm Query Applications). To add to the acronym confusion, the Web Clipping Application Builder is actually known as the Query Application Builder (QAB), while the program itself is called the PQA Builder. For simplicity, let's just stick with PQA.

3Com would also have us believe that the only use for this technology is to retrieve snippets of information from the Web, like your parents might send you clippings from the hometown newspaper. But developers have already found ways to deliver much more—right up to standard Web browsing, should you want to do that on a 153x144 pixel device with a 14.4k modem.

However, perhaps because of the name, many developers seem to equate this technology with "Web scraping" and dismiss it as a worthwhile technique. This is unfortunate because PQA's simplicity makes it a good choice for rapidly developing wireless Palm applications.

To write PQA programs, you don't have to learn any new programming languages— you write it entirely in HTML. But there are a few restrictions on the HTML tags you can use, which we'll get to later. For the most part, a PQA is just a self-contained series of interconnected HTML pages.

The first thing to realize is that Web Clipping isn't the same thing as Web browsing. At no time does your Palm device actually connect directly with the origin Web server. A Web Clipping Proxy Server that resides in 3Com Corp's data center performs this interaction on your behalf.

The proxy server connects via normal HTTP protocols with the origin server, then uses a compressed UDP protocol to connect with the Palm device.

Getting the Tools

So what do you need to write applications? Surprisingly, very little. Aside from your HTML editor of choice, the only other tool you'll need is the Web Clipping Application Builder (that is, the PQA Builder)—a long title for a very simple utility. The PQA Builder is a free download from Palm at www.palmos.com/dev/tech/webclipping/ and is available for either PC or Mac.

Of course, it helps to have a Palm VII or a Palm V with clip-on OmniSky modem, so you can actually experience how your PQA works. If you don't have a wireless Palm, there's an emulator available from the same location. In my experience, the emulator is more trouble than it's worth. For some obscure reason, Palm insists that you perform a complicated process to install ROM images from a real Palm device, rather than just giving you a functional emulator. But if you want to experiment with Web Clipping before you spring for a wireless Palm, then you'll need to install this also.

One note: There are a few limitations on the code you can use. You're probably not going to be able to use a GUI HTML editor such as Dreamweaver or Frontpage.

While you can try most of the techniques below with an emulator on your local machine, it's better if you can put some pages on a Web server. No special setup is required. Your free Webspace from your ISP will work just fine, as long as you can use something like FTP or Fetch to put raw HTML files there. But you can't use "localhost" to test locally on your own desktop; the files need to be accessible from the Internet.

Writing your First PQA

Let's jump right in and design our first PQA. I'm going to assume here that you're familiar with basic HTML. Of course, it's almost a requirement that your first app in a new language be the venerable "Hello World." Since writing PQAs is so ludicrously simple, I'm going to complicate this a little, just to keep it interesting. Let's start right off with the world's first multipage, Web-connected Hello World application. Fire up your HTML editor and construct these two files, then save them with the suggested names in a new folder.

• Listing 1: index.html
• Listing 2: more.html

Next, you'll need to run the PQA Builder you installed earlier. It will open up with a blank window. From the File menu, select Open Index (or just Open on Mac). Navigate to the folder where you stored the index.html file, select it and click Open. You'll notice that the program window now contains not just the index file, but also more.html. PQA Builder scanned the HTML in your index.html file and automatically loaded all linked files. As we'll see later, it can also locate linked graphics. Once the files are loaded, select the File menu again, then select Build PQA. In the file name box, type HelloWorld.pqa—ignore the Logo options for now—and save to the same folder as your source HTML files.

Installing the PQA on your Palm

Now you need to put your compiled PQA onto your Palm. With the Palm Emulator, drag-and-drop the .pqa file onto the emulator window. If you've got a Palm VII, and you've ever downloaded and installed an application program for your Palm, the process is identical. In Windows, click Start > Programs > Palm Desktop > Install Tool. Or just double-click the HelloWorld.pqa file in Explorer. If requested, select the User to install this for, then click Done. That's it. The next time you sync, the HelloWorld PQA will be installed to your Palm.

Now start your Palm, go to the Palm.Net category—PQA's are installed into this category by default—and click the little black diamond icon named HelloWorld. You should see your Hello World page with an underlined "More Info" link. Click this link, and you'll see your second page. Notice the word "Real" is underlined because it's a link. It also has a little radial icon next to it. This indicates that it's an external link—it will take you out to the network. Network links may incur a charge, depending on the service plan you signed up for when you activated your Palm.Net service. But go ahead. Click the link. In a few seconds, you should find yourself at a Yahoo page. While Yahoo does some device sniffing to serve you a low-weight page, we could just as easily have pointed this link at any Web page out there. In general, this tends not to give the best results because normal Web pages can't be rendered properly on the mini screen of the Palm.

Going Online

Rather than bore you with a tutorial on how to create some useless demo app, I'm going to leave the question of what to build up to you. But let's look at how to build a true PQA using the application-partitioning concept.

The first thing you'll need to do is create some graphics to spruce up your interface. Here, you have to keep in mind the limitations of the handheld device's screen size and resolution. In order to display on a Palm, your graphics need to be a maximum of 153 pixels wide. You'll want to keep them as small as possible to maximize the amount of information space available on the screen. However, if you use application partitioning wisely, bandwidth concerns won't be as important as you might assume.

For this demo, I created a graphic with Fireworks. You can use any graphics program that can save as GIF or JPG—animated GIFs are not supported. You'll be happy to know you can choose from 4 times as many colors as Henry Ford offered on his first automobile. Your choices are black, white, silver, and gray. Create a suitable graphic and save it in the same local folder as your HTML files.

You'll need to modify the two files you already made, and create a new one. Add the following line to index.html, within the HEAD section:

<meta name="localicon" content="webrev.gif">

This instructs the PQA Builder to include your graphic in the compiled application, and allows you to reference it later from an online page, as we'll shortly see.

Modify more.html as shown in Listing 3. Remember to replace www.mydomain.com with your actual Web server address. Then create a new file: online.html, as found in Listing 4.

You'll need to upload this file (online.html) to your Web server. For simplicity, I put this in a subdirectory, as you can see in Listing 3, and called it clip.

Next, use the PQA builder to reopen your index.html—if it's still open on your desktop, choose Rescan HTML from the File menu. You'll see that it has added your image to the list of files. Again, the compiler scanned your code, and determined that this graphic was needed in the compiled application.

Now reinstall the PQA onto your Palm or emulator, as before, and remember to hotsync again. Start it up and you'll see the same first page. But when you click on More Info, you'll now see your new graphic. Click the "Online" link. And there's your graphic again—but remember, you never uploaded that graphic to your Web server. Let's look at that image tag:

<img src="file:HelloWorld.pqa/Webrev.gif" width="150" <br /> height="40" alt="Web Review">

What's happening here is that your online files are referencing a graphic that's resides on your Palm device. Because Palm.Net users pay by the kilobyte for downloading content, it makes sense to pre-load your graphics onto the Palm like this whenever possible. While it can be confusing at first to remember exactly where the files you need to link to are, you'll find this makes sense once you understand the application partitioning concept. You use a similar syntax to refer to PQA-resident pages from your online pages:

<a href="file:HelloWorld.pqa/index.html">Back</a>

Note that links from online pages to PQA-resident pages and images cannot include subdirectories.

Bear in mind that there's a physical system limit on the size of a PQA; currently this is 63Kb for a single compressed PQA for the Palm VII. Palm recommends that your compressed PQAs should average less than 15Kb, including all pages and images. This includes actual text characters and HTML markup, so you can optimize your PQA by keeping variables and page names as short as possible. Your users will never enter an actual URL, so there's nothing wrong with naming your pages a.html, b.html, and so on. The same concept goes for naming graphics. Every byte counts.

Back to HTML

Most articles on a new technology would now go into describing the range of new commands. We're going to reverse that. If you know HTML, then you already know almost all the tags you need to make PQAs. So instead, let's look at what you can't do with Web Clipping.

Web Clippings are authored in a subset of HTML 3.2. While you can use most familiar tags, the following are not supported:

• Named fonts
• Imagemaps
• Frames (thankfully)
• Nested tables
• Style sheets

Web Clipping applications also can't use Javascript or Cookies. If you're interested, there's a DTD available for Palm OS HTML—see the Resources section below.

There are a few Palm-specific META tags that you should use. You've seen two of these already.

<meta name="palmcomputingplatform" content="true">

This indicates to the PQA Builder that this page was specifically authored for the Palm VII. When you use this tag, the compiler won't include images wider than 153 pixels because that's the widest allowable image. Your PQA will also not compile properly without this tag present.

<meta name="historylisttext" content="text_string &date <br /> &time">

Use this to optionally customize what appears in the history tab. The variables &date and &time will insert the date and time the page was visited. The practical viewable limit for this text string is about 20 characters.

<meta name="palmlauncherrevision" content="x">

This tag isn't required, but it's useful if you expect to update your application. Replace "x" with a version number, then query this number in the online portion of your code—you'll need to do some server-side processing such as CGI or ASP for this. In this way, you can prompt people to download the latest version of your PQA.

There's one custom attribute that you can use to make standard links appear as buttons.

<a href="file:HelloWorld.pqa/index.html" button>Back</a>

This will cause the normal link to be replaced by a button in your application. The button label will be whatever is between the <a>x</a> tags, in this case "Back".

Web Clipping supports most of the normal form widgets. One exception is in drop-down select lists. Don't use the value attribute of the option element. Instead, allow this to default to the string displayed in the drop-down box.

There are also a few Palm-specific variables available for use in your forms.

<input type="datepicker" name="date" value="value">

If "value" is left undefined, this returns the current date, in YYYY-MM-DD format. Specify the value to assign a value to the date.

<input type="timepicker" name="date" value="value">

Similar to datepicker, this returns the current time in HH:MM 24-hour format. Note that this is displayed in am/pm format to the user, unless overridden by the personal preferences.

Two unique variables can be used to provide some interesting functionality in your applications:

<input type="hidden" name="date" value="%zipcode">

This returns the zip code of the nearest Palm.Net base station, which Palm claims is usually within five to ten miles of the user. While this is hardly GPS, it could be used to provide some rudimentary location-specific content.

<input type="hidden" name="id" value="deviceid">

This should return a unique string specific to an individual Palm organizer, which is set at activation. Obvious uses for this could be some basic authentication. The Web Clipping Developer's Guide has more details on security for Web Clipping apps.

So Now What?

So now you've got the basics of Web Clipping. As you can see, if you're familiar with HTML, you should have no problems authoring PQA applications. The real trick comes in using the application partitioning concept to optimize your pages for the low-bandwidth, high-latency environment that is the current generation of the wireless Web.

What's the future for Web Clipping? It's certainly one of the easiest ways to author for the Palm, but its proprietary nature means it's also limited to just those devices. While there are a lot of Palms out there, the latest generation of WinCE devices seem to be finally getting it right and could be serious competition. (It's also possible to use a very similar technique with these devices, but using nonproprietary, standards-compliant HTML or XHTML 1.0.)

Despite the hype, broadband wireless Net access is still probably at least two years away in the U.S. So for now Web Clipping is a good way to leverage your HTML skills to make your site available for the growing number of wireless-enabled Palms coming online, and a good way to get your feet wet in the business of providing content on the wireless Web.

Rory has worked in Web development in both Japan and the US. He is constantly puzzled as to why his travel bag of wireless devices contains so many wires.