Subversion-Projekte lars-tiefland.prado

<?php

/**

 * TBaseValidator class file

 *

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

 * @link http://www.pradosoft.com/

 * @copyright Copyright © 2005-2008 PradoSoft

 * @license http://www.pradosoft.com/license/

 * @version $Id: TBaseValidator.php 2551 2008-10-30 17:07:05Z carlgmathisen $

 * @package System.Web.UI.WebControls

 */

/**

 * Using TLabel class

 */

Prado::using('System.Web.UI.WebControls.TLabel');

/**

 * 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 <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 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.

 *

 * 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 {@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 customized the client-side behaviour by adding javascript

 * code to the subproperties of the {@link getClientSide ClientSide}

 * property. See quickstart documentation for further details.

 *

 * 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.

 *

 * 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, 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 TBaseValidator, you must

 * override the method {@link evaluateIsValid}.

 *

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

 * @version $Id: TBaseValidator.php 2551 2008-10-30 17:07:05Z carlgmathisen $

 * @package System.Web.UI.WebControls

 * @since 3.0

 */

abstract class TBaseValidator extends TLabel implements IValidator

{

	/**

	 * @var boolean whether the validation succeeds

	 */

	private $_isValid=true;

	/**

	 * @var boolean whether the validator has been registered with the page

	 */

	private $_registered=false;

	/**

	 * @var TValidatorClientSide validator client-script options.

	 */

	private $_clientSide;

	/**

	 * Controls for which the client-side validation3.js file needs to handle

	 * them specially.

	 * @var array list of control class names

	 */

	private static $_clientClass = array('THtmlArea', 'TDatePicker', 'TListBox', 'TCheckBoxList');

	/**

	 * 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

	 */

	public function onInit($param)

	{

		parent::onInit($param);

		$this->getPage()->getValidators()->add($this);

		$this->_registered=true;

	}

	/**

	 * Unregisters the validator from page.

	 * @param mixed event parameter

	 */

	public function onUnload($param)

	{

		if($this->_registered && ($page=$this->getPage())!==null)

			$page->getValidators()->remove($this);

		$this->_registered=false;

		parent::onUnload($param);

	}

	/**

	 * Adds attributes to renderer. Calls parent implementation and renders the

	 * client control scripts.

	 * @param THtmlWriter the renderer

	 */

	protected function addAttributesToRender($writer)

	{

		$display=$this->getDisplay();

		$visible=$this->getEnabled(true) && !$this->getIsValid();

		if($display===TValidatorDisplayStyle::None || (!$visible && $display===TValidatorDisplayStyle::Dynamic))

			$writer->addStyleAttribute('display','none');

		else if(!$visible)

			$writer->addStyleAttribute('visibility','hidden');

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

		parent::addAttributesToRender($writer);

		$this->renderClientControlScript($writer);

	}

	/**

	 * Returns an array of javascript validator options.

	 * @return array javascript validator options.

	 */

	protected function getClientScriptOptions()

	{

		$control = $this->getValidationTarget();

		$options['ID'] = $this->getClientID();

		$options['FormID'] = $this->getPage()->getForm()->getClientID();

		$options['Display'] = $this->getDisplay();

		$options['ErrorMessage'] = $this->getErrorMessage();

		if($this->getFocusOnError())

		{

			$options['FocusOnError'] = $this->getFocusOnError();

			$options['FocusElementID'] = $this->getFocusElementID();

		}

		$options['ValidationGroup'] = $this->getValidationGroup();

		$options['ControlToValidate'] = $control->getClientID();

		$options['ControlCssClass'] = $this->getControlCssClass();

		$options['ControlType'] = $this->getClientControlClass($control);

		//get date format from date picker target control

		if($control instanceof TDatePicker)

			$options['DateFormat'] = $control->getDateFormat();

		$options = array_merge($options,$this->getClientSide()->getOptions()->toArray());

		return $options;

	}

	/**

	 * Gets the Control type for client-side validation. If new cases exists in

	 * TBaseValidator::$_clientClass, be sure to update the corresponding

	 * "Javascript/validation3.js" file as well.

	 * @param TControl control to validate.

	 * @return string control type for client-side validation.

	 */

	private function getClientControlClass($control)

	{

		foreach(self::$_clientClass as $type)

			if($control instanceof $type)

				return $type;

		return get_class($control);

	}

	/**

	 * 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 TValidatorClientSide javascript validator event options.

	 */

	public function getClientSide()

