>> Visual Web Pack のほかのドキュメント
コンポーネント
執筆: Visual Web Pack チュートリアルチーム
| 2007 年 5 月 [Revision number: V5.5.1-1] |
|
|
コンポーネントは、対話式 Web ページの基本要素です。このチュートリアルでは、Visual Web Pack に付属しているコンポーネントを最大限に活用するための基礎知識を提供します。概要を理解できたら、個々のコンポーネントのチュートリアルで詳細を学ぶことができます。また、「パレット」の任意のコンポーネントを選択して F1 キーを押すと、そのコンポーネントに関する詳細な説明が表示されます。
このチュートリアルでは、「NetBeans Visual Web Pack 5.5 について」と「Web アプリケーションの開発」で説明している概念について詳しく説明しています。 |
目次
|
|
 |
このチュートリアルでは、次のテクノロジとリソースを使用します。
JavaServer Faces コンポーネント /
Java EE プラットフォーム |
 Java EE 5* の場合、1.2
J2EE 1.4 の場合、1.1
|
| Travel データベース |
 任意 |
| BluePrints AJAX コンポーネントライブラリ |
任意 |
* このチュートリアルの公開時点で Java EE 5 をサポートしていたのは Sun Java System Application Server だけです。
このチュートリアルは、Sun Java System Application Server PE 9.0 Update Release 1 と Tomcat 5.5.17 を使用することを想定しています。別のサーバーを使用している場合は、「リリースノート」と「FAQ」(または「日本語 FAQ」) で既知の問題やその回避策を確認してください。サポートされているサーバーと Java EE プラットフォームについては、「リリースノート」を参照してください。
コンポーネントとは
静的な HTML ページの作成には、長い時間や豊富な知識は必要ありません。しかし、動的な対話式のページの構築は複雑です。クライアント側での操作に JavaScript を使用する方法を理解し、サーバー側での対話と妥当性検査に使用する Java コードと JavaServer Pages (JSP) タグを記述する必要があります。また、ブラウザによってタグの表示が異なることも、生産性を低下させる原因になります。
Visual Web Pack に付属する JavaServer Faces ベースのコンポーネントを使用すると、対話式 Web ページの構築が簡単になり、開発サイクルが短縮されます。また、Visual Web Pack では、JavaServer Faces 技術の細部を理解していなくてもこれらのコンポーネントを使用できます。
コンポーネントは、タグを強化したものです。つまり、単なるドロップダウンリストなどの描画タグではなく、簡単に装飾でき、簡単な Java コードで処理できるイベントを生成する見栄えのいいタグです。たとえば、「テキストフィールド」コンポーネントは、JavaServer Faces フレームワークと連動することにより、入力内容を変換、検査し、変更イベントと妥当性検査イベントがブロードキャストされます。
また、データソースがデータベース、Web サービス、配列、またはリストのいずれであっても、数回クリックするだけで、コンポーネントのプロパティーを Bean プロパティーまたはデータソースのデータプロバイダラッパーにバインドできます。バインド機能を使用すると、コンポーネントの値を設定するコードや、コンポーネントの値をバインド先のオブジェクトに保存するコードを記述する必要がありません。
IDE に付属するコンポーネントには、通常の HTML タグでは実現できないしかけがあります。たとえば、次の図に示すように、「表」コンポーネントには、列をソート可能にする機能や自動的にページ付けを行う機能があります。
図 1:表コンポーネント |
Visual Web Pack には 2 つのコンポーネントセットが付属しています。1 つは JavaServer Faces 1.1 テクノロジで構築され、もう 1 つは JavaServer Faces 1.2 テクノロジで構築されています。Web アプリケーションプロジェクトに設定した Java EE バージョンと互換性のあるコンポーネントが、「パレット」に表示されます。Java EE バージョンを Java EE 5 に設定すると、「パレット」には JavaServer Faces 1.2 互換コンポーネントが表示されます。Java EE バージョンを J2EE 1.3 または 1.4 に設定すると、「パレット」には JavaServer Faces 1.1 互換コンポーネントが表示されます。
このチュートリアルでは、「パレット」の「基本」、「レイアウト」、「複合」の各セクションにあるコンポーネント (次の図を参照) について主に説明します。
 図 2:「基本」、「レイアウト」、「複合」の各セクション |
注: 「パレット」の「標準」セクションには、JavaServer Faces リファレンス実装のコンポーネントが含まれます。標準コンポーネントは、機能が少なく、プログラミング量が多くなるので、「パレット」のほかのセクションにある表示コンポーネントを使用してください。
注: 「パレット」には「フォーム」コンポーネントがありますが、このチュートリアルでは、「フォーム」コンポーネントについて説明していません。ページ内で複数のフォームを処理するほとんどの場合は、仮想フォームメカニズムが適しています。
一般情報
この節では、ほとんどの、またはすべてのコンポーネントに適用する情報を示します。このチュートリアルのそのほかの部分は、次の図に示すように 5 つの節 (出力、入力、アクションとリンク、レイアウト、非表示) で構成されています。
 図 3:5 種類のコンポーネント |
