validation
[ class tree: validation ] [ index: validation ] [ all elements ]
Packages:
form
formdata
formelements
tools
validation


Files:
HtmlForm.FormValidator.class.php

Classes:
FormValidator

Class: FormValidator

Source Location: /HtmlForm.FormValidator.class.php

Class Overview




A FormValidator defines a set of rules a widget-value has to fulfill before being able to be called valid.




Author(s):


    
          
  • Sebastian Schlapkohl
    • 
            





        
    

Version:


    
  
  • 1.0
    • 



        





Constants






Methods
























Class Details



[line 27]

A FormValidator defines a set of rules a widget-value has to fulfill before being able to be called valid.

Validation is an all-or-nothing game. If just one validator fails inside a structure being validated the whole  construct is deemed invalid. Keep that in mind when setting up the rules for a validator.
Depending on the nature of a formelement a validator is being provided with either one value or a bunch of values.  You don't have to care about this, the validator will handle this for you. Just use the rules as they seem logical  and if problems arise, read the description for the rule setter for further details.
If you validate after a form is completely constructed you also won't have to worry about utf-8 or language settings  for messages.





Tags:





  

    author:  Sebastian Schlapkohl
  

  

    version:  1.0
  










[ Top ]








Class Methods



  

	
	
static method get [line 82]

	

    

    

		static FormValidator get(
)
    

    


	
		Factory method for FormValidator, returns new instance.

Factories are used to make instant chaining possible.





Tags:





  

    return:  new FormValidator-instance
  

  

    access:  public
  









	
        
[ Top ]

  


  

	
	
method activateJavascriptValidation [line 2191]

	

    

    

		FormValidator activateJavascriptValidation(
[String|null
$selector = null], [String|null
$errorSelector = null])
    

    


	
		Prepares the validator for output of JS-valiation-code later on.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        String|null  
        $selector  
        jQuery-selector to specifically select elements to drag values from, normally the selector will be constructed by html-name-attribute
      

          

        String|null  
        $errorSelector  
        jQuery-selector to specifically select elements to error-mark in case of a failed validation, normally identical to selector
      

        

    


        
[ Top ]

  

  

	
	
method hasRule [line 2142]

	

    

    

		void hasRule(

$ruleName, [
$ruleValue = null])
    

    


	
		



Tags:





  

    access:  public
  









	
        
Parameters:

    

    

          

          
        $ruleName  
        
      

          

          
        $ruleValue  
        
      

        

    


        
[ Top ]

  

  

	
	
method printJavascriptValidationCode [line 2254]

	

    

    

		String printJavascriptValidationCode(
[Boolean
$prepareMessages = true])
    

    


	
		Compiles and returns the JS-validation-code for this validator, to be printed beneath the validated form elements  in the source later on. This code contains a sequence of single tests, that will be executed on every update of the  connected elements, which validate the value(s) one by one.

At the moment, there is no smart procedure to reuse code parts in several validations. Each fragment is specifically and  autonomously constructed for each validator.





Tags:





  

    return:  the JS-code to insert into the form-rendering, that validates the values of this validator according to its rules on the fly
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Boolean  
        $prepareMessages  
        defines if language messages shall be required, only has to be the case once, deactivating this is simply a question of performance
      

        

    


        
[ Top ]

  

  

	
	
method printMessageQueue [line 2223]

	

    

    

		String printMessageQueue(
[Boolean
$onlyCustomMessages = false])
    

    


	
		Return all aggregated error messages of the validator.

This method will only return something wortwhile after process() has been called, since before that  there are no messages queued.





Tags:





  

    return:  all compiled messages of the validator
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Boolean  
        $onlyCustomMessages  
        sets if all standard messages should be used or only custom ones
      

        

    


        
[ Top ]

  

  

	
	
method process [line 2166]

	

    

    

		Boolean process(
)
    

    


	
		Starts the validation if the given values accourding to all set rules of the validator.

Normally called automatically by the widget the values originate from.





Tags:





  

    return:  value(s) is/are valid yes/no
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setAutoErrorMessagesAsCustom [line 130]

	

    

    

		FormValidator setAutoErrorMessagesAsCustom(
)
    

    


	
		Tells the validator to treat standard messages as custom in the context of this validator.

This method has the purpose to use standard messages selectively in a form where standard  messages are disabled by default.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setCharacterClass [line 584]

	

    

    

		FormValidator setCharacterClass(
String
$regExCharacterClass)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must only consist of characters defined in a given  regex-character-class.

a-zA-Z0-9äüöÄÜÖß for example





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        String  
        $regExCharacterClass  
        the regex-character class to check against
      

        

    


        
[ Top ]

  

  

	
	
method setCreditcard [line 569]

	

    

    

		FormValidator setCreditcard(
)
    

    


	
		Adds a rule to the validator's ruleset -	The widget's value has have the form of a valid creditcard-number.

