5 Defining an ADF Mobile Application

This chapter describes using the overview editors to define the display behavior of the ADF Mobile application's springboard and navigation bar and how to designate content by embedding application features.

5.1 Introduction to Defining ADF Mobile Applications

An ADF Mobile application can have one or more view controller-type projects, each of which describes a set of features in an adfmf-feature.xml file. As described in Chapter 4, "Getting Started with ADF Mobile Application Development," ADF Mobile provides you with the adfmf-application.xml configuration file for the mobile application itself, and the adfmf-feature.xml file, which you use to define the content of the application. While you can manually change these files, ADF Mobile provides two overview editors that enable you to build these files declaratively.

5.1.1 Using the Overview Editor for adfmf-applications.xml

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

5.2 About the Mobile Application Configuration File

The adfmf-application.xml configuration file enables you to set the basic configuration of the ADF Mobile application by designating its display name, a unique application ID (to prevent naming collisions) and also by selecting the application features that will display on the application springboard (the equivalent of a home page on a smartphone). Further, this file enables you to create the user preferences pages for the mobile application. This file, which is generated by JDeveloper after you complete the application creation wizard as described in Section 4.2, "Creating an Application Workspace," is comprised of the elements listed in Table 5-1.

Table 5-1 Elements of the Application Descriptor File

Element

Description

<adfmf:application>

The root element of adfmf-application.xml.

<adfmf:description>

A description of the application.

<adfmf:featureReference>

A feature reference denotes which of the application features packaged in the FAR (Feature archive file) or defined in the adfmf-feature.xml file is relevant to the content of the mobile application. You define the character and content of ADF Mobile applications by selecting feature references. For more information about FARs, see Section 5.12, "Working with Feature Archive Files."

<adfmf:preferences>

Enables you to set the user preference options and behavior at the application level. You can also set how user preferences display and behave for the application features in the adfmf-feature.xml file. For more information, see Chapter 13, "Enabling User Preferences."

Enables you to define the behavior of the navigation bar and the springboard. A springboard is a home page in which all of the application icons and labels for the embedded application features are organized in a List View. A springboard provides a top-level view of all of the applications available to a user, who can page through and select applications. For more information, see Section 5.4, "Configuring the Springboard and Navigation Bar Behavior."

Example 5-1 illustrates the adfmf-application.xml file for an application called Acme Sales, a mobile application whose content includes a customer contacts application (<adfmf:featureReference id="customers" showOnNavigationBar="true"/>) which displays on the springboard, as shown in Figure 5-2.

Figure 5-1 Application Features Displaying in the Mobile Application's Springboard

You can modify these elements declaratively using the overview editor, shown in Figure 5-2, or manually using the Source editor. You can use either of these approaches interchangeably.

Figure 5-2 The Overview Editor for the adfmf-application.xml File

5.3 Setting the Basic Information for an ADF Mobile Application

The Application page enables you to set the name, application ID, and how the mobile application displays.

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

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

Before you begin:

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

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

To set the basic information for a mobile application:

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

Note:

By default, the editor opens the Application page.

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

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

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

Enter the version in the Version field.

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

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

Figure 5-5 Retrieving the Application Event Listener

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

5.4 Configuring the Springboard and Navigation Bar Behavior

You can configure the ADF Mobile application to control the display behavior of the springboard and the navigation bar in the following ways:

Hide or show the springboard and navigation bar to enable the optimal usage of the mobile device's real estate. These options override the default display behavior for the navigation bar, which is shown by default unless otherwise specified by the application feature.

