4 Defining a Mobile Application

4.1.1 Using the MAF Application Editor for maf-application.xml

The MAF Application 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. From these pages you have access to registered features (created with the MAF Feature Editor), navigation, device access, security, feature archives, and plugins. For more information, see Section 4.4, "Setting the Basic Information for a Mobile Application."

4.1.2 Using the Mobile Feature Editor for maf-features.xml

The MAF Feature Editor enables you to add features to your application by editing the maf-features.xml file. You create the features with this editor, and specify the characteristics (ID, name, description, vendor information, version, lifecycle event listener, security, and images for navigation and for the springboard) through the editor. For more information, see Section 4.10, "Setting the Basic Configuration for the Application Features."

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

The Application page of the MAF Application 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 MAF Application Editor for the maf-application.xml file by double-clicking MAF Application Editor (located in the MAF node of the assembly project in the Project Explorer panel, as shown in Figure 4-3).

Figure 4-3 Selecting MAF Application Editor in the Project Explorer

To set the basic information for a mobile application:

1. Choose the Application page by selecting the application's name in the Outline.

   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.12.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.6, "How to Create an iOS Deployment Configuration."

3. Accept the default, or enter a unique ID in the Id field.

   To avoid naming collisions, Android and iOS use reverse package names, such as com.company.application. Oracle Enterprise Pack for Eclipse 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.4, "How to Create an Android Deployment Configuration" and Section 19.2.6, "How to Create an iOS Deployment Configuration."

   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 next to 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.

   Note:

   If you place the mouse pointer over the label for Lifecycle Event Listener, Oracle Enterprise Pack for Eclipse displays a tooltip describing the listener class.

   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 Select Class dialog, shown in Figure 4-5. After you close this dialog, Oracle Enterprise Pack for Eclipse 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.8, "About Lifecycle Event Listeners."

4.6.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 MAF Application Editor from assembly project > MAF in the Project Explorer to open maf-application.xml.

To set the display behavior for the navigation bar:

1. Select Show Navigation Bar 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 deselect Show Navigation Bar, 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 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. To display the springboard select Show Springboard. This is selected by default.

2. Select Show on application launch to enable the mobile application to display the springboard to the end user after the mobile application has been launched.

3. Select Show Springboard Toggle Button to enable the display of the springboard button, shown in Figure 4-9, 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.

   Figure 4-9 The Springboard Toggle Button

   
   

To set the slide out behavior for the springboard:

1. Select Slide Right for Animation. The springboard occupies an area determined by the number of pixels (or the percent) entered for the 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.

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

4.6.2 What Happens When You Configure the Navigation Options

Setting the springboard and navigation bar options updates or adds elements to the maf-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>

4.6.3 What Happens When You Set the Animation for the Springboard

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

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

The following line disables the animation:

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

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

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

In addition to the animation, Example 4-5 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.6.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, "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 an 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.6.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.7.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-6, to launch the embedded application features.

The default springboard (adfmf.default.springboard.jar) is an 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.3, "Deploying Feature Archive Files (FARs)."

The default springboard (springboard.amx, illustrated in Example 4-6) is implemented as an 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-10, an 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-10 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-11, 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-11 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.6.6 What You May Need to Know About the Runtime Springboard Behavior

If you chose the Show 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.7.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.3, "About the Mobile Application Configuration File maf-application.xml," 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-7 shows some of the defined feature references and their associated attributes. The MAF Application 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.

Figure 4-12 Registered Features in the Application Page

Using Registered Features, you enter the references to the application feature and set its display within the mobile application's springboard, as shown in Figure 4-12.

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-37. 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 Application Editor, as described in Section 4.10, "Setting the Basic Configuration for the Application Features." In addition, you must open the MAF Application Editor.

To designate feature references:

1. Select Registered Features in the outline of the MAF Application Editor.

2. Click Browse to open the Register Mobile Feature dialog, as shown in Figure 4-15.

   Figure 4-15 Registering Features for an Application

   
   

   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.7.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."

3. Select the select the ID of the application feature you want to register with the application. You can use Shift and Ctrl to select more than one, and click OK.

   You can also add references to application features that are contained in an imported feature archive (FAR) file. For more information, see Section 4.14.1, "Importing a FAR as an Application Library."

