Understanding the Mobile Applications

This chapter describes the three mobile applications provided by the The SunTM ONE Portal Server, Mobile Access 6.2 software. This chapter contains the following sections:

Mobile Applications Overview

Portal Server, Mobile Access software contains three mobile applications: Calendar, Address Book, and Mail. Each mobile application is based on JavaServer Pages™ (JSPTM) technology, and can be accessed through any mobile device supporting any of a number of standard markup languages -- for example, WML and XHTML. These three applications are accessed through the mobile Portal Desktop. The user may select an application for use and return to the mobile Portal Desktop when finished.

The goal of this chapter is to demonstrate the key functionality offered by the calendar, address book, and mail applications, while simultaneously providing a developer’s perspective of control flow through the individual JSP pages.

Each application contains at least two full sets of JSP pages: an AML-based set, and a WML-based set. Most mobile device are supported using the AML-based JSP pages. The output of the AML pages is processed by the rendering engine, which translates AML to device specific markup. Some WML devices are supported by the WML-based JSP pages, whose output is returned directly to the WML device.


Note	Due to the large number of source files, this chapter does not attempt to provide a complete code review of every individual file. Instead, it uses a tutorial-style format to walk through the user through each application, describing the key features of certain JSP pages as they pertain to the current screen.

The JSP pages comprising these three applications make extensive use of five custom tag libraries: cal, socs, ab, mail, and util. Each tag library is fully documented, with code examples, in the SunTM ONE Portal Server, Mobile Access 6.2 Tag Library Reference.

Preview of the util Tag Library

Three navigational tags apply to virtually every JSP page in the three sample applications: <util:url>, <util:link>, and <util:forward>. A fourth tag, <util:include>, affects the visible content on pages that use it.

<util:url>

This tag facilitates the construction of context-sensitive URL values. It is used in both the AML-based and WML-based versions of all three mobile applications.

In this example, the URL specifies a file named someFile.jsp, and associates it with the calendar mobile application.



Note	This tag generates a compressed URL, which can make it difficult to discern the target by looking at the generated markup. Developers wishing to debug the application JSP pages may wish to disable URL compression in the following manner: Edit the file: /etc/opt/SUNWps/MAP/MAPConfig.properties and set the ma.compressor.enable property to false.

<util:link>

This tag facilitates the construction of link-type tags, whose content is dynamically generated. Each tag contains a tagstart and tagend attribute for specifying what appears at the start and end of the generated link:

<util:link tagstart=”<a” tagend=”>”>

<util:attr attr=”href”>

<util:url file=”someFile.jsp” comp=”cal”>

... other parameters...

</util:url>

</util:attr>

</util:link>

<util:forward>

The comp attribute associates the named file with a particular mobile application. In the above case, cal is an abbreviation for “calendar”.

<util:include>

This tag performs an include operation, similar to <jsp:include>, but constructs the resource name in one of two ways: with a path attribute, or with a combination of file and comp attributes. Certain JSP pages use this tag to include reusable GUI elements in their output.

For more information regarding <util:url>, <util:link>, <util:forward>, and <util:include>, consult the SunTM ONE Portal Server, Mobile Access 6.2 Tag Library Reference.

The Mobile Calendar Application

The calendar application is a useful organization tool. It allows the user to add, edit, and remove events and tasks, and includes support for repeating events, email reminders, and multiple calendar servers.

To launch calendar, first log in to the sample portal provided with Mobile Access . The mobile Portal Desktop displays the SunTM ONE Portal Server title, followed by a list of numbered options to choose from: User Information, Bookmarks, Personal Notes, Calendar, Address Book, and Mail.

Following the calendar link brings the user to the calendar channel, which summarizes the events and tasks scheduled for the day. Clicking on the View Calendar link launches the calendar application, and displays the day view page, which is where the user interaction actually begins.

The Day View Page


Note	Three different calendar servers are capable of interacting with this application: Sun ONE Calendar Server, Microsoft Exchange, and Lotus Notes. Because these three servers do not support all of the same features, three server-specific sets of JSP pages exist in the cal/sun-one, cal/exchange, and cal/notes directories.

The day view page (dayview.jsp) displays the current calendar ID, the date, and a summary of any tasks or events currently scheduled. It also provides links for adding a new event, adding a new task, viewing other calendars, or resetting the calendar to a specific date. In the source code, such links are specified as <util:link> from the util tag library, as described above.

The calendar application allows the user to add two basic kinds of scheduling objects: events, and tasks. Events and tasks are similar in that they both contain generic properties such as title, location, and details, but differ in that events specify a start and end time, whereas tasks specify a due date and indicator of whether or not the task is complete.

