4 Defining a Mobile Application

4.1.1 Using the Overview Editor for maf-application.xml

The overview editor enables you to configure the maf-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.

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

The Application page of the overview editor, shown in Figure 4-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 maf-application.xml file by double-clicking the maf-application.xml file (located in the ADF META-INF node of the Application Resources panel, as shown in Figure 4-3).

Figure 4-3 Selecting the maf-application.xml File in the Applications Window.

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 4-4 shows the portion of the application page where you define the basic information.

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

   
   

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

   Note:

   MAF uses the value entered in this field as the name for the iOS archive (.ipa or .app) file that it creates when you deploy the application to an iOS-powered device or simulator. For more information, see Section 19.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 prefixes 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 document entitled "The AndroidManifest.xml File," which is 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 19.2.3, "How to Create an Android Deployment Profile" and Section 19.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 or a period. 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 4-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 4-5 Retrieving the Application Event Listener

   
   

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

   Note:

   The application lifecycle listener must remain within the application controller project (its default location).

   Example 4-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 a mobile application</adfmf:description>
      <adfmf:featureReference id="feature1"/>
   </adfmf:application>
   

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

4.5.1 How to Configure Application Navigation

The Navigation options of the Applications page, shown in Figure 4-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 4-6 The Navigation Options of the Application Page

Before you begin:

You must select the Application page of the maf-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 (instead of the springboard), by default, as shown in Figure 4-7.

   Figure 4-7 The Navigation Bar, Shown By Default

   
   

   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 4-8 illustrates this option, showing how the navigation bar illustrated in Figure 4-7 becomes hidden by the application feature content.

   Figure 4-8 Hiding the Navigation Bar

   
   

   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 MAF, which uses styles illustrated in Figure 4-1. The default springboard is implemented as a MAF AMX page. For more information, see Section 4.5.5, "What You May Need to Know About Custom Springboard Application Features with MAF AMX Content."

   • Custom—Select to use a customized springboard. You may, for example, create a custom springboard that arranges the embedded application features in a grid layout pattern, or includes a search function, or data, such as a list of common tasks (My Reports, or My Leads, for example). This application, which can be implemented either as an HTML page or as a MAF Mobile AMX page, is declared as an application feature in the maf-feature.xml file (which is located within a view controller project). For more information, see Section 4.9.1, "How to Define the Basic Information for an Application Feature."For information on enabling navigation within a customized springboard written in HTML, see Chapter B, "Local HTML and Application Container APIs."

     • Feature—Select the application feature used as a springboard, as shown in Figure 4-10. See the APIDemo sample application for an example of a custom springboard. For more information, see Appendix F, "Mobile Application Framework Sample Applications."

       Note:

       MAF's design time prompts you to set the Show on Navigation Bar and Show on Springboard options to false when you designate an application feature as a custom springboard. This ensures that the page behaves as a springboard rather than as an application feature that users launch from a navigation bar or from a springboard. For more information, see Section 4.6.1, "How to Designate the Content for a Mobile Application."

       Figure 4-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 4-10, that displays within an application feature. Figure 4-7, "The Navigation Bar, Shown By Default" shows this button within the context of an application feature. This option is only available for the Default or Custom options.

   Figure 4-10 The Springboard Toggle Button

   
   

To set the slideout 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, MAF does not provide the animation to enable this action). The springboard takes the entire display area.

   Note:

   The slideout 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 4.5.3, "What Happens When You Set the Animation for the Springboard."

4.5.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 4-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 4-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 4-5. The id attribute refers to an application feature defined in the maf-feature.xml file that is used as a custom springboard.

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

4.5.3 What Happens When You Set the Animation for the Springboard

Example 4-6 shows the navigation block of the maf-application.xml file, where the springboard is set to slideout 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 4-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.

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

The default HTML springboard page provided by MAF 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 references to the methods described in Chapter B, "Local HTML and Application Container APIs" that call the Apache Cordova 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.

  A springboard authored in HTML (or any custom HTML page) can leverage the Apache Cordova APIs by including a <script> tag that references the base.js library. You can determine the location of this library (or other JavaScript libraries) by first deploying a MAF application and then locating the www/js directory within platform-specific artifacts in the deploy directory. For an Android application, the www/js directory is located within the Android application package (.apk) file at:

  application workspace directory/deploy/deployment profile name/deployment profile name.apk/assets/www/js
  

  For iOS, this library is located at:

  application workspace directory/deploy/deployment profile name/temporary_xcode_project/www/js
  

  For more information, see Section B.1, "Using MAF APIs to Create a Custom HTML Springboard Application Feature."

• 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 maf-feature.xml file and referenced in the maf-application.xml file.

4.5.5 What You May Need to Know About Custom Springboard Application Features with MAF AMX Content

Like their HTML counterparts, springboards written using MAF AMX are application features that are referenced by the mobile application, as described in Section 4.6.1, "How to Designate the Content for a Mobile Application." Because a springboard is typically written as a single MAF AMX page rather than as a task flow, it uses the gotoFeature method, illustrated by the method expression in Example 4-7, to launch the embedded application features.

The default springboard (adfmf.default.springboard.jar, located in jdev_install\jdeveloper\jdev\extensions\oracle.maf\lib) is a MAF AMX page that is bundled in a Feature Archive (FAR) JAR file and deployed with other FARs that are included in the 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 maf-application.xml file. Selecting this option also adds this FAR to the application classpath. For more information, see Section 19.5, "Deploying Feature Archive Files (FARs)."

The default springboard (springboard.amx, illustrated in Example 4-7) is implemented as a MAF 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 4-11, a MAF AMX file defines the springboard using a List View whose List Items are the mobile application's embedded application features. These application features, once deployed, are displayed by their names and associated icons. The gotoFeature method of the AdfmfContainerUtilities API provides the page's navigation functions. For a description of using this method to display a specific application feature, see Section B.2.6, "gotoFeature." See also Section 6.3.15, "How to Use List View and List Item Components."

Figure 4-11 The Default Springboard

MAF 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 4-12, enables you to declaratively build a springboard page using its data collections of attributes that describe both the mobile application and its application features. For an example of a custom springboard page, see the APIDemo sample application. For more information on this application (and other samples that ship with MAF), see Appendix F, "Mobile Application Framework Sample Applications."

Figure 4-12 ApplicationFeatures Data Control

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

4.5.6 What You May Need to Know About the Runtime Springboard Behavior

If you chose the Show Springboard on Application Launch option and defined the slideout width to full size of the screen, then MAF loads the default application feature in the background at startup. When the mobile application hibernates, MAF hides the springboard.

4.6.1 How to Designate the Content for a Mobile Application

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

<adfmf:featureReference id="Prod"
                        showOnNavigationBar="true"
                        showOnSpringboard="true"/>
<adfmf:featureReference id="Customers"
                        showOnNavigationBar="true"
                        showOnSpringboard="true"/>
<adfmf:featureReference id="HCM"
                        showOnNavigationBar="true"
                        showOnSpringboard="true"/>
<adfmf:featureReference id="custom_springboard"
                        showOnNavigationBar="false"
                        showOnSpringboard="false"/>
<adfmf:navigation>
   <adfmf:springboard enabled="true">
      <adfmf:springboardFeatureReference id="custom_springboard"/>
   </adfmf:springboard>
</adfmf:navigation>

Example 4-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 4-14 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 4-1.

In addition, the page enables you to set the order in which the application features display on the navigation bar and springboard. At runtime, the width of the device screen can limit the number of application features that display on the navigation bar. Those that cannot be accommodated on the navigation bar display under a More tab, as shown in Figure 4-46. Users can reorder the application features within the More tab by using the Edit function.

Figure 4-13 The More Tab

Figure 4-14 Designating Application Features Using the Feature References Page

Before you begin:

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

To designate feature references:

1. Click the Feature References page of the maf-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 4-15. You can also add references to application features that are contained in an imported feature archive (FAR) file. For more information, see Section 4.13.2, "What Happens When You Add a FAR as a Library."

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

   Figure 4-15 Selecting the Content for the Mobile Application

   
   

4. If needed, use the up- and down-arrows shown in Figure 4-15 to arrange the display order of the feature references, or use the dropdown list in rows of the Id column, shown in Figure 4-16, to reorder the feature references. The top-most application feature is the default application feature. Depending on the security configuration for this application, MAF can enable users to login anonymously to view unsecured content, or it can prompt users to provide their authentication credentials. For more information, see Section 21.1, "About Mobile Application Framework Security."

   Note:

   The top-most ID in the Feature References table is the first application feature to display within the mobile application. See, for example, the Feature 1 application feature illustrated in Figure 4-7.

   Figure 4-16 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 4-17 shows selecting these options to prevent an application feature from displaying in the navigation bar.

   Tip:

   Set these options to false if the application uses a custom springboard or if the application feature will display as a sliding window. For more information, see Section 4.7.6, "Enabling Sliding Windows."

   Figure 4-17 Changing the Navigation Options

   
   

   The springboard and the navigation bar display by default (that is, these attributes are set to true). 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 B.2.11, "hideNavigationBar" and Section B.2.12, "showNavigationBar."

   Note:

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

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

