1. Developing Mobile Applications with Oracle Mobile Application Framework
  2. Converting Preferences for Deployment

D Converting Preferences for Deployment

This chapter describes how MAF converts user preferences during deployment.

This document includes the following sections:

Naming Patterns for Preferences

Conversion of MAF application preferences to a mobile-platform representation occurs when a deployment target is invoked.

Following conversion, the naming pattern described in table ensures that each preference can be uniquely identified on the mobile platform. Each preference element in the maf-application.xml and maf-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 describes how to generate fully qualified preference identifiers.

Table D-1 MAF Naming Patterns for Preferences

Expression Description Syntax

PreferenceIdentifier

Represents an identifier value of a preference element that has been converted to a mobile platform representation.

ApplicationPreferences | FeaturePreferences

ApplicationPreferences

Use this expression to build a preference identifier value that is generated from the maf-application.xml file.

application.ApplicationElementPath

ApplicationElementPath represents a dot-separated list of id attribute values beginning with the top-most parent element, <adfmf:preferences>, and ending with the element that is to be identified. In the following segment from the maf-application.xml file, this generated identifier is shown in the comment as application.gen.gps.trackGPS. 

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

FeaturePreferences

Use this expression to build a preference identifier value that is generated from the maf-feature.xml file.

feature.FeatureElementPath

FeatureElementPath represents a dot-separated list of id attribute values beginning with <adfmf:feature>, the top-most parent element, and ending with the element that is to be identified. In the following segment from the maf-feature.xml file, this generated identifier is displayed in the comment as feature.f0.gen.gps.trackGPS. 

<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 D-1 does not have an id attribute and is therefore not represented in any preference identifiers.

Converting Preferences for Android

The MAF deployment uses XML and XLS to transform the user preference pages defined at both the application feature and application-level into the following three XML documents.

The three documents are:

  • maf_preferences.xml

  • maf_arrays.xml

  • maf_strings.xml

maf_preferences.xml

This file contains the transformed preferences from both of the maf-feature.xml and maf-application.xml files.

Preferences Element Mapping

Table shows the mapping of MAF's preference definitions to Android template preferences, and Android native preferences:

Table D-2 Mapping MAF Preferences to Android Preferences

MAF Preference Definition Custom or Android Native Preference Definition (Used by MAF Deployment) Android Native Preference Definition (Not used by MAF Deployment)

<adfmf:preferenceBoolean>

oracle.adfmf.preferences.AdfMFPreferenceBoolean

CheckBoxPreference

<adfmf:preferenceNumber>

oracle.adfmf.preferences.AdfMFPreferenceText

EditPreferenceText

<adfmf:preferenceText>

oracle.adfmf.preferences.AdfMFPreferenceText

EditTextPreference

<adfdmf:preferenceList>

oracle.adfmf.preferences.AdfMFPreferenceList

ListPreference

<adfmf:PreferenceGroup>

PreferenceCategory

PreferenceCategory

<adfmf:PreferencePage>

PreferenceScreen

PreferenceScreen
Preference Attribute Mapping

The maf_preferences.xml file contains references to string resources contained in both the maf_strings.xml and maf_arrays.xml files. 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 Naming Patterns for Preferences for the definition of <PreferenceIdentifier>.

Table D-3 and Table D-4 show the mapping of MAF attributes for a given MAF preference to the Android preference.

In this table:

  • Entries of the form {X} (such as {default} in the table below) indicate the value of a MAF attribute named X.

  • Entries having <PreferenceIdentifier> indicate the value of the preference identifier, as defined in Naming Patterns for Preferences.

  • Attributes with an asterisk (*) are custom template attributes defined in a MAF namespace and must appear in the maf_preferences.xml file in the form adfmf:<attributeName>. Otherwise, the attributes are part of the Android namespace and must appear in the maf_preferences.xml file as android:<attributeName>.

Table D-3 Mapping of MAF Preference Attributes to Android Preferences

MAF Attribute Definition Template Custom or Android Native Preference Attribute Android Attribute Value Applies to

id

key

<PreferenceIdentifier>

AdfMFPreferenceBoolean, AdfMFPreferenceText, AdfMFPreferenceList, PreferenceScreen, PreferenceCategory

default

defaultValue

{default}

AdfMFPreferenceBoolean, AdfMFPreferenceText, AdfMFPreferenceList

label

title