コンポーネントのプロパティー
「プロパティー」ウィンドウを使用して、コンポーネントの外観と動作を指定します。たとえば、「リストボックス」コンポーネントの「rows」プロパティーを使用して、リストボックスの長さを指定し、「multiple」プロパティーを使用して、ページの訪問者がリストから複数の項目を選択できるかどうかを指定します。
Visual Web Pack では、各コンポーネントの一般的な作業をメニュー (コンポーネントを右クリック) から実行することもできます。たとえば、「画像」コンポーネントには、「画像を設定」メニュー項目があり、「静的テキスト」コンポーネントには「テキストを編集」メニュー項目があり、「ドロップダウンリスト」コンポーネントには「ラベルを編集」メニュー項目があります。
次の表に、コンポーネントの動作と外観を制御するための共通のプロパティーを示します。各コンポーネントに固有のプロパティーについては、このあとの各節で説明します。
| プロパティー |
説明 |
id |
コンポーネントには、そのページ内で一意の id が必要です。コンポーネントをページに追加すると、IDE によって id が作成されます。次の場合は、コンポーネントの id を変更することをお勧めします。
- コンポーネントが入力コンポーネントの場合。バインド先のプロパティーまたは列に対応する id に設定します (
personIdDropDown など)。
- ボタンなどのコンポーネントがアクションイベントを生成する場合。id をコンポーネントのラベルと一致する動詞の名前に設定します (
submitButton など)。
- ページ上に同じ種類のコンポーネントが複数あり、一部のコンポーネントのプロパティー値を設定またはアクセスする Java ソースコードを記述する必要がある場合。たとえば、
textField1 と textField2 ではなく、nameTF と addressTF を参照するほうが、コードがわかりやすくなります。
|
toolTip |
このプロパティーを使用して、ページの訪問者がコンポーネントの上にカーソルを置いたときに表示されるテキストを指定します。 |
style |
「style」プロパティーを使用して次の設定を変更します。
- フォント
- 背景情報
- テキストブロック
- ボーダー
- マージン
- 位置
「style」プロパティーの省略符号ボタン (...) をクリックすると、スタイルエディタが開き、簡単に設定を変更したり、結果をプレビューしたりできます。このエディタの使用方法については、エディタ下部の「ヘルプ」ボタンをクリックしてください。
一般に、コンポーネントのサイズを変更すると、IDE によって高さ、幅、またはその両方が設定されます。ページがグリッドレイアウトモードの場合は、コンポーネントをページにドロップしたときと、ページ上でコンポーネントを移動したときに IDE によって位置の値が設定されます。
「bgcolor」や「border」など、「style」プロパティーの設定に似ているプロパティーがある場合もあります。これらは HTML 4 の標準のスタイル属性です。「style」プロパティーは、これらの標準属性を拡張したもので、コンポーネントの外観を設定するのにより適しています。
コンポーネントセットは、階層式スタイルシート (CSS) ファイルの組織的なセットである、Web UI デフォルトテーマを実装します。「style」プロパティーの設定は、テーマのほとんどのスタイル機能より優先されます。しかし、たとえば、「style」プロパティーを使用して表の背景色や、「label」プロパティーのフォントの色は設定できません。これは、設定がコンポーネントのテーマと異なる場合に特にあてはまります。また、「style」プロパティーの設定が異なるほかの子コンポーネントによって特定の領域が隠される場合もあります。 |
styleClass |
すべてのプロジェクトにはテーマがあります。テーマとは、階層式スタイルシート (CSS)、JavaScript ファイル、およびアイコン画像のセットです。Visual Web Pack には Web UI デフォルトテーマがあります。テーマに独自のスタイルを追加するには、スタイルシートエディタを使用するか、プロジェクトの resources フォルダにスタイルシートを追加します。「styleClass」プロパティーには、アプリケーションで使用されているすべてのスタイルシートのすべてのスタイルクラスが表示されます。通常は、このプロパティーは独自のスタイルシートからスタイルクラスを選択する必要がない限りは使用しません。「styleClass」プロパティーの設定は、コンポーネントのテーマのスタイルクラスに加えて適用されます。 |
visible |
「visible」プロパティーは、コンポーネントをページに表示するかどうかを指定します。「visible」プロパティーを False に設定すると、コンポーネントはページに表示されませんが、生成される HTML (ページのソース) には含まれ、値は送信され、コンポーネントのすべての変換、妥当性検査、およびイベントの生成は実行されます。 |
rendered |
コンポーネントの「rendered」プロパティーを False に設定すると、コンポーネントが生成される HTML から削除され、コンポーネントがクライアントから使用できなくなります。コンポーネントは JavaScript から参照できず、ページの送信時に変換、妥当性検査、またはイベントの生成は実行されません。 |
コンポーネントの値の設定
入力コンポーネントと出力コンポーネントはすべて値を保持するコンポーネントです。たとえば、「テキストフィールド」コンポーネントはテキストを保持し、「リストボックス」コンポーネントは選択された値を保持します。入力コンポーネントと出力コンポーネントには、複数の方法で値を設定できます。
- コンポーネントの値を保持するプロパティーを設定する。「プロパティー」ウィンドウで、値を保持するプロパティーの省略符号ボタン (
...) をクリックしてテキストエディタを開きます。また、ほとんどの入力コンポーネントと出力コンポーネントでは、ビジュアルデザイナでコンポーネントを選択してコンポーネントの値を直接入力することもできます。値を保持するプロパティーのポップアップメニューにはコンポーネントの編集可能なテキストの編集メニュー項目があります。
- コンポーネントの設定メソッドをページ Bean のソースコードから呼び出す。たとえば、「テキストフィールド」コンポーネントの値を設定するには
setText メソッドを呼び出し、「リストボックス」コンポーネントの値を設定するには setSelected メソッドを呼び出します。設定メソッドは、一般に前処理、事前描画、値変更、およびアクションの各メソッドで呼び出します。
- コンポーネントをデータプロバイダまたは Bean プロパティーにバインドする。コンポーネントのデータへのバインドについては、次の項を参照してください。
注: JavaServer Pages の実装と同様に、サーバーで JSP ソースからページが構築されるとき、JSP ソースでのタグ属性の設定は、実行時の設定より優先されます。たとえば、「静的テキスト」コンポーネントの「text」プロパティーを「月」に設定すると、IDE によって JSP ファイル内の「静的テキスト」コンポーネントのタグに「text="月"」が追加されます。ページの prerender メソッドに staticText1.setText("太陽") 文があっても、アプリケーションでページが表示されるときに「静的テキスト」コンポーネントには「月」と表示されます。ページが再表示されると、staticText1.setText("太陽") 文が有効になり、「静的テキスト」コンポーネントに「太陽」と表示されます。別のページを表示してから戻ると、サーバーではページが JSP ソースから構築されて、JSP タグ属性で設定されている値が優先されるため、ページに「月」と表示されます。
ヒント:プロパティーを設定するコードが常に優先されるようにするには、「プロパティー」ウィンドウでそのプロパティーを静的な値に設定しないでください。
データへのバインド
ほとんどの入力コンポーネントと出力コンポーネントはデータオブジェクトにバインドできます。コンポーネントをデータにバインドすることにより、Web アプリケーションでコンポーネントの値とバインド先の値との同期を自動的にとれます。たとえば、コンポーネントを Bean プロパティーにバインドすると、Web アプリケーションでページが生成されるときにコンポーネントの値が Bean プロパティーの値に設定され、ページが送信されるときに Web アプリケーションによって Bean プロパティーの値が、コンポーネントの値の変更に合わせて変更されます。
Visual Web Pack には、データベース表、Web サービス、エンタープライズ JavaBeans オブジェクト、マップ、配列、およびリストのデータプロバイダラッパーが含まれています。データプロバイダをデータオブジェクトにバインドすることで、コンポーネントをデータプロバイダにバインドします。データプロバイダの利点は、すべての種類のデータにアクセスする共通のインタフェースである点です。
データベース表のデータプロバイダを作成するには、データベース表を「実行時」ウィンドウの「データベース」セクションからドラッグし、ページにドロップするか、ページ内のコンポーネントにドロップします。IDE によってデータベース表のキャッシュされた行セット表データプロバイダが作成されます。
バインドとデータプロバイダについては、チュートリアル「「データバウンド」コンポーネント」を参照してください。
値の変換
Visual Web Pack には、ほとんどの入力コンポーネントと出力コンポーネントに適用できるコンバータが複数あります。コンバータは、オブジェクトの値を String 型に変換し、値を HTML 応答に書き込むことができるようにします。また、コンバータは HTML 要求内の String 型の値を、Boolean や Float などの指定のデータ型に変換し直します。
注: Web アプリケーションでは、データにバインドされている任意のコンポーネントに対して適切な変換が自動的に実行されます。たとえば、「テキストフィールド」コンポーネントが Integer 型のオブジェクトにバインドされている場合、Web アプリケーションでは入力値 (String 型) が自動的に Integer 型に変換されます。
出力コンポーネント
Visual Web Pack には、さまざまな出力コンポーネントがあります (次の図を参照)。これらのコンポーネントは、テキスト、メッセージ、および画像の 3 つのグループに分類されます。出力テキストコンポーネントは、ページにテキストを配置するときに使用し、出力メッセージコンポーネントは、ユーザー入力への応答として、またはその他の動的な処理のために使用します。画像コンポーネントは、jpg ファイルや gif ファイルなどのピクセル値のリポジトリの表示に使用します。
 図 4:出力コンポーネント |
