Country picker TCA type

New in version 14.0

The TCA type country can be used to render a country picker. Its main purpose is to use the Country API to provide a country selection in the backend and use the stored representation in Extbase or TypoScript output.

Table of contents

Example: Define a basic country picker

A country picker in the TYPO3 backend, displaying the ISO2 Code, here 'CH' and the flag of the country

The following code displays a basic country picker with Suisse (Iso code CH) as default value. The localized name is displayed to the backend users.

packages/my_extension/Configuration/TCA/tx_myextension_domain_model_address.php 
<?php

return [
    // ...
    'columns' => [
        'my-country' => [
            'label' => 'Country of Receiver',
            'config' => [
                'type' => 'country',
                'labelField' => 'iso2',
                'default' => 'CH',
            ],
        ],
    ],
];
Copied!
packages/my_extension/Configuration/FlexForms/Address.xml 
<settings.country>
    <label>Country of Receiver</label>
    <config>
        <type>country</type>
        <labelField>iso2</labelField>
        <default>CH</default>
    </config>
</settings.country>
Copied!

Extended country picker example

The following example demonstrates most of the properties of the country picker TCA type:

packages/my_extension/Configuration/TCA/tx_myextension_domain_model_address.php 
<?php

return [
    // ...
    'columns' => [
        'my-country' => [
            'label' => 'Country of Receiver',
            'config' => [
                'type' => 'country',
                // available options: name, localizedName, officialName, localizedOfficialName, iso2, iso3
                'labelField' => 'iso2',
                // countries which are listed before all others
                'prioritizedCountries' => ['AT', 'CH'],
                // sort by the label
                'sortItems' => [
                    'label' => 'asc',
                ],
                'filter' => [
                    // restrict to the given country ISO2 or ISO3 codes
                    'onlyCountries' => ['DE', 'AT', 'CH', 'FR', 'IT', 'HU', 'US', 'GR', 'ES'],
                    // exclude by the given country ISO2 or ISO3 codes
                    'excludeCountries' => ['DE', 'ES'],
                ],
                'default' => 'HU',
                // When required=false, an empty selection ('') is possible
                'required' => false,
            ],
        ],
    ],
];
Copied!
packages/my_extension/Configuration/FlexForms/Address.xml 
<settings.country>
    <label>Country</label>
    <config>
        <type>country</type>
        <labelField>iso2</labelField>
        <prioritizedCountries>
            <numIndex index="0">AT</numIndex>
            <numIndex index="1">CH</numIndex>
        </prioritizedCountries>
        <filter>
            <onlyCountries>
                <numIndex index="0">DE</numIndex>
                <numIndex index="1">AT</numIndex>
                <numIndex index="2">CH</numIndex>
                <numIndex index="3">FR</numIndex>
                <numIndex index="4">IT</numIndex>
                <numIndex index="5">HU</numIndex>
                <numIndex index="6">US</numIndex>
                <numIndex index="7">GR</numIndex>
                <numIndex index="8">ES</numIndex>
            </onlyCountries>
            <excludeCountries>
                <numIndex index="0">DE</numIndex>
                <numIndex index="1">ES</numIndex>
            </excludeCountries>
        </filter>
        <sortItems>
            <label>asc</label>
        </sortItems>
        <default>HU</default>
        <required>0</required>
    </config>
</settings.country>
Copied!

Additional countries can be added via the BeforeCountriesEvaluatedEvent.

Properties of TCA column type country

Name Type Scope
default
 string Display / Proc.
filter
onlyCountries
 array of strings Display
excludeCountries
 array of strings Display
labelField
 string, one of localizedName, name, iso2, iso3, officialName, localizedOfficialName Display
prioritizedCountries
 array of strings Display
readOnly
 boolean Display
required
 boolean Display / Proc.
size
 integer Display
sortItems.label
 string, one of asc, desc Display

default

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

Default value as ISO2 code set if a new record is created. If empty, no country gets selected.

filter

filter
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']

onlyCountries

onlyCountries
Type
array of strings
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']['onlyCountries']
Scope
Display
Default
[]
Example
['DE', 'AT', 'CH']

Restrict the displayed countries (ISO2 or ISO3 codes) to the ones listed.

Additional countries can be added via the BeforeCountriesEvaluatedEvent.

excludeCountries

excludeCountries
Type
array of strings
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']['excludeCountries']
Scope
Display
Default
[]
Example
['DE', 'AT', 'CH']

Exclude the countries (ISO2 or ISO3 codes) in this list from being displayed in the selector.

labelField

labelField
Type
string, one of localizedName, name, iso2, iso3, officialName, localizedOfficialName
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['labelField']
Scope
Display
Default
name

prioritizedCountries

prioritizedCountries
Type
array of strings
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['prioritizedCountries']
Scope
Display
Default
[]
Example
['DE', 'AT', 'CH']

Countries (ISO2 or ISO3 codes) which are listed before all others countries.

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.

size

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

If set to 1 (default), displays a select drop-down, else a select box of given size.

A country select box

sortItems.label

sortItems.label
Type
string, one of asc, desc
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['sortItems']['label']
Scope
Display
Default
asc

Sort order of the select items in the country picker.