Configuration of field evaluation.
Some of these evaluation keywords will trigger a JavaScript pre-evaluation in the form. Other evaluations will be performed in the backend.
The eval-functions will be executed in the list-order.
Keywords:
-
required : A non-empty value is required in the field (otherwise the form cannot be saved).
-
trim : The value in the field will have whitespaces around it trimmed away.
-
date : The field will evaluate the input as a date, automatically converting the input to a UNIX-time in seconds. The display will be like "12-8-2003" while the database value stored will be "1060639200".
-
datetime : The field will evaluate the input as a date with time (detailed to hours and minutes), automatically converting the input to a UNIX-time in seconds. The display will be like "16:32 12-8-2003" while the database value will be "1060698720".
-
time : The field will evaluate the input as a timestamp in seconds for the current day (with a precision of minutes). The display will be like "23:45" while the database will be "85500".
-
timesec : The field will evaluate the input as a timestamp in seconds for the current day (with a precision of seconds). The display will be like "23:45:13" while the database will be "85513".
-
year : Evaluates the input to a year between 1970 and 2038. If you need any year, then use "int" evaluation instead.
-
int : Evaluates the input to an integer.
-
upper : Converts to uppercase (only A-Z plus a selected set of Western European special chars).
-
lower : Converts the string to lowercase (only A-Z plus a selected set of Western European special chars).
-
alpha : Allows only a-zA-Z characters.
-
num : Allows only 0-9 characters in the field.
-
alphanum : Same as "alpha" but allows also "0-9"
-
alphanum_x : Same as "alphanum" but allows also "_" and "-" chars.
-
nospace : Removes all occurencies of space characters (chr(32))
-
md5 : Will convert the inputted value to the md5-hash of it (The JavaScript MD5() function is found in typo3/md5.js)
-
is_in : Will filter out any character in the input string which is not found in the string entered in the key "is_in" (see below).
-
password : Will show "*******" in the field after entering the value and moving to another field. Thus passwords can be protected from display in the field. Notice that the value during entering it is visible!
-
double2 : Converts the input to a floating point with 2 decimal positions, using the "." (period) as the decimal delimited (accepts also "," for the same).
-
unique : Requires the field to be unique for the whole table. (Evaluated on the server only). NOTICE: When selecting on unique-fields, make sure to select using “AND pid>=0” since the field CAN contain duplicate values in other versions of records (always having PID = -1). This also means that if you are using versioning on a table where the unique-feature is used you cannot set the field to be truely unique in the database either!
-
uniqueInPid : Requires the field to be unique for the current PID (among other records on the same page). (Evaluated on the server only)
-
tx_* : User defined form evaluations. See below.
All the above evaluations (unless noted) are done by JavaScript with the functions found in the script t3lib/jsfunc.evalfield.js
"(TCE)" means the evaluation is done in the TCE on the server. The class used for this is t3lib_TCEmain.
Example:
Setting the field to evaluate the input to a date returned to the database in UNIX-time (seconds)
'eval' => 'date',
Trimming the value for white space before storing in the database (important for varchar fields!)
'eval' => 'trim',
By this configuration the field will be stripped for any space characters, converted to lowercase, only accepted if filled in and on the server the value is required to be unique for all records from this table:
'eval' => 'nospace,lower,unique,required'
User defined form evaluations:
You can supply your own form evaluations in an extension by creating a class with two functions, one which returns the JavaScript code for client side validation called returnFieldJS() and one which does the server side validation called evaluateFieldValue().
The function evaluateFieldValue() has 3 arguments:
-
$value :The field value to be evaluated.
-
$is_in : The is_in value of the field configuration from TCA.
-
&$set : Boolean defining if the value is written to the database or not. Must be passed by reference and changed if needed.
Example:
class.tx_exampleextraevaluations_extraeval1.php:
<?php
class tx_exampleextraevaluations_extraeval1 {
function returnFieldJS() {
return '
return value + " [added by JS]";
';
}
function evaluateFieldValue($value, $is_in, &$set) {
return $value.' [added by PHP]';
}
}
?>
ext_localconf.php
<?php
// here we register "tx_exampleextraevaluations_extraeval1"
$TYPO3_CONF_VARS['SC_OPTIONS']['tce']['formevals']['tx_exampleextraevaluations_extraeval1'] = 'EXT:example_extraevaluations/ class.tx_exampleextraevaluations_extraeval1.php';
?>
Feel free to download the example extension as a T3X file.
typo3.org/documentation/document-library/core-documentation/doc_core_api/4.1.0/view/4/2/