org.vaadin.csvalidation
Class CSValidator

java.lang.Object
  extended by com.vaadin.server.AbstractClientConnector
      extended by com.vaadin.server.AbstractExtension
          extended by org.vaadin.csvalidation.CSValidator
All Implemented Interfaces:
com.vaadin.event.MethodEventSource, com.vaadin.server.ClientConnector, com.vaadin.server.Extension, com.vaadin.shared.Connector, java.io.Serializable

public class CSValidator
extends com.vaadin.server.AbstractExtension

Component extension for validating TextField, PasswordField, and TextArea components on the client-side. The extension supports both regular expression and JavaScript based validation on the client side.

The validation is executed at each key press. If invalid input is allowed (the default), the invalid CSS style is added when the value is invalid. If the value is correct, but incomplete, the partial style is set. If the value is valid, the valid style is set.

If typing invalid input is not allowed (setPreventInvalidTyping() is set to true), and the resulting value would be invalid, the text field value remains unchanged.

To enable validation with a regular expression, set it with setRegExp(). To enable validation with a JavaScript program, set it with setJavaScript(). You can use both a regular expression and JavaScript validation simultaneously; the regular expression is validated first so you can use it to block unwanted input altogether by having setPreventInvalidTyping(true).

Otherwise, the functionality of the component is identical to the standard TextField.

Author:
Marko Grönroos
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector
com.vaadin.server.ClientConnector.AttachEvent, com.vaadin.server.ClientConnector.AttachListener, com.vaadin.server.ClientConnector.ConnectorErrorEvent, com.vaadin.server.ClientConnector.DetachEvent, com.vaadin.server.ClientConnector.DetachListener
 
Constructor Summary
CSValidator()
           
 
Method Summary
 void extend(com.vaadin.ui.AbstractTextField tf)
          Extends a text field to enable client-side validation.
 org.vaadin.csvalidation.widgetset.client.csvalidator.CSValidatorState getState()
           
 void setErrorMessage(java.lang.String msg)
          Sets the error message for invalid regular expression validation.
 void setInputPadding(java.lang.String padding)
          Sets an input padding template for fixed-length input with regular expression validation.
 void setJavaScript(java.lang.String javascript)
          Sets the JavaScript code for validating the value.
 void setPreventInvalidTyping(boolean preventInvalid)
          Sets whether the field should prevent invalid input.
 void setRegExp(java.lang.String regexp)
          Sets the regular expression for validating the input.
 void setRegExp(java.lang.String regexp, java.lang.String padding)
          Sets the regular expression and a valid padding input.
 void setValidateEmpty(boolean validateEmpty)
          Deprecated. renamed to setValidateInitialEmpty(boolean)
 void setValidateEmptyValue(boolean validateEmpty)
          Sets whether the field is validated also when it is empty.
 void setValidateInitialEmpty(boolean validateInitialEmpty)
          Sets whether the field is validated immediately after creation.
 
Methods inherited from class com.vaadin.server.AbstractExtension
extend, getSupportedParentType, remove, setParent
 
Methods inherited from class com.vaadin.server.AbstractClientConnector
addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, attach, beforeClientResponse, createState, detach, encodeState, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getParent, getResource, getRpcManager, getRpcProxy, getSession, getState, getStateType, getUI, handleConnectorRequest, hasListeners, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.vaadin.server.ClientConnector
addAttachListener, addDetachListener, attach, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getParent, getRpcManager, getStateType, getUI, handleConnectorRequest, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler
 
Methods inherited from interface com.vaadin.shared.Connector
getConnectorId
 

Constructor Detail

CSValidator

public CSValidator()
Method Detail

extend

public void extend(com.vaadin.ui.AbstractTextField tf)
Extends a text field to enable client-side validation.

The behavior of the created text field is identical to that of the regular TextField component. To enable validation with a regular expression, set it with setRegExp(). To enable validation with a JavaScript program, set it with setJavaScript().

Parameters:
tf - the text field or area to extend

getState

public org.vaadin.csvalidation.widgetset.client.csvalidator.CSValidatorState getState()
Overrides:
getState in class com.vaadin.server.AbstractClientConnector

setRegExp

public void setRegExp(java.lang.String regexp)
Sets the regular expression for validating the input.

You should also set the error message with setErrorMessage() to provide feedback about the problem.

You can choose to not allow invalid input at all by setting setPreventInvalidTyping(true). If you do not allow invalid input, you need to provide an example value with setInputPadding() to allow determining partially correct values. This is usually possible only for fields with fixed lengths.

Please refer to JavaScript documentation for the syntax of the regular expressions. If you use the same expression to validate the value on the server-side, notice that the Java regular expressions have slightly different syntax.

 // The Finnish Social Security Number
 final TextField ssn = new TextField("SSN");
 String ssn_regexp = "[0-9]{6}[+-A][0-9]{3}[0-9a-zA-Z]";
 
 // The client-side validation
 CSValidator validator = new CSValidator();
 validator.setRegExp(ssn_regexp);
 validator.extend(ssn);
 
 // The server-side validation
 ssn.addValidator(new RegexpValidator(ssn_regexp, "Invalid SSN"));
 ssn.setRequired(true);
 ssn.setRequiredError("SSN is required");
 
 form.addField("ssn", ssn);
 

