## Class TBaseValidator

Description

Implements interfaces:

- IValidator

TBaseValidator class

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 TPage::validate(). The input control to be validated is specified by ControlToValidate.

Validator controls always validate the associated input control on the serve side. In addition, if 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 TRequiredFieldValidator to ensure the input of username and a TRegularExpressionValidator to ensure the proper input.

If an input control fails validation, the text specified by the ErrorMessage property is displayed in the validation control. However, if the Text property is set, it will be displayed instead. If both ErrorMessage and Text are empty, the body content of the validator will be displayed. Error display is controlled by Display property.

You can also customized the client-side behaviour by adding javascript code to the subproperties of the ClientSide property. See quickstart documentation for further details.

You can also place a TValidationSummary control on a page to display error messages from the validators together. In this case, only the ErrorMessage property of the validators will be displayed in the TValidationSummary control.

Validators can be partitioned into validation groups by setting their 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 TPage::getIsValid property of the current TPage instance will be automatically updated by the validation process which occurs after TPage::onLoad of TPage and before the postback events. Therefore, if you use the TPage::getIsValid() property in the TPage::onLoad() method, you must first explicitly call the TPage::validate() method.

Notes to Inheritors When you inherit from TBaseValidator, you must override the method evaluateIsValid.

- abstract:
- since: 3.0
- version: $Revision: $ $Date: $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TBaseValidator.php (line 72)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TLabel
                   |
                   --TBaseValidator

Direct descendents

Class | Description
--- | ---
TCompareValidator | TCompareValidator class
TCustomValidator | TCustomValidator class
TDataTypeValidator | TDataTypeValidator class
TListControlValidator | TListControlValidator class.
TRangeValidator | TRangeValidator class
TRegularExpressionValidator | TRegularExpressionValidator class
TRequiredFieldValidator | TRequiredFieldValidator class

Method Summary
TBaseValidator __construct ()
void addAttributesToRender (THtmlWriter $writer)
TValidatorClientScript createClientScript ()
boolean evaluateIsValid ()
array getClientScriptOptions ()
TValidatorClientScript getClientSide ()
string getControlCssClass ()
string getControlToValidate ()
string getDisplay ()
boolean getEnableClientScript ()
string getErrorMessage ()
string getFocusElementID ()
boolean getFocusOnError ()
boolean getIsValid ()
string getValidationGroup ()
TControl getValidationTarget ()
string getValidationValue (TControl $control)
void onInit (mixed $param)
void onPreRender (TEventParameter $param)
void onUnload (mixed $param)
void registerClientScriptValidator ()
void renderContents (THtmlWriter $writer)
void setControlCssClass (string $value)
void setControlToValidate (string $value)
void setDisplay (string $value)
void setEnableClientScript (boolean $value)
void setEnabled (boolean $value)
void setErrorMessage (string $value)
void setFocusElementID (string $value)
void setFocusOnError (boolean $value)
void setForControl (string $value)
void setIsValid (boolean $value)
void setValidationGroup (string $value)
boolean updateControlCssClass ()
boolean validate ()
Methods
Constructor __construct (line 97)

Constructor.

This method sets the foreground color to red.

- access: public

TBaseValidator __construct ()

Redefinition of:

TControl::__construct()
  Constructor.

addAttributesToRender (line 130)

Adds attributes to renderer.

- access: protected

void addAttributesToRender (THtmlWriter $writer)

- THtmlWriter $writer: the renderer

Redefinition of:

TLabel::addAttributesToRender()
  Adds attributes to renderer.

createClientScript (line 211)

- return: javascript validator event options.
- access: protected

TValidatorClientScript createClientScript ()
evaluateIsValid (line 499)

This is the major method for validation.

Derived classes should implement this method to provide customized validation.

- return: whether the validation succeeds
- access: protected
- abstract:

boolean evaluateIsValid ()

Redefined in descendants as:

- TCompareValidator::evaluateIsValid() : This method overrides the parent's implementation.
- TCustomValidator::evaluateIsValid() : This method overrides the parent's implementation.
- TDataTypeValidator::evaluateIsValid() : This method overrides the parent's implementation.
- TListControlValidator::evaluateIsValid() : This method overrides the parent's implementation.
- TRangeValidator::evaluateIsValid() : This method overrides the parent's implementation.
- TRegularExpressionValidator::evaluateIsValid() : This method overrides the parent's implementation.
- TEmailAddressValidator::evaluateIsValid() : Returns an array of javascript validator options.
- TRequiredFieldValidator::evaluateIsValid() : This method overrides the parent's implementation.

getClientScriptOptions (line 146)

