Added documentation to validator controls.

8 files changed, 214 insertions, 194 deletions

diff --git a/framework/Exceptions/messages.txt b/framework/Exceptions/messages.txt
index 8c3cd3cb..f3d741cb 100644
--- a/framework/Exceptions/messages.txt
+++ b/framework/Exceptions/messages.txt
@@ -177,3 +177,9 @@ filelogroute_maxlogfiles_invalid		= TFileLogRoute.MaxLogFiles must be greater th
 emaillogroute_sentfrom_required			= TEmailLogRoute.SentFrom cannot be empty.

 

 repeatinfo_repeatcolumns_invalid		= TRepeatInfo.RepeatColumns must be no less than 0.

+

+basevalidator_associatedcontrolid_unsupported = TBaseValidator.AssociatedControlID is not supported.

+basevalidator_controltovalidate_invalid = TBaseValidator.ControlToValidate is empty or contains an invalid control ID path.

+basevalidator_validatable_required		= TBaseValidator.ControlToValidate must point to a control implementing IValidatable interface.

+

+comparevalidator_controltocompare_invalid = TCompareValidator.ControlToCompare contains an invalid control ID path.
\ No newline at end of file
diff --git a/framework/Web/UI/WebControls/TBaseValidator.php b/framework/Web/UI/WebControls/TBaseValidator.php
index 9c4dd1be..0f8167b5 100644
--- a/framework/Web/UI/WebControls/TBaseValidator.php
+++ b/framework/Web/UI/WebControls/TBaseValidator.php
@@ -15,70 +15,50 @@
  *
  * TBaseValidator serves as the base class for validator controls.
  *
- * Validation is performed when a button control, such a TButton, a TLinkButton
- * or a TImageButton is clicked and the <b>CausesValidation</b> of these controls is true.
- * You can also manually perform validation by using the validate() method of the TPage class.
+ * 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 <b>CausesValidation</b> 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 server.
- * TValidation controls also have complete client-side implementation that allow
- * DHTML supported browsers to perform validation on the client via Javascript.
+ * 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.
+ * the round-trip of information necessary for server-side validation.
  *
- * You can use multiple validator controls to validate an individual input control,
- * each responsible for validating 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.
+ * 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 <b>ErrorMessage</b>
- * property is displayed in the validation control. If the <b>Text</b> property is set
- * it will be displayed instead, however. If both <b>ErrorMessage</b> and <b>Text</b>
- * are empty, the body content of the validator will be displayed.
+ * 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 place a <b>TValidationSummary</b> control on the page to display error messages
- * from the validators together. In this case, only the <b>ErrorMessage</b> property of the
- * validators will be displayed in the TValidationSummary control.
+ * 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.
  *
- * Note, the <b>IsValid</b> property of the current TPage instance will be automatically
- * updated by the validation process which occurs after <b>OnLoad</b> of TPage and
- * before the postback events. Therefore, if you use the <b>IsValid</b>
- * property in the <b>OnLoad</b> event of TPage, you must first explicitly call
- * the validate() method of TPage. As an alternative, you can place your code
- * in the postback event handler, such as <b>OnClick</b> or <b>OnCommand</b>,
- * instead of <b>OnLoad</b> event.
+ * 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, to use validators derived from this control, you have to
- * copy the file "<framework>/js/prado_validator.js" to the "js" directory
- * which should be under the directory containing the entry script file.
+ * 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.
  *