A mobile application can contain many projects and can therefore also include multiple maf-feature.xml files. In the application configuration file, a feature reference relates to a feature described by a maf-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 maf-application.xml file must be the same as the id attribute defined for <adfmf:feature> element in maf-feature.xml. For example, <adfmf:featureReference id="customers"> in maf-application.xml is defined by <adfmf:feature id="customers"> in maf-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 4-18, 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 Monitoring Java Projects" chapter in Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

Figure 4-18 Auditing id Attributes

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

Figure 4-19 Finding Application Feature Declarations in the maf-feature.xml File

The feature IDs must be unique across an application. Because application features can be reused, use proper naming conventions to ensure that their feature IDs are unique.

4.7.1 Events in Mobile Applications

Lifecycle listener classes for mobile applications must implement the start, stop, activate, and deactivate methods of the LifeCycleListener interface, as illustrated in Example 4-11 to execute the application lifecycle events.

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

The AppListener class, shown in Example 4-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). For more information, see Section 4.7.2, "Timing for Mobile Application Events." See also the LifeCycleListener interface in Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

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...
    }
}

The application controller project of the LifeCycleEvents sample application, described in Appendix F, "Mobile Application Framework Sample Applications," contains a class (LifeCycleListenerImpl.java) that implements the LifeCycleListener interface.

4.7.2 Timing for Mobile Application Events

MAF calls application lifecycle methods at specific times during the mobile application's startup, shutdown, and hibernation. Table 4-3 describes when these methods are called and also notes their Objective-C counterparts.

4.7.3 Using the activate and deactivate Methods to Save Application State

Because checkpointing saves the application state, you can enable users to continue using the last page of a mobile application that was active before it began to hibernate by adding checkpoint entries to the activate and deactivate methods. The lifecycle listener reads the checkpoint entries added to the activate class and allows the processes to resume after the application has returned from hibernating; users can continue with application uninterrupted by not having to log in a second time. If the application is terminated during hibernation, you can enable the application to resume by specifying that checkpoint information be written to a database or to a device's cache directory as part of the deactivate method. The application resumes at the same page by reading this checkpoint information during activation.

4.7.4 About Application Feature Lifecycle Listener Classes

A mobile application feature lifecycle listener class, such as FeatureListenerPhoneList, illustrated in Example 4-14, must implement the activate and deactivate methods of the LifeCycleListener interface, as shown in Example 4-13.

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

Example 4-14 illustrates a class called FeatureListenerPhoneList that uses the activate and deactivate methods by implementing the LifeCycleListener to show and hide the application feature as described in Table 4-4. These methods hide the application feature when it hibernates, or display it when it returns from hibernating.

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...
    }
 
}

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

By implementing an application feature lifecycle listener class, you enable an application feature to automatically obtain any data changes to the applicationScope variable or to application feature-specific variables that changed when the application feature was deactivated. Table 4-4 describes when the activate and deactivate events are fired for an application feature. For more information, see Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

4.7.6 Enabling Sliding Windows

By implementing the oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities interface in the application lifecycle listener (ALCL), you can use an application feature as a sliding window, which displays concurrently with the other application features that display within the navigation bar or springboard. You can use a sliding window to display content that always present within the application, such as a global tool bar, or for temporary (pop-up) content, such as a help window. For information on displaying application features within the springboard or navigation bar, see Section 4.6.1, "How to Designate the Content for a Mobile Application." For information on using the methods of the AdfmfSlidingWindowUtilities API, refer to Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

4.9.1 How to Define the Basic Information for an Application Feature

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

Figure 4-20 The General Tab of the Application Feature

Before you begin:

If an application feature uses custom images for the navigation bar and springboard rather than the default ones provided by MAF, you must create these images to the specifications described by the Android Developers website (http://developer.android.com/design/style/iconography.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 4.10.2, "What You May Need to Know About Selecting External Resources."

In addition, you must open the maf-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 MAF Feature dialog, shown in Figure 4-18, 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 maf-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 maf-application.xml. The table in the Feature References page, shown in Figure 4-14, includes the feature reference after you complete the dialog. See also Section 4.6.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."

     Figure 4-21 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 4.7, "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 Applications window into the file location field. This is an optional value.

4.10.1 How to Define the Application Content

The Content tab of the overview editor, shown in Figure 4-22, provides you with dropdown lists and fields for defining the target content-related elements and attributes shown in Example 4-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 4-22, for example, you must specify the location of the MAF AMX page or task flow for the application features that you implement as MAF AMX content. 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 mobile application itself), or select a JavaScript file that controls the actions of the MAF AMX components.

Figure 4-22 Defining the Implementation of the Application Feature

Before you begin:

Each content type has its own prerequisites, as follows:

• MAF AMX—The default content type for application features, which includes both individual MAF AMX pages and task flows. You can build the MAF AMX content declaratively using a set of mobile-specific user interface components, ADF data bindings, and data controls that integrate device services, such as a camera, and data visualization tools, such as charts, graphs, and thematic maps. For information on building a MAF AMX page, see Chapter 5, "Creating MAF AMX Pages."

  An application feature implemented as MAF AMX requires an existing view (that is, a single MAF AMX page) or a bounded or unbounded task flow. Including a JavaScript file provides rendering logic to the MAF AMX components or overrides the existing rendering logic. Including a style sheet (CSS) with selectors that specify a custom look and feel for the application feature, one that overrides the styles defined at the mobile application level that are used by default for application features. In other words, you ensure that the entire application feature has its own look and feel.

  If you create the MAF 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 Applications window and then by choosing New. Alternatively, you can create a MAF AMX page using the context menu shown in Figure 4-23 that appears when you right-click the view controller project in the Applications window and then choose New.

  Note:

  When manually editing references to task flows, MAF AMX pages, CSS and JavaScript files in the maf-feature.xml file, keep in mind that file systems used on devices may enforce case-sensitivity and may not allow special characters. To ensure that these files can be referenced, check the mobile device specification.

  Figure 4-23 Context Menu for Creating a MAF Page

  
  

• Remote URL—A reference to a web application. You can enhance an existing web application for mobile usage and extend device services. Remote content can complement both MAF AMX and local HTML content by providing a local data cache and a full set of server-side data and functionality. The remote URL implementation requires a valid web address as well as a hosted mobile application. For more information, see Chapter 13, "Implementing Application Feature Content Using Remote URLs."

• Local HTML—Reference a HTML page that is packaged within your mobile application. Such HTML pages can reference JavaScript, as demonstrated by the HelloWorld sample application described in Appendix F, "Mobile Application Framework Sample Applications." Consider using this content type to implement application functionality through usage of the Cordova JavaScript APIs if the MAF is not best suited to implementing your application's functionality. For more information about JavaScript APIs and the MAF, see Appendix B, "Local HTML and Application Container APIs."

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

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

2. Click Content.

3. Click Add to create a new row in the Content table.

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 4-24, that represents address of the web pages on the server (and the location of the launch page).

     Figure 4-24 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 4-25. 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 4-25 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 4-26, 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 4-26 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 15, "Setting Constraints on Application Features."

   • Select navigation bar and springboard images.

To designate the application feature content as MAF 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 MAF AMX from the dropdown list in the Type column as shown in Figure 4-27.

   Figure 4-27 Selecting MAF AMX as the Content Type

   
   

4. In the File field, click Browse, and choose either MAF AMX Page or Task Flow, as shown in Figure 4-28, to navigate to, and retrieve, the location of the MAF AMX page or the bounded task flow. Alternatively, you can drag and drop a MAF AMX page from the Applications window into the file location field.

   Figure 4-28 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 MAF AMX or Task Flow as shown in Figure 4-29.

      Figure 4-29 Adding a MAF AMX Page or Task Flow from the File Field

      
      

   2. Complete the create dialogs, such as the Create MAF AMX Page dialog shown in Figure 4-30.

      Figure 4-30 The Create MAF AMX Page Dialog

      
      

   3. Build the MAF 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 4.12.9, "Overriding the Default Skin Styles."

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

   • Enter the constraints, as described in Chapter 15, "Setting Constraints on Application Features."

   • 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 4.10.2, "What You May Need to Know About Selecting External Resources."

4.10.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 the view controller project.

• 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 4.9.1, "How to Define the Basic Information for an 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 4.10, "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 4.10, "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 4.10, "Defining the Content Types for an Application Feature" and Section 21.5.3.2, "The 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"/> or <adfmf:include type="StyleSheet" file="resources/css/stylesheet.css" id="i3"/>). See also Section 4.12, "Skinning Mobile Applications."

