text (multiline)

This page describes the text type with no renderType (default).

The according database field is generated automatically.

type='text' without a given specific renderType either renders a simple <textarea> or a Rich Text field if enableRichtext is enabled in TCA and page TSconfig.

Table of contents:

Examples for multiline text fields

Multiline plain text area

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_4' => [
            'label' => 'text_4',
            'description' => 'cols=20, rows=2',
            'config' => [
                'type' => 'text',
                'cols' => 20,
                'rows' => 2,
            ],
        ],
    ],
]
Copied!

Rich text editor field

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_rte.php 
[
    'columns' => [
        'rte_1' => [
            'label' => 'rte_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'text',
                'enableRichtext' => true,
            ],
        ],
    ],
]
Copied!

Properties of the TCA column type text with or without enabled rich text

Name Type Scope
behaviour
allowLanguageSynchronization
 boolean Proc.
cols
 integer Display
default
 string Display / Proc.
enableRichtext
 boolean Display / Proc.
enableTabulator
 boolean Display
eval
 string (list of keywords) Display / Proc.
fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences
 array
localizationStateSelector
 array
otherLanguageContent
 array
fixedFont
 boolean Display
is_in
 string Display / Proc.
max
 integer Display
min
 integer Display
nullable
 boolean Proc
placeholder
 string Display
readOnly
 boolean Display
required
 boolean Display / Proc.
richtextConfiguration
 string (keyword) Display / Proc.
rows
 integer Display
search
 array Search
pidonly
 boolean
case
 boolean
andWhere
 string
softref
 string Proc.
wrap
 string (keyword) 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

$textTableField = [
    'config' => [
        'type' => 'text',
        'renderType' => 'textTable',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];
Copied!

cols

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

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

Does not apply to RTE fields.

Example: A simple text editor with 2 rows
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_4' => [
            'label' => 'text_4',
            'description' => 'cols=20, rows=2',
            'config' => [
                'type' => 'text',
                'cols' => 20,
                'rows' => 2,
            ],
        ],
    ],
]
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.

enableRichtext

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

If set to true, the system renders a Rich Text Editor if that is enabled for the editor (default: yes), and if a suitable editor extension is loaded (default: rteckeditor).

If either of these requirements is not met, the system falls back to a <textarea> field.

Example: Rich text editor (RTE)
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_rte.php 
[
    'columns' => [
        'rte_1' => [
            'label' => 'rte_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'text',
                'enableRichtext' => true,
            ],
        ],
    ],
]
Copied!

enableTabulator

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

Enabling this allows to use tabs in a text field. This works well together with fixed-width fonts (monospace) for code editing.

Does not apply to RTE fields.

Example: Fixed font field with tabulators enabled
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_15' => [
            'label' => 'text_15',
            'description' => 'enableTabulator, fixedFont',
            'config' => [
                'type' => 'text',
                'enableTabulator' => true,
                'fixedFont' => true,
            ],
        ],
    ],
]
Copied!

eval

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

Configuration of field evaluation. None of these apply for RTE fields.

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, available keywords:

trim
The value in the field will have white spaces around it trimmed away.
Vendor\Extension\*
User defined form evaluations.
Example: Trimming input

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

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_7' => [
            'label' => 'text_7',
            'description' => 'eval=trim',
            'config' => [
                'type' => 'text',
                'eval' => 'trim',
            ],
        ],
    ],
]
Copied!
Example: Custom form evaluation
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_9' => [
            'label' => 'text_9',
            'description' => 'readOnly=1',
            'config' => [
                'type' => 'text',
                'readOnly' => 1,
            ],
        ],
    ],
]
Copied!

You can supply own form evaluations in an extension by creating a class with two functions: deevaluateFieldValue() called when opening the record and evaluateFieldValue() called for validation when saving the record:

EXT:styleguide/Classes/UserFunctions/FormEngine/TypeText9Eval.php

<?php

namespace TYPO3\CMS\Styleguide\UserFunctions\FormEngine;

class TypeText9Eval
{
    /**
     * Adds text "PHPfoo-evaluate" at end on saving
     */
    public function evaluateFieldValue(string $value, string $is_in, bool &$set): string
    {
        return $value . 'PHPfoo-evaluate';
    }

    /**
     * Adds text "PHPfoo-deevaluate" at end on opening
     */
    public function deevaluateFieldValue(array $parameters): string
    {
        $value = $parameters['value'];
        return $value . 'PHPfoo-deevaluate';
    }
}
Copied!
EXT:styleguide/ext_localconf.php 
<?php

// Register the class to be available in 'eval' of TCA
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tce']['formevals']
['TYPO3\\CMS\\Styleguide\\UserFunctions\\FormEngine\\TypeText9Eval'] = '';
Copied!

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.

fixedFont

fixedFont
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display
RenderType
default, textTable

Enables a fixed-width font (monospace) for the text field. This is useful when using code.

Does not apply to RTE fields.