- * <b>Notes to Inheritors</b>  When you inherit from the TBaseValidator class,
- * you must override the method {@link evaluateIsValid}.
- *
- * Namespace: System.Web.UI.WebControls
- *
- * Properties
- * - <b>EnableClientScript</b>, boolean, default=true, kept in viewstate
- *   <br>Gets or sets a value indicating whether client-side validation is enabled.
- * - <b>Display</b>, string, default=Static, kept in viewstate
- *   <br>Gets or sets the display behavior (None, Static, Dynamic) of the error message in a validation control.
- * - <b>ControlToValidate</b>, string, kept in viewstate
- *   <br>Gets or sets the input control to validate. This property must be set to
- *   the ID path of an input control. The ID path is the dot-connected IDs of
- *   the controls reaching from the validator's parent control to the target control.
- *   For example, if HomePage is the parent of Validator and SideBar controls, and
- *   SideBar is the parent of UserName control, then the ID path for UserName
- *   would be "SideBar.UserName" if UserName is to be validated by Validator.
- * - <b>Text</b>, string, kept in viewstate
- *   <br>Gets or sets the text of TBaseValidator control.
- * - <b>ErrorMessage</b>, string, kept in viewstate
- *   <br>Gets or sets the text for the error message.
- * - <b>EncodeText</b>, boolean, default=true, kept in viewstate
- *   <br>Gets or sets the value indicating whether Text and ErrorMessage should be HTML-encoded when rendering.
- * - <b>IsValid</b>, boolean, default=true
- *   <br>Gets or sets a value that indicates whether the associated input control passes validation.
+ * <b>Notes to Inheritors</b>  When you inherit from TBaseValidator, you must
+ * override the method {@link evaluateIsValid}.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @version $Revision: $  $Date: $
@@ -88,18 +68,28 @@
 abstract class TBaseValidator extends TLabel implements IValidator
 {
 	/**
-	 * whether the validation succeeds
-	 * @var boolean
+	 * @var boolean whether the validation succeeds
 	 */
 	private $_isValid=true;
+	/**
+	 * @var boolean whether the validator has been registered with the page
+	 */
 	private $_registered=false;
 
+	/**
+	 * Constructor.
+	 * This method sets the foreground color to red.
+	 */
 	public function __construct()
 	{
 		parent::__construct();
 		$this->setForeColor('red');
 	}
 
+	/**
+	 * Registers the validator with page.
+	 * @param mixed event parameter
+	 */
 	protected function onInit($param)
 	{
 		parent::onInit($param);
@@ -107,6 +97,10 @@ abstract class TBaseValidator extends TLabel implements IValidator
 		$this->_registered=true;
 	}
 
+	/**
+	 * Unregisters the validator from page.
+	 * @param mixed event parameter
+	 */
 	protected function onUnload($param)
 	{
 		if($this->_registered && ($page=$this->getPage())!==null)
@@ -165,14 +159,14 @@ abstract class TBaseValidator extends TLabel implements IValidator
 			$scripts->registerEndScript($scriptKey, $js);
 		}
 		if($this->getEnableClientScript())
-			$this->renderClientScriptValidator();
+			$this->registerClientScriptValidator();
 		parent::onPreRender($param);
 	}
 
 	/**
-	 * Renders the individual validator client-side javascript code.
+	 * Registers the individual validator client-side javascript code.
 	 */
-	protected function renderClientScriptValidator()
+	protected function registerClientScriptValidator()
 	{
 		if($this->getEnabled(true) && $this->getEnableClientScript())
 		{
@@ -234,7 +228,6 @@ abstract class TBaseValidator extends TLabel implements IValidator
 	}
 
 	/**
-	 * Sets the value indicating whether client-side validation is enabled.
 	 * @param boolean whether client-side validation is enabled.
 	 */
 	public function setEnableClientScript($value)
@@ -247,8 +240,7 @@ abstract class TBaseValidator extends TLabel implements IValidator
 	 */
 	public function getErrorMessage()
 	{
-		return $this->getText();
-		//return $this->getViewState('ErrorMessage','');
+		return $this->getViewState('ErrorMessage','');
 	}
 
 	/**
@@ -257,8 +249,7 @@ abstract class TBaseValidator extends TLabel implements IValidator
 	 */
 	public function setErrorMessage($value)
 	{
-		$this->setText($value);
-		//$this->setViewState('ErrorMessage',$value,'');
+		$this->setViewState('ErrorMessage',$value,'');
 	}
 
 	/**
@@ -270,7 +261,9 @@ abstract class TBaseValidator extends TLabel implements IValidator
 	}
 
 	/**
-	 * Sets the ID path of the input control to validate
+	 * 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.
 	 * @param string the ID path
 	 */
 	public function setControlToValidate($value)
@@ -279,7 +272,7 @@ abstract class TBaseValidator extends TLabel implements IValidator
 	}
 
 	/**
-	 * @return boolean whether to set focus at the validating place if the validation fails. Defaults to true.
+	 * @return boolean whether to set focus at the validating place if the validation fails. Defaults to false.
 	 */
 	public function getFocusOnError()
 	{
@@ -348,14 +341,24 @@ abstract class TBaseValidator extends TLabel implements IValidator
 		$this->_isValid=TPropertyValue::ensureBoolean($value);
 	}
 
