20. Writing Mobile Applications in ADF UIX

One of the goals of Oracle ADF UIX is to provide the same technology to write pages for different devices. This chapter discusses how to write a mobile application using UIX.

UIX is currently supported on Internet Explorer on a Pocket PC, Palm Web Pro 3.0 on Palm OS, and Blazer 3.0 on Palm OS. There is not currently phone/pager support. In the future this will be supported in conjunction with iAS Wireless.

This chapter contains the following sections:

Introduction
UI Considerations
Agent Types
Targeting a pda

Introduction

In most ways writing a mobile application in UIX is the same as writing a desktop application in UIX. The following example demonstrates this.



<ctrl:page xmlns="http://xmlns.oracle.com/uix/ui"
           xmlns:ctrl="http://xmlns.oracle.com/uix/controller"
           expressionLanguage="el">

  <ctrl:content xmlns:ui="http://xmlns.oracle.com/uix/ui">

   <form name="demoForm"
         xmlns="http://xmlns.oracle.com/uix/ui">
     <contents>
       <pageLayout title="New Expense">
         <privacy>
           <link text="Privacy"
                 destination="http://www.oracle.com"/>
         </privacy>
         <about>
           <link text="About"
                 destination="http://www.oracle.com"/>
         </about>
         <globalButtons>
           <globalButtonBar>
             <contents>
               <globalButton text="Home"
                             destination="http://www.oracle.com"/>
               <globalButton text="Portal"
                             destination="http://www.oracle.com"/>
             </contents>
           </globalButtonBar>
         </globalButtons>
         <corporateBranding>
           <image source="images/pdaOracle.gif"/>
         </corporateBranding>
         <pageButtons>
           <pageButtonBar>
             <contents>
               <submitButton text="OK" event="error"/>
               <submitButton text="Cancel"/>
               <submitButton text="New Expense"/>
             </contents>
           </pageButtonBar>
         </pageButtons>
         <contents>
           <labeledFieldLayout>
             <contents>
               <messageTextInput required="yes"
                                 id="amount"
                                 name="amount"
                                 prompt="Amount"/>
               <messageDateField required="yes"
                                 name="date"
                                 prompt="Date" />
               <inlineMessage  prompt="Have Receipt">
                 <contents>
                   <flowLayout>
                     <contents>
                       <radioGroup name="receipt">
                         <childData>
                           <option text="Yes" value="yesReceipt"/>
                           <option text="No" value="noReceipt"/>
                         </childData>
                       </radioGroup>
                     </contents>
                   </flowLayout>
                 </contents>
               </inlineMessage>
             </contents>
           </labeledFieldLayout>
         </contents>
       </pageLayout>
     </contents>
   </form>
 </ctrl:content>
</ctrl:page>

The following images show how the page is displayed on a destop browser and pda.

Figure 20-1: Desktop Browser
UIX XML rendered in web browser

Figure 20-2: Pda Browser
UIX XML rendered in PDA

UI Considerations

Although one of the goals of UIX is to provide the same technology to write pages for different devices, this does not mean developers will be able to "write once, run anywhere". Here are some of the reasons why:

Screen size: The size of a desktop screen is larger than the size of a pda screen, which is larger than the size of a phone screen.
User input: It is easier for a user to enter data on a desktop than on a pda, and it is quite difficult to enter data on a phone.

It should be apparent that a page designed for a pda will look best if it is relatively simple, and that most pages designed with a desktop in mind will look overwhelming on a pda. This is an example of why the goal of UIX is to provide a single technology to write pages for different devices, not to use the same UIX pages on every device.

Agent Types

Looking at the example given in the Introduction section above shows that output is modified depending on the device making the request, for example page buttons are repeated and right aligned on a desktop browser, but rendered once and left aligned on a pda. Devices are grouped into the following three "types":

Agent.TYPE_DESKTOP: Devices with a full-sized screen, like a desktop or laptop.
Agent.TYPE_PDA: Devices with a medium-sized screen, like a pda.
Agent.TYPE_PHONE: Devices with a small-sized screen, like a phone or pager.

Developers should write pages with a specific agent type in mind. In fact while many pages can run on multiple agent types, this is not always the case. For a given agent type, a bean may not be supported at all, or certain attributes or children may not be supported. In general what's supported on a desktop machine is a superset of what's supported on a pda, which is a superset of what's supported on a phone. This reflects the fact that in general the functionality on a desktop machine is a superset of the functionality of a pda, which is a superset of the functionality of a phone.

Developers can determine the agent type in UIX XML with the <agent> tag. An example:


