Email

New in version 12.0

The TCA type email has been introduced. It replaces the eval=email option of TCA type input. See also Migration.

The TCA type email should be used to input values representing email addresses.

Table of contents

Properties of the TCA column type `email`

Name	Type	Scope
behaviour
allowLanguageSynchronization	boolean	Proc.
autocomplete	boolean	Display
eval	string (list of keywords)	Display / Proc.
fieldInformation
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
mode	string (keywords)	Display
nullable	boolean	Proc
placeholder	integer Unix timestamp	Display
readOnly	boolean	Display
required	boolean	Display / Proc.
size	integer	Display

behaviour

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

$emailField = [
    'config' => [
        'type' => 'email',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

autocomplete

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

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

<?php

$temporaryColumns['email'] = [
    'label' => 'email',
    'config' => [
        'type' => 'email',
        'size' => 20,
        'nullable' => true,
        'autocomplete' => true,
    ],
];

eval

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

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 evaluation functions will be executed in the list-order. Keywords:

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

Note

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 truly 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.

Example: Email field unique on the storage page

Require an email address to be unique for this record type in this folder

<?php

$temporaryColumns['email'] = [
    'label' => 'aLabel',
    'config' => [
        'type' => 'email',
        'eval' => 'uniqueInPid',
    ],
];

fieldInformation: For details see fieldInformation.

fieldWizard

defaultLanguageDifferences

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

For details see defaultLanguageDifferences.

localizationStateSelector

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

For details see localizationStateSelector.

otherLanguageContent

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

For details see otherLanguageContent.

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.

Warning

In order for this property to apply properly, option nullable must be set to true.

nullable

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['nullable']
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.

When the eval option is set to unique or uniqueInPid multiple null values are still possible.

The database field must allow the NULL value.

Example:

EXT:some_extension/Configuration/TCA/tx_sometable.php

'columns' => [
     'nullable_column' => [
          'title' => 'A nullable field',
          'config' => [
                'type' => 'email',
                'nullable' => true,
                'eval' => 'uniqueInPid',
          ],
     ],
],

placeholder

Type: integer Unix timestamp
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
Scope: Display

Placeholder, containing a default date.

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

<?php

$temporaryColumns['my-date'] = [
    'title' => 'My email field',
    'config' => [
        'type' => 'email',
        'placeholder' => 'info@example.com',
        'mode' => 'useOrOverridePlaceholder',
    ],
];

readOnly

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

Renders the field in a way that the user can see the values but cannot edit them. The rendering is as similar as possible to the normal rendering but may differ in layout and size.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

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.

size

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

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

Note

The softref definition 'softref' => 'email[subst]' is automatically applied to all email fields.

Migration

The migration from eval='email' to type=email is done like following:

 'email_field' => [
     'label' => 'Email',
     'config' => [
-        'type' => 'input',,
-        'eval' => 'trim,email',
+        'type' => 'email'
-        'max' => 255,
     ]
 ],

An automatic TCA migration is performed on the fly, migrating all occurrences to the new TCA type and triggering a PHP E_USER_DEPRECATED error where code adoption has to take place.

Note

The value of TCA type email columns is automatically trimmed before being stored in the database. Therefore, the eval=trim option is no longer needed and should be removed from the TCA configuration.

Email

Properties of the TCA column type email

behaviour

allowLanguageSynchronization

autocomplete

eval

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

mode

nullable

placeholder

readOnly

required

size

Migration

Properties of the TCA column type `email`