出力テキストコンポーネント
Visual Web Pack には、次の 3 種類の出力テキストコンポーネントがあります。
| 出力テキストコンポーネント |
用途 |
静的テキスト
|
「静的テキスト」コンポーネントは、単にテキストをページに表示するときに使用します。 |
ラベル
|
「ラベル」コンポーネントは、入力コンポーネントにテキストを関連付けるときに使用します。「ラベル」コンポーネントを入力コンポーネントに関連付けるには、「ラベル」コンポーネントの「for」プロパティーを設定します。「ラベル」コンポーネントを入力コンポーネントに関連付けると、「ラベル」コンポーネントに機能が付加されます。具体的には、入力コンポーネントの「required」プロパティーが True の場合に「ラベル」コンポーネントにアスタリスクが表示されます。入力が無効なため、ページの送信がサーバーで拒否された場合は、ページで「ラベル」コンポーネントのテキストが強調表示されます。
入力コンポーネントには「label」プロパティーがありますが、この「label」プロパティーを設定すると、コンポーネントのサイズ変更や位置揃えができなくなるので、「ラベル」コンポーネントを使用することをお勧めします。また、「ラベル」コンポーネントのほうがスタイルのオプションが多くなっています。 |
インラインヘルプ
|
「インラインヘルプ」コンポーネントを使用して、短いヘルプの情報をページに表示します。
|
出力メッセージコンポーネント
Visual Web Pack には、さまざまな種類のメッセージを表示できる次の出力コンポーネントがあります。「ページ警告」コンポーネントを除き、これらのコンポーネントは、値が null 以外の場合にのみページに表示されます。
| 出力メッセージコンポーネント |
用途 |
警告
|
「警告」コンポーネントを使用して、イベント終了時に警告、エラー、成功の状態、または情報の状態などの動的な情報を表示します。概要テキストとともにエラーアイコン、情報アイコン、警告アイコン、または成功アイコンを表示できます。必要に応じて詳細テキストとハイパーリンクを表示することもできます。
「summary」プロパティーと「detail」プロパティーを使用してコンポーネントのテキストを設定し、「type」プロパティーを使用して、表示するアイコンを指定します。コンポーネントは、「summary」プロパティーに値がある場合にのみページに表示されます。
「linkText」と「linkURL」の値を指定することで、必要に応じてハイパーリンクを追加できます。「detail」プロパティーが値を持たないかぎり、「linkText」の値はコンポーネントに表示されません。
リンクに動的なページナビゲーションを指定するには、次の手順に従います。
- 「
linkText」プロパティーを設定します。
- ページナビゲーションエディタを使用して、ページのコネクタポートと接続先ページとの間にコネクタを作成します。コネクタには「
alertOutcome」などの名前を付けます。
- ビジュアルデザイナーに切り替え、「警告」コンポーネントをダブルクリックします。IDE によってアクションイベントハンドラメソッドが作成され、Java エディタにメソッドが表示されます。
- 接続線に付けた名前 (「
alertOutcome」など) を返すようにメソッドの return 文を変更します。
この手順は、「アクションコンポーネントとリンクコンポーネント」で説明しているほかのアクションコンポーネントの手順と異なります。これは、ページナビゲーションエディタでは、ページおよび UICommand を拡張するコンポーネントからのみ接続できるからです。「警告」コンポーネントは、UICommand を拡張するコンポーネントではありません。 |
ページ警告
|
「ページ警告」コンポーネントは、「警告」コンポーネントに似ていますが、別個のページに動的なメッセージを表示するときに使用します。ページ警告では、エラー、警告、情報、および質問のアイコンを選択できます。「title」、「summary」、「detail」の各プロパティーを使用してコンポーネントのテキストを設定し、表示するアイコンを「type」プロパティーによって指定します。 |
メッセージ
|
「メッセージ」コンポーネントを使用して入力コンポーネントのエラーメッセージを表示します。「メッセージ」コンポーネントを入力コンポーネントに関連付けるには、「メッセージ」コンポーネントの「for」プロパティーを設定します。「メッセージ」コンポーネントには、アプリケーションから、変換エラーと妥当性検査エラーに関するメッセージが送信されます。妥当性検査に関する独自のメッセージをコンポーネントに送信するには、次のいずれかの例外をスローします。
ValidatorException(new FacesMessage(summary)) ValidatorException(new FacesMessage(summary, detail))ValidatorException(new FacesMessage(severity, summary, detail))severity 引数には、
FacesMessage.SEVERITY_INFO、
FacesMessage.SEVERITY_WARN、
FacesMessage.SEVERITY_ERROR、または
FacesMessage.SEVERITY_FATAL を指定できます。
JavaServer Faces 1.2 コンポーネントセットでは、コンポーネントの requiredMessage、converterMessage、および validatorMessage メソッドを呼び出してカスタムメッセージを指定することで、標準のエラーメッセージを変更できます。 |
メッセージグループ
|
「メッセージグループ」コンポーネントを使用して実行時エラーを表示します。また、「showGlobalOnly」プロパティーのチェックボックスを選択解除すると、妥当性検査エラーや変換エラーなどの個々のコンポーネントのエラーも表示できます。「メッセージグループ」コンポーネントは、プログラミングエラーの診断にも便利です。
このコンポーネントに独自のテキストを書き込むには、info(String summary)、warn(String summary)、error(String summary)、または fatal(String summary) を呼び出します。メソッドの重要度に応じて、Web アプリケーションで異なるスタイルがテキストに適用されます。
概要メッセージと詳細メッセージの両方を書き込むには、FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(summary, detail)) または ValidatorException(new FacesMessage(severity, summary, detail)) を使用します。
詳細メッセージを表示するには、コンポーネントの「showDetail」のチェックボックスを選択する必要があります。
|
出力テキストコンポーネントと同様に、適切なプロパティーの設定メソッドを呼び出すことで、「ページ警告」コンポーネントと「警告」コンポーネントの出力値をプログラムで設定できます。たとえば、「ページ警告」コンポーネントの概要テキストを設定するには、setSummary(String) を呼び出します。これらのプロパティーを管理 Bean のプロパティーやデータプロバイダのフィールドにバインドすることもできます。
「画像」コンポーネント
「画像」コンポーネントは、「url」プロパティーで指定する画像を表示するとき、または ALARM_CRITICAL_MEDIUM や ALERT_OK_SMALL など、付属のアイコンを表示するときに使用します。付属のアイコンは、「icon」プロパティーのダイアログ (省略符号ボタン (...) をクリック) で選択できます。
 図 5:「画像」コンポーネントの例 |