4. In the Registered Features page of the MAF Application Editor, as shown in Figure 4-14 use the up- and down-arrows to arrange the display order of 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.8.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 features 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.6.5, "What You May Need to Know About Custom Springboard Application Features with MAF AMX Content."

4.7.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 an 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. Oracle Enterprise Pack for Eclipse 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, Oracle Enterprise Pack for Eclipse 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.

Figure 4-18 Auditing id Attributes

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.8.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-10 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-11, 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.8.2, "Timing for Mobile Application Events." See also the LifeCycleListener interface in 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.8.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.8.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.8.4 About Application Feature Lifecycle Listener Classes

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

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

Example 4-13 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.8.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 Java API Reference for Oracle Mobile Application Framework.

4.8.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.7.1, "How to Designate the Content for a Mobile Application." For information on using the methods of the AdfmfSlidingWindowUtilities API, refer to Java API Reference for Oracle Mobile Application Framework.

4.10.1 How to Define the Basic Information for an Application Feature

The MAF Feature editor, shown in Figure 4-19, enables you to add an application feature, designate its basic information, and its display icons.

Figure 4-19 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 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 viewContent directory. See also Section 4.11.2, "What You May Need to Know About Selecting External Resources."

In addition, you must open the MAF Feature Editor.

To set the basic information for the application feature:

1. In the outline, click Right-click to open the New Object dialog.

2. Type a unique identifier for the application feature for the feature you are creating.

3. Complete the fields in the MAF Feature Editor, shown in Figure 4-20, and then click OK. To complete this dialog:

   • Enter a display name for the application feature in the Name 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.7.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."

     Figure 4-20 Adding an Application Feature

     
     

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

5. Enter the originator of the application feature in the Vendor field. This is an optional value.

6. Enter the version number of the application feature in the Version 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.8, "About Lifecycle Event Listeners." This is an optional value.

8. If your application uses security, select the Enable Security checkbox.

9. 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 Project Explorer into the file location field. This is an optional value.

4.11.1 How to Define the Application Content

Once you have created features in the MAF Feature Editor, you define their content by right-clicking on each of the features to bring up the New Object dialog, shown in Figure 4-21. This dialog provides you with a selection of target content-related elements. The selections in this dialog let you 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-21, 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-21 Defining the Implementation of the Application Feature

Before you begin:

Each content type has its own prerequisites, as follows:

• AMX Page—The default content type for application features, which includes both individual MAF AMX pages. 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 an 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). 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 available from File > New. Alternatively, you can create an MAF AMX page using the context menu shown in Figure 4-22 that appears when you right-click the view project in the Project Explorer 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-22 Context Menu for Creating an MAF Page

  
  

• Task Flow—A task flow page defines the path through the application, from feature to feature. Task flow files include control flow specifications and activities; activities include calling methods, using routers, calling another task flow, returning from a task flow, and displaying view pages. For more information, see Section 5.2, "Creating Task Flows."

• 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, "Application Container APIs."

• 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 12, "Implementing Application Feature Content Using Remote URLs."

To create new application content:

1. Select an application feature listed in the Outline of the MAF Feature Editor.

2. Click the right mouse button and select New, as shown in Figure 4-23.

   Figure 4-23 Context Menu for New Feature

   
   

3. In the New Object dialog, expand the Content node, if necessary and choose one of the following content types to correspond with the generated ID, and then click OK:

   • AMX Page. See Figure 4-27.

   • Task Flow

   • Local HTML. See Figure 4-24

   • Remote URL. See Figure 4-26.

4. Define the content-specific parameters:

   • For an AMX Page, click Browse to specify an existing page, or click Create to open the New MAF Page dialog. See Figure 4-27.

   • For a Task Flow, click Browse to specify an existing page, or click Create to open the New MAF Task Flow dialog.

   • For a Local HTML file, click Browse to specify an existing page, or click Create to open the New Mobile HTML Page dialog. See Figure 4-24.

   • For a Local HTML file, click Browse to specify an existing page, or click Create to open the New Mobile HTML Page dialog. See Figure 4-24. Select the parent folder for this file and give it a descriptive file name for later use. Choose whether to save the file as HTML or as XHTML, then click Finish. Because this is an application feature, this page is stored within the Web Content folder of the view controller project.

     Figure 4-24 Creating the Local HTML Page as the Content for an Application Feature

     
     

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

     Figure 4-25 Selecting the Connection for the Hosted Application

     
     

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

     Figure 4-26 Creating a URL Connection

     
     

