Oracle® Fusion Middleware Oracle Application Development Framework Webユーザー・インタフェース開発者ガイド 11gリリース2 (11.1.2.1.0) B66719-01 |
|
前 |
次 |
この章では、データの入力、値の選択、テキストの編集およびファイルのロードに使用される入力コンポーネントについて説明します。非常に大きくなる可能性のあるリスト、またはオブジェクト間の関係を表す可能性のあるリストを作成する場合(別のオブジェクトの外部キーである属性を表すリストの作成など)、値リスト・コンポーネントを使用できます。これらのコンポーネントの詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。
この章では、次の項目について説明します。
入力コンポーネントは、様々な形式のユーザー入力を受け入れます。最も一般的な形式は、フォームの内部に表示され、フォームの送信時に送信されるテキスト、数値、日付および選択リストです。入力された値または選択は、さらに処理される前に検証および変換できます。図11-1は、ADF Facesの標準入力コンポーネントを示しています。
ADF Faces入力コンポーネントには、図11-2に示すように、ユーザーが1つまたは複数の値を選択できるいくつかのコンポーネントも含まれます。
多くの場合、入力コンポーネントは、ユーザー入力用のフォームの作成に使用されます。たとえば、File Explorerアプリケーションには、ユーザーが新規ファイルを作成できるフォームが含まれます。図11-3に示すように、入力コンポーネントでは、ユーザーが名前やサイズの入力、権限の選択、キーワードとファイルの説明の追加を行うことができます。アスタリスクで示されているように、「名前」フィールドは必須です。ユーザーが値を入力しなかった場合は、エラー・メッセージが表示されます。検証および関連エラー・メッセージはコンポーネントで構成されます。
richTextEditor
コンポーネントには、ユーザーに単純なテキスト以外を入力させる場合に必要になる、異なるフォント、サイズ、行揃えおよびその他の編集機能を使用した書式設定可能な、多数の行にわたるリッチ・テキスト入力が用意されています。たとえば、richTextEditor
をWebベースのディスカッション・フォーラムで使用して、図11-4に示すように、ユーザーが公開する必要のあるテキストを書式設定できるようにすることができます。
inputFile
コンポーネントでは、ユーザーはアプリケーション・サーバーにアップロードするローカル・ファイルを参照できます。たとえば、電子メール・メッセージでは、図11-5に示すようにユーザーがメッセージにファイルを添付できます。
ADF Faces選択コンポーネントを使用すると、ユーザーは値を入力するかわりに項目のリストから選択できるようになります。ADF Facesは、単一選択の選択リストと複数選択の選択リストの両方を提供します。単一選択リストは、図11-6に示すように、オンライン食品注文での目的の飲料など、リストから1つの値を選択するために使用します。
ADF単一選択コンポーネントには、ドロップダウン・リスト(図11-6を参照)、リスト・ボックス、ラジオ・ボタンおよびチェックボックスがあります。
ADF複数選択コンポーネントでは、ユーザーはリストの値を複数選択できます。たとえば、1つの飲料タイプを選択するかわりに、selectManyChoice
コンポーネントでは、図11-7に示すようにユーザーが複数の飲料を選択できます。
ADF複数選択コンポーネントには、ドロップダウン・リスト、チェックボックスおよびシャトルが含まれます。
ベスト・プラクティス: 選択リストまたは値リスト(LOV)コンポーネントを使用して、リストを表示できます。LOVコンポーネントは、選択リストが大きい場合に使用する必要があります。LOVコンポーネントは、ListOfValueModel クラスを使用したモデルドリブンであり、APIを使用してプログラムで構成できます。これらは、問合せパネルを含むこともあるポップアップ・ウィンドウの内部の選択リストを表します。選択リストは、単純に静的な値リストを表示します。LOVコンポーネントの使用の詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。 |
フォーム・コンポーネントには、その他のコンポーネント用のコンテナがあります。form
コンポーネントは、埋め込まれた入力コンポーネントからの値を送信できるリージョンを表します。formコンポーネントをネストさせることはできません。ADF Facesには、form内で個別にコンポーネント値を送信できるサブリージョンを定義することで柔軟性を高めるsubform
コンポーネントも用意されています。ADF Faces resetButton
コンポーネントを使用すると、ユーザーは、formまたはsubform内の入力値を簡単に以前の状態にリセットできるようになります。
入力コンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページに入力コンポーネントまたはフォームを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。入力コンポーネントで使用できる他の機能へのリンクを次に示します。
テキストでのパラメータの使用: コンポーネントに表示されるテキストに、実行時に解決されるパラメータを含める場合は、ADF Faces EL書式タグを使用できます。詳細は、3.5.2項「EL書式タグの使用方法」を参照してください。
クライアント・コンポーネント: 入力コンポーネントはクライアント・コンポーネントにすることができます。クライアントでコンポーネントを処理するには、第4章「ADF Facesクライアント側アーキテクチャの使用方法」を参照してください。
JavaScript API: すべての入力コンポーネントには、プロパティ値を設定または取得するために使用できるJavaScriptクライアントAPIがあります。詳細は、ADF Faces JavaScript APIドキュメントを参照してください。
イベント: 入力コンポーネントは、なんらかのロジックを実行することでアプリケーションで対応できるサーバー側とクライアント側両方のイベントを起動します。詳細は、第6章「イベントの処理」を参照してください。
検証および変換を入力コンポーネントに追加できます。詳細は、第7章「入力の検証および変換」を参照してください。
ヒントとメッセージを表示でき、入力コンポーネントにオンライン・ヘルプを関連付けることができます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。
特定の入力コンポーネントをページの他のコンポーネントより前に検証することが必要になる場合があります。詳細は、5.2項「immediate属性の使用」を参照してください。
選択コンポーネントから行った選択に基づいてページの他のコンポーネントを更新できます。詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。
scrollComponentIntoViewBehavior
タグをrichTextEditorコンポーネントとともに使用すると、ユーザーはコンポーネント内の特定の領域にジャンプできます。詳細は、6.6.1項「scrollComponentIntoViewBehaviorタグの使用方法」を参照してください。
スキンを使用して、必須および変更済通知に使用するアイコンを変更できます。詳細は、第28章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。
入力コンポーネントをアクセス可能にできます。詳細は、第30章「アクセス可能なADF Facesページの開発」を参照してください。
文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第29章「ページの国際化およびローカライズ」を参照してください。
アプリケーションでFusionテクノロジ・スタックを使用する場合は、ADFビジネス・コンポーネントがどのように構成されているかに基づいて、バインドされたフォームを自動的に作成できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「データバインドされた基本的なページの作成」の章を参照してください。アプリケーションでEnterprise JavaBeansを使用する場合は、同じことを行うことができます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Java EE開発者ガイド』のデータバインドされた基本的なページの作成に関する項を参照してください。
formは、他のコンポーネントのコンテナとして機能するコンポーネントです。フォーム内で送信アクションが発生すると、変更された入力値が送信されます。たとえば、入力コンポーネントと選択コンポーネントで構成される入力フォーム、および送信コマンド・ボタンを作成し、すべてをform内に配置できます。ユーザーが複数の入力フィールドに値を入力して送信ボタンをクリックすると、それらの新しい入力値が送信されて処理されます。
JDeveloperでJSFページを作成すると、デフォルトで、ページにform
コンポーネントが自動的に挿入されます。ページにコンポーネントを追加すると、form
コンポーネント内に挿入されます。
ヒント: ページにaf:form タグがない状態で、そのページにADF Facesコンポーネントをドラッグ・アンド・ドロップすると、JDeveloperにより、コンポーネントをformコンポーネントで囲むよう要求されます。 |
例11-1に、2つの入力コンポーネント、およびクリックされると両方の入力値が送信されて処理される送信ボタンを示します。
例11-1 入力コンポーネントのコンテナとしてのADF Facesのform
<af:form id="f1"> <af:panelFormLayout id="pfl1"> <af:inputText value="#{myBean.firstName}" label="#{First Name}" id="it1" </af:inputText> <af:inputText value="#{myBean.lastName}" label="#{Last Name}" id="it2" </af:inputText> <f:facet name="footer"> <af:commandButton text="Submit"/> id="cb1" </f:facet> </af:panelFormLayout> </af:form>
ページに使用できるform
コンポーネントは1つのみであるため、入力値を送信できる個別のリージョンを作成するには、form内にsubformを使用します。リージョンにおいて、subform内の値は、subform内のコンポーネントが値の送信を行う場合にのみ検証および処理されます。また、subform内に別のsubformをネストさせて、値を送信できるネストしたリージョンを作成することもできます。subformの詳細は、5.5項「サブフォームを使用したページでのセクションの作成」を参照してください。
例11-2に、それぞれに独自の入力コンポーネントと送信ボタンを含む2つのsubformがあるformを示します。送信ボタンをクリックすると、そのsubform内の入力値のみが送信されて処理されます。
例11-2 form内のADF Facesのsubform
<af:form> <af:subform> <af:panelFormLayout> <af:inputText value="#{myBean.firstName}" </af:inputText> <af:inputText value="#{myBean.lastName}" </af:inputText> <f:facet name="footer"> <af:commandButton text="Submit"/> </f:facet> </af:panelFormLayout> </af:subform> <af:subform> <af:panelFormLayout> <af:inputText value="#{myBean.primaryPhone}" </af:inputText> <af:inputText value="#{myBean.cellPhone}" </af:inputText> <f:facet name="footer"> <af:commandButton text="Submit"/> </f:facet> </af:panelFormLayout> </af:subform> </af:form>
基本的な送信ボタンの他に、form内にその他のコマンド・コンポーネントを追加して、そのform内の任意のフィールドで機能させることができます。ADF Facesには、resetButton
コンポーネントという特殊なコマンド・コンポーネントがあり、これをクリックすると、form内のすべての入力および選択コンポーネントがリセットされます。つまり、値の編集が可能なすべてのコンポーネントが、現在のモデルの値で更新されます。resetButton
コンポーネントが検証または変換エラーなしにサーバーに部分的または完全に正常に送信された以前の状態に入力コンポーネントをリセットするという点で、resetButton
コンポーネントはHTMLリセットとは異なります。たとえば、ユーザーが値A
を入力して送信ボタンをクリックし、値をA
からB
に変更してresetButton
コンポーネントをクリックすると、値A
がリストアされます。
多くの場合、JDeveloperを使用してformコンポーネントを追加します。ただし、手動でのformの追加や、特定の属性値を使用したformの構成が必要な場合があります。
始める前に:
formコンポーネントに関する知識が役立つ場合があります。詳細は、11.2項「formの定義」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
ページにformを追加する手順:
コンポーネント・パレットで、「レイアウト」パネルの「コア構造」グループから、「フォーム」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタで、「共通」セクションを開きます。ここでは、オプションで次の内容を設定できます。
DefaultCommand: [Enter]キーが押され、form内にフォーカスがある場合に、アクションを起動する必要のあるコマンド・コンポーネントのID属性を指定します。
UsesUpload: formでファイルのアップロードをサポートするかどうかを指定します。デフォルト値はFalse
です。ファイルのアップロードの詳細は、11.9項「ファイルのアップロード機能の使用方法」を参照してください。
TargetFrame: 新しいページを表示するかどうかを指定します。使用可能な値は、HTMLのターゲット属性の有効な値です。デフォルトは、_self
です。
ページのセクションで値を個別に送信できることが必要な場合は、formコンポーネント内にsubformコンポーネントを追加する必要があります。
始める前に:
formおよびsubformに関する知識が役立つ場合があります。詳細は、11.2項「formの定義」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
formコンポーネントをページに追加する必要があります。手順は、11.2.1項「ページへのformの追加方法」を参照してください。
ページにsubformを追加する手順:
コンポーネント・パレットで、「レイアウト」パネルの「コア構造」グループから、「サブ・フォーム」をform
コンポーネントの子としてページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタを使用して、次の設定を行います。
Default: subformで値を送信済であると仮定するかどうかを指定します。デフォルト値false
に設定すると、その他のsubform
コンポーネントが送信されていない場合にのみ、そのsubform
コンポーネントは送信済とみなされます。true
に設定すると、そのsubformコンポーネントは値を送信済とみなされます。
ヒント: subform は、リクエスト値の適用より後のフェーズ(つまり、decode()より後)に対してイベントが子またはファセットの1つによってキューに入れられた場合に送信済とみなされます。ライフサイクル・フェーズの詳細は、第5章「ADF FacesでのJSFライフサイクルの使用」を参照してください。 |
Default Command: [Enter]キーが押され、subform内にフォーカスがある場合に、アクションを起動する必要のあるコマンド・コンポーネントのID属性を指定します。
formまたはsubformに、resetButton
コンポーネントを追加できます。リセット・ボタンは、そのformまたはsubform内のコンポーネントでのみ機能します。
始める前に:
formコンポーネントおよびリセット・ボタンに関する知識が役立つ場合があります。詳細は、11.2項「formの定義」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
ページにリセット・ボタンを追加する手順:
コンポーネント・パレットで、「一般コントロール」パネルから「ボタン(リセット)」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタを使用して、次の設定を行います。
Text: ボタンのテキスト・ラベルを指定します。
Disabled: ボタンを無効にするかどうかを指定します。たとえば、ボタンを無効化する必要のある特定の状況を判断するEL式を入力できます。
ピッカー、スライダ、スピン・ボックスなど、入力コンポーネントには多くのバリエーションがありますが、inputText
コンポーネントは、値入力のための基本的な入力コンポーネントです。inputText
コンポーネントは、1行の入力フィールドとして定義することも、rows
属性を1より大きい値に設定してテキスト領域として定義することもできます。ただし、複数行のテキスト入力を作成する場合は、11.8項「richTextEditorコンポーネントの使用方法」で説明されているように、richTextEditor
コンポーネントの使用を検討します。
autoComplete
属性を使用して、inputText
コンポーネントでオートコンプリートを使用できます。true
に設定されている場合、コンポーネントは以前のエントリを記憶し、ユーザーがそれらのエントリと一致する値から始まる値を入力したときにそれらのエントリを表示します。
secret
属性をtrue
に設定することで、パスワードなどの入力値を非表示にできます。その他のADF Facesコンポーネントと同じように、inputText
コンポーネントではラベル、テキストおよびメッセージがサポートされています。このコンポーネントをラベルなしで表示する場合は、simple
属性をtrue
に設定します。図11-8に、1行のinputText
コンポーネントを示します。
rows
属性を使用して、inputText
コンポーネントで複数行のテキストを表示できます。rows
属性を1より大きい値に設定し、simple
属性をtrueに設定した場合、inputText
コンポーネントは、dimensionsFrom
属性を使用してそのコンテナに合せて拡大するように構成できます。コンポーネントが拡大される方法の詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。図11-10に、複数行のinputText
コンポーネントを示します。
複数のinputText
コンポーネントを追加して、入力フォームを作成できます。図11-9に、3つのinputText
コンポーネントと「発行」コマンド・ボタンを使用した入力フォームを示します。
コマンド・コンポーネントと連携して、inputText
コンポーネントに特定のテキストを挿入するinsertTextBehavior
タグも構成できます。入力するテキストには、簡単な文字列、またはその他のコンポーネントの値(selectOneChoice
コンポーネントで選択したリスト項目など)を指定できます。たとえば、図11-10は、ユーザーがすでにテキストを入力したinputText
コンポーネントを示しています。
この後、ユーザーがドロップダウン・リストから追加テキストを選択し、コマンド・ボタンをクリックすると、図11-11に示すように、inputText
コンポーネントにそのテキストが表示されます。
第9章「Webページ上のコンテンツの編成」で説明されている任意のレイアウト・コンポーネントの内部で、inputText
コンポーネントを使用できます。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
inputTextコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから「入力テキスト」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。
Label: ラベルとして使用するテキストを指定するための値を入力します。
使用するテキストがリソース・バンドルに格納されている場合は、ドロップダウン・リストを使用して「テキスト・リソースの選択」を選択します。「テキスト・リソースの選択」ダイアログを使用して、既存のバンドル内の適切なテキストを検索するか、既存のバンドル内に新しいエントリを作成します。リソース・バンドルの使用方法の詳細は、第29章「ページの国際化およびローカライズ」を参照してください。
Value: コンポーネントの値を指定します。値のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指していて、それが値の編集が可能なコンポーネントの場合、コンポーネントは読取り専用モードでレンダリングされます。
注意: inputText コンポーネントを使用してCharacter Large Object(CLOB)を表示する場合は、CLOBを文字列に変換するカスタム・コンバータを作成する必要があります。変換の詳細は、7.4項「カスタムJSFコンバータの作成」を参照してください。 |
「外観」セクションを開き、次の設定を行います。
Columns: フィールドに入力可能な最大の文字数を入力し、テキスト・コントロールのサイズを指定します。
Rows: 表示される行数を入力し、テキスト・コントロールの高さを指定します。デフォルト値は1で、1行の入力フィールドを生成します。行数は、ブラウザのデフォルトのフォント・サイズに基づいて見積られます。2以上に設定する場合は、wrap
属性も設定する必要があります。
DimensionsFrom: inputText
コンポーネントでジオメトリ管理を処理する方法を決定します。この属性に次のいずれかを設定します。
auto
: inputText
コンポーネントの親コンポーネントがその子の拡大を許可する場合、rows
属性が1より大きい数値に設定され、simple
属性がtrue
に設定されているかぎり、inputText
コンポーネントは親コンポーネントに合せて拡大されます。親コンポーネントが拡大を許可しない場合、inputText
コンポーネントはそのディメンションをコンテンツから取得します。
content: inputText
コンポーネントは、そのディメンションをコンポーネント・コンテンツから取得します。これがデフォルトです。
parent
: inputText
コンポーネントは、そのディメンションをinlineStyle
属性から取得します。inlineStyle
の値が存在しない場合、親コンテナによってサイズが決定されます。
Secret: 1行のテキスト・コントロールにのみ適用されるブール値を指定します。true
に設定されている場合、secret
属性により、テキストの実際の値がユーザーには非表示になります。
Wrap: 複数行のテキスト・コントロールで使用されるテキストの折返しタイプを指定します。この属性は、1行のコンポーネントでは無視されます。デフォルトでは属性がsoft
に設定されており、複数行のテキストは視覚的には折り返されますが、送信される値に改行は含まれません。この属性をoff
に設定すると折返しは無効にされ、複数行のテキストは水平にスクロールして表示されます。hard
に設定すると、行の折返しに必要な改行がテキストの値に含まれます。
ShowRequired: フィールドが必須であることを視覚的に表示するかどうかを指定します。required
属性をtrue
に設定しても、視覚的な表示が行われることに注意してください。showRequired
属性は、別のフィールドの値が変更された場合にのみ、フィールドが必須の場合に使用する必要があります。
Changed: フィールドの値が変更されるたびに青い円を表示するかどうかを指定します。これをtrue
に設定した場合は、changedDesc
属性も設定します。
ChangedDesc: 変更済アイコン上にマウスを移動したときにツールチップに表示されるテキストを指定します。デフォルトでは、テキストは"変更済"です。別の値を指定することで、これをオーバーライドできます。
Editable: コンポーネントを常に編集可能にするかどうかを決定します。そうする場合は、always
を選択します。ユーザーがマウスを値の上に移動するまでその値を読取り専用にする場合は、onAccess
を選択します。値を祖先コンポーネントから継承する場合は、inherit
を選択します。
注意: inherit を選択し、どの祖先コンポーネントでもeditable 値が定義されていない場合は、always の値が使用されます。 |
AccessKey: フィールドにアクセスするために押すキーを指定します。
LabelAndAccessKey: ラベルとアクセス・キーを別々に指定するかわりに、2つを結合して、アクセス・キーがラベルの一部になるようにできます。アクセス・キーとして使用する文字の前にアンパサンド(&)を付けます。
たとえば、フィールドのラベルが「Description」で、Dをアクセス・キーにする場合は、&Description
と入力します。
注意: 値はXMLのページ・ソースに格納されるため、アンパサンド(&)文字をエスケープする必要があります。そのため、ソース・ページでは、アンパサンドを意味する文字& を使用して表されます。 |
Simple: ラベルを表示しない場合にtrue
に設定します。
ラベル・テキストのスタイルを設定する場合は、「スタイル」セクションを展開し、LabelStyleを設定します。CSSスタイル・プロパティと値を入力します。たとえば、ラベル・テキストを折り返さない場合は、値にwhite-space:nowrap;
と入力します。
「動作」セクションを開き、次の設定を行います。
Required: 値が必要かどうかを指定します。true
に設定されている場合、値を入力する必要があることをユーザーに知らせるために視覚的に表示されます。値が入力されない場合、例外が発生し、コンポーネントの検証が失敗します。
ReadOnly: コントロールを、値の編集が可能なフィールドとして表示するか、出力スタイルのテキスト・コントロールとして表示するかを指定します。
AutoSubmit: 値が変更されたらコンポーネントを自動的に送信するかどうかを指定します。autoSubmit
属性の使用の詳細は、5.3項「最適化されたライフサイクルの使用」を参照してください。
AutoComplete: ユーザーが以前の値と一致する値の入力を開始した場合にコンポーネントがその値を表示できるようにする場合は、on
に設定します。一致を表示しない場合はoff
に設定します。デフォルトはon
です。
AutoTab: 現在のコンポーネントの最大長に達した場合に、フォーカスを次のタブ位置に自動的に移動するかどうかを指定します。
MaximumLength: テキスト・コントロールに入力できる1行当たりの最大文字数を指定します。これには、改行を表す文字も含まれます。0以下に設定されている場合、maximumLength
属性は無視されます。Internet Explorerなどのブラウザでは、改行は2文字として扱われます。
Converter: コンバータ・オブジェクトを指定します。詳細は、7.3項「変換の追加」を参照してください。
Validator: EL式を使用して、バリデータ・メソッドへのメソッド参照を指定します。詳細は、7.5項「検証の追加」を参照してください。
insertTextBehavior
タグは、コマンド・コンポーネントと連携して、inputText
コンポーネントに特定のテキストを挿入します。入力するテキストには、簡単な文字列、またはその他のコンポーネントの値(selectOneChoice
コンポーネントで選択したリスト項目など)を指定できます。inputText
コンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてinsertTextBehavior
タグを追加します。
注意: insertTextBehavior タグでは、サーバー側イベントの配信が自動的に取り消されます。親コマンド・コンポーネントのactionListener またはaction 属性は無視されます。サーバー側機能をトリガーする必要もある場合は、サーバー側イベントを配信するためにカスタム・クライアント・リスナーを追加する必要があります。詳細は、6.4項「クライアントからサーバーへのカスタム・イベントの送信」を参照してください。 |
操作を開始する前に
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.3項「inputTextコンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
insertTextBehavior
タグを追加する前に、11.3.1項「inputTextコンポーネントの追加方法」の説明に従ってinputText
コンポーネントを作成する必要があります。clientComponent
属性をtrue
に設定します。
テキスト挿入動作を追加する手順:
テキストを挿入するためにユーザーがクリックするコマンド・コンポーネントを追加します。手順は、20.3.1項「コマンド・ボタンおよびコマンド・リンクの使用方法」を参照してください。
コンポーネント・パレットで、「操作」パネルの「動作」グループから、「テキストの挿入動作」をコマンド・コンポーネントに子としてドラッグ・アンド・ドロップします。
テキスト挿入動作ダイアログで、次の内容を入力します。
For: ドロップダウン矢印を使用して「編集」を選択し、テキストを挿入するinputText
コンポーネントに移動して選択します。
Value: 挿入するテキストの値を入力します。静的テキストを挿入する場合は、そのテキストを入力します。ユーザーが別のコンポーネントの値(selectOneChoice
コンポーネントの値など)を挿入できるようにする場合は、その値に解決されるEL式を入力します。例11-3に、ドロップダウン・リストの値または静的テキストの値を挿入できるinputText
コンポーネントのページ・コードを示します。
例11-3 insertTextBehaviorタグの使用
<af:inputText clientComponent="true" id="idInputText" label="String value" value="#{demoInput.value}" rows="10" columns="60"/> <af:selectOneChoice id="targetChoice" autoSubmit="true" value="#{demoInput.choiceInsertText}" label="Select text to insert"> <af:selectItem label="Some Text." value="Some Text."/> <af:selectItem label="0123456789" value="0123456789"/> <af:selectItem label="~!@#$%^*" value="~!@#$%^*"/> <af:selectItem label="Two Lines" value="\\nLine 1\\nLine 2"/> </af:selectOneChoice> <af:commandButton text="Insert Selected Text" id="firstButton" partialTriggers="targetChoice"> <af:insertTextBehavior for="idInputText" value="#{demoInput.choiceInsertText}"/> </af:commandButton> <af:commandButton text="Insert Static Text"> <af:insertTextBehavior for="idInputText" value="Some Static Text."/> </commandButton>
デフォルトでは、コマンド・コンポーネントをクリックしてアクション・イベントがトリガーされるとテキストが挿入されます。ただし、プロパティ・インスペクタでinsertTextBehavior
コンポーネントのtriggerType
属性のドロップダウン・メニューからイベントを選択することで、これを別のクライアント・イベントに変更できます。
スライダ・コンポーネントを使用すると、スライダ上の位置が値に対応している1つまたは2つのマーカーがあるスライダを作成できます。スライダの値が表示され、一方にはマイナス・アイコンが、もう一方にはプラス・アイコンがあります。ユーザーはマーカーを選択し、スライダ上を移動させて値を選択します。図11-12(水平レイアウト)および図11-13(垂直レイアウト)に示すように、inputNumberSlider
コンポーネントにはマーカーが1つあり、ユーザーはスライダから値を1つ選択できます。
図11-14に示すように、inputRangeSlider
コンポーネントにはマーカーが2つあり、ユーザーは範囲のエンド・ポイントを選択できます。
図11-15に示すように、inputNumberSpinbox
は、数値用の入力フィールド、および入力フィールドの現在の値を増減させるための上矢印キーと下矢印キーのセットを作成する入力コンポーネントです。
inputNumberSlider
またはinputRangeSlider
コンポーネントを追加する際には、表示される数値の範囲と増分を決定できます。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.4項「数値入力コンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
inputNumberSliderまたはinputRangeSliderコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから、「スライダ(番号)」または「スライダ(範囲)」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタで、「共通」セクションを開いて、次の属性を設定します(inputRangeSlider
コンポーネントの場合は、「データ」セクションも開きます)。
Label: コンポーネントのラベルを指定します。
Minimum: 選択可能な最小値を指定します。この値は、スライダの開始値です。
Maximum: 選択可能な最大値を指定します。この値は、スライダの終了値です。
MinimumIncrement: 最小の増分値を指定します。これは、ユーザーがプラスまたはマイナスのアイコンをクリックすると適用される増分です。
MajorIncrement: 大きい方の2つの目盛り間の距離を指定します。この値を指定すると、ラベルの付いた値が表示されます。たとえば、図11-14のinputRangeSlider
コンポーネントのmajorIncrement
値は5.0
です。0
未満の場合、大きい方の増分値は表示されません。
MinorIncrement: 小さい方の2つの目盛り間の距離を指定します。0未満の場合、小さい方の増分値は表示されません。
Value: コンポーネントの値を指定します。value
のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。
「外観」セクションを展開し、「Orientation」を設定して、コンポーネントを水平レイアウトと垂直レイアウトのどちらにするかを指定します。この項のその他の属性の詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。
inputNumberSpinbox
コンポーネントを使用すると、ユーザーは一連の数値をスクロールして値を選択できるようになります。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.4項「数値入力コンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
inputNumberSpinboxコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから、「入力数値スピンボックス」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタの「データ」セクションを開き、次の設定を行います。
Value: コンポーネントの値を指定します。value
のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。
Minimum: 入力フィールドで許可される最小値を指定します。
Maximum: 入力フィールドで許可される最大値を指定します。
StepSize: スピン・ボックスが入力フィールドの数値を増減する際の増分を指定します。
「外観」および「動作」セクションを開き、属性を設定します。これらの属性設定の詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。
inputColor
コンポーネントでは、ユーザーがパレットから色を選択できます。これは、色のコードを入力するテキスト入力フィールドを表します。図11-16に示すように、ポップアップのパレットから色を選択するためのボタンも表示します。
デフォルトでは、ポップアップのコンテンツ配信は遅延です。ユーザーがボタンをクリックすると、inputColor
コンポーネントがPPRリクエストを受信し、レンダラがchooseColor
コンポーネントをpopup
コンポーネントに表示します。
パフォーマンスのヒント: inputColor コンポーネントのclientComponent 属性がtrue に設定されている場合、ポップアップおよびchooseColor コンポーネントは即時に配信されます。カラー・パレットが大きい場合、これは初期ページ・ロードのパフォーマンスに悪影響を与えることがあります。 |
デフォルトの色のコード形式は16進の色の形式です。ただし、ColorConverter
クラスを使用して書式設定をオーバーライドできます。
inputDate
コンポーネントを使用すると、図11-17に示すように、日付を入力するためのテキスト入力フィールドと、ポップアップ・カレンダから日付を選択するためのボタンを作成できます。デフォルトの日付フォーマットは、現在のロケールに適切な省略の日付フォーマットです。たとえば、米語(ENU)のデフォルトの書式はmm/dd/yy
です。ただし、この書式は日時コンバータを使用してオーバーライドできます(コンバータの使用方法の詳細は、7.3項「変換の追加」を参照してください)。
日時コンバータを追加して、日付と時間の両方を表示するように構成すると、ユーザーが時間を入力するための追加のコントロールのある日付ピッカーがモーダル・ダイアログとして表示されます。また、コンバータがタイム・ゾーンを表示するように構成されている場合、図11-18に示すようにタイムゾーン・ドロップダウン・リストがダイアログに表示されます。
inputColor
コンポーネントを使用すると、ユーザーによる入力テキスト・フィールドへの値の入力や、カラー・チューザからの色の選択が可能になります。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.5項「カラー・チューザおよび日付チューザの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
inputColorコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから「入力色」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタで、「共通」セクションを開いて次の設定を行います。
Label: コンポーネントのラベルを指定します。
Compact: 図11-19
に示すように、入力テキスト・フィールドを表示しない場合はtrueに設定します。
「データ」セクションを開き、次の属性を設定します。
Value: コンポーネントの値を指定します。value
のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。
ColorData: 標準のカラー・パレットに表示される色のリストを指定します。表示される色の数は、49(7色x7色)、64(8色x8色)または121(11色x11色)です。この属性に設定される数値により、width
属性の有効な値が決定されます。たとえば、colorData
属性を49に設定した場合、幅は7にする必要があります。色の数が幅に合っていない場合、リストの余分な色要素は無視され、欠落している色要素は色なしとして表示されます。色のリストは、クライアント側ではタイプTrColor
の配列であることが必要です。
CustomColorData: カスタム定義の色のリストを指定します。色の数は7、8、11のいずれかです。色のリストは、クライアント側ではタイプTrColor
の配列であることが必要です。サーバー側では、java.awt.Color
オブジェクトのList
または16進の色文字列のリストである必要があります。
DefaultColor: #000000
など、16進の色のコードを使用してデフォルトの色を指定します。
「外観」セクションを開き、次の属性を設定します。
Width: セルにおける標準のパレットの幅を指定します。有効な値は7、8および11で、colorData
およびcustomColorData
属性の値に対応します。
CustomVisible: 「カスタム・カラー」ボタンおよびカスタム・カラー行を表示するかどうかを指定します。true
に設定すると、「カスタム・カラー」ボタンおよびカスタム・カラー行がレンダリングされます。
DefaultVisible: 「デフォルト」ボタンを表示するかどうかを指定します。true
に設定すると、「デフォルト」ボタンがレンダリングされます。「デフォルト」ボタンを使用すると、ユーザーはdefaultColor
属性の値として、簡単に色のセットを選択できるようになります。
LastUsedVisible: 「最終使用」ボタンを表示するかどうかを指定します。true
に設定すると、「最終使用」ボタンがレンダリングされ、ユーザーは前回使用した色を選択できるようになります。
Editable: ユーザーがマウスを値の上に移動するまでコンポーネントの値を読取り専用にする場合は、onAccess
に設定します。コンポーネントを常に編集可能にする場合は、always
を選択します。値を祖先コンポーネントから継承する場合は、inherit
を選択します。
注意: inherit を選択し、どの祖先コンポーネントでもeditable 値が定義されていない場合は、always の値が使用されます。 |
ラベルのスタイルを設定する場合は、「スタイル」セクションを展開し、LabelStyleを設定します。ラベルのCSSスタイル・プロパティと値を入力します。たとえば、ラベル・テキストを折り返さない場合は、値にwhite-space:nowrap;
と入力します。
「動作」セクションを開き、次の属性を設定します。
ChooseId: 色の値を選択するために使用できるchooseColor
コンポーネントのid
を指定します。設定しない場合、inputColor
コンポーネントには、chooseColor
コンポーネントが使用された独自のデフォルトのポップアップ・ダイアログが使用されます。
AutoComplete: ユーザーが以前の値と一致する値の入力を開始した場合にコンポーネントがその値を表示できるようにする場合は、true
に設定します。一致を表示しない場合はfalse
に設定します。デフォルトはtrue
です。
inputDate
コンポーネントを使用すると、ユーザーは日付の入力または選択を実行できます。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.5項「カラー・チューザおよび日付チューザの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
inputDateコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから「入力日」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタの「共通」セクションで、次の設定を行います。
Label: コンポーネントのラベルを指定します。
Value: コンポーネントの値を指定します。value
のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。
オプションで、「スタイル」セクションを開き、LabelStyle属性をCSSスタイル・プロパティと値に設定します。たとえば、ラベル・テキストを折り返さない場合は、値としてwhite-space:nowrap;
を入力します。
「データ」セクションを開き、次の属性を設定します。
MinValue: 日付値に許可される最小値を指定します。タグで固定値に設定されている場合、この値はISO 8601の日付として解析されます。ISO 8601の日付は、yyyy-MM-dd(2002-02-15など)の形式です。この他すべての使用方法では、java.util.Date
オブジェクトが必要です。
MaxValue: 日付値に許可される最大値を指定します。タグで固定値に設定されている場合、この値はISO 8601の日付として解析されます。ISO 8601の日付は、yyyy-MM-dd(2002-02-15など)の形式です。この他すべての使用方法では、java.util.Date
オブジェクトが必要です。
DisableDays: org.apache.myfaces.trinidad.model.DateListProvider
インタフェースの実装へのバインディングを指定します。getDateList
メソッドによって、無効に指定される個々のjava.util.Date
オブジェクトのList
が生成されます。日付は、指定されたベース・カレンダのコンテキストに存在する必要があります。
パフォーマンスのヒント: このバインディングには、定期的なラウンドトリップが必要です。特定の曜日(土曜日および日曜日など)のみを無効にする場合は、disableDaysOfWeek 属性を使用します。 |
DisableDaysOfWeek: 各週に無効の状態でレンダリングする必要のある曜日を空白で区切ったリストで指定します。リストには、sun
、mon
、tue
、wed
、thu
、fri
、sat
の1つ以上の略語を含める必要があります。デフォルトでは、すべての曜日が有効です。
DisableMonths: 各年に無効の状態でレンダリングする必要のある月を空白で区切ったリストで指定します。リストには、jan、feb、mar、apr、may、jun、jul、aug、sep、oct、nov、dec
の1つ以上の略語を含める必要があります。デフォルトでは、すべての月が有効です。
「動作」セクションを開き、次の設定を行います。
ChooseId: 日付値を選択するために使用できるchooseDate
コンポーネントのid
を指定します。設定しない場合、inputDate
コンポーネントには、chooseDate
コンポーネントが使用された独自のポップアップ・ダイアログが使用されます。
AutoComplete: ユーザーが以前の値と一致する値の入力を開始した場合にコンポーネントがその値を表示できるようにする場合は、true
に設定します。一致を表示しない場合はfalse
に設定します。デフォルトはtrue
です。
ユーザーがマウスを値の上に移動するまでコンポーネントの値を読取り専用として表示する場合は、「外観」セクションを開き、EditableをonAccess
に設定します。コンポーネントを常に編集可能にする場合は、always
を選択します。値を祖先コンポーネントから継承する場合は、inherit
を選択します。
注意: inherit を選択し、どの祖先コンポーネントでもeditable 値が定義されていない場合は、always の値が使用されます。 |
デフォルトでは、関連付けられたコンバータがタイム・ゾーンを表示するように構成されている場合、たとえばコンバータのパターンにタイムゾーン・プレースホルダz
を含めた場合、inputDate
コンポーネントにはタイム・ゾーンのドロップダウン・リストが表示されます。エンド・ユーザーは、このリストを使用してタイムゾーンの変更のみ行うことができます。リストは、最も一般的なタイム・ゾーンを表示するように構成されています。
ただし、inputDate
コンポーネントの外部のタイム・ゾーンのリストを表示する必要がある場合があります。たとえば、「アプリケーション・プリファレンス」ページで、アプリケーションにすべてのinputDates
を表示するために使用されるタイム・ゾーンをユーザーが選択できるようにするselectOneChoice
コンポーネントを使用できます。バッキングBeanは、タイム・ゾーンIDとjava.util.TimeZone
オブジェクト間の変換を処理します。アプリケーションのinputDate
インスタンスのコンバータは、タイム・ゾーンをそのタイム・ゾーン・オブジェクトにバインドします。
DateTimeUtils
クラスのAPIを使用するか、コンポーネントでEL式を使用して、このリストにアクセスできます。
DateTimeUtils
クラスのメソッドを次に示します。
getCommonTimeZoneSelectItems ()
: よく使用されるタイム・ゾーンのリストを返します。
getCommonTimeZoneSelectItems (String timeZoneId)
: リストの一部でない特定のタイム・ゾーンを含め、よく使用されるタイム・ゾーンのリストを返します。
ELを使用してこのリストにアクセスするには、次のいずれかの式を使用します。
af:getCommonTimeZoneSelectItems
次に例を示します。
<f:selectItems value="#{af:getCommonTimeZoneSelectItems()}" id="tzones2" />
af:getMergedTimeZoneSelectItems (id)
次に例を示します。
<f:selectItems value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" id="tzones" />
inputDate
コンポーネントとそのタイム・ゾーンの選択リストを同じページで使用している場合は、inputDate
のタイムゾーンのローカル値をクリアして、選択の値バインディングが優先されるようにする必要があります。そうしないと、null以外のローカル値が優先され、inputDate
コンポーネントは更新されていないように見えます。例11-4では、バッキングBeanに、バインディング属性を使用したinputDate
コンポーネントへの参照があります。ユーザーが新しいタイム・ゾーンを選択すると、IDが設定され、コードがinputDate
のコンバータを取得し、そのタイム・ゾーンをクリアします。ページがレンダリングされる場合、コンバータのタイム・ゾーンのローカル値はnullであるため、#{demoInput.preferredTimeZone}
と評価され、更新されたタイム・ゾーンを取得します。
例11-4 inputDateとタイム・ゾーンの選択リストの併用
<af:selectOneChoice label="Select a new timezone" value="#{demoInput.preferredTimeZoneId}" autoSubmit="true"> <f:selectItems value="#{af:getMergedTimeZoneSelectItems(demoInput.preferredTimeZoneId)}" id="tzones" /> </af:selectOneChoice> <af:inputDate label="First inputDate with timezone bound" id="bound1" partialTriggers="tzpick" binding="#{demoInput.boundDate1}"> <af:convertDateTime type="both" timeStyle="full" timeZone="#{demoInput.preferredTimeZone}"/> </af:inputDate> DemoInputBean.java public void setPreferredTimeZoneId(String _preferredTimeZoneId) { TimeZone tz = TimeZone.getTimeZone(_preferredTimeZoneId); setPreferredTimeZone (tz); this._preferredTimeZoneId = _preferredTimeZoneId; } public void setPreferredTimeZone(TimeZone _preferredTimeZone) { this._preferredTimeZone = _preferredTimeZone; DateTimeConverter conv1 = (DateTimeConverter) _boundDate1.getConverter(); conv1.setTimeZone(null); }
選択コンポーネントを使用すると、ユーザーは項目のリストやグループから、単一または複数の値を選択できるようになります。ADF Facesには、単純なブール・ラジオ・ボタンから、ユーザーが複数の項目を選択できるリスト・ボックスまで、様々な選択コンポーネントがあります。選択コンポーネント内の項目のリストは、複数のselectItem
コンポーネントで構成されています。
selectItem
コンポーネントを除くすべての選択コンポーネントは、ValueChangeEvent
およびAttributeChangeEvent
イベントを送信します。selectItem
コンポーネントは、AttributeChangeEvent
イベントのみを送信します。これらのイベント用に、valueChangeListener
ハンドラまたはattributeChangeListener
ハンドラ(あるいはその両方)を作成する必要があります。
selectBooleanCheckbox
コンポーネント値は、常にオブジェクトではなくブール値に設定する必要があります。図11-20に示すように、選択状態と選択解除状態を切り替えます。
selectBooleanRadio
コンポーネントにはブール値の選択肢が表示され、常にブール値に設定する必要があります。selectBooleanCheckbox
コンポーネントとは異なり、selectBooleanRadio
コンポーネントを使用すると、同じgroup
属性を使用してselectBooleanRadio
コンポーネントをグループ化できます。
たとえば、ユーザーが10歳から18歳までの年齢かどうかを決定する1つのブール値と、ユーザーが19歳から100歳までの年齢かどうかを決定する別のブール値があるとします。図11-21に示すように、2つのselectBooleanRadio
コンポーネントをページの任意の場所に配置でき、これらは隣り合っている必要はありません。ページ内での物理的な配置にかかわらず、同じgroup
値を共有するかぎり、これらの選択は相互に排他的になります。
ヒント: 各selectBooleanRadio コンポーネントは、一意のブール値にバインドされている必要があります。 |
selectOneRadio
コンポーネントを使用して、図11-22に示すように、ユーザーが単一値を選択できるラジオ・ボタンのリストを作成します。
selectManyCheckbox
コンポーネントを使用して、図11-23に示すように、ユーザーが1つ以上の値を選択できるチェックボックスのリストを作成します。
selectOneListbox
コンポーネントを使用すると、図11-24に示すように、ユーザーは影付きのボックスに表示された項目のリストから値を1つ選択できるコンポーネントを作成できます。
selectManyListbox
コンポーネントは、ユーザーが項目リストから多くの値を選択できるコンポーネントを作成するものです。図11-25に示すように、このコンポーネントには、チェック・ボックスのリストの先頭に表示される「すべて」チェック・ボックスが含まれます。
selectOneChoice
コンポーネントを使用すると、ユーザーが項目のドロップダウン・リストから値を1つ選択できるメニュー形式のコンポーネントを作成できます。selectOneChoice
コンポーネントは、ドロップダウン・リストの項目が比較的少ない場合に使用します。
ベスト・プラクティス: 多数の項目が必要な場合は、inputComboboxListOfValues コンポーネントを使用します。詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。 |
図11-26に、selectOneChoice
コンポーネントを示します。
図11-27に示すように、selectOneChoice
コンポーネントは、コンパクト・モードで表示されるように構成できます。コンパクト・モードでは、入力フィールドが小さなアイコンに置き換えられます。
ユーザーがアイコンをクリックすると、図11-28に示されているようにドロップダウン・リストが表示されます。
selectManyChoice
コンポーネントを使用すると、ユーザーが項目のドロップダウン・リストから複数の値を選択できるメニュー形式のドロップダウン・コンポーネントを作成できます。このコンポーネントは、選択項目のリストの先頭に表示される「すべて」選択項目を含めるように構成できます。図11-29に示すように、選択肢の数が15より多い場合は、スクロールバーが表示されます。
デフォルトでは、すべてのselectItem
子コンポーネントは、ページがレンダリングされるときに、selectManyChoice
コンポーネントの作成時に作成されます。ただし、リスト項目がアクセスされる方法が低速な場合は、パフォーマンスが低下することがあります。この遅延は、ユーザーが項目を1回選択し、その後のアクセス時に変更しない可能性が高い場合に、特に問題になることがあります。
たとえば、ページに表示される内容のフィルタに使用されるselectManyChoice
コンポーネントがあり、子selectItem
コンポーネントの値がWebサービスからアクセスされるとします。ユーザーが、ページにアクセスするたびに選択内容を変更する可能性が低いことも想定します。デフォルトでは、ページがレンダリングされるたびに、ユーザーが実際に参照する必要があるかどうかにかかわらず、すべてのselectItems
を構築する必要があります。かわりに、selectManyChoice
コンポーネントのcontentDelivery
属性をimmediate
(デフォルト)からlazy
に変更できます。lazy
設定により、selectItem
コンポーネントはユーザーがドロップダウンをクリックしたときにのみ作成されます。
immediate
とlazy
のどちらでも、ユーザーが選択を行うと、選択されたselectItem
コンポーネントの値がフィールドに表示されます。ただし、遅延コンテンツ配信が使用されている場合は、その後のアクセス時に、選択された値をselectItem
コンポーネントから取得する(これにより、これらのコンポーネントの作成が必要になります)かわりに、値がlazySelectedLabel
属性から取得されます。この属性は、通常、選択された項目を表すStrings
の配列を返すメソッドにバインドされます。selectItem
コンポーネントは、ユーザーがドロップダウンを使用してこれらを表示または変更するまで作成されません。
selectManyChoice
コンポーネントでlazy
配信メソッドを使用する場合は、制限事項があります。selectManyChoice
コンポーネントのコンテンツ配信とその制限事項の詳細は、11.6.2項「SelectManyChoiceコンポーネントのcontentDelivery属性について」を参照してください。
次のコンポーネントの場合、コントロールの上にラベルを表示させるには、これらをpanelFormLayout
コンポーネント内に配置します。
selectOneChoice
selectOneRadio
selectOneListbox
selectManyChoice
selectManyCheckbox
selectManyListbox
次のコンポーネントでは、セキュリティ上の理由から、属性disabled
、immediate
、readOnly
、required
、requireMessageDetail
およびvalue
をクライアント上のJavaScriptから設定することはできません(詳細は、4.6.1項「クライアントでのプロパティ値の設定方法」を参照してください)。
selectOneChoice
selectOneRadio
selectOneListbox
selectBooleanRadio
selectBooleanCheckbox
selectManyChoice
selectManyCheckbox
selectManyListbox
選択コンポーネントの追加手順は、どのコンポーネントでも同じです。まず、選択コンポーネントを追加して属性を構成します。次に、リスト内の個々の項目用に任意の数のselectItem
コンポーネントを追加して構成します。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.6項「選択コンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
選択コンポーネントを使用する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから選択コンポーネントをページにドラッグ・アンド・ドロップします。
selectBooleanCheckbox
およびselectBooleanRadio
コンポーネント以外のすべての選択コンポーネントで、マネージドBeanの値にバインドするか、静的リストを作成するかを選択するダイアログが開きます。ダイアログの2番目のページで、次のプロパティを設定できます。
Label: リストのラベルを入力します。
RequiredMessageDetail: ユーザーが選択を行わない場合に表示するメッセージを入力します。メッセージの詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。
Validator: マネージドBeanの検証メソッドに解決されるEL式を入力します(詳細は、第7章「入力の検証および変換」を参照してください)。
Value: コンポーネントの値を指定します。value
のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。
注意: selectBooleanRadio またはselectBooleanCheckbox コンポーネントを作成し、value 属性の値を入力する場合、selected 属性はvalue 属性の型安全な別名であるため値を入力できません。両方を使用することはできません。 |
ValueChangeListener: 値変更イベントを処理するマネージドBeanのリスナーに解決されるEL式を入力します。
プロパティ・インスペクタの「外観」セクションを開き、表11-1に説明されている属性を設定します。ここで説明するのは、選択コンポーネントに固有の属性のみであることに注意してください。多くの属性は、テキスト入力コンポーネントと同じです。詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。
表11-1 選択コンポーネントの外観属性
コンポーネント | 属性 |
---|---|
|
Layout: |
|
Size: リストに表示する項目の数に設定します。リスト内の項目数が |
|
SelectAllVisible: |
|
Mode: |
|
UnselectedLabel: 値が |
プロパティ・インスペクタの「動作」セクションを開き、表11-2に説明されている属性を設定します。ここで説明するのは、選択コンポーネントに固有の属性のみであることに注意してください。多くの属性は、テキスト入力コンポーネントと同じです。詳細は、11.3.1項「inputTextコンポーネントの追加方法」を参照してください。
表11-2 選択コンポーネントの動作属性
コンポーネント | 属性 |
---|---|
ブール選択コンポーネントを除くすべて |
ValuePassThru: クライアントに値を渡すかどうかを指定します。 選択コンポーネントがADFモデル・バインディングを使用している場合、この値は無視されます。 |
|
Group: 同じ |
ユーザーがマウスを値の上に移動するまでselectOneChoice
またはselectManyChoice
コンポーネントの値を読取り専用として表示する場合は、「外観」セクションを開き、EditableをonAccess
に設定します。コンポーネントを常に編集可能にする場合は、always
を選択します。値を祖先コンポーネントから継承する場合は、inherit
を選択します。
注意: inherit を選択し、どの祖先コンポーネントでもeditable 値が定義されていない場合は、always の値が使用されます。 |
ページがレンダリングされるたびにselectManyChoice
の子selectItem
コンポーネントを作成しない場合は、次の操作を実行します。
選択した項目のラベルを格納でき、それらのラベルを文字列の配列として返すロジックを作成します。
「拡張」セクションを開き、ContentDeliveryをlazyに設定します。
LazySelectedLabelを、選択した項目の配列を返すメソッドにバインドします。
遅延コンテンツ配信の使用には制限があることに注意してください。selectManyChoice
コンポーネントのコンテンツ配信の詳細は、11.6.2項「SelectManyChoiceコンポーネントのcontentDelivery属性について」を参照してください。
ブール・コンポーネントの場合は、ブール・コンポーネントの子として、任意の数のselectItem
コンポーネントをドラッグ・アンド・ドロップします。これらはリストの項目を表します(その他の選択コンポーネントの場合は、手順2のダイアログにより自動的に追加されます)。
selectItem
コンポーネントが選択された状態で、プロパティ・インスペクタの「共通」セクションを開き、設定されていない場合はvalue
属性に値を入力します。これが送信される値です。
「外観」セクションを開き、設定されていない場合はLabelの値を入力します。これがリストに表示されるテキストです。
項目が無効化された状態でリストに表示されるようにする場合は、「動作」セクションを開いて、Disabledをtrue
に設定します。
selectManyChoice
コンポーネントのcontentDelivery
属性がimmediate
(デフォルト)に設定されている場合は、次のようになります。
ページへの初回アクセス時:
ページがレンダリングされると、selectManyChoice
およびすべてのselectItem
コンポーネントが作成されます。これは、多くの項目がある場合、またはselectItem
コンポーネントの値がたとえばWebサービスからアクセスされる場合に、パフォーマンスの問題を引き起こすことがあります。
selectManyChoice
コンポーネントのレンダリング時に、まだ何も選択されていないためフィールドには何も表示されません。
ユーザーがドロップ・ダウンをクリックすると、すべての項目が表示されます。
ユーザーが項目を選択すると、選択したselectItem
コンポーネントに対応するラベルがフィールドに表示されます。
ページが送信されると、値がモデルにポストバックされます。
その後のアクセス時: ページがレンダリングされると、selectManyChoice
およびすべてのselectItem
コンポーネントが再び作成されます。選択したselectItem
コンポーネントのラベルがフィールドに表示されます。これは、ページへの初回アクセス時と同じパフォーマンスの問題の原因となります。
selectManyChoice
コンポーネントのcontentDelivery
属性がlazy
に設定されている場合は、次のようになります。
ページへの初回アクセス時:
selectManyChoice
はページがレンダリングされると作成されますが、selectItem
コンポーネントは作成されません。
selectManyChoice
コンポーネントのレンダリング時に、まだ何も選択されていないためフィールドには何も表示されません。
ユーザーがドロップ・ダウンをクリックすると、selectItem
コンポーネントが作成されます。この状況が発生している間、ユーザーには"ビジー"・スピナーが表示されます。コンポーネントが作成されると、すべての項目が表示されます。
ユーザーが項目を選択すると、選択したselectItem
コンポーネントに対応するラベルがフィールドに表示されます。
ページが送信されると、値がモデルにポストバックされます。
その後のアクセス時:
ページの初回レンダリング時には、selectManyChoice
コンポーネントのみ作成されます。この時点で、lazySelectedLabel
属性の値を使用して、選択された項目が表示されます。
ユーザーがドロップ・ダウンをクリックすると、selectItem
コンポーネントが作成されます。この状況が発生している間、ユーザーには"ビジー"・スピナーが表示されます。コンポーネントが作成されると、すべての項目が表示されます。
selectItem
コンポーネントが作成されると、selectManyChoice
コンポーネントはcontentDelivery
属性がimmediate
に設定されているかのように動作し、selectItem
コンポーネントの実際の値を使用して、選択された項目を表示します。
selectManyChoice
コンポーネントでの遅延コンテンツ配信の使用には、次の制限があります。
selectManyChoice
の値をリクエスト・スコープに格納することはできません。ポストバックでは、value属性はクライアントから返された内容をデコードするかわりにモデルからアクセスされます。値がリクエスト・スコープに格納される場合、その値は空になります。リクエスト・スコープには値を格納しないでください。
ポストバックでは、コンバータはコールされません。ポストバックをコンバータに依存している場合は、遅延コンテンツ配信を使用しないでください。
スクリーン・リーダー・モードでは、contentDelivery
属性は無視されます。selectItem
コンポーネントは、ページのレンダリング時に必ず作成されます。
selectManyShuttle
およびselectOrderShuttle
コンポーネントを使用すると、ユーザーが一方のリスト・ボックスからもう一方のリスト・ボックスに項目を移動するための2つのリスト・ボックスおよびボタンを作成できます。ユーザーは、先行(Available values)リスト・ボックスと後続(Selected values)リスト・ボックスの間を移動させる単一の項目または複数の項目を選択できます。どちらのコンポーネントでも、コントロールの上にラベルを表示する場合には、それらをpanelFormLayout
コンポーネント内に配置します。
図11-30に、selectManyShuttle
コンポーネントを示します。
図11-31に示すように、selectOrdershuttle
コンポーネントには、ユーザーが「選択した値」リスト・ボックスの値を並べ替えるために使用する上矢印および下矢印ボタンを追加で含めることができます。リストを並べ替えると、ValueChangeEvent
イベントが送信されます。readOnly
属性をtrue
に設定した場合は、並べ替える値が、後続リスト(「選択した値」)に表示される選択済の値であることを確認します。
他のselectMany
コンポーネント同様、これらのコンポーネントのvalue
属性は、含まれるselectItem
コンポーネントの1つの値と一致する値のList
またはArray
である必要があります。selectItems
の1つの値がList
またはArray
にある場合、その項目は後続リストに表示されます。selectManyListbox
コンポーネントをselectManyShuttle
に直接変換することもできます。リストボックスでどの項目が選択されているかを確認するvalue
にかわり、これがselectOrderShuttle
コンポーネントの後続リストに表示される項目の選択に影響します。
その他の選択コンポーネント同様、項目のリストまたは配列は、selectManyShuttle
またはselectOrderShuttle
コンポーネントにネストしているselectItem
コンポーネントで構成されています。例11-5に、ユーザーがファイル・タイプのリストから上位5つのファイル・タイプを選択できるselectOrderShuttle
コンポーネントのサンプルを示します。
例11-5 selectOrderShuttleのJSFページ・コード
<af:selectOrderShuttle value="#{helpBean.topFive}" leadingHeader="#{explorerBundle['help.availableFileTypes']}" trailingHeader="#{explorerBundle['help.top5']}" simple="true"> <af:selectItem label="XLS"/> <af:selectItem label="DOC"/> <af:selectItem label="PPT"/> <af:selectItem label="PDF"/> <af:selectItem label="Java"/> <af:selectItem label="JWS"/> <af:selectItem label="TXT"/> <af:selectItem label="HTML"/> <af:selectItem label="XML"/> <af:selectItem label="JS"/> <af:selectItem label="PNG"/> <af:selectItem label="BMP"/> <af:selectItem label="GIF"/> <af:selectItem label="CSS"/> <af:selectItem label="JPR"/> <af:selectItem label="JSPX"/> <f:validator validatorId="shuttle-validator"/> </af:selectOrderShuttle>
selectOrdershuttle
コンポーネントのreorderOnly
属性をtrue
に設定すると、移動機能が無効にされ、「選択した値」リスト・ボックスのみが表示されます。図11-32に示すように、ユーザーは、リスト・ボックス内の項目の並替えのみを実行できます。
シャトル・コンポーネントの追加手順は、どちらのコンポーネントも同じです。まず、選択コンポーネントを追加して属性を構成します。次に、リスト内の個々の項目用に任意の数のselectItem
コンポーネントを追加して構成します。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.7項「シャトル・コンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
selectManyShuttleまたはselectOrderShuttleコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから「シャトル」または「シャトル(順序付け済)」をページにドラッグ・アンド・ドロップします。
マネージドBeanの値にバインドするか、静的リストを作成するかを選択するダイアログが表示されます。ダイアログの2番目のページで、次の設定を行うことができます。
Label: リストのラベルを入力します。
RequiredMessageDetail: ユーザーが選択を行わない場合に表示するメッセージを入力します。メッセージの詳細は、19.3項「検証および変換用のヒントとエラー・メッセージの表示」を参照してください。
Size: リストの表示サイズ(項目の数)を指定します。指定するサイズは、10から20項目の範囲である必要があります。属性が設定されていない場合、または10より小さい値の場合、サイズはデフォルトまたは最小値の10になります。指定された属性値が20項目より多い場合、サイズは最大値の20になります。
Validator: マネージドBeanの検証メソッドに解決されるEL式を入力します。
Value: コンポーネントの値を指定します。value
のELバインディングが、set
メソッドではなくget
メソッドが指定されているBeanプロパティを指している場合、コンポーネントは読取り専用モードでレンダリングされます。
ValueChangeListener: 値変更イベントを処理するマネージドBeanのリスナーに解決されるEL式を入力します。
プロパティ・インスペクタで、「外観」セクションを開いて次の設定を行います。
Layout: コンポーネントを水平または垂直レイアウトのどちらにするかを指定します。デフォルトはhorizontal
で、先行および後続のリスト・ボックスは相互に隣り合って表示されます。vertical
に設定すると、先行のリスト・ボックスは後続のリスト・ボックスの上に表示されます。
LeadingHeader: シャトル・コンポーネントの先行リストのヘッダー・テキストを指定します。
LeadingDescShown: true
に設定すると、先行のリスト・ボックスの下部に選択された項目の説明が表示されます。
TrailingHeader: シャトル・コンポーネントの後続リストのヘッダーを指定します。
TrailingDescShown: true
に設定すると、後続のリスト・ボックスの下部に選択された項目の説明が表示されます。
「動作」セクションを開き、オプションで次の属性を設定します。
ValuePassThru: クライアントに値を渡すかどうかを指定します。valuePassThru
がfalse
の場合、この値およびオプションの値は、索引に変換されてからクライアントに送信されます。そのため、valuePassThru
がfalse
の場合、値またはオプション、あるいはその両方としてカスタム・オブジェクトを使用するときに、独自のコンバータを記述する必要はありません。クライアント側での実際の値を知る必要がある場合は、valuePassThru
をtrue
に設定できます。これにより、カスタム・コンバータが使用可能な場合は、カスタム・コンバータを使用して、クライアントに値が渡されます。カスタム・コンバータは、カスタム・オブジェクトを使用する場合に必要です。デフォルトはfalse
です。
ReorderOnly(selectOrderShuttle
コンポーネントのみ): シャトル・コンポーネントを並替え専用モードにするかどうかを指定します。このモードでは、ユーザーは値リストの順序を変更できますが、追加や削除はできません。
構造ウィンドウでselectItem
コンポーネントの1つを選択し、プロパティ・インスペクタで必要な属性を設定します。
ヒント: 先行または後続のリスト・ボックスに説明を表示することを選択した場合は、各selectItem コンポーネントのshortDesc 属性に値を設定する必要があります。 |
項目の選択のイベントに応答して処理を実行するJavaScriptコードを作成することで、ユーザーが選択された各項目をあるリストから別のリストに移動する前に、その項目に関する情報をユーザーに提供できます。たとえば、コードでその項目に関する追加情報を取得し、ユーザーが項目を移動するかどうかの選択を行えるようにポップアップとして表示できます。図11-33に、ユーザーがMeyersを選択し、ポップアップがこの選択に関する追加情報を提供するselectManyShuttle
コンポーネントを示します。
この機能は、selectManyShuttle
またはselectOrderShuttle
コンポーネントにクライアント・リスナーを追加し、このイベントを処理するJavaScriptメソッドを作成して実装します。JavaScriptコードは、ユーザーがリストから項目を選択すると実行されます。イベントのクライアント・リスナーの詳細は、4.2項「クライアント・イベントのリスニング」を参照してください。
選択イベントを処理するシャトル・コンポーネントにクライアント・リスナーを追加する方法:
コンポーネント・パレットで、「操作」パネルの「リスナー」グループから「クライアント・リスナー」をドラッグし、シャトル・コンポーネントに子としてドロップします。
「クライアント・リスナーの挿入」ダイアログで、「メソッド」フィールドに関数名(次の手順でこの関数を実装します)を入力し、「タイプ」ドロップダウンから「propertyChange
」を選択します。
たとえば、関数としてshowDetailsを入力した場合、JDeveloperにより、例11-6に太字で示されたコードが入力されます。
例11-6 選択を登録するためのclientListenerの使用
<af:selectManyShuttle value="#{demoInput.manyListValue1}"
valuePassThru="true" ...>
<af:clientListener type="propertyChange" method="showDetails"/>
<af:selectItem label="coffee" value="bean" />
...
</af:selectManyShuttle>
このコードにより、showDetails
関数は、プロパティ値が変更されるたびにコールされます。
JavaScriptで、前の手順で入力された関数を実装します。この関数により、次の操作が実行されます。
イベントのソースを取得して、シャトル・コンポーネントを取得します。
クライアントJavaScript APIコールを使用して、選択した項目の情報を取得します。
例11-7では、AdfShuttleUtils.getLastSelectionChange
をコールして、最後に選択された項目の値が取得されています。
例11-7 選択の処理に使用されるJavaScriptメソッドshowDetailsのサンプル
function showDetails(event)
{
if(AdfRichSelectManyShuttle.SELECTION == event.getPropertyName())
{
var shuttleComponent = event.getSource();
var lastChangedValue = AdfShuttleUtils.getLastSelectionChange(shuttleComponent, event.getOldValue());
var side = AdfShuttleUtils.getSide(shuttleComponent, lastChangedValue);
if(AdfShuttleUtils.isSelected(shuttleComponent, lastChangedValue))
{
//do something...
}
else
{
//do something else
}
if(AdfShuttleUtils.isLeading(shuttleComponent, lastChangedValue))
{
//queue a custom event (see serverListener) to call a java method on the server
}
}
}
richTextEditor
コンポーネントは、書式設定されたテキストを使用できる入力フィールドを提供します。ラベル、テキストおよびメッセージもサポートされています。ユーザーは、フォント名、サイズ、スタイルの変更、順序付けられたリストの作成、およびテキストの両端の調整を実行でき、その他の様々な機能も使用できます。richTextEditor
コンポーネントは、HTMLソース・ファイルの編集にも使用できます。2つのコマンド・ボタンを使用して、標準の書式設定されたテキストの編集とHTMLソース・ファイルの編集を相互に切り替えられます。図11-34に、標準のリッチ・テキスト編集モードのリッチ・テキスト・エディタ・コンポーネントを示します。
図11-35に、ソース・コード編集モードのエディタを示します。
次にサポートされているその他の機能を示します。
フォント・タイプ
フォント・サイズ
リンク付け/リンク解除
スタイルのクリア
元に戻す/やり直し
太字/イタリック/下線
下付き/上付き
調整(左、中央、右、均等)
順序付けられたリスト/順序付けられていないリスト
インデント
文字色/背景色
リッチ・テキスト編集モード/ソース・コード編集モード
リッチ・テキスト・エディタの値(入力されたテキスト)は、整形式XHTMLフラグメントです。値の書式設定を可能にするために、ブラウザ固有の要件で値の一部が変更される場合があります。また、セキュリティ上の理由から、スクリプト関連タグや属性などの一部の機能が削除されます。このコンポーネントにより、ユーザーによる最小限の変更のみが記録されるという保証はありません。エディタでXHTMLドキュメントを編集しているため、次の要素が変更される可能性があります。
意味のない空白
要素の最小化
要素タイプ
属性の順序
文字エンティティの使用
エディタでサポートされているのは、次の例外を除いて4つのHTMLタグのみです。
script、noscript
frame、frameset、noframes
フォーム関連要素(input、select、optgroup、option、textarea、form、button、label、isindex)
ドキュメント関連要素(html、head、body、meta、title、base、link)
richTextEditor
コンポーネントでは、コンテンツを取得するタグ(applet
、iframe
、object
、img
およびa
など)もサポートされています。ブラウザで許可されているのは同じドメインのコンテンツとの対話のみであるため、iframe
タグの場合は、コンテンツがページのその他の部分と対話できないようにする必要があります。ただし、ページのこの部分はアプリケーションの管理外です。
richTextEditor
コンポーネントではpx
やem
などのフォント単位はサポートされていませんが、HTML仕様に説明されているように1から7のフォント・サイズはサポートされています。埋込みタグや未知のタグ(<foo>
など)はサポートされていません。
クライアント側では、richTextEditor
コンポーネントで、getValue
およびsetValue
メソッドがサポートされていません。クライアント上のコンポーネントの値が、サーバー上の値と同一であるという保証はありません。そのため、richTextEditor
では、クライアント側のコンバータおよびバリデータがサポートされていません。それでも、サーバー側のコンバータおよびバリデータは機能します。
リッチ・テキスト・エディタでは、ValueChangeEvent
およびAttributeChangeEvent
イベントが送信されます。必要に応じて、これらのイベント用にvalueChangeListener
およびattributeChangeListener
ハンドラを作成します。
コマンド・コンポーネントと連携して、richTextEditor
コンポーネントに特定のテキストを挿入するrichTextEditorInsertBehavior
タグも構成できます。入力するテキストには、簡単な文字列、またはマネージドBeanなどに保持されている事前フォーマット済テキストを指定できます。
デフォルトでは、richTextEditor
コンポーネントのツールバーでは、図11-36に示すように、ユーザーはフォント、フォントのサイズと太さ、テキストの文字位置、表示モードなどの多くの側面を変更できます。
図11-37に、カスタマイズされているツールバーを示します。ツールバー・ボタンの多くは削除されており、カスタム・ツールバー・ボタンおよびメニューのあるツールバーが追加されています。
richTextEditor
コンポーネントを追加した後で、テキストを特定の場所に挿入できるように構成し、ツールバーをカスタマイズすることもできます。詳細は、11.8.2項「richTextEditorコンポーネントへのテキストの挿入機能を追加する方法」および11.8.3項「ツールバーのカスタマイズ方法」を参照してください。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.8項「richTextEditorコンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
richTextEditorコンポーネントを追加する手順:
コンポーネント・パレットで、「テキストおよび選択」パネルから「リッチ・テキスト・エディタ」をページにドラッグ・アンド・ドロップします。
プロパティ・インスペクタの「共通」セクションを開き、value
属性を設定します。
「外観」セクションを開き、次の設定を行います。
Rows: 表示される文字の概数で編集ウィンドウの高さを指定します。
Columns: 表示される文字の概数で編集ウィンドウの幅を指定します。
Label: コンポーネントのラベルを指定します。
「動作」セクションを開き、次の設定を行います。
EditMode: WYSIWYGまたはソース・モードを使用してエディタを表示するかどうかを選択します。
ContentDelivery: コンポーネントが最初にレンダリングされる際に、エディタ内のデータをフェッチするかどうかを指定します。contentDelivery
属性の値がimmediate
の場合、レンダリングされる際に、データがフェッチされてコンポーネントに表示されます。値がlazy
に設定されている場合は、データがフェッチされて後続のリクエスト中にクライアントに送信されます。詳細は、12.2.2項「コンテンツの配信」を参照してください。
ヒント: richTextEditor コンポーネントの幅は、全幅または100%に設定できます。ただし、これが確実に機能するのは、エディタがジオメトリ管理の親コンポーネントに配置されている場合のみです。panelFormLayout またはpanelGroupLayout などの配置レイアウト・コンテナに配置されていると、機能しない場合があります。詳細は、9.2.1項「ジオメトリ管理およびコンポーネントの拡大」を参照してください。 |
richTextEditor
コンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてrichTextEditorInsertBehavior
タグを追加します。
前提作業
リッチ・テキスト・エディタ・コンポーネントに関する知識が役立つ場合があります。詳細は、11.8項「richTextEditorコンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
11.8.1項「richTextEditorコンポーネントの追加方法」の説明に従ってrichTextEditor
コンポーネントを作成する必要があります。clientComponent
属性をtrue
に設定します。
テキスト挿入動作を追加する手順:
テキストを挿入するためにユーザーがクリックするコマンド・コンポーネントを追加します。手順は、20.3.1項「コマンド・ボタンおよびコマンド・リンクの使用方法」を参照してください。
コンポーネント・パレットで、「操作」パネルの「動作」グループから「リッチ・テキスト・エディタの挿入動作」をコマンド・コンポーネントに子としてドラッグ・アンド・ドロップします。
リッチ・テキスト・エディタの挿入動作ダイアログで、次の内容を入力します。
For: ドロップダウン矢印を使用して「編集」を選択し、テキストを挿入するrichTextEditor
コンポーネントに移動して選択します。
Value: 挿入するテキストの値を入力します。静的テキストを挿入する場合は、そのテキストを入力します。ユーザーが別のコンポーネントの値(selectOneChoice
コンポーネントの値など)を挿入できるようにする場合は、その値に解決されるEL式を入力します。ユーザーに事前フォーマット済テキストを入力させる場合は、そのテキストに解決されるEL式を入力します。たとえば、例11-8は、demoInput
マネージドBeanの属性の値としての事前フォーマット済テキストを示しています。
例11-8 マネージドBeanの事前フォーマット済テキスト
private static final String _RICH_INSERT_VALUE = "<p align=\"center\" style=\"border: 1px solid gray; margin: 5px; padding: 5px;\">" + "<font size=\"4\"><span style=\"font-family: Comic Sans MS, Comic Sans,cursive;\">Store Hours</span></font><br/>\n" + "<font size=\"1\">Monday through Friday 'til 8:00 pm</font><br/>\n" + "<font size=\"1\">Saturday & Sunday 'til 5:00 pm</font>" + "</p>";
例11-9に、テキストがrichTextEditorInsertBehavior
タグからどのように参照されるかを示します。
例11-9 richTextEditorInsertBehaviorタグの使用
<af:richTextEditor id="idRichTextEditor" label="Rich text value" value="#{demoInput.richValue2}"/> . . . </af:richTextEditor> <af:commandButton text="Insert Template Text"> <af:richTextEditorInsertBehavior for="idRichTextEditor" value="#{demoInput.richInsertValue}"/> </af:commandButton>
デフォルトでは、コマンド・コンポーネントをクリックしてアクション・イベントがトリガーされるとテキストが挿入されます。ただし、triggerType
属性のドロップダウン・メニューからイベントを選択することで、これを別のクライアント・イベントに変更できます。
作成するカスタム・ファセットに、追加するツールバーおよびツールバー・ボタンを配置します。次に、含まれている項目の表示方法および表示場所を決定するキーワードとともに、ツールバーの属性からファセットを参照します。
richTextEditor
コンポーネントにテキストを挿入できるようにするには、テキストの挿入に使用されるコマンド・コンポーネントの子としてrichTextEditorInsertBehavior
タグを追加します。
前提作業
リッチ・テキスト・エディタ・コンポーネントに関する知識が役立つ場合があります。詳細は、11.8項「richTextEditorコンポーネントの使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
ツールバーをカスタマイズする手順:
コンポーネント・パレットの「JSF」ページで、「コア」パネルから、追加するツールバーの各セクションの「ファセット」をドラッグ・アンド・ドロップします。たとえば、図11-37に示されているカスタム・ボタンを追加するには、2つの<f:facet>
タグを追加します。各ファセットには、ページに対する一意な名前を付けてください。
ヒント: ADF Facesの今後のリリースと競合が生じないようにするには、すべてのファセット名をcustomToolbar で開始します。 |
コンポーネント・パレットの「ADF Faces」ページで、「メニューおよびツールバー」パネルから「ツールバー」を各ファセットにドラッグ・アンド・ドロップし、ツールバー・ボタンまたはその他のコンポーネントを追加し、必要に応じて構成します。ツールバーとツールバー・ボタンの詳細は、16.3項「ツールバーの使用方法」を参照してください。
richTextEditor
コンポーネントを選択した状態で、プロパティ・インスペクタの「外観」セクションで、toolboxLayout
属性のドロップダウン・アイコンをクリックし、「編集」を選択して「プロパティの編集: ToolboxLayout」ダイアログを開きます。この属性の値は、カスタム・ファセット名のリストに、カスタム・ファセット内のコンテンツを表示する順序で設定する必要があります。これらのファセットのみでなく、次のキーワードを使用して、デフォルトのツールバーのすべてまたは一部を含めることもできます。
all
: デフォルトのツールバーのすべてのツールバー・ボタンおよびテキスト。all
が入力された場合、カスタムでないボタンのキーワードは無視されます。
font
: フォント選択およびフォント・サイズ・ボタン。
history
: 元に戻すボタンと再実行ボタン。
mode
: リッチ・テキスト・モードおよびソース・コード・モード・ボタン。
color
: 前景色および背景色ボタン。
formatAll
: 太字、イタリック、下線、上付き、下付き、取消線ボタン。formatAll
が指定されている場合、formatCommon
およびformatUncommon
は無視されます。
formatCommon
: 太字、イタリックおよび下線ボタン。
formatUncommon
: 上付き、下付きおよび取消線ボタン。
justify
: 左、中央、右および両端揃えボタン。
list
: 箇条書きおよび番号付きリスト・ボタン。
indent
: アウトデントおよびインデント・ボタン。
link
: リンクの追加および削除ボタン。
たとえば、customToolbar1
およびcustomToolbar2
という名前の2つのファセットを作成し、デフォルトのツールバー全体をカスタム・ツールバーの間に表示する場合は、次のリストを入力します。
customToolbar1
all
customToolbar2
ツールバーのレイアウトは、次のキーワードを使用して決定することもできます。
newline
: 新しい行の次の名前付きファセット(またはtoolboxLayout
属性のリストの次のキーワード)にツールバーを配置します。たとえば、customToolbar2
ファセットのツールバーを新しい行に表示する場合は、次のリストを入力します。
customToolbar1
all
newline
customToolbar2
かわりに、デフォルトのすべてのツールバーを使用せず、フォント、色および共通書式設定ボタンのみ使用し、これらのボタンを新しい行に表示する場合は、次のリストを入力します。
customToolbar1
customToolbar2
newline
font
color
formatCommon
stretch
: 使用可能なすべての領域を埋めるために拡大されるspacerコンポーネントを追加して、次の名前付きファセット(またはデフォルトのツールバーの次のキーワード)がツールバーに右揃えで表示されるようにします。
inputFile
コンポーネントを使用すると、ユーザーにファイルのアップロード機能および更新機能を提供できます。このコンポーネントを使用すると、ユーザーはローカル・ファイルを選択し、サーバー上の選択可能な場所にアップロードできます(ファイルをサーバーからユーザーにダウンロードするには、20.5.1項「ファイルをダウンロードするためのコマンド・コンポーネントの使用方法」を参照してください)。
inputFile
コンポーネントにより、ファイルのアップロード時に標準のValueChangeEvent
イベントが送信され、ロード・プロセスが透過的に管理されます。inputFile
コンポーネントのvalue
プロパティは、ファイルのアップロード時に、org.apache.myfaces.trinidad.model.UploadedFile
クラスのインスタンスに設定されます。
アップロード・プロセスを開始するには、まず、アップロードを許可するようにページのフォームを構成する必要があります。次に、図11-38に示すように、ファイルのアップロードに使用できるコマンド・ボタンなどのアクション・コンポーネントを作成します。
ファイルがアップロードされ、(最初のロードが成功した後またはその値が初期値として指定された後に)inputFile
の値がnull以外の場合は、「更新」ボタンを作成できます。図11-39に示されているように、このボタンは「参照」ボタンのかわりに表示されます。これにより、ユーザーはinputFile
コンポーネントの値を変更できます。
注意: ファイルがアップロードされると、inputFile コンポーネントの値はorg.apache.myfaces.trinidad.model.UploadedFile クラスのインスタンスになります。したがって、値(つまりファイル自体)にアクセスする必要がある場合は、このクラスにアクセスする必要があります。binding 属性を通じてコンポーネントにアクセスすると、コンポーネントにのみアクセスし、アップロード・ファイルにはアクセスしません。 |
readOnly
プロパティをtrue
に設定すると、特定のファイルのみをロードできるようにコンポーネントを指定することもできます。図11-40に示すように、このモードでは、指定されたファイルのみをロードできます。
inputFile
コンポーネントは、h:form
タグまたはaf:form
タグに配置できますが、どちらの場合も、ファイルのアップロードをサポートするようにformタグを設定必要があります。JSFの基本HTMLであるh:form
を使用する場合は、enctype
をmultipart/form-data
に設定します。これにより、リクエストはサーバーへのファイル・アップロードをサポートするためのマルチパート・リクエストになります。ADF Facesのaf:form
タグを使用している場合は、usesUpload
をtrue
に設定します。これは、enctypeをmultipart/form-data
に設定してファイル・アップロードをサポートするのと同じ機能を実行します。
ADF Facesフレームワークでは、ファイルの汎用アップロードが実行されます。アップロード後にファイルを処理(たとえば、xml
ファイル、pdf
ファイルなどの処理)するには、actionListener
またはアクション・メソッドを作成する必要があります。
inputFile
コンポーネントのvalue
は、org.apache.myfaces.trinidad.model.UploadedFile
インタフェースのインスタンスです。このAPIを使用すると、ファイル名、MIMEタイプ、サイズだけでなく、ファイルの実際のバイト・ストリームを取得できます。
注意: APIを使用して、ファイルのアップロード元に関するパス情報をクライアントから取得することはできません。 |
アップロードされたファイルは、ファイルとしてファイル・システムに格納できますが、メモリーに格納することもできます。この違いがAPIよって表面化されることはありません。フィルタを使用すると、リクエストの完了後、確実にUploadedFile
コンテンツがクリーン・アップされます。このため、複数のリクエストにわたってUploadedFile
オブジェクトを有効にキャッシュすることはできません。ファイルを保持する必要がある場合は、リクエストが完了する前にファイルを永続記憶域にコピーする必要があります。
たとえば、例11-10に示すように、ファイルを保存するかわりに、マネージドBeanをValueChangeEvent
イベントへのレスポンスとして使用し、ファイルのアップロードが成功したという内容のメッセージを追加します。
例11-10 アップロード・メッセージを表示するためのvalueChangeListenerの使用
JSF Page Code -----> <af:form usesUpload="true"> <af:inputFile label="Upload:" valueChangeListener="#{managedBean.fileUploaded}"/> <af:commandButton text="Begin"/> </af:form> Managed Bean Code ----> import javax.faces.application.FacesMessage; import javax.faces.context.FacesContext; import javax.faces.event.ValueChangeEvent; import org.apache.myfaces.trinidad.model.UploadedFile; public class ABackingBean { ... public void fileUploaded(ValueChangeEvent event) { UploadedFile file = (UploadedFile) event.getNewValue(); if (file != null) { FacesContext context = FacesContext.getCurrentInstance(); FacesMessage message = new FacesMessage( "Successfully uploaded file " + file.getFilename() + " (" + file.getLength() + " bytes)"); context.addMessage(event.getComponent().getClientId(context), message); // Here's where we could call file.getInputStream() } } }
また、例11-11に示すように、値をマネージドBeanに直接バインドすることでアップロードを処理できます。
例11-11 マネージドBeanへの値のバインド
JSF Page Code ----> <af:form usesUpload="true"> <af:inputFile label="Upload:" value="#{managedBean.file}"/> <af:commandButton text="Begin" action="#{managedBean.doUpload}"/> </af:form> Managed Bean Code ----> import org.apache.myfaces.trinidad.model.UploadedFile;public class AManagedBean { public UploadedFile getFile() { return _file; } public void setFile(UploadedFile file) { _file = file; } public String doUpload() { UploadedFile file = getFile(); // ... and process it in some way } private UploadedFile _file; }
Javaクラスは、inputFile
コンポーネントにバインドする必要があります。このクラスにより、アップロードしたファイルの値が含まれます。
始める前に:
属性が機能に与える影響に関する知識が役立つ場合があります。詳細は、11.9項「ファイルのアップロード機能の使用方法」を参照してください。
他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、11.1.2項「入力コンポーネントおよびフォームの追加機能」を参照してください。
inputFileコンポーネントを追加する手順:
入力ファイルの値を保持するJavaクラスを作成します。org.apache.myfaces.trinidad.model.UploadedFile
インタフェースのインスタンスであることが必要です。
af:form
コンポーネントを選択し、UsesUploadをtrueに設定します。
コンポーネント・パレットで、「テキストおよび選択」パネルから「入力ファイル」をページにドラッグ・アンド・ドロップします。
valueを手順1で作成したクラスに設定します。
ユーザーがマウスを値の上に移動するまでコンポーネントの値を読取り専用として表示する場合は、「外観」セクションを開き、EditableをonAccess
に設定します。コンポーネントを常に編集可能にする場合は、always
を選択します。値を祖先コンポーネントから継承する場合は、inherit
を選択します。
注意: inherit を選択し、どの祖先コンポーネントでもeditable 値が定義されていない場合は、always の値が使用されます。 |
コンポーネント・パレットで、「一般コントロール」パネルから任意のコマンド・コンポーネントをページにドラッグ・アンド・ドロップします。これは、アップロード・プロセスの開始に使用されます。
コマンド・コンポーネントが選択された状態で、actionListener
属性を、アップロード後にファイルを処理するリスナーに設定します。
ADF Facesではアップロードされるファイルが(ディスクまたはメモリーに)一時的に格納されるため、アップロード・ファイルでハード・ドライブやメモリーを一杯にしようとするDoS攻撃を未然に防ぐため、デフォルトでは、許容される着信アップロード・リクエストのサイズが制限されています。デフォルトでは、1つのリクエストで最初の100KBがメモリーに格納されます。これが一杯になると、ディスク領域が使用されます。この場合も、デフォルトでは、すべてのファイルに対し、1つのリクエストで2,000KBのディスク領域に制限されます。これらの制限を超えると、フィルタによりEOFException
がスローされます。
ファイルは、デフォルトで、java.io.File.createTempFile()
メソッドによって使用される一時ディレクトリに格納されます。これは通常、システム・プロパティjava.io.tmpdir
によって定義されます。明らかに、これは一部のアプリケーションでは不十分であるため、例11-12に示すように3つのサーブレット・コンテキスト初期化パラメータを使用して、これらの値を構成できます。
例11-12 ファイルのアップロード・サイズおよびディレクトリを定義するパラメータ
<context-param> <!-- Maximum memory per request (in bytes) --> <param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY</param-name> <!-- Use 500K --> <param-value>512000</param-value> </context-param> <context-param> <!-- Maximum disk space per request (in bytes) --> <param-name>org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE</param-name> <!-- Use 5,000K --> <param-value>5120000</param-value> </context-param> <context-param> <!-- directory to store temporary files --> <param-name>org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR</param-name> <!-- Use a TrinidadUploads subdirectory of /tmp --> <param-value>/tmp/TrinidadUploads/</param-value> </context-param> <!-- This filter is always required; one of its functions is file upload. --> <filter> <filter-name>trinidad</filter-name> <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class> </filter>
org.apache.myfaces.trinidad.webapp.UploadedFileProcessor
クラス全体をtrinidad-config.xml
構成ファイルの<uploaded-file-processor>
要素に置き換えることで、ファイルのアップロード・プロセスをカスタマイズできます。UploadedFileProcessor
クラスを置き換えると、例11-12にリストされているパラメータは無関係になり、デフォルトのUploadedFileProcessor
クラスによってのみ処理されます。
<uploaded-file-processor>
要素は、oracle.adf.view.rich.webapp.UploadedFileProcessor
インタフェースを実装するクラスの名前である必要があります。このAPIにより、個々のアップロード・ファイルが着信リクエストから取得される際に処理され、そのコンテンツを残りのリクエストで使用できるようになります。大部分のアプリケーションは、デフォルトのUploadedFileProcessor
クラスで十分ですが、大規模ファイルのアップロードをサポートする必要のあるアプリケーションでは、リクエスト中にADF Facesで一時記憶域を処理するかわりに、ファイルをただちに最終的な宛先に格納することでパフォーマンスを向上させます。