+	/**
+	 * @return TControl control to be validated. Null if no control is found.
+	 * @throw TConfigurationException if {@link getControlToValidate ControlToValidate} is empty or does not point to a valid control
+	 */
 	protected function getValidationTarget()
 	{
-		if(($id=$this->getControlToValidate())!=='')
-			return $this->findControl($id);
+		if(($id=$this->getControlToValidate())!=='' && ($control=$this->findControl($id))!==null)
+			return $control;
 		else
-			return null;
+			throw new TConfigurationException('basevalidator_controltovalidate_invalid');
 	}
 
+	/**
+	 * Retrieves the property value of the control being validated.
+	 * @param TControl control being validated
+	 * @return string property value to be validated
+	 * @throws TInvalidDataTypeException if the control to be validated does not implement {@link IValidatable}.
+	 */
 	protected function getValidationValue($control)
 	{
 		if($control instanceof IValidatable)
@@ -390,5 +393,19 @@ abstract class TBaseValidator extends TLabel implements IValidator
 	 * @return boolean whether the validation succeeds
 	 */
 	abstract protected function evaluateIsValid();
+
+	/**
+	 * Renders the validator control.
+	 * @param THtmlWriter writer for the rendering purpose
+	 */
+	protected function renderContents($writer)
+	{
+		if(($text=$this->getText())!=='')
+			$writer->write($text);
+		else if(($text=$this->getErrorMessage())!=='')
+			$writer->write($text);
+		else
+			parent::renderContents($writer);
+	}
 }
 ?>
\ No newline at end of file
diff --git a/framework/Web/UI/WebControls/TCompareValidator.php b/framework/Web/UI/WebControls/TCompareValidator.php
index cfc2e876..02eddfd4 100644
--- a/framework/Web/UI/WebControls/TCompareValidator.php
+++ b/framework/Web/UI/WebControls/TCompareValidator.php
@@ -18,31 +18,32 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
 /**

  * TCompareValidator class

  *

- * TCompareValidator compares the value entered by the user into an input component with the value

- * entered into another input component or a constant value. To specify the input component to

- * validate, set the <b>ControlToValidate</b> property to the ID of the input component.

+ * TCompareValidator compares the value entered by the user into an input

+ * control with the value entered into another input control or a constant value.

+ * To compare the associated input control with another input control,

+ * set the {@link setControlToCompare ControlToCompare} property to the ID path

+ * of the control to compare with. To compare the associated input control with

+ * a constant value, specify the constant value to compare with by setting the

+ * {@link setValueToCompare ValueToCompare} property.

  *

- * To compare the associated input component with another input component,

- * set the <b>ControlToCompare</b> property to the ID of the component to compare with.

- *

- * To compare the associated input component with a constant value,

- * specify the constant value to compare with by setting the <b>ValueToCompare</b> property.

- *

- * The <b>ValueType</b> property is used to specify the data type of both comparison values.

- * Both values are automatically converted to this data type before the comparison operation

- * is performed. The following value types are supported:

+ * The {@link setValueType ValueType} property is used to specify the data type

+ * of both comparison values. Both values are automatically converted to this data

+ * type before the comparison operation is performed. The following value types are supported:

  * - <b>Integer</b> A 32-bit signed integer data type.

  * - <b>Double</b> A double-precision floating point number data type.

  * - <b>Currency</b> A decimal data type that can contain currency symbols.

  * - <b>Date</b> A date data type. The format follows the GNU date syntax.

  * - <b>String</b> A string data type.

  *

- * Use the <b>Operator</b> property to specify the type of comparison to perform,

- * such as Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, DataTypeCheck.

- * If you set the <b>Operator</b> property to DataTypeCheck, the TCompareValidator component

- * will ignore the <b>ControlToCompare</b> and <b>ValueToCompare</b> properties and simply

- * indicates whether the value entered into the input component can be converted to the data type

- * specified by the <b>ValueType</b> property.

+ * Use the {@link setOperator Operator} property to specify the type of comparison

+ * to perform. Valid operators include Equal, NotEqual, GreaterThan, GreaterThanEqual,

+ * LessThan, LessThanEqual, and DataTypeCheck.

+ *

+ * Note, if you set {@link setOperator Operator} to DataTypeCheck, the validator

+ * will ignore the {@link setControlToCompare ControlToCompare} and

+ * {@link setValueToCompare ValueToCompare} properties and simply

+ * indicates whether the value entered into the input control can be converted

+ * to the data type specified by the {@link setValueType ValueType} property.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -145,9 +146,7 @@ class TCompareValidator extends TBaseValidator
 	 */

 	public function evaluateIsValid()

 	{

-		if(($control=$this->getValidationTarget())===null)

-			throw new TInvalidDataValueException('comparevalidator_controltovalidate_invalid');

-		if(($value=$this->getValidationValue($control))==='')

+		if(($value=$this->getValidationValue($this->getValidationTarget()))==='')

 			return true;

 

 		if($this->getOperator()==='DataTypeCheck')

@@ -245,6 +244,10 @@ class TCompareValidator extends TBaseValidator
 		return array($value1, $value2);

 	}

 

