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,
            ],
        ],
    ],
]

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,
            ],
        ],
    ],
]

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

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,
        ],
    ],
];

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 20 width

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,
            ],
        ],
    ],
]

default

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

Default value set if a new record is created.

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,
            ],
        ],
    ],
]

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,
            ],
        ],
    ],
]

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',
            ],
        ],
    ],
]

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,
            ],
        ],
    ],
]

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';
    }
}

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'] = '';

fieldControl: For details see fieldControl.

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.

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,
            ],
        ],
    ],
]

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

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,
            ],
        ],
    ],
]

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.

Note

This option does not work for text fields, if RTE is enabled.

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,
    ],
];

placeholder

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

Placeholder text for the field.

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.

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.

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.

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 20 width .. include:: /Images/Rst/Text4.rst.txt

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,
            ],
        ],
    ],
]

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

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

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

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\'',
        ],
    ],
];

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

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

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 wraping

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.',
            ],
        ],
    ],
]

Textarea with virtual wraping

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.',
            ],
        ],
    ],
]

text (multiline)

Examples for multiline text fields

Multiline plain text area

Rich text editor field

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

behaviour

allowLanguageSynchronization

cols

default

enableRichtext

enableTabulator

eval

fieldControl

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

fixedFont

is_in

max

min

nullable

placeholder

readOnly

required

richtextConfiguration

rows

search

pidonly

case

andWhere

softref

wrap

Textarea with no wraping

Textarea with virtual wraping

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