## 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: $Id: TBaseValidator.php 2418 2008-04-08 14:48:48Z tof $
- author: Qiang Xue <qiang.xue@gmail.com>

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

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

Direct descendents

Class | Description
--- | ---
TCaptchaValidator | TCaptchaValidator class
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)
TValidatorClientSide createClientSide ()
boolean evaluateIsValid ()
string getClientClassName ()
array getClientScriptOptions ()
TValidatorClientSide getClientSide ()
string getControlCssClass ()
string getControlToValidate ()
TValidatorDisplayStyle 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 (mixed $param)
void onUnload (mixed $param)
void onValidate ()
void onValidationError ()
void onValidationSuccess ()
void registerClientScriptValidator ()
void renderClientControlScript (THtmlWriter $writer)
void renderContents (THtmlWriter $writer)
void setControlCssClass (string $value)
void setControlToValidate (string $value)
void setDisplay (TValidatorDisplayStyle $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 102)

Constructor.

This method sets the foreground color to red.

- access: public

TBaseValidator __construct ()

Redefinition of:

TControl::__construct()
  Constructor.

Redefined in descendants as:

- TActiveCustomValidator::__construct() : Creates a new callback control, sets the adapter to TActiveControlAdapter. If you override this class, be sure to set the adapter appropriately by, for example, by calling this constructor.

addAttributesToRender (line 136)

Adds attributes to renderer. Calls parent implementation and renders the client control scripts.

- access: protected

void addAttributesToRender (THtmlWriter $writer)

- THtmlWriter $writer: the renderer

Redefinition of:

TLabel::addAttributesToRender()
  Adds attributes to renderer.

Redefined in descendants as:

- TActiveCustomValidator::addAttributesToRender() : Ensure that the ID attribute is rendered and registers the javascript code for initializing the active control.

createClientSide (line 221)

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

TValidatorClientSide createClientSide ()
evaluateIsValid (line 536)

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:

- TCaptchaValidator::evaluateIsValid() : This method overrides the parent's implementation.
- 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.

getClientClassName (line 297)

Gets the name of the javascript class responsible for performing validation for this control.

This method overrides the parent implementation.

- return: the javascript class name
- access: protected
- abstract:

string getClientClassName ()

Redefined in descendants as:

- TCaptchaValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TCompareValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TCustomValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TActiveCustomValidator::getClientClassName()
- TDataTypeValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TListControlValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TRangeValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TRegularExpressionValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TEmailAddressValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.
- TRequiredFieldValidator::getClientClassName() : Gets the name of the javascript class responsible for performing validation for this control.

getClientScriptOptions (line 153)

Returns an array of javascript validator options.

- return: javascript validator options.
- access: protected

array getClientScriptOptions ()

Redefined in descendants as:

- TCaptchaValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TCompareValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TCustomValidator::getClientScriptOptions() : Returns an array of javascript validator options.
- TActiveCustomValidator::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 211)

Gets the TValidatorClientSide 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>OnValidationSuccess</tt> -- raised after client-side validation is completed

and is successfull, overrides default validator error messages updates.

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

TValidatorClientSide getClientSide ()

Redefined in descendants as:

- TActiveCustomValidator::getClientSide()

getControlCssClass (line 518)

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

string getControlCssClass ()
getControlToValidate (line 373)

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

string getControlToValidate ()
getDisplay (line 324)

- return: the style of displaying the error message. Defaults to TValidatorDisplayStyle::Fixed.
- access: public

TValidatorDisplayStyle getDisplay ()

Redefinition of:

TWebControl::getDisplay()

getEnableClientScript (line 340)

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

boolean getEnableClientScript ()
getErrorMessage (line 356)

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

string getErrorMessage ()
getFocusElementID (line 410)

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 392)

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

boolean getFocusOnError ()
getIsValid (line 445)

- return: whether the validation succeeds
- access: public

boolean getIsValid ()
getValidationGroup (line 429)

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

string getValidationGroup ()
getValidationTarget (line 464)

- 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 478)

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 112)

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 252)

Override parent implementation to update the control CSS Class before

the validated control is rendered

- access: public

void onPreRender (mixed $param)

Redefinition of:

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

onUnload (line 123)

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.

onValidate (line 560)

This event is raised right before the validator starts to perform validation.

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.

- access: public

void onValidate ()
onValidationError (line 549)

This event is raised when the validator fails in validation.

- access: public

void onValidationError ()
onValidationSuccess (line 541)

This event is raised when the validator succeeds in validation.

- access: public

void onValidationSuccess ()
registerClientScriptValidator (line 281)

Registers the individual validator client-side javascript code.

- access: protected

void registerClientScriptValidator ()

Redefined in descendants as:

- TCustomValidator::registerClientScriptValidator() : Only register the client-side validator if setClientValidationFunction is set.

