検証振る舞い

フィールドがフォーカスされた場合、 またはフォーカスが外れた場合に、 値に対して相応の修正を行ったあとで、 その値が有効であるかどうかを検証します。

フィールドは (値のフォーマット/パターンを指定する) コンバーターに 対してチェックされ、次にすべての検証制約に対してチェックされます。 コンバーターおよびバリデーターの 詳細については、『JSF コンバーター』 および『JSF バリデーター』を 参照してください。

フィールドがフォーカスされたとき、 またはフィールドのフォーカスが外れたときに、 フィールドの値が有効であるかどうかを調べます。 その値が有効な場合は、 以下のステップが実行されます (最初のステップ以外はオプションです)。
  • 変換された値で、フィールドの値を更新します。
  • JavaScript 関数を 実行します。
  • フィールドの CSS クラスを設定します。
  • ラベルの CSS クラスを設定します。
  • エラー・スパンを非表示にし、情報スパンを表示します。
  • アクションを 1 つ以上実行します
フィールドの値が有効でなかった場合は、 以下のステップが実行されます (すべてのステップがオプションです)。
  • JavaScript 関数を 実行します。
  • フィールドの CSS クラスを設定します。
  • ラベルの CSS クラスを設定します。
  • エラー・スパンを表示して、 情報スパンを非表示にします (スパンが「常時」表示されていない限り)
  • アクションを 1 つ以上実行します

この振る舞いを onfocus イベントを 使用して実行した場合、 提供されたコンバーターによって (バリデーターは起動されません) JavaScript オブジェクトに 変換可能なフィールドを、有効であると判断します。 エラー・スパンが提供されている場合、 そのエラー・スパンが表示されているときは、 フィールドで最初からエラーが発生していると考えられます。

この振る舞いを onblur イベントを使用して実行した場合、 文字列 (フィールドの値) から JavaScript オブジェクト に、提供されたコンバーターを使用して 変換可能なフィールドを、有効であると判断します。 例えば、日付/時刻パターンが「MM/dd/yy」であるとすると、 文字列「12/31/04」は変換可能ですが、 値「13/40/99」は変換できません。 変換が成功すると、 バリデーター内に提供された検証制約に対して、 値のチェックが行われます。 コンバーターおよびバリデーターの 詳細については、『JSF コンバーター』 および『JSF バリデーター』を 参照してください。

フィールドが有効な場合、 この振る舞いを onblur を使用して実行すると、 値が文字列に変換されて、フィールドの値に 結果が書き込まれます (これによって、 オプションのリテラルが値に組み込まれたり、 コンバーターが提供する文字が表示されたり するようになります)。 例えば、strict が 1 (中程度の厳密さ) で、 パターンが「MM/dd/yy」に設定されている場合、 文字列「11/22」は有効であると判断されて (年が提供されて)、 「完全な」値「11/22/05」が表示されます。 値が更新されたあと、success 関数が 提供されていれば、onfocus および onblur 両方を 呼び出すために、その関数が実行されます。 この関数が false を戻さなかった場合は、 フィールドの CSS クラスは success クラスに 設定され (提供されている場合)、success アクションが 実行されます (提供されている場合)。

フィールドが有効でない場合、 値はそのまま残され、error 関数が実行されます (提供されている 場合)。 フィールドの CSS クラスが error クラスに 設定されて (提供されている場合)、error アクションが 実行されます (提供されている場合)。

success 関数には、追加の機能が 1 つあります。 success 関数が実行されると、 その関数の戻り値は「バリデーター」として扱われます。 この関数が true を戻すと、success CSS と success アクションが 実行されます。 この関数が false を戻すと、 エラー処理タスク全体が実行されます (error 関数の 実行、error CSS の適用、error アクションの実行が行われます)。 したがって success 関数は、 検証の追加ステージの処理と「成功時の」機能の処理 (例えばエラー div の非表示) の 両方を行うことができます。