	{

		if(is_null($this->_clientSide))

			$this->_clientSide = $this->createClientSide();

		return $this->_clientSide;

	}

	/**

	 * @return TValidatorClientSide javascript validator event options.

	 */

	protected function createClientSide()

	{

		return new TValidatorClientSide;

	}

	/**

	 * 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.

	 * @param THtmlWriter the renderer

	 */

	public function renderClientControlScript($writer)

	{

		$scripts = $this->getPage()->getClientScript();

		$formID=$this->getPage()->getForm()->getClientID();

		$scriptKey = "TBaseValidator:$formID";

		if($this->getEnableClientScript() && !$scripts->isEndScriptRegistered($scriptKey))

		{

			$manager['FormID'] = $formID;

			$options = TJavaScript::encode($manager);

			$scripts->registerPradoScript('validator');

			$scripts->registerEndScript($scriptKey, "new Prado.ValidationManager({$options});");

		}

		if($this->getEnableClientScript() & $this->getEnabled(true))

			$this->registerClientScriptValidator();

	}

	/**

	 * Override parent implementation to update the control CSS Class before

	 * the validated control is rendered

	 */

	public function onPreRender ($param)

	{

		parent::onPreRender($param);

		$this->updateControlCssClass();

	}

	/**

	 * Update the ControlToValidate component's css class depending

	 * if the ControlCssClass property is set, and whether this is valid.

	 * @return boolean true if change, false otherwise.

	 */

	protected function updateControlCssClass()

	{

		if(($cssClass=$this->getControlCssClass())!=='')

		{

			$control=$this->getValidationTarget();

			if($control instanceof TWebControl)

			{

				$class = preg_replace ('/ '.preg_quote($cssClass).'/', '',$control->getCssClass());

				if(!$this->getIsValid())

				{

					$class .= ' '.$cssClass;

					$control->setCssClass($class);

				} elseif ($control->getIsValid())

					$control->setCssClass($class);

			}

		}

	}

	/**

	 * Registers the individual validator client-side javascript code.

	 */

	protected function registerClientScriptValidator()

	{

		$key = 'prado:'.$this->getClientID();

		if(!$this->getPage()->getClientScript()->isEndScriptRegistered($key))

		{

			$options = TJavaScript::encode($this->getClientScriptOptions());

			$script = 'new '.$this->getClientClassName().'('.$options.');';

			$this->getPage()->getClientScript()->registerEndScript($key, $script);

		}

	}

	/**

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

	 * This method overrides the parent implementation.

	 * @return string the javascript class name

	 */

	abstract protected function getClientClassName();

	/**

	 * This method overrides the parent implementation to forbid setting ForControl.

	 * @param string the associated control ID

	 * @throws TNotSupportedException whenever this method is called

	 */

	public function setForControl($value)

	{

		throw new TNotSupportedException('basevalidator_forcontrol_unsupported',get_class($this));

	}

	/**

	 * This method overrides parent's implementation by setting {@link setIsValid IsValid} to true if disabled.

	 * @param boolean whether the validator is enabled.

	 */

	public function setEnabled($value)

	{

		$value=TPropertyValue::ensureBoolean($value);

		parent::setEnabled($value);

		if(!$value)

			$this->_isValid=true;

	}

	/**

	 * @return TValidatorDisplayStyle the style of displaying the error message. Defaults to TValidatorDisplayStyle::Fixed.

	 */

	public function getDisplay()

	{

		return $this->getViewState('Display',TValidatorDisplayStyle::Fixed);

	}

	/**

	 * @param TValidatorDisplayStyle the style of displaying the error message

	 */

	public function setDisplay($value)

	{

		$this->setViewState('Display',TPropertyValue::ensureEnum($value,'TValidatorDisplayStyle'),TValidatorDisplayStyle::Fixed);

	}

	/**

	 * @return boolean whether client-side validation is enabled.

	 */

	public function getEnableClientScript()

	{

		return $this->getViewState('EnableClientScript',true);

	}

	/**

	 * @param boolean whether client-side validation is enabled.

	 */

	public function setEnableClientScript($value)

	{

		$this->setViewState('EnableClientScript',TPropertyValue::ensureBoolean($value),true);

	}

	/**

	 * @return string the text for the error message.

	 */

	public function getErrorMessage()

	{

		return $this->getViewState('ErrorMessage','');

	}

	/**

	 * Sets the text for the error message.

	 * @param string the error message

	 */

	public function setErrorMessage($value)

	{

		$this->setViewState('ErrorMessage',$value,'');

	}