「url」プロパティーには、インターネット上の画像の URL、またはプロジェクトの resources フォルダにある画像ファイル (/resources/images/duke.gif など) を指定できます。また、「url」プロパティーは、管理 Bean のプロパティー、または String 形式で URL のパスを返すデータプロバイダのフィールドにバインドすることもできます。「url」プロパティーの省略符号ボタン (...) をクリックしたら、「バインドを使用」ラジオボタンを選択してプロパティーをデータオブジェクトにバインドするか、「値を使用」ラジオボタンを選択して画像ファイルを指定できます。画像が resources フォルダにない場合は、「ファイルを追加」をクリックしてファイルを選択し、フォルダにコピーします。また、プロパティーの「URL」テキストフィールドに有効な URL を入力することもできます。
ヒント:Web アプリケーションとともにパッケージ化する画像の URL を指定する場合は、コンテキストを基準とした URL を使用します。つまり、URL をスラッシュ (/) から始めます (/resources/images/dot.gif など)。コンテキストを基準とした URL を使用すると、ページが生成されてクライアントに送信される前に、サーバーで URLが完全な URL に変換されます。先頭にスラッシュを付加しなかった場合は、クライアント側で解釈が行われ、現在のページの URL が画像の URL の前に付加されます。ページがサブフォルダにある場合は、要求が転送されるときに、URL が正しく解決されない可能性があります (デフォルトの発信機構)。
入力コンポーネント
Visual Web Pack では、複数の方法でユーザー入力を取得できます (次の図を参照)。この節では、入力コンポーネントについて、その共通の機能、および入力値を取得し、処理する方法について説明します。
 図 6:入力コンポーネント