error 関数と success 関数は、いずれも 「通常」の JavaScript 関数と 同じシグニチャーを持ってます。 すなわち、関数に受け渡される最初の引数は 「この」ポインターで、関数に受け渡される 2 番目の引数は イベント・オブジェクトになります。 このイベント・オブジェクトは、2 つの 追加プロパティーによって拡張されます。 エラーが発生した場合、evt.errorMsg 属性に エラー・メッセージが (ローカライズされて) 取り込まれます。 success が発生すると、evt.objValue 属性に 変換された値が取り込まれます (例えば、日付/時刻フィールドには、 その値で評価される JavaScript 日付 オブジェクトが存在します)。

コンポーネントを発行する JSF タグ

<hx:inputHelperAssist>

<hx:formItem>

基本 HTML

<input type="text" /> or <textarea />

JavaScript コンストラクター

hX_5.addBehavior("id", "event-name", new hX_5.JSFBehaviorValidate(attributes)); 各部の意味は次のとおりです。

id

コンポーネントが付加される HTML タグの ID。

属性

コンマで区切られた属性のリスト。 各属性は、属性名と値から成る引用符付きストリングになっており、 コロンで区切られています (例: "label:MyLabel")。

サポートされるイベント

イベント

説明

onfocus

onfocus が付加された値は、 それが正しい「型」であるか (例えば数値であるか) どうかを チェックされます。 検証のルールはチェックされません。

onblur

onblur が付加された値は、 それが正しい型であるかどうかをチェックされます。 また、すべての検証のルールがチェックされます。

属性

表 1. 検証振る舞い属性

属性名

説明

converter

構成済みのコンバーターの ID。 コンバーターは、入力フィールド内の値のフォーマットを記述します。

validator

構成済みのバリデーターの ID。 バリデーターが提供されている場合、 そのバリデーターで記述された制約は、 ユーザーが選出できる値を制限するために使用されます。

success-class

フィールドが有効な場合、 その CSS クラスが success-class に設定されます (その表示も変更されます)。 (複数のクラス名を指定する場合は、スペースで区切ってください。)

error-class

フィールドが無効な場合、 その CSS クラスが error-class に設定されます (その表示も変更されます)。 (複数のクラス名を指定する場合は、スペースで区切ってください。)

default-class

success-class の同義語。 (success-class を指定しない場合、 このクラスが success-class として使用されます。)

success-action

フィールドが有効である場合に実行されるアクション (複数可)。 使用可能なアクションのリストについては、 アクションに関する文書を参照してください。

success-target

フィールドが有効である場合に成功したアクションのターゲット (複数可)。 ターゲットの説明については、 アクションに関する文書を参照してください。 ターゲットが指定されていない場合は、 フィールドそのものがターゲットとして使用されます。

error-action

フィールドが無効である場合に実行されるアクション (複数可)。 使用可能なアクションのリストについては、 アクションに関する文書を参照してください。

error-target

フィールドが無効である場合に成功したアクションのターゲット (複数可)。 ターゲットの説明については、 アクションに関する文書を参照してください。 ターゲットが指定されていない場合は、 フィールドそのものがターゲットとして使用されます。

success-function

フィールドが有効である場合に 実行される JavaScript 関数 (また は JavaScript の インライン・ストリング)。 この関数が false を戻した場合、 検証は失敗し、エラー・アクション/関数が実行されます。

error-function

フィールドが無効である場合に 実行される JavaScript 関数 (また は JavaScript の インライン・ストリング)。

label-id

フィールドのラベルとして使用される、 ページ上のタグの ID (タグが提供されている場合) 通常、この ID によって、スパンまたは div を識別します。

label-success-class

フィールドの検証/変換が成功した場合に、 ラベルに適用される CSS クラスの名前。

label-error-class

フィールドの検証/変換が失敗した場合に、 ラベルに適用される CSS クラスの名前。

info-span-id

フィールドに関連した「ヘルプ」テキスト または「通知」テキストが含まれている、ページ上のタグの ID。 このタグは、フィールドがエラー状態の場合には非表示になります。 通常、この ID によって、スパンまたは div を識別します。

error-span-id

フィールドに関連したエラーの表示に使用される、 ページ上のタグの ID。 ページが表示されたときに、 このタグが可視になっている場合は、 フィールドが初期エラー状態にある (例えば、 サーバー・サイドの検証に失敗した) と見なされます。 通常、この ID によって、スパンまたは div を識別します。

span-is-popup

キーワードが提供されている場合、 情報および誤差幅がブロック・レベルの要素 (div) として処理され、 入力フィールドの上、下または左に (例えば「ポップアップ」として) 配置されます。

