PHP Class Prado\Web\UI\WebControls\TBaseValidator

TBaseValidator serves as the base class for validator controls. Validation is performed when a postback control, such as a TButton, a TLinkButton or a TTextBox (under AutoPostBack mode) is submitting the page and its CausesValidation property is true. You can also manually perform validation by calling {@link TPage::validate()}. The input control to be validated is specified by {@link setControlToValidate ControlToValidate}. Validator controls always validate the associated input control on the serve side. In addition, if {@link getEnableClientScript EnableClientScript} is true, validation will also be performed on the client-side using javascript. Client-side validation will validate user input before it is sent to the server. The form data will not be submitted if any error is detected. This avoids the round-trip of information necessary for server-side validation. You can use multiple validator controls to validate a single input control, each responsible for validating against a different criteria. For example, on a user registration form, you may want to make sure the user enters a value in the username text box, and the input must consist of only word characters. You can use a {@link TRequiredFieldValidator} to ensure the input of username and a {@link TRegularExpressionValidator} to ensure the proper input. If an input control fails validation, the text specified by the {@link setErrorMessage ErrorMessage} property is displayed in the validation control. However, if the {@link setText Text} property is set, it will be displayed instead. If both {@link setErrorMessage ErrorMessage} and {@link setText Text} are empty, the body content of the validator will be displayed. Error display is controlled by {@link setDisplay Display} property. You can also customized the client-side behaviour by adding javascript code to the subproperties of the {@link getClientSide ClientSide} property. See quickstart documentation for further details. You can also place a {@link TValidationSummary} control on a page to display error messages from the validators together. In this case, only the {@link setErrorMessage ErrorMessage} property of the validators will be displayed in the {@link TValidationSummary} control. Validators can be partitioned into validation groups by setting their {@link setValidationGroup ValidationGroup} property. If the control causing the validation also sets its ValidationGroup property, only those validators having the same ValidationGroup value will do input validation. Note, the {@link TPage::getIsValid IsValid} property of the current {@link TPage} instance will be automatically updated by the validation process which occurs after {@link TPage::onLoad onLoad} of {@link TPage} and before the postback events. Therefore, if you use the {@link TPage::getIsValid()} property in the {@link TPage::onLoad()} method, you must first explicitly call the {@link TPage::validate()} method. Notes to Inheritors When you inherit from TBaseValidator, you must override the method {@link evaluateIsValid}.
Since: 3.0
Author: Qiang Xue ([email protected])
Inheritance: extends TLabel, implements Prado\Web\UI\IValidator
Show file Open project: pradosoft/prado Class Usage Examples

Public Methods

Method Description
__construct ( ) Constructor.
getClientSide ( ) : TValidatorClientSide Gets the TValidatorClientSide that allows modification of the client- side validator events.
getControlCssClass ( ) : string
getControlToValidate ( ) : string
getDisplay ( ) : TValidatorDisplayStyle
getEnableClientScript ( ) : boolean
getErrorMessage ( ) : string
getFocusElementID ( ) : string Gets the ID of the HTML element that will receive focus if validation fails and {@link getFocusOnError FocusOnError} is true.
getFocusOnError ( ) : boolean
getIsValid ( ) : boolean
getValidationGroup ( ) : string
getValidationTarget ( ) : TControl
onInit ( $param ) Registers the validator with page.
onPreRender ( $param ) Override parent implementation to update the control CSS Class before the validated control is rendered
onUnload ( $param ) Unregisters the validator from page.
onValidate ( ) This event is raised right before the validator starts to perform validation.
onValidationError ( ) This event is raised when the validator fails in validation.
onValidationSuccess ( ) This event is raised when the validator succeeds in validation.
renderClientControlScript ( $writer ) Renders the javascript code to the end script.
renderContents ( $writer ) Renders the validator control.
setControlCssClass ( $value )
setControlToValidate ( $value ) Sets the ID path of the input control to validate.
setDisplay ( $value )
setEnableClientScript ( $value )
setEnabled ( $value ) This method overrides parent's implementation by setting {@link setIsValid IsValid} to true if disabled.
setErrorMessage ( $value ) Sets the text for the error message.
setFocusElementID ( $value ) Sets the ID of the HTML element that will receive focus if validation fails and {@link getFocusOnError FocusOnError} is true.
setFocusOnError ( $value )
setForControl ( $value ) This method overrides the parent implementation to forbid setting ForControl.
setIsValid ( $value ) Sets the value indicating whether the validation succeeds
setValidationGroup ( $value )
validate ( ) : boolean Validates the specified control.

Protected Methods

Method Description
addAttributesToRender ( $writer ) Adds attributes to renderer. Calls parent implementation and renders the client control scripts.
createClientSide ( ) : TValidatorClientSide
evaluateIsValid ( ) : boolean This is the major method for validation.
getClientClassName ( ) : string Gets the name of the javascript class responsible for performing validation for this control.
getClientScriptOptions ( ) : array Returns an array of javascript validator options.
getValidationValue ( $control ) : string Retrieves the property value of the control being validated.
registerClientScriptValidator ( ) Registers the individual validator client-side javascript code.
updateControlCssClass ( ) : boolean Update the ControlToValidate component's css class depending if the ControlCssClass property is set, and whether this is valid.