Returns an array of javascript validator options.

- return: javascript validator options.
- access: protected

array getClientScriptOptions ()

Redefined in descendants as:

- TCompareValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TCustomValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TDataTypeValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TListControlValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TRangeValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TRegularExpressionValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TRequiredFieldValidator::getClientScriptOptions() : Returns an array of javascript validator options.

getClientSide (line 201)

Gets the TValidatorClientScript that allows modification of the client- side validator events.

The client-side validator supports the following events.

- <tt>OnValidate</tt> -- raised before client-side validation is

executed.

- <tt>OnSuccess</tt> -- raised after client-side validation is completed

and is successfull, overrides default validator error messages updates.

- <tt>OnError</tt> -- 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

- return: javascript validator event options.
- access: public

TValidatorClientScript getClientSide ()
getControlCssClass (line 481)

- return: the css class that is applied to the control being validated in case the validation fails
- access: public

string getControlCssClass ()
getControlToValidate (line 351)

- return: the ID path of the input control to validate
- access: public

string getControlToValidate ()
getDisplay (line 301)

- return: the display behavior (None, Static, Dynamic) of the error message in a validation control. Defaults to Static.
- access: public

string getDisplay ()
getEnableClientScript (line 318)

- return: whether client-side validation is enabled.
- access: public

boolean getEnableClientScript ()
getErrorMessage (line 334)

- return: the text for the error message.
- access: public

string getErrorMessage ()
getFocusElementID (line 388)

Gets the ID of the HTML element that will receive focus if validation fails and getFocusOnError is true.

Defaults to the client ID of the ControlToValidate.

- return: the ID of the HTML element to receive focus
- access: public

string getFocusElementID ()
getFocusOnError (line 370)

- return: whether to set focus at the validating place if the validation fails. Defaults to false.
- access: public

boolean getFocusOnError ()
getIsValid (line 423)

- return: whether the validation succeeds
- access: public

boolean getIsValid ()
getValidationGroup (line 407)

- return: the group which this validator belongs to
- access: public

string getValidationGroup ()
getValidationTarget (line 442)

- return: control to be validated. Null if no control is found.
- access: protected
- throws: TConfigurationException if ControlToValidate is empty or does not point to a valid control

TControl getValidationTarget ()
getValidationValue (line 456)

Retrieves the property value of the control being validated.

- return: property value to be validated
- access: protected
- throws: TInvalidDataTypeException if the control to be validated does not implement IValidatable.

string getValidationValue (TControl $control)

- TControl $control: control being validated

onInit (line 107)

Registers the validator with page.

- access: public

void onInit (mixed $param)

- mixed $param: event parameter

Redefinition of:

TControl::onInit()
  This method is invoked when the control enters 'OnInit' stage.

onPreRender (line 222)

Renders the javascript code to the end script.

If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

- access: public

void onPreRender (TEventParameter $param)

- TEventParameter $param: event parameter to be passed to the event handlers

Redefinition of:

TControl::onPreRender()
  This method is invoked when the control enters 'OnPreRender' stage.

onUnload (line 118)

Unregisters the validator from page.

- access: public

void onUnload (mixed $param)

- mixed $param: event parameter

Redefinition of:

TControl::onUnload()
  This method is invoked when the control enters 'OnUnload' stage.

registerClientScriptValidator (line 263)

Registers the individual validator client-side javascript code.

- access: protected

void registerClientScriptValidator ()
renderContents (line 505)

Renders the validator control.

- access: public

void renderContents (THtmlWriter $writer)

- THtmlWriter $writer: writer for the rendering purpose

Redefinition of:

TLabel::renderContents()
  Renders the body content of the label.

setControlCssClass (line 489)

- access: public

void setControlCssClass (string $value)

- string $value: the css class that is applied to the control being validated in case the validation fails

setControlToValidate (line 362)

Sets the ID path of the input control to validate.

The ID path is the dot-connected IDs of the controls reaching from the validator's naming container to the target control.

- access: public

void setControlToValidate (string $value)

- string $value: the ID path

setDisplay (line 310)

Sets the display behavior (None, Static, Dynamic) of the error message in a validation control.

- access: public

void setDisplay (string $value)

- string $value: the display behavior (None, Static, Dynamic)

setEnableClientScript (line 326)

- access: public

void setEnableClientScript (boolean $value)

- boolean $value: whether client-side validation is enabled.

setEnabled (line 290)

This method overrides parent's implementation by setting setIsValid to true if disabled.

- access: public

void setEnabled (boolean $value)

- boolean $value: whether the validator is enabled.

Redefinition of:

TControl::setEnabled()