	/**

	 * @return string the ID path of the input control to validate

	 */

	public function getControlToValidate()

	{

		return $this->getViewState('ControlToValidate','');

	}

	/**

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

	{

		$this->setViewState('ControlToValidate',$value,'');

	}

	/**

	 * @return boolean whether to set focus at the validating place if the validation fails. Defaults to false.

	 */

	public function getFocusOnError()

	{

		return $this->getViewState('FocusOnError',false);

	}

	/**

	 * @param boolean whether to set focus at the validating place if the validation fails

	 */

	public function setFocusOnError($value)

	{

		$this->setViewState('FocusOnError',TPropertyValue::ensureBoolean($value),false);

	}

	/**

	 * Gets the ID of the HTML element that will receive focus if validation fails and {@link getFocusOnError FocusOnError} is true.

	 * Defaults to the client ID of the {@link getControlToValidate ControlToValidate}.

	 * @return string the ID of the HTML element to receive focus

	 */

	public function getFocusElementID()

	{

		if(($id=$this->getViewState('FocusElementID',''))==='')

			$id=$this->getValidationTarget()->getClientID();

		return $id;

	}

	/**

	 * Sets the ID of the HTML element that will receive focus if validation fails and {@link getFocusOnError FocusOnError} is true.

	 * @param string the ID of the HTML element to receive focus

	 */

	public function setFocusElementID($value)

	{

		$this->setViewState('FocusElementID', $value, '');

	}

	/**

	 * @return string the group which this validator belongs to

	 */

	public function getValidationGroup()

	{

		return $this->getViewState('ValidationGroup','');

	}

	/**

	 * @param string the group which this validator belongs to

	 */

	public function setValidationGroup($value)

	{

		$this->setViewState('ValidationGroup',$value,'');

	}

	/**

	 * @return boolean whether the validation succeeds

	 */

	public function getIsValid()

	{

		return $this->_isValid;

	}

	/**

	 * Sets the value indicating whether the validation succeeds

	 * @param boolean whether the validation succeeds

	 */

	public function setIsValid($value)

	{

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

	}

	/**

	 * @return TControl control to be validated. Null if no control is found.

	 * @throws TConfigurationException if {@link getControlToValidate

	 * ControlToValidate} is empty or does not point to a valid control

	 */

	protected function getValidationTarget()

	{

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

			return $control;

		else

			throw new TConfigurationException('basevalidator_controltovalidate_invalid',get_class($this));

	}

	/**

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

			return $control->getValidationPropertyValue();

		else

			throw new TInvalidDataTypeException('basevalidator_validatable_required',get_class($this));

	}

	/**

	 * Validates the specified control.

	 * Do not override this method. Override {@link evaluateIsValid} instead.

	 * @return boolean whether the validation succeeds

	 */

	public function validate()

	{

		$this->setIsValid(true);

		$this->onValidate();

		if($this->getVisible(true) && $this->getEnabled(true))

		{

			// if the target is not a disabled web control

			if(($target=$this->getValidationTarget())!==null && !($target instanceof TWebControl && !$target->getEnabled(true)))

			{

				if($this->evaluateIsValid())

				{

					$this->setIsValid(true);

					$this->onValidationSuccess();

				}

				else

				{

					$target->setIsValid(false);

					$this->setIsValid(false);

					$this->onValidationError();

				}

			}

			else

			{

				$this->evaluateIsValid();

				$this->setIsValid(true);

				$this->onValidationSuccess();

			}

		}

		return $this->getIsValid();

	}

	/**

	 * @return string the css class that is applied to the control being validated in case the validation fails

	 */

	public function getControlCssClass()

	{

		return $this->getViewState('ControlCssClass','');

	}

	/**

	 * @param string the css class that is applied to the control being validated in case the validation fails

	 */

	public function setControlCssClass($value)

	{

		$this->setViewState('ControlCssClass',$value,'');

	}

	/**

	 * This is the major method for validation.

	 * Derived classes should implement this method to provide customized validation.

	 * @return boolean whether the validation succeeds

	 */

	abstract protected function evaluateIsValid();

	/**

	 * This event is raised when the validator succeeds in validation.

	 */

	public function onValidationSuccess()

	{

		$this->raiseEvent('OnValidationSuccess',$this,null);

	}

	/**

	 * This event is raised when the validator fails in validation.

	 */

	public function onValidationError()

	{

		$this->raiseEvent('OnValidationError',$this,null);

	}

	/**

	 * 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.

	 */