To designate the application feature content as an AMX Page:

1. Select the parent folder for your new AMX page.

2. Give your page a descriptive name that will make it easier to identify when working on your mobile application.

3. Click Finish to save the page. The New MAF Page dialog is shown in Figure 4-27.

   Figure 4-27 Selecting MAF AMX as the Content Type

   
   

4.11.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 ViewContent directory of the view 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.10.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.11, "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.11, "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.11, "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.13, "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.

4.12.1 Working with Resource Bundles

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

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

<amx:facet name="header">
      <amx:outputText value="#{viewControllerBundle.NewPage_header}"
       id="ot1" />
    </amx:facet>

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

4.12.1.5 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, through the same XLIFF file process used for externalizing strings. See Figure 4-32.

Figure 4-32 Externalizing Images in the XLIFF File

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

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

<amx:image id="i1" source="#{viewControllerBundle.NewPage_icon2JPG}"
 shortDesc="#{viewControllerBundle.NewPage_myFavoriteImage}" />
         <trans-unit id="NewPage_icon2JPG">
             <source>/icon2.JPG</source>
             <target/>
         </trans-unit>
         <trans-unit id="NewPage_myFavoriteImage">
             <source>My Favorite Image</source>
             <target/>
         </trans-unit>
<trans-unit id="IMAGEPATH">
     <source>/feature1/test.jpg</source>
     <target/>
</trans-unit>

Note:

The image location defined in the <source> element in Example 4-18 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.11.2, "What You May Need to Know About Selecting External Resources."

After you update ViewControllerBundle.xlf, Oracle Enterprise Pack for Eclipse automates the construction of an EL expression for the source attribute for the icon attribute.

<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.13.1 About the maf-skins.xml File

After you create a mobile application, Oracle Enterprise Pack for Eclipse populates the maf-skins.xml file to the mobile application's src/META-INF node. The file itself is populated with the empty adfmf-skins tag and the skin and skin-addition tags can be added later.

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

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.13.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.13.10, "What You May Need to Know About Skinning."

4.13.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.2.css, and amx-v1.2.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 deployment subdirectory of the assembly project (for example, assembly project\.main.android). 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 build/release/assets or build/debug/assets directory of the Android application package (.apk) file.

4.13.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.2</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 an MAF CSS when you integrate a style sheet into an existing skin.

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

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf-skins xmlns="http://xmlns.oracle.com/adf/mf/config">
  <skin-addition>
    <skin-id>mobileAlta-v1.2.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.2.iPhone5,1</skin-id>
   <style-sheet-name>iPhoneStylesheet.css</style-sheet-name>
</skin-addition>

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

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

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

4.13.4 How to Add a Custom Skin to an Application

To add a custom skin to your application, first create a CSS file with in the application controller project's ViewContent directory and then refer it from maf-skins.xml using either the skin-addition or skin tag.

To add a custom skin to an application:

1. From the Main Menu, select File > New > Other and then type CSS in the filter. Select Web > CSS File.

2. In the New CSS File wizard, specify a name and directory (subdirectory of the ViewContent directory) for the CSS file.

3. Click OK.

4.13.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 Project Explorer, expand the assembly project, then adf, then META-INF, then double-click maf-config.xml file to open it in the XML Editor.

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, as shown in Figure 4-33.

   Figure 4-33 Editing maf-config.xml

   
   

   To see the file in the Source Editor, click the Source tab at the bottom of the XML Editor. Example 4-24 shows the configuration required to make a mobile application use the mobileAlta.v1.2 skin.

   Example 4-24 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.2</skin-version>
   </adfmf-config>
   

To add a new style sheet to a skin

1. In the Project Explorer, expand the application project > src, > META-INF folders, then double-click the file maf-skins.xml to open it in the XML Editor.

2. Switch to the Design tab. Select and right-click the adfmf-skins tag. Select Add Child > skin-addition.

   • Select skin-id tag under skin-addition tag. Go to the Content column and enter the identifier of the skin to which you want to add a new style (for example, mobileAlta-v1.2).

   • Right click skin-addition tag and select Add Child > style-sheet-name. Select the style-sheet-name tag and go to the Content column. Specify the path of the css file relative to the ViewContent folder. For example, if you created the css file at ViewContent/css/myaddedcss.css, then enter css/myaddedcss.css as the value

3. Save the file maf-skins.xml.

