Chapter 5   Application JSPs


This chapter discusses the cHTML and WML JSP 1.1 files for iPlanet Messaging Server, Personal Address Book server, and iPlanet Calendar Server. These files, in conjunction with the tag libraries (see Chapter 6 "JSP Tag Libraries" for more information), facilitate the display of the application (for iPlanet Messaging Server, Personal Address Book, and iPlanet Calendar Server) content on devices that support these markup languages.

The JSP files are located in <ips_install_base>/SUNWips/public_html/jsp/<locale>/<component>/<clientType> where:

• ips_install_base refers to the installation location of the iPlanet Portal Server software

• locale refers to the user's locale

• component refers to either mail, calendar (referred to as cal), or address book (referred to as ab)

• clientType refers to WML or cHTML clients

Use the templates to configure and customize the content, the layout, and the user interface of these services for each supported client type.

Introduction

When the client connects to the backend calendar, mail, or address book server, the Mobile Access Pack JSP files for these servers fetch and display the content from these servers and enable interaction with these servers via the respective tag libraries. These files are locale and client specific, with multiple clientTypes sharing the same JSP files. The corresponding calendar, mail, and address book providers retrieve the appropriate client specific JSP files using the file lookup mechanism.

These JSPs and Tag Libraries use the:

• Client data for information on the client's file path

• File lookup mechanism to retrieve the client specific file

• Profile Service to store and retrieve their own properties

• Session Service to validate the user's session

• Logging Service to log messages related to the user's session

The Calendar TagLibs use WCAP to access the Calendar Server. The Mail TagLibs use the JavaMail API to access the Mail Server. The Address Book TagLibs use the NSLDAP API to access the Directory Server.

iPlanet Calendar Server JSPs

This section discusses the WML and cHTML template files used by the calendar client graphical user interface. See the appropriate figure and the files used for the interfaces (in the figure) to customize the display of the calendar client on the user's mobile device. Refer to the "iPlanet Calendar Server Client Tag Library" for detailed information on the tags used in these template files to enable interaction with the calendar server from the user's mobile device.

User Interface Flowcharts

This section discusses the calendar user interface, for WML and cHTML clients, that utilize the template files discussed in "JSP Files."

The WML and cHTML screen flowcharts shown in use calHome.jsp and dayview.jsp. See description of relevant files in Table 5-1 for more information.

Figure 5-1    WML and cHTML Calendar Home Screen Flowcharts

The WML and cHTML screen flowcharts shown in use event.jsp, change.jsp, and delete.jsp files. See description of relevant files in Table 5-1 for more information.

Figure 5-2    WML and cHTML Screen Flowcharts to View an Event

The WML and cHTML screen flowcharts shown use edit.jsp, add.jsp, and doAdd.jsp files. See description of relevant files in Table 5-1 for more information.

Figure 5-3    WML and cHTML Screen Flowcharts to Add Event

The WML and cHTML screen flowcharts shown in use edit.jsp, change.jsp, changeType.jsp, and doChange.jsp files. The process of changing an event is similar to adding an event (see and substitue Add with Change). See description of relevant files in Table 5-1 for more information.

Figure 5-4    WML and cHTML Screen Flowcharts to Change Event

The WML and cHTML screen flowcharts shown in use delete.jsp and deleteType.jsp files. See description of relevant files in Table 5-1 for more information.

Figure 5-5    WML and cHTML Screen Flowcharts to Delete Event

The WML and cHTML screen flowcharts shown in use date.jsp, doDate.jsp, doRoll.jsp, and goto.jsp files. See description of relevant files in Table 5-1 for more information.

Figure 5-6    WMl and cHTML Screen Flowcharts to Browse the Calendar

JSP Files

Table 5-1    Calendar JSPs

Filename	Description
launchCal.jsp	This file launches the calendar client on the user's mobile device. It uses the "forward" tag from the utilities tag library to display the calHome.jsp file (see ).
calHome.jsp	This provides the calendar home page. It fetches the events in the calendar database and forwards it to dayview.jsp (see ).
dayview.jsp	It lists all the events for the current date in a summary (see ). It provides links to: Add an event Go to a particular date Browse through the next 6 days from the current date
edit.jsp	It provides the event properties to add or modify an event in the calendar database.
add.jsp	It provides the fields to add an event in the calendar (see ). By default, specify only the start time, end time, description, summary, and location (see "event" for details) of the event.
doAdd.jsp	It adds the specified event to the calendar database (see ). It uses the error code CAL_001 (see errorCode) when it is unable to add the event in the calendar.
change.jsp	It provides the fields to change the specified event properties (see ).
changeType.jsp	It provides the fields to specify the type of change to make to the selected event. By default, specify whether to change this occurance of the event only, or to change this and all future occurances of the selected event in the database (see ). This file is required by cHTML clients only.
doChange.jsp	It modifies the specified event properties in the calendar database (see ). It uses the error code CAL_001 (see errorCode) when it is unable to add the event in the calendar.
date.jsp	It provides the fields to specify a date to proceed to (see ). This is unique to each client type.
doDate.jsp	It fetches and displays the events in the specified date (see ). It uses the error code CAL_001 (see errorCode) when it is unable to add the event in the calendar.
delete.jsp	It deletes the selected event from the calendar database.
deleteType.jsp	It provides the fields to specify whether to delete this instance of the event only, or to delete this and all future instances of the selected event in the database. It is required by cHTML clients only.
doRoll.jsp	It handles the dateroll command. It takes the arguments in the URL and displays the: Next 6 days or next week or month (see ) Previous week or month (see )
event.jsp	It displays all the details of the selected event (see "event" and ).
goto.jsp	It provides a navigation menu to fetch events for today, next week, next month, previous week, previous month, or a specific date.