Private Methods

Method Description
getClientControlClass ( $control ) : string Gets the Control type for client-side validation. If new cases exists in TBaseValidator::$_clientClass, be sure to update the corresponding "Javascript/validation3.js" file as well.

Method Details

__construct() public method

This method sets the foreground color to red.
public __construct ( )

addAttributesToRender() protected method

Adds attributes to renderer. Calls parent implementation and renders the client control scripts.
protected addAttributesToRender ( $writer )

createClientSide() protected method

protected createClientSide ( ) : TValidatorClientSide
return TValidatorClientSide javascript validator event options.

evaluateIsValid() abstract protected method

Derived classes should implement this method to provide customized validation.
abstract protected evaluateIsValid ( ) : boolean
return boolean whether the validation succeeds

getClientClassName() abstract protected method

This method overrides the parent implementation.
abstract protected getClientClassName ( ) : string
return string the javascript class name

getClientScriptOptions() protected method

Returns an array of javascript validator options.
protected getClientScriptOptions ( ) : array
return array javascript validator options.

getClientSide() public method

The client-side validator supports the following events. # OnValidate -- raised before client-side validation is executed. # OnValidationSuccess -- raised after client-side validation is completed and is successfull, overrides default validator error messages updates. # OnValidationError -- raised after client-side validation is completed and failed, overrides default validator error message updates. You can attach custom javascript code to each of these events
public getClientSide ( ) : TValidatorClientSide
return TValidatorClientSide javascript validator event options.

getControlCssClass() public method

public getControlCssClass ( ) : string
return string the css class that is applied to the control being validated in case the validation fails

getControlToValidate() public method

public getControlToValidate ( ) : string
return string the ID path of the input control to validate

getDisplay() public method

public getDisplay ( ) : TValidatorDisplayStyle
return TValidatorDisplayStyle the style of displaying the error message. Defaults to TValidatorDisplayStyle::Fixed.

getEnableClientScript() public method

public getEnableClientScript ( ) : boolean
return boolean whether client-side validation is enabled.

getErrorMessage() public method

public getErrorMessage ( ) : string
return string the text for the error message.

getFocusElementID() public method

Defaults to the client ID of the {@link getControlToValidate ControlToValidate}.
public getFocusElementID ( ) : string
return string the ID of the HTML element to receive focus

getFocusOnError() public method

public getFocusOnError ( ) : boolean
return boolean whether to set focus at the validating place if the validation fails. Defaults to false.

getIsValid() public method

public getIsValid ( ) : boolean
return boolean whether the validation succeeds

getValidationGroup() public method

public getValidationGroup ( ) : string
return string the group which this validator belongs to

getValidationTarget() public method

public getValidationTarget ( ) : TControl
return TControl control to be validated. Null if no control is found.

getValidationValue() protected method

Retrieves the property value of the control being validated.
protected getValidationValue ( $control ) : string
return string property value to be validated

onInit() public method

Registers the validator with page.
public onInit ( $param )

onPreRender() public method

Override parent implementation to update the control CSS Class before the validated control is rendered
public onPreRender ( $param )

onUnload() public method

Unregisters the validator from page.
public onUnload ( $param )

onValidate() public method

You may use this event to change the behavior of validation. For example, you may disable the validator if certain condition is satisfied. Note, the event will NOT be raised if the validator is invisible.
public onValidate ( )

onValidationError() public method

This event is raised when the validator fails in validation.
public onValidationError ( )

onValidationSuccess() public method

This event is raised when the validator succeeds in validation.
public onValidationSuccess ( )

registerClientScriptValidator() protected method

Registers the individual validator client-side javascript code.
protected registerClientScriptValidator ( )

renderClientControlScript() public method

If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.
public renderClientControlScript ( $writer )

renderContents() public method

Renders the validator control.
public renderContents ( $writer )

setControlCssClass() public method

public setControlCssClass ( $value )

setControlToValidate() public method

The ID path is the dot-connected IDs of the controls reaching from the validator's naming container to the target control.
public setControlToValidate ( $value )

setDisplay() public method

public setDisplay ( $value )

setEnableClientScript() public method

public setEnableClientScript ( $value )

setEnabled() public method

This method overrides parent's implementation by setting {@link setIsValid IsValid} to true if disabled.
public setEnabled ( $value )

setErrorMessage() public method

Sets the text for the error message.
public setErrorMessage ( $value )

setFocusElementID() public method

Sets the ID of the HTML element that will receive focus if validation fails and {@link getFocusOnError FocusOnError} is true.
public setFocusElementID ( $value )

setFocusOnError() public method

public setFocusOnError ( $value )

setForControl() public method

This method overrides the parent implementation to forbid setting ForControl.
public setForControl ( $value )

setIsValid() public method

Sets the value indicating whether the validation succeeds
public setIsValid ( $value )

setValidationGroup() public method

public setValidationGroup ( $value )

updateControlCssClass() protected method

Update the ControlToValidate component's css class depending if the ControlCssClass property is set, and whether this is valid.
protected updateControlCssClass ( ) : boolean
return boolean true if change, false otherwise.

validate() public method

Do not override this method. Override {@link evaluateIsValid} instead.
public validate ( ) : boolean
return boolean whether the validation succeeds