MAF 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, MAF includes an audit rule called File not in public_html directory. You can access the MAF audit profiles, shown in Figure 4-31, from the Audit Profiles node in Preferences by choosing Tools > Preferences > Audit > Profiles.

Figure 4-31 MAF Audit Profiles

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

Figure 4-32 The External Resource Warning

4.11.1 Working with Resource Bundles

MAF uses only XLIFF (XML Localization Interchange File Format) files for localization, meaning that JDeveloper produces resource bundle .xlf files to store the strings. For information on XLFF, see

http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html.

4.11.1.1 How to Set Resource Bundle Options

You can create resource bundles for the view controller and application controller projects using Resource Bundle Settings page for projects, shown in Figure 4-33.

Figure 4-33 Project Properties Resource Bundle Page

To set the resource bundle options for a project:

1. In the Applications window, double-click the project.

2. In the Project Properties dialog, select Resource Bundle.

3. To automatically generate a default resource file, select Automatically Synchronize Bundle.

4. Select one of the following resource bundle file options:

   • One Bundle Per Project —Configured in a file named <ProjectName>.xlf. For more information, see Section 4.11.1.2, "What Happens When You Select Resource Bundle Options."

   • One Bundle Per File— Creates a new bundle each time you put a resource into file (maf-feature.xml, maf-application.xml or a MAF AMX page). As a result, each file has its own bundle. This option limits the number of resource bundles to one per file; if you select this option, JDeveloper prevents you from creating a second bundle.

5. Click OK.

   Note:

   Xliff Resource Bundle is the only resource bundle format used by MAF. For more information on this page, see the online help for Oracle JDeveloper.

4.11.1.4 What Happens When You Add a Resource Bundle

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

Figure 4-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="#{acmeBundle.Acme_Sales}" based on the ACME_SALES value entered for the Key in the Select Text 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 maf-application.xml and maf-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.

<amx:facet name="header">
      <amx:outputText value="#{viewcontrollerBundle.LES_PRODUITS}"
                      id="ot1"
                      rendered="true"/>
    </amx:facet>

<amx:loadBundle basename="mycomp.mobile.ViewControllerBundle"
                 var="viewcontrollerBundle" 
                 id="lb1"/>

4.11.1.7 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 icon="/feature1/test.png". Instead, you must edit the ViewControllerBundle.xlf file manually by adding a <trans-unit> element for the image path, as illustrated in Example 4-19.

Example 4-19 Defining the Resource for an <amx:image> Component

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

Note:

The image location defined in the <source> element in Example 4-19 is relative to the location of the application feature file in ViewController\public_html. Alternatively, you can enter the name of the image file, such as <source>test.png</source>. See also Section 4.10.2, "What You May Need to Know About Selecting External Resources."

After you update ViewControllerBundle.xlf, use the Expression Builder to define an EL expression for the source attribute for the icon attribute, as shown in Figure 4-39.

Figure 4-39 Creating the EL Expression for a Localized Icon Image

<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>

<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-featureBundle" 
                          var="mobileBundle"/>
        <adfmf:loadBundle basename="mobile.adfmf-stringsBundle" 
                          var="strings"/>

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

4.12.1 About the maf-config.xml File

After you create a mobile application, JDeveloper populates the maf-config.xml file to the mobile application's META-INF node. The file itself is populated with the base MAF skin family, mobileAlta, illustrated in Example 4-23.

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-config xmlns="http://xmlns.oracle.com/adf/mf/config">
  <skin-family>mobileAlta</skin-family>
  <skin-version>v1.1</skin-version>
  <generic-type>
    <conversion>
      <validated>false</validated>
    </conversion>
  </generic-type>
</adfmf-config>

MAF applies skins as a hierarchy, with device-specific skins occupying the top tier, followed by platform-specific skins, and then the base skin, mobileAlta. In terms of MAF's mobileAlta skin family, this hierarchy is expressed as follows:

1. mobileAlta.<DeviceModel> (for example, mobileAlta.iPhone5,3)

2. mobileAlta.iOS or mobileAlta.Android

3. mobileAlta

MAF gives precedence to selectors defined at the device-specific level of this hierarchy. In other words, MAF overwrites a selector defined in mobileAlta.iOS with the mobileAlta.iPhone definition for the same selector. The <extends> element, described in Section 4.12.3, "About the maf-skins.xml File," defines this hierarchy for the MAF runtime. For more information on how skins are applied at various levels, see Section 4.12.10, "What You May Need to Know About Skinning."

4.12.2 What You May Need to Know About MAF Styles

The underlying skinning styles for the base skin family, mobileAlta, are defined in the amx.css, amx-mobileAlta-1.0.css, and amx-v1.1.css files. These files, which define the selectors for MAF AMX pages, reside in the www\css directory. To access this directory, you must first deploy a mobile application to a simulator or device and then traverse to the deploy directory (for example, C:\JDeveloper\mywork\application name\deploy). The www\css directory resides within the platform-specific artifacts generated by the deployment. For iOS deployments, the directory is located within the temporary_xcode_project directory. For Android deployments, this directory is located in the assets directory of the Android application package (.apk) file.

4.12.3 About the maf-skins.xml File

The maf-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 create a new skin by extending an existing skin. The <skin-addition> element adds a style sheet to an existing skin.

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

<skin>
  <id>mySkin-v1</id>
  <family>mySkin</family>
  <extends>mobileAlta-v1.1</extends>
  <style-sheet-name>styles/myskin.css</style-sheet-name>
  <version>
    <name>v1</name>
  </version>     
</skin>

Table 4-10 lists elements that you can use to define the <skin-addition> element in a MAF CSS when you integrate a style sheet into an existing skin.

Example 4-24 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-v1.1.iOS</skin-id>
    <style-sheet-name>skins/mystyles.iphone.addition1.css</style-sheet-name>
  </skin-addition>
</adfmf-skins>

You can use the <skin-id> and <style-sheet-name> elements to render to a particular iOS or Android device, or alternatively, you can define these elements to handle the styling for all of the devices of a platform. Table 4-11 provides examples of using these elements to target all of the devices belonging to the iOS platform, as well as specific iOS device types (tablets, phones, and simulators).

<skin-addition>
   <skin-id>mobileAlta-v1.1.iPhone5,1</skin-id>
   <style-sheet-name>iPhoneStylesheet.css</style-sheet-name>
</skin-addition>

<skin-addition>
   <skin-id>mobileAlta-v1.1.iPad4,2</skin-id>
   <style-sheet-name>iPadStylesheet.css</style-sheet-name>
</skin-addition>

<skin-addition>
   <skin-id>mobileAlta-v1.1.iPhone Simulator x86_64</skin-id>
   <style-sheet-name>iPhoneSimStylesheet.css</style-sheet-name>
</skin-addition>

<skin-addition>
   <skin-id>mobileAlta-v1.1.iOS</skin-id>
   <style-sheet-name>iOSSimStylesheet.css</style-sheet-name>
</skin-addition>

4.12.4 How to Add a Custom Skin to an Application

To add a custom skin to your application, create a CSS file within JDeveloper, which places the CSS in a project's source file for deployment with the application.

To add a custom skin to an application:

1. In the Applications window, right-click the ApplicationController project and choose New > CSS File.

2. In the Create Cascading Style Sheet dialog, specify a name and directory for the CSS file.

3. Click OK.

4.12.5 How to Specify a Skin for an Application to Use

You configure values in the maf-config.xml file that determine what skin the application uses.

To specify a skin for an application to use:

1. In the Applications window, double-click the maf-config.xml file. By default, this is in the Application Resources pane under the Descriptors and ADF META-INF node.

2. In the maf-config.xml file, specify the value of the <skin-family> element for the skin you want to use and, optionally, the <skin-version> element.

   Example 4-25 shows the configuration required to make a mobile application use the mobileAlta.v1.1 skin.

   Example 4-25 Configuration to Specify a Skin for an Application

   <adfmf-config xmlns="http://xmlns.oracle.com/adf/mf/config">
     <skin-family>mobileAlta</skin-family>
     <skin-version>v1.1</skin-version>
   </adfmf-config>
   

To add a new style sheet to a skin

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

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

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

   • Retrieve the location of the CSS file.

   Figure 4-41 The Insert skin-addition Dialog

   
   

3. Click OK.

4.12.6 How to Register a Custom Skin

You register a custom skin by adding the property values to the maf-skins.xml file that identify the custom skin to your application.

To register a custom skin:

1. In the Applications window, expand ApplicationController > Application Sources > META-INF and double-click maf-skins.xml.

2. In the Structure window, right-click the adfmf-skins node and choose Insert Inside adfmf-skins > skin.

