NAME

HTML::FormEngine::Checks - collection of FormEngine check routines

CHECK ROUTINES

NOTE: all error messages are passed through gettext, that means if you configured you locales e.g. to german you get the corresponding german error message instead of the english messages which are mentioned here. Read HTML::FormEngine and HTML::FormEngine::Handler on how to overwrite the default error messages with your own in the form configuration.

not_null

Returns value missing if the field wasn't filled.

email

Returns invalid if the format of the field value seems to be incompatible to an email address. A simple regular expression is used here , so far it matches the common email addresses. But it isn't compatible to any standard. Use rfc822 if you want to check for RFC compatible address format.

Here is the used regexp, please inform me if you discover any bugs:

^[A-Za-z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$

rfc822

Returns standard incompatible if the given field value doesn't match the RFC 822 specification. In RFC 822 the format of valid email addresses is defined. This check routine is somewhat better than email, the only disadvantage is, that some working email addresses don't follow the RFC 822 standard. So if you have problems try using the email routine.

Thanks to Richard Piacentini for fixing this method :)

It now simply uses the rfc822 method of Email::Valid (you have to install Email::Valid to be able to use this method).

date

Returns invalid if the field value seems to be incompatible to common date formats or the date doesn't exist in the Gregorian calendar. The following formats are allowed:

dd.mm.yyyy dd-mm-yyyy dd/mm/yyyy yyyy-mm-dd yyyy/mm/dd yyyy.mm.dd

The check_date method of the Date::Pcalc package is used to prove the dates existence.

digitonly

... returns invalid if the value doesn't match [0-9]*.

match

Expects a variable name as first argument. If the argument is not given, the method uses saved as variable name. It then trys to read in the value of the variable and returns an error if its not equal to the value of the current field.

This method can also compare arrays. In that case the two arrays must have the same count of fields and every field must match its partner in the other array.

Please also read "fmatch ".

fmatch

Like match but instead of expecting the argument to be a variable name it expects it to be a fieldname and thus compares the currents field value with the value of the field which fieldname was given. If the argument is not given, the method will try to read in the variable fmatch to be compatible to older versions of FormEngine (fmatch is deprecated, don't use it!). The rest works exactly as in match.

If the value of the field that you want to check against isn't unique because you used that field name several times, you can use a trick: call the handler save_to_global in the fields definition so that its value is saved to a global variable which by default is saved (that's why the match check methods default is also saved). Have a look at FormEngine:.DBSQL s example manageuserswithpassword.cgi for better understanding.

Note: When you're using the DBSQL extension and you defined several tables, you must reference other fields with tablename.fieldname!

regex

Expects a regular expression string as first argument. For being compatible to older versions of FormEngine it'll read in the special variable regex if the first argument is not given (regex is deprecated, don't use it!). If the value doesn't match this regex, invalid is returned.

unique

This check method simply checks that the fields value is unique in the list of values of fields with the same field name. So this check method only makes sense if you used a field name more than one time. You can pass it the name of the variable which configures the field name. The default is NAME which should be fine, so you normally don't have to pass any arguments.

It returns not unique! if the check fails. Note: you can translate this text easily so that it is displayed in the language configured by your locale setting. Read ERROR MESSAGE TRANSLATION for more info.

WRITING A CHECK ROUTINE

Design

In general, a check routine has the following structure:

  sub mycheck {
    my($value,$self,$caller,@args) = @_;
    #some lines of code#
    return gettext('My ErrorMessage');
  }

$value contains the submitted field value.

$self contains a reference to the FormEngine object.

$caller contains the name with which the check method was called, this is only given if the check method has a name! That means that it was referenced by its name defined in by the skin. Methods referenced directly by a function reference do not get passed this value.

@args contains the list of arguments configured by the user for that check method call.

Note: you can define the error message and pass arguments by yourself with the help of an array: [checkmethod, errmsg, arg1, arg2..]

Install

If your routine does a general job, you can make it part of a FormEngine skin. Therefore just add the routine to e.g. this file and refer to it from Skin.pm or any other skin package. Please send me such routines.

ERROR MESSAGE TRANSLATIONS

The translations of the error messages are stored in FormEngine.po files. Calling msgfmt translates these into FormEngine.mo files. You must store these FormEngine.mo files in your locale directory, this should be /usr/share/locale, if it isn't, you have to pass the right pass to the constructor of your FormEngine skin (see HTML::FormEngine::Skin and e.g. sendmessages.cgi).

Provided that a translation for yourlanguage exists, you can call setlocale(LC_MESSAGES, 'yourlanguage') in your script to have the FormEngine error message in yourlanguage.

cpanm HTML::FormEngine

perl -MCPAN -e shell
install HTML::FormEngine