Rich UI の検査およびフォーマット設定
このトピックでは、Model-View-Controller (MVC) でロジックを編成する方法について簡単に説明してから、Rich UI で MVC の理念を使用して検証とフォーマット設定をサポートする方法を調べます。
MVC
- ビュー は、ユーザー・インターフェース、ユーザー・インターフェースをサポートするロジック、またはユーザー・インターフェース内のビジネス・データです。
- モデル は、データベース (またはその他のデータ・ストレージ)、データベースにアクセスするロジック、またはデータベースに送信されるかデータベースから取得されるデータです。
コントローラー は、ユーザー・インターフェースとデータベース・アクセス・ロジック間でデータの転送を監視するロジックです。
多くの場合、頭字語 MVC は、複数のプラットフォーム間での処理を指します。 例えば、Windows プラットフォーム上の Rich UI アプリケーションはビューである (またコントローラーを含む) とみなされることがあるのに対して、データベースにアクセスするサービスはモデルであるとみなされることがあります。
- ビュー は、ユーザー・インターフェース内のウィジェットです。このウィジェットに追加されるデータは、他の処理で使用する前に検証する必要があります。 ウィジェットで表示することを意図されているアプリケーション・データは、表示する前にフォーマット設定する必要があります。
- モデル は、アプリケーションの内部にあるデータ・フィールドです。
EGL 定義であるコントローラーを使用すると、特定のビュー (特定のウィジェット) を特定のモデルに結合できます。コントローラーは、後述するように、 検証と形式の規則の監視も行います。
また、表示フィールド・セットと関連するコントローラーを識別するフォームを定義することもできます。このようなフォームでは、 検証とフォーマット設定に起因するエラー・メッセージを表示できます。
次のセクションでは、コントローラーとその操作方法について説明します。フォームの作成の詳細については、ここで説明されているメカニズムを使用する『Rich UI での書式処理』を参照してください。
Rich UI でのコントローラー
nameField TextField;
name String {inputRequired=yes,
validationPropertiesLibrary=myLibrary,
inputRequiredMsgKey="requiredMessage"};
- inputRequired は、そのデータ・フィールド (モデル) に関連付けられたすべてのウィジェット (ビュー) にユーザーが入力を提供するようにします。
- validationPropertiesLibrary は、メッセージとその他のテキストで使用するための宣言を含むライブラリー (ステレオタイプ RUIPropertiesLibrary) を識別します。このプロパティーを含めない場合は、EGL ランタイムはデフォルト・メッセージにアクセスします。Rich UI における検証メッセージのカスタマイズの詳細については、『表示可能テキストのプロパティー・ファイルの使用』を参照してください。
- inputRequiredMsgKey は、カスタマイズされた検証メッセージを識別します。
nameController Controller
{ @MVC
{ model=name, view=nameField },
validators = [myValidationFunction01, myValidationFunction02]
};
宣言は、特定のモデル (name フィールド) を特定のビュー (nameField ウィジェット) と結合します。 一般に、特殊タイプのウィジェットのみをコントローラー・ビューにすることができます。これについては『コントローラー・ビューとして使用可能なウィジェット』で説明しています。
- ビューからモデルにデータを転送するには、データを検証してから、検証されたデータをコミットします。ほとんど場合、コミット・ステップにより、通貨記号などの書式制御文字は除去されます。
- モデルからビューにデータを転送するには、データを公開します。ほとんどの場合、公開ステップでは、表示のためにデータをフォーマットします。
Delegate
MVCValidatorFunction(input String in) returns(String?)
end
この関数が空ストリングまたは NULL を返せば、バリデーターへの入力は有効であると見なされます。一方、バリデーターが内容を含むストリングを返せば、入力は無効です。そのようなストリングは、エラー・メッセージであると見なされます。関数がエラー・メッセージを返す場合、後続の関数は実行されません。
if (nameController.isValid())
nameController.commit();
end
ユーザー入力の検証
- isValid 関数は、ユーザーがウィジェットからフォーカスを移動させるときにはいつでも呼び出されます。
さらに、失敗した検証の結果であるエラー・メッセージを表示する関数をコードで呼び出すこともできます。
エラー・メッセージは、ユーザーがウィジェットにフォーカスを戻したときではなく、検証が正常に実行されたときのみ削除されます。
- validate 関数は、isValid 関数によって呼び出され、最初に検出したエラーのメッセージを保管しますが、そのメッセージは表示しません。保管されたエラー・メッセージには、コントローラー固有の getErrorMessage 関数を呼び出すことでアクセスできます。この関数にはパラメーターはなく、タイプ STRING? の値を返します。
コードでは、制御を向上させるために、isValid 関数の代わりに validate 関数を呼び出すことができます。 例えば、コードで validate 関数を呼び出して、エラーが検出された場合にヘルプ・ページを表示するかまたは他の何らかのアクションを取るかどうかをテストすることができます。さらに、関数から戻されたエラー・メッセージを表示しないようにすることもできます。
- isControllerValid 関数を呼び出すことで、有効な状態変更リスナーに通知せずにコントローラーの有効な状態を検査できます。
関連するコントローラー固有の関数は isValidStateInitialized です。これは、コントローラー固有の検証関数 (isValid または validate のいずれか) が、Rich UI アプリケーションの現在の実行で一度でも実行されたかどうかを示します。 関数 isValidStateInitialized にはパラメーターはなく、ブール値を返します。
- DojoCurrencyTextBox
- DojoDateTextBox
- DojoTextField
- DojoTimeTextBox
- 失敗したビュー・レベルの検証結果のエラー・メッセージは、必ずウィジェットの近くにツールチップで表示されます。
ウィジェットがフォーカスを失うと、ツールチップは非表示になります。ウィジェットがフォーカスを得ると、ツールチップは表示されます。
上述の動作は、Dojo の特性です。
- ユーザーがフォーカスをウィジェットから移動させると、コントローラー・レベルの検証が実行されます。ただしこれはビュー固有の検証が正常に実行された場合に限ります。
- retrieveViewHelper プロパティー (例には示されていません) によって参照されている関数を実行します。このプロパティーは、ウィジェット・コンテンツを取得する関数を識別します。関数はパラメーターを持たず、ストリングを戻します。この関数を使用して、何らかの方法で入力を変換できます。ただし、ほとんどの場合、retrieveViewHelper プロパティーを設定する必要はありません。このプロパティーがない場合は、ウィジェット・コンテンツは、後続の処理ではストリングとして使用可能です。
- unformatters プロパティー (例には示されていません) によって参照されている関数を実行します。このプロパティーは、関数の配列を識別します。それぞれにストリング・パラメーター (STRING in) があり、ストリングを戻します。これらの関数を使用して、入力から書式制御文字を除去できます。最初にリストされている関数は retrieveViewHelper 関数から戻されたストリングを受け入れ、その後にリストされている各関数はその前の関数から戻されたストリングを受け入れます。unformatters プロパティーを設定する必要はないことがあります。
- フォーマット設定プロパティーをソース・コードに指定してある場合は、そのプロパティーに従ってユーザー入力から書式制御文字を削除します。 書式制御文字の例には通貨記号があります。通貨記号は、currency プロパティーに関連付けられています。2 番目の例は、dateFormat プロパティーで指定された区切り文字です。
- データ型に関連する検証エラーが発生した場合は、ユーザーに制御を戻します。例えば、モデルが数値フィールドである場合にユーザーが文字を入力した場合などです。
- ビューではなくモデル に設定されている EGL プロパティーによって
指定されている基本検証を実行します。
後のセクションでは、例に示されている inputRequired を含め、使用可能なプロパティーをリストします。(このプロパティーは、そのデータ・フィールドに関連付けられたすべてのウィジェットにユーザーが入力を提供するようにします。)
以下に、基本検証の考えられる結果を示します。- いずれかの基本検証が失敗した場合は、制御はユーザーに戻ります。
コントローラーがフォームに関連付けられている場合、最初に失敗した検証に関連するメッセージが保管されます。
特定の検証でデフォルトの EGL メッセージを受け入れることができます。ただし、独自のメッセージを指定する場合は、『表示可能テキストのプロパティー・ファイルの使用』の説明を参照してください。
- 基本検証がすべて完了した場合は、次に説明されているように、バリデーターが実行されます。
- いずれかの基本検証が失敗した場合は、制御はユーザーに戻ります。
コントローラーがフォームに関連付けられている場合、最初に失敗した検証に関連するメッセージが保管されます。
- コントローラーの validators 配列に指定された順にバリデーターが実行されます。
各バリデーターは、通貨記号などの書式制御文字のない入力ストリング (STRING in) を受け入れます。また、各バリデーターはストリングまたは NULL を戻します。(戻り値はタイプ STRING? です。)
バリデーターが NULL またはブランクを戻す場合は、EGL ランタイムは、検証が正常に完了したとみなします。ただし、『表示可能テキストのプロパティー・ファイルの使用』で説明されているように、バリデーターが異なる値 (例えば、プロパティー・ファイルから取得された値) を戻す場合は、以下の記述が適用されます。
- EGL ランタイムは、検証が失敗したとみなします。
- 制御は即時にユーザーに戻されます。その場合は、後続のバリデーターは実行されません。
- 返されるストリングは、エラー・メッセージとして保管されます。 ビュー・レベルの検証をサポートする EGL Dojo ウィジェットに固有の詳細については、EGL Dojo ウィジェットでのコントローラー・レベルのエラー・メッセージの表示を参照してください。
複数のコントローラーによりアクセスされるバリデーターを作成できます。 コントローラーを識別できるようになったため、再利用が可能です。これについては以下に示します。function commonValidator(input string in) returns(string?) currController Controller = MVCLib.getCurrentContext(); viewId string = currController.view.id; end
最後に、publishMessageHelper プロパティーは単一のパラメーターを持つ関数を取ります。これは IN により変更され、戻り値はありません。 この関数は、ウィジェットがフォーカスを得ると呼び出され、その関数への入力は、ウィジェットがフォーカスを失ったときに保管された最終メッセージになります。
無効な入力の表示の変更およびエラー・メッセージの処理
デフォルトでは、無効なコンテンツがあるウィジェットは、カスケード・スタイルシート (CSS) クラス (特に、EglRuiTextField などの初期クラスと 2 次クラス FormErrorEditor) で指定されたスタイルで表示されます。組織の Web 設計者は、最大の効果が得られるようにスタイル・シートをセットアップする可能性が高くなります。
検証の失敗に応答して異なる CSS クラス・セット (または異なる CSS ID) を割り当てることも、表示される出力の別の側面を変更することもできます。 例えば、(デフォルトでは) 検証フォームを使用するときのように、CSS クラスをラベルに割り当てることができます。(詳細については、『Rich UI での書式処理』を参照してください)。
- EGL ランタイムが検証の終了時に呼び出す機能を識別するコントローラー・プロパティー validStateSetter を設定します。
- 2 つのパラメーターを持ち、
戻り値を持たない関数を作成します。
最初のパラメーターは、検証中のデータを保持するウィジェットを受け取ります。2 番目のパラメーターは、検証が成功したかどうかを示します。
以下に、各関数が準拠する必要がある Delegate パーツを示します。
Delegate MVCValidStateSetter(widget Widget in, valid boolean in) end - この関数では、別のクラスまたは追加のクラス (または別の CSS ID) を、無効なコンテンツを含むウィジェット、またはほとんどの場合はそのウィジェットのラベルに割り当てます。
同じ関数で、コントローラー固有の getErrorMessage 関数を呼び出すことで、コントローラー・レベルのエラー・メッセージにアクセスできます。 前述のとおり、関数にはパラメーターはなく、タイプ STRING? の値を返します。
EGL Dojo ウィジェットでのコントローラー・レベルのエラー・メッセージの表示
- ビュー・レベルの検証をサポートする EGL Dojo ウィジェットに関して、ビュー・レベルの検証からのすべてのメッセージを表示するツールチップにメッセージを配置できます。
この場合、ウィジェットはエラーに応答して即時にエラー標識を表示します。しかしコントローラー・レベルのメッセージは、ウィジェットがフォーカスを得た後に初めて表示されます。
(ビュー・レベルの検証の以前の説明については、ユーザー入力の検証を参照してください。)
ウィジェットがフォームに関連付けられている場合、エラー・ラベルを除去することで、コントローラー・レベルのエラー・メッセージがエラー・ラベルに表示されないようにすることができます。
- すべての EGL または EGL Dojo ウィジェットに関して、エラー・ラベルにメッセージを配置することができます。これについては『Rich UI での書式処理』で説明しています。
この場合、ウィジェットはエラーに応答して即時にエラー標識を表示します。さらに、メッセージはエラーが発生するとすぐに表示されます。
エラー・ラベル内にメッセージを配置することに決め、ビュー・レベルの検証をサポートする EGL Dojo ウィジェットを使用している場合、メッセージがツールチップに表示されないようにすることができます。 重複する表示を避けるには、コントローラー固有の publishMessageHelper プロパティーをヌルに設定するか、または独自の関数をそのプロパティーに割り当てます。 プロパティーを設定しないでおくか、または独自の関数を割り当てる場合、内部 EGL 関数を呼び出して、エラー・メッセージをツールチップに送信します。
ビュー・レベルの検証をサポートする EGL Dojo ウィジェット用の資料に記載されているとおり、ウィジェット固有の showErrorIndicator 関数を呼び出すことでエラー標識を設定したり、ウィジェット固有の showErrorMessage 関数を呼び出すことでエラー・メッセージを表示したりできます。
検証済みの入力のコミット
- retrieveViewHelper プロパティーは、ウィジェット・コンテンツを取得する関数を識別します。関数はパラメーターを持たず、ストリングを戻します。この関数を使用して、何らかの方法で入力を変換できます。ただし、ほとんどの場合、retrieveViewHelper プロパティーを設定する必要はありません。このプロパティーがない場合は、ウィジェット・コンテンツは、後続の処理ではストリングとして使用可能です。
- unformatters プロパティーは、関数の配列を識別します。それぞれにストリング・パラメーター (STRING in) があり、ストリングを戻します。これらの関数を使用して、入力から書式制御文字を除去できます。最初にリストされている関数は retrieveViewHelper 関数から戻されたストリングを受け入れ、その後にリストされている各関数はその前の関数から戻されたストリングを受け入れます。unformatters プロパティーを設定する必要はないことがあります。
- ソース・コードに指定されているフォーマット設定プロパティーがある場合は、書式制御文字は、そのプロパティーに従ってユーザー入力から除去されます。 書式制御文字の例には通貨記号があります。通貨記号は、currency プロパティーに関連付けられています。2 番目の例は、dateFormat プロパティーで指定された区切り文字です。
- commitHelper プロパティーは、モデルに値を割り当てる関数を識別します。この関数はストリング・パラメーターをとり、戻り値はありません。このプロパティーを設定する必要はないことがあります。 このプロパティーがない場合は、モデルは、前の関数によって提供されたストリング (ある場合) のうち、書式制御文字を含まないストリングを受け取ります。
モデル・データの公開
- retrieveModelHelper プロパティーは、データ・コンテンツを取得する関数を識別します。関数はパラメーターを持たず、ストリングを戻します。この関数を使用して、何らかの方法で出力を変換できます。ただし、ほとんどの場合、retrieveModelHelper プロパティーを設定する必要はありません。このプロパティーがない場合は、モデル・コンテンツは、後続の処理ではストリングとして使用可能になります。
- 書式制御文字は、ソース・コードに指定されたフォーマット設定プロパティーがあれば、それに従うデータ内容に追加されます。 書式制御文字の例には通貨記号があります。通貨記号は、currency プロパティーに関連付けられています。2 番目の例は、dateFormat プロパティーで指定された区切り文字です。
- formatters プロパティーは、関数の配列を識別します。それぞれにストリング・パラメーター (STRING in) があり、ストリングを戻します。これらの関数を使用して、出力をフォーマットできます。最初にリストされている関数は、ステップ 2 で追加した書式制御文字とともに、retrieveModelHelper 関数から戻されたストリングを受け入れます。その後にリストされているそれぞれの関数は、前の関数から戻されたストリングを受け入れます。 formatters プロパティーを設定する必要はないことがあります。
- publishHelper プロパティーは、ビューに値を割り当てる関数を識別します。この関数には、1 つのストリング・パラメーター (STRING in) があり、戻り値はありません。このプロパティーを設定する必要はないことがあります。 このプロパティーがない場合は、ビューは、前の関数によって提供されたストリング (ある場合) のうち、書式制御文字を含むストリングを受け取ります。
検証プロパティーとフォーマット設定プロパティー
- フォーマット設定の場合は F です。このカテゴリーのプロパティーは、コミット中に書式制御文字を除去して、公開中に書式制御文字を追加します。これらのいずれかのプロパティーを使用すると、エラー・メッセージが表示されることがあります。例えば、入力された日付が必要な日付形式と大幅に異なる場合や、整数値が 0 または 1 以外の数値であるが、isBoolean に関連付けられている場合などです。
- 入力検証の場合は V です。
- currency (F)
- currencySymbol (F)
- dateFormat (F)
- fillCharacter (F)
- inputRequired (V)
- inputRequiredMsgKey (V)
- isBoolean (F)
- isDecimalDigit (V)
- isHexDigit (V)
- lowercase (F)
- minimumInput (V)
- minimumInputMsgKey (V)
- numericSeparator (F)
- sign (F)
- timeFormat (F)
- timestampFormat (F)
- typeChkMsgKey (V)
- uppercase (F)
- validValues (V)
- validValuesMsgKey (V)
- zeroFormat (F)
- inputRequiredMsgKey (V)
- minimumInputMsgKey (V)
- typeChkMsgKey (V)
- validValuesMsgKey (V)
DataItem 定義、変数、またはレコード・フィールドで検証プロパティーとフォーマット設定プロパティーを指定できます。ただし、これらのプロパティーは、コントローラーの宣言時に @MVC プロパティーを指定する場合に、特定の Rich UI コントローラーについてのみ有効になります。