3. In the Insert skin dialog, complete the fields as follows:

   • family—Enter a value for the family name of your skin.

     You can enter a new name or specify an existing family name. If you specify an existing family name, you need to version skins, as described in Section 4.12.7, "How to Version MAF Skins," to distinguish between skins that have the same value for family.

     The value you enter is set as the value for a <family> element in the maf-skins.xml where you register the skin that you create. At runtime, the <skin-family> element in the application's maf-config.xml uses this value to identify the skin that an application uses.

   • id—Enter an ID for the skin that uses one of the following naming formats: skinFamily-version or skinFamily-version.platform. For example, mySkinFamily-v1.1.android.

   • extends—Enter the name of the parent skin that you want to extend. For example, if you want your custom skin to extend the mobileAlta-v1.1 skin, enter mobileAlta-v1.1.

   • style-sheet-name—Enter or select the name of the style sheet.

4. Click OK.

4.12.7 How to Version MAF Skins

You can specify version numbers for your skins in the maf-skins.xml file using the <version> element. Use this optional capability if you want to distinguish between skins that have the same value for the <family> element in the maf-skins.xml file. This capability is useful in scenarios where you want to create a new version of an existing skin in order to change some existing behavior. Note that when you configure an application to use a particular skin, you do so by specifying values in the maf-config.xml file, as described in section Section 4.12.5, "How to Specify a Skin for an Application to Use."

You specify a version for your skin by entering a value for the <version> element in the maf-skins.xml file.

To version a MAF skin:

1. In the Applications window, double-click the maf-skins.xml file. By default, this is in the META-INF node of the application controller project.

2. In the Structure window, right-click the skin node for the skin that you want to version and choose Insert inside skin > version.

3. In the Insert version dialog, select true from the default list if you want your application to use this version of the skin when no value is specified in the <skin-version> element of the maf-config.xml file, as described in Section 4.12.5, "How to Specify a Skin for an Application to Use."

4. Enter a value in the name field. For example, enter v1 if this is the first version of the skin.

5. Click OK.

4.12.8 What Happens When You Version Skins

The version information that you configure for skins takes precedence over platform and device values when an application applies a skin at runtime. At runtime, a mobile application applies a device-specific skin before it applies a platform-specific skin. If skin version information is specified, the application first searches for a skin that matches the specified skin version value. If the application finds a skin that matches the skin version and device values, it applies this skin. If the application cannot find a skin with the specified skin version in the device-specific skins, it searches for a skin with the specified version in the platform-specific skins. If it does not find a skin that matches the specified version in the available platform-specific skins, it searches the base skins.

Example 4-26 shows an example maf-skins.xml that references three skins (customFamily-v1.iphone5,3, customFamily-v2.iPhone and customFamily-v3.iPhone). Each of these skins have the same value for the <family> element (customFamily). The values for the child elements of the <version> elements distinguish between each of these skins.

At runtime, an application that specifies customFamily as the value for the <skin-family> element in the application's maf-config.xml file uses customFamily-v1.iphone5,3 because this skin is configured as the default skin in the maf-skins.xml file (<default>true</default>). You can override this behavior by specifying a value for the <skin-version> element in the maf-config.xml file, as described in Section 4.12.5, "How to Specify a Skin for an Application to Use." For example, if you specify v2 as a value for the <skin-version> element in the maf-config.xml file, the application uses customFamily-v2.iPhone instead of customFamily-v1.iphone5,3 that is defined as the default in the maf-skins.xml file.

If you do not specify the skin version to pick (using the <skin-version> element in the maf-config.xml file), then the application uses the skin that is defined as the default using the <default>true</default> element in the maf-skins.xml file. If you do not specify a default skin, the application uses the last skin defined in the maf-skins.xml file. In Example 4-26, the last skin to be defined is customFamily-v3.iPhone.

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-skins xmlns="http://xmlns.oracle.com/adf/mf/skin">
  <skin id="s1">
    <family>customFamily</family>
    <id>customFamily-v1.iphone5,3</id>
    <extends>customFamily-v1.iOS</extends>
    <style-sheet-name>iphone.css</style-sheet-name>
    <version>
      <default>true</default>
      <name>v1</name>
    </version>
  </skin>
  <skin id="s2">
    <family>customFamily</family>
    <id>customFamily-v2.iPhone</id>
    <extends>customFamily-v1.iOS</extends>
    <style-sheet-name>iphone-v2.css</style-sheet-name>
    <version>
      <name>v2</name>
    </version>
  </skin>
  <skin id="s3">
    <family>customFamily</family>
    <id>customFamily-v3.iPhone</id>
    <extends>customFamily-v1.iOS</extends>
    <style-sheet-name>iphone-v3.css</style-sheet-name>
    <version>
      <name>v3</name>
    </version>
  </skin>
</adfmf-skins>

4.12.9 Overriding the Default Skin Styles

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

4.12.9.1 How to Apply New Style Classes to an Application Feature

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

Figure 4-42 The Includes Table

Before you begin:

Create a MAF task flow as described in Section 5.2, "Creating Task Flows." Create or add a Cascading Style Sheet (CSS) file for the skin. You can create the CSS file by selecting the view controller project and then choosing New > CSS File. Alternatively, you can package the CSS file in a JAR file as follows:

1. From the main menu, choose Application > Project Properties.

2. In the Project Properties dialog, select the Libraries and Classpath page and click Add JAR/Directory.

3. In the Add Archive or Directory dialog, navigate to the JAR file that contains the ADF skin you want to import and click Select.

   The JAR file appears in the Classpath Entries list.

4. Click OK.

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 4-43.

   Figure 4-43 Selecting the StyleSheet Option

   
   

3. In the File column, click Edit, as shown in Figure 4-43.

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

   Note:

   The .css file must reside within the view controller project; you cannot include a .css file that resides in the application controller project.

   Figure 4-44 Selecting the CSS for the Application Feature

   
   

4.12.9.2 What Happens When You Apply a Skin to an Application Feature

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

Figure 4-45 The Feature Content Dropdown Menu

4.12.10 What You May Need to Know About Skinning

The CSS files defined in the maf-skins.xml file, illustrated in Example 4-27, 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. 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.maf/Samples

For example, at the iOS level, the stylesheet (mobileAlta in Example 4-27) is applied to both an iPhone or an iPad. For device-specific styling, 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.

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

4.12.11 What You May Need to Know About Migrating Skinning Styles

Applications created by MAF derive their styles from the mobileFusionFX skin family. Like the mobileAlta skin family, such device- and platform-specific styles as mobileFusionFx.iPhone and mobileFusionFx.iOS are applied before the base skin itself, mobileFusionFx. To ensure that an application has the look and feel of the mobileAlta skin replace <skin-family>mobileFusionFx</skin-family> in the maf-config.xml file as follows:

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

4.12.12 Enabling Dynamic Skin Selection at Runtime

You can configure your application to enable end users select an alternative skin at runtime. You might configure this functionality when you want end users to render the application using a skin that is more suitable for their needs.

Figure 4-46 shows how you might implement this functionality by displaying buttons to allow end users to change the skin the application uses at runtime. Configure the buttons on the page to set a scope value that can later be evaluated by the skin-family property in the application's maf-config.xml file.

Figure 4-46 Changing an Application's Skin at Runtime (on iOS)

4.13.1 How to Use FAR Content in a MAF Application

You make an application feature available to a 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 19.5.2, "How to Deploy the Feature Archive Deployment Profile."

How to add application feature content to a mobile application as a library:

1. Open the Resources window, choose New, then IDE Connections, and then choose File System.

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 Resources window.

4. Choose Add to Application As and then choose Library to add the consuming application's classpath, as shown in Figure 4-47.

   Figure 4-47 Adding a FAR to a Mobile Application as a Library

   
   

   Tip:

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

How to add a FAR as a view controller project:

1. Open the Resources window, choose New, then IDE Connections, and then choose File System.

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 Resources window.

4. Choose Add to Application As and then choose ViewController Project, as shown in Figure 4-48.

   Figure 4-48 Adding a FAR to a Mobile Application as a View Controller Project

   
   

4.13.2 What Happens When You Add a FAR as a Library

