jsf-comp

Introduction

JSF Client Validators component library provides a rich set of implementation independent custom components aiming to bring client side validation features to the JSF Framework. Validators has several customization attributes like display mode, highlighting, error messages and etc.

Dependencies

The only dependency at runtime is a JSF implementation. Although myFaces is the suggested implementation, the library is also tested with the RI.

JSF Implementation: MyFaces 1.1.X

Installation

classpath

Put the clientvalidators-0.9.0.jar to the WEB-INF/lib of your JSF application.

taglib

Define the taglib at the top of your jsf page.

<%@ taglib uri="http://sourceforge.net/projects/jsf-comp/clientvalidators" prefix="cv"%>

return validate();

Define the javascript caller for the component causing the submit. Examples should be a form's onSubmit, a button's onClick and etc.

Form onSubmit: <h:form id="form1" onSubmit="return validate();" />
Button onClick: <h:commandButton id="btn1" onClick="return validate();" />

Prefix Mapping

Resources are loaded from the distribution jar using the default /faces/* prefix, make sure this mapping is defined in web.xml.

<servlet-mapping
	<servlet-name>Faces Servlet</servlet-name>
	<url-pattern>/faces/*</url-pattern>
</servlet-mapping>

Validators in Detail

Required Field Validator

Validates whether the input is empty or not.

componentToValidate: Server id of the component to be validated.
errorMessage: Message to be displayed in case the input is empty.
highlight: A boolean value, if indicated as true the component with the invalid input is highlighted with color. Default value is false.
display: Optional attribute indicating the display mode of the validation error. Possible values are "static", "dynamic" (default), "none". More info at display mode section.
style: Optional attribute specifying the style class of the validation message.

Example:

<cv:requiredFieldValidator componentToValidate="txt1" highlight="true" display="dynamic" errorMessage="Value is required"/>

Range Validator

Validates whether the input satisfying the range requirements or not. Either minValue or maxValue must be supplied.

componentToValidate: Server id of the component to be validated.
minValue: Value the input must be greater or equal.
maxValue: Value the input must be less or equal.
errorMessage: Message to be displayed in case the input is empty.
highlight: A boolean value, if indicated as true the component with the invalid input is highlighted with color. Default value is false.
display: Optional attribute indicating the display mode of the validation error. Possible values are "static", "dynamic" (default), "none". More info at display mode section.
style: Optional attribute specifying the style class of the validation message.

Example:

<cv:rangeFieldValidator componentToValidate="txt1" minValue="10" maxValue="20" highlight="true" />

Compare Validator

Validates whether the input of these components equal or not.

componentToValidate: Server id of the component to be compared.
componentToCompare: Server id of the component whose value to be compared with.
operator: Comparing is done according to this attribute. Possible values are "eq" and "not".
errorMessage: Message to be displayed in case the input is empty.
highlight: A boolean value, if indicated as true the component with the invalid input is highlighted with color. Default value is false.
display: Optional attribute indicating the display mode of the validation error. Possible values are "static", "dynamic" (default), "none". More info at display mode section.
style: Optional attribute specifying the style class of the validation message.

Example:

<cv:compareValidator componentToValidate="txt1" componentToCompare="txt2" op="not"  errorMessage="Value is invalid"/>

Regular Expression Validator

Validates whether the input satisfies the pattern of a regular expression.

componentToValidate: Server id of the component to be validated.
pattern: A mandatory attribute specifying the regular expression pattern the input must satisfy.
errorMessage: Message to be displayed in case the input is empty.
highlight: A boolean value, if indicated as true the component with the invalid input is highlighted with color. Default value is false.
display: Optional attribute indicating the display mode of the validation error. Possible values are "static", "dynamic" (default), "none". More info at display mode section.
style: Optional attribute specifying the style class of the validation message.

Example:

<cv:regularExpressionValidator componentToValidate="txt1" pattern="/[abcd]/" highlight="true" />

Length Validator Validator

Validates whether the length of the input satisfies the length requirements.

componentToValidate: Server id of the component to be validated.
exactly: The length of the input must be equal to the value supplid with this attribute.
min: The length of the input must be (ge) greater than or equal to the value supplid with this attribute.
max: The length of the input must be (le) less or equal to the value supplid with this attribute.
errorMessage: Message to be displayed in case the input is empty.
highlight: A boolean value, if indicated as true the component with the invalid input is highlighted with color. Default value is false.
display: Optional attribute indicating the display mode of the validation error. Possible values are "static", "dynamic" (default), "none". More info at display mode section.
style: Optional attribute specifying the style class of the validation message.

Example:

<cv:lengthValidator componentToValidate="txt1" exactly="10" display="dynamic" errorMessage="Value is invalid"/>

Integer Only Validator

This validator is not implemented as a component instead comes as a javascript function. It disables the keypressing of letters and allow only integers. Function call onkeypress must be "keyPressNumber(false);"

Example:

<h:inputText id="txt_ssn" value="#{pc_Index.person.ssn}" onkeypress="keyPressNumber(false);"/>

Custom Validator

Enables application developers to integrate their own validators to the client validation framework.

componentToValidate: Server id of the component to be validated.
function: Name of the javascript function that will be called during validation.
params: String representing the parameters of the specified function.
errorMessage: Message to be displayed in case the input is empty.
highlight: A boolean value, if indicated as true the component with the invalid input is highlighted with color. Default value is false.
display: Optional attribute indicating the display mode of the validation error. Possible values are "static", "dynamic" (default), "none". More info at display mode section.
style: Optional attribute specifying the style class of the validation message.

Example:

<cv:customValidator componentToValidate="txt_custom" function="customFunctionName" params="'form1:txt_custom'" />

function customFunctionName(param1) {
var value = document.all[param1].value;
if(value == 'someValueToBeTested')
	return true;
else
	return false;
}

Validation Summary

If supplied in the page, the validation summary displays all the validation errors in the page.

style: Optional attribute specifying the style class of the validation message.

Example:

<cv:validationSummary />

Script Generator

Main component responsible for encoding the validator function calls.

form: Server id of the form to be validated.
popup: Optional attribute, if flagged as true then the validation summary is displayed in a popup. Default is false.

Example:

<cv:scriptGenerator popup="false" />

Internalization and Error Messages

Client validators follow a chain when getting the error message for the validation.

1) errorMessage attribute: At first message supplied with this attribute is used. It can also take a valuebinding expression as well as a static text.
2) Resource Bundle: If errorMessage attribute is not supplied then messages in the application's message bundle is checked with the specifed keys. These built-in keys are shown at f.a.q. section.
3) Built-in constant messages.: In the end, if there is no message with the specified key then message is retrieved hardcoded.

F.A.Q. and MORE INFO

1) What is display attribute for?

Display mode is customized using the "display" attribute. Here are the possible values and their effects.
					dynamic
Default display mode, the space for the validation message is not reserved and created when the validation error occurs.
static
Space for the validation message is allocated.
none
Validation error is not displayed where the validator component is put instead displayed at validation summary.

2) How can I turn on popup validation?

By default popup is turned off. Validation messages are displayed where the validator tags are placed. If the popup is 
turned on via the script generator component, the validation summary is displayed in a popup window.

3) I have my own validation functions, how can I plug them?

Custom validator is an extension point for this job, it takes a function name and parameters as a comma seperated string.

4) Can I use resource bundles and what are the default keys that can be used in a message bundle?

Yes, you can via the f:loadBundle tag. Also here are the built-in keys
				
CV_REQUIRED_FIELD_VALIDATOR_ERROR = Some Text
CV_COMPARE_VALIDATOR_ERROR = Some Text
CV_RANGE_VALIDATOR_ERROR = Some Text
CV_REGULAR_EXPRESSION_VALIDATOR_ERROR = Some Text
CV_LENGTH_VALIDATOR_ERROR = Some Text

5) Is there a sample web application?

Yes, at jsf-comp downloads section.

6) Is it possible to change the look of the validation messages?

Yes, this is what style attribute for, you can supply your own style class.

7) What is author doing now?

The author is currently working on client side validation features for extended validators in myfaces. These validators will
have enableClientScript attribute that will enable them to do validation at client site.

8) What is your favorite team?

F.C. Barcelona

Author

Cagatay Civici

You can reach me via cagataycivici at gmail dot com . Also you can check my blog at JRoller .

Components

Development

jsf-comp@sf.net

sf.net

Introduction

Dependencies

Installation

classpath

taglib

return validate();

Prefix Mapping

Validators in Detail

Required Field Validator

Range Validator

Compare Validator

Regular Expression Validator

Length Validator Validator

Integer Only Validator

Custom Validator

Validation Summary

Script Generator

Internalization and Error Messages

F.A.Q. and MORE INFO

Author

Cagatay Civici