|
Visual Web Pack には、次の入力コンポーネントがあります。
| 入力コンポーネント |
用途 |
テキスト入力コンポーネント
|
「テキストフィールド」コンポーネントは 1 行のテキストの入力に、「テキスト領域」コンポーネントは複数行の入力に使用します。「パスワードフィールド」コンポーネントは、入力された文字を別の文字で表示して入力内容を隠す入力フィールドに使用します。 |
選択コンポーネント
|
「ラジオボタングループ」、「チェックボックスグループ」、「ドロップダウンリスト」、「リストボックス」、および「追加・削除リスト」の各コンポーネントは、よく似ています。これらはいずれもページの訪問者が 1 つまたは複数の選択肢を選択できる項目 (表示値) リストです。
選択コンポーネントの各項目には戻り値があり、ページの訪問者がそのオプションを選択すると、その戻り値が「selected」プロパティーの値として返されます。
項目リストは複数の方法で初期化できます。
項目を事前に選択する方法として、prerender() メソッドから setSelected(Object[]) または setSelected(Object) を呼び出すことができます。このとき、選択する項目の戻り値を渡します。デフォルトオプションを設定する前に getSelected() が null を返すことを確認します。そうしなければ、データがクライアント側から送信されるときにユーザーの選択が上書きされます。
選択コンポーネントがデフォルトオプションコンポーネントにバインドされている場合は、選択コンポーネントのポップアップメニューから「デフォルトオプションを設定」を選択して項目を事前に選択できます。「項目を選択」チェックボックスを選択し、事前選択するデフォルトオプションを選択します。
警告:「追加・削除リスト」コンポーネントの Javadoc とコード補完に Iterator を返す getSelectedItems() メソッドが表示されます。このメソッドは使用しないでください。このメソッドは、内部の描画処理用であり、実際に選択された項目を示すものではありません。
|
チェックボックスとラジオボタン
|
「チェックボックス」コンポーネントと「ラジオボタン」コンポーネントは、「表」コンポーネントの列に追加できます。「チェックボックス」コンポーネントと「ラジオボタン」コンポーネントは、単独のコンポーネントとしてページに追加することもできます。ただし、選択可能な項目のリストには、「ラジオボタングループ」コンポーネントと「チェックボックスグループ」コンポーネントが適しています。 |
カレンダ
|
「カレンダ」コンポーネントを使用すると、ページの訪問者が日付を入力できます。日付は直接入力するか、ポップアップカレンダから選択できます。「selectedDate」プロパティーに、入力された値が java.util.Date 型のオブジェクトとして含まれます。
ポップアップカレンダの日付範囲を設定するには、「minDate」プロパティーと「maxDate」プロパティーを、開始日と終了日の値がある java.util.Date 型の Bean プロパティーにバインドします。次の例は、現在の日付に日付の最小値を設定するコードを示しています。日付の最小値では、時刻を 0 に設定する必要があります。
| コード例 2:日付の最小値プロパティー |
private Date minCalDate;
public Date getMinCalDate() {
java.util.Calendar date =
java.util.Calendar.getInstance(
FacesContext.getCurrentInstance().
getViewRoot().getLocale());
// 日付の比較は時刻の影響を受けるため、
// 時刻を 0 に設定する
date.set(java.util.Calendar.HOUR_OF_DAY, 0);
date.set(java.util.Calendar.MINUTE, 0);
date.set(java.util.Calendar.SECOND, 0);
date.set(java.util.Calendar.MILLISECOND, 0);
return date.getTime();
} |
このバージョンの Visual Web Pack では、「minimumDate」プロパティーを設定しなかった場合、日付の最小値のデフォルトは 100 年前、「maximumDate」のデフォルトは現在の日付から 100 年後になります。
日付形式は、デフォルトでロケールのデフォルト形式になります。「dateFormatPattern」プロパティーのエディタを使用して、日付形式パターンのリストから選択できます。
コンポーネントの入力フィールドの下に表示される日付形式を変更するには、「dateFormatPatternHelp」プロパティーを編集します。
ヒント:カスタムエラーメッセージを String 型でコンポーネントの「validatorMessage」メソッドに渡すことによって、最小および最大の日付のエラーメッセージを変更できます。 |
ファイルアップロード
|
「ファイルアップロード」コンポーネントを使用すると、ページの訪問者が自身のシステムにあるファイルを検索し、そのファイルをサーバーにアップロードできます。
コンポーネントの「uploadedFile」プロパティーは、JavaServer Faces 1.2 コンポーネントに対して「com.sun.webui.model.UploadedFile」型の値を返し、JavaServer Faces 1.1 コンポーネントに対しては「com.sun.rave.web.ui.model.UploadedFile」型の値を返します。UploadedFile インタフェースには、ファイルの名前とサイズを取得するメソッド、ファイルの MIME タイプ (text/plain、image/jpeg など) を判別するメソッド、ファイルの内容をバイトまたは String で取得するメソッド、および内容をディスクに書き込むメソッドがあります。Java ソースの宣言文にある UploadedFile を右クリックし、ポップアップメニューから「Javadoc を表示」を選択すると、説明が表示されます。
デフォルトでは、アプリケーションでアップロードファイルのサイズが 1M バイトに制限されます。サイズ制限を変更するには、アプリケーションの web.xml ファイルで UploadFilter フィルタの「maxSize」パラメータを変更します。 |
入力コンポーネントの動作と外観のカスタマイズ
Visual Web Pack には、入力コンポーネントの動作と外観をカスタマイズできる次の機能があります。
-
フィールドにラベルを付ける。入力コンポーネントには、次の 2 通りの方法でラベルを付けることができます。
- 「label」プロパティーを使用する。入力コンポーネントの「
label」プロパティーと「labelLevel」プロパティーを設定して簡単にラベルを追加できます。「label」プロパティーを設定すると、標準コンバータ、必須、およびバリデータエラーメッセージで、コンポーネントの id ではなくコンポーネントの「label」値が使用されます。
- 「ラベル」コンポーネントを使用する。「ラベル」コンポーネントを使用すると、「label」プロパティーよりもスタイルを詳細に制御できます。また、入力コンポーネントの配置とは別にラベルを配置でき、ラベルのサイズと関連付けられている入力コンポーネントのサイズを詳細に制御できます。「label」プロパティーの代わりに「ラベル」コンポーネントを使用するときの不利点は、「label」プロパティーが設定されていないと、エラーメッセージに、コンポーネントの内部 id が表示されることです。コンポーネントの
converterMessage、requiredMessage、および validatorMessage の各メソッドをカスタムメッセージ付きで呼び出すか、アプリケーション全体で標準メッセージをオーバーライドするリソースバンドルを追加すると、標準のエラーメッセージをオーバーライドできます。
-
エラーメッセージを表示する。前述のように、「メッセージ」コンポーネントと「メッセージグループ」コンポーネントを追加して、変換エラーや妥当性検査エラーを表示できます。「メッセージ」コンポーネントを入力コンポーネントに関連付けるには、「メッセージ」コンポーネントの「for」プロパティーを、入力コンポーネントの id に設定します。「メッセージグループ」コンポーネントでは、「showGlobalOnly」プロパティーを True に設定しない限り、入力時の変換エラーと妥当性検査エラーのメッセージがすべて表示されます。
ヒント:すべてのページに「メッセージグループ」コンポーネントを追加すると、プログラミングエラーの診断に役立ちます。
- 入力を無効にし、入力コンポーネントを読み取り専用にする。すべての入力コンポーネントには「
disabled」プロパティーと「readOnly」プロパティーがあります。ユーザーが Tab キーを押してコンポーネントに移動できないようにしたり、アプリケーションで値が変換、検査、および送信されないようにするには、「disabled」を True に設定します。ユーザーが値を入力または変更できないようにし、アプリケーションで値を変換、検査、および送信するには、「readOnly」を True に設定します。
- タブ順を設定する。「
tabIndex」プロパティーを使用して、ユーザーが Tab キーを押してページ上の入力コンポーネント間を移動する順序を指定します。
- 空白文字を削除する。「
trim」プロパティーを True に設定すると、アプリケーションで入力の前後の空白文字がすべて削除されます。空白文字の削除は、変換と妥当性検査の前に行われます。「カレンダ」コンポーネントや「ファイルアップロード」コンポーネントなどの一部の入力コンポーネントには「trim」プロパティーがありません。これらの入力はアプリケーションで自動的に削除されます。
- 入力可能な文字数を制限する。「
maxLength」プロパティーを使用して、ページの訪問者が入力フィールドに入力できる最大文字数を設定できます。この最大文字数に達したあとに入力された文字は無視されます。たとえば、「maxLength」の値が 5 で、ページの訪問者が「bicycle」と入力すると、フィールドには「bicyc」と表示されます。
-
入力コンポーネントを使用してページを送信する。ほとんどの入力コンポーネントでは、コンポーネントのポップアップメニューから「変更時に自動送信」を選択して、入力値が変更されたときにブラウザからページが送信されるように指定できます。この機能を一般に使用すると、ページの訪問者がマスターデータのドロップダウンリストから新しい項目を選択する度にページが送信されるため、詳細データがマスターデータの選択に合わせて同期できます。たとえば、ページの訪問者がドロップダウンリストから新しい製品を選択したときに、ページにその製品の詳細データを表示できます。
コンポーネントの値が変更されたときにすべての入力値が送信されないようにするには、仮想フォームを使用して送信する値を指定します。
入力値の取得と設定
次の表に、各入力コンポーネントの値を保持するプロパティーを示します。値を保持するプロパティーの取得メソッドと設定メソッドを使用して、入力値にアクセスします。たとえば、getSelected と setSelected を使用して、値を保持するプロパティーとして「selected」プロパティーを持つコンポーネントの入力値を取得および設定します。「一般情報」の節で説明したように、これらの値を保持するプロパティーをデータにバインドすることもできます。
| コンポーネント |
値を保持するプロパティー |
タイプ |
注 |
| テキストフィールド、テキスト領域、パスワードフィールド |
テキスト |
String、またはフィールドがバインドされている場合はバインド先のオブジェクト型 |
|
| ドロップダウンリスト |
selected |
「items」プロパティーに、ドロップダウンリスト内の各項目の表示ラベルと戻り値を指定します。「selected」プロパティーには、戻り値と同じ型のオブジェクトが返されます。デフォルトオプションコンポーネントを使用して項目と戻り値を指定すると、「selected」に String が返されます。 |
ページの訪問者がドロップダウンリストから項目を選択すると、アプリケーションでコンポーネントの「selected」プロパティーが、選択されたリスト項目の戻り値に設定されます。 |
| リストボックス |
selected |
「items」プロパティーに、リスト内の各項目の表示ラベルと戻り値を指定します。「selected」プロパティーには、戻り値と同じ型のオブジェクトが 1 つ、または「multiple」プロパティーが選択されている場合はオブジェクトの配列が返されます。
デフォルトオプションコンポーネントを使用して項目と戻り値を指定した場合は、「selected」には String 型のオブジェクト、または「multiple」プロパティーが True の場合は String 型オブジェクトの配列が返されます。 |
「multiple」プロパティーが False の場合、コンポーネントの「selected」プロパティーの値は、選択されたリスト項目の戻り値と一致します。ユーザーが複数の項目を選択できるように「multiple」プロパティーを True に設定した場合は、「selected」を Object 型の配列、基本型の配列、または java.util.List にバインドする必要があります。java.util.List を使用する場合、リストのメンバーが String 型のオブジェクトではない限り、メンバーの型のコンバータを指定する必要があります。配列には、選択された項目の戻り値と一致する値が含まれます。 |
| ラジオボタン (単独) |
selected |
デフォルトでは boolean。ただし、Boolean、Byte、Character、Double、Float、Integer、Long、Short、String などのラッパー型、これらのいずれかのラッパー型の基本型、またはアプリケーションで定義されたオブジェクト値にバインドできます。 |
コンポーネントは、「selected」プロパティーの値が「selectedValue」プロパティーの値と一致したときに選択されていると見なされます。「selectedValue」の値はデフォルトで True に設定されています。
「name」プロパティーに同じ値を持つ「ラジオボタン」コンポーネントが複数ある場合、セット内で同時に選択できるラジオボタンは 1 つだけです。通常、「name」プロパティーは、「表」コンポーネント列に「ラジオボタン」コンポーネントがある場合に使用します。 |
| ラジオボタングループ |
selected |
「items」プロパティーに、各ラジオボタンの表示ラベルと戻り値を指定します。「selected」プロパティーには、戻り値と同じ型のオブジェクトが返されます。デフォルトオプションコンポーネントを使用して項目と戻り値を指定すると、「selected」に String が返されます。 |
ページの訪問者がラジオボタンを選択すると、アプリケーションによってラジオボタングループの「selected」プロパティーが、選択されているラジオボタンの戻り値に設定されます。 |
| チェックボックス (単独) |
selected |
デフォルトでは boolean。ただし、Boolean、Byte、Character、Double、Float、Integer、Long、Short、String などのラッパー型、これらのラッパー型の基本型、またはアプリケーションで定義されたオブジェクト値にバインドできます。 |
コンポーネントは、「selected」プロパティーの値が「selectedValue」プロパティーの値と一致したときに選択されていると見なされます。「selectedValue」の値はデフォルトで True に設定されています。
JavaServer Faces 1.2 version では、「チェックボックス」が「表」コンポーネントにある場合、「name」プロパティーを設定し、「selectedValue」を、取得メソッドがチェックボックスを識別する値を返すプロパティーにバインドします。たとえば、取得メソッドが tableRowGroup1.getRowKey().toString() を返すようにします。どのチェックボックスが選択されているかを調べるには、「チェックボックス」コンポーネントの getSelected メソッドを呼び出して、ArrayList を返します。 |
| チェックボックスグループ |
selected |
「items」プロパティーに、表示ラベルと戻り値を指定します。「selected」の値には、戻り値と同じ型のオブジェクトの配列が返されます。デフォルトオプションコンポーネントを使用して項目と戻り値を指定すると、「selected」に String 型のオブジェクトの配列が返されます。 |
「selected」の配列の値は、選択されているチェックボックスの戻り値と一致します。 |
| カレンダ |
selectedDate |
java.util.Date |
|
| ファイルアップロード |
uploadedFile |
com.sun.rave.web.ui.model.UploadedFile |
セキュリティー上の理由より、「uploadedFile」プロパティーは読み取り専用です。
UploadedFile インタフェースには、ファイルの名前とサイズを取得するメソッド、ファイルの内容を String として取得するメソッド、および内容をディスクに書き込むメソッドがあります。Java ソースの宣言文にある UploadedFile を右クリックし、ポップアップメニューから「Javadoc を表示」を選択すると、説明が表示されます。
UploadedFile.getOriginalName() メソッドは、ブラウザから提供された、クライアントのファイルシステムでの元のファイル名を返します。ほとんどの場合、これはパス情報を含まないファイル名です。ただし、ブラウザによってはパス情報が含まれる場合があります。
注: 「ファイルアップロード」コンポーネントの表示は、ブラウザによって異なります。通常、コンポーネントは、ブラウザではビジュアルデザイナーよりも小さく表示されます。 |
| 追加・削除リスト |
selected |
Object の配列 |
「items」プロパティーに、表示ラベルと戻り値を指定します。「selected」の配列の値は、選択されている項目の戻り値と一致します。 |
ユーザー入力の妥当性検査
次の機能を使用して、ユーザー入力を検査できます。1 つまたは複数の入力フィールドが妥当性検査に合格しなかった場合、Web アプリケーションによってページが再表示され、無効な入力に関連付けられたラベルが赤色で強調表示され、「メッセージグループ」コンポーネントや、関連付けられた「メッセージ」コンポーネントがある場合は、これらのコンポーネントにエラーメッセージが表示されます。
- 必須の入力。すべての入力コンポーネントには「
required」プロパティーがあります。このプロパティーを True に設定すると、値が入力されているかどうかを Web アプリケーションで自動的に検査されます。
- 値の変換。「一般情報」の節で説明しているように、Visual Web Pack には、入力コンポーネントに適用できるコンバータが複数あります。変換は、妥当性検査処理が開始する前に行われます。ページの訪問者が入力した値をアプリケーションで指定されたデータ型に変換できない場合は、Web アプリケーションで入力が拒否され、エラーメッセージが送信されます。このエラーメッセージは、「メッセージグループ」コンポーネントや、関連付けられた「メッセージ」コンポーネントがページにある場合は、これらのコンポーネントに表示されます。数値コンバータは便利なコンバータで、入力が一致する必要があるパターンを指定できます。
-
入力の妥当性検査。Visual Web Pack には、3 つの妥当性検査コンポーネントがあり、任意の入力コンポーネントに適用できます。
- Double 範囲バリデータ。コンポーネントの変換された値が特定の範囲内にあるかどうかを確認します。値のデータ型は、浮動小数点型であるか、浮動小数点型に変換可能である必要があります。
- 長さバリデータ。コンポーネントのローカル値の長さが特定の範囲内にあるかどうかを確認します。値は
String 型である必要があります。
- Long 範囲バリデータ。コンポーネントのローカル値が特定の範囲内にあるかどうかを確認します。値は数値型であるか、
long 型に変換できる String 型である必要があります。
また、コンポーネントを右クリックし、「イベントハンドラを編集」>「validate」を選択することで、独自の妥当性検査メソッドを追加することもできます。このメニュー項目を実行すると、妥当性検査メソッドが作成され、そのメソッドが妥当性検査イベントリスナーとして登録されます。妥当性検査メソッドは、FacesContext、UIComponent、および Object (値) を受け取り、ValidatorException をスローします。
変換エラーと同様に、妥当性検査エラーメッセージは、「メッセージグループ」コンポーネントや、関連付けられた「メッセージ」コンポーネントがページにある場合は、アプリケーションによってこれらのコンポーネントに送信されます。
注: コンポーネントにバリデータを適用するか、コンポーネントの妥当性検査イベントハンドラを登録できますが、両方はできません。
Web アプリケーションでは、値変更リスナーやアクションリスナーが呼び出される前に妥当性検査が実行されます。1 つまたは複数の妥当性検査エラーが発生した場合は、値変更リスナーとアクションリスナーは呼び出されず、ページの訪問者が問題を解決できるように、Web アプリケーションによってページが再表示されます。
- 変更時の即時処理。ページの訪問者がコンポーネントの値を変更したらすぐにブラウザからページが送信されるようにするには、コンポーネントを右クリックし、ポップアップメニューから「変更時に自動送信」を選択します。
-
変換と妥当性検査の無効化。ページ上の一部の入力コンポーネントで変換や妥当性検査などの処理を無効にする必要がある場合があります。この場合は、IDE の仮想フォームの設定を使用して、特定の操作が発生したときに処理するフィールドを指定できます。たとえば、「取消し」ボタンがクリックされたときに、すべての入力フィールドの処理を省略できます。また、ページにボタンが 2 つあるときに、クリックされたボタンによって送信するフィールドを変えることができます。
「immediate」プロパティーを使用して入力値の処理を制限することもできます。ただし、仮想フォーム機能のほうが簡単に使用できます。たとえば、Web アプリケーションでは、「immediate」プロパティーが True に設定されているコンポーネントの変換、妥当性検査、および値変更リスナー (アクションコンポーネントの場合はアクションリスナーも) が、JavaServer Faces のライフサイクルの中でほかのコンポーネントよりも早い段階で呼び出されます。つまり、これらのコンポーネントの処理手順は、「要求値の適用」段階で通常の変換処理が行われる前や、そのあとの「処理の妥当性検査」段階で妥当性検査が行われる前に呼び出されます。これに対して、仮想フォームは、JavaServer Faces のライフサイクルが変わらないので、より簡単です。
ページの訪問者がページを送信すると、Web アプリケーションでは、次の順序で入力が検査されます。
- 変換
- 必須入力
- 妥当性検査
注: 値変更イベントは、値が実際に変更され、すべての妥当性検査に合格した場合にのみ発生します。
値変更イベントの処理
Visual Web Pack で構築した Web アプリケーションでは、入力コンポーネントの妥当性検査に合格し、送信された値が表示されていた値と異なる場合に、値変更イベントが送信されます。このようなイベントに応答する値変更イベントハンドラとしてメソッドを登録できます。たとえば、ユーザーがマスター値を変更したときに詳細データを変更するメソッドを作成し、そのメソッドを値変更リスナーとして登録できます。ページの訪問者がマスター値を変更し、ページを送信すると、Web アプリケーションによってこのメソッドが呼び出され、詳細データが更新されます。
アプリケーションでは、次の順序でイベントが発生します。
- コンポーネントツリーの深さ優先で「
immediate」プロパティーが設定されているコンポーネントのイベントが先に発生します。
- コンポーネントツリーの深さ優先で「
immediate」プロパティーが設定されていないコンポーネントの値変更イベントが次に発生します。
- コンポーネントツリーの深さ優先で「
immediate」プロパティーが設定されていないコマンドコンポーネントのアクションイベントが最後に発生します。
値変更イベントハンドラを簡単に作成し、登録するには、ビジュアルデザイナーで入力コンポーネントをダブルクリックします。ダブルクリックすると、IDE によってメソッドが作成され、そのメソッドがコンポーネントの値変更イベントのリスナーとして登録されます。登録されたイベントハンドラの名前がある場合は、コンポーネントの「valueChange」プロパティーに表示されます。
アクションコンポーネントとリンクコンポーネント
アクションコンポーネントとリンクコンポーネントを使用すると、ページの訪問者がページ間を移動したり、入力を送信したりできます。次の図に、「パレット」にあるアクションコンポーネントとリンクコンポーネントを示します。
 図 7:アクションコンポーネントとリンクコンポーネント