After you add a FAR as a library (or manually to the application's classpath):

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

  Figure 4-49 The FAR JAR File in the Application Resources of the Consuming Application

  
  

• Every application feature declared in the maf-feature.xml files included in the JARs becomes available to the consuming application, as illustrated by Figure 4-50 where the dropdown lists IDs of the available application features belonging to AcmeFAR.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, StockTrackerFAR.jar. See also Section 4.6.1, "How to Designate the Content for a Mobile Application."

  Figure 4-50 Referencing the Application Features Defined in Various maf-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.

  Alternatively, you can add or remove an application feature from the Resources window as follows:

  1. Expand the feature archive JAR in the Resources window.

  2. From the MAF Features folder, right-click an application feature.

  3. Choose Add Feature Reference to maf-application.xml, as shown in Figure 4-51, or Remove Feature Reference from maf-application.xml, shown in Figure 4-52. Figure 4-51 illustrates adding an application feature called customers from acmeFAR.jar, an imported FAR.

     Figure 4-51 Adding a Feature Reference

     
     

  Figure 4-52 illustrates removing the customers feature reference (initially added from the imported FAR, acmeFAR.jar) from the maf-application.xml file.

  Figure 4-52 Removing a Feature Reference

  
  

• 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 4-53, displays naming conflicts.

  Note:

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

  Figure 4-53 The Messages Log Window Showing Name Conflicts for Connections

  
  

4.13.3 What Happens When You Add a FAR as a View Controller Project

When you add a FAR as a view controller project:

• MAF generates a view controller project that bears the same name as the imported FAR. Figure 4-54 illustrates how MAF creates a view controller project (a .jpr file) for an imported FAR file called StockTracker (which is illustrated as StockTrackerFAR.jar in Figure 4-48). This view controller project contains the default structure and metadata files of a MAF view controller project, as described in Section 3.2.2.3, "About the View Controller Project Resources." In particular, the FAR view controller project includes the maf-feature.xml file. If the MAF application contains other view controller projects, you must ensure that none of these projects include application features with the same ID. See also Section 4.13.4, "What You May Need to Know About Enabling the Reuse of Feature Archive Resources."

  Figure 4-54 The Imported FAR as a View Controller Project within a Mobile Application

  
  

• As with a FAR imported as a library, the information in the connections.xml file located in the Feature Archive JAR is merged into the consuming application's connections.xml file. MAF will create a connections.xml file if one does not already exist in the target application. Likewise, the sync-config.xml file is merged into the consuming applications's sync-config.xml file.

• MAF makes any .class and JAR files included in the FAR available as a library to the view controller project by copying them into its lib directory (such as C:\jdeveloper\mywork\application\FAR view controller project\lib). MAF compiles these files into a file called classesFromFar.jar.

• Unlike a FAR imported as a library, you can customize the files of a view controller project.

  Note:

  Because the original resource bundles included in FAR might not be usable in the generated view controller project, you must create new resources bundles within the project as described in Section 4.14.6.1, "How to Enable Customizations in Resource Bundles."

• Like a FAR imported as a library, every application feature declared in the FAR's maf-feature.xml file becomes available to the consuming application.

4.13.4 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 IDs must be globally unique; ensure there are no duplicate feature reference IDs in the maf-application.xml file. 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.

4.13.5 What You May Need to Know About Using a FAR to Update the sync-config.xml File

The sync-config.xml file enables the mobile application to not only cache the data retrieved from server-side resources accessed through various types of web services (SOAP, REST-XML, or REST with JSON payloads) to the embedded SQLite database, but also enables the application to update this data within the cache and to the server-side resource.

The sync-config.xml file is included in the Feature Archive file when the view controller project is deployed as a FAR. Like the connections.xml file, MAF merges the contents of the sync-config.xml file in the FAR (jar-sync-config.xml) with those of the consuming application's sync-config.xml file after you add the FAR to the application. Because the sync-config.xml file describes the web service endpoints used by the mobile application, you can update the endpoints for all of the web services used by the application features that comprise a mobile application by adding a FAR as described in Section 4.13.3, "What Happens When You Add a FAR as a View Controller Project."

After you add the FAR to the application, MAF logs messages that prompt you to verify and, if needed, modify the application's sync-config.xml and connections.xml files. As illustrated in Figure 4-55, these messages reflect the state of the sync-config.xml file in the consuming application.

Figure 4-55 The Messages Log

If the consuming application lacks the sync-config.xml file, then MAF adds the file to the application and writes a message similar to the following:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logNoSyncConfigInAppUsingFar
WARNING: The application does not contain a synchronization file, "sync-config.xml". Creating one 
containing the synchronization configuration in the Feaure Archive.

MAF writes a log message similar to the following that requests that you verify (or create) a connection if the sync-config.xml file's <ServerGroup> elements do not have corresponding <Reference> elements defined in the consuming application's connections.xml file:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logAddedServerGroups
WARNING: The following server groups were added sync-config.xml by the Add to Application 
operation:
{
  ServerGroup1 - there is no existing application connection defined for this server group.
Please create the connection.

  ServerGroup2 - verify its configuration.
}

If the <ServerGroup> definitions in the consuming application's config-sync.xml file duplicate those of the counterpart config-sync.xml file included in the FAR, then MAF writes the following SEVERE-level message to the log:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logDuplicateServerGroups
SEVERE: Cannot merge the server groups from the Feature Archive because the following definitions 
already exist:
ServerGroup1
ServerGroup2

4.14.1 How to Create a Customization Layer

Customizations can be global (that is, available to an entire instance of JDeveloper), or application-specific. JDeveloper stores global customizations in the CustomizationLayerValues.xml file located at jdev_install/jdeveloper/jdev/CustomizationLayerValues.xml. By default, this file is seeded with layer values called site1 and site2. They are defined using the <cust-layer-value> element as follows:

<cust-layers xmlns="http://xmlns.oracle.com/mds/dt">
   <cust-layer id-prefix="s" name="site"> 
      ...
         <cust-layer-value id-prefix="1" display-name="Site One" value="site1"/>
         <cust-layer-value id-prefix="2" display-name="Site Two" value="site2"/>
      ...
   <cust-layer-value display-name="Site" value="site"/>
</cust-layer>

Any layer values defined in this file can be overridden at runtime by those defined in an application-specific CustomizationLayerValues.xml file.

To create an application-specific CustomizationLayerValues.xml file:

1. In the Applications window, expand the Application Resources folder.

2. Expand the ADF-META INF folder and open the adf-config.xml file.

3. In the MDS page of the overview editor, click Configure Design Time Customization Values.

4. Open the CustomizationLayerValues.xml file and update the seeded layer values (Site One and Site Two) as needed. For example:

   <cust-layers xmlns="http://xmlns.oracle.com/mds/dt">
     <cust-layer name="site" id-prefix="s">
       <!-- Generated id-prefix would be "s1" and "s2" for values 
        site1" and "site2"-->
       <cust-layer-value value="headquarters" display-name="Headquarters"
        id-prefix="1"/>
       <cust-layer-value value="remoteoffices" display-name="Remote Offices"
        id-prefix="2"/>
   ...
   

4.14.2 How to Create a Customization Class

Do not create this file in the mobile application that you plan to customize. Instead, create a separate Java application for the customization class. After you complete the Java class, you import it into the mobile application that you plan to customize.

To create a customization class:

1. Create a Java application.

2. Click File, New, and then Project.

3. In the New Gallery, choose Java Application Project. Complete the wizard.

4. In the Applications window, right click the Java application project and then choose Project Properties.

5. In the Project Properties dialog, select Libraries and Classpath, and then click Add Library.

6. In the Add Library dialog, select MDS Runtime and then click OK. Click OK to close the Project Properties dialog.

7. In the Applications window, right-click the Java application project and then choose New and then Java Class.

8. In the Create Java Class dialog, enter the class' name and package.

9. In the Extends field, browse the class hierarchy and retrieve oracle.mds.cust.CustomizationClass, as shown in Figure 4-57. Click OK.

   Note:

   Implement Abstract Methods (the default setting) must be selected in the Create Java Class dialog.

   Figure 4-57 Creating the Customization Class

   
   

10. Update the stub file. Example 4-30 illustrates a customization class.

    Example 4-30 Customization Class

    package mobile;
     
    import java.io.IOException;
    import java.io.InputStream;
    import java.util.Properties;
    import oracle.mds.core.MetadataObject;
    import oracle.mds.core.RestrictedSession;
    import oracle.mds.cust.CacheHint;
    import oracle.mds.cust.CustomizationClass;
     
    public class SiteCC extends CustomizationClass {
        private static final String DEFAULT_LAYER_NAME = "site";
        private String mLayerName = DEFAULT_LAYER_NAME;
        public SiteCC() {
           
        }
     
        public SiteCC (String layerName) {
            mLayerName = layerName;
        }
        public CacheHint getCacheHint() {
                   return CacheHint.ALL_USERS;
        }
     
        public String getName() {
            
            return mLayerName;
        }
     
           public String[] getValue(RestrictedSession restrictedSession, MetadataObject metadataObject)
    {
            // This needs to return te site value at runtime.
            //For now, it's always null
               Properties properties = new Properties();
               String configuredValue = null;
               Class clazz = SiteCC.class;
               InputStream is  = clazz.getResourceAsStream("/customization.properties");
    
               if (is != null){
                   try {
                       properties.load(is);
                       String propValue = properties.getProperty(mLayerName);
                       if (propValue != null){
                           configuredValue = propValue;
                       }
                   } catch (IOException e) {
                       e.printStackTrace();
                   }
               }
               
               return new String[] {configuredValue};
        }
    }
    

11. Rebuild the Java application project.

4.14.3 How to Enable the Design Time to Access the Customization Class

You must first package the customization class as a JAR file and then register the class with the mobile application. To package the customization class and any related artifacts into a JAR file, you must create a deployment profile using the Create Deployment Profile wizard. For more information, see Section 3.2.2.4, "About Automatically Generated Deployment Profiles."

To add customization classes into a JAR:

1. In the Applications window, right-click the Java application project and choose New > From Gallery.

2. In the New Gallery, expand General, select Deployment Profiles and then JAR File, and click OK.

   Tip:

   Click the All Features tab if the Deployment Profiles node does not appear in the Categories tree.

3. In the Create Deployment Profile -- JAR File dialog, enter a name for the project deployment profile (for example, SiteCC in Figure 4-58) and then click OK.

   Figure 4-58 Creating the Deployment Profile for the Customization Class

   
   

4. In the Edit JAR Deployment Profile Properties dialog, select JAR Options.

5. If needed, enter a location for the JAR file. Otherwise, accept the default location.

6. Expand Files Groups > Project Output > Filters to list the files that can be selected to be included in the JAR.

7. In Filters page, in the Files tab, select the customization classes you want to add to the JAR file, as illustrated in Figure 4-59.

   Figure 4-59 Including the Customization Class in the JAR File

   
   

8. Click OK to exit the Edit JAR Deployment Profile Properties dialog.

9. Click OK again to exit the Project Properties dialog.

10. In the Applications window, right-click the Java application project and then choose the deployment profile. In the Deployment Action page, illustrated in Figure 4-60, Deploy to JAR is selected by default. Click Next.

    Figure 4-60 Deploying the Customization Class to a JAR File

    
    

11. Review the confirmation for the output location of the JAR file. Click OK.

    Figure 4-61 Summary Page (Showing the Output Location for the JAR File)

    
    

    The log file window, shown in Figure 4-62, displays the status of the deployment.

    Figure 4-62 Deployment Log

    
    

To register the customization class with the mobile application:

1. Open the mobile application.

2. Choose Application and then Application Properties.

3. Choose Libraries and Classpath.

4. Click Add JAR/Directory.

5. In the Add Archive or Directory dialog, navigate to the JAR file that contains the customization classes, and click Open.

6. Click OK.

7. In the overview editor for the MDS page of the adf-config.xml file, add the customization class, as illustrated in Figure 4-63.

   Figure 4-63 Adding the Customization Class

   
   

4.14.4 What You May Need to Know About Web Service Data Controls and Customized Application Deployments

Because web service Java Bean Definition (JDB) files cannot be created by a customization deployment, you must perform a non-customization deployment to create these files before performing a customization deployment, as follows:

1. Launch the application in the Studio Developer role.

2. Choose Build and then Clean All to remove any web service JDB files that may have become obsolete since the previous deployment.

3. Select from among the deployment options (accessed by choosing Application, then Deploy, and then by selecting the deployment profile). For more information, see Chapter 19, "Deploying Mobile Applications."

4. Launch the application in the Customization Developer role.

5. Select the same deployment profile chosen in Step 3 to enable the customization deployment to access the JBD files created by the non-customization deployment.

4.14.5 What Happens When You Customize a Mobile Application

When you implement customizations for a mobile application, JDeveloper creates a metadata file for these customizations and a subpackage for storing them. The metadata file contains the customizations for the customized object, which are applied over the base metadata at runtime. JDeveloper gives the new metadata file the same name as the base file for the object, but includes an additional .xml extension, as illustrated by maf-feature.xml.xml in Figure 4-64.

Figure 4-64 maf-feature.xml Metadata File

4.14.6 Enabling Customizations in Resource Bundles in Mobile Applications

To implement customization for resource keys, you must create additional resource bundle files; you cannot use the base resource bundle file.

4.14.7 Upgrading a Mobile Application with Customizations

Customizations are upgrade-safe because they are saved separately from the base applications. Because customizations retain changes, they enable you to upgrade an application by applying these changes to newer versions of the application. The MAF Application Archive (.maa) file provides the mechanism for upgrading mobile applications. When you create an application from an .maa file, you can upgrade the application using an updated version of the .maa file.

4.14.7.1 How to Upgrade a Mobile Application

Using the Upgrade Mobile Application from Archive wizard, you can upgrade an application to a higher version while retaining the customizations made prior to the upgrade.

Before you begin:

You may want to familiarize yourself with the MAF Application Archive (.maa) file. For more information, see Section 19.6, "Creating a Mobile Application Archive File" and Section 19.7, "Creating Unsigned Deployment Packages."

Ensure that the application that is packaged into the .maa file and used for the upgrade has the same application ID as the application to which it will be applied. It must also have a higher version number than the application targeted for the upgrade.

To upgrade a mobile application:

1. Create a mobile application from an .maa file.

2. Apply customization to the mobile application, as described in Section 4.14, "Customizing MAF Files Using Oracle Metadata Services" and Section 4.14.6, "Enabling Customizations in Resource Bundles in Mobile Applications."

3. Click Application and then choose Select Mobile Application from Archive.

4. Browse to and select the .maa file. The wizard discontinues the upgrade if the application packaged in the .maa has the same (or lower) version number than the current application, or a different application ID.

   Figure 4-68 Selecting the .maa File

   
   

5. Review the Summary page for files that require a manual merge. As noted in Figure 4-69, MAF saves the initial version (Version 1) of the application in the Temp directory. The Summary page also notes the temporary location of the log files.

   Figure 4-69 Application Upgrade Information

   
   

6. If the upgrade completes successfully, restart JDeveloper. JDeveloper notifies you if different versions of a configuration file require reconciliation, as illustrated by Figure 4-70.

   Figure 4-70 Manual Merge Notification

   
   

During the upgrade, MAF copies a set of files that cannot be customized for both Version 1 of the application and Version 2 (the upgraded version of the application). These files include the connections.xml and adf-config.xml files. If MAF detects differences between Version 1 and Version 2 connections.xml and adf-config.xml files, it retains both copies of these files and writes an entry to the merge log file. MAF differentiates Version 1 by appending a version number if version numbers exist to the file name. If version numbers do not exist, MAF adds _old to the file name, as illustrated by connections_old.xml in Figure 4-70. If needed, you can manually merge the differences into the new version. As illustrated in Figure 4-71, MAF places the merge file log in the temporary location noted in the Summary page. MAF names the files as workspace name_timestamp.

Figure 4-71 The Merge Log File

4.14.8 What Happens in JDeveloper When You Upgrade Applications

In addition to copying Version 1 to the Temp directory and creating Version 1 and Version 2 copies of the non-upgradable configuration files, MAF also performs the following when you upgrade an application using the Upgrade Mobile Application from Archive wizard:

• Saves the libraries and resource bundles settings for each project in a map keyed with the project file name.

• Saves the resource bundle settings for the workspace.

• Saves the registered customization class in the adf-config.xml file.

• Imports the Version 2 .maa file to the temporary directory.

• Copies the application from the .maa file used for the upgrade to Version 1.

• Updates each Version 2 project (.jpr) file with the registered resource bundle and library dependency map. The new version of the library overrides the previous version. However, the Version 1 library remains unchanged if it shares the same name as the library used in Version 1.

• Updates the Version 2 workspace (.jws) file with the registered resource bundle settings.

• Updates the Version 2 adf-config.xml file to register the customization class.

4.14.9 What You May Need to Know About Upgrading FARs

If the application includes a FAR file that was not packaged in the original .maa file that was used to create the application (or included in the .maa file that is used to upgrade the application), then you must upgrade the FAR file separately. For example, you can create an application from an .maa file, add a FAR file, and then perform customization. You can upgrade the application to use a newer version of the FAR by adding the updated FAR from the Resources window as described in Section 4.13.1, "How to Use FAR Content in a MAF Application."

4.15.1 How to Integrate Cordova Plugins for iOS and Android

The Cordova Plugins page, illustrated in Figure 4-72, enables you to integrate the plugins to the mobile application by updating the platform-specific XML files (cordova.plist file for iOS and the config.xml file for Android) as described by the plugin instructions that are provided by the developer of the plugin.

Figure 4-72 The Cordova Plugins Page

In addition to the overview editor, you can configure MAF to use Cordova plugins by dragging the Cordova components from the Components window, shown in Figure 4-73, onto the Source editor or the Structure window. You can also use the Properties window to edit the configuration.

Figure 4-73 The Cordova Plugin Components

Before you begin:

Perform the following:

• Obtain the plugin integration instructions from the plugin developer.

• Obtain the plugin itself (the source code, the JavaScript file, and any additional libraries, resources, or assets).

• Table 4-12 lists the directories that you manually create in the application controller and view controller projects. Once created, copy the plugin artifacts to the directories. The primary components of a plugin, JavaScript file and the plugin binary libraries, are located in different projects (the view controller project and the application controller project) within a mobile application.

  Tip:

  The Installation section for the Cordova Plugins page provides read-only guidelines for these file locations.

  Table 4-12 Locations of Directories to Create Plugin Artifacts

  Artifact	File Location	Description
  Assets	application workspace directory\ApplicationController\src\plugins\Plugin Name\Platform\assets For example: JDeveloper\mywork\application1\ApplicationController\src\plugins\BarcodeScanner\Android\assets	This folder contains plugin assets. This Android-only artifact is optional.
  JavaScript Files	application workspace directory\ViewController\public_html\plugins\Plugin Name\Platform\js For example: JDeveloper\mywork\application1\ViewController\public_html\plugins\BarcodeScanner\Android\js	This directory contains the plugin JavaScript files. This folder is required and must contain a JavaScript file.
  Plugin Library	application workspace directory\ApplicationController\src\plugins\Plugin Name\Platform\bin For example: JDeveloper\mywork\application1\ApplicationController\src\plugins\BarcodeScanner\Android\bin	Contains the plugin binary. This is a required folder, one which must contain this content.
  Dependent Libraries	application workspace directory\ApplicationController\src\plugins\Plugin Name\Platform\libs For example: JDeveloper\mywork\application1\ApplicationController\src\plugins\BacodeScanner\Android\libs	Copy any additional, dependent libraries to this location. This is an optional folder.
  Resources	application workspace directory\ApplicationController\src\plugins\Plugin Name\Platform\res For example: JDeveloper\mywork\application1\ApplicationController\src\plugins\BacodeScanner\Android\res	Copy additional plugin resources folder. This is an optional folder.

  
  

  Figure 4-74 illustrates these locations in the Applications window.

  Figure 4-74 The Plugin Artifacts

  
  

• For application features authored in MAF AMX, the task flow's managed bean must contain a handler method that uses the invokeContainerJavaScriptFunction as follows:

  AdfmfContainerUtilities.
  invokeContainerJavaScriptFunction(featureid, methodname, new Object[]
                                                           { params... })
  

  This method invokes JavaScript. For an example implementation, see the ManagedBean.java file in the APIDemo sample application. 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.maf/Samples
  

  For more information about the invokeContainerJavaScriptFunction, see Section B.2.14, "invokeContainerJavaScriptFunction" and Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

• If you obtain the plugin-related artifacts and the JavaScript files from a FAR, as described in Section 4.15.4, "What You May Need to Know About Integrating Plugins Using FARs," then you must ensure that the plugin has an accompanying JavaScript file. If the FAR consumed by the mobile application does not include the JavaScript file, then you must obtain one, or create one using the FAR developer's instructions. You must also add the FAR to the application as described in Section 4.13.1, "How to Use FAR Content in a MAF Application."

To add an Android plugin:

1. Open the maf-application.xml overview editor and choose the Cordova Plugins page.

2. Click Add.

3. Complete the Insert Plugin dialog, shown in Figure 4-75.

   Figure 4-75 Adding an Android Plugin

   
   

   • Fully Qualified Name—The fully qualified name of the plugin. This name is provided by the manifest or readme file and maps to the name attribute of the plugin element in the config.xml file.

   • Implementation Class—The name of the class that implements the plugin. This name, which is provided by the manifest or readme file, is typically a Java package followed by a class name. It maps to the value attribute of the plugin element in the config.xml file.

   • Name—The name of the plugin. This is the name of the folder containing the plugin artifacts as well as the value logged to the deployment when errors are detected.

   • Platform—Choose Android.

4. Click OK.

   Tip:

   You can also access this dialog by dragging a Plugin component from the Cordova Plugins components window onto the editor or into the Structure window.

5. If the plugin requires its own Android resources, enter the Java package that these resources should appear under in the Resource Package Name field. Otherwise, leave this field blank. This is an optional value.

Figure 4-76 Integrating an Android Plugin

To add an iOS plugin:

1. Open the maf-application.xml overview editor and choose the Cordova Plugins page.

2. Click Add.

3. Complete the Insert Plugin dialog, shown in Figure 4-77.

   Figure 4-77 Adding an iOS Plugin

   
   

   • Fully Qualified Name—The fully qualified name of the plugin. This name is provided by the manifest or readme file and maps to the <key> element in the cordova.plist file.

   • Implementation Class—The name of the class that implements the plugin. This name is provided by the manifest or readme file and is typically the name of an Objective-C class. It maps to the <string> element in the cordova.plist file.

   • Name—The name of the plugin. This is the name of the folder containing the plugin artifacts as well as the value logged to the deployment when errors are detected.

   • Platform—Choose iOS.

4. Click OK.

5. In the Linker Flags field, enter any additional linker flags required by the plugin. You must add an option to link to the plugin library, such as -l BarcodeScanner. For example:

   -l BarcodeScanner -lc++ -liconv -framework CoreVideo -framework AssetsLibrary
   -framework AVFoundation
   

   Consult the readme file to determine if any additional libraries are required.

   Figure 4-78 Integrating an iOS Plugin

   
   

To enable MAF AMX content to reference the plugin's JavaScript file:

1. Open the maf-feature.xml overview editor, then choose the application feature that uses the plugin.

2. Click Content and then select MAF AMX.

   Note:

   The view controller project must contain a class that invokes JavaScript using the invokeContainerJavaScriptFunction in a Java handler as follows:

   AdfmfContainerUtilities.invokeContainerJavaScriptFunction( 
                                                             featureid, methodname, new Object[] { params... });
   

3. Click Add in the Includes table to open the Insert Include dialog.

   Figure 4-79 Referencing the Plugin JavaScript File in the View Controller Project

   
   

4. Choose JavaScript, and then browse to the location of the plugin's JavaScript file, which is located in the view controller project's public_html folder. As illustrated in Figure 4-79, the JavaScript file is located within the view controller project at plugins/plugin name/platform/js/JavaScript file name.

To enable a local HTML content to reference the plugin's JavaScript file:

1. Open the maf-feature.xml overview editor, then choose the application feature that uses the plugin.

2. Click Content and then select Local HTML.

3. Reference the JavaScript file using a <script> tag in the HTML document, such as <script type="text/javascript" src="../../../../www/js/barcodescanner.js"></script> in Example 4-31.

   Example 4-31 Referencing the Plugin JavaScript File Using the <script> Tag

   <!DOCTYPE html>
   <html>
     <head>
       <meta name="viewport" content="user-scalable=no,height=device-height,width=device-width" />
       <meta name="apple-mobile-web-app-capable" content="yes" />
       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></meta>
       <script type="text/javascript">if (!window.adf) window.adf = {};  
                                         adf.wwwPath = "../../../../www/";</script>
       <script type="text/javascript" src="../../../../www/js/base.js"></script>
       <script type="text/javascript" src="../../../../www/js/barcodescanner.js"></script>
       <script type="text/javascript" charset="utf-8">
           function scanBarcode()
           {
             window.plugins.barcodeScanner.scan(
                                                function(result) {
                                                 if (result.cancelled)
                                                   updateContentNode("the user cancelled the scan");
                                                 else
                                                 updateContentNode("We got a barcode: " +
                                                   result.text);
                                                },
                                                function(error) {
                                                   updateContentNode("scanning failed: " + error);
                                                }
                                               )
           }
    
           function updateContentNode(newContent)
           {
             $("#content").html(newContent);
           }
         </script>
     </head>
     <body onload="onBodyLoad()">
    
       <!-- MAIN PAGE -->
       <div data-role="page" id="main" data-url="main.jspx" data-position="fixed">
         <div data-role="header" data-position="fixed">
           <h1>
             Barcode Scanner Test
           </h1>
         </div>
         <div data-role="content" id="content">
           No barcode scanned yet
         </div>
         <div data-role="footer" data-position="fixed">
           <div data-role="navbar">
             <ul>
               <li>
                   <a href="javascript:try{scanBarcode();}catch(e){alert(e.description);}"
                   data-rel="dialog" data-transition="pop">Scan barcode</a>
               </li>
             </ul>
           </div>
         </div>
       </div>
     </body>
   </html>
   

4.15.2 What Happens When You Configure a Plugin

Using the overview editor or the Cordova Plugins components from the Components windows populates the maf-application.xml file with a <adfmf:cordovaPlugins> element, as illustrated in Figure 4-30. Refer to Oracle Fusion Middleware Tag Reference for Oracle Mobile Application Framework for more information on this element and its child elements.

<adfmf:cordovaPlugins>
    <adfmf:plugin name="BarcodeScanner" platform="iOS" 
                 implementationClass="CDVBarcodeScanner"
                 fullyQualifiedName="ios.apache.cordova.barcodeScanner">
      <adfmf:iosPluginInfo>
        <adfmf:linkerFlags>-l BarcodeScanner     
                           -lc++
                           -liconv
                           -framework CoreVideo
                           -framework AssetsLibrary
                           -framework AVFoundation</adfmf:linkerFlags>
      </adfmf:iosPluginInfo>
    </adfmf:plugin>
    <adfmf:plugin platform="Android" name="BarcodeScanner"
                  implementationClass="com.phonegap.pluigns.barcodescanner.BarcodeScanner"
                  fullyQualifiedName="BarcodeScanner">
      <adfmf:androidPluginInfo>
        <adfmf:resourcePackageName>com.google.zxing.client.android</adfmf:resourcePackageName>
        <adfmf:androidManifestActivities>&lt;activity android:name=".CaptureActivity"
              android:screenOrientation="landscape"
              android:clearTaskOnLaunch="true"
              android:stateNotNeeded="true"
              android:configChanges="orientation|keyboardHidden"
              android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
              android:windowSoftInputMode="stateAlwaysHidden"&gt;
              ...
         </adfmf:androidManifestActivities>
      </adfmf:androidPluginInfo>
    </adfmf:plugin>
  </adfmf:cordovaPlugins>
</adfmf:application>

4.15.3 How to Add Plugin Preferences

On both the application-level and application feature-level user preferences pages, the Cordova plugin preferences display either at the bottom of a user preference page beneath the preferences defined by the preferences elements described in Chapter 14, "Enabling User Preferences" or as a child preference page that opens from a preference group or from a single item preference list selection.

Before you begin:

Refer to Preferences and Settings Programming Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/) for information on the Settings bundle (Settings.bundle) and its contents (such as the Root.plist file and the .strings file).

