Zen のフォーム

フォームとコントロール

Zen ライブラリには、フォームで使用するコントロールが多数用意されています。これらのコントロールの多くは、標準的な HTML コントロールのラッパですが、それらにはない機能を持つものもあります。以下の図は、テキスト・フィールドやラジオ・ボタンなど、多数のコントロールを持つフォームを示します。これは、SAMPLES ネームスペースのクラス ZENDemo.FormDemoOpens in a new tab で生成したサンプル・フォームです。

以下の図は、Zen に用意されているフォーム・コンポーネントおよびコントロール・コンポーネントのリストです。図に挙げられているクラスのほとんどはコントロールです。 図に示されているすべてのクラス、例えば %ZEN.Component.formOpens in a new tab や %ZEN.Component.controlOpens in a new tab などは、パッケージ %ZEN.Component にあります。図は、これらのクラスの継承関係を表し、このドキュメントで最も頻繁に取り上げるベース・クラスに焦点を当てます。

個々のコントロールの詳細は、“Zen コントロール” の章を参照してください。

ユーザ対話

Zen アプリケーション・ユーザと Zen フォームの間の基本的な対話は以下のとおりです。

1. ユーザはフォーム上のコントロールと対話します。

2. Zen ではデータの入力時にそのデータを検証できます。

3. ユーザ・アクションにより、フォームの送信を指示します。

4. Zen では、送信する前にデータを検証できます。

5. Zen ではユーザと対話して、検出されたエラーを処理します。

6. すべてのエラーが解消されると、Zen ではフォームのデータを送信します。

7. 以下のいずれかが実行されることがあります。

   • フォームのデータがサーバに書き込まれます。

   • 同じ Zen ページが再表示されます。

   • 別の Zen ページが表示されます。

   • 同じ Zen ページが、コンポーネントを追加または変更して表示されます。

フォームの定義

Zen コンポーネント “<form>” および “<dynaForm>” はそれぞれ、フォームの特性を定義する以下の属性をサポートします。

OnLoadForm メソッドは、最初に開いたときにフォームに表示される値を取得します。これは、モデル ID がフォームの key 属性で指定されるオブジェクトから値を取得することも、リテラル値を割り当てることもできます。またこのメソッドでは、それらの値を入力配列に配置する必要があります (配列は、フォームの対応するコントロールの name 属性が添え字になります)。コントロールと値を関連付ける属性は、この name であって、id ではありません。Zen は、初めてフォームを描画するときに、このメソッドを呼び出して、自動的に以下のパラメータを渡します。

• %StringOpens in a new tab — フォームの key 値。

• 参照渡しの %StringOpens in a new tab の配列。

このコールバックは、データ型が %StatusOpens in a new tab である値を返す必要があります。以下の例は、有効なメソッド・シグニチャとパラメータの使用法を示しています。

Method LoadForm(pKey As %String,
                ByRef pValues As %String) As %Status
{
  Set emp = ##class(ZENDemo.Data.Employee).%OpenId(pKey)
  If ($IsObject(emp)) {
    Set pValues("ID") = emp.%Id()
    Set pValues("Name") = emp.Name
    Set pValues("SSN") = emp.SSN
  }
  Quit $$$OK
}

コールバックとして上のメソッドを使用するには、<form> または <dynaForm> で OnLoadForm="LoadForm" と設定します。

フォームの値の指定

初期状態のフォームでは、すべてのフィールドを空白のまま表示できるほか、いくつかのフィールドにデータが入力された状態にしておくこともできます。ユーザに対して表示するフィールドにデータを指定するには、Zen でフォームを表示する前に、そのフィールドに関連付けた Zen コントロール・コンポーネントの value プロパティを設定しておきます。それには以下のような方法があります。

• XData ontents に各コントロールを追加する際に value 属性を設定します。

  <text value="hello"/>

• XData Contents にフォームを追加する際に onLoadForm 属性を設定します。

  <form id="MyForm" OnLoadForm="LoadForm">

• ページの %OnAfterCreatePage メソッドの value プロパティを設定します。

  Do ..%SetValueById("Doctor",$G(^formTest("Doctor")))

• クライアント側で、各コントロールの setValue メソッドを呼び出します。

ユーザがフォームの編集を開始すると、任意のコントロールの初期値を変更できます。

フォームの変更の検出

Zen フォーム・コンポーネントは、フォーム上のいずれかのコントロールで変更が発生したかどうかを追跡します。%ZEN.Component.formOpens in a new tab および %ZEN.Component.controlOpens in a new tab にはそれぞれ、プログラムによってこれを判定する isModified というクライアント側メソッドがあります。

コントロールの isModified メソッドは、コントロールの現在の論理値 (value プロパティ) が元の論理値 (originalValue プロパティ) と異なる場合、True を返します。送信操作を繰り返すたびに、各コントロールの originalValue はその前の value を取得するので、フォームの現在の状態に関してはこの返り値は必ず最新となります。

フォームの isModified メソッドを呼び出すと、このメソッドにより、フォームの各コントロールの isModified が呼び出されます。いずれかのコントロールが True を返すと、isModified はそのフォームについて True を返します。

