This appendix describes how ADF Mobile converts user preferences during deployment.
This document includes the following sections:
Conversion of ADF Mobile application preferences to a mobile-platform representation occurs when a deployment target is invoked. Following conversion, the naming pattern described in Table B-1 ensures that each preference can be uniquely identified on the mobile platform. Each preference element in the adfmf-application.xml
and adfmf-feature.xml
files must be uniquely identified within the scope of its sibling elements prior to deployment.
The following are examples of identifier values:
application.gen.gps.trackGPS
feature.f0.gen.gps.trackGPS
Table B-1 describes how to generate fully qualified preference identifiers.
Table B-1 ADF Mobile Naming Patterns for Preferences
Expression | Description | Syntax |
---|---|---|
|
Represents an identifier value of a preference element that has been converted to a mobile platform representation. |
|
|
Use this expression to build a preference identifier value that is generated from the |
<adfmf:preferences> <adfmf:preferenceGroup id="gen"> <adfmf:preferenceGroup id="gps"> <!-- The mobile-platform identifier would be "application.gen.gps.trackGPS" --> <adfmf:preferenceBoolean id="trackGPS"/> </adfmf:preferenceGroup> </adfmf:preferenceGroup> </adfmf:preferences> |
|
Use this expression to build a preference identifier value that is generated from the |
<adfmf:feature id="f0"> <adfmf:preferences> <adfmf:preferenceGroup id="gen"> <adfmf:preferenceGroup id="gps"> <!-- The mobile-platform identifier would be "feature.f0.gen.gps.trackGPS" --> <adfmf:preferenceBoolean id="trackGPS"/> </adfmf:preferenceGroup> </adfmf:preferenceGroup> </adfmf:preferences> </adfmf:feature> |
The <adfmf:preferences>
element cited in the code examples in Table B-1 does not have an id
attribute and is therefore not represented in any preference identifiers.
The ADF Mobile deployment uses XML and XLS to transform the user preference pages defined at both the application feature and ADF Mobile application-level into the following three XML documents:
preferences.xml
arrays.xml
strings.xml
This file contains the transformed preferences from both of the adfmf-feature.xml
and adfmf-application.xml
files.
Table B-2 shows the mapping of ADF Mobile's preference definitions to Android template preferences, and Android native preferences:
Table B-2 Mapping ADF Mobile Preferences to Android Preferences
ADF Mobile Preference Definition | Template Custom or Android Native Preference Definition (Used by Deployment) | Android Native Preference Definition (Not used by Deployment) |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The Preferences.xml
file contains references to string resources contained in both strings.xml
and arrays.xml
. The Android SDK defines the syntax for resources in XML files as @[<package_name>:]<resource_type>/<resource_name>. This file contains references to string values as well as the name and value pairs of list preferences. The XSL constructs the following for the strings and list preferences:
<package_name>
is the name of the package in which the resource is located (not required when referencing resources from the same package). This component of the reference will not be used.
<resource_type>
is the R subclass for the resource type. This component will have a value of string
if constructing a string reference or array
if constructing a list preference.
<resource_name>
is the android:name
attribute value in the XML element. The value for this component will be the value of the <PreferenceIdentifier>_title
when specifying the android:title
attribute (see Section B.1, "Naming Patterns for Preferences." for the definition of <PreferenceIdentifier>
.
Table B-3 and Table B-4 show the mapping of ADF Mobile attributes for a given ADF Mobile preference to the Android preference.
In this table:
Entries of the form {X} (such as {default}
in Table B-3) indicate the value of an ADF Mobile attribute named X.
Entries having <PreferenceIdentifier>
indicate the value of the preference identifier, as defined in Section B.1, "Naming Patterns for Preferences."
Attributes with an asterisk (*) are custom template attributes defined in an ADF Mobile namespace and must appear in the preferences.xml
in the form adfmf:<attributeName>
. Otherwise, the attributes are part of the Android namespace and must appear in the preferences.xml
as android:<attributeName>
.
Table B-3 Mapping of ADF Mobile Preference Attributes to Android Preferences
ADF Mobile Attribute Definition | Template Custom or Android Native Preference Attribute | Android Attribute Value | Applies to |
---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The overview editors for the adfmf-application.xml
and adfmf-feature.xml
files exclude an attribute name and value from the XML if:
The attribute type is xsd:boolean
.
The attribute value has a <default>
value option.
The user specifies <default>
as the value.
The XSL must know the ADF Mobile attributes that are boolean typed and their corresponding default values. The XSL, then, specifies the appropriate Android or template custom attribute value where has been selected by the user.
Table B-4 indicates what the deployment will specify for the android:defaultValue
attribute if the ADF Mobile preference being transformed does not contain a default
attribute:
The preferences.xml
has a root element called <PreferenceScreen>
element. The Android template requires that this element have the following XML namespace definition:
xmlns:adfmf="http://schemas.android.com/apk/res/<Application Package Name>
where <Application Package Name>
is the same application package name put in the AndroidManifest.xml
file. <Android Package Name>
defines the definition for the Android package name specified in the AndroidManifest.xml
. For more information, see Section 5.3.1, "How to Set the ID and Display Behavior for a Mobile Application."
The deployment uses the Application Bundle Id value from the Android deployment profile, if it exists. If it does not exist in the profile, the deployment obtains this value from the application display name and Application Id contained in the adfmf-application.xml
file. The deployment Java code will pass the value to the XSL document as a parameter.
Example B-1 shows ADF Mobile preferences contained in the adfmf-feature.xml
file. Example B-1 shows the corresponding preferences.xml
file.
Example B-1 Preferences Defined in the adfmf-feature.xml File
<?xml version="1.0" encoding="UTF-8" ?> <adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance xmlns:adfmf="http://xmlns.oracle.com/jdev/adfmf"> <adfmf:feature id="oracle.hello" name="Hello" icon="oracle.hello/navbar-icon.png" image="oracle.hello/springboard-icon.png"> <adfmf:content id="Hello.Generic"> <adfmf:localHTML url="oracle.hello/index.html"/> </adfmf:content> <adfmf:preferences> <adfmf:preferenceGroup id="prefGroup" label="preference group"> <adfmf:preferenceBoolean id="boolPref" label="boolPref perference" default="true"/> <adfmf:preferenceNumber id="numPref" label="numPref preference" default="1" min="1" max="10"/> <adfmf:preferenceText id="textPref" label="textPref preferences" default="Foo"/> <adfmf:preferenceList id="listPref" label="listPref preference" default="value2"> <adfmf:preferenceValue name="name1" value="value1"/> <adfmf:preferenceValue name="name2" value="value2"/> </adfmf:preferenceList> </adfmf:preferenceGroup> </adfmf:preferences> </adfmf:feature> </adfmf:features>
This file consists of string-array elements that enumerate the names and values of list preferences that are referenced from the preferences.xml
file. Each <preferenceList>
contained in the adfmf-application.xml
and adfmf-feature.xml
files will be transformed into two string-array elements, one for the name and one for the values. For example, an ADF Mobile preferenceList
definition described in Example B-2 results in <string-array name="feature.oracle.hello.prefGroup.MyList___entry_values">
and <string-array name="feature.oracle.hello.prefGroup.MyList___entries">
in the arrays.xml
file shown in Example B-3
Example B-2 PreferenceList Definition in the adfmf-feature.xml File
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adfmf="http://xmlns.oracle.com/jdev/adfmf"> <adfmf:feature id="oracle.hello" name="Hello" icon="oracle.hello/navbar-icon.png" image="oracle.hello/springboard-icon.png"> ... <adfmf:preferences> <adfmf:preferenceGroup id="prefGroup"> <adfmf:preferenceList id="MyList" label="My List"> <adfmf:preferenceValue name="name1" value="value1"/> <adfmf:preferenceValue name="name2" value="value2"/> <adfmf:preferenceValue name="name3" value="value3"/> </adfmf:preferenceList> </adfmf:preferenceGroup> </adfmf:preferences> </adfmf:feature> ...
Example B-3 Preference Lists Converted to <string-array> Elements in arrays.xml
<resources xmlns:android="http://schemas.android.com/apk/res/android" xmlns:adfmf="http://schemas.android.com/apk/res/oracle.myandroidapp"> <string-array name="feature_oracle_hello_prefGroup.MyList___entry_values"> <item>name1</item> <item>name2</item> <item>name3</item> </string-array> <string-array name="feature_oracle_hello_prefGroup.MyList___entries"> <item>value1</item> <item>value2</item> <item>value3</item> </string-array> </resources>
Example B-4 shows the <string-arrays>
referenced in preferences.xml
.
Example B-4 PreferenceList Reference from the preferences.xml File
<oracle.adfmf.preferences.AdfMFPreferenceList android:key="feature.oracle.hello.MyList" android:title="@string/feature_oracle_hello_prefGroup.MyList___title" android:entries="@array/feature_oracle_hello_prefGroup.MyList___entries" android:entryValues="@array/feature_oracle_hello_prefGroup.MyList___entry_values" />
The strings.xml
file, shown in Example B-5, consists of string elements that are referenced by the preferences.xml
file, as well as any resource bundle references defined in the adfmf-application.xml
and adfmf-feature.xml
files. Each string element has a name
attribute that uniquely identifies the string and the string value.
Example B-5 The strings.xml File
<resources xmlns:android="http://schemas.android.com/apk/res/android" xmlns:adfmf="http://schemas.android.com/apk/res/oracle.myandroidapp"> ... <string name="feature.PROD.bundle.FeatureName">Products</string> <string name="feature.oracle.hello.prefGroup.MyBooleanPreference___title">My feature boolean pref</string> ... </resources>
If the source of the string is not a reference to a resource bundle string, the naming convention for the name
attribute is <PreferenceIdentifier>___<androidAttributeName>
.
Example B-6 Resource Bundle References Defined in the adfmf-feature.xml File
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adfmf="http://xmlns.oracle.com/jdev/adfmf"> <adfmf:loadBundle basename="mobile.ViewControllerBundle" var="bundle"/> <adfmf:feature id="oracle.hello" name="Hello" icon="oracle.hello/navbar-icon.png" image="oracle.hello/springboard-icon.png"> <adfmf:feature id="PROD" name="#{bundle.FeatureName}" icon="openMore.png" image="G.png" credentials="none"> ... <adfmf:preferences> <adfmf:preferenceGroup id="prefGroup"> <adfmf:preferenceBoolean default="true" id="MyBooleanPreference" label="My feature boolean pref"/> </adfmf:preferenceGroup> </adfmf:preferences> </adfmf:feature>
The iOS deployer transforms the ADF Mobile preferences listed in Table B-4 to the preference list (.plist
) file representation required by an iOS Settings application.
Table B-5 ADF Mobile Preferences and Their iOS Counterparts
ADF Mobile Preferences Component | iOS Representation |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
For information on the iOS requirement for preference list (.plist
) files, see the "Implementing Application Preferences" section in iOS Application Programming Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
).
Example B-7 shows an ADF Mobile preferences stanza.