To merge the Cordova plugin preferences at the bottom of a preference page of an iOS application:

1. Create a resource (res) file within the application controller project for the plugin, such as:

   application workspace directory\ApplicationController\src\plugins\plugin name\iOS\res
   

2. Copy the Settings bundle (Settings.bundle ) file into the plugin's res folder.

To merge the Cordova plugin preferences as a child page in an iOS application:

1. Create a resource (res) folder within the application controller project for the plugin, such as:

   application workspace directory\ApplicationController\src\plugins\plugin name\iOS\res
   

2. Copy the Settings bundle (Settings.bundle ) file into the plugin's res folder.

3. Rename the Root.plist file to PluginName.Root.plist, where PluginName is the name of the plugin. For example, rename this file BarcodeScanner.Root.plist.

4. Define a sting ID and localizable value for the title of the child page in the plugin's .strings file. This ID must be PluginName.page.title where PluginName is the name of the plugin. For example:

   "PluginName.page.title" = "Some Localized Page Title";

To merge the Cordova plugin preferences at the bottom of a preference page of an Android application:

1. Create a resource (res) folder for the plugin in the application controller project, such as:

   application workspace directory\ApplicationController\src\plugins\plugin name\Android\res
   

2. Copy the resources that contain the preferences.xml file into the plugin's res folder. For more information the preferences.xml file and defining subscreens, see "Defining Preferences in XML" in Settings guide, available from the Android Developers website (http://developer.android.com/guide/topics/ui/settings.html) or the Android SDK documentation. For information on how the MAF deployment framework converts preferences, see Section C.2, "Converting Preferences for Android."