+	/**

+	 * Returns an array of javascript validator options.

+	 * @return array javascript validator options.

+	 */

 	protected function getClientScriptOptions()

 	{

 		$options = parent::getClientScriptOptions();

diff --git a/framework/Web/UI/WebControls/TCustomValidator.php b/framework/Web/UI/WebControls/TCustomValidator.php
index 8c42b580..546f015b 100644
--- a/framework/Web/UI/WebControls/TCustomValidator.php
+++ b/framework/Web/UI/WebControls/TCustomValidator.php
@@ -22,11 +22,12 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
  * server-side or client-side or both) on an input component.

  *

  * To create a server-side validation function, provide a handler for

- * the <b>OnServerValidate</b> event that performs the validation.

- * The data string of the input component to validate can be accessed

- * by the <b>value</b> property of the event parameter which is of type

- * <b>TServerValidateEventParameter</b>. The result of the validation

- * should be stored in the <b>isValid</b> property of the event parameter.

+ * the {@link onServerValidate ServerValidate} event that performs the validation.

+ * The data string of the input control to validate can be accessed

+ * by {@link TServerValidateEventParameter::getValue Value} of the event parameter.

+ * The result of the validation should be stored in the

+ * {@link TServerValidateEventParameter::getIsValid IsValid} property of the event

+ * parameter.

  *

  * To create a client-side validation function, add the client-side

  * validation javascript function to the page template.

@@ -42,8 +43,9 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
  * }

  * --></script>

  * </code>

- * Use the <b>ClientValidationFunction</b> property to specify the name of

- * the client-side validation script function associated with the TCustomValidator.

+ * Use the {@link setClientValidationFunction ClientValidationFunction} property

+ * to specify the name of the client-side validation script function associated

+ * with the TCustomValidator.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -76,24 +78,16 @@ class TCustomValidator extends TBaseValidator
 	 */

 	public function evaluateIsValid()

 	{

-		if(($id=$this->getControlToValidate())!=='')

-		{

-			if(($control=$this->findControl($id))!==null)

-				$value=$this->getValidationValue($control);

-			else

-				throw new TInvalidDataValueException('customvalidator_controltovalidate_invalid');

-			return $this->onServerValidate($value);

-		}

-		else

-			throw new TInvalidDataValueException('customvalidator_controltovalidate_required');

+		$value=$this->getValidationValue($this->getValidationTarget());

+		return $this->onServerValidate($value);

 	}

 

 	/**

 	 * This method is invoked when the server side validation happens.

-	 * It will raise the <b>OnServerValidate</b> event.

+	 * It will raise the <b>ServerValidate</b> event.

 	 * The method also allows derived classes to handle the event without attaching a delegate.

 	 * <b>Note</b> The derived classes should call parent implementation

-	 * to ensure the <b>OnServerValidate</b> event is raised.

+	 * to ensure the <b>ServerValidate</b> event is raised.

 	 * @param string the value to be validated

 	 * @return boolean whether the value is valid

 	 */