info-span-always

true の場合、info-span は (エラーが 発生しない限り) 常時表示されます。 それ以外の場合、info-span は フィールドがフォーカスされている間のみ表示されます。

error-span-always

true の場合、 何らかのクライアント・サイドのエラーが検出されるたびに、 誤差幅の内容が必ず (現状のまま) 表示されます。 それ以外の場合、 クライアント・サイドのエラーが 検出されると、hxclient_v3_s.js のエラー・メッセージが使用されます。

順序付け

イベント用に指定された他のハンドラーのあとに、実行されます。

イベントのバブルを停止します。 onblur イベントまたは onfocus イベントの続行は、 停止することができません。

API 呼び出し

表 2. 検証振る舞い API 呼び出し

API 呼び出し

説明

object = setAttribute(attribute)

属性を設定します。 属性がすでに設定されたものである場合は、 その値を変更します。

string = getAttribute(attribute-name)

属性の現行値を取得します。

制限

サンプル・コード

onblur が発生した場合に、日付フィールドが正しいことと、 指定された制約内にあることをチェックします。 そうでない場合は、CSS クラスを変更します。

hX.addConverter("24", new hX.DateTimeConverter("strict:1", "format:MM/dd/yyyy"));
hX.addValidator("25", new hX.DateTimeValidator( "min-bound:20000101000000",  "required:true"));
hX.addBehavior("form1:text1", "onblur", new hX.JSFBehaviorValidate("success-class:inputText", 
                 "converter:24", "validator:25", "error-class:inputText_Error"));

onblur が発生した場合に、数値フィールドが正しいこと、 指定された制約内にあること、func_1 関数が指定する カスタム検証に一致していることをチェックします。 失敗した場合は CSS クラスを変更します。

<SCRIPT>
function func_1(thisObj, thisEvent) {
    if (thisEvent.objValue != null) {
        if (thisEvent.objValue == 10 || thisEvent.objValue == 20)
            return false;
    }
    return true;
}
</SCRIPT>

hX.addConverter("26", new hX.NumberConverter("strict:1", "pattern:#,##0", "locale:,.%?-$"));
hX.addValidator("28", new hX.NumberValidator( "min-bound:0.0",  "max-bound:100.0",  "required:true"));
hX.addBehavior("form1:text2", "onblur", new hX.JSFBehaviorValidate("default-class:inputText", 
                 "converter:26", "validator:28", "success-function:return func_1(this, event);", 
                 "error-class:inputText_Error"));

指定された文字セット内の 文字のみがフィールドに含まれている こと、その長さが 1 文字または 2 文字であることをチェックします。 フィールドがフォーカスされた場合、 それが有効であれば、フィールドがフォーカスされていることを 表すように CSS スタイルを変更し、 フィールドのコンテンツを選択解除して、 通知プロンプトを表示し、 エラー・メッセージを非表示にします。 有効でない場合は、 フィールドでエラーが発生していることを 表すように CSS スタイルを変更し、 エラー・メッセージを表示します。 フィールドからフォーカスが外れた場合、 そのフィールドが有効であれば、CSS クラスを通常の表示に変更し、 エラー・メッセージと通知プロンプトを非表示にします。 有効でない場合は、エラー・メッセージを表示して、 通知プロンプトを非表示にし、 フィールドの CSS を変更して、 フィールドのコンテンツを選択します。

hX.addValidator("1e", new hX.StringValidator("constraint-regexpression:^[A-Za-z]+$", "required:true", 
            "min-length:2"));
hX.addBehavior("form1:text1", "onfocus", new hX.JSFBehaviorValidate("validator:1e", 
            "error-class:inputTextWhite_Error", "success-class:inputTextWhite", 
            "success-action:unselect", "info-span-id:form1:span1", 
            "error-span-id:form1:span2", "span-is-popup:below")); hX.addBehavior("form1:text1", "onblur", new hX.JSFBehaviorValidate ("validator:1e", 
            "error-class:inputTextWhite_Error", "success-class:inputText", 
            "error-action:selected", "info-span-id:form1:span1", 
             "error-span-id:form1:span2", "span-is-popup:below")); 

フィードバック