5 Defining an ADF Mobile Application

5.1.1 Using the Overview Editor for adfmf-applications.xml

The overview editor enables you to configure the adfmf-application.xml file to describe a mobile application and its resources. Each page of the editor enables you to add or update the elements of the configuration file.

5.3.1 How to Set the ID and Display Behavior for a Mobile Application

The Application page of the overview editor, shown in Figure 5-2, enables you to name the mobile application and control the display of the mobile application within the springboard and navigation bar.

Before you begin:

Open the overview editor for the adfmf-application.xml file by double-clicking the adfmf-application.xml file (located in the ADF META-INF node of the Application Resources panel, as shown in Figure 5-3).

Figure 5-3 Selecting the adfmf-application.xml File in the Application Navigator.

To set the basic information for a mobile application:

1. Choose the Application page and if needed, choose the Overview tab.

   Note:

   By default, the editor opens the Application page.

   Figure 5-4 shows the portion of the application page where you define the basic information.

   Figure 5-4 Setting the Basic Information for the ADF Mobile Application

   
   

2. Enter a display name for the application in the Name field. This attribute can be localized. For more information, see Section 5.10, "Working with Resource Bundles."

   Note:

   ADF Mobile uses the value entered in this field as the name for the iOS archive file (that is, the .ipa file) that it creates when you deploy the application to an iOS-powered device. For more information, see Section 16.2.4, "How to Create an iOS Deployment Profile."