|
簡単なページナビゲーション
ユーザーがコンポーネントをクリックすると特定のページに移動し、ブラウザからユーザー入力が送信されないようにするには、「ハイパーリンク」、「画像ハイパーリンク」、「タブ」、または「ツリーノード」の各コンポーネントを使用して、移動先ページのパスをコンポーネントの「url」プロパティーに入力します (たとえば /faces/Page1.jsp)。
動的なページナビゲーション
ページナビゲーションエディタを使用すると、ユーザーの操作と決定論理の結果を移動先のページに対応付けるナビゲーション規則を指定できます。対応付けを指定するには、リンクコンポーネントまたはアクションコンポーネントから名前付きコネクタを移動先のページまでドラッグします。また、結果を返すコンポーネントのアクションハンドラを作成する必要があります。結果は、コネクタの名前と同じ String 型の値です。アクションハンドラを作成するには、コンポーネントの「action」プロパティーを使用できます。
ページの訪問者がコンポーネントをクリックすると、ブラウザによって入力が送信され、アクションハンドラから結果が返されます。サーバーによって、ナビゲーション規則の対応付けで結果が検索され、応答するページが判別されます。その結果のナビゲーション規則がない場合は、現在のページが再表示されます。ビジネスロジックに基づいて、異なる結果を返すアクションハンドラを記述できます。
注: 「url」プロパティーと「action」プロパティーの両方を設定した場合は、url ハンドラが優先されます。アクションハンドラは呼び出されません。
ページナビゲーションの詳細については、「ページナビゲーションを設定する」のチュートリアルを参照してください。
レイアウトコンポーネント
「パレット」には、ページ上でコンポーネントの配置を調整し、コンポーネントを操作しやすいように表示できるレイアウトコンポーネントがあります (次の図を参照)。
 図 8:レイアウトコンポーネント |