Adding an Event

To add an event to the calendar, follow the add event link from the day view page. dayview.jsp contains a <util:link> pointing to eventSess.jsp, which creates the new event and adds it to the user’s session (see <util:session> in the SunTM ONE Portal Server, Mobile Access 6.2 Tag Library Reference for more information about user sessions). The user is prompted for event information, such as start time, end time, title, location, and details. After filling in the required information, the user is presented with the following choices: submit, remind, invite, and repeat.

The first option, submit, is a <util:link> to doUpdateEvent.jsp, which submits the newly created event. It also displays a success/failure confirmation message, and displays a link for returning back to dayview.jsp.

The second option, remind, is for sending an email reminder. Following this link prompts the user for additional reminder data, (with one prompt per screen), as follows: the recipient’s email address, the time (prior to the event) to send the email reminder, and a message to be included with the reminder. After clicking the remind link, control flows through the following pages: remindMail.jsp, remindTime.jsp, remindInterval.jsp, remindMsg.jsp, doRemind.jsp, and then back to eventHm.jsp.



Note	This feature is not supported when connecting to servers other than Sun ONE Calendar Server.

The third link, invite, allows the user to invite another person (the invitee) to the event. Following this link presents the user with a number of choices for specifying the invitee, including: quick invite, search, and calendar ID. When following the invite link, control flows from dayview.jsp to rsvp.jsp, to doRSVP.jsp, and then back to eventHm.jsp.



Note	This feature is not supported when connecting to servers other than Sun ONE Calendar Server.

The fourth link, repeat, allows the user to specify the repeat frequency (daily, weekly, monthly, or yearly) for the event. Depending on the selected repeat frequency, the user choices vary slightly.

For the daily repeat frequency, the user may specify the event to repeat every day, on alternate days, or on a group of days, such as MonWedFri, TueThu, or SatSun.

For the weekly repeat frequency, the user may specify the event to repeat every week, on alternate weeks, or once per week on a particular day.

For the monthly repeat frequency, the user may specify the event to repeat every month, on alternate months, or once per month on a specified date.

For the yearly repeat frequency, the user may specify the event to repeat every year, on alternate years, or once per year on a specified date.

After choosing a repeat frequency and supplying the information mentioned above, the user has the option of supplying one final parameter: the repeat until value. As its name implies, this value sets the duration of time that the repeat should continue for. The choices are: repeat forever, repeat for a specific number of instances, or repeat until a specific date.

The JSP pages responsible for the repeat process all begin with the prefix repeat, as in repeatFreq.jsp. The files involved are: repeatFreq.jsp, repeatInt.jsp, repeatInterval.jsp, repeatIntOK.jsp, repeatOn.jsp, repeatOnOK.jsp, repeatOnMonthly.jsp, repeatOnWeekly.jsp, repeatOnYearly.jsp, repeatUntil.jsp, repeatUntilDate.jsp, repeatUntilDateOK.jsp, repeatUntilNumber.jsp, and repeatUntilNumOK.jsp.

Adding a Task

Adding a task to the calendar is similar to adding an event. From the day view page, the user simply selects the add task link and proceeds to fill in the requested information, such as task title, location, due date, due time, details, and whether or not the task is already complete. When finished, the user is prompted with the following choices: submit task, remind, and repeat.

Control flow through the various JSPTM pages is similar as well. First, it passes from dayview.jsp to taskSess.jsp, which creates a new task and adds it to the user’s session. From there, a <util:forward> passes control to taskHm.jsp, which issues the task-related prompts as described in the first paragraph above. The reminder and repeat links take the user through the same process as previously described under adding an event. The only difference is that the source files responsible for “task remind” and “task repeat” all end in the suffix “Task”. For example, remindMailTask.jsp instead of remindMail.jsp.

Going to a Different Date


Note	The task location, task remind, and task repeat features are not supported when connecting to servers other than Sun™ ONE Calendar Server.

It is possible for the user to reset the day view page to any arbitrary date by selecting the go to link. Doing so follows a <util:link> from dayview.jsp to goto.jsp, which presents the user with the following go to options: today, next week, next month, previous week, previous month, or a specific date. As you might expect, the next week/next month links roll the calendar forward by a week or month, and the previous week/previous month links roll the calendar back. The specific date link rolls the calendar to the specified date, and the today link rolls the calendar to today. When rolling the calendar forward/backward, control passes from dayview.jsp to doRoll.jsp, and then back to dayview.jsp, which displays the data for the new date. For convenience, the day view page also provides links to the next six days of the calendar, each of which link to doRoll.jsp as well.

