验证行为

当字段获得焦点和/或失去焦点时,验证值在进行任何合理的更正后是否有效。

根据转换器(为值指定格式/模式)和任何验证约束来检查字段。有关转换器和验证器的详细信息,请参阅 JSF 转换器JSF 验证器

当字段获得焦点或失去焦点时,检查以查看该字段的值是否有效。如果值有效,则执行下列步骤(除第一步之外都是可选的):
  • 使用转换的值更新字段值
  • 运行 JavaScript 函数
  • 设置字段的 CSS 类
  • 设置标签的 CSS 类
  • 隐藏 error-span 并显示 info-span
  • 运行一个或多个操作
同样,如果字段的值无效,则执行下列步骤(所有步骤都是可选的):
  • 运行 JavaScript 函数
  • 设置字段的 CSS 类
  • 设置标签的 CSS 类
  • 显示 error-span 并隐藏 info-span(除非 span“始终”显示在屏幕上)
  • 运行一个或多个操作

当使用 onfocus 事件来运行行为时,如果可通过提供的转换器(未调用验证器)将字段转换为 JavaScript 对象,则该字段被视为有效。注意,如果提供了 error-span,则当该 error-span 可视时,此字段在初始时被视为出错。

当使用 onblur 事件来运行行为时,如果可通过提供的转换器将字段中的字符串(字段值)转换为 JavaScript 对象,则该字段被视为有效。例如,如果日期/时间模式为“MM/dd/yy”,则字符串“12/31/04”可以转换,但值“13/40/99”不能转换。如果转换成功,则将根据验证器中提供的任何验证约束来检查该值。有关转换器和验证器的详细信息,请参阅 JSF 转换器JSF 验证器

如果字段有效,则当使用 onblur 来运行行为时,值将转换回至字符串,并将结果放入字段值中,这可确保值包含可选的字面值,显示由转换器提供的字符等。例如,如果精确性设置为 1(适当的精确性)且模式为“MM/dd/yy”,则字符串“11/22”被视为有效(提供了年份)并显示“补全的”值“11/22/05”。在对 onfocus 和 onblur 调用更新值后,如果提供了 success-function,则将运行该函数。如果该函数未返回 false,则字段的 CSS 类被设置为 success-class(如果提供)并运行 success-action(如果提供)。

如果字段无效,则其值保留不变,并运行 error-function(如果提供),字段的 CSS 类被设置为 error-class(如果提供),然后运行 error-action(如果提供)。

success-function 具有一个附加的功能。如果运行该函数,则它的返回值会被作为一个“验证器”来处理。如果该函数返回 true,则将执行成功 CSS 和操作。如果该函数返回 false,则将运行整个错误处理任务,即运行 error-function,应用错误 CSS 以及运行 error-action。因此,success-function 既可以处理验证的附加阶段,也可以处理“成功”特征,例如,隐藏一个错误 div。

error-function 和 success-function 具有与一般的 JavaScript 函数一样的特征符,即,传递给函数的第一个参数是“this”指针,传递给函数的第二个参数是事件对象。使用两个附加的属性对该事件对象进行了扩充。如果发生了错误,则将使用错误消息(已本地化)来填充属性 evt.errorMsg。如果成功,则使用转换的值来填充属性 evt.objValue,例如,对于日期/时间字段,如果存在转换的值,则将使用该值对 JavaScript 日期对象进行赋值。

发送组件的 JSF 标记

<hx:inputHelperAssist>

<hx:formItem>

基本 HTML

<input type="text" /><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,则将使用 default-class 作为 success-class。

success-action

字段有效时要执行的操作。请参阅有关操作的文档以获取可用操作的列表。

success-target

字段有效时成功操作的目标。请参阅有关操作的文档以获取目标的描述。如果未提供任何目标,则字段自身将用作为目标。

error-action

字段无效时要执行的操作。请参阅有关操作的文档以获取可用操作的列表。

error-target

字段无效时成功操作的目标。请参阅有关操作的文档以获取目标的描述。如果未提供任何目标,则字段自身将用作为目标。

success-function

字段有效时要执行的 JavaScript 函数或 JavaScript 的内联字符串。如果函数返回 false,则验证将失败并执行错误操作/函数。

error-function

字段无效时要执行的 JavaScript 函数或 JavaScript 的内联字符串。

label-id

如果提供,则为页面上用作字段标签的标记的 ID。该 ID 通常标识一个 span 或一个 div。

label-success-class

字段通过验证/转换时要应用于标签的 CSS 类的名称。

label-error-class

字段验证/转换失败时要应用于标签的 CSS 类的名称。

info-span-id

页面上包含与字段相关联的“帮助”或“参考”文本的标记的 ID。字段出错时将隐藏此标记。该 ID 通常标识一个 span 或一个 div。

error-span-id

页面上相应标记的 ID,该 ID 用于显示与字段相关联的错误。当页面显示时,如果此标记可视,则假定字段在初始时出错,例如,未通过服务器端验证。该 ID 通常标识一个 span 或一个 div。

span-is-popup

如果提供了关键字,则 info-span 和 error-span 将被作为块级别元素(作为 div)来处理,然后放置在输入字段的正上方、下方或左边,例如,作为“弹出菜单”。

info-span-always

如果为 true,则 info-span 将始终显示,除非发生了错误。否则,info-span 仅在字段获得焦点时才显示。

error-span-always

如果为 true,则只要检测到任何种类的客户端错误,error-span 的内容都将始终显示(按原样)。否则,如果检测到客户端错误,则将使用 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")); 

反馈