21 ユーザー・プリファレンスの有効化
この章の内容は次のとおりです。
モバイル・アプリケーションのユーザー・プリファレンス・ページの作成
プリファレンスによって、エンド・ユーザーが構成可能な設定を追加できます。
maf-application.xmlおよびmaf-feature.xmlの両方のファイル内で、<adfmf:preferences>要素を使用してユーザー・プリファレンス・ページを定義します。また、<adfmf:preferences>要素を使用して、各アプリケーション機能内でユーザーが管理するプリファレンスを作成します。
次の例に示すとおり、<adfmf:preferenceGroup>と呼ばれる<adfmf:preferences>の子要素とその子要素によってユーザー・プリファレンスを定義し、これには、テキスト文字列、ドロップダウン・メニューや、このケースのようにアプリケーション設定の追加オプションをユーザーに提示する子ページなど、様々な形でオプションを提示するページを作成します。
<?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>
子ユーザー・プリファレンス・ページを開くことで、それに続くオプションを提供する方法の例を図に示します。
プリファレンス・ページは<adfmf:preferenceGroup>要素内で定義され、次の子要素が存在します。
-
<adfmf:preferencePage>: ユーザー・インタフェースに新しいページを指定します。 -
<adfmf:preferenceList>: ユーザーに特定のオプション・セットを提供します。-
<adfmf:preferenceValue>: リスト要素を定義する子要素です。
-
-
<adfmf:preferenceBoolean>: ブール設定です。 -
<adfmf:preferenceText>: テキスト・プリファレンス設定です。
これらの要素とその属性の詳細は、Oracle Mobile Application Frameworkタグ・リファレンスを参照してください。
アプリケーションおよびアプリケーション機能レベルの両方のプリファレンス・ページを作成する例については、PrefDemoサンプル・アプリケーションを参照してください。このサンプル・アプリケーションは、開発コンピュータのJDeveloperインストール・ディレクトリ内で次の場所にあるPublicSamples.zipファイルに置かれています。
jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples
PrefDemoアプリケーションは、アプリケーションレベルの設定ページと、MAF AMXとして実装されている3つのアプリケーション機能のプリファレンス・ページで構成されています。通常の設定ページから起動するPrefDemoアプリケーションの設定ページを図に示します。この図では、プリファレンス設定ページをiOSの設定アプリケーションから起動しています。
次の図で「App」、「Feature1」(これが選択されています)および「Feature 2」と表示されているアプリケーション機能のプリファレンス・ページでは、MAF AMXブール・スイッチ、入力テキストおよび出力テキストの各コンポーネントから構築されたプリファレンス・ページの例が示されており、これらのコンポーネントは、EL (式言語)を使用してアプリケーション機能やその内部に構成されている様々な<adfmf:preferences>コンポーネントにアクセスします。「ユーザー・プリファレンス・ページ用に格納された値を取得するEL式の使用方法」を参照してください。
図21-3 PrefDemoアプリケーションに表示されたアプリケーション機能のプリファレンス・ページ
「図21-3 PrefDemoアプリケーションに表示されたアプリケーション機能のプリファレンス・ページ」の説明
PrefDemoアプリケーションでは、ビュー・アクティビティとページ・リフレッシュが可能な制御フロー・ケースで構成される単一のバインド・タスク・フローによって、MAF AMXの各プリファレンス・ページが参照されます。
モバイル・アプリケーションレベルのプリファレンス・ページの作成方法
図のmaf-application.xml概要エディタの「プリファレンス」ページでは、<adfmf:preferenceGroup>内の子プリファレンス・ページ要素をネストすることでアプリケーションレベルのプリファレンス・ページ・セットを構築できます。このページでは、<adfmf:preferenceGroup>およびその子要素が同様に名付けられたオプション(「プリファレンス・ページ」、「プリファレンス・リスト」、「ブール型のプリファレンス」など)として示され、JDeveloperの「構造」ウィンドウと同様にこれらを階層(またはツリー)にアセンブルします。
図21-4 「プリファレンス・ページ」を使用したモバイル・アプリケーションレベルのプリファレンスの追加
「図21-4 「プリファレンス・ページ」を使用したモバイル・アプリケーションレベルのプリファレンスの追加」の説明
maf-application.xmlファイルを正しく構成するには、上の図に示す「プリファレンス」ページの「追加」ドロップダウン・リストを使用して、ユーザー・プリファレンス・ページを構築します。また、次の図に示す「プリファレンス」パレットからコンポーネントをドラッグして、エディタ、「ソース」ウィンドウまたは「構造」ウィンドウのいずれかにドロップできる一方で、そのページのドロップダウン・リストには、選択されたプリファレンス要素に対して、適切な親、子または兄弟の関係を持つことができる要素のみが提示されます。たとえば、上の図にはプリファレンス・グループ要素であるMobileApp内に挿入できるコンポーネントのみが示されています。また、このエディタでは、各プリファレンス要素に固有の属性に対して値を入力できます。
プリファレンス・ページを作成するには:
- 図のように、「プリファレンス・グループの挿入」ダイアログに入力します。
-
プリファレンス・グループ要素の一意の識別子を入力します。
-
ユーザー・インタフェースに表示される説明テキストを入力します。ユーザー・インタフェースにこのテキストを表示する方法の例は、図21-1の例を参照してください。
-
新しいユーザー・プリファレンス・ページの作成方法
プリファレンス・ページ・コンポーネントでは新しいユーザー・インタフェース・ページを作成できます。「前に挿入」、「内部に挿入」、「後ろに挿入」の各オプションを使用してプリファレンス・ページを作成します。
始める前に:
プリファレンス・グループ要素を作成する必要があります。
新しいユーザー・プリファレンス・ページを作成するには:
- 図に示すように、「追加」をクリックして、「プリファレンス・グループの中に挿入」→「プリファレンス・ページ」を選択します。
- 図に示すように、次のプリファレンス・ページ属性を「プリファレンス・ページの挿入」ダイアログに定義します。
-
プリファレンス・ページ要素の一意の識別子を入力します。
-
ユーザー・インタフェースに表示される説明テキストを入力します。
-
- プリファレンス・ページを選択し、図に示すように、「プリファレンス・ページの中に挿入」→「プリファレンス・グループ」と選択することで、子プリファレンス・グループ要素を挿入し、プリファレンス・ページの本体を作成します。子プリファレンス・グループの一意の識別子と表示名を定義すると、これにプリファレンス・リスト要素などの他の要素を移入できます(「プリファレンス・ページを追加する場合の処理」を参照)。
プリファレンス・ページを追加する場合の処理
概要エディタでプリファレンス・ページとその子プリファレンス・グループ・コンポーネントを定義すると、JDeveloperでは、次の例に示すように、属性を使用して<adfmf:preferencePage>が生成されます。<adfmf:preferencePage>は、親<adfmf:preferenceGroup>要素内にネストされます。
<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>
ユーザー・プリファレンス・リストの作成方法
プリファレンス・リスト・コンポーネントを追加してオプションのリストを作成します。
始める前に:
プリファレンス・リストまたは他のすべてのリストに関連するコンポーネントの親としてプリファレンス・グループを作成する必要があります。
ユーザー・プリファレンス・リストを作成するには:
- 「プリファレンス・グループ」または「プリファレンス・ページ」を選択して、「追加」→「内部に挿入」→「プリファレンス・リスト」の順にクリックします。図には、Select Your Versionという名前のプリファレンス・グループ・コンポーネントの子としてプリファレンス・リストを追加する例が示されています。
- 図に示すように、「プリファレンス・リストの挿入」ダイアログを使用して次の属性を定義し、「OK」をクリックします。
-
一意の識別子を入力します。
-
ユーザー・インタフェースに表示される説明テキストを入力します。
-
- 図に示すように、「プリファレンス値」表で「追加」をクリックし、アイテムのリストを定義します。プリファレンス値を選択してから「削除」をクリックすることで、この値を削除することもできます。プリファレンス値の表示順番を変更するには、プリファレンス値を選択してから上および下の矢印を使用します。
ユーザーにデフォルト設定を提供するには、「デフォルト」を選択します。「プリファレンス・ページを追加する場合の処理」に示すように、
<adfmf:preferenceList>要素内でデフォルト・ステータスは、default="ENTERPIRSE"と定義されています。ヒント:
「追加」をクリックするほか、それらをドラッグして「構造」ウィンドウまたは「ソース」ウィンドウのいずれかにドロップしても、プリファレンス値コンポーネントを追加できます。
プリファレンス・リストを作成する場合の処理
プリファレンス・リスト・コンポーネントをプリファレンス・グループに追加し、一連のプリファレンス値を定義すると、「プリファレンス・ページを追加する場合の処理」に示すように、JDeveloperでは<adfmf:preferenceList>要素を使用して<adfmf:preferences>セクションが更新されます。
ブール型のプリファレンス・リストの作成方法
開始する前に、 「モバイル・アプリケーションのユーザー・プリファレンス・ページの作成」を参照してください。
<adfmf:preferenceBoolean>要素は<adfmf:preferenceGroup>要素内にネストされる必要があるため、まずプリファレンス・グループ・コンポーネントを階層に挿入する必要があります。
ユーザー・ブール型リストを作成するには:
- 図に示すように、GPS設定などのプリファレンス・グループ要素を選択します。
- 図に示すように、「ブール型のプリファレンスの挿入」ダイアログを使用して次の属性を定義し、「OK」をクリックします。
-
一意の識別子を入力します。
-
ユーザー・インタフェースに表示される説明テキストを入力します。
-
ブール型のプリファレンスを追加する場合の処理
ブール型のプリファレンスを追加してそのデフォルト値を指定した場合、次の例に示すように、JDeveloperでは、<adfmf:preferenceBoolean>要素を使用してmaf-application.xmlファイルの<adfmf:preferences>セクションが更新されます。
<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>
テキストのプリファレンスの追加方法
挿入オプションを使用して、ユーザーが情報を格納したりデフォルト・テキストを閲覧できるようにする「テキストのプリファレンス」というダイアログを作成します。「セキュリティ」という名前のプリファレンス・グループ内にテキストのプリファレンスを作成する例を図に示します。
始める前に:
プリファレンス・グループ要素を作成します。
テキストのプリファレンスを作成するには:
- 図に示すように、「テキストのプリファレンスの挿入」ダイアログに次の情報を入力して、「OK」をクリックします。
-
一意の識別子を入力します。
-
ユーザー・インタフェースに表示される説明テキストを入力します。
-
テキストのプリファレンスを定義する場合の処理
テキストのプリファレンスを追加してそのデフォルト値を指定した場合、次の例に示すように、JDeveloperでは、<adfmf:preferenceText>要素を使用してmaf-application.xmlファイルの<adfmf:preferences>セクションが更新されます。
<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>
セキュリティURL、ユーザー名およびパスワードのプリファレンス設定を定義するプリファレンス・グループ要素は、図のように表示されます。
図では、セキュリティURLがシードされた値を示し、ユーザー名が入力値の<adfmf:preferenceText>要素を示しています。MAFのプリファレンスはiOS設定アプリケーションと統合されているため、パスワード入力テキストのsecret="true"属性により、ユーザーの入力を黒丸で覆うiOSの表記規則に従うアプリケーションとなります。『Settings Application Schema Reference』のisSecureテキスト・フィールド要素の詳細は、iOS Developer Library (http://developer.apple.com/library/ios/navigation/)および「プラットフォームによる表示の差異」を参照してください。
アプリケーションレベルのプリファレンス・ページを作成する場合の処理
モバイル・アプリケーションをデプロイすると、アプリケーション全体のプリファレンス設定ページがiOSデバイスの設定アプリケーションなど、デバイスのグローバル設定アプリケーションに伝播されます。「デプロイメントでのプリファレンスの変換」を参照してください。
アプリケーション機能のユーザー・プリファレンス・ページの作成
アプリケーション機能をモバイル・アプリケーションと別個に配布するには、そのアプリケーション機能を含む機能アプリケーション・アーカイブ(FAR) .jarファイルを、別のモバイル・アプリケーションのライブラリに追加します。
その後、このアプリケーション機能を、アプリケーションのmaf-application.xmlファイル内で参照します。アプリケーション機能において、使用先のアプリケーション用に定義した全般的なプリファレンスだけでなく、特定のユーザー・プリファレンスのセットが必要になる場合は、図に示すように、maf-feature.xmlの概要エディタの「プリファレンス」タブを使用して、該当するプリファレンスを定義できます。「モバイル・アプリケーションのユーザー・プリファレンス・ページの作成」で説明されているように、アプリケーション・レベルのプリファレンスと同じ方法でアプリケーション機能のプリファレンスを構築します。maf-feature.xmlファイルにプリファレンスを定義した後で、「UIコンポーネントの作成と使用方法」で説明されているように、ブール・スイッチ、入力および出力コンポーネントが埋め込まれているMAF AMXページを参照するアプリケーション機能を作成することで、実際のプリファレンス・ページを作成します。
ユーザー・プリファレンス・ページ用に格納された値を取得するEL式の使用方法
アプリケーション機能レベルのプリファレンス・ページを作成する際は、EL式をMAF AMXコンポーネントに追加します。
入力テキスト・コンポーネントなどのMAF AMXコンポーネントを次の例に示します。
<amx:inputText label="Number" id="it1" inputType="number"
value="#{preferenceScope.feature.Feature1.f1top.f1Number}"/>
この例に示すとおり、EL式では、preferenceScopeオブジェクトを使用して、アプリケーションがアプリケーション機能レベルのプリファレンスにアクセスできるようにします。これらのEL式の書式は次のとおりです。
preferenceScope.feature.feature-id.group-id.property-id
図は、式ビルダーを使用したEL式の作成について説明しています。アプリケーション機能(<adfmf:feature id="Feature1">)のID、プリファレンス・グループ(<adfmf:preferenceGroup id="f1top">)のID、プリファレンス・プロパティ(<adfmf:preferenceNumber id="f1Number">)のIDなど、maf-feature.xml内の様々なコンポーネントに対して構成されるIDによってプリファレンス自体が指定されています。
EL式には、ゼロ個以上のgroup-id要素およびproperty-id要素が含まれる可能性があります。
preferenceScopeに関する必知事項
EL式には次の解決パターンがあります。
-
JavaScriptレイヤーから、次のJavaScript関数を使用してEL値式を解決します。
adf.mf.el.getValue(expression, success, failed)
adf.mf.el.getValueの解決では、まずJS-ELパーサーとJavaScriptコンテキスト・キャッシュをローカルで使用して式の解決を試みます。式がローカルで解決できない場合は、その式を埋込みJavaレイヤーに評価用として渡し、そこでJava ELパーサーによって解決されます。これは、モデルのgetValueメソッドに対するGenericInvokeRequestを使用して処理されます。 -
Javaレイヤーで、次の手法を使用してEL値式を解決します。
String val = AdfmfJavaUtilities.evaluateELExpression("#{preferenceScope.feature.f0.vendor}");setValueメソッドでは、次のように式を解決します。ValueExpression ve = AdfmfJavaUtilities.getValueExpression("#{preferenceScope.feature.f0.vendor}"); ve.setValue(AdfmfJavaUtilities.getADFELContext(), value);EL式の評価には、
preferenceScopeオブジェクトの検索が含まれます。評価は左から右に行われ、各トークンは別個に解決されます。トークンが解決されると、これは次の(その右側の)トークンの解決に使用されます。
preferenceScopeオブジェクトがない場合は、プリファレンスを公開できません。preferenceScopeオブジェクトの詳細は、「モバイル・アプリケーション・フレームワークのオブジェクト・カテゴリについて」を参照してください。
iOSネイティブ・ビューでのプリファレンス値の読取り
MAFでは、ネイティブUI (UIView、UIViewControllerなど)に提供されているAPIが統合され、iOSプラットフォームで一定の構成が可能です。
ネイティブUIを初期化すると、ADFSession オブジェクトのインスタンスが利用可能になります。そのgetPreferencesメソッドを使用して、MAFに対し、maf-application.xmlファイルで定義されているアプリケーションで利用可能なプリファレンスのリストを提供するように命令できます。次の例に示すとおり、このメソッドでは、プリファレンスにid、valueおよびlabelを含めることができるプリファレンス・プロパティ・オブジェクトのNSArray*が戻されます。このAPIコールでは、エンド・ユーザーによって特定のプリファレンスの値が提供されたこと、またはプリファレンスのデフォルト値が戻されていることのいずれかを確認します。
//...
-(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;
}プラットフォームによる表示の差異
MAFプリファレンス・ページでは、MAFアプリケーションをデプロイするプラットフォームでネイティブのルック・アンド・フィールが維持されます。
その結果、MAFのプリファレンス・ページの表示はサポートされるプラットフォームで異なります。表は、AndroidとiOSプラットフォーム間の表示の違いを示しています。iOSプラットフォームではプリファレンスがインラインで表示されるため、そのシステムではダイアログ・ページを起動しません。いくつかの例外を除いて、Androidプラットフォームではこれらのコンポーネントがダイアログで表示されます。
表21-1 プラットフォームごとのプリファレンス・コンポーネントの比較
| コンポーネント | iOS | iOSの表示例 | Android | Androidの表示例 |
|---|---|---|---|---|
|
プリファレンス・グループ(カテゴリ選択) |
iOSでは、その親プリファレンス・グループ内にプリファレンス要素が表示されます。 |
 |
Androidでは、その親プリファレンス・グループ内にプリファレンス要素が表示されます。 |
 |
|
ブール型のプリファレンス・リスト |
ブール型のプリファレンスは、onとoffなどのペアの値で表示されます。 |
 |
Androidでは、ブール型のプリファレンスをチェック・ボックスで表示します。 |
 |
|
テキストのプリファレンス |
iOSはテキストをインラインで表示します。 |
 |
Androidはデフォルト・テキストを入力フィールド内に表示します。 |
 |
|
テキストのプリファレンス(機密入力テキスト) |
iOSプラットフォームでは、ユーザーはテキストをインラインで入力し、各文字はその入力後に黒丸で覆われます。「テキストのプリファレンスを定義する場合の処理」を参照してください。 |
 |
Androidでは、入力テキスト・ダイアログが起動し、各文字はその入力後に黒丸で覆われます。 |
 |
|
単一のアイテム選択リスト(プリファレンス・リストから) |
iOSプラットフォームでは別のプリファレンス・ページに単一のアイテム選択リストが表示されます。 |
 |
Androidでは、ダイアログ内に単一のアイテム選択リストが表示されます。 |
 |
|
プリファレンス・ページ |
iOSでは、プリファレンス・グループから子プリファレンス・ページを起動します。 |
 |
Androidでは、プリファレンス・グループから子プリファレンス・ページを起動します。 |
 |
iOSおよびAndroidのプラットフォームには設定アプリケーションがありますが、図のプリファレンスで示すように、設定アプリケーションへのアプリケーション・レベルのプリファレンスの統合はiOSプラットフォームのみでサポートされます。
Androidデバイスでは、ユーザーは、アプリケーションが実行されている場合のみ、次の図のようなアプリケーション固有のプリファレンス・ページにアクセスします。
