20 Enabling User Preferences
This chapter includes the following sections:
20.1 Creating User Preference Pages for a Mobile Application
Preferences enable you to add settings that can be configured by end users.
Within both the maf-application.xml and maf-feature.xml files, the user preference pages are defined with the <adfmf:preferences> element. You also use the <adfmf:preferences> element to create the preferences that users manage within each application feature.
As shown in the following example, the child element of <adfmf:preferences> called <adfmf:preferenceGroup> and its child elements define the user preferences by creating pages that present options in various forms, such as text strings, dropdown menus, or in this case, as a child page that can present the user with additional options for application settings.
<?xml version="1.0" encoding="UTF-8" ?>
<adfmf:application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:adfmf="http://xmlns.oracle.com/adf/mf"
name="MobileApplication"
id="com.company.MobileApplication"
appControllerFolder="ApplicationController"
version="1"
vendor="oracle"
listener-class="application.LifeCycleListenerImpl">
<adfmf:description>This app created by Mobile Application Framework</adfmf:description>
<adfmf:featureReference id="PROD"/>
<adfmf:featureReference id="HCM"/>
<adfmf:featureReference id="Customers"/>
<adfmf:preferences>
<adfmf:preferenceGroup id="a" label="Prefs Group A">
<adfmf:preferenceBoolean id="a1_sound" label="Sound Effects"/>
<adfmf:preferenceNumber id="a2_retries" label="Retries" default="3"/>
<adfmf:preferenceList id="a3_background" label="Background" default="3">
<adfmf:preferenceValue name="None" value="0" id="pv4"/>
<adfmf:preferenceValue name="Field" value="1" id="pv1"/>
<adfmf:preferenceValue name="Galaxy" value="2" id="pv5"/>
<adfmf:preferenceValue name="Mountain" value="3" id="pv6"/>
</adfmf:preferenceList>
<adfmf:preferenceText id="a4_name" label="Default Name"/>
<adfmf:preferencePage id="aa" label="Prefs SubGroup AA">
<adfmf:preferenceGroup id="aa_sec" label="Security">
<adfmf:preferenceBoolean id="aa_sec_useSec" label="Use Security"/>
<adfmf:preferenceNumber id="aa_sec_timeout" label="Timeout (secs)" default="120"/>
</adfmf:preferenceGroup>
</adfmf:preferencePage>
</adfmf:preferenceGroup>
<adfmf:preferenceGroup id="b" label="Prefs Group B">
<adfmf:preferenceBoolean id="b_cloudSync" label="Cloud Sync"/>
<adfmf:preferenceList id="b_dispUsage" label="Display Usage As" default="1">
<adfmf:preferenceValue name="Percent" value="1" id="pv2"/>
<adfmf:preferenceValue name="Minutes" value="2" id="pv3"/>
</adfmf:preferenceList>
</adfmf:preferenceGroup>
</adfmf:preferences>
</adfmf:application>
Preference pages are defined within the <adfmf:preferenceGroup> element and have the following child elements:
-
<adfmf:preferencePage>—Specifies a new page in the user interface. -
<adfmf:preferenceList>—Provides users with a specific set of options.-
<adfmf:preferenceValue>—A child element that defines a list element.
-
-
<adfmf:preferenceBoolean>—A boolean setting. -
<adfmf:preferenceText>—A text preference setting.
See Oracle® Fusion Middleware Tag Reference for Oracle Mobile Application Framework for information on these elements and their attributes.
For an example of creating preference pages at both the application and application-feature levels, refer to the PrefDemo sample application. This sample application is available from File > New > MAF Examples.
The PrefDemo application is comprised of an application-level settings page as well as three application feature preference pages, which are implemented as MAF AMX. Figure 20-2 shows the PrefDemo application settings page, which you invoke from the general settings page. In this illustration, the preference settings page is invoked from the iOS Settings application.
Figure 20-2 The PrefDemo Application Settings Page
Description of "Figure 20-2 The PrefDemo Application Settings Page"
The application feature preference pages, illustrated by App, Feature1 (which is selected), and Feature 2 in figure below, provide examples of preferences pages constructed from the MAF AMX Boolean Switch, Input Text, and Output Text components that use EL (Expression Language) to access the application feature and the various <adfmf:preferences> components configured within it. See Using EL Expressions to Retrieve Stored Values for User Preference Pages.
Figure 20-3 An Application Feature Preference Page from the PrefDemo Application
Description of "Figure 20-3 An Application Feature Preference Page from the PrefDemo Application"
In the PrefDemo application, each MAF AMX preference page is referenced by a single bounded task flow comprised of a view activity and a control flow case that enables the page refresh.
20.1.1 How to Create Mobile Application-Level Preferences Pages
The Preferences section of the MAF Application Feature Editor, enables you to build sets of application-level preference pages by nesting the child preference page elements within <adfmf:preferenceGroup>.
The section presents the <adfmf:preferenceGroup> and its child elements as similarly named options (such as Preference Page, Preference List, Boolean Preference, and so on), which you assemble into a hierarchy (or tree) shown in figure.
Figure 20-4 Adding Mobile Application-Level Preferences Using the Preference Page
Description of "Figure 20-4 Adding Mobile Application-Level Preferences Using the Preference Page"
To ensure that the maf-application.xml file is well-formed, use the MAF Application Editor, shown in figure above, to construct the user preferences pages. This ensures that you can only select an element that can have the appropriate parent, child, or sibling relationship to a selected preferences element. For example, figure below shows only the components that can be inserted within the Preference Group element, MyMobile. The editor also enables you to enter the values for the attributes specific to each preference element.
To create preferences pages:
- Enter the following information for the new preference group, shown in figure.
Figure 20-6 Defining the Parent Preference Group Element
Description of "Figure 20-6 Defining the Parent Preference Group Element"-
Enter a unique identifier for the Preference Group id element.
-
Enter the descriptive text that displays in the user interface. For an example of how this text displays in the user interface, see Samples in Figure 20-1.
Note:
If a preference ID has a character that is considered an illegal identifier in EL, OEPE displays a warning because the runtime cannot support it properly. There is no problem unless a feature content page attempts to reference the preference using EL.
-
20.1.1.1 How to Create a New User Preference Page
The Preference Page component enables you to create a new user interface page.
Before you begin
You must create a Preferences Group element.
To create a new user preference page:
- Right-click and choose New > Preference Page, as shown in figure.
Figure 20-7 Selecting the Preference Page Component
Description of "Figure 20-7 Selecting the Preference Page Component" - Define the following Preference Page attributes in the Insert Preference Page dialog, shown in figure:
-
Enter a unique identifier for the Preference Page element.
-
Enter the descriptive text that displays in the user interface.
-
20.1.1.2 What Happens When You Add a Preference Page
After you define the Preference Page and its child Preference Group components in the overview editor, OEPE generates an <adfmf:preferencePage> with attributes similar to the example below. The <adfmf:preferencePage> is nested within a parent <adfmf:preferenceGroup> element.
This example shows how to add an <adfmf:PreferencePage> element.]]
<adfmf:preferences>
<adfmf:preferenceGroup id="gen"
label="MobileApp">
<adfmf:preferencePage id="application_version"
label="Version">
<adfmf:preferenceGroup id="version_select"
label="Select Your Version">
<adfmf:preferenceList id="edition"
label="Edition"
default="PERSONAL">
adfmf:preferenceValue name="Enterprise"
id="pv2"/>
<adfmf:preferenceValue name="Personal"
value="PERSONAL"
id="pv1"/>
</adfmf:preferenceList>
</adfmf:preferenceGroup>
</adfmf:preferencePage>
</adfmf:preferences>
20.1.1.3 How to Create User Preference Lists
Add a Preference List component to create a list of options.
Before you begin
You must create Preference Group as the parent to the Preference List or any other list-related component.
To create a user preference list:
- Select a Preference Group or Preference Page and then click Add, then Insert Inside, and then Preference List.
Figure 20-9 Adding a Preference List Component to a Preference Group
Description of "Figure 20-9 Adding a Preference List Component to a Preference Group" - Define the following attributes using for the List Preference, shown in figure below.
-
Enter a unique identifier.
-
Enter the descriptive text that displays in the user interface.
-
- Now you can define the values of the list. Enter the Id, Value and Label, as shown in figure below.
You can present the user with a default setting by selecting Default. As illustrated in the example in the previous section, the default status is defined within the
<adfmf:preferenceList>element asdefault="ENTERPRISE".
20.1.1.4 What Happens When You Create a Preference List
After you add Preference List component to a Preference Group and then define a series of Preference Values, OEPE updates the <adfmf:preferences> section with an <adfmf:preferenceList> element, as shown in What Happens When You Add a Preference Page.
20.1.1.5 How to Create a Boolean Preference List
See the example in Creating User Preference Pages for a Mobile Application.
Before you begin
Because an <adfmf:preferenceBoolean> element must be nested within an <adfmf:preferenceGroup> element, you must first insert a Preference Group component to the hierarchy.
To create a boolean preference list:
- Select a Preference Group element, such as GPS Settings as shown in figure.
Figure 20-12 Adding a Boolean Preference to a Preference Group
Description of "Figure 20-12 Adding a Boolean Preference to a Preference Group" - Right-click and choose New > Boolean Preference.
Define the following attributes in the figure below, and then click OK.
-
Enter a unique identifier.
-
Enter the descriptive text that displays in the user interface.
Figure 20-13 Inserting a Boolean Preference
Description of "Figure 20-13 Inserting a Boolean Preference" -
20.1.1.6 What Happens When You Add a Boolean Preference
When you add a Boolean Preference and designate its default value, OEPE updates the <adfmf:preferences> section of the maf-application.xml file with a <adfmf:preferenceBoolean> element, as illustrated in the example below.
<adfmf:preferencePage id="gps_tracking"
label="Your_GPS_Locations">
<adfmf:preferenceGroup id="gps"
label="GPS Settings">
<adfmf:preferenceBoolean id="track_gps"
label="Automatically Track Location"
default="true"/>
</adfmf:preferencePage>
20.1.1.7 How to Add a Text Preference
Use the insert options, shown in figure, to create a Text Preference, a dialog that enables users to store information or view default text.
Before you begin
Create a Preference Group element.
To create a text preference:
- Enter the following information into the Insert Text Preference dialog, shown in the figure below, and then click OK.
-
Enter a unique identifier.
-
Enter the descriptive text that displays in the user interface.
-
Enter the default text value.
Figure 20-15 The Insert Text Preference Dialog
Description of "Figure 20-15 The Insert Text Preference Dialog" -
20.1.1.8 What Happens When You Define a Text Preference
When you add a Text Preference and designate its default value, OEPE updates the <adfmf:preferences> section of the maf-application.xml file with a <adfmf:preferenceText> element, as illustrated in the example below.
<adfmf:preferenceGroup id="security" label="Security">
<adfmf:preferenceText id="serviceURL"
label="Security URL"
default="http://security.example.com/provider"/>
<adfmf:preferenceText id="username"
label="User Name"/>
<adfmf:preferenceText id="password"
label="Password"
secret="true"/>
</adfmf:preferenceGroup>
The Preference Group elements that define a security URL, user name, and password preference setting display similarly as shown in figure.
The figure above illustrates <adfmf:preferenceText> elements with a seeded value for the Security URL and an input value for the User Name. Because the MAF preferences are integrated with the iOS Settings application, the secret="true" attribute for the Password input text results in the application following the iOS convention of obscuring the user input with bullet points. See the description for the isSecure text field element in Settings Application Schema Reference, available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/) and Platform-Dependent Display Differences.
20.1.2 What Happens When You Create an Application-Level Preference Page
After you deploy the mobile application, the application-wide preference settings page is propagated to the device's global settings application, such as the Settings application on iOS-powered devices. See Converting Preferences for Deployment.
20.2 Creating User Preference Pages for Application Features
You can distribute an application feature independently of its mobile application by adding a Feature Application Archive (FAR) .jar file containing the application feature to the library of another mobile application.
You then reference the application feature in the application's maf-application.xml file. If an application feature requires a specific set of user preferences in addition to the general preferences defined for the consuming application, you can define them using the Preferences tab of the MAF Feature Editor, shown in figure. You build application feature preferences in the same manner as the application-level preferences, which are described in Creating User Preference Pages for a Mobile Application. After you define the preferences in the MAF Feature Editor, you then create the actual preference page by creating an application feature that references a MAF AMX page that is embedded with the Boolean Switch, Input, and Output components described in Creating and Using UI Components.
Figure 20-17 Setting Application Feature-Level Preferences
Description of "Figure 20-17 Setting Application Feature-Level Preferences"
20.3 Using EL Expressions to Retrieve Stored Values for User Preference Pages
When creating an application feature-level preference page, you add EL expressions to the MAF AMX components, such as the Input Text component in the example later in this section.
To create a feature-level preference page:
- Open the AMX Editor for the page.
- Select the XML element (for example,
<amx:inputTest ...>in the example below]. - Open the Properties pane.
- Select the Common tab in the Properties pane.
- Click the Binding button on the Value attribute. This opens the OEPE EL expression builder.
This example shows how to reference preference values using EL in AMX components.
<amx:inputText label="Number" id="it1" inputType="number"
value="#{preferenceScope.feature.Feature1.f1top.f1Number}"/>
As illustrated in the example above, EL expressions use the preferenceScope object to enable applications to access an application feature-level preference. These EL expressions are in the following format:
preferenceScope.feature.feature-id.group-id.property-id
The figure below illustrates using the Expression Builder to create the EL expression.The preference itself is designated by the IDs configured for various components in maf-feature.xml, such as the ID of the application feature <adfmf:feature id="Feature1">), the ID of a Preference Group (<adfmf:preferenceGroup id="f1top">), and the ID of a preference property (<adfmf:preferenceNumber id="f1Number">).
The EL expression may include zero or more group-id and property-id elements.
Figure 20-18 Building an EL Expression for a Preference
Description of "Figure 20-18 Building an EL Expression for a Preference"
20.3.1 What You May Need to Know About preferenceScope
An EL expression has the following resolution pattern:
-
From the JavaScript layer, EL value expressions are resolved using the following JavaScript function:
adf.mf.el.getValue(expression, success, failed)
The resolution of
adf.mf.el.getValuebegins with an attempt to resolve the expression locally using the JS-EL parser and JavaScript Context Cache. If the expression cannot be resolved locally, the expression is passed to the embedded Java layer for evaluation where it is resolved by the Java EL parser. This is done through theGenericInvokeRequestto the Model'sgetValuemethod. -
At the Java layer, an EL value expression is resolved using the following approach:
String val = AdfmfJavaUtilities.evaluateELExpression("#{preferenceScope.feature.f0.vendor}");For a
setValuemethod, the expression is resolved as follows:ValueExpression ve = AdfmfJavaUtilities.getValueExpression("#{preferenceScope.feature.f0.vendor}"); ve.setValue(AdfmfJavaUtilities.getADFELContext(), value);Evaluation of the EL expression involves looking up the
preferenceScopeobject. The evaluation is from left to right, where each token is resolved independently. After a token is resolved, it is used to resolve the next token (which is on its right).
Preferences cannot be exposed without the preferenceScope object. For information about the preferenceScope object, see About the Mobile Application Framework Objects Category.
20.3.2 Reading Preference Values in iOS Native Views
MAF integrates APIs provided for a native UI (such as UIView or UIViewController) to allow certain configurations on iOS platform.
When the native UI is initialized, an instance of the ADFSession object becomes available. You can use its getPreferences method to instruct MAF to provide a listing of the available preferences for the application as defined in the maf-application.xml file. As shown in the next example, this method returns a NSArray* of preference property objects that can include the id, value, and label for the preference. This API call ensures that either the end user provided the value for a particular preference, or that the default value of the preference is returned.
This example shows how to get preferences.
//...
-(id) initWithADFSession:(id<ADFSession>) providedSession
{
id me = [self init];
session = providedSession;
//...
// Dump the preferences to the data display
NSArray* prefsArray = [session getPreferences];
NSString* prefs = [prefsArray JSONRepresentation];
self.theData.text = [[NSString alloc ] initWithFormat:
:@"%@\nUser Preferences = --> %@ <--", self.theData.text, prefs];
//...
return me;
}
20.4 Platform-Dependent Display Differences
The MAF preference pages maintain the native look-and-feel for both the iOS and Android platforms.
Consequently, the MAF preference pages display differently on the two platforms. As shown in the table below, preferences display inline on the iOS platform, meaning that the system does not invoke dialog pages. With a few exceptions, the Android platform presents these components as dialogs.
Table 20-1 Preference Component Comparison by Platform
| Component | iOS | iOS Display Examples | Android | Android Display Examples |
|---|---|---|---|---|
|
Preference Groups (Category Selection) |
The iOS platform displays the preference elements within their parent preference group. |
The Android platform displays the preference elements within their parent preference group. |
 |