4.13.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 Project Explorer, expand Application Project > src > META-INF and double-click maf-skins.xml to open it in the XML Editor.

2. Switch to the Design tab. Select and right click adfmf-skins tag. Select Add Child > skin.

3. Expand the skin node and notice that id and family tags are created by default. You can right click and select Add Child > extends or Add Child > style-sheet-name to create extends and style-sheet-name respectively.

4. Select any of the following fields and go to the Content column in order to edit the values 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.13.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.2 skin, enter mobileAlta-v1.2.

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

5. Save the file maf-skins.xml.

4.13.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.13.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 Project Explorer, expand the application project > src > META-INF, then double-click maf-skins.xml to open it in the XML Editor.

2. Switch to the Design tab. Select and right click skin tag. Select Add Child > version.

3. Right-click on version and select Add Child > default. Select default tag, go to the Content column and set the value of default as true 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.13.5, "How to Specify a Skin for an Application to Use."

4. Select name tag under skin tag and go to the Content column. Enter the value of the name field. For example, enter v1 if this is the first version of the skin.

5. Save the file maf-skins.xml.

4.13.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-25 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.13.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-25, 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.13.9 Overriding the Default Skin Styles

For an 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.13.9.1 How to Apply New Style Classes to an Application Feature

The Includes section in the MAF Feature Editor for the maf-feature.xml files enables you to add a cascading style sheet (CSS) to an MAF AMX application feature.

Figure 4-34 The Includes Section

Before you begin:

Create an 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 right clicking the ViewContent folder of the view controller project, and then select File > New > Other and type CSS in the filter. Then, select Web > CSS File.

How to add a style to an application feature:

1. Open the file maf-feature.xml. Ensure that there is a feature that has AMX Page as the content type.

2. In the Outline section, expand Features > feature name > Contents > Feature Id and select Includes. On selection, the Includes section will appear on the right side of the editor, as shown in Figure 4-35.

   Figure 4-35 Selecting the StyleSheet Option

   
   

3. Select the Browse button to select a file for inclusion in the Includes section. This opens the Select CSS Stylesheet or JavaScript File dialog, as shown in Figure 4-35.

4. Select the CSS file that you created earlier under the ViewContent directory of the view controller project.

   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-36 Selecting the CSS for the Application Feature

   
   

5. Save the file maf-feature.xml.

4.13.10 What You May Need to Know About Skinning

The CSS files defined in the maf-skins.xml file, illustrated in Example 4-26, 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. You can find this example by selecting File > New > MAF Examples, then selecting SkinningDemo from the MAF Examples page.

For example, at the iOS level, the stylesheet (mobileAlta in Example 4-26) 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.2.iPhone</id>
        <family>mobileAlta</family>
        <extends>mobileAlta-v1.2.iOS</extends>
        <style-sheet-name>skins/mobileAlta-v1.2.iphone.css</style-sheet-name>
    </skin>
    <skin>
        <id>mobileAlta-v1.2.iPad</id>
        <family>mobileAlta</family>
        <extends>mobileAlta-v1.2.iOS</extends>
        <style-sheet-name>skins/mobileAlta-v1.2.ipad.css</style-sheet-name>
    </skin>
    <skin>
        <id>mobileAlta-v1.2.iPod</id>
        <family>mobileAlta</family>
        <extends>mobileAlta-v1.2.iOS</extends>
        <style-sheet-name>skins/mobileAlta-v1.2.ipod.css</style-sheet-name>
    </skin>
    <!--  Skin Additions -->
    <skin-addition>
        <skin-id>mobileAlta-v1.2.iPhone</skin-id>
        <style-sheet-name>skins/mystyles.iphone.addition1.css</style-sheet-name>
    </skin-addition>
    <skin-addition>
        <skin-id>mobileAlta-v1.2.iPhone</skin-id>
        <style-sheet-name>skins/mystyles.iphone.addition2.css</style-sheet-name>
    </skin-addition>
    <skin-addition>
        <skin-id>mobileAlta-v1.2.iOS</skin-id>
        <style-sheet-name>skins/mystyles.ios.addition2.css</style-sheet-name>
    </skin-addition>
</adfmf-skins>

4.13.11 Enabling Dynamic Skin Selection at Runtime

You can configure your application to enable end users select an alternative skin at runtime. You can find this example by selecting File > New > MAF Examples, then selecting SkinningDemo from the MAF Examples page. You can configure this functionality when you want end users to render the application using a skin that is more suitable for their needs.