Sample Customizations

):"> To add "Next Year" and "Previous Year" links in the Go To menu (as shown in ):

1. Log in to the Mobile Access Pack server and become superuser.

2. Change directories to /<iPS_install_base>/SUNWips/public_html/jsp/<locale>/cal/<clientType>.

3. Modify the goto.jsp file. That is, add a link similar to next week for next and previous years.

      Next week

      <a href="doRoll.jsp?fd=WEEK_OF_YEAR">Next week</a>

      Next Year:

      <a href="doRoll.jsp?fd=YEAR">Next year</a>

      Previous Year:

      <a href="doRoll.jsp?fd=YEAR&amt=-1">Previous year</a>

4. Save and close the file.

   "Next year" and "Previous year" must be localized in cal.properties file (in <iPS_install_base>/SUNWips/locale) instead of hard coded in the template.

To change the time format for a day:

1. Log in to the Mobile Access Pack server and become superuser.

2. Change directories to /<iPS_install_base>/SUNWips/locale.

3. Modify the cal.properties file. That is, change the title date format.

      datefmt = "EEE MMM d yyyy" to "MMMMM d, yyyy"

   The display for the current date will be changed, for example, from "Wed Aug 29 2001" to "August 29, 2001"

4. Save and close the file.

To add event end fields to event list in dayview:

1. Log in to the Mobile Access Pack server and become superuser.

2. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<locale>/cal/<clientType>.

3. Modify the dayview.jsp file. That is, add the following lines to display the end time.

      <cal:event>

         <cal:get id="end" property="endTime"/>

         <cal:dateformat name="end" format="$[i18n:timefmt]"/>

      </cal:event>

4. Save and close the file.

iPlanet Messaging Server JSPs

This section discusses the WML and cHTML template files used by the messaging server user interface for a mobile device. See the appropriate figure and the files used by the interfaces (in the figure) to customize the display of the service content on the user's mobile device. Refer to the "iPlanet Messaging Server Client Tag Library" for detailed information on the tags used in these template files to enable the display of mail content on the user's mobile device.

User Interface Flowcharts

This section discusses the mail user interface, for WML and cHTML clients, that utilize the template files discussed in "JSP Files."

The WML and cHTML screen flowcharts shown in use the summary.jsp file. See Table 5-2 for more information on the files.

Figure 5-7    WML and cHTML Mail Home Screen Flowcharts

The WML and cHTML screen flowcharts shown in use inbox.jsp and doInbox.jsp file. See Table 5-2 for more information on the files.

Figure 5-8    WML and cHTML Inbox Screen Flowcharts

The WML and cHTML screen flowcharts shown in use getmsg.jsp and message.jsp files. See Table 5-2 for more information on the files.

Figure 5-9    WML and cHTML Message Screens

The WML and cHTML screen flowcharts shown in use addpab.jsp and doAdd.jsp files. See Table 5-2 for more information on the files.

Figure 5-10    WML and cHTML Screen Flowcharts to Add User to the Address Book

The cHTML and WML screen flowcharts shown in and use compose.jsp, presetMsg.jsp, typeMsg.jsp, pickaddr.jsp, cancel.jsp, and sent.jsp. See Table 5-2 for more information on the files.

Figure 5-11    cHTML Screen Flowcharts to Compose a Message

Figure 5-12    WML Screen Flowcharts to Compose a Message

The WML and cHTML screen flowcharts shown in use menu.jsp file. For WML clients, this is embedded in the message.jsp file. See Table 5-2 for more information on the files.

Figure 5-13    WML and cHML Mail Menu Screens

The WMl and cHTML screen flowcharts shown in use the header.jsp file.

Figure 5-14    WML and cHTML View Headers Screens

