D デプロイメントでのプリファレンスの変換

この付録では、デプロイメント時、MAFがどのようにユーザー・プリファレンスを変換するかについて説明します。

このドキュメントには次の項が含まれます。

第D.1項「プリファレンスのネーミング・パターン」
第D.2項「Android用のプリファレンスの変換」
第D.3項「iOS用のプリファレンスの変換」

D.1 プリファレンスのネーミング・パターン

デプロイメント・ターゲットが呼び出されると、モバイル・アプリケーション・プリファレンスの、モバイル・プラットフォーム表現への変換が行われます。変換後、表D-1で説明されているネーミング・パターンにより、モバイル・プラットフォーム上で各プリファレンスを一意に識別できるようになります。maf-application.xmlおよびmaf-feature.xmlファイル内の各プリファレンス要素は、デプロイメントの前に、その兄弟要素の範囲内で一意に識別される必要があります。

識別子値の例は、次のとおりです。

application.gen.gps.trackGPS
feature.f0.gen.gps.trackGPS

表D-1は、完全修飾されたプリファレンス識別子の生成方法を示しています。

表D-1 プリファレンスに対するMAFのネーミング・パターン

式説明構文

式	説明	構文
`PreferenceIdentifier`	モバイル・プラットフォーム表現に変換されたプリファレンス要素の識別子値を表します。	`ApplicationPreferences` \| `FeaturePreferences`
`ApplicationPreferences`	`maf-application.xml`ファイルから生成されるプリファレンス識別子値をビルドするには、この式を使用します。	`application`.`ApplicationElementPath` `ApplicationElementPath`は、最上位の親要素である`<adfmf:preferences>`で始まり、識別対象の要素で終わる、`id`属性値のドット区切りのリストを表します。`maf-application.xml`ファイルの次のセグメントで、生成されたこの識別子は、`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`	`maf-feature.xml`ファイルから生成されるプリファレンス識別子値をビルドするには、この式を使用します。	`feature.FeatureElementPath` `FeatureElementPath`は、最上位の親要素である`<adfmf:feature>`で始まり、識別対象の要素で終わる、`id`属性値のドット区切りのリストを表します。`maf-feature.xml`ファイルの次のセグメントで、生成されたこの識別子は、`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>

PreferenceIdentifier

モバイル・プラットフォーム表現に変換されたプリファレンス要素の識別子値を表します。

ApplicationPreferences | FeaturePreferences

ApplicationPreferences

maf-application.xmlファイルから生成されるプリファレンス識別子値をビルドするには、この式を使用します。

application.ApplicationElementPath

ApplicationElementPathは、最上位の親要素である<adfmf:preferences>で始まり、識別対象の要素で終わる、id属性値のドット区切りのリストを表します。maf-application.xmlファイルの次のセグメントで、生成されたこの識別子は、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

maf-feature.xmlファイルから生成されるプリファレンス識別子値をビルドするには、この式を使用します。

feature.FeatureElementPath

FeatureElementPathは、最上位の親要素である<adfmf:feature>で始まり、識別対象の要素で終わる、id属性値のドット区切りのリストを表します。maf-feature.xmlファイルの次のセグメントで、生成されたこの識別子は、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>

表D-1のコード例で引用されている<adfmf:preferences>要素にはid属性がなく、そのため、これはどのプリファレンス識別子でも表されません。

D.2 Android用のプリファレンスの変換

MAFのデプロイメントでは、XMLとXLSを使用して、アプリケーション機能とアプリケーション・レベルの両方で定義されているユーザー・プリファレンス・ページを、次の3つのXMLドキュメントに変換します。

preferences.xml
arrays.xml
strings.xml

D.2.1 Preferences.xml

このファイルには、maf-feature.xmlとmaf-application.xmlの両方のファイルからの変換済のプリファレンスが含まれています。

D.2.1.1 プリファレンス要素のマッピング

表D-2は、MAFのプリファレンス定義の、Androidテンプレート・プリファレンスおよびAndroidネイティブ・プリファレンスへのマッピングを示しています。

表D-2 MAFプリファレンスの、Androidプリファレンスへのマッピング

MAFプリファレンス定義	カスタムまたはAndroidネイティブ・プリファレンス定義(MAFデプロイメントで使用される)	Androidネイティブ・プリファレンス定義(MAFデプロイメントで使用されない)
`<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`

D.2.1.2 プリファレンス属性のマッピング

Preferences.xmlファイルには、strings.xmlおよびarrays.xmlファイルの両方に格納されている文字列リソースへの参照が含まれています。Android SDKでは、XMLファイル内のリソースの構文を@[<package_name>:]<resource_type>/<resource_name>と定義しています。このファイルには、文字列値への参照だけでなく、リスト・プリファレンスの名前と値のペアも含まれています。XSLは、文字列とリスト・プリファレンスに対して次のものを作成します。

<package_name> は、リソースが存在するパッケージの名前です(同じパッケージのリソースを参照するときは必要ありません)。参照のこのコンポーネントは使用されません。
<resource_type>は、リソース・タイプのRサブクラスです。このコンポーネントは、文字列参照の作成時はstring、リスト・プリファレンスの作成時はarrayの値を持ちます。
<resource_name>は、XML要素内のandroid:name属性値です。android:title属性を指定する場合、このコンポーネントの値は、<PreferenceIdentifier>_titleになります(<PreferenceIdentifier>の定義については、第D.1項「プリファレンスのネーミング・パターン」を参照してください)。

表D-3と表D-4は、特定のMAFプリファレンスに対するMAF属性の、Androidプリファレンスへのマッピングを示しています。

この表では、

{X}というフォームのエントリ(表D-3の{default}など)は、Xという名前のMAF属性の値を示しています。
<PreferenceIdentifier>があるエントリは、第D.1項「プリファレンスのネーミング・パターン」で説明されているとおり、プリファレンス識別子の値を示しています。
アスタリスク(*)が付いている属性は、MAFの名前空間で定義されているカスタムのテンプレート属性であり、preferences.xmlにadfmf:<attributeName>というフォームで存在している必要があります。それ以外の属性は、Androidの名前空間の一部であり、preferences.xmlにandroid:<attributeName>として存在している必要があります。

表D-3 MAFプリファレンス属性の、Androidプリファレンスへのマッピング

MAF属性定義	テンプレート・カスタムまたはAndroidネイティブ・プリファレンス属性	Android属性値	適用先
`id`	`key`	`<PreferenceIdentifier>`	`AdfMFPreferenceBoolean`、`AdfMFPreferenceText`、`AdfMFPreferenceList`、`PreferenceScreen`、`PreferenceCategory`
`default`	`defaultValue`	`{default}`	`AdfMFPreferenceBoolean`、`AdfMFPreferenceText`、`AdfMFPreferenceList`
`label`	`title`	指定された`{label}`値が文字列リソース・バンドルへの参照でない場合は、`@string/<PreferenceIdentifier>___title`。指定された`{label}`を持つ、`strings.xml`内の文字列を参照します。	`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`

D.2.1.3 属性のデフォルト値

MAFアプリケーション・エディタとMAF機能エディタでは、次の場合はXMLから属性の名前と値が除外されます。

属性タイプがxsd:booleanである。
属性値に<default>値オプションがある。
ユーザーが値として<default>を指定している。

XSLは、ブール・タイプのMAF属性と、対応するデフォルト値を認識している必要があります。XSLはその後、適切なAndroidまたはテンプレート・カスタム属性値を指定します(ユーザーによって選択された場合)。

表D-4は、変換されるMAFプリファレンスにdefault属性が含まれていない場合に、デプロイメントでandroid:defaultValue属性に対して指定されるものを示しています。

表D-4 デフォルト以外の値を持つ属性の変換

MAFプリファレンス要素	等価のAndroidプリファレンス	デフォルトの属性値
`preferenceBoolean`	`AdfMFPreferenceBoolean`	`false`
`preferenceText`	`AdfMFPreferenceText`	空の文字列
`preferenceList`	`AdfMFPreferenceList`	空の文字列

D.2.1.4 プリファレンス画面ルート要素

preferences.xmlファイルには、<PreferenceScreen>と呼ばれるルート要素があります。Androidテンプレートでは、この要素に次のXML名前空間定義が存在している必要があります。

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

ここで、<Application Package Name>要素は、AndroidManifest.xmlファイル内にあるものと同じアプリケーション・パッケージ名として定義されます。<Android Package Name>は、AndroidManifest.xmlファイルで指定されているAndroidパッケージ名を定義します。詳細は、第3.3項「MAFアプリケーションの表示プロパティの設定」を参照してください。

デプロイメントでは、Androidデプロイメント・プロファイルのアプリケーション・バンドルID値が使用されます(存在する場合)。プロファイルにアプリケーション・バンドルID値が存在しない場合は、maf-application.xmlファイルに含まれているアプリケーションの表示名およびアプリケーションIDからこの値が取得されます。デプロイメントJavaコードは、この値をXSLドキュメントにパラメータとして渡します。

次の例は、サンプル・アプリケーションのPrefDemoでmaf-feature.xmlファイルに含まれるMAFプリファレンスを示しています(付録G「サンプルのMAFアプリケーション」を参照)。

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
                xmlns:adfmf="http://xmlns.oracle.com/adf/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>

D.2.2 arrays.xml

arrays.xmlファイルは、preferences.xmlファイルから参照されるリスト・プリファレンスの名前と値を列挙する文字列配列要素で構成されています。maf-application.xmlおよびmaf-feature.xmlファイルに含まれている各<preferenceList>要素は、2つの文字列配列要素(1つは名前用、もう1つは値用)に変換されます。たとえば、次の例に記載されているMAFのpreferenceList定義は、次の2番目の例に示されているように、arrays.xmlファイル内の<string-array name="feature.oracle.hello.prefGroup.MyList___entry_values">および<string-array name="feature.oracle.hello.prefGroup.MyList___entries">に変換されます。

<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:adfmf="http://xmlns.oracle.com/adf/mf">
 
<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>
...

次の例は、arrays.xmlファイルに含まれている、<preferenceList>要素から変換された文字列配列要素のペアを示しています。

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

次の例は、preferences.xmlで参照されている<string-arrays>を示しています。

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

D.2.3 Strings.xml

次の例で示されているstrings.xmlファイルは、preferences.xmlファイルによって参照される文字列要素、およびmaf-application.xmlファイルとmaf-feature.xmlファイルで定義されているリソース・バンドル参照で構成されています。各文字列要素には、文字列および文字列値を一意に識別するname属性があります。

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

文字列のソースがリソース・バンドル文字列への参照でない場合、name属性の命名規則は<PreferenceIdentifier>___<androidAttributeName>です。

<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:adfmf="http://xmlns.oracle.com/adf/mf">
   <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>

D.3 iOS用のプリファレンスの変換

MAFデプロイメントは、表D-4に記載されているMAFプリファレンスを、iOS設定アプリケーションで必要なプリファレンス・リスト(strict the Display to a)ファイル表現に変換します。

表D-5 MAFプリファレンスと、対応するiOS表現

MAFプリファレンス・コンポーネント	iOS表現
`<adfmf:preferencePage>`	`PSChildPaneSpecifier`
`<adfmf:preferenceGroup>`	`PSGroupSpecifier`
`<adfmf:preferenceBoolean>`	`PSToggleSwitchSpecifier`
`<adfmf:preferenceList>`	`PSMultiValueSpecifier`
`<adfmf:preferenceText>`	`PSTextFieldSpecifier`
`<adfmf:preferenceNumber>`	`PSTextFieldSpecifier`

プリファレンス・リスト(.plist)ファイルのiOS要件については、iOS Developer Library (http://developer.apple.com/library/ios/navigation/)にある『Preferences and Settings Programming Guide』を参照してください。

次の例は、maf-application.xmlファイルに基づくXMLを示しています。

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