Figure 4-37 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-37 Changing an Application's Skin at Runtime (on iOS)

4.14.1 Importing a FAR as an Application Library

You can import a FAR as an application library to make its features accessible to your MAF application.

To import a FAR as an application library:

1. In the Project Explorer, expand the folder for the top-level assembly project, then expand the MAF folder.

2. Double-click MAF Application Editor to open maf-application.xml.

3. Right-click on the Feature Archives folder and choose New > Feature Archive.

4. Give the archive a name, or accept the default name (featureArchive1, where subsequent archives will be numbered in sequence).

5. Click the Browse button for the URI field to open the Mobile Feature Archive Location dialog, then type in the URI at which the FAR can be located. Oracle Enterprise Pack for Eclipse verifies that the selected file contains feature definitions, and that the location is accessible.

6. When you have specified the URI and Oracle Enterprise Pack for Eclipse has verified it, click OK.

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

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-38, these messages reflect the state of the sync-config.xml file in the consuming application.

Figure 4-38 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 Feature 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.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. This view controller project contains the default structure and metadata files of a MAF view controller project. 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.

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

• 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.14.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.15.1 How to Integrate Cordova Plugins for iOS and Android

The Cordova Plugins page, illustrated in Figure 4-39, 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-39 The Cordova Plugins Page

OEPE manages plugins with file mapping instructions, used at deployment time, to copy the artifacts to the desired places.

OEPE allows you to copy to the source project. This may be useful for development. The IDE allows for these files to be removed so that all files will be deployed using the file mapping.

You can drag and drop using the Browse dialog to create mapping, according to the following file filters:

foo.xyz mapping means copy foo.xyz to the target root directory

*.xyz mapping means copy all files with xyz extension in the current directory.

**.xyz mapping means copy all files with extension xyz in all subdirectories.

**\foo\**\*.xyz mapping means copy all files with xyz extension that are contained with in a foo subdirectory.

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.

  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	This folder contains plugin assets. This Android-only artifact is optional.
  JavaScript Files	application workspace directory\ViewController\public_html\plugins\Plugin Name\Platform\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	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	Copy any additional, dependent libraries to this location. This is an optional folder.
  Native Libraries	application workspace directory\ApplicationController\src\plugins\Plugin Name\Platform\native-libs	For Android only. Copy native Android libraries to this location.
  Resources	application workspace directory\ApplicationController\src\plugins\Plugin Name\Platform\res	Copy additional plugin resources folder. This is an optional folder.

  
  

  These items are only visible in Oracle Enterprise Pack for Eclipse when the view includes .* resources. For more information, see Section 3.2.2, "What Happens When You Create an MAF Application."

• 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 available from File > New > MAF Examples.

  For more information about the invokeContainerJavaScriptFunction, see Section B.2.14, "invokeContainerJavaScriptFunction" and 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.14.1, "Importing a FAR as an Application Library."

To add an Android plugin:

1. In the Project Explorer, expand the folder for the top-level assembly project, then expand the MAF folder.

2. In the outline, right-click Plug-Ins and choose New > Cordova Plug-in.

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

   Figure 4-40 Adding an Android Plugin

   
   

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

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

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

To add an iOS plugin:

1. In the Project Explorer, expand the folder for the top-level assembly project, then expand the MAF folder.

2. In the outline, right-click Plug-Ins and choose New > Cordova Plug-in.

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

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

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

   Figure 4-41 Adding an iOS Plugin

   
   

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

   • URI—the uniform resource indicator for the plugin. Click the Browse button to search for it, or drag it directly from an open folder into the URI spot in the MAF Application Editor.

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

   • Linker Flags — 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.

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

1. Open the MAF Feature Editor from the Project Explorer, 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-29.

   Example 4-29 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 MAF Application Editor populates the maf-application.xml file with a <adfmf:cordovaPlugins> element. Refer to 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 13, "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-31) within another PreferenceScreen element as illustrated in Example 4-32.

   Example 4-31 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-32 illustrates defining an android:key attribute to wrap the PreferenceScreen element.

   Example 4-32 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.11.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 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-33 illustrates a portion of the a README.md file that describes how to integrate an iOS plugin:

      Example 4-33 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.14.1, "Importing a FAR as an Application Library."

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.