3. Enter a unique ID in the Id field.

   To avoid naming collisions, Android and iOS use reverse package names, such as com.company.application. JDeveloper prepends com.company as a reverse package to the application name, but you can overwrite this value with another as long as it is unique and adheres to the ID guidelines for both iOS- and Android-powered devices. For iOS application, see the "Creating and Configuring App IDs" section in iOS Team Administration Guide (available from the iOS Developer Library at http://developer.apple.com/library/ios). For Android, refer to the information provided about the Android manifest file available from the Android Developers website (http://developer.android.com/guide/topics/manifest/manifest-intro.html). You can overwrite this ID in the deployment profiles described in Section 16.2.3, "How to Create an Android Deployment Profile" and Section 16.2.4, "How to Create an iOS Deployment Profile."

   Note:

   To ensure that an application deploys successfully to an Android-powered device or emulator, the ID must begin with a letter, not with a number. For example, an ID comprised of a wholly numeric value, such as 925090 (com.company.925090) will prevent the application from deploying. An ID that begins with letters, such as hello925090 (com.company.hello925090) will enable the deployment to succeed.

4. Enter a short, but detailed summary of the application that describes the application's purpose in the Description field.

5. Enter the version in the Version field.

6. Enter the name of the vendor who originated this application in the Vendor field.

7. Click Browse in the Lifecycle Event Listener field to invoke the Edit Property dialog, shown in Figure 5-5, to register the event listener that enables runtime calls for start, stop, activate, and deactivate events. You must enter the fully qualified class name of the event listener. This is an optional field.

   Figure 5-5 Retrieving the Application Event Listener

   
   

   The default application listener class is application.LifeCycleListenerImpl. ADF Mobile does not register this class by default, because it starts the JVM and therefore may not be preferable for each ADF Mobile application. You must instead register this class manually using the Edit Property dialog, shown in Figure 5-5. After you close this dialog, JDeveloper updates <adfmf:application> element with a listener-class attribute, as illustrated in Example 5-2.

   Example 5-2 Adding the listener-class Attribute

   <adfmf:application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xmlns:adfmf="http://xmlns.oracle.com/adf/mf"
                      name="OracleMobileApplication"
                      id="com.company.OracleMobileApplication"
                      appControllerFolder="ApplicationController" 
                      listener-class="application.LifeCycleListenerImpl"
                      version="1.1"
                      vendor="Oracle">
      <adfmf:description>This is an ADF Mobile application</adfmf:description>
      <adfmf:featureReference id="feature1"/>
   </adfmf:application>
   

   For more information, see Section 5.6, "About Lifecycle Event Listeners."

5.4.1 How to Configure Application Navigation

The Navigation options of the Applications page, shown in Figure 5-6, enable you to hide or show the navigation bar, select the type of springboard used by the application, and define how the springboard reacts when users page through applications.

Figure 5-6 The Navigation Options of the Application Page

Before you begin:

You must select the Application page of the adfmf-application.xml overview editor.

To set the display behavior for the navigation bar:

1. Select Show Navigation Bar on Application Launch to enable the mobile application to display its navigation bar, rather than the springboard, by default after it is launched, as shown in Figure 5-7.

   Figure 5-7 The Navigation Bar, Shown By Default (on iPhone)

   
   

   If you clear this option, then you hide the navigation bar when the application starts, presenting the user with the springboard as the only means of navigation. Because the navigation bar serves the same purpose as the springboard, hiding it can, in some cases, remove redundant functionality.

2. Select Show Navigation Bar Toggle Button to hide the navigation bar when the content of a selected application feature is visible. Figure 5-8 illustrates this option, showing how the navigation bar illustrated in Figure 5-7 becomes hidden by the application feature content.

   Figure 5-8 Hiding the Navigation Bar (on iPhone)

   
   

   This option is selected by default; the navigation bar is shown by default if the show or hide state is not specified by the application feature.

To set the display behavior for the springboard:

1. Select the type of springboard (if any):

   • None—Select this option if the springboard should not be displayed in the application.

   • Default—Select to display the default springboard provided by ADF Mobile, which uses styles illustrated in Figure 5-1. The default springboard is implemented as an ADF Mobile AMX page. For more information, see Section 5.4.5, "What You May Need to Know About Custom Springboard Application Features with ADF Mobile AMX Content."

   • Custom—Select to use a customized springboard, which can be implemented either as an HTML page or as an ADF Mobile AMX page. This application is declared as an application feature in the adfmf-feature.xml file, which is located within a view controller project. For more information, see Section 5.8.1, "How to Define the Basic Information for the Application Feature." For information on enabling navigation within a customized springboard written in HTML, see Chapter 6, "Controlling the Display of Application Features."

     • Feature—Select the application feature used as a springboard, as shown in Figure 5-10.

       Note:

       A custom springboard application feature cannot display within the ADF Mobile application's navigation bar, nor can it display as one of the application features that display in its springboard. For more information, see Section 5.5.1, "How to Designate the Content for a Mobile Application."

       Figure 5-9 Selecting an Application Feature as a Custom Springboard

       
       

2. Select Show Springboard on Application Launch to enable the mobile application to display the springboard to the end user after the mobile application has been launched. (This option is only available for the Default or Custom options.)

3. Select Show Springboard Toggle Button to enable the display of the springboard button, shown in Figure 5-10, that displays within an application feature. Figure 5-7, "The Navigation Bar, Shown By Default (on iPhone)" shows this button within the context of an application feature. This option is only available for the Default or Custom options.

   Figure 5-10 The Springboard Toggle Button (Used on iPhones)

   
   

To set the slide out behavior for the springboard:

1. Select Springboard Animation and then choose Slide Right. The springboard occupies an area determined by the number of pixels (or the percent) entered for the Slideout Width option. If you select None, then the springboard cannot slide from the right (that is, ADF Mobile does not provide the animation to enable this action). The springboard takes the entire display area.

   Note:

   The slide out option is only applicable when you select either the Custom or Default springboard options.

2. Set the width (in pixels). The default width of a springboard on an iOS-powered device is 320 pixels. On Android-powered devices, the springboard occupies the entire screen by default, thereby taking up all of the available width.

   Note:

   If the springboard does not occupy the entire area of the display, then an active application feature occupies the remainder of the display. For more information, see Section 5.4.3, "What Happens When You Set the Animation for the Springboard."

5.4.2 What Happens When You Configure the Navigation Options

Setting the springboard and navigation bar options updates or adds elements to the adfmf:application.xml file's <adfmf:navigation> element. For example, selecting None results in the code updated with <springboard enabled="false"> as illustrated in Example 5-3.

<adfmf:application>
  ...
  <adfmf:navigation>
     <adfmf:navigationBar enabled="true"/>
     <adfmf:springboard enabled="false"/>
  </adfmf:navigation>
</adfmf:application>

<adfmf:application>
  ...
<adfmf:navigation>
    <adfmf:springboard enabled="true"/>
  </adfmf:navigation>
  ...
</adfmf:application>

Example 5-4 illustrates how the enabled attribute is set to true when you select Default.

<adfmf:application>
  ...
  <adfmf:navigation>
     <adfmf:navigationBar enabled="true"/>
     <adfmf:springboard enabled="true"/>
  </adfmf:navigation>
</adfmf:application>

If you select Custom and then select the application feature used as the springboard, the editor populates the <adfmf:navigation> element as illustrated in Example 5-5. The id attribute refers to an application feature defined in the adfmf-feature.xml file that is used as a custom springboard.

<adfmf:navigation>
    <adfmf:springboard enabled="true">
      <adfmf:springboardFeatureReference id="springboard"/>
    </adfmf:springboard>
  </adfmf:navigation>

5.4.3 What Happens When You Set the Animation for the Springboard

Example 5-6 shows the navigation block of the adfmf-application.xml file, where the springboard is set to slide out and occupy a specified area of the display (213 pixels).

<adfmf:navigation>
   <adfmf:navigationBar enabled="true"
                        displayHideShowNavigationBarControl="true"/>
   <!-- default interpretation of width is pixels -->
   <adfmf:springboard enabled="true"
                      animation="slideright"
                      width="213"
                      showSpringbaordAtStartup="true"/>
</adfmf:navigation>

The following line disables the animation:

<adfmf:springboard enabled="true" animation="none"/>

The following line sets the springboard to occupy 100 pixels from the left of the display area and also enables the active application feature to occupy the remaining portion of the display:

<adfmf:springboard enabled="true" animation="slideright" width="100px"/>

In addition to the animation, Example 5-6 demonstrates the following:

• The use of the showSpringboardAtStartup attribute, which defines whether the springboard displays when the application starts. (By default, the springboard is displayed.)

• The use of the navigationBar's displayHideShowNavigationBarControl attribute.

To prevent the springboard from displaying, set the enabled attribute to false.

5.4.4 What You May Need to Know About Custom Springboard Application Features with HTML Content

The default HTML springboard page provided by ADF Mobile uses the following technologies, which you may also want to include in a customized login page:

• Cascading Style Sheets (CSS)—Defines the colors and layout.

• JavaScript—The <script> tag embedded within the springboard page contains methods described in Chapter 6, "Controlling the Display of Application Features" that call PhoneGap APIs. In addition, the HTML page uses JavaScript to respond to the callbacks and to detect page swipes. When swipe events are detected, JavaScript enables the dynamic modification of the style sheets to animate the page motions.

• WebKit—Provides smooth animation of the icons during transitions between layouts as well as between different springboard pages. For more information on the WebKit rendering engine, see http://www.webkit.org/.

Springboards written in HTML are application features declared in the adfmf-feature.xml file and referenced in the adfmf-application.xml file.

5.4.5 What You May Need to Know About Custom Springboard Application Features with ADF Mobile AMX Content

Like their HTML counterparts, springboards written using ADF Mobile AMX are application features that are referenced by the ADF Mobile application, as described in Section 5.5.1, "How to Designate the Content for a Mobile Application."

The default springboard (adfmf.default.springboard.jar, located in jdev_install\jdeveloper\jdev\extensions\oracle.adf.mobile\lib) is an ADF Mobile AMX page that is bundled in a Feature Archive (FAR) JAR file and deployed with other FARs that are included in the ADF Mobile application. This JAR file includes all of the artifacts associated with a springboard, such as the DataBindings.cpx and PageDef.xml files. This file is only available after you select Default as the springboard option in the adfmf-application.xml file. Selecting this option also adds this FAR to the application classpath. For more information, see Section 16.5, "Deploying Feature Archive Files (FARs)."

The default springboard (springboard.amx, illustrated in Example 5-7) is implemented as an ADF Mobile AMX application feature.

<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
          xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <amx:panelPage id="pp1">
      <amx:facet name="header">
         <amx:outputText value="#{bindings.name.inputValue}" id="ot3"/>
      </amx:facet>
      <amx:listView var="row"  
                    value="#{bindings.features.collectionModel}"
                    fetchSize="#{bindings.features.rangeSize}"
                    id="lv1"
                    styleClass="amx-springboard">
         <amx:listItem showLinkIcon="false"  
                       id="li1"
                       actionListener="#{bindings.gotoFeature.execute}">
            <amx:tableLayout id="tl1"
                             width="100%">
               <amx:rowLayout id="rl1">
                  <amx:cellFormat id="cf11"  
                                  width="46px"
                                  halign="center">
                      <amx:image source="#{row.image}"  
                                 id="i1"
                                 inlineStyle="width:36px;height:36px"/>
                  </amx:cellFormat>
                  <amx:cellFormat id="cf12"  
                                  width="100%"
                                  height="43px">
                     <amx:outputText value="#{row.name}" 
                                     id="ot2"/>
                  </amx:cellFormat>
               </amx:rowLayout>
            </amx:tableLayout>
               <amx:setPropertyListener from="#{row.id}" 
                                        to="#{pageFlowScope.FeatureId}"/>
         </amx:listItem>
      </amx:listView>
   </amx:panelPage>
</amx:view>

As shown in Figure 5-11, an ADF Mobile AMX file defines the springboard using a List View whose List Items are the ADF Mobile application's embedded application features. These application features, once deployed, are displayed by their names and associated icons. Selecting an application feature calls the AdfmfContainerUtilities.gotoFeature method. For more information, see Section 6.2.7, "gotoFeature." See also Section 8.2.7, "How to Use List View and List Item Components."

Figure 5-11 The Default Springboard

ADF Mobile provides the basic tools to create a custom springboard (or augment the default one) in the ApplicationFeatures data control. This data control, illustrated in Figure 5-12, enables you to declaratively build a springboard page using its data collections of attributes that describe both the ADF Mobile application and its application features.

Figure 5-12 The ApplicationFeatures Data Control

The methods of the ApplicationFeatures data control enable you to add navigation functions. These adfmf.containerUtilities methods are described in Table 5-2. For more information, see Section 6.2, "The ADF Mobile Container Utilities API." See also Chapter 9, "Using Bindings and Creating Data Controls."

5.5.1 How to Designate the Content for a Mobile Application

Figure 5-13 shows the Feature References page, which enables you to build the content for the mobile application. As noted in Section 5.2, "About the Mobile Application Configuration File," the mobile application descriptor file's <adfmf:featureReference> element designates these application features.

<adfmf:featureReference id="Customers"
                        allowDeviceAccess="true"
                        showOnSpringboard="true"
                        showOnNavigationBar="true"/>
<adfmf:featureReference id="HCM"
                        allowDeviceAccess="true"
                        showOnSpringboard="true"
                        showOnNavigationBar="true"/>
<adfmf:featureReference id="PROD"
                        allowDeviceAccess="true"
                        showOnSpringboard="true"
                        showOnNavigationBar="true"/>

Example 5-8 shows some of the defined feature references and their associated attributes. The overview editor displays these feature references in the Feature References table. Figure 5-13 shows the defined feature references for HCM and PROD that represent the Customers and Products application features, respectively. Using this page, you enter the references to the application feature and set its display within the mobile application's springboard, as shown in Figure 5-1.

In addition, the page enables you to set the order in which the application features display on the navigation bar and springboard.

Figure 5-13 Designating Application Features Using the Feature References Page

Before you begin:

You must have application features configured in the adfmf-feature.xml file, as described in Section 5.8, "Setting the Basic Configuration for the Application Feature." In addition, you must open the adfmf-application.xml overview editor.

To designate feature references:

1. Click the Feature References page of the adfmf-application.xml overview editor.

2. Click Add.

3. In the Insert Feature Reference dialog, select the ID of the application feature from the dropdown list, as shown in Figure 5-14.

   This dialog lists all of the application features described in the <adfmf:feature> elements of the adfmf-feature.xml file Using this dialog ensures that the id attributes of both the <adfmf:featureReference> and <adfmf:feature> elements match. See also Section 5.5.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."

   Figure 5-14 Selecting the Content for the Mobile Application

   
   

4. If needed, use the up- and down-arrows shown in Figure 5-14 to arrange the display order of the feature references, or use the dropdown list in rows of the Id column, shown in Figure 5-15, to reorder the feature references.

   Note:

   The top-most ID in the Feature References table is the first application feature to display within the ADF Mobile application. See, for example, the Employees application feature illustrated in Figure 5-7.

   Figure 5-15 Reordering Feature References

   
   

5. Set the springboard and navigation bar display behavior for the application feature by selecting true or false from the dropdown lists in the rows of the Show on Navigation Bar and Show on Springboard columns. Figure 5-16 shows selecting these options to prevent an application feature from displaying in the navigation bar.

   Figure 5-16 Changing the Navigation Options

   
   

   By default, display is enabled (that is, true) for the springboard and the navigation bar. If both the navigation bar and springboard attributes are set to false, then the application feature only displays if it is in the first position. See also Section 6.2.12, "hideNavigationBar" and Section 6.2.13, "showNavigationBar."

   Note:

   Because springboard applications do not display on the navigation bar or within the springboard of an ADF Mobile application, Show on Navigation Bar and Show on Springboard must both be set to false for feature references for custom springboard application features. See also Section 5.4.5, "What You May Need to Know About Custom Springboard Application Features with ADF Mobile AMX Content."

6. To enable a domain configured within the connections.xml file to access the device services enabled by the ADF Mobile PhoneGap API, select true in the Allow Device Access column. By default, all application features allow such access. To prevent domains from accessing device services, select false. For more information, see Chapter 12, "Implementing Application Features as Remote URLs."

5.5.2 What You May Need to Know About Feature Reference IDs and Feature IDs

An ADF Mobile application can contain many projects and can therefore also include multiple adfmf-feature.xml files. In the application configuration file, a feature reference relates to a feature described by an adfmf-feature.xml file. The ID of an <adfmf:featureReference> identifies where the corresponding application feature is defined. In other words, the id attributes for <adfmf:featureReference> elements in the adfmf-application.xml file must be the same as the id attribute defined for <adfmf:feature> element in adfmf-feature.xml. For example, <adfmf:featureReference id="customers"> in adfmf-application.xml is defined by <adfmf:feature id="customers"> in adfmf-feature.xml. JDeveloper audits the references between the application and feature descriptor files in the same mobile application, and warns you when it finds discrepancies. As shown in Figure 5-17, JDeveloper highlights the mismatch within the code between a feature reference and the features declared in the features application descriptor file with a wavy underline and a Reference not Found warning, which in this case is a feature reference ID defined as PRiD rather than the correct PROD. For more information on JDeveloper's syntax auditing, see the "Auditing and Profiling Applications" chapter in Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

Figure 5-17 Auditing id Attributes

If the ID for an <adfmf:featureReference> is defined in the adfmf-feature.xml file, you can use Go To Declaration in the context menu, as shown in Figure 5-18, to traverse from the id of a <adfmf:featureReference> in the adfmf-application.xml file to the corresponding id of the <adfmf:feature> in the adfmf-feature.xml file.

Figure 5-18 Finding Application Feature Declarations in the adfmf-feature.xml File

5.6.1 Events in ADF Mobile Applications

Lifecycle listener classes for ADF Mobile applications must implement the start, stop, activate, and deactive methods of the LifeCycleListener interface, illustrated in Example 5-11.

package oracle.adfmf.application;
 
public interface LifeCycleListener
{
   void start();
   void stop();
   void activate();
   void deactivate();
}

The AppListener class, shown in Example 5-12, uses the LifeCycleListener method calls for starting or stopping events as well as those used when the application is about to hibernate (deactivate) or return from hibernating (activate).

package some.package;
import oracle.adfmf.application.LifeCycleListener;
 
public class AppListener implements LifeCycleListener
{
    public AppListener()
    {
        super();
    }
    public void start()
    {
        // Perform application startup tasks...
    }
    public void stop()
    {
        // Perform tasks to stop the application...
    }
    public void activate()
    {
        // Perform appplication activation tasks...
    }
    public void deactivate()
    {
        // Perform application deactivation tasks...
    }
}

5.6.2 Timing for Mobile Application Events

ADF Mobile calls application lifecycle events at specific times during the ADF Mobile application's startup, shutdown, and hibernation. Table 5-3 describes when these events are fired and also notes their Objective-C counterparts.

5.6.3 About Application Feature Lifecycle Listener Classes

An ADF Mobile application feature lifecycle listener class, such as FeatureListenerPhoneList illustrated in Example 5-14, must implement the activate and deactivate methods of the LifeCycleListener interface, shown in Example 5-13, to hide the application feature when it hibernates or to display it when it returns from hibernating.

package oracle.adfmf.feature;
public interface LifeCycleListner
{
   void activate();
   void deactivate();
}

Example 5-14 illustrates a class called FeatureListenerPhoneList that uses the activate and deactive functions by implementing the LifeCycleListener to show and hide the application feature as described in Table 5-4.

package some.package;
 
import oracle.adfmf.feature.LifeCycleListener;
 
public class FeatureListenerPhoneList implements LifeCycleListener
{
    public FeatureListenerPhoneList()
    {
        super();
    }
    public void activate()
    {
        // Perform application activation tasks...
    }
    public void deactivate()
    {
        // Perform application deactivation tasks...
    }
 
}

5.6.4 Timing for Activate and Deactivate Events in the Application Feature Application Lifecycle

Table 5-4 describes when the activate and deactivate events are fired for an application feature.

5.8.1 How to Define the Basic Information for the Application Feature

The General tab of the overview editor, shown in Figure 5-19, enables you to add an application feature, designate its basic information, and its display icons.

Figure 5-19 The General Tab of the Feature Application

Before you begin:

If an application feature uses custom images for the navigation bar and springboard rather than the default ones provided by ADF Mobile, you must create these images to the specifications described the Android Developers website (http://developer.android.com/guide/practices/ui_guidelines/icon_design.html) and in the "Custom Icon and Image Creation Guidelines" chapter in iOS Human Interface Guidelines, which is available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

You place these images in the view controller project's public_html directory. See also Section 5.9.2, "What You May Need to Know About Selecting External Resources."

In addition, you must open the adfmf-feature.xml file and select the General tab.

To set the basic information for the application feature:

1. Choose the General tab.

2. Click Add in the Features table.

3. Complete the Create ADF Mobile Feature dialog, shown in Figure 5-17, and then click OK. To complete this dialog:

   • Enter a display name for the application feature in the Feature Name field.

   • Enter a unique identifier for the application feature in the Feature ID field.

   • If needed, change the location for the application feature to any directory within the public_html directory (the default parent directory). Enter this location in the Directory field.

   • To include the newly defined application feature in the mobile application, add a new <adfmf:featureReference> element to the adfmf-application.xml file with the id attribute that matches the value that you entered in the Feature ID. Choose Add a corresponding feature reference to adfmf-application.xml. The table in the Feature References page, shown in Figure 5-13, includes the feature reference after you complete the dialog. See also Section 5.5.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."

     Figure 5-20 Adding an Application Feature

     
     

4. In the General tab of the overview editor, enter the originator of the application feature in the Vendor field. This is an optional value.

5. Enter the version number of the application feature in the Version field. This is an optional value.

6. Enter a brief description of the application's purpose in the Description field. This is an optional value.

7. Enter the fully qualified class name (including the package, such as oracle.adfmf.feature) using the Class and Package Browser in the Lifecycle Event Listener field to enable runtime calls for start, stop, hibernate, and return to hibernate events. For more information, see Section 5.6, "About Lifecycle Event Listeners." This is an optional value.

8. In the Navigation Bar Icon and Springboard Image fields, browse to, and select, images from the project to use as the icon in the navigation bar and also an image used for the display icon in the springboard. You can also drag and drop the image files from the Application navigator into the file location field. This is an optional value.

5.9.1 How to Define the Application Content

The Content tab of the overview editor, shown in Figure 5-21, provides you with dropdown lists and fields for defining the target content-related elements and attributes shown in Example 5-16. The fields within this tab enable you to set constraints that can control the type of content delivered for an application feature as well as the navigation and springboard icon images that it uses.

Each content type has its own set of parameters. As shown in Figure 5-21, for example, you must specify the location of the ADF Mobile AMX page or task flow for the application features that you implement as an ADF Mobile AMX. In addition, you can optionally select a CSS file to give the application feature a look and feel that is distinct from other application features (or the ADF Mobile application itself), or select a JavaScript file that controls the actions of the ADF Mobile AMX components.

Figure 5-21 Defining the Implementation of the Application Feature

Before you begin:

Each content type has its own prerequisites, as follows:

• ADF Mobile AMX—An application feature implemented as ADF Mobile AMX requires an existing view (that is, a single ADF Mobile AMX page) or a bounded or unbounded task flow. Including a JavaScript file provides rendering logic to the ADF Mobile AMX components or overrides the existing rendering logic. Include a style sheet (CSS) that includes selectors to specify a custom look and feel, one that overrides the look and feel of the skinning files provided for the embedded application features at the ADF Mobile application level. By including a CSS, you ensure that the entire application feature has its own look and feel.

  If you create the ADF Mobile AMX pages as well as the mobile application that contains them, you can create both using the wizards in the New Gallery. You access these wizards by first highlighting the view controller project in the Application Navigator and then by choosing New. Alternatively, you can create an ADF Mobile AMX page using the context menu shown in Figure 5-22 that appears when you right-click the view controller project in the Application Navigator and then choose New. For information on building an ADF Mobile AMX page, see Chapter 7, "Creating ADF Mobile AMX Pages."

  Figure 5-22 Context Menu for Creating an ADF Mobile Page

  
  

• Remote URL—The remote URL implementation requires a valid web address as well as a hosted mobile application. For more information, see Chapter 12, "Implementing Application Features as Remote URLs."

• Local HTML—An application feature implemented as local HTML requires an existing bundle of HTML files and supporting resources.

To define the application content as Remote URL or Local HTML:

1. Select an application feature listed in the Features table in the adfmf-feature.xml file.

2. Click Content.

3. Click Add to create a new row in the Content table (see, for example, products.1 in Figure 5-21).

4. Select one of the following content types to correspond with the generated ID:

   • Remote URL

   • Local HTML

5. Define the content-specific parameters:

   • For remote URL content, select the connection, as shown in Figure 5-23, that represents address of the web pages on the server (and the location of the launch page).

     Figure 5-23 Selecting the Connection for the Hosted Application

     
     

     You can create this connection by first clicking Add and then completing the Create URL Connection dialog, shown in Figure 5-24. For more information on this dialog, see the online help for Oracle JDeveloper. This connection is stored in the connections.xml file.

     Note:

     This connection can only be created as an application resource.

     Figure 5-24 Creating a URL Connection

     
     

   • For local HTML content, enter the location of the local bundle or create the HTML page by clicking Add in the URL field, completing the dialog as shown in Figure 5-25, and then building the page using JDeveloper's HTML editor. Because this is an application feature, this page is stored within the Web Content folder of the view controller project.

     Figure 5-25 Creating the Local HTML Page as the Content for an Application Feature

     
     

6. If needed, do the following:

   • Enter constraints that describe the conditions under which this content is available to users. For more information, see Chapter 14, "Setting Constraints."

   • Select navigation bar and springboard images.

To designate the application feature content as ADF Mobile AMX:

1. Select the application feature.

2. Click Content.

3. If needed, click Add to create a row in the Content table and the choose ADF Mobile AMX from the dropdown list in the Type column as shown in Figure 5-26.

   Figure 5-26 Selecting ADF Mobile AMX as the Content Type

   
   

4. In the File field, click Browse, and choose either ADF Mobile AMX Page or Task Flow, as shown in Figure 5-27, to navigate to, and retrieve, the location of the ADF Mobile AMX page or the bounded task flow. Alternatively, you can drag and drop an ADF Mobile AMX page from the Application Navigator into the file location field.

   Figure 5-27 Browsing for the File Location in the File Field

   
   

5. Alternatively, create the page or task flow. To do this:

   1. Click Add in the File field and then choose either ADF Mobile AMX or Task Flow as shown in Figure 5-28.

      Figure 5-28 Adding an ADF Mobile AMX Page or Task Flow from the File Field

      
      

   2. Complete the create dialogs, such as the Create ADF Mobile AMX Page dialog shown in Figure 5-29.

      Figure 5-29 The Create ADF Mobile AMX Page Dialog

      
      

   3. Build the ADF Mobile AMX page or Task flow using an editor.

6. If needed, do the following:

   • Enter the JavaScript files by clicking Add in the Includes table, choose JavaScript, and then browse to the location of the file. For more information, see Section 5.11.4, "Overriding the Default Skin Styles."

   • Override the default style sheet designated as adfmf-config.xml by first clicking Add and then by choosing Stylesheet. Browse to the location of the file. For more information, see Section 5.11, "Skinning ADF Mobile Applications."

   • Enter the constraints, as described in Chapter 14, "Setting Constraints."

   • Select navigation bar and springboard images.

   Note:

   The images, style sheet, and JavaScript files must reside within the public_html folder to enable deployment. See Section 5.9.2, "What You May Need to Know About Selecting External Resources."

5.9.2 What You May Need to Know About Selecting External Resources

To enable deployment, all resources referenced by the following attributes must be located within the public_html directory of either the view controller or application controller projects.

• The icon and image attributes for <adfmf:feature> (for example, <adfmf:feature id="PROD" name="Products" icon="feature_icon.png" image="springboard.png">). See also Section 5.8.1, "How to Define the Basic Information for the Application Feature."

• The icon and image attributes for <adfmf:content> (for example, <adfmf:content id="PROD" icon="feature_icon.png" image="springboard_image.png">). See also Section 5.9, "Defining the Content Types for an Application Feature."

• The file attribute for <adfmf:amx> (for example, <adfmf:amx file="PRODUCT/home.amx" />). See also Section 5.9, "Defining the Content Types for an Application Feature."

• The url attribute for <adfmf: localHTML> (for example, <adfmf:localHTML url="oracle.hello/index.html"/>). See also Section 5.9, "Defining the Content Types for an Application Feature" and Section 17.4.10, "What Happens When You Designate a Custom Login Page."

• The file attribute defined for type=stylesheet and type=JavaScript in <adfmf:includes> (for example, <adfmf:include type="JavaScript" file="myotherfile.js"/>). See also Section 5.11, "Skinning ADF Mobile Applications."

ADF Mobile does not support resources referenced from another location, meaning that you cannot, for example, enter a value outside of the public_html directory using ../ as a prefix. To safeguard against referencing resources outside of public_html, ADF Mobile includes an audit rule called File not in public_html directory. You can access the ADF Mobile audit profiles, shown in Figure 5-30, from the Audit Profiles node in Preferences by choosing Tools > Preferences > Audit > Profiles.

Figure 5-30 ADF Mobile Audit Profiles

When this profile is selected, JDeveloper issues a warning if you change the location of a resource. As shown in Figure 5-31, JDeveloper displays such a warning when the default values are overridden. For information on auditing, see the "Auditing and Profiling Applications" chapter in Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

Figure 5-31 The External Resource Warning

5.10.1 How to Create Project-Level Resource Bundles

At the project-level, you create resource bundle files when you use the resource bundle dialog, accessed by clicking Select Text Resource in the Property Inspector, shown in Figure 5-33. This dialog enables you to automatically create text resources in the base resource bundle for the adfmf-feature.xml attributes listed in Table 5-7.

Figure 5-33 Localizing Feature Application Attributes

Before you begin:

You may need to configure the resource bundle properties as described in the "How to Set Message Bundle Options" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

To use strings in a resource bundle:

1. Select an attribute in the Property Inspector, such as Name in Figure 5-34.

2. Choose Select Text Resource. Figure 5-34 shows the application name attribute selected in the Property Inspector.

   Figure 5-34 Selecting the Text Resource Dialog

   
   

3. In the Select Text Resource dialog, shown in Figure 5-35, create a new string resource by entering a display name, key, and then click Save and Select.

   Figure 5-35 Select Resource Dialog

   
   

5.10.2 What Happens When You Add a Resource Bundle

After you add a resource in the Select Text Resource dialog, JDeveloper creates a new application-level resource bundle containing the specified display name string and key file in the ADF Meta-INF file, as shown by Application15Bundle.xlf in Figure 5-36.

Figure 5-36 The Application Resource Bundle

If an attribute has been localized for the first time, JDeveloper adds an <adfmf:loadbundle> element whose basename attribute refers to the newly created resource bundle.

JDeveloper also changes the localized attribute string to an EL expression that refers to the key of the string defined in the resource bundle. For example, JDeveloper changes an application name attribute called Acme Sales to name="#{application15Bundle.ACME_SALES}" based on the ACME_SALES value entered for the Key in the Select Resource Dialog.

JDeveloper adds each additional string that you localize to the same resource bundle file because there is only one resource bundle file at the application level.

Each adfmf-application.xml and adfmf-feature.xml file contains only one adfmf:loadBundle element. When you deploy an application, the resource bundles are converted into the language format expected by the runtime.

5.10.2.1 What Happens When You Create Project-Level Resource Bundles for ADF Mobile AMX Components

You can use the project- level resource bundles to localize strings for the attributes of ADF Mobile AMX components as described in Section 8.7, "Localizing UI Components." When you localize a component, such as the text attribute for a <amx:commandButton> in Example 5-17, JDeveloper transforms the string into an EL expression (such as #{viewcontrollerBundle.MYBUTTON in Example 5-17).

Example 5-17 Localizing an ADF Mobile XML Component

<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:amx="http://xmlns.oracle.com/jdev/amx"
          xmlns:dvtm="http://xmlns.oracle.com/jdev/dvtm">
  <amx:panelPage id="pp1">
    <amx:commandButton id="commandButton1" text="#{viewcontrollerBundle.MYBUTTON}" 
  </amx:panelPage>
  <amx:loadBundle basename="mobile.ViewControllerBundle" var="viewcontrollerBundle"/>
</amx:view>

In addition, JDeveloper creates the resource bundle under the project default package, similar to ViewControllerBundle.xlf in Figure 5-37. In the generated <amx:loadBundle> element, the basename represents this package as, for example, mobile.ViewControllerBundle.

Figure 5-37 The Project-Level Resource Bundle

5.10.3 What You May Need to Know About Localizing Image Files

If an image contains text or reflects a specific country or region (for example, a picture of a flag), you can specify an alternate image as part of the localization process. You cannot hard-code the image, such as <amx:image="image2" source="feature1/test.jpg">. Instead, you must edit the ViewControllerBundle.xlf file manually by adding a <trans-unit> element for the image path, as illustrated in Example 5-18.

<trans-unit id="IMAGEPATH">
     <source>/feature1/test.jpg</source>
     <target/>
</trans-unit>

After you update ViewControllerBundle.xlf, use the Expression Builder to define an EL expression for the source attribute for the <amx:image> component, as shown in Figure 5-38.

Figure 5-38 Creating the EL Expression for a Localized <amx:image> Component

5.10.4 What You May Need to Know About XLIFF Files for iOS Applications

A family of one or more XLIFF files must exist at the location described by the <adfmf:loadBundle> element. A family of XLIFF files includes the following:

• Base XLIFF File—The name of the base XLIFF file must match the last token in the path specified by the basename attribute. This file bears the .xlf extension, such as ViewControllerBundle.xlf. In the following definition, the file is called ViewControllerBundle:

  <adfmf:loadBundle var="stringBundle" basename="view.ViewControllerBundle"/>
  

• Zero, or more, localized XLIFF Files—There can be zero (or many) localized XLIFF files for each base XLIFF file. For each file:

  • The file extension must be .xlf.

  • Must be co-located in the same directory as the corresponding base XLIFF file.

  • The file name is in the following format:

    <BASE_XLIFF_FILE_NAME>_<LANGUAGE_TOKEN>.xlf
    

    Where:

    • <BASE_XLIFF_FILE_NAME> is the base XLIFF file name, without the .xlf extension.

    • <LANGUAGE_TOKEN> is in the following format:

      <ISO-639-lowercase-language-code>
      

      Note:

      ADF Mobile does not support countries or regions.

      For example, for Spain, the language token is es. For more information, see the "Manually Defining Resource Bundles and Locales" section in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

    For example, localized file names for XLIFF files referencing a base XLIFF named stringBundle.xlf for language codes en, es, and fr would be:

    • stringBundle_en.xlf

    • stringBundle_es.xlf

    • stringBundle_fr.xlf

5.10.5 Internationalization for iOS Applications

The localizable elements of the adfmf-application.xml and adfmf-feature.xml files reference internationalized strings through the use of EL-like strings in the attributes listed in Table 5-7 and Table 5-6. Because these configuration files are read early in the application lifecycle, these strings are not evaluated as EL statements at runtime. Instead, these strings are taken as the full key for the translated string in the native device translation infrastructure.

Although the Expression Language syntax is "${BUNDLE_NAME.STRING_KEY}", ADF Mobile uses the entire string enclosed by "#{}" as the key to look up the translated string. These strings are in the form of #{bundleName.['My.String.ID']}, where the XLIFF string is separated by periods and #{bundleName.['MyStringID']}, which is used only for string identifiers that are not separated by periods. Example 5-19 illustrates the latter, such as #{strings.CONTACTS}, that modify the name attribute. For the iOS native framework, the deployment ensures that the content of that statement matches the proper key in the *.string file used for translation.

Only the attributes that are displayed to the end user, or control the location of content displayed to the end user, support the use of internationalized strings. These include the following attributes:

• The <adfmf:application> element's name attribute

• The <adfmf:feature> element's name attribute

• The <adfmf:feature> element's icon attribute

• The <adfmf:feature> element's image attribute

• The <adfmf:content> element's icon attribute

• The <adfmf:content> element's image attribute

Example 5-19 shows an application feature with name, icon, and image attributes use internationalization strings.

<adfmf:feature id="CTCS" name="#{strings.CONTACTS}"  
                         icon="#{strings.CONTACTS_ICON}"
                         image="#{strings.CONTACTS_IMAGE}">
        <adfmf:constraints>
            <adfmf:constraint property="user.roles" 
                              operator="contains" 
                              value="employee" />
        </adfmf:constraints>
        <adfmf:description>The HTML Device Contacts</adfmf:description>
        <adfmf:loadBundle basename="mobile.adfmf-stringsBundle"
                          var="strings"/>
        <adfmf:content id="CTCS.Generic">
            <adfmf:constraints />
            <adfmf:localHTML url="contacts.html" />
        </adfmf:content>
    </adfmf:feature>

When you define the <adfmf:loadBundle> elements, as shown in Example 5-20, you create the mapping of bundle names to actual bundles. The bundle name is used when the expression is evaluated.

<adfmf:constraint property="user.roles"  
                  operator="contains"
                  value="employee" />
        </adfmf:constraints>
        <adfmf:description>The HTML Device Contacts</adfmf:description>
        <adfmf:loadBundle basename="mobile.adfmf-featureBundle" 
                          var="mobileBundle"/>
        <adfmf:loadBundle basename="mobile.adfmf-stringsBundle" 
                          var="strings"/>

ADF Mobile's runtime holds the <adfmf:loadBundle> elements until the first access of the JVM. After the ADFChannel for the application feature is created, a message is sent to the JVM to initialize the mapping of basenames to EL names for all of the bundles. Example 5-21 illustrates the structure of the message sent to the JVM:

{classname:"oracle.adfmf.framework.api.Model",method:"setBundles",
 params:[[{basename:"mobile.adfmf-featureBundle",elname:"mobileBundle"},{basename:"mobile.adfmf-stringsBundle",elname:"strings"}]]}

5.11.1 About the adfmf-config.xml File

After you create an ADF Mobile application, JDeveloper populates the adfmf-config.xml file to the ADF Mobile application's META-INF node. The file itself is populated with the base ADF Mobile skin family, MobileFusionfx, illustrated in Example 5-22.

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-config xmlns="http://xmlns.oracle.com/adf/mf/config">
  <skin-family>mobileFusionFx</skin-family>
<skin-version>1</skin-version>
</adfmf-config>

ADF Mobile defines skins for the mobileFusionFx skin family. The skinning hierarchy descends from mobileFusionFx, the top-most skin, the next skin is the platform (iOS), and device-type skins (iPad and iPhone) are at the third level. Figure 5-39 shows the list of seeded form factors in ADF Mobile preference page, which illustrates this hierarchy in terms of platform and model. For more information on how skins are applied at various levels, see Section 5.11.5, "What You May Need to Know About Skinning."

Figure 5-39 The Skinning Hierarchy

5.11.2 About the adfmf-skins.xml File

The adfmf-skins.xml file, located in the META-INF node of the application controller project, uses the <skin> and the <skin-addition> elements. Use the <skin> element to extend a skin family. The <skin-addition> element adds a style sheet to an existing skin.

By default, this file is empty, but the elements listed in Table 5-9 describe the child elements that you can use to populate this file to extend mobileFusionFx or to define the CSS files that are available to the application. You use the <skin> element to create new skins or extend an existing skin. Do not use the <extends> element when defining a new skin.

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-skins xmlns="http://xmlns.oracle.com/adf/mf/config">
    <skin>
        <id>mobileFusionFx.iPhone</id>
        <family>mobileFusionFx</family>
        <extends>mobileFusionFx.iOS</extends>
       <style-sheet-name>styles/myiphone.css</style-sheet-name>
    </skin>
</adfmf-skins>

Table 5-10 lists elements that you can use to define the <skin-addition> element in an ADF Mobile CSS when you must integrate style sheet into an existing skin.

Example 5-23 illustrates designating the location of the CSS file in the <style-sheet-name> element and the target skin family in <skin-id>.

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-skins xmlns="http://xmlns.oracle.com/adf/mf/config">
  <skin-addition>
    <skin-id>mobileFusionFx.iPhone</skin-id>
    <style-sheet-name>skins/mystyles.iphone.addition1.css</style-sheet-name>
  </skin-addition>
</adfmf-skins>

5.11.3 How to Change the Default Skin Family

By editing the adfmf-config.xml and adfmf-skins.xml files, which respectively designate the current skin used by the ADF Mobile application and then describing the skin families available to it, you can customize, add, and test skins.

You can edit the source file directly, or use the Structure window, shown in Figure 5-40, to update the adfmf-skins.xml and adfmf-config.xml files. You maintain all of the skins and skin additions within the adfmf-skins.xml file and then designate the default skin for rendering the application components in the adfmf-config.xml file. You create new CSS files within the application controller project using the Create Cascading Style Sheet dialog. Because the CSS files are associated with the <skin-id>, you then update the <skin-id> elements in adfmf-skins.xml with the new CSS references. If a skin family is not specified in adfmf-config.xml, then it cannot be used for skinning.

Figure 5-40 Configuring the Skinning Files

To customize the default skin:

1. If needed, create a new CSS file:

   1. Right-click the application controller project and then choose New, or click File > New.

   2. In the New Gallery, select HTML (located within Web Tier) and then CSS File. Click OK.

   3. Complete the Create Cascading Style Sheet dialog by entering a name for the CSS file and also a directory location.

      Note:

      The CSS file must reside somewhere within the public_html folder of the application controller project (such as /Users/user name/jdeveloper/mywork/Mobile Application/ApplicationController/public_html/resources/css). The adfmf-skins.xml, where you reference this CSS, is also located within the application controller project (application_workspace/ApplicationController/src/META-INF).

      Figure 5-41 The Create Cascading Style Sheet Dialog

      
      

2. Open the adfmf-skins.xml file.

3. Drag and drop a <skin> component from the ADF Mobile Skins Component Palette to the Structure window.

4. Populate the <skin> element with the elements described in Table 5-9 by completing the Insert skin dialog, shown in Figure 5-42, as follows:

   • family—Enter the base skin family. For these styles to be applied, the base skin family must be the same as the one defined by the <skin-family> element in the adfmf-config.xml file.

   • id—Enter the identifier for the skin.

   • extends—Enter the name of the parent style. For the mobilefusionFX family, enter the base family, appended with the operating system (mobileFusionFx.iOS).

   • style-sheet-name—Retrieve the style sheet.

   Figure 5-42 The Insert Skin Dialog

   
   

5. Click OK.

6. Define the CSS within the adfmf-config.xml file. The context of the CSS definition within this file depends on whether this style sheet is used to extend the mobilefusionfx skin family or be added to it.

To add a new style sheet to a skin

1. Drag and drop a <skin-addition> element from the Component Palette to the Structure window.

2. Populate the <skin-addition> element with the elements described in Table 5-10 by completing the Insert skin-addition dialog, shown in Figure 5-43.

   • Enter the identifier of the skin to which you want to add a new style.

   • Retrieve the location of the CSS file.

   Figure 5-43 The Insert skin-addition Dialog

   
   

3. Click OK.

5.11.4 Overriding the Default Skin Styles

For an ADF Mobile AMX application, you can designate a specific style for the application feature implemented as ADF Mobile AMX, thereby overriding the default skin styles set at the application-level within the adfmf-config.xml and adf-skins.xml files. You add individual styles to the application feature using a CSS file as the Includes file.

5.11.4.1 How to Apply New Style Classes to an Application Feature

The Includes table in the overview editor for the adfmf-feature.xml files enables you to add a cascading style sheet (CSS) to an ADF Mobile AMX application feature.

Figure 5-44 The Includes Table

Before you begin:

Create an ADF Mobile task flow as described in Section 7.2, "Creating Task Flows." Create or add a Cascading Style Sheet as described in the "Importing ADF Skins from an ADF Library JAR" and "About Creating an ADF Skin" sections in Oracle Fusion Middleware Creating ADF Skins with Oracle ADF Skin Editor.

How to add a style to an application feature:

1. Click Add to create a new row in the Includes table.

2. Choose Stylesheet from the dropdown menu in the Type column, as shown in Figure 5-45.

   Figure 5-45 Selecting the StyleSheet Option

   
   

3. In the File column, click Edit, as shown in Figure 5-45.

4. Select the CSS from the Edit Property dialog, shown in Figure 5-46, and then click OK.

   Figure 5-46 Selecting the CSS for the Application Feature

   
   

5.11.4.2 What Happens When You Apply a Skin to a Feature Application

After you add a CSS (or JavaScript file) to the Includes table, the CSS and JavaScript pages added to the application feature can be applied to an ADF Mobile AMX page by selecting the application feature from the Feature Content dropdown menu in the preview pane of the ADF Mobile AMX editor, as shown in Figure 5-47.

Figure 5-47 The Feature Content Dropdown Menu

5.11.5 What You May Need to Know About Skinning

The CSS files defined in the adfmf-skins.xml file, illustrated in Example 5-24, show how to extend a skin to accommodate the different display requirements of the Apple iPhone and iPad. These styles are applied in a descending fashion, as illustrated in Figure 5-39. The SkinningDemo sample application provides a demonstration of how customized styles can be applied when the application is deployed to different devices. This sample application is in the PublicSamples.zip file at the following location within the JDeveloper installation directory of your development computer:

jdev_install/jdeveloper/jdev/extensions/oracle.adf.mobile/Samples

For example, at the iOS level, the stylesheet (mobileFusionFx in Example 5-24) is applied to both an iPhone or an iPad. For device-specific styling, you would define the <skin-id> elements for the iPhone and iPad skins. The skinning demo application illustrates the use of custom skins defined through this element. Figure 5-48 shows how a custom style is applied to an iPhone.

Figure 5-48 iPhone-Specific Rendering

adfmf-skins.xml
<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-skins xmlns="http://xmlns.oracle.com/adf/mf/skins">
    <skin>
        <id>mobileFusionFx.iPhone</id>
        <family>mobileFusionFx</family>
        <extends>mobileFusionFx.iOS</extends>
        <style-sheet-name>skins/mobilefusionfx.iphone.css</style-sheet-name>
    </skin>
    <skin>
        <id>mobileFusionFx.iPad</id>
        <family>mobileFusionFx</family>
        <extends>mobileFusionFx.iOS</extends>
        <style-sheet-name>skins/mobilefusionfx.ipad.css</style-sheet-name>
    </skin>
    <skin>
        <id>mobileFusionFx.iPod</id>
        <family>mobileFusionFx</family>
        <extends>mobileFusionFx.iOS</extends>
        <style-sheet-name>skins/mobilefusionfx.ipod.css</style-sheet-name>
    </skin>
    <!--  Skin Additions -->
    <skin-addition>
        <skin-id>mobileFusionFx.iPhone</skin-id>
        <style-sheet-name>skins/mystyles.iphone.addition1.css</style-sheet-name>
    </skin-addition>
    <skin-addition>
        <skin-id>mobileFusionFx.iPhone</skin-id>
        <style-sheet-name>skins/mystyles.iphone.addition2.css</style-sheet-name>
    </skin-addition>
    <skin-addition>
        <skin-id>mobileFusionFx.iOS</skin-id>
        <style-sheet-name>skins/mystyles.ios.addition2.css</style-sheet-name>
    </skin-addition>
</adfmf-skins>

5.12.1 How to Use FAR Content in an ADF Mobile Application

You make an application feature available to an ADF Mobile application by adding it to the consuming application's class path.

Before you begin:

Deploy the application feature as a Feature Archive file, as described in Section 16.5.2, "How to Deploy the Feature Archive Deployment Profile."

How to add application feature content to an ADF Mobile application:

1. Open the Resource Palette and then choose New File Systems Connection.

2. Complete the File Systems Connection dialog to create a file connection to the directory that contains the Feature Archive JAR file. For more information, refer to the Oracle JDeveloper Online help.

3. Right-click the Feature Archive file (which is noted as a JAR file) in the Resource Palette.

4. Choose Add to Application to add consuming application's classpath, as shown in Figure 5-49.

   Figure 5-49 Adding a FAR to an ADF Mobile Application

   
   

   Note:

   Choose Remove from Application to remove the feature archive JAR from the consuming application's classpath.

5.12.2 What Happens When You Add a Feature Archive JAR to a Classpath

After a FAR is added to the application's classpath:

• The contents of the FAR display in the Application Resources under the Libraries node, as shown in Figure 5-50.

  Figure 5-50 The Feature Archive File in the Application Resources of the Consuming Application

  
  

• Every application feature declared in the adfmf-feature.xml files included in the JARs becomes available to the consuming application, as illustrated by Figure 5-51 where the dropdown lists IDs of the available application features belonging to AcmeSales.jar (HCM, PROD, and Customers) as well as one called Portfolio that is defined in another Feature Archive that has been added to the application, StockTracker.jar. See also Section 5.5.1, "How to Designate the Content for a Mobile Application."

  Figure 5-51 Referencing the Application Features Defined in Various adfmf-feature.xml Files

  
  

  Tip:

  Manually adding the Feature Archive JAR to the application classpath also results in the application features displaying in the Insert Feature Reference dialog.

• The information in the connections.xml file located in the Feature Archive JAR is merged into the consuming application's connections.xml file. The Log window, shown in Figure 5-52, displays naming conflicts.

  Note:

  You must verify that the connections are valid in the consuming application.

  Figure 5-52 The Messages Log Window Showing Name Conflicts for Connections

  
  

5.12.3 What You May Need to Know About Enabling the Reuse of Feature Archive Resources

To ensure that the resources of a FAR can be used by an application, both the name of the FAR and its feature reference ID must be globally unique. Within the FAR itself, the DataControl.dcx file must be in a unique package directory. Rather than accepting the default names for these package directories, you should instead create a unique package hierarchy for the project. You should likewise use a similar package naming system for the feature reference IDs.