Parameters:
regexp - the regular expression to match

setErrorMessage

public void setErrorMessage(java.lang.String msg)
Sets the error message for invalid regular expression validation. The error message is not used for JavaScript validation, where the error message is returned by the script. The error message is meaningless if setPreventInvalidTyping(true) is set, as in that case it is not possible to type invalid input at all.

Parameters:
msg -
See Also:
setRegExp(String), setPreventInvalidTyping(boolean)

setRegExp

public void setRegExp(java.lang.String regexp,
                      java.lang.String padding)
Sets the regular expression and a valid padding input.

The padding must be a valid string or otherwise the value will never match. See #setInputPadding() for a more detailed description of the padding.

The component will automatically be set as setPreventInvalidTyping(true), as the padding is meaningless in the non-preventive mode.

Example:

 // The Finnish Social Security Number
 final TextField ssn = new TextField("SSN");
 String ssn_regexp = "[0-9]{6}[+-A][0-9]{3}[0-9a-zA-Z]";
 
 // The client-side validation
 CSValidator validator = new CSValidator();
 validator.setRegExp(ssn_regexp, "000000-000A");
 validator.extend(ssn);
 
 // The server-side validation
 ssn.addValidator(new RegexpValidator(ssn_regexp, "Invalid SSN"));
 
 form.addField("ssn", ssn);
 

Parameters:
regexp - the regular expression to be used for validating the input
padding - padding string which should be valid, see setExample()
See Also:
setRegExp(String), setInputPadding(String)

setJavaScript

public void setJavaScript(java.lang.String javascript)
Sets the JavaScript code for validating the value.

The program gets a value variable, which contains the current value of the field as a string.

The program must return null if validation is successful, or otherwise an error description. If it returns the special string "partial", it is interpreted as a partial match, so that the value is unfinished. Returning the result must be done with the value of the final executed statement, not with the return keyword!

Example:

     if (value == "hello")
         null; // success
     else
         "Must greet!"; // failure
 

The partial keyword can be followed by a message, which is displayed in the message element with style v-validatedtextfield-partialmessage. If the return string begins with valid keyword, the text following it is displayed in the message element with style v-validatedtextfield-validmessage.

In error state, the message element has style v-validatedtextfield-validmessage and the text field an additional invalid style. A valid text field has valid style and partial a partial style.

Parameters:
javascript - a JavaScript program

setInputPadding

public void setInputPadding(java.lang.String padding)
Sets an input padding template for fixed-length input with regular expression validation.

The padding is a value that matches the validation condition. It must also match if the beginning, to any point, is replaced with user input so that the combined content is a valid value. For example, if the regular expression is [0-9][0-9][0-9][0-9][0-9][0-9], a valid padding would be 000000. Now, if the user inputs 12 as the first letters, the padded value would be 120000, which is also valid.

The padding is usually meaningful if the input value is expected to have a fixed length, but can be used in some cases as well, for example when input is homogeneous and has a minimum length.

Parameters:
padding - the example value

setPreventInvalidTyping

public void setPreventInvalidTyping(boolean preventInvalid)
Sets whether the field should prevent invalid input.

If invalid values are not allowed (parameter is true), the field prevents typing them. This can cause problems if the regular expression does not match if the input is partial. For example, if expression is "..." and you try to type the first "a". In such case, you also need to set the inputPadding property, for example to "xxx". Giving the padding does, however, help only with fixed-width patterns.

If invalid values are allowed (parameter is false), the field does not prevent writing an invalid value, but sets the invalid CSS style class. If the value is valid, the valid style class is set. If the value is partially valid, the partial style is set.

The preventInvalid is automatically set to true when the inputPadding property is set to a non-null value, and to false when the inputPadding is null.

Parameters:
preventInvalid - true if invalid values are be prevented, otherwise false

setValidateEmptyValue

public void setValidateEmptyValue(boolean validateEmpty)
Sets whether the field is validated also when it is empty.

Used currently only for regular expression validation, not for JavaScript.

When this setting is false, the text fields are validated only if they have non-zero length. If true, merely visiting a field will validate it.

Default value is true.

Parameters:
validateEmpty - should empty text fields be validated
Since:
0.4

setValidateEmpty

@Deprecated
public void setValidateEmpty(boolean validateEmpty)
Deprecated. renamed to setValidateInitialEmpty(boolean)

Sets whether the field is validated immediately after creation.

Parameters:
validateEmpty -

setValidateInitialEmpty

public void setValidateInitialEmpty(boolean validateInitialEmpty)
Sets whether the field is validated immediately after creation.

Normally, when this setting is false, the text fields are validated only after the user types something in the input box. In some cases it can be desirable to run the validation immediately when a new field is created, even if it is empty. For example, if you use the validation to display a character counter, you want to have it displayed even when the text field is empty in the beginning.

Regardless of this setting, new text fields are validated automatically if they are not empty.

Parameters:
validateInitialEmpty - should new empty text fields be validated