	public function onValidate()

	{

		$this->raiseEvent('OnValidate',$this,null);

	}

	/**

	 * Renders the validator control.

	 * @param THtmlWriter writer for the rendering purpose

	 */

	public function renderContents($writer)

	{

		if(($text=$this->getText())!=='')

			$writer->write($text);

		else if(($text=$this->getErrorMessage())!=='')

			$writer->write($text);

		else

			parent::renderContents($writer);

	}

}

/**

 * TValidatorClientSide class.

 *

 * Client-side validator events can be modified through the {@link

 * TBaseValidator::getClientSide ClientSide} property of a validator. The

 * subproperties of ClientSide are those of the TValidatorClientSide

 * properties. The client-side validator supports the following events.

 *

 * The <tt>OnValidate</tt> event is raise before the validator validation

 * functions are called.

 *

 * The <tt>OnValidationSuccess</tt> event is raised after the validator has successfully

 * validate the control.

 *

 * The <tt>OnValidationError</tt> event is raised after the validator fails validation.

 *

 * See the quickstart documentation for further details.

 *

 * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

 * @version $Id: TBaseValidator.php 2551 2008-10-30 17:07:05Z carlgmathisen $

 * @package System.Web.UI.WebControls

 * @since 3.0

 */

class TValidatorClientSide extends TClientSideOptions

{

	/**

	 * @return string javascript code for client-side OnValidate event.

	 */

	public function getOnValidate()

	{

		return $this->getOption('OnValidate');

	}

	/**

	 * Client-side OnValidate validator event is raise before the validators

	 * validation functions are called.

	 * @param string javascript code for client-side OnValidate event.

	 */

	public function setOnValidate($javascript)

	{

		$this->setFunction('OnValidate', $javascript);

	}

	/**

	 * Client-side OnSuccess event is raise after validation is successfull.

	 * This will override the default client-side validator behaviour.

	 * @param string javascript code for client-side OnSuccess event.

	 */

	public function setOnValidationSuccess($javascript)

	{

		$this->setFunction('OnValidationSuccess', $javascript);

	}

	/**

	 * @return string javascript code for client-side OnSuccess event.

	 */

	public function getOnValidationSuccess()

	{

		return $this->getOption('OnValidationSuccess');

	}

	/**

	 * Client-side OnError event is raised after validation failure.

	 * This will override the default client-side validator behaviour.

	 * @param string javascript code for client-side OnError event.

	 */

	public function setOnValidationError($javascript)

	{

		$this->setFunction('OnValidationError', $javascript);

	}

	/**

	 * @return string javascript code for client-side OnError event.

	 */

	public function getOnValidationError()

	{

		return $this->getOption('OnValidationError');

	}

	/**

	 * @param boolean true to revalidate when the control to validate changes value.

	 */

	public function setObserveChanges($value)

	{

		$this->setOption('ObserveChanges', TPropertyValue::ensureBoolean($value));

	}

	/**

	 * @return boolean true to observe changes.

	 */

	public function getObserveChanges()

	{

		$changes = $this->getOption('ObserveChanges');

		return is_null($changes) ? true : $changes;

	}

}

/**

 * TValidatorDisplayStyle class.

 * TValidatorDisplayStyle defines the enumerable type for the possible styles

 * that a validator control can display the error message.

 *

 * The following enumerable values are defined:

 * - None: the error message is not displayed

 * - Dynamic: the error message dynamically appears when the validator fails validation

 * - Fixed: Similar to Dynamic except that the error message physically occupies the page layout (even though it may not be visible)

 *

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

 * @version $Id: TBaseValidator.php 2551 2008-10-30 17:07:05Z carlgmathisen $

 * @package System.Web.UI.WebControls

 * @since 3.0.4

 */

class TValidatorDisplayStyle extends TEnumerable

{

	const None='None';

	const Dynamic='Dynamic';

	const Fixed='Fixed';

}

/**

 * TValidationDataType class.

 * TValidationDataType defines the enumerable type for the possible data types that

 * a comparison validator can validate upon.

 *

 * The following enumerable values are defined:

 * - Integer

 * - Float

 * - Date

 * - String

 *

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

 * @version $Id: TBaseValidator.php 2551 2008-10-30 17:07:05Z carlgmathisen $

 * @package System.Web.UI.WebControls

 * @since 3.0.4

 */

class TValidationDataType extends TEnumerable

{

	const Integer='Integer';

	const Float='Float';

	const Date='Date';

	const String='String';

}