フォームの検証

各 Zen フォームには、フォームの各コントロールの値の検証を目的とする validate メソッドがあります。フォームの autoValidate プロパティが True の場合、そのフォームが送信されるたびに validate が自動的に呼び出されます。それ以外の場合は、アプリケーションで明示的に validate を呼び出すことができます。validate は以下を実行します。

1. フォーム固有の onvalidate イベント・ハンドラを定義しておくと、まずこのイベント・ハンドラが呼び出されます。このイベントから False が返された場合、このフォームは無効と判断され、それ以上の検証は行われません。

2. フォームにあるすべてのコントロールの invalid プロパティを False にリセットした後、各コントロールの validationHandler メソッドを呼び出して、そのコントロールをテストします。その結果を受けて、このメソッドは以下を実行します。

   • コントロールの readOnly プロパティまたは disabled プロパティが True の場合は、True を返します。

   • コントロールの required プロパティが True で、このコントロールが値を持たない (値が "") 場合は、False を返します。

   • コントロールで onvalidate イベントを定義しておくと、そのイベントが実行され、値が返されます。それ以外の場合、コントロールの isValid メソッドが呼び出されます。isValid メソッドは、組み込みの検証機能の提供を目的とするサブクラスでオーバーライドできます (dateText コントロールなど)。

3. validate メソッドによる各コントロールの検証が進むに従って、このフォームにより、無効なコントロールのローカル配列が構築されます。

4. validate メソッドによるコントロールの検証が完了し、フォームが有効だった場合は True が返されます。

5. 無効な値を持つ 1 つ以上のコントロールがフォームに存在する場合、そのフォームは無効です。このケースに対処するために、validate は以下の追加手順のいずれかを実行します。

   • フォームで oninvalid イベント・ハンドラが定義されている場合は、以下のとおりです。

     そのハンドラを実行します。これによってフォームでエラーの状況を処理できます。その後、oninvalid イベントからの返り値が、フォームの validate メソッドから返されます。 oninvalid ハンドラには、無効なコントロールのリストが記述された JavaScript 配列を受け取る invalidList という引数があります。 以下はその例です。

     <form oninvalid="return zenPage.formInvalid(zenThis,invalidList);" />

     

     この formInvalid メソッドは以下のようになります。

     
     ClientMethod formInvalid(form,list) [ Language = javascript ]
     {
       return false;
     }

     

   • フォームに oninvalid イベント・ハンドラがない場合は、以下のとおりです。

     validate により、無効な各コントロールの invalid プロパティが True に設定され、そのコントロールのスタイルが zenInvalid に変更されます。次に、最初の無効なコントロールにフォーカスが移り、警告ボックスにエラー・メッセージが表示されます。警告ボックスに表示されるメッセージは、フォームの invalidMessage プロパティと、無効な各コントロールの getInvalidReason メソッドから返された値を組み合わせて生成されます。

エラーと無効な値

フォームの送信中にエラーが発生した場合、またはフォームの検証に失敗した場合、Zen ではそのフォームを持つページを再表示します。これにより、ユーザは、誤った値を入力し直し、そのページを再度送信できます。Zen ページに <form> コンポーネントまたは <dynaForm> コンポーネントを追加すると、これらすべてを極めて容易に設定できます。

SAMPLES ネームスペースのクラス ZENTest.FormTestOpens in a new tab を使用すると、Zen フォームでのエラー処理を次のように体験できます。

1. ブラウザを起動します。

2. 次の URI を入力します。

   http://localhost:57772/csp/samples/ZENTest.FormTest.clsOpens in a new tab

   ここで、57772 は、Caché に割り当てた Web サーバのポート番号です。

3. [名前] フィールドが空白であることを確認します。

4. [状態] チェック・ボックスのチェックを外します。

5. [実行] をクリックします。

6. フォームの validate メソッドにより無効なフィールドが検出され、そのフィールドがピンク色でハイライト表示されます。

7. 以下の警告メッセージがブラウザに表示されます。

   

   このメッセージを生成するために、フォームには以下のテキストの断片がまとめられています。Zen には、これらのアイテムの既定値が用意されているので、特に何か実行しなくても、既定のメッセージが表示されます。ただし、必要に応じて、メッセージを希望に合わせてカスタマイズできます。

   • メッセージは、フォームの invalidMessage テキストから始まります。

   • required 属性が True に設定されていて、エントリを持たないコントロールごとに、コントロールの label に続いて、requiredMessage テキストがメッセージに表示されます。

   • 無効な値を持つコントロールごとに、コントロールの label に続いて、invalidMessage テキストがメッセージに表示されます。

8. [OK] をクリックし、警告メッセージ・ボックスを閉じます。

9. 無効なコントロールは、ユーザがそのコントロールを編集し、フォームを再送信するまで、ハイライト表示されたままになります。

フォームの送信処理

フォームの内容を送信する要求は、次の 2 つのうちいずれかの方法でトリガできます。

• ユーザがフォーム内の “<submit>” ボタンをクリックします。

• アプリケーションが、以下のユーザ・イベントに応答してフォーム・オブジェクトの submit メソッドを呼び出します。

  %form.submit