<ctrl:page xmlns="http://xmlns.oracle.com/uix/ui"
           xmlns:ctrl="http://xmlns.oracle.com/uix/controller">
  <ctrl:content>
    <dataScope>
      <contents>
        <flowLayout>
         <contents>
           <styledText styleClass="OraInstructionText" text="You are looking at this on a "/>
           <styledText styleClass="OraInstructionText" >
             <boundAttribute name="text">
               <if>
                 <agent type="desktop"/>
                 <fixed text="desktop or laptop."/>
                 <if>
                   <agent type="pda"/>
                   <fixed text="pda."/>
                   <fixed text="um, well, let's see, not a desktop machine, laptop, or pda. You're wild!"/>
                 </if>
               </if>
             </boundAttribute>
           </styledText>
          </contents>
        </flowLayout>
      </contents>
    </dataScope>
  </ctrl:content>
</ctrl:page>

Targeting a pda

Scripting

Developers should not rely on javascript support. While pda browsers are moving toward supporting javascript, many still don't. The script bean is supported to enhance the user experience on javascript-enabled browsers, but an application should not fail if scripting isn't available.

Typically, this means not relying on javascript to do client-side validation. While developers should always be doing server-side validation, this is an absolute must for a mobile application.

Component Support

Below are lists of some of the differences between what is supported on a desktop machine and a pda. This is not a complete list. The componenent specific documentation has information about any attribute(s) and/or child(ren) that aren't supported on a pda.

The following components aren't supported. Neither the component nor its children are rendered and a warning is written to the error log.

AddTableRow
ApplicationSwitcher
BrowseMenu
ContentContainer
FileUpload
HGrid
Shuttle
SideBar
SideNav
StyledItem
StyledList
SubTabBar
TotalRow
Tree

The following components are ignored. No warning is written to the log as these should not be essential to the correct behavior of the page.

Footer
QuickLinks
StyleSheet

The following components render nothing themselves, but do render their indexed children.

HideShow
HideShowHeader
SubTabLayout
Tip

The following components are supported on a pda. Their behavior, however, deviates sufficiently from the behavior on a desktop machine as to be worth mentioning.

Multiple windows are not available on most pda browsers, so on a pda there is page navigation with the following components.

DateField - The application must navigate onto a separate calendar page. Thus on the pda the dateField sends a 'date' event which can be handled by the class oracle.cabo.servlet.event.mobile.DateEventHandler. For those not using the UIX Servlet, there is a utility class oracle.cabo.servlet.event.mobile.DateEventUtils. An example follows:

<ctrl:page xmlns="http://xmlns.oracle.com/uix/ui"
           xmlns:ctrl="http://xmlns.oracle.com/uix/controller"
           expressionLanguage="el">
  <ctrl:content>
    <form name="demoForm">
      <contents>
        <messageDateField required="yes" name="p_date" prompt="Date" value="${uix.eventResult.p_date}"/>
      </contents>
    </form>
  </ctrl:content>
  <ctrl:handlers>
   <ctrl:event name="date cancel" >
     <ctrl:instance class="oracle.cabo.servlet.event.mobile.DateEventHandler"
                    method="getEventHandler" />
   </ctrl:event>
  </ctrl:handlers>
</ctrl:page>

LovInput - The application must navigate to/from a separate listOfValues page. On the pda the lovInput sends a 'lovFilter' event with an additonal 'uri' parameter containing the value of the 'destination' attribute. It is necessary to forward to this destination on the server.
ListOfValues - The application must navigate to/from the lovInput page. It is necessary to forward or redirect from the listOfValues page back the lovInput page on the server. It is up to the application to know where to forward or redirect. On pda there is no support to do a search from the listOfValues page.

Other components with differences worth mentioning:

Frame - renders as its own page
FrameBorderLayout - a list of links to frames
LovField - a textfield but no button
MessageBox - does not render indexed children
PageLayout - many children not supported

Decoding Parameters

Due to limitations in a pda, multiple parameters may be encoded as a single parameter, and thus need to be decoded. Developers using the UIX Servlet do not need to worry about this as parameters are decoded automatically. Otherwise the developer has several options to decode the parameters.

If using a javax.servlet.ServletRequest, then developers can use it to create an instance of oracle.cabo.share.data.ServletRequestParameters, and then call on it any method found on ServletRequest to access parameters. For example, suppose "request" is an instance of ServletRequest and the code is as follows:


     String fooValue = request.getParameter("foo");
     ....

This could be replaced by the following:


     ServletRequestParameters params = new ServletRequestParameters(request)
     String fooValue = params.getParameter("foo");
     ....

Another possibility is to use "request" to retrieve a java.util.Dictionary. For example:


     Dictionary d = ServletRequestParameters.createRequestDictionary(request);
     String fooValue = (String)d.get("foo");

Developers can also start with a java.util.Dictionary and have a Dictionary returned. For example, suppose "dictionary" is an instance of Dictionary:


     Dictionary d = ServletRequestParameters.createRequestDictionary(dictionary);
     String fooValue = (String)d.get("foo");

HTTP cache headers

Web Browser 2.0 on palm uses a cached version of a page when no cache information is sent with the HTTP response. This is different from all other browsers we support which don't use a cached version when no cache information is sent. If you are not using the UIX Servlet you must set the http "Cache-Control" response header to "no-cache" if a page has been modified.