The WML and cHTML screen flowcharts shown in and use reply.jsp, compose.jsp, presetMsg.jsp, typeMsg.jsp, pickaddr.jsp, cancel.jsp, and sent.jsp files. Replying and forwarding a message uses the same flow as composing a message (see also and ). See Table 5-2 for more information on the files.

Figure 5-15    cHTML Interface to Reply To or Forward a Message

Figure 5-16    WML Interface to Reply to or Forward a Message

JSP Files

Table 5-2    Mail JSPs

Filename	Description
launchMail.jsp	It launches the mail client on the user's mobile device (see ).
summary.jsp	It provides the mail home page (see ) and displays the Inbox summary (the total number of messages and the number of unread messages).
doInbox.jsp	it handles the fetch inbox command (see "fetch" and ).
getmsg.jsp	It handles the fetch message command (see "fetch" and ).
addpab.jsp	It provides the fields to add the sender to the personal address book database (see also add.jsp, doAdd.jsp in Table 5-3, and ).
doAdd.jsp	It adds the sender to the Personal Address Book database (see ). It uses the error code AB_001 (see errorCode) when it is unable to add the entry to the address book.
cancel.jsp	It aborts the send mail operation and returns to the Inbox (see and ).
delete.jsp	It deletes the selected message from the Inbox.
message.jsp	It displays the message headers and body. It also indicates if there is an attachment, but does not display attachments (see ).
sent.jsp	It handles the send command (see "sendmessage" and see and ). It uses the error code MAIL_001 and MAIL_002 (see errorCode) when it is unable to send the mail.
compose.jsp	It provides the fields to compose a new message (see and ). By default, specify only the email address to send the message to, the subject, and the text of the message. The text of the message can be a preset message (see presetMsg.jsp for more information).
header.jsp	It displays the message headers in detail. By default, it displays the to, cc, date, and subject property fields (see ).
inbox.jsp	it lists the messages in the Inbox in the reverse order; that is, the last or the most recent message is displayed first (see ).
pickaddr.jsp	It allows the user to pick recipients from the Personal Address Book database (see and ).
reply.jsp	It allows the user to reply to the sender or to all recepients of the message (see and ).
typeMsg.jsp	It allows the user to type the message body (see ). For WML clients, this is embedded in compose.jsp and reply.jsp (see ).
menu.jsp	It provides a menu of mail box commands including delete, reply to, or forward a message, add sender to personal address book, view message header, return to the Inbox or to the Mail Home page (see ).
presetMsg.jsp	It allows a message to be saved (or preset) for future use. For WML clients, this is embedded in compose.jsp and reply.jsp.

Sample Customizations

To bypass the summary page and display the user's inbox:

1. Log in to the machine running the Mobile Access Pack server and become superuser.

2. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<locale> and in the launchMail.jsp file, change:

   <util:forward comp="mail" file="summary.jsp"/> to <util:forward comp="mail" file="doInbox.jsp"/>

3. Save and close the file.

To display the number of new messages in the mail summary page:

1. Log in to the machine running the Mobile Access Pack server and become superuser.

2. Change directories to <iPS_install_base>/SUNWips/locale and modify the mail.properties file. That is, in the mail.properties file, enter:

      new=new message(s)

3. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<locale>/mail and in the summary.jsp file (in wml and chtml directories), add lines:

      <mail:get property="numNewMsgs"/>

      <util:msg name="i18n" key="new"/>

4. Save and close the files.

To include links to the Address Book Home and Search Address Book in the mail summary page:

1. Log in to the machine running the Mobile Access Pack server and become superuser.

2. Change directories to /<iPS_install_base>/SUNWips/locale and modify the mail.properties file. That is, in the mail.properties file, enter:

      addressbook=Address Book

      searchab=Search Address Book

3. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<default>/mail and in the summary.jsp file (in wml and chtml directories), add the following lines to the end of the file:

         %><%-- address book --%>

         <util:link tagstart="<a" tagend=">"><%

             %><util:attr attr="href"><%

               %><util:url file="abHome.jsp" comp="ab"/><%

            %></util:attr><%

         %></util:link><%

         %><util:msg name="i18n" key="addressbook"/>...</a>

         %><%-- search address book --%>

         <util:link tagstart="<a" tagend=">"><%

            %><util:attr attr="href"><%

               %><util:url file="search.jsp" comp="ab"/><%

            %></util:attr><%

         %></util:link><%

         %><util:msg name="i18n" key="searchab"/>...</a><%

4. Save and close the files.

Personal Address Book JSPs

This section discusses the WML and cHTML template files used by the address book client graphical user interface for a mobile device. See the appropriate figure and the files used by the interfaces (in the figure) to customize the display of the address book client on the user's mobile device. Refer to the "Personal Address Book Client Tag Library" for detailed information on the tags used in these template files to enable the display of address book content on the user's mobile device.

User Interface Flowcharts

This section discusses the address book user interface on WML and cHTML clients that utilize the template files discussed in "JSP Files."