Viewing an Existing Event or Task

As described above, the day view page summarizes all events and tasks for the day. Each summary is also a link, which when followed, will display the details of the particular event or task. For the purpose of this discussion, imagine our calendar containing one event (a party at 7:00PM) and one task (buying refreshments, due by 5:00PM).

To view the event or task, the user follows the desired link, which passes control from dayview.jsp to event.jsp or task.jsp.

To change the event details, the user follows the change link, which prompts the user for event details (see "Adding an Event"). To delete the event, the user follows the delete link, which leads to delete.jsp, and eventually back to the day view screen.

As with the event details, changing or deleting the task is simply a matter of following the appropriate links.

The Mobile Address Book Application

The address book is a convenient application for storing personal contacts. It works in conjunction with the mail mobile application to provide an efficient mechanism for sending mail to one or more recipients.

As with the calendar application, the user launches the address book application from links provided on the mobile desktop. From the mobile desktop, the address book link brings the user to the address book channel, which summarizes the number of contacts currently stored. Clicking on the view address book link launches the address book application, bringing the user to list.jsp, where the interaction with the user actually begins.

Adding a Contact

To add a contact to the address book, the user follows the add contact link, which is a <util:link> from list.jsp to add.jsp. The add contact page uses a <util:include> to include GUI code from edit.jsp, which presents the user with a series of individual prompts describing the new contact. The prompts include: first name, last name, phone number, and email address. Control passes from add.jsp to doAdd.jsp, (which submits the contact to the address book), and a <util:forward> automatically returns the user to list.jsp.

Adding a Group

The address book allows the user to place multiple contacts into named groups. To create a new group, the user follows the add group link, which passes control from the current page (list.jsp) to the add group page (addGroup.jsp). The add group page prompts the user for the name of the group, then passes control to the members options page (addMembersOption.jsp), which presents the following menu: search, browse, and enter member.

The search link allows the user to find a specific contact/group, or a list of contacts/groups, by entering search criteria and choosing the contacts/groups from the list of results. Following this link passes control from addMembersOption.jsp to searchMemberChoices.jsp, then to doSearchMemberChoices.jsp, which forwards to pickMemberChoices.jsp. The file pickMemberChoices.jsp displays the results in the form of a choice list, from which the user can pick and select the contacts/groups to be added to the group.

The browse link allows the user to scroll through the complete list of stored contacts and groups, without having to explicitly perform a search. Selecting this link passes control from addMembersOption.jsp to browseMemberChoices.jsp.

After fetching all of the contacts and groups, browseMemberChoices.jsp forwards control to pickMemberChoices.jsp. As mentioned above, this file displays the results in the form of a choice list, from which the user can pick and select the contacts/groups to be added to the group.

The enter member link allows the user to enter a contact or group directly if the exact name is already known.

Viewing/Changing/Deleting a Contact

To view the details for a specific contact, the user selects the desired name from the list of contacts presented on list.jsp, as previously discussed. If the selected link points to a single contact, control passes from list.jsp to view.jsp. If the link is for an entire group, control passes to viewGroup.jsp.

After selecting a single contact, the user has three options: compose an email (to the named contact), change (the contact details), or delete (the selected contact). Depending on which link the user chooses, control will pass from the current page to compose.jsp, change.jsp, or delete.jsp.

The change link allows the user to change the first name, last name, phone number, and email address of the selected contact. The JSPTM page responsible for generating this page (change.jsp) uses the <util:include> tag to include the GUI from edit.jsp. Existing properties appear with their current values, which the user may change or accept. Control flow passes from change.jsp, which collects the information, to doChange.jsp, which submits the changes and returns the user to the address book home.

To delete a contact from the address book, the user simply follows the Delete link. Control passes from the current page (view.jsp) to the delete page (delete.jsp) and then back to the address book home.

Viewing, changing, or deleting a group from the address book follows the same procedure as described above, but passes control to group-specific JSP files such as changeGroup.jsp, doChangeGroup.jsp, and deleteGroup.jsp.

Viewing/Changing/Deleting a Group

Viewing a group lists the members of the group and lets the user compose an email to the entire group. Changing a group allows the user to add or delete group members, or change the name of the group. Deleting a group is the same as for deleting a contact.

The Mobile Mail Application

The mail mobile application is an email client that works in conjunction with the address book. Like the calendar and address book applications, mail is accessed through the main menu on the mobile desktop. Following the mail link accesses the mail channel, which provides a link to launch the mail application.

