Input

type='input' generates a html <input> field with the type attribute set to text. It is possible to apply additional features such as the valuePicker.

The according database field is generated automatically. For short input fields allowing less than 255 chars VARCHAR() is used, TEXT for larger input fields.

Extension authors who need or want to override default TCA schema details for whatever reason, can of course do so by defining something specific in ext_tables.sql.

Changed in version 13.2

Tables with TCA columns set to type="input" do not need an ext_tables.sql entry anymore. The Core now creates this column automatically.

Examples

Simple input field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php
[
    'columns' => [
        'input_1' => [
            'l10n_mode' => 'prefixLangTitle',
            'label' => 'input_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'input',
                'behaviour' => [
                    'allowLanguageSynchronization' => true,
                ],
            ],
        ],
    ],
]
Copied!

Input with placeholder and null handling

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php
[
    'columns' => [
        'input_28' => [
            'label' => 'input_28',
            'description' => 'placeholder=__row|input_26 mode=useOrOverridePlaceholder nullable=true default=null',
            'config' => [
                'type' => 'input',
                'placeholder' => '__row|input_26',
                'nullable' => true,
                'default' => null,
                'mode' => 'useOrOverridePlaceholder',
            ],
        ],
    ],
]
Copied!

Value picker

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php
[
    'columns' => [
        'input_33' => [
            'label' => 'input_33',
            'description' => 'valuePicker',
            'config' => [
                'type' => 'input',
                'size' => 20,
                'eval' => 'trim',
                'valuePicker' => [
                    'items' => [
                        [
                            'spring',
                            'Spring',
                        ],
                        [
                            'summer',
                            'Summer',
                        ],
                        [
                            'autumn',
                            'Autumn',
                        ],
                        [
                            'winter',
                            'Winter',
                        ],
                    ],
                ],
            ],
        ],
    ],
]
Copied!

Properties of the TCA column type input

Name Type Scope
boolean Proc.
boolean Display
string Display / Proc.
string (list of keywords) Display / Proc.
array
array
array
string Display / Proc.
integer Display
integer Display
string (keywords) Display
boolean Proc
string Display
boolean Display
boolean Display / Proc.
array Search
boolean
boolean
string
integer Display
string Proc.
array Display

behaviour

behaviour

allowLanguageSynchronization

allowLanguageSynchronization
Type
boolean
Default
false
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope
Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

EXT:my_extension/Configuration/TCA/Overrides/someTable.php
<?php