renderClientControlScript (line 232)

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 renderClientControlScript (THtmlWriter $writer)

- THtmlWriter $writer: the renderer

renderContents (line 569)

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 526)

- 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 384)

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 332)

- access: public

void setDisplay (TValidatorDisplayStyle $value)

- TValidatorDisplayStyle $value: the style of displaying the error message

Redefinition of:

TWebControl::setDisplay()

setEnableClientScript (line 348)

- access: public

void setEnableClientScript (boolean $value)

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

setEnabled (line 313)

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 365)

Sets the text for the error message.

- access: public

void setErrorMessage (string $value)

- string $value: the error message

Redefined in descendants as:

- TActiveCustomValidator::setErrorMessage() : Sets the text for the error message. Updates client-side erorr message.

setFocusElementID (line 421)

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 400)

- access: public

void setFocusOnError (boolean $value)

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

setForControl (line 304)

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 454)

Sets the value indicating whether the validation succeeds

- access: public

void setIsValid (boolean $value)

- boolean $value: whether the validation succeeds

setValidationGroup (line 437)

- access: public

void setValidationGroup (string $value)

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

updateControlCssClass (line 263)

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 491)

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::getData()
> TLabel::getForControl()
> TLabel::getTagName()
> TLabel::getText()
> TLabel::render()
> TLabel::renderContents()
> TLabel::setData()
> TLabel::setForControl()
> TLabel::setText()

Inherited From TWebControl

> TWebControl::addAttributesToRender()
> TWebControl::clearStyle()
> TWebControl::copyBaseAttributes()
> TWebControl::createStyle()
> TWebControl::getAccessKey()
> TWebControl::getBackColor()
> TWebControl::getBorderColor()
> TWebControl::getBorderStyle()
> TWebControl::getBorderWidth()
> TWebControl::getCssClass()
> TWebControl::getDisplay()
> 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::setDisplay()
> TWebControl::setForeColor()
> TWebControl::setHeight()
> TWebControl::setStyle()
> TWebControl::setTabIndex()
> TWebControl::setToolTip()
> TWebControl::setWidth()

Inherited From TControl

> TControl::__construct()
> TControl::addedControl()
> TControl::addParsedObject()
> TControl::addToPostDataLoader()
> TControl::applyStyleSheetSkin()
> TControl::autoBindProperty()
> TControl::autoDataBindProperties()
> TControl::bindProperty()
> TControl::broadcastEvent()
> TControl::bubbleEvent()
> TControl::clearChildState()
> TControl::clearControlState()
> TControl::clearNamingContainer()
> TControl::clearViewState()
> TControl::convertUniqueIdToClientId()
> TControl::createChildControls()
> TControl::createControlCollection()
> 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::getCustomData()
> TControl::getEnabled()
> TControl::getEnableTheming()
> TControl::getEnableViewState()
> TControl::getHasAdapter()
> TControl::getHasAttributes()
> TControl::getHasChildInitialized()
> TControl::getHasControls()
> TControl::getHasInitialized()
> TControl::getHasLoaded()
> TControl::getHasLoadedPostData()
> TControl::getHasPreRendered()
> 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::setCustomData()
> TControl::setEnabled()
> TControl::setEnableTheming()
> TControl::setEnableViewState()
> TControl::setID()
> TControl::setPage()
> TControl::setSkinID()
> TControl::setTemplateControl()
> TControl::setViewState()
> TControl::setVisible()
> TControl::trackViewState()
> 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::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> 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

> TControl::AUTOMATIC_ID_PREFIX
> TControl::CLIENT_ID_SEPARATOR
> TControl::CS_CHILD_INITIALIZED
> TControl::CS_CONSTRUCTED
> TControl::CS_INITIALIZED
> TControl::CS_LOADED
> TControl::CS_PRERENDERED
> TControl::CS_STATE_LOADED
> TControl::ID_FORMAT
> TControl::ID_SEPARATOR
> TControl::IS_CHILD_CREATED
> TControl::IS_CREATING_CHILD
> TControl::IS_DISABLE_THEMING
> TControl::IS_DISABLE_VIEWSTATE
> TControl::IS_ID_SET
> TControl::IS_SKIN_APPLIED
> TControl::IS_STYLESHEET_APPLIED
> TControl::RF_ADAPTER
> TControl::RF_AUTO_BINDINGS
> TControl::RF_CHILD_STATE
> TControl::RF_CONTROLS
> TControl::RF_CONTROLSTATE
> TControl::RF_DATA_BINDINGS
> TControl::RF_EVENTS
> TControl::RF_NAMED_CONTROLS
> TControl::RF_NAMED_CONTROLS_ID
> TControl::RF_NAMED_OBJECTS
> TControl::RF_SKIN_ID

Documentation generated on Mon, 21 Apr 2008 11:31:19 -0400 by phpDocumentor 1.3.0RC4