setErrorMessage (line 343)

Sets the text for the error message.

- access: public

void setErrorMessage (string $value)

- string $value: the error message

setFocusElementID (line 399)

Sets the ID of the HTML element that will receive focus if validation fails and getFocusOnError is true.

- access: public

void setFocusElementID (string $value)

- string $value: the ID of the HTML element to receive focus

setFocusOnError (line 378)

- access: public

void setFocusOnError (boolean $value)

- boolean $value: whether to set focus at the validating place if the validation fails

setForControl (line 281)

This method overrides the parent implementation to forbid setting ForControl.

- access: public
- throws: TNotSupportedException whenever this method is called

void setForControl (string $value)

- string $value: the associated control ID

Redefinition of:

TLabel::setForControl()
  Sets the ID of the control that the label is associated with.

setIsValid (line 432)

Sets the value indicating whether the validation succeeds

- access: public

void setIsValid (boolean $value)

- boolean $value: whether the validation succeeds

setValidationGroup (line 415)

- access: public

void setValidationGroup (string $value)

- string $value: the group which this validator belongs to

updateControlCssClass (line 245)

Update the ControlToValidate component's css class depending if the ControlCssClass property is set, and whether this is valid.

- return: true if change, false otherwise.
- access: protected

boolean updateControlCssClass ()
validate (line 469)

Validates the specified control.

Do not override this method. Override evaluateIsValid instead.

- return: whether the validation succeeds
- access: public

boolean validate ()

#### Inherited Methods

Inherited From TLabel

> TLabel::addAttributesToRender()
> TLabel::getForControl()
> TLabel::getTagName()
> TLabel::getText()
> TLabel::renderContents()
> TLabel::setForControl()
> TLabel::setText()

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> TWebControl::getFont()
> TWebControl::getForeColor()
> TWebControl::getHasStyle()
> TWebControl::getHeight()
> TWebControl::getStyle()
> TWebControl::getTabIndex()
> TWebControl::getTagName()
> TWebControl::getToolTip()
> TWebControl::getWidth()
> TWebControl::render()
> TWebControl::renderBeginTag()
> TWebControl::renderContents()
> TWebControl::renderEndTag()
> TWebControl::setAccessKey()
> TWebControl::setBackColor()
> TWebControl::setBorderColor()
> TWebControl::setBorderStyle()
> TWebControl::setBorderWidth()
> TWebControl::setCssClass()
> TWebControl::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::broadcastEventInternal()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::createChildControls()
> TControl::createControlCollection()
> TControl::createdOnTemplate()
> TControl::dataBind()
> TControl::dataBindChildren()
> TControl::dataBindProperties()
> TControl::ensureChildControls()
> TControl::findControl()
> TControl::findControlsByID()
> TControl::findControlsByType()
> TControl::focus()
> TControl::getAdapter()
> TControl::getAllowChildControls()
> TControl::getAttribute()
> TControl::getAttributes()
> TControl::getChildControlsCreated()
> TControl::getClientID()
> TControl::getControls()
> TControl::getControlStage()
> TControl::getControlState()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasControls()
> TControl::getID()
> TControl::getNamingContainer()
> TControl::getPage()
> TControl::getParent()
> TControl::getRegisteredObject()
> TControl::getSkinID()
> TControl::getSourceTemplateControl()
> TControl::getTemplateControl()
> TControl::getUniqueID()
> TControl::getViewState()
> TControl::getVisible()
> TControl::hasAttribute()
> TControl::initRecursive()
> TControl::isDescendentOf()
> TControl::isObjectRegistered()
> TControl::loadRecursive()
> TControl::loadState()
> TControl::loadStateRecursive()
> TControl::onDataBinding()
> TControl::onInit()
> TControl::onLoad()
> TControl::onPreRender()
> TControl::onUnload()
> TControl::preRenderRecursive()
> TControl::raiseBubbleEvent()
> TControl::registerObject()
> TControl::removeAttribute()
> TControl::removedControl()
> TControl::render()
> TControl::renderChildren()
> TControl::renderControl()
> TControl::saveState()
> TControl::saveStateRecursive()
> TControl::setAdapter()
> TControl::setAttribute()
> TControl::setChildControlsCreated()
> TControl::setControlStage()
> TControl::setControlState()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::traverseChildControls()
> TControl::unbindProperty()
> TControl::unloadRecursive()
> TControl::unregisterObject()
> TControl::__get()

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Class Constants

#### Inherited Constants

Inherited from TControl

Documentation generated on Sun, 04 Jun 2006 18:58:38 -0400 by phpDocumentor 1.3.0RC4