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.

  • 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 ()
boolean evaluateIsValid ()
string getClientClassName ()
string getControlCssClass ()
string getErrorMessage ()
string getFocusElementID ()
boolean getFocusOnError ()
boolean getIsValid ()
string getValidationGroup ()
string getValidationValue (TControl $control)
void onInit (mixed $param)
void onPreRender (mixed $param)
void onUnload (mixed $param)
void onValidate ()
void renderContents (THtmlWriter $writer)
void setControlCssClass (string $value)
void setControlToValidate (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 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)

Redefinition of:
TLabel::addAttributesToRender()
Adds attributes to renderer.

Redefined in descendants as:
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:
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:
getClientScriptOptions (line 153)

Returns an array of javascript validator options.

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

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

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:
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

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