フォームを送信すると、そのフォーム内のコントロールの値がサーバに送信され、そのフォームを持つページの %OnSubmit コールバック・メソッドが呼び出されます。ここで呼び出される %OnSubmit コールバック・メソッドは、フォームそのものやフォームにあるコンポーネントのものではなく、フォームを持つページのものです。

%OnSubmit は、送信されたすべての値を含む特別な %ZEN.SubmitOpens in a new tab オブジェクトのインスタンスを受信します。送信処理中は、ページ・オブジェクトは使用できなくなることに注意してください。Zen では、サーバ・コールバックの呼び出しやエラー処理など、送信操作の詳細をすべて自動的に処理します。すべてのフォームは、HTTP POST 送信メソッドを使用して送信されます。

設定 ENCODED=2 を使用すると、<form> コンポーネントが無効となります。それは、ENCODED=2 になっていると、暗号化されていないパラメータがすべて URL から削除されるためです。

以下のテーブルは、Zen で送信操作がどのように実行されているかを詳しく説明するために、内部イベントをユーザの観点、ブラウザベースの実行、およびサーバ側の実行の順に示したものです。通信の詳細部分のほとんどは、CSP テクノロジを基盤とする Zen が処理します。背景情報は、"Zen の使用法" の “Zen のクライアントおよびサーバ” の章を参照してください。

ユーザ・ログインのフォーム

アプリケーション・ログイン・ページは、Zen フォームの特殊なケースです。アプリケーションのログイン・ページとログアウト・ページを作成するには、"Zen アプリケーションの開発" の “Zen のセキュリティ” の章の “アプリケーションへのアクセスの制御” のセクションを参照してください。

動的なフォーム

<dynaForm> は、Zen ページのグループ (複数可) にコントロール・コンポーネントを動的に挿入する、特殊なタイプのフォームです。レイアウトは自動的に、<dynaForm> 内部のコードによって決まります。コントロールのリストは、関連付けられたデータ・コントローラのプロパティ、またはコントロールのリストを生成するコールバック・メソッドによって指定できます。

<dynaForm> には以下の属性があります。

OnGetPropertyInfo 属性で指定されたコールバック・メソッドは、フォームが表示されたときに挿入する追加コントロールを準備します。ページ・クラスでこのメソッドが定義されている場合、Zen は、初めてフォームを描画するときに、このメソッドを呼び出して自動的に以下のパラメータを渡します。

• %IntegerOpens in a new tab — 生成されたフォームにコントロールを適用する、次のインデックス番号。コールバック・メソッドはフォームに追加コントロールを挿入するごとに、次の例に示すように、このインデックス値をインクリメントする必要があります。

• 参照渡しの %StringOpens in a new tab の配列。

• %StringOpens in a new tab — 現在のデータ・モデル ID (動的フォームのコンテンツが、データ・モデル・オブジェクトのインスタンスごとに異なる場合)。メソッドは、このオブジェクトから値を取得することも、リテラル値を割り当てることもできます。

追加コントロールを定義するには、以下のように、メソッドで 2 つの部分の添え字を使用して、値を入力配列に配置する必要があります。

1. 最初の添え字は、フォームの対応するコントロールに割り当てられた name 属性の値です。コントロールを識別し、コントロールと値を関連付ける属性は、この name であって、id ではありません。例えば、以下の配列の位置には、フォームのコントロールの位置の順序を表すインデックス (先頭インデックスは 1) を格納します。

   pInfo(name)

2. 2 番目の添え字は、コントロール・オブジェクトのプロパティの名前です。%type は、その値でコントロールの種類を識別するコントロール・プロパティです。他のプロパティの名前は、“Zen コントロール” の章の、“コントロールの属性” のセクションまたは当該のコントロールのトピックに一覧があります。例えば、以下の配列の位置には name コントロールの attr 属性の値を格納します。

   pInfo(name,attr)

このコールバックは、データ型が %StatusOpens in a new tab である値を返す必要があります。以下の例は、有効なメソッド・シグニチャおよび、パラメータと配列の添え字の使用法を示しています。

Method GetInfo(pIndex As %Integer,
               ByRef pInfo As %String,
               pModelId As %String) As %Status
{
  Set pInfo("Field1") = pIndex
  Set pInfo("Field1","%type") = "textarea"
  Set pInfo("Field2") = pIndex + 1
  Set pInfo("Field2","label") = "Field 2"
  Quit $$$OK
}

コールバックとして上のメソッドを使用するには、<dynaForm> で OnGetPropertyInfo="GetInfo" と設定します。

生成したフォームの最後のコントロールが n 個のフィールドを持つ埋め込みプロパティから取得された場合、コールバックはインデックスをコントロールに割り当てる前に、メソッドの開始時に n をインデックス番号に加算して、過去に生成されたコントロールをインクリメントする必要があります。この規則は、フォームに最後に生成されたコントロールが %StringOpens in a new tab、%BooleanOpens in a new tab、%NumericOpens in a new tab などの単純なデータ型から取得された場合は不要です。前の例は単純なケースを示しており、メソッドは提供されたインデックスを使用し、インクリメントしています。