(1)234-1234-1234-1234





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setCustomCase [line 236]

	

    

    

		FormValidator setCustomCase(
Boolean/String/Array
$customResult)
    

    


	
		Adds a rule to the validator's ruleset - Includes a predefined validation-result into the ruleset.

The result may have two characteristics:  Eiter it's a boolean value, simply telling the validator if the test has succeeded  or failed. Or it's a string, with an empty string being a successful test and a  non-empty string being a failed test, where the string is the error message to display.  This is not a custom message, but rather an override for the standard message, which is  rather nondescript for custom cases.
You can also provide an Array, where the first element is the PHP-expression, while the second element  must be valid JS-code to return the validation result from. The JS-validation-code has to set the var res  (don't redeclare the var) to the result of the validation.
You can even set this handler up for async validation by not setting res, but instead calling customCaseAsyncFinalize(res)  at the end of the async request. Here two examples for special-JS-code:
sequential:  ->setCustomCase(array(true, 'res = $('body .class_'+$(this).val()).length > 0;'))
async:  ->setCustomCase(array(true, '$.getJSON('/service:validation/something', {a:'b'}, function(data){ customCaseAsyncFinalize(data.res) });'))





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Boolean/String/Array  
        $customResult  
        the precalculated result of the custom case
      

        

    


        
[ Top ]

  

  

	
	
method setDataName [line 160]

	

    

    

		FormValidator setDataName(

$dataName)
    

    


	
		Tells the validator the name of the element's data in the submit-resultset.

This is normally identical to the html-name-attribute's value of the rendered element.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

          
        $dataName  
        
      

        

    


        
[ Top ]

  

  

	
	
method setDate [line 412]

	

    

    

		FormValidator setDate(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard american date.

(d)d/(m)m/yyyy





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setDateDE [line 490]

	

    

    

		FormValidator setDateDE(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard german date.

(d)d.(m)m.yyyy





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setDateISO [line 451]

	

    

    

		FormValidator setDateISO(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard iso-date.

yyyy-mm-dd





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setDateTime [line 438]

	

    

    

		FormValidator setDateTime(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be standard american datetime.

Either dd/mm/yyyy + (h)h:mm(:ss)am|pm





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setDateTimeDE [line 516]

	

    

    

		FormValidator setDateTimeDE(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard german datetime.

(d)d.(m)m.yyyy hh:mm:ss(h)





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setDateTimeISO [line 477]

	

    

    

		FormValidator setDateTimeISO(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be standard iso-datetime.

yyyy-mm-dd(T| )hh:mm:ss





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setDigits [line 556]

	

    

    

		FormValidator setDigits(
)
    

    


	
		Adds a rule to the validator's ruleset -	The number-representation of the widget's value must be only  digits without any other characters.

1234567890





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setEmail [line 384]

	

    

    

		FormValidator setEmail(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a valid eMail-address.

This is no run-of-the-mill check, but quite elaborate.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setErrorMessage [line 116]

	

    

    

		FormValidator setErrorMessage(
String
$message)
    

    


	
		Sets a custom error message for the validator, overwriting all standard messages from  the dictionaries.

Use this to further describe special error cases, to aid your users.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        String  
        $message  
        the message to display in case of a validation error
      

        

    


        
[ Top ]

  

  

	
	
method setFieldName [line 147]

	

    

    

		FormValidator setFieldName(
String
$name)
    

    


	
		Tells the validator the name of the element in validates.

In most cases this is the value of the widget's label.  This information is necessary for standard-message-display and normally provided  automatically when inserting a validator into an element.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        String  
        $name  
        the description of the widget the validator validates
      

        

    


        
[ Top ]

  

  

	
	
method setMax [line 355]

	

    

    

		FormValidator setMax(
int
$max)
    

    


	
		Adds a rule to the validator's ruleset - The number-representation of the widget's value can  only have a maximum numeric value.

For multiple values this rule will check each value individually.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        int  
        $max  
        the maximum numeric value
      

        

    


        
[ Top ]

  

  

	
	
method setMaxLength [line 309]

	

    

    

		FormValidator setMaxLength(
uint
$maxlength)
    

    


	
		Adds a rule to the validator's ruleset - The string-representation of the widget's value may only  have a certain length.

For multiple values this method uses the amount of values.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        uint  
        $maxlength  
        the maximum length the value can have
      

        

    


        
[ Top ]

  

  

	
	
method setMessageLanguage [line 101]

	

    

    

		FormValidator setMessageLanguage(
String
$language)
    

    


	
		Sets the language for all validation-error-messages take from message dictionaries.

The available languages and their names are defined by the dictionaries present  in /messages.





Tags:





  

    return:  method owner
  

  

    see:  messages/english.inc.php
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        String  
        $language  
        the name of the language to use
      

        

    


        
[ Top ]

  

  

	
	
method setMin [line 340]

	

    

    

		FormValidator setMin(
int
$min)
    

    


	
		Adds a rule to the validator's ruleset - The number-representation of the widget's value must  have a minimum numeric value.

For multiple values this rule will check each value individually.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        int  
        $min  
        the minimum numeric value
      

        

    


        
[ Top ]

  

  

	
	
method setMinLength [line 294]

	

    

    

		FormValidator setMinLength(
uint
$minlength)
    

    


	
		Adds a rule to the validator's ruleset - The string-representation of the widget's value needs  to have a certain length.

For multiple values this method uses the amount of values.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        uint  
        $minlength  
        the minimum length the value has to have
      

        

    


        
[ Top ]

  

  

	
	
method setNotEmpty [line 265]

	

    

    

		FormValidator setNotEmpty(
[
$additionalEmptyValues = array()])
    

    


	
		Adds a rule to the validator's ruleset - The widget needs to have a non-empty value.

Either this means that the value can't be an empty string or one consisting of whitespace  or that the amount of values mustn't be 0.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Array  
        $additionalEmptyValues  
        array of additional widget values to be considered empty besides an empty string
      

        

    


        
[ Top ]

  

  

	
	
method setNumber [line 529]

	

    

    

		FormValidator setNumber(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard english decimal number.

123(.456)





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setNumberDE [line 542]

	

    

    

		FormValidator setNumberDE(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard german decimal number.

123(,456)





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setOptional [line 279]

	

    

    

		FormValidator setOptional(
[
$additionalEmptyValues = array()])
    

    


	
		Adds a rule to the validator's ruleset - The widget's value becomes optional, either its not set at all, or it get  validated by all other present rules.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Array  
        $additionalEmptyValues  
        array of additional widget values to be considered empty besides an empty string
      

        

    


        
[ Top ]

  

  

	
	
method setRange [line 371]

	

    

    

		FormValidator setRange(

$range)
    

    


	
		Adds a rule to the validator's ruleset - The number-representation of the widget's value  must have a minimum and can only be of a maximum numeric value.

In general this is a shortcut for setMin()+setMax().  For multiple values this rule will check each value individually.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Array[int]  
        $range  
        
      

        

    


        
[ Top ]

  

  

	
	
method setRangeLength [line 325]

	

    

    

		FormValidator setRangeLength(

$range)
    

    


	
		Adds a rule to the validator's ruleset - The string-representation of the widget's value must have  a minimum length and must not exceed a maximum length.

In general this is a shortcut for setMinLength()+setMaxLength().  For multiple values this method uses the amount of values.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Array[uint]  
        $range  
        first element is min, second is max
      

        

    


        
[ Top ]

  

  

	
	
method setRequired [line 250]

	

    

    

		FormValidator setRequired(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget needs to have a value.

Either this means that the value can't be an empty string or that the amount  of values mustn't be 0.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setTime [line 425]

	

    

    

		FormValidator setTime(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be standard american time.

(h)h:mm(:ss)am|pm





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setTimeDE [line 503]

	

    

    

		FormValidator setTimeDE(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a standard german time.

hh:mm:ss(h)





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setTimeISO [line 464]

	

    

    

		FormValidator setTimeISO(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be standard iso-time.

hh:mm:ss





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setUrl [line 399]

	

    

    

		FormValidator setUrl(
)
    

    


	
		Adds a rule to the validator's ruleset - The widget's value must be a valid url.

This is no run-of-the-mill check, but quite elaborate.  Url has to look something like this.  [http(s)/ftp][subdomain/domain][domain/tld]([tld])([port])([query])([anchor])





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
[ Top ]

  

  

	
	
method setUtf8Safety [line 204]

	

    

    

		FormValidator setUtf8Safety(
[Boolean
$needed = true])
    

    


	
		Tells the validator to treat all validated values as utf-8-encoded or vice versa.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        Boolean  
        $needed  
        multibyte-security needed yes/no
      

        

    


        
[ Top ]

  

  

	
	
method setValue [line 177]

	

    

    

		FormValidator setValue(
String
$value)
    

    


	
		Set the value the validator should validate.

Used for widgets with single values.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        String  
        $value  
        current value of the connected widget
      

        

    


        
[ Top ]

  

  

	
	
method setValues [line 191]

	

    

    

		FormValidator setValues(

$values)
    

    


	
		Set the values the validator should validate.

Used for widgets with multiple values.





Tags:





  

    return:  method owner
  

  

    access:  public
  









	
        
Parameters:

    

    

          

        array  
        $values  
        
      

        

    


        
[ Top ]

  









Class Constants



	
	

	
MESSAGECLASS =  'htmlform_message_div'

	
[line 33]

  css-class for individual validation-error-messages


  

	
[ Top ]






        

		    

		    Documentation generated on Fri, 18 Jul 2014 16:32:01 +0200 by phpDocumentor 1.4.3