The WML and cHTML screens shown in use abHome.jsp and list.jsp files. See Table 5-3 for detailed information on the files.

Figure 5-17    WML and cHTML Address Book Home Screens

The WML and cHTML screens shown in use view.jsp file.

Figure 5-18    WML and cHTML Screens to View a Contact

The WML and cHTML screens shown in use edit.jsp, add.jsp, and doAdd.jsp files. See Table 5-3 for detailed information on the files.

Figure 5-19    WML and cHTML Screen Flowcharts to Add a Contact

The WML and cHTML screens shown in use edit.jsp, change.jsp, and doChange.jsp files. See Table 5-3 for detailed information on the files.

Figure 5-20    WML and cHTML Screen Flowcharts to Change a Contact

The WML and cHTML screens shown in use delete.jsp file. See Table 5-3 for detailed information on the files.

Figure 5-21    WML and cHTML Screens to Delete a Contact

The WML and cHTML screens shown in use search.jsp, doSearch.jsp, and list2.jsp files. See Table 5-3 for detailed information on the files.

Figure 5-22    WML and cHTML Screen Flowcharts to Search for a Contact

JSP Files

Table 5-3    Address Book JSPs

Filename	Description
launchAB.jsp	It launches the address book client on the user's mobile device (see )
abHome.jsp	It provides the address book home page for the mobile client (see ). It verifies the validity of the session and initializes the connection to the address book database. Once the connection is established, it fetches all entries (in the sorting order discussed in "fetch") in the address book database and forwards the entries to list.jsp.
list.jsp	It displays all the entries in the address book database on the address book home page (see ). If there are too many entries, it chunks the entries.
search.jsp	It provides the address book search page to search for an entry in the address book database (see ). It takes only one entry property to search for in the database.
doSearch.jsp	It searches the address book database for the specified entry and forwards the search result to list2.jsp (see ). It can search for only one entry property (see "entry") in the database.
list2.jsp	It displays the results of the search (see "fetch" and ).
edit.jsp	It provides the address book entry properties (see "entry") for adding (see "add") or changing (see "modify") an entry in the address book database.
add.jsp	It provides the address book add contact page with empty fields to fill in with the entry properties (see "add" and ). By default, to add an entry, specify only the first name, last name, email, and home phone number.
doAdd.jsp	It adds the specified entry (using the entry properties passed in the URL) to the address book database (see ). It uses the error code AB_001 (see errorCode) when it is unable to add the entry to the address book.
view.jsp	It displays the properties of the specified address book entry on the address book view contact page (see ).
change.jsp	It provides the address book change contact page to modify the specified entry properties (see "modify" and ). By default, only the first name, last name, email, and home phone number can be modified.
doChange.jsp	It modifies the specified entry (using the entry id and entry properties passed in the URL) in the address book database (see ). It uses the error code AB_001 (see errorCode) when it is unable to modify the entry in the address book.
delete.jsp	It deletes the specified address book entry from the address book database and returns to the address book home page (see also "delete" and ).

Sample Customizations

To enable search on different fields in the address book

1. Log in to the machine running the Mobile Access Pack server and become superuser.

2. Change directories to <ips_install_base>/SUNWips/public_html/jsp/<locale>/ab/<clientType>/<UP or Nokia if clientType is wml>.

3. Modify the search.jsp file. That is, add more <input> wml tags similar to <input name="str"/> and pass them on to doSearch.jsp similar to <a href="doSearch.jsp?str=$(str)">Go</a>.

4. Save and close the file.

5. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<locale>/ab and modify the doSearch.jsp file. That is, modify the fetch entry to something similar to the following:

      <ab:fetch ln="$(ln)" fn="$(fn)"/>

6. Save and close the file.

To add field values to address book entries
For example, in order to add business phone (bp) number in the address book:

1. Log in to the machine running the Mobile Access Pack server and become superuser.

2. Change directories to <ips_install_base>/SUNWips/public_html/jsp/<locale>/ab/<clientType>/<UP or Nokia if clientType is wml>.

3. Modify the add.jsp file. That is, add more <input> wml tags similar to <input name="bp"/> and pass them on to doAdd.jsp similar to <a href="doAdd.jsp?bp=$(bp)">Go</a>.

4. Save and close the file.

5. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<locale>/ab and modify the doAdd.jsp file. That is:

      <ab:set property="bp" value="$(bp)"/>

6. Save and close the file.

To display the error messages:

1. Log in to the Mobile Access Pack server and become superuser.

2. Change directories to <iPS_install_base>/SUNWips/public_html/jsp/<locale>/.

3. Modify the error.jsp file. For example, add the following line:

      <util:msg name="i18n" key="servererror"/>

      <%= exception.toString() %>

   This will print out java exception to the mobile device.