$inputField = [
    'config' => [
        'type' => 'input',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];
Copied!

autocomplete

autocomplete
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Controls the autocomplete attribute of a given input field. If set to true (default false), adds attribute autocomplete="on" to the input field allowing browser auto filling the field:

'title' => [
    'label' => 'LLL:EXT:lang/locallang_tca.xlf:sys_file_reference.title',
    'config' => [
        'type' => 'input',
        'size' => 20,
        'nullable' => true,
        'autocomplete' => true
    ]
],
Copied!

default

default
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
Scope
Display / Proc.

Default value set if a new record is created. If empty, no input gets selected.

eval

eval
Type
string (list of keywords)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

Configuration of field evaluation. See also Input fields with eval.

Some of these evaluation keywords will trigger a JavaScript pre- evaluation in the form. Other evaluations will be performed in the backend. The evaluation functions will be executed in the list-order. Keywords:

alpha
Allows only a-zA-Z characters.
alphanum
Same as "alpha" but allows also "0-9"
alphanum_x
Same as "alphanum" but allows also "_" and "-" chars.
domainname
Allows a domain name such as example.org and automatically transforms the value to punicode if needed.
is_in
Will filter out any character in the input string which is not found in the string entered in the property is_in.
lower
Converts the string to lowercase (only A-Z plus a selected set of Western European special chars).
md5
Will convert the input value to its md5-hash using a JavaScript function.
nospace
Removes all occurrences of space characters (chr(32))
num
Allows only 0-9 characters in the field.
trim
The value in the field will have white spaces around it trimmed away.
unique

Requires the field to be unique for the whole table. Evaluated on the server only.

uniqueInPid
Requires the field to be unique for the current PID among other records on the same page. Evaluated on the server only.
upper
Converts to uppercase (only A-Z plus a selected set of Western European special chars).
year
Evaluates the input to a year between 1970 and 2038. If you need any year, then use "int" evaluation instead.
Vendor\Extension\*
User defined form evaluations.

fieldControl

fieldControl

For details see fieldControl.

fieldInformation

fieldInformation

For details see fieldInformation.

fieldWizard

fieldWizard

defaultLanguageDifferences

defaultLanguageDifferences
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector

localizationStateSelector
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent

otherLanguageContent
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

is_in

is_in
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

If the evaluation type "is_in" (see eval) is used for evaluation, then the characters in the input string should be found in this string as well. This value is also passed as argument to the evaluation function if a user-defined evaluation function is registered.

max

max
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Value for the "maxlength" attribute of the <input> field. Javascript prevents adding more than these number of characters.

If the form element edits a varchar(40) field in the database you should also set this value to 40.

min

min
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

This option allows to define a minimum number of characters for the <input> field and adds a minlength attribute to the field. If at least one character is typed in and the number of characters is less than min, the FormEngine marks the field as invalid, preventing the user to save the element. DataHandler will also take care for server-side validation and reset the value to an empty string, if min is not reached.

When using min in combination with , one has to make sure, the min value is less than or equal max. Otherwise the option is ignored.

Empty fields are not validated. If one needs to have non-empty values, it is recommended to use required => true in combination with min.

mode

mode
Type
string (keywords)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['mode']
Scope
Display

Possible keywords: useOrOverridePlaceholder

This property is related to the placeholder property. When defined, a checkbox will appear above the field. If that box is checked, the field can be used to enter whatever the user wants as usual. If the box is not checked, the field becomes read-only and the value saved to the database will be NULL.

nullable

nullable
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Default
false
Scope
Proc

If set to true, a checkbox will appear, which by default deactivates the field. In the deactivated state the field is saved as NULL in the database. By activating the checkbox it is possible to set a value. If nothing is entered into the field, then an empty string will be saved and not a NULL.

The database field must allow the NULL value.

Example: A nullable field
EXT:some_extension/Configuration/TCA/tx_sometable.php
'columns' => [
     'nullable_column' => [
          'title' => 'A nullable field',
          'config' => [
                'type' => 'input',
                'nullable' => true,
                'eval' => 'trim',
          ],
     ],
],
Copied!

placeholder

placeholder
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
Scope
Display

Placeholder, containing a default value.

EXT:my_extension/Configuration/TCA/Overrides/some-table.php
<?php

$temporaryColumns['ainputField'] = [
    'title' => 'My input field',
    'config' => [
        'type' => 'input',
        'placeholder' => '#FF8700',
        'mode' => 'useOrOverridePlaceholder',
    ],
];
Copied!

readOnly

readOnly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope
Display

Renders the field in a way that the user can see the value but cannot edit it.

required

required
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
Default
false

If set to true a non-empty value is required in the field. Otherwise the form cannot be saved.

search

Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']
Scope
Search

Defines additional search-related options for a given field.

pidonly

pidonly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['pidonly']

Searches in the column only if search happens on the single page, does not search the field if searching in the whole table.

case

case
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['case']

Makes the search case-sensitive. This requires a proper database collation for the field, see your database documentation.

andWhere

andWhere
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['andWhere']

Additional SQL WHERE statement without 'AND'. With this it is possible to place an additional condition on the field when it is searched

EXT:some_extension/Configuration/TCA/tx_sometable.php
$temporaryColumns['some_date'] => [
    'config' => [
        'search' => [
            'andWhere' => '{#CType}=\'type_x\' OR {#CType}=\'type_y\'',
        ],
        // ...
    ],
];
Copied!

This means that the "some_date" field of the "tt_content" table will be searched in only for elements of type X and Y. This helps making any search more relevant.

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

size

size
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Abstract value for the width of the <input> field. To set the input field to the full width of the form area, use the value 50. Minimum is 10. Default is 30.

softref

softref
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc.
Types
input

Used to attach "soft reference parsers".

The syntax for this value is key1,key2[parameter1;parameter2;...],...

See Soft references of core API for more details about softref keys.

valuePicker

valuePicker
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Renders a select box with static values next to the input field. When a value is selected in the box, the value is transferred to the field. Keys:

mode (keyword)
blank (or not set)
The selected value substitutes the value in the input field
append
The selected value is appended to an existing value of the input field
prepend
The selected value is prepended to an existing value of the input field
items (array)
An array with selectable items. Each item is an array with the first value being the label in the select drop-down (LLL reference possible) the second being the value transferred to the input field.
Example: An input field with value picker
'input_33' => [
    'label' => 'input_33',
    'config' => [
        'type' => 'input',
        'valuePicker' => [
            'items' => [
                ['spring', 'Spring'],
                ['summer', 'Summer'],
                ['autumn', 'Autumn'],
                ['winter', 'Winter'],
            ],
        ],
    ],
],
Copied!

Input fields with eval

Trim white space

Trimming the value for white space before storing in the database:

<?php

$aField = [
    'label' => 'aLabel',
    'config' => [
        'type' => 'input',
        'eval' => 'trim',
    ],
];
Copied!

Combine eval rules

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'
Copied!

Custom eval rules

You can supply own form evaluations in an extension by creating a class with three functions, one which returns the JavaScript code for client side validation called returnFieldJS() and two for the server side: deevaluateFieldValue() called when opening the record and evaluateFieldValue() called for validation when saving the record:

EXT:extension/Classes/Evaluation/ExampleEvaluation.php

EXT:my_extension/Classes/EvaluationExampleEvaluation.php
<?php

namespace MVendor\MyExtension\Evaluation;

/**
 * Class for field value validation/evaluation to be used in 'eval' of TCA
 */
class ExampleEvaluation
{
    /**
     * JavaScript code for client side validation/evaluation
     *
     * @return string JavaScript code for client side validation/evaluation
     */
    public function returnFieldJS()
    {
        return 'return value + " [added by JavaScript on field blur]";';
    }

    /**
     * Server-side validation/evaluation on saving the record
     *
     * @param string $value The field value to be evaluated
     * @param string $is_in The "is_in" value of the field configuration from TCA
     * @param bool $set Boolean defining if the value is written to the database or not.
     * @return string Evaluated field value
     */
    public function evaluateFieldValue($value, $is_in, &$set)
    {
        return $value . ' [added by PHP on saving the record]';
    }

    /**
     * Server-side validation/evaluation on opening the record
     *
     * @param array $parameters Array with key 'value' containing the field value from the database
     * @return string Evaluated field value
     */
    public function deevaluateFieldValue(array $parameters)
    {
        return $parameters['value'] . ' [added by PHP on opening the record]';
    }
}
Copied!
EXT:my_extension/ext_localconf.php
<?php

use Vendor\Extension\Evaluation\ExampleEvaluation;

// ....

// Register the class to be available in 'eval' of TCA
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tce']['formevals'][ExampleEvaluation::class] = '';
Copied!
EXT:extension/Configuration/TCA/tx_example_record.php
<?php

return [
    // ...
    'columns' => [
        'example_field' => [
            'config' => [
                'type' => 'text',
                'required' => true,
                'eval' => 'trim,' . \MyVendor\MyExtension\Evaluation\ExampleEvaluation::class,
            ],
        ],
    ],
];
Copied!