To merge the Cordova plugin preferences as a child page in an Android application:

1. Copy the resources that contain the preferences.xml file into the plugin's res folder.

2. Nest the set of preferences (illustrated in Example 4-33) within another PreferenceScreen element as illustrated in Example 4-34.

   Example 4-33 Preferences

   <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">
         <PreferenceCategory android:title="@string/preferences_scanning_title">
               <CheckBoxPreference android:key="preferences_decode_1D"
                                   android:defaultValue="true" 
                                   android:title="@string/preferences_decode_1D_title"/>
               ...
          </PreferenceCategory>
           ...
    
   </PreferenceScreen>
   

   Example 4-34 illustrates defining an android:key attribute to wrap the PreferenceScreen element.

   Example 4-34 A Set of Preferences Wrapped in a PreferenceScreen Element

   <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">
     <PreferenceScreen android:key="wrapperScreen" android:title="Barcode Scanner">
         <PreferenceCategory android:title="@string/preferences_scanning_title">
               <CheckBoxPreference android:key="preferences_decode_1D"
                                   android:defaultValue="true"
                                   android:title="@string/preferences_decode_1D_title"/>
               ...
          </PreferenceCategory>
           ...
     </PreferenceScreen>
   </PreferenceScreen>
   

3. If the preference page requires localization, define the string values in the localized strings.xml files. For more information on the strings.xml files, see the "String Resources" section in App Resources Guide, available from the Android Developers website (http://developer.android.com/guide/topics/resources/index.html) or the Android SDK documentation. For information on how the MAF deployment framework handles the strings.xml file, see Section C.2.3, "Strings.xml."

4.15.4 What You May Need to Know About Integrating Plugins Using FARs

Although the components of a mobile application may be created by a single developer, an application may typically be comprised from resources provided by different developers. Adding third-party plugins illustrates the latter case, with a FAR developer first creating and testing an application feature that uses a plugin before deploying the view controller project as a Feature Archive file (FAR). The FAR developer publishes this FAR to an Application Assembler developer and provides a set of instructions (such as a readme file) for integrating the plugin as well as the JavaScript file. The FAR developer may also provide the Application Assembler developer with a ZIP file of the plugin binary library. The Application Assembler then adds a FAR to a mobile application and uses the instructions to integrate the JavaScript file and plugin binary libraries into the mobile application's projects. The mobile application is subsequently tested, deployed as a platform-specific package, and published. Specifically, the collaboration between the FAR developer and the Application Assembler is comprised of the following:

1. The FAR developer uses Xcode or the Android SDK to create the Cordova plugin library (resulting in an .a file for iOS or a JAR file for Android). To enable MAF applications to consume this library, the developer performs the following:

   1. Creates a mobile application. The developer includes the plugin binary to various locations within the application controller project and then adds the JavaScript file to the public_html directory in the view controller project. For a user interface implemented as MAF AMX, the JavaScript file is referenced in the maf-feature.xml file using the Insert Includes dialog, as described in Section 4.10.1, "How to Define the Application Content." For HTML-based user interfaces, reference this file using a JavaScript includes.

      For MAF AMX-authored application features, JavaScript is invoked by including the invokeContainerJavaScriptFunction method in a Java handler. For more information, see Section B.2.14, "invokeContainerJavaScriptFunction" and Oracle Fusion Middleware Java API Reference for Oracle Mobile Application Framework.

      In an HTML-authored application feature, JavaScript is called directly by referencing the location of the JavaScript file in the <script> tag.

   2. Integrates the Cordova plugin using the Cordova Plugins page of the maf-application.xml overview editor and its dialogs.

   3. Deploys the application to a device for testing.

   4. Deploys the view controller project as a FAR. This FAR itself may include such artifacts as MAF AMX and HTML pages that reference the Cordova plugins as well as the JavaScript files.

      Note:

      The FAR may not always include the JavaScript file.

   5. Although not included in the FAR, the FAR developer provides the Application Assembler developer with a set of instructions to integrate the plugin into a mobile application. Because these instructions are specific to both the development organization and the plugin itself, the means and format through which they are conveyed (such as a metadata file or a readme file), results from agreements between the FAR and Application Assembler developers. Example 4-35 illustrates a portion of the a README.md file that describes how to integrate an iOS plugin:

      Example 4-35 The README.md File

      ...
      ## Adding the plugin to your project ##
      * Copy the .h, .cpp and .mm files to the Plugins directory in your project.
      * Copy the .js file to your www directory and reference it from your html file(s).
      * In the `Supporting Files` directory of your project, add a new plugin by editing  
       the file `Cordova.plist` and in the `Plugins` dictionary adding the following
       key/value pair:
        * key: `org.apache.cordova.barcodeScanner`
        * value: `CDVBarcodeScanner`
       Add the following libraries to your Xcode project, if not already there:
        * AVFoundation.framework
        * AssetsLibrary.framework
        * CoreVideo.framework
        * libiconv.dylib
      ...
      

2. The Application Assembler adds the FAR mobile application, as described in Section 4.13.1, "How to Use FAR Content in a MAF Application."

3. Unless the FAR developer provides a ZIP file of the plugin binary, the Application Assembler must build the plugin using the platform-specific SDKs. The plugin is packaged in the platform-specific package (the .a file for iOS or a JAR file for Android).

4. The Application Assembler developer adds the plugin binary libraries to the application controller project and the JavaScript file to the public_html directory of the view controller project.

5. Using the Cordova Plugins page of the maf-application.xml overview editor and its dialogs, the Application Assembler developer updates the platform-specific XML files (that is, the cordova.plist file for iOS and the config.xml file for Android) as specified in the instructions. The MAF deployment uses this configuration to incorporate the plugins into the mobile application.