@string/<PreferenceIdentifier>___title if the given {label} value is not a reference to a string resource bundle. References a string in maf_strings.xml having the given {label}.

AdfMFPreferenceBooleanAdfM, FPreferenceNumber, AdfMFPreferenceText, AdfMFPreferenceList, PreferenceScreen, PreferenceCategory

secret

password

{secret}

AdfMFPreferenceText

min

min*

{min}

AdfMFPreferenceText

max

max*

{max}

AdfMFPreferenceText

name

entryValues

@array/<PreferenceIdentifier>___entryValues

AdfMFPreferenceList

value

entries

@array/<PreferenceIdentifier>___entries

AdfMFPreferenceList
Attribute Default Values

The overview editors for the maf-application.xml and maf-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 MAF 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 indicates what the deployment will specify for the android:defaultValue attribute if the MAF preference being transformed does not contain a default attribute:

Table D-4 Transforming Attributes with Non-Default Values

MAF Preference Element Android Preference Equivalent Default Attribute Value

preferenceBoolean

AdfMFPreferenceBoolean

false

preferenceText

AdfMFPreferenceText

Empty string

preferenceList

AdfMFPreferenceList

Empty string
Preferences Screen Root Element

The maf_preferences.xml file has a root element called <PreferenceScreen>. The Android template requires that this element have the following XML namespace definition:

xmlns:adfmf="http://schemas.android.com/apk/res/<Application Package Name>

The <Application Package Name> element is defined as the same application package name in the AndroidManifest.xml file. <Android Package Name> defines the definition for the Android package name specified in the AndroidManifest.xml file. See Setting Display Properties for a MAF Application .

The deployment uses the Package Name 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 maf-application.xml file. The deployment Java code will pass the value to the XSL document as a parameter.

The following example shows MAF preferences contained in the maf-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>

maf_arrays.xml

The maf_arrays.xml file consists of string-array elements that enumerate the names and values of list preferences that are referenced from the maf_preferences.xml file. Each <preferenceList> element contained in the maf-application.xml and maf-feature.xml files is transformed into two string-array elements, one element for the name and one element for the values. The following example shows a MAF preferenceList definition. 

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

The following example illustrates the pair of string array elements in the maf_arrays.xml file that are transformed from a <preferenceList> element. The MAF preferenceList definition in the preceding example results in <string-array name="feature.oracle.hello.prefGroup.MyList___entry_values"> and <string-array name="feature.oracle.hello.prefGroup.MyList___entries"> in the maf_arrays.xml file shown in the following example. 

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

The following example shows the <string-arrays> referenced in maf_preferences.xml. 

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

maf_strings.xml

The maf_strings.xml file, shown in the following example, consists of string elements that are referenced by the maf_preferences.xml file, as well as any resource bundle references defined in the maf-application.xml and maf-feature.xml files. Each string element has a name attribute that uniquely identifies the string and the string value. 

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

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

Converting Preferences for iOS

MAF can convert the MAF Preference elements to the respective iOS counterparts.

The MAF deployment transforms the MAF preferences listed in Table D-4 to the preference list (.plist) file representation required by an iOS Settings application.

Table D-5 MAF Preferences and Their iOS Counterparts

MAF Preferences Component iOS Representation

<adfmf:preferencePage>

PSChildPaneSpecifier

<adfmf:preferenceGroup>

PSGroupSpecifier

<adfmf:preferenceBoolean>

PSToggleSwitchSpecifier

<adfmf:preferenceList>

PSMultiValueSpecifier

<adfmf:preferenceText>

PSTextFieldSpecifier

<adfmf:preferenceNumber>

PSTextFieldSpecifier

For information on the iOS requirement for preference list (.plist ) files, see Preferences and Settings Programming Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

The following example shows XML of MAF preferences based on the maf-application.xml file. 

<adfmf:preferences>
   <adfmf:preferenceGroup id="gen"
                          label="Oracle Way Cool Mobile App">
      <adfmf:preferenceGroup id="SubPage01"
                             label="Child Page">
   </adfmf:preferenceGroup>
</adfmf:preferences>

Converting Preferences for Windows

Provides information on preferences for the Windows platform.

For the Windows platform, from the maf-feature.xml and maf-application.xml metadata, MAF generates a single maf-preferences.json file and multiple maf-preferences.resjson files, one each for every supported locale in the application. MAF uses the JSON file, saves it as Windows settings for the application, and also uses it to display the settings screen.