Enable the springboard to slide from the right. By default, the springboard does not occupy the entire display, but instead slides from the left, pushing the active content (which includes the navigation bar's Home button and application features) to the right.

5.4.1 How to Configure Application Navigation

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

Figure 5-6 The Navigation Options of the Application Page

Before you begin:

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

To set the display behavior for the navigation bar:

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

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

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

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

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

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

To set the display behavior for the springboard:

Select the type of springboard (if any):

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

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

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

Note:

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

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.

5.4.2 What Happens When You Configure the Navigation Options

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

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

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

The use of the navigationBar's displayHideShowNavigationBarControl attribute.

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

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

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

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

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

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

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

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

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

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

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

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

Note:

Because building a mobile application is an iterative process, you can add, delete or update feature references as new FARs become available (and new application features are added to the adfmf-feature.xml file).

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

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

Note:

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

Figure 5-15 Reordering Feature References

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

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

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

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

Note:

The feature IDs must be unique across applications. Since the application features can be reused, use proper naming conventions to ensure that feature IDs are unique.

Figure 5-17 Auditing id Attributes

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

5.6 About Lifecycle Event Listeners

Within the ADF Mobile runtime, classes implement various LifeCycleListener methods to communicate event notifications sent from the native operating system frameworks to the JVM. These event notifications describe various states (starting, stopping, or hibernating) for both the mobile application and its embedded application features. ADF Mobile invokes the class functions to the JVM using a generic invoke message.

The overview editors for both the adfmf-application.xml and adfmf-feature.xml files enable you to declaratively add a lifecycle listener class that ADF Mobile calls when events occur. After you enter a fully qualified class name (including the package) using the Class and Package Browser in the overview editor's LifeCycle Event Listener Class field, JDeveloper populates the XML page with the listener-class attribute. For ADF Mobile applications, this attribute is included in the <adfmf:application> element, as shown in Example 5-9.

Example 5-9 The listener-class Attribute in the adfmf-application.xml File

The LifeCycle Events sample application provides an example of declaring the event listener class in both the adfmf-application.xml and adfmf-feature.xml files. This sample application is in the PublicSamples.zip file at the following location within the JDeveloper installation directory of your development computer:

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

For an example of implementing the LifeCycleListenerImpl.java interface at the application level, see the AppHandler.java file in the LifeCycleEvents sample application. This file is located in the application node within the application controller project's Application Sources folder.

5.6.2 Timing for Mobile Application Events

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

Table 5-3 ADF Mobile LIfecycle Events

ADF Mobile Application Event

Timing

Relation to iOS Application Delegate Methods

start

Called after the ADF Mobile application has completely loaded the application features and immediately before presenting the user with the initial application feature or the springboard.

This event does not correspond to a specific application delegate method. It is called after the adfmf-application.xml and adfmf-feature.xml files have loaded, just prior to hiding the splash screen.

stop

Called as the ADF Mobile application begins its shutdown.

This is called in the applicationWillTerminate: method on the application delegate.

activate

Called as the ADF Mobile application activates from being situated in the background.

This is called in the applicationDidBecomeActive: method on the application delegate.

deactivate

Called as the ADF Mobile application deactivates and moves into the background.

This is called in the applicationWillResignActive: method on the application delegate.

5.6.3 About Application Feature Lifecycle Listener Classes

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

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

The LifeCycle Events sample application provides an example of using the LifeCycleListener interface at the feature application level through the Feature1Handler.java and Feature2Handler.java files. These files are located within the view controller project's Application Sources folder.

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

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

Table 5-4 The activate and deactivate Events

Event

Timing

activate

Called immediately before the display of the application feature to end users.

deactivate

Called after the application feature has been hidden from the end user.

5.7 About the Mobile Feature Application Configuration File

The adfmf-feature.xml file, an example of which is illustrated in Example 5-15, enables you to configure the actual mobile application features that are referenced by the <adfmf:featureReference> element in the corresponding adfmf-application.xml file.

By defining the elements of the adfmf-feature.xml file, you set the behavior for the application features by, in turn, defining the child elements of the <Feature> element, the top-most element in the XML file under the root element, <adfmf:features>. The <Feature> element itself describes the basic information of the application feature, including its name, version, and whether or not it participates in security. For the latter, see Chapter 17, "ADF Mobile Application Security." The child elements of the <Feature> elements are listed in Table 5-5. Like the overview editor for the adfmf-application.xml descriptor file, you can update this file with these elements (or edit them) declaratively using the overview editor for the adfmf-feature.xml file, described in Section 5.8, "Setting the Basic Configuration for the Application Feature."

Table 5-5 Child Elements of <Feature> Element

Element

Description

<adfmf:content>

Describes how to implement the content of an application feature. The content of an application feature can be delivered as ADF Mobile AMX pages, locally stored HTML pages, or remotely served web applications. For more information on designating content as a web application, see Chapter 12, "Implementing Application Features as Remote URLs."

<adfmf:constraint>

Determines whether a given application feature can be displayed in the application runtime. Constraints can be used to allow or prevent the use of an application feature based on such criteria as user roles or device properties. For more information, see Chapter 14, "Setting Constraints."

5.8 Setting the Basic Configuration for the Application Feature

Each mobile application must have at least one application feature. Because each application feature can be developed independently from one another (and also from the mobile application itself), the overview editor for the adfmf-feature.xml file enables you to define the child elements of <adfmf:features> to differentiate the application features by assigning each a name, an ID, and setting how their content can be implemented. Using the overview editor for application features, you can also control the runtime display of the application feature within mobile application and designate when an application feature requires user authentication.

5.8.1 How to Define the Basic Information for the Application Feature

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

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

To set the basic information for the application feature:

Choose the General tab.

Click Add in the Features table.

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

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

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

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

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

Figure 5-20 Adding an Application Feature

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

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

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

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

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

5.9 Defining the Content Types for an Application Feature

Adding a child element to the <adfmf:content> element, shown in Example 5-16, enables you to define if the application feature is implemented as local HTML, remote URL, a Mobile ADF AMX file. You can implement each application feature as one or all of the content types.

5.9.1 How to Define the Application Content

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

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

Figure 5-21 Defining the Implementation of the Application Feature

Before you begin:

Each content type has its own prerequisites, as follows:

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

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

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

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

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

Click Content.

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

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

Remote URL

Local HTML

Define the content-specific parameters:

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

Figure 5-23 Selecting the Connection for the Hosted Application

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

Note:

This connection can only be created as an application resource.

Figure 5-24 Creating a URL Connection

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

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

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

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

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

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

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

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

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

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

Figure 5-30 ADF Mobile Audit Profiles

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

Figure 5-31 The External Resource Warning

5.10 Working with Resource Bundles

ADF Mobile uses the standard localization structures of ADF to specify English language text resources (although you can use any tool to generate resource bundle files in other languages). You can configure an ADF Mobile application to store translatable UI strings at both the application and project level, as described in the "Working with Resource Bundles" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. ADF Mobile uses only XLIFF (XML Localization Interchange File Format) files for localization, meaning that JDeveloper produces an .xlf file to store the strings. (Also, xliff Resource Bundle is the only available resource bundle type in the Resource Bundle Settings page for projects, shown in Figure 5-32. For more information on this page, see the online help for Oracle JDevelolper.)

Figure 5-32 The Project Properties Resource Bundle Page

At the application level, you can localize strings for such attributes as application names or preference page labels, which are listed in Table 5-6.

Table 5-6 Localizable ADF Mobile Application Attributes

Element

Attribute(s)

<adfmf:Application>

name

<adfmf:PreferenceGroup>

label

<adfmf:PreferencePage>

label

<adfmf:PreferenceBoolean>

label

<adfmf:PreferenceText>

label

<adfmf:PreferenceNumber>

label

<adfmf:PreferenceList>

label

<adfmf:PreferenceValue>

name

At the project (view controller) level, you can localize application feature-related attributes listed in Table 5-7.

Table 5-7 Localizable Application Feature Attributes

Element

Attribute

<adfmf:Feature>

name

<adfmf:Constraint>

value

<adfmf:Parameter>

value

<adfmf:PreferencePage>

label

<adfmf:PrefrenceGroup>

label

<adfmf:PreferenceBoolean>

label

<adfmf:PreferenceText>

label

<adfmf:PreferenceNumber>

label

<adfmf:PreferenceList>

label

<adfmf:PreferenceValue>

name

You can create resource bundles for attributes of such ADF Mobile AMX components as the text attribute of <amx:commandButton>. Table 5-8 lists these ADF Mobile AMX (amx) components. For more information see Section 8.7, "Localizing UI Components."

Table 5-8 Localizable Attributes of ADF Mobile AMX Components

Component

Attribute

<amx:inputDate>

label

<amx:inputNumberSlider>

label

<amx:panelLabelAndMessage>

label

<amx:selectBooleanCheckBox>

label

<amx:selectBooleanSwitch>

label

<amx:selectItem>

label

<amx:selectManyCheckBox>

label

<amx:selectManyChoice>

label

<amx:selectOneButton>

label

<amx:selectOneChoice>

label

<amx:selectOneRadio>

label

<amx:commandButton>

text

<amx:commandLink>

text

<amx:goLink>

text

<amx:inputText>

label, value, hintText

<amx:outputText>

value

5.10.1 How to Create Project-Level Resource Bundles

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

Figure 5-33 Localizing Feature Application Attributes

Before you begin:

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

To use strings in a resource bundle:

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

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

Figure 5-35 Select Resource Dialog

5.10.2 What Happens When You Add a Resource Bundle

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

Figure 5-36 The Application Resource Bundle

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

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

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

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

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

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

Figure 5-37 The Project-Level Resource Bundle

5.10.3 What You May Need to Know About Localizing Image Files

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

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

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

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

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

The file extension must be .xlf.

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

The file name is in the following format:

<BASE_XLIFF_FILE_NAME>_<LANGUAGE_TOKEN>.xlf

Where:

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

<LANGUAGE_TOKEN> is in the following format:

<ISO-639-lowercase-language-code>

Note:

ADF Mobile does not support countries or regions.

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

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

stringBundle_en.xlf

stringBundle_es.xlf

stringBundle_fr.xlf

5.10.5 Internationalization for iOS Applications

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

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

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

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

5.11 Skinning ADF Mobile Applications

ADF Mobile's use of CSS (Cascading Style Sheet) language-based skins ensures that all application components within an ADF Mobile application (including those used in its constituent application features) share a consistent look and feel. Changes that affect the presentation of an application can be made by creating or extending a skin rather than through re-configuring an ADF Mobile AMX or HTML component. Any changes made to a skin take effect when an application starts, because ADF Mobile applies skins at runtime.

As noted in Section 4.2.2, "What Happens When You Create an ADF Mobile Application," the artifacts resulting from the creation of an application controller project include two skinning-related files, adfmf-config.xml and adfmf-skins.xml. You use these files to control the skinning for the ADF Mobile application. The adfmf-config.xml file designates the default skin family used to render application components and the adfmf-skins.xml file enables you to customize the default skin family or define a new one.

5.11.1 About the adfmf-config.xml File

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

Example 5-22 The Default Skin, mobileFusionFX in the adfmf-config.xml File

The <skin-family> element does not support EL expressions. The <skin-version> element has only one value, 1.

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

Figure 5-39 The Skinning Hierarchy

5.11.2 About the adfmf-skins.xml File

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

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

Table 5-9 Child Elements of the <skin> Element

Elements

Description

<id>

Because ADF Mobile skinning customizes the default mobileFusionFx skin, the identifier syntax reflects the version of the operating system. This is a required element. To define this element in terms of mobileFusionFx, mobileFusionFx.iOS identifies a style sheet that renders components on the Apple iPad and the iPhone.

mobileFusionFx.iPad and mobileFusionFx.iPhone render exclusively to the iPad or iPhone, respectively.

<family>

Identifies the skin family. This is a required element.

<extends>

Use this element to customize the default skin, mobileFusionFx, to a specific device.

5.11.2.1 About the ADF Mobile Skin Identifiers

The skin identifier (<skin-id>) is identical to the <skin-family> element and can be appended with the operating system, such as iOS, iPhone, or iPad. ADF Mobile first searches for the skin identifier in the format of <skin-family>.<OS>, such as mobileFusionFx.iPad. If it cannot find the skin, it searches instead for a skin identifier of <skin-family> which falls back to the default skin family, mobileFusionFx. (This top-level skin is referenced by the <skin-id> which equals the <skin-family>). The <skin-family> must always be identified in the adfmf-config.xml file.

5.11.3 How to Change the Default Skin Family

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

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

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

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

Note:

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

Figure 5-41 The Create Cascading Style Sheet Dialog

Open the adfmf-skins.xml file.

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

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

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

id—Enter the identifier for the skin.

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

style-sheet-name—Retrieve the style sheet.

Figure 5-42 The Insert Skin Dialog

Click OK.

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

To add a new style sheet to a skin

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

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

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

Retrieve the location of the CSS file.

Figure 5-43 The Insert skin-addition Dialog

Click OK.

Caution:

Creating custom styles that use DOM-altering structures can cause ADF Mobile applications to hang. Specifically, the display property causes rendering problems in the HTML that is converted from ADF Mobile AMX. This property, which uses such values as table, table-row, and table-cell to convert components into a table, may result in table-related structures that are not contained within the appropriate parent table objects. Although this problem may not be visible within the application user interface itself, the logging console reports it through a Signal 10 exception.

5.11.4 Overriding the Default Skin Styles

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

5.11.4.1 How to Apply New Style Classes to an Application Feature

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

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

Figure 5-46 Selecting the CSS for the Application Feature

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

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

Figure 5-47 The Feature Content Dropdown Menu

5.11.5 What You May Need to Know About Skinning

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

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

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

5.12 Working with Feature Archive Files

The adfmf-application.xml file references at least one application feature. These application features, when packaged into a JAR file known as a Feature Archive file (FAR), provide the reusable content that can be consumed by other ADF Mobile applications. A FAR is essentially a self-contained collection of everything that an application feature requires, such as icon images, resource bundles, HTML, JavaScript, or other implementation-specific files. As described in Section 16.5, "Deploying Feature Archive Files (FARs)," the contents of a FAR includes a single adfmf-feature.xml file, which identifies each of the packaged application features by a unique ID. You can edit this file, as described in Section 5.7, "About the Mobile Feature Application Configuration File," to update such feature properties as content implementation (local or remote HTML files or ADF Mobile AMX pages) and display based on such factors as user roles and privileges or device properties. A mobile application can reference one FAR, several of them, or none at all.

5.12.1 How to Use FAR Content in an ADF Mobile Application

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

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

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

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

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

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

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

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

Tip:

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

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

Note:

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

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

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

Scripting on this page enhances content navigation, but does not change the content in any way.