|
|
Boolean Preference List |
The Boolean preference is represented as value pair, such as on and off. |
 |
Android presents the Boolean preference as a check box. |
 |
|
Text Preference |
iOS displays the text inline. |
 |
Android displays the default text within an input field. |
 |
|
Text Preference (as secret input text) |
On iOS platforms, users enter text inline, with each character obscured by a bullet point after it has been entered. See What Happens When You Define a Text Preference. |
 |
Android launches an input text dialog and obscures each character with a bullet point after it has been entered. |
 |
|
Single Item Selection List (from a Preference List) |
iOS platforms display the single item selection list in a separate preferences page. |
 |
Android displays the single item selection list in a dialog. |
 |
|
Preference Page |
iOS launches a child preference page from a preference group. |
 |
Android launches a child preference page from a preference group. |
 |
Although iOS and Android platforms have a Settings application, only the iOS platform supports integrating application-level preferences into the Settings application, as shown by the preferences in Figure 20-19.
Figure 20-19 Oracle Mobile Preferences in the iOS Settings Application
Description of "Figure 20-19 Oracle Mobile Preferences in the iOS Settings Application"
On Android-powered devices, users access application-specific preferences pages similar to the one shown in the figure below only when the application is running.
Figure 20-20 The Preferences Menu on an Android-Powered Device
Description of "Figure 20-20 The Preferences Menu on an Android-Powered Device"