@@ -142,22 +136,36 @@ class TServerValidateEventParameter extends TEventParameter
 	 */

 	private $_isValid=true;

 

+	/**

+	 * Constructor.

+	 * @param string property value to be validated

+	 * @param boolean whether the value is valid

+	 */

 	public function __construct($value,$isValid)

 	{

 		$this->_value=$value;

 		$this->setIsValid($isValid);

 	}

 

+	/**

+	 * @return string value to be validated

+	 */

 	public function getValue()

 	{

 		return $this->_value;

 	}

 

+	/**

+	 * @return boolean whether the value is valid

+	 */

 	public function getIsValid()

 	{

 		return $this->_isValid;

 	}

 

+	/**

+	 * @param boolean whether the value is valid

+	 */

 	public function setIsValid($value)

 	{

 		$this->_isValid=TPropertyValue::ensureBoolean($value);

diff --git a/framework/Web/UI/WebControls/TEmailAddressValidator.php b/framework/Web/UI/WebControls/TEmailAddressValidator.php
index 48516c44..b6ceff90 100644
--- a/framework/Web/UI/WebControls/TEmailAddressValidator.php
+++ b/framework/Web/UI/WebControls/TEmailAddressValidator.php
@@ -20,7 +20,7 @@ Prado::using('System.Web.UI.WebControls.TRegularExpressionValidator');
  *

  * TEmailAddressValidator validates whether the value of an associated

  * input component is a valid email address. It will check MX record

- * if checkdnsrr() is implemented.

+ * if checkdnsrr() is available in the installed PHP.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -29,14 +29,24 @@ Prado::using('System.Web.UI.WebControls.TRegularExpressionValidator');
  */

 class TEmailAddressValidator extends TRegularExpressionValidator

 {

+	/**

+	 * Regular expression used to validate the email address

+	 */

 	const EMAIL_REGEXP="\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*";

 

+	/**

+	 * @return string the regular expression that determines the pattern used to validate a field.

+	 */

 	public function getRegularExpression()

 	{

 		$regex=parent::getRegularExpression();

 		return $regex===''?self::EMAIL_REGEXP:$regex;

 	}

 

+	/**

+	 * Returns an array of javascript validator options.

+	 * @return array javascript validator options.

+	 */

 	public function evaluateIsValid()

 	{

 		$valid=parent::evaluateIsValid();

diff --git a/framework/Web/UI/WebControls/TRegularExpressionValidator.php b/framework/Web/UI/WebControls/TRegularExpressionValidator.php
index 9fe0f778..f20c2d16 100644
--- a/framework/Web/UI/WebControls/TRegularExpressionValidator.php
+++ b/framework/Web/UI/WebControls/TRegularExpressionValidator.php
@@ -21,7 +21,7 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
  * TRegularExpressionValidator validates whether the value of an associated

  * input component matches the pattern specified by a regular expression.

  *

- * You can specify the regular expression by setting the <b>RegularExpression</b>

+ * You can specify the regular expression by setting the {@link setRegularExpression RegularExpression}

  * property. Some commonly used regular expressions include:

  * <pre>

  * French Phone Number: (0( \d|\d ))?\d\d \d\d(\d \d| \d\d )\d\d

@@ -40,6 +40,9 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
  * U.S. Social Security Number: \d{3}-\d{2}-\d{4}

  * </pre>

  *

+ * Note, the validation succeeds if the associated input control contains empty input.

+ * Use a {@link TRequiredFieldValidator} to ensure the input is not empty.

+ *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

  * @package System.Web.UI.WebControls

@@ -56,8 +59,7 @@ class TRegularExpressionValidator extends TBaseValidator
 	}

 

 	/**

-	 * Sets the regular expression that determines the pattern used to validate a field.

-	 * @param string the regular expression

+	 * @param string the regular expression that determines the pattern used to validate a field.

 	 */

 	public function setRegularExpression($value)

 	{

@@ -73,19 +75,18 @@ class TRegularExpressionValidator extends TBaseValidator
 	 */

 	public function evaluateIsValid()

 	{

-		if(($control=$this->getValidationTarget())!==null)

-		{

-			if(($value=$this->getValidationValue($control))==='')

-				return true;

-			if(($expression=$this->getRegularExpression())!=='')

-				return preg_match("/^$expression\$/",$value);

-			else

-				return true;

-		}

+		if(($value=$this->getValidationValue($this->getValidationTarget()))==='')

+			return true;

+		if(($expression=$this->getRegularExpression())!=='')

+			return preg_match("/^$expression\$/",$value);

 		else

-			throw new TInvalidDataValueException('regularexpressionvalidator_controltovalidate_invalid');

+			return true;

 	}

 

+	/**

+	 * Returns an array of javascript validator options.

+	 * @return array javascript validator options.

+	 */

 	protected function getClientScriptOptions()

 	{

 		$options = parent::getClientScriptOptions();

diff --git a/framework/Web/UI/WebControls/TRequiredFieldValidator.php b/framework/Web/UI/WebControls/TRequiredFieldValidator.php
index c937abf8..2d1dd612 100644
--- a/framework/Web/UI/WebControls/TRequiredFieldValidator.php
+++ b/framework/Web/UI/WebControls/TRequiredFieldValidator.php
@@ -18,6 +18,9 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
 /**

  * TRequiredFieldValidator class

  *

+ * TRequiredFieldValidator makes the associated input control a required field.

+ * The input control fails validation if its value does not change from

+ * the {@link setInitialValue InitialValue} property upon losing focus.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -26,27 +29,42 @@ Prado::using('System.Web.UI.WebControls.TBaseValidator');
  */

 class TRequiredFieldValidator extends TBaseValidator

 {

+	/**

+	 * @return string the initial value of the associated input control. Defaults to empty string.

+	 * If the associated input control does not change from this initial value

+	 * upon postback, the validation fails.

+	 */

 	public function getInitialValue()

 	{

 		$this->getViewState('InitialValue','');

 	}

 

+	/**

+	 * @param string the initial value of the associated input control.

+	 * If the associated input control does not change from this initial value

+	 * upon postback, the validation fails.

+	 */

 	public function setInitialValue($value)

 	{

 		$this->setViewState('InitialValue',TPropertyValue::ensureString($value),'');

 	}

 

+	/**

+	 * This method overrides the parent's implementation.

+	 * The validation succeeds if the input component changes its data

+	 * from the {@link getInitialValue InitialValue} or the input control is not given.

+	 * @return boolean whether the validation succeeds

+	 */

 	protected function evaluateIsValid()

 	{

-		if(($control=$this->getValidationTarget())!==null)

-		{

-			$value=$this->getValidationValue($control);

-			return trim($value)!==trim($this->getInitialValue());

-		}

-		else

-			throw new TInvalidDataValueException('requiredfieldvalidator_controltovalidate_invalid');

+		$value=$this->getValidationValue($this->getValidationTarget());

+		return trim($value)!==trim($this->getInitialValue());

 	}

 

+	/**

+	 * Returns an array of javascript validator options.

+	 * @return array javascript validator options.

+	 */

 	protected function getClientScriptOptions()

 	{

 		$options = parent::getClientScriptOptions();

diff --git a/framework/Web/UI/WebControls/TValidationSummary.php b/framework/Web/UI/WebControls/TValidationSummary.php
index 0ac7584a..056c8f3e 100644
--- a/framework/Web/UI/WebControls/TValidationSummary.php
+++ b/framework/Web/UI/WebControls/TValidationSummary.php
@@ -13,29 +13,21 @@
 /**

  * TValidationSummary class

  *

- * TValidationSummary displays a summary of all validation errors inline on a Web page,

- * in a message box, or both. The summary can be displayed as a list, as a bulleted list,

- * or as a single paragraph based on the <b>DisplayMode</b> property.

- * The summary can be displayed on the Web page and in a message box by setting

- * the <b>ShowSummary</b> and <b>ShowMessageBox</b> properties, respectively.

+ * TValidationSummary displays a summary of validation errors inline on a Web page,

+ * in a message box, or both. By default, a validation summary will collect

+ * {@link TBaseValidator::getErrorMessage ErrorMessage} of all failed validators

+ * on the page. If {@link getValidationGroup ValidationGroup} is not

+ * empty, only those validators who belong to the group will show their error messages

+ * in the summary.

  *

- * Namespace: System.Web.UI.WebControls

+ * The summary can be displayed as a list, as a bulleted list, or as a single

+ * paragraph based on the {@link setDisplayMode DisplayMode} property.

+ * The messages shown can be prefixed with {@link setHeaderText HeaderText}.

  *

- * Properties

- * - <b>DisplayMode</b>, string, default=BulletList, kept in viewstate

- *   <br>Gets or sets the display mode (BulletList, List, SingleParagraph) of the validation summary.

- * - <b>HeaderText</b>, string, kept in viewstate

- *   <br>Gets or sets the header text displayed at the top of the summary.

- * - <b>EnableClientScript</b>, boolean, default=true, kept in viewstate

- *   <br>Gets or sets a value indicating whether the TValidationSummary component

- *   updates itself using client-side script.

- * - <b>ShowMessageBox</b>, boolean, default=false, kept in viewstate

- *   <br>Gets or sets a value indicating whether the validation summary is displayed in a message box.

- *   If <b>EnableClientScript</b> is <b>false</b>, this property has no effect.

- * - <b>ShowSummary</b>, boolean, default=true, kept in viewstate

- *   <br>Gets or sets a value indicating whether the validation summary is displayed inline.

- * - <b>Group</b>, string, kept in viewstate

- *   <br>Gets or sets the validation group ID.

+ * The summary can be displayed on the Web page and in a message box by setting

+ * the {@link setShowSummary ShowSummary} and {@link setShowMessageBox ShowMessageBox}

+ * properties, respectively. Note, the latter is only effective when

+ * {@link setEnableClientScript EnableClientScript} is true.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -44,20 +36,6 @@
  */

 class TValidationSummary extends TWebControl

 {

-

-	protected static $currentGroup;

-

-	public static function setCurrentGroup($group)

-	{

-		self::$currentGroup = $group;

-	}

-

-	public static function getCurrentGroup()

-	{

-		return self::$currentGroup;

-	}

-

-

 	/**

 	 * @return string the header text displayed at the top of the summary

 	 */

@@ -190,29 +168,6 @@ class TValidationSummary extends TWebControl
 		$this->setViewState('ValidationGroup',$value,'');

 	}

 

-	/**

-	 * Get a list of validators considering the validation groups.

-	 * @return array list of validators.

-	 */

-	protected function getValidators()

-	{

-		$groupID = $this->getGroup();

-		if(empty($groupID)) return $this->getPage()->getValidators();

-

-		$parent = $this->getParent();

-		$group = $parent->findObject($groupID);

-

-		$validators = array();

-

-		foreach($group->getMembers() as $member)

-		{

-			$control = $parent->findObject($member);

-			if(!is_null($control))

-				$validators[] = $control;

-		}

-		return $validators;

-	}

-

 	protected function addAttributesToRender($writer)

 	{

 		$writer->addAttribute('id',$this->getClientID());

@@ -341,11 +296,13 @@ class TValidationSummary extends TWebControl
 		$header=$this->getHeaderText();

 		$messages=$this->getErrorMessages();

 		$content = $header;

-		$show = count($messages) > 0;

-		if($show) $content .= "<ul>\n";

-		foreach($messages as $message)

-			$content.= '<li>'.$message."</li>\n";

-		if($show) $content .= "</ul>\n";

+		if(count($messages)>0)

+		{

+			$content .= "<ul>\n";

+			foreach($messages as $message)

+				$content.= '<li>'.$message."</li>\n";

+			$content .= "</ul>\n";

+		}

 		$writer->write($content);

 	}

 }