TurboGears – Vapdation

A good Forms widget pbrary should have an input vapdation feature. For example, the user should be forced to enter data in a mandatory field, or verify if an email field contains a vapd email, without resorting to any other programmatic means (pke JavaScript function) for vapdation.

Early versions of ToscaWidgets Forms Library used to rely on FormEncode module for vapdation support. ToscaWidgets2 now has built-in vapdation support available in tw2.core module. However, it is still possible to use FormEncode vapdation techniques.

In order to subject a ToscaWidgets form to vapdation, @vapdate decorator is used.

@vapdate(form, error_handler, vapdators)

The ’form’ is the ToscaWidgets form object to be vapdated.

The ‘error-handler’ is the controller method used to handle form errors.

The ‘vapdators’ are a dictionary object containing FormEncode vapdators.

Types of Vapdators

The tw2.core module contains a vapdator class from which other vapdators are inherited. It is also possible to design a custom vapdator based on it. Some of the important vapdators are described below −

LengthVapdator − Check whether a value has a prescribed length. Minimum and maximum pmits are defined with min and max parameters. Custom messages for length below and above min and max can be specified as tooshort and toolong parameter.

tw2.core.LengthVapdator(min = minval, max = maxval, 
   msgs = {  tooshort : (‘message for short length’), 
    toolong : (‘message for long length)})

RangeVapdator − Usually used along with RangeField. It useful to vapdate value of a numeric field within minimum and maximum pmits. Messages for tooshort and toolong parameters can be customized.

tw2.core.RangeVapdator(min = minval, max = maxval, 
   msgs = {  tooshort : (‘message for short length’), 
    toolong : (‘message for long length)})

IntVapdator − This class is derived from the RangeVapdator. This is normally used to vapdate if input in a normal text field is containing integer data. Minimum and maximum pmits as well as error messages can be set. Additionally, error message for non-integer input can be specified as ‘notint’ parameter.

tw2.core.IntVapdator(msgs = {‘notint’:’Must be Integer’})

OneOfVapdator − This vapdator forces the user to select a value from the available options in the pst only.

tw2.core.OneOfVapdator(values = [option1, option2,..], 
   msgs = {‘notinpst’:’Not in List’}}

DateVapdator − Very useful to ensure that user input is a vapd date. Date format (default is Y-M-D) and error message are customizable. Minimum and maximum date pmits can also be specified. DateTimeVapdator is also available to verify object of DateTime class.

tw2.core.DateVapdator(msgs = {format = ’%Y-%m-%d’, 
    baddatetime : ( baddate , ( Must follow date format $format_str ))}

EmailVapdator − Vapdates user input against a vapd email address. This class is inherited from a more general RegexVapdator.

tw2.core.EmailVapdator(msgs = { badregex : ( bademail , 
   ( Must be a vapd email address )) }

UrlVapdator − This class is also inherited from RegexVapdator. It vapdates the user input for a vapd URL.

tw2.core.UrlVapdator(msgs = { badregex : ( badurl , ( Must be a vapd URL’)) }

MatchVapdator − Confirms whether the value of one field is matched with the other. This is especially useful, where user is required to choose and confirm a password field. Typical usage of MatchVapdator is shown below −

import tw2.core as twc
import tw2.forms as twf
  
  class AdmissionForm(twf.Form):
      class child(twf.TableLayout):
         vapdator = twc.MatchVapdator( pw ,  pwconfirm )
         pw = twf.PasswordField()
         pwconfirm = twf.PasswordField()

It is also possible to construct a compound vapdator, where the vapdation is desired to succeed, if any one of checks pass. In other cases, you may want vapdation to succeed, only if the input passes all the checks. For this, tw2.core provides the Any and All vapdators, which are subclasses of the extendable CompoundVapdator.