Example: Fixed font field with tabulators enabled
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_15' => [
            'label' => 'text_15',
            'description' => 'enableTabulator, fixedFont',
            'config' => [
                'type' => 'text',
                'enableTabulator' => true,
                'fixedFont' => true,
            ],
        ],
    ],
]
Copied!

is_in

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

If a user-defined evaluation is used for the field (see eval), then this value will be passed as argument to the user-defined evaluation function.

Does not apply to RTE fields.

max

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

Adds the HTML5 attribute "maxlength" to a textarea. Prevents the field from adding more than specified number of characters. This is a client side restriction, no server side length restriction is enforced.

Does not apply for RTE fields.

Example: Textarea with a maximum of 30 characters
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_11' => [
            'label' => 'text_11',
            'description' => 'max=30',
            'config' => [
                'type' => 'text',
                'cols' => 30,
                'rows' => 4,
                'max' => 30,
            ],
        ],
    ],
]
Copied!

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.

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 text editor
EXT:some_extension/Configuration/TCA/tx_sometable.php 
<?php

$textTableField = [
    'title' => 'A nullable field',
    'config' => [
        'type' => 'text',
        'nullable' => true,
    ],
];
Copied!

placeholder

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

Placeholder text for the field.

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.

richtextConfiguration

richtextConfiguration
Type
string (keyword)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
RenderType
default

The value is a key in $GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets'] array and specifies the YAML configuration source field used for that RTE field. It does not make sense without having property enableRichtext set to true.

Extension rte_ckeditor registers three presets: default, minimal and full and points to YAML files with configuration details.

Integrators may override for instance the default key to point to an own YAML file which will affect all core backend RTE instances to use that configuration.

If this property is not specified for an RTE field, the system will fall back to the default configuration. The preset can be overridden with page TSconfig RTE.

See also Examples for Rich text editor fields in the TYPO3 Backend.

rows

rows
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display
RenderType
textTable, codeEditor, default

The number of rows in the textarea. May be corrected for harmonization between browsers. Will also automatically be increased if the content in the field is found to be of a certain length, thus the field will automatically fit the content. Default is 5. Max value is 20.

Does not apply to RTE fields.

A simple text editor with 2 rows
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_4' => [
            'label' => 'text_4',
            'description' => 'cols=20, rows=2',
            'config' => [
                'type' => 'text',
                'cols' => 20,
                'rows' => 2,
            ],
        ],
    ],
]
Copied!

search

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

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:my_extension/Configuration/TCA/Overrides/someTable.php 
<?php

$temporaryColumns['my_editor'] = [
    'config' => [
        'type' => 'text',
        'renderType' => 'textTable',
        'search' => [
            'andWhere' => '{#type}=\'type_x\' OR {#type}=\'type_y\'',
        ],
    ],
];
Copied!

This means that the "my_editor" field of the "tx_mytable" 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.

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.

wrap

wrap
Type
string (keyword)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display
RenderType
textTable, default

Determines the wrapping of the textarea field. Does not apply to RTE fields. There are two options:

virtual (default)
The textarea automatically wraps the lines like it would be expected for editing a text.
off
The textarea will not wrap the lines as you would expect when editing some kind of code.

Examples .. _tca_example_text_5:

Textarea with no wrapping

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_5' => [
            'label' => 'text_5',
            'description' => 'wrap=off, long default text',
            'config' => [
                'type' => 'text',
                'wrap' => 'off',
                'default' => 'This textbox has wrap set to "off", so these long paragraphs should appear in one line: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean non luctus elit. In sed nunc velit. Donec gravida eros sollicitudin ligula mollis id eleifend mauris laoreet. Donec turpis magna, pulvinar id pretium eu, blandit et nisi. Nulla facilisi. Vivamus pharetra orci sed nunc auctor condimentum. Aenean volutpat posuere scelerisque. Nullam sed dolor justo. Pellentesque id tellus nunc, id sodales diam. Sed rhoncus risus a enim lacinia tincidunt. Aliquam ut neque augue.',
            ],
        ],
    ],
]
Copied!

Textarea with virtual wrapping

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php 
[
    'columns' => [
        'text_6' => [
            'label' => 'text_6',
            'description' => 'wrap=virtual, long default text',
            'config' => [
                'type' => 'text',
                'wrap' => 'virtual',
                'default' => 'This textbox has wrap set to "virtual", so these long paragraphs should appear in multiple lines (wrapped at the end of the textbox): Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean non luctus elit. In sed nunc velit. Donec gravida eros sollicitudin ligula mollis id eleifend mauris laoreet. Donec turpis magna, pulvinar id pretium eu, blandit et nisi. Nulla facilisi. Vivamus pharetra orci sed nunc auctor condimentum. Aenean volutpat posuere scelerisque. Nullam sed dolor justo. Pellentesque id tellus nunc, id sodales diam. Sed rhoncus risus a enim lacinia tincidunt. Aliquam ut neque augue.',
            ],
        ],
    ],
]
Copied!