Class TBaseValidator

Description

Implements interfaces:

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.

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 ()
boolean evaluateIsValid ()
string getControlCssClass ()
string getDisplay ()
string getErrorMessage ()
string getFocusElementID ()
boolean getFocusOnError ()
boolean getIsValid ()
string getValidationGroup ()
string getValidationValue (TControl $control)
void onInit (mixed $param)
void onPreRender (TEventParameter $param)
void onUnload (mixed $param)
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 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)

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:
getClientScriptOptions (line 146)

Returns an array of javascript validator options.

  • return: javascript validator options.
  • access: protected
array getClientScriptOptions ()

Redefined in descendants as:
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