272 Chapter 6 • Web Clipping Choosing a Date with the Timepicker Object The timepicker is another useful element that is unique to the Web clipping environment.The timepicker is invoked using a syntax very similar to the datepicker: Output of this object is always in 24-hour HH:MM format, but the input of this object may be in 12-hour format depending on the user’s prefer- ences (accessible via the Formats screen under Prefs). The following sets the 24-hour format: <input type="timepicker" name="time" value="hh:mm"> The following sets the 12-hour format: <input type="timepicker" name="time" value="hh:mm am/pm"> Figure 6.24 illustrates the timepicker object in action. First, the user is pre- sented with a screen containing the specified time (in this case, 11:30 AM), or, if no time is specified, the current time. www.syngress.com Figure 6.23 Selected Date Returns the User to the Datepicker Object Figure 6.24 Timepicker Object with Value Attribute Omitted 159_wg_wi_06 10/22/01 4:37 PM Page 272 Web Clipping • Chapter 6 273 Upon clicking on the input field, the user is presented with a dialog to specify the time. Each field is selected and manipulated with the arrows in the center of the dialog box (see Figure 6.25). Once the user selects the new time and presses OK, they are returned to the page containing the timepicker object, with the selected time displayed (see Figure 6.26). If the value attribute is omitted, or if the value is not in the expected format, the current time will be displayed in the timepicker when the user clicks on it. This being the case, it is not necessary for you to overly concern yourself with the user’s preferences.The default preference is 12-hour format, so you may want to keep this in mind as you build your application. www.syngress.com Figure 6.25 Selecting a Time Figure 6.26 Selected Time Returns the User to the Timepicker Object 159_wg_wi_06 10/22/01 4:37 PM Page 273 274 Chapter 6 • Web Clipping The device-specific extensions to Web clipping are quite useful and conve- nient, and come in handy both to reduce development time (by eliminating the need to code client-side functionality such as calendars and time inputs), and to increase the quality of the user experience (by providing a consistent interface to input data). In addition, location-based features such as %ZIPCODE (and %LOCATION for Palm OS 4.0) provide an easy route to providing users with information relevant to their location while accessing your server.The %DEVI- CEID, despite its variability, can be used as a convenient way to recognize indi- vidual users when there is not a risk to the user should the authenticity of %DEVICEID become compromised. Now that we have covered the available code to build a Web clipping applica- tion, we can move on to discuss some examples. Web Clipping in Action: Examples In this section, we will discuss two examples: one that illustrates how a WCA can pass information to other local applications, and one that illustrates how you can send information to a Web server and return a page that is appropriate for Clipper. For the most part, this will be similar to methods you will already be familiar with from developing HTML for desktop browsers.The first example that we will use is a mailto: link that will be processed using the local e-mail application on the device (iMessenger, in this case).This feature utilizes Messaging Application Protocol Interface (MAPI), a library that allows applica- tions to send parameters to an e-mail program.This is the same feature that allows mailto: links to launch the e-mail program on a desktop computer.The same syntax used to pass parameters to a mailto: link is used to pass parameters to other applications on the device using the palm: or palmcall: URL protocols. We will then illustrate a form-based example of how you can send an e-mail message using a CGI script installed on your server. Chances are you have used this in one form or another already. In this chapter, we will be using a mailform example using PHP due to its portability across platforms and open-source avail- ability.You can download a free copy of PHP from www.php.net. Using a mailto: Link with Parameters This example is fairly straightforward and will illustrate some basic concepts about exchanging information between programs located on a Palm-powered handheld device.We will use an HTML mailto: link to compose an outgoing e-mail using iMessenger, the e-mail application that is included on the Palm VII/VIIx (see Figure 6.27). www.syngress.com 159_wg_wi_06 10/22/01 4:37 PM Page 274 Web Clipping • Chapter 6 275 Figure 6.27 E-mail Example <html> <head> <title> Email Example </title> </head> <body> <h1>Email Example</h1> <p>This example illustrates both how you can use the 'button' attribute of the anchor tag to render a link as a button, and how you can pass parameters within a link that will help compose the email.</p> <a href="mailto:example@syngress.com?subject=From WCA&body=This is a message that came from a WCA" button>example@synress.com</a> </body> </html> The code in Figure 6.27 should look fairly familiar. It consists of a paragraph of text and a single link with an href that uses the mailto: protocol.This is a stan- dard protocol that specifies an e-mail address. It is possible to pass parameters using the mailto: protocol.The only parameters that we can pass here are subject and body. Subject denotes some text that should be used as the subject of the mes- sage, and body denotes the message text. Figure 6.28 illustrates what this WCA looks like in the POSE, and what users will see once they click on the button. The same syntax that is used to pass parameters in this example can also be used to pass parameters to other applications called using the palm: or palmcall: protocols. Unfortunately, it is not possible to pass any parameters directly to the native Palm applications such as the Memo Pad or Address Book from a WCA. There is, however, a third-party application called iKnapsack that uses the Palm OS device library to access to these native applications.The iKnapsack applica- tion provides an API that allows you to write to the Memo Pad, set contacts in the Address Book, or schedule events in the Date Book using a WCA.You can obtain a copy of iKnapsack (and a WCA that allows you to write memos, set contacts, and schedule events) for free from www.tow.com/software/iknapsack. www.syngress.com 159_wg_wi_06 10/22/01 4:37 PM Page 275 276 Chapter 6 • Web Clipping Once users compose their messages, they have the option to put the e-mails in their outboxes.The e-mail will not be sent until the users open the iMessenger application and send/receive their mail. If the information that the users wish to send is time-sensitive, then we may want to deliver the messages via a form sub- mitted to our Web server.This is demonstrated in the following example. Sending E-mail via a Web Server In this example, we will use a Web clipping application to send e-mail via a PHP script installed on a Web server.This example is written using PHP, but it is cer- tainly possible to use most any server-side language (such as Perl or ASP) to send e-mail using information submitted from an HTML form. Figure 6.29 contains the HTML that we will use for our WCA. Figure 6.29 mailform.html <html> <head> <title>Mail Form</title> </head> <body> <form action="http://www.yoursite.com/WCAmailer.php"> <h1>Mail Form</h1> To: <input type="text" name="to" size=20><br> From: www.syngress.com Figure 6.28 E-mail Example on the POSE Continued 159_wg_wi_06 10/22/01 4:37 PM Page 276 Web Clipping • Chapter 6 277 <input type="text" name="from" size=20><br> Subject: <input type="text" name="subject" size=20><br> Message: <textarea name="body"></textarea><br> <input type="submit" value="Send Message"> </form> </body> </html> Once we have scanned this HTML into the WCA builder and created a .pqa file from it, we install it on our POSE and launch it.The WCA as it appears in the POSE is shown in Figure 6.30. In this case, we have filled in the input fields with a simple test message. The WCA itself does no good unless we have a script to which we can point it.You can install the PHP script from Figure 6.31 on your Web server and alter the action attribute of the <form> tag in Figure 6.29 to point to where you have placed the script. In the event that you do not have PHP available, you can obtain a copy for free from www.php.net. www.syngress.com Figure 6.29 Continued Figure 6.30 Mailform.html Launched as .pqa from the POSE 159_wg_wi_06 10/22/01 4:37 PM Page 277 278 Chapter 6 • Web Clipping Figure 6.31 WCAmailer.php <? header("Content-type: text/html"); header("PalmComputingPlatform: true"); if(empty($to)) error("No recipient specified"); if(empty($from)) error("No from address specified"); if(empty($body)) error("No message text specified"); if( mail($to,$subject,$body,"From:$from\n") ) { print<<<__THANKS__ <html> <head> <title>Success!</title> <meta name="HistoryListText" content="Success!"> </head> <h1>Success!</h1> <p>Your message has been sent!</p> <b>To:</b> $to<br> <b>From:</b> $from<br> <b>Subject:</b> $subject<br> <b>Message:</b> <br> $body </body> </html> __THANKS__; exit(); } else { error("Message delivery failure!"); } function error($err) { print<<<__ERROR__ www.syngress.com Continued 159_wg_wi_06 10/22/01 4:37 PM Page 278 Web Clipping • Chapter 6 279 <html> <head> <title>ERROR!</title> <meta name="HistoryListText" content="ERROR!"> </head> <h1>ERROR!</h1> <p>Your message cannot be sent for the following reason:</p> <p><strong>$err</strong></p> <p>Please go back and try again!</p> </body> </html> __ERROR__; exit(); } ?> The first element of the header describes the MIME type of the content contained in the response as being composed of HTML text.This header is nec- essary whenever information is returned to any browser from a server-side script, or else the Web server will return an error. The second line of the header is optional, but marks the content as valid for display on a handheld device.As mentioned before, the PalmComputingPlatform header informs the Palm.net proxy server that our HTML should not be refor- matted for Clipper. It is strongly encouraged that this information be included in any page that is sent to Clipper. When we are serving out static HTML pages we can specify this information as a <meta> tag within the document. In fact, we could specify this information in a <meta> tag here as well (as we have done with HistoryListText), but instead we are specifying the information directly in the header itself. This script makes use of the PHP mail() function, which accepts several argu- ments used to compose an e-mail message.The first argument specifies the e-mail address to which the message should be sent.The second argument contains the subject of the message, and the third argument contains the message body.We can specify additional mail headers (such as cc:, bcc:, or, in this case ‘-From:’-) in the www.syngress.com Figure 6.31 Continued 159_wg_wi_06 10/22/01 4:37 PM Page 279 280 Chapter 6 • Web Clipping fourth argument.Any additional headers must be separated by newline characters (\n on UNIX systems, and \r\n on Win32 systems), but in this case, we are sub- mitting only one additional header so this is not necessary.The mail function will return a true value if it is able to successfully send the e-mail, and will return false if it cannot. We have specified a specific error function that will print an error message to the user’s browser if there is a problem with their input or if the mail cannot be delivered.We check to see if the variables have been set by using the empty() function, which will return true if the variable contains a value and false if it does not. In the event that these variables are empty, then the program will print out an error message and stop executing. NOTE If we were to implement the Figure 6.31 script into production, we would want to validate the to and from e-mail addresses with a regular expression in the script. There are many examples of e-mail validation that can be found on the php-general mailing list archives at www.php.net. Once the user submits the form and the mail is successfully sent, the user receives the clipping shown in Figure 6.32. In the event that an error occurs, the user is returned a clipping exemplified in Figure 6.33, with an appropriate error message displayed. www.syngress.com Figure 6.32 Success! 159_wg_wi_06 10/22/01 4:37 PM Page 280 Web Clipping • Chapter 6 281 Guidelines for Authoring your Web Clipping Application As with every application or site you build, you should view any interactive aspect from the user’s point of view. It is often best to refrain from thinking about technical architecture until a clear picture of the user’s needs is created. Once the user’s perception and goals are understood, the application may be built within this framework. Also, in addition to the needs of your users, you should consider the con- straints of the device that will be used to access your application. In this case, your constraints are limited by a slow connection speed, a small (at least in rela- tion to a standard monitor) screen size, and input limited, for the most part, to the use of a stylus. So, what does this mean for your Web clipping application? We suggest the following guidelines: ■ Avoid implementing unnecessary, unwanted, or unused features. For example, let’s say that your WCA allows users to browse news headlines, synopses, and full news stories. If you find that 99 percent of your users read only headlines and synopses, you should consider eliminating the option to “read the full story.” ■ Keep the dominant, or most likely, action highly accessible. For example, if you provide weather information in your WCA, and your users are most interested in a daily forecast, you should use a button instead of a link, and make sure that your users do not have to scroll to find it. www.syngress.com Figure 6.33 ERROR! 159_wg_wi_06 10/22/01 4:37 PM Page 281 . computer .The same syntax used to pass parameters to a mailto: link is used to pass parameters to other applications on the device using the palm: or palmcall: URL protocols. We will then illustrate. compose their messages, they have the option to put the e-mails in their outboxes .The e-mail will not be sent until the users open the iMessenger application and send/receive their mail. If the information. with an href that uses the mailto: protocol.This is a stan- dard protocol that specifies an e-mail address. It is possible to pass parameters using the mailto: protocol .The only parameters that