次の表では、各レイアウトコンポーネントの目的とコンポーネントの使用方法について説明します。
非表示コンポーネント
Visual Web Pack には次の 2 つの非表示コンポーネントがあります。
| コンポーネント |
用途 |
| 非表示フィールド |
「非表示フィールド」コンポーネントは、不可視のフォームフィールドです。「非表示フィールド」コンポーネントは、通常は JavaScript で使用する値の保存に使用します。「非表示フィールド」コンポーネントの値は送信されるので、ページ Bean などのサーバー側コードで JavaScript コードによる変更内容を確認できます。また、「非表示フィールド」コンポーネントを使用して再表示されるページに値を渡すこともできます。 |
| アンカー |
「アンカー」コンポーネントを使用して、ページ内のリンクターゲットを配置できます。「アンカー」コンポーネントは、HTML の <a name=<ターゲット名>> に相当します。コンポーネントの id がターゲット名です。たとえば、コンポーネントの id が anchor1 の場合、ハイパーリンクの「url」プロパティーを #anchor1 に設定して、「アンカー」コンポーネントの位置までジャンプできます。 |
まとめ
- 「パレット」には、情報を表示し、ユーザー入力を受け付け、フォームの送信とページナビゲーションを可能にし、ページレイアウトを設定するためのコンポーネントがあります。
- 「プロパティー」ウィンドウを使用して、コンポーネントの外観と動作を設定します。プロパティーの
get メソッドと set メソッドを使用してプロパティーの値をプログラムで定義することもできます。
- ほとんどのプロパティーはデータにバインドできます。
- バインドされたデータの値変換は IDE によって処理されます。コンバータを使用してコンポーネントの値を変換することもできます。
- 入力の妥当性検査には、「
required」プロパティー、バリデータ、および妥当性検査イベント処理を使用できます。
- 仮想フォームを使用すると、フォームの送信時に処理するコンポーネントを簡単に制御できます。
- アクションメソッドと URL を使用してページナビゲーションを定義します。
- 値変更イベント処理を使用して入力を処理します。
更新日: 2007 年 5 月 24 日