Control passes to summary.jsp, which summarizes the messages, and provides links for accessing the inbox, composing a new message, accessing other folders, or changing the view.

Inbox

The Inbox contains a from line at the top of the screen indicating the range of messages that are currently viewable. If the inbox contains more messages, a link labeled more appears at the bottom of the page. Following that link reloads the current page while incrementing the message index value to load the next set of messages.

Each individual email is summarized to show the sender’s address and message subject. To view a message, the user follows the desired link, which passes control from the current page to getmsg.jsp, which fetches the message data from the server and forwards the user to message.jsp, which displays the subject and body of the message.

The Next link at the bottom of the screen loads the next message, and the Menu link (menu.jsp) provides the user with the following actions: reply, delete, forward, move to, copy to, add to addr, view header, and mailbox.

The first link, reply, provides the user with a dialog for replying to the sender’s message. Following this link passes control to reply.jsp, which asks the user if the reply should go only to the sender, or to everyone included in the original email. The user answers this question by choosing To Sender or To All, both of which pass control to compose.jsp, where the user composes the message (see "Compose").

The second link, delete, simply deletes the message. Control passes from the current page (menu.jsp) to delete.jsp, and then back to the inbox.

The third link, forward, forwards the message to a specified recipient. If the user already has an address book channel configured, control first passes to pickaddr.jsp, which allows the user to choose a recipient from the list of stored contacts. The user selects the recipients to include, which passes control to compose.jsp. If no address book channel is configured, control passes to compose.jsp directly. For details about the compose screen, see the compose discussion later in this chapter.

The fourth link, move to, moves the message to a specified folder, deleting it from the inbox in the process. Following this link passes control to getfolders.jsp, which fetches the folder names from the server, then forwards the user to folders.jsp, which displays the available list of folders. A New Folder link also appears, enabling the user to create a new folder if desired (see "Folders").

The fifth link, copy to, behaves exactly as move to, except that the original message is left in the inbox after the operation.

The sixth link, add to addr, adds a contact to the address book. Selecting this link passes control from the current page (menu.jsp), to addpab.jsp (short for add personal address book), which prompts the user for the following contact information: first name, last name, phone, and email address. After supplying this information a Mailbox link appears which returns the user to the current mailbox folder, the inbox in this case.

The seventh link, view header, links to header.jsp, and displays the following email header fields: from, date, subject, and to. This screen simply displays information. It does not present the user with additional choices.

The eighth link, mailbox, returns the user to the currently selected mailbox. In our case, following this link returns control to the inbox.

Having returned to the inbox, there are three main options that have yet to be discussed: compose, folders, and views.

Compose

The compose page, compose.jsp, is where a user composes a new email message. This link is available from the main menu of summary.jsp:

Following this link first passes control to pickaddr.jsp, (if an address book comm channel is already configured), then to compose.jsp. The compose page prompts the user for standard email fields, such as: to, cc, subject, and message body. The interface is intuitive; the user simply supplies the requested fields, submits the message, and returns to the inbox.

Because composing an email on a mobile device can be a time-consuming process, the user is allowed to define up to nine preset messages. These can be selected for inclusion at the beginning of the compose screen.

To create a preset message, log in to the standard Portal Server with an HTML browser, click on the mail comm channel, select Edit (the pencil icon), then follow the edit your mobile preferences link. Preset messages have a 30-character maximum.

Folders

Selecting the folders link allows the user to view or create a specific folder. Following this link passes control to getfolders.jsp, which fetches the folder names from the server and forwards the user to folders.jsp, which displays the available list of folders. A new folder link also appears, enabling the user to create a new folder if needed.

Selecting the New folder link passes control from the current page (folders.jsp), do newFd.jsp, which prompts the user for the name of the folder, then passes control to doNewFd.jsp, which creates the new folder. The user then return to the folders page by following the Folders link that appears after the new folder has been created.

Selecting an existing folder passes control to folderMenu.jsp, which provides the user with three choices: open, rename, or delete. Choosing open reloads the inbox screen (passing control to doInbox.jsp), substituting the selected folder data for the inbox data. Choosing rename passes control to renameFd.jsp, which prompts the user to enter a new name for the folder. Choosing delete passes control to delFd.jsp, which deletes the folder. All three links eventually present the user with a Folders link that returns control to folders.jsp.

Views

Views are pre-configured rules that determine which messages are visible on screen. To configure a view, log into the portal server using a standard HTML browser, and enter the mail comm channel edit page as described earlier. Once configured, the user may select a view by following the Views link from the main menu of summary.jsp.The views link appears only if the user has already configured the views in this manner.

Chapter 1 Understanding the Mobile Applications