Webmaster''''s Guide to the Wireless Internet part 31 pdf

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

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

Figure 6.23Selected Date Returns the User to the Datepicker Object

Figure 6.24Timepicker Object with Value Attribute Omitted

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

Figure 6.25Selecting a Time

Figure 6.26Selected Time Returns the User to the Timepicker Object

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

Figure 6.27E-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

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.29mailform.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:

Figure 6.28E-mail Example on the POSE

<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

Figure 6.29Continued

Figure 6.30Mailform.html Launched as pqa from the POSE

Figure 6.31WCAmailer.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) {

<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

Figure 6.31Continued

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

Figure 6.32Success!

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

Figure 6.33ERROR!