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
The country of a speaker
The following code displays a basic country picker for the country of a speaker. The localized name is displayed to the backend users.
EXT:my_extension/Configuration/TCA/Overrides/325-tx_myextension_speaker-country.php
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_speaker', [
'country' => [
'label' => 'my_extension.db:speaker.country',
'config' => [
'type' => 'country',
'labelField' => 'localizedName',
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_speaker',
'country',
'',
'before:--div--;my_extension.db:tab.integration',
);
EXT:my_extension/Configuration/FlexForms/ConferenceList.xml
<T3DataStructure>
<sheets>
<sDEF>
<ROOT>
<sheetTitle>my_extension.db:plugin.conferencelist.sheet.general</sheetTitle>
<type>array</type>
<el>
<settings.mode>
<label>my_extension.db:plugin.conferencelist.mode</label>
<onChange>reload</onChange>
<config>
<type>select</type>
<renderType>selectSingle</renderType>
<items>
<numIndex index="0">
<label>my_extension.db:plugin.conferencelist.mode.upcoming</label>
<value>upcoming</value>
</numIndex>
<numIndex index="1">
<label>my_extension.db:plugin.conferencelist.mode.past</label>
<value>past</value>
</numIndex>
<numIndex index="2">
<label>my_extension.db:plugin.conferencelist.mode.selected</label>
<value>selected</value>
</numIndex>
</items>
</config>
</settings.mode>
<settings.conferences>
<label>my_extension.db:plugin.conferencelist.conferences</label>
<displayCond>FIELD:settings.mode:=:selected</displayCond>
<config>
<type>group</type>
<allowed>tx_myextension_conference</allowed>
</config>
</settings.conferences>
<settings.categories>
<label>my_extension.db:plugin.conferencelist.categories</label>
<config>
<type>category</type>
</config>
</settings.categories>
<settings.display>
<label>my_extension.db:plugin.conferencelist.display</label>
<config>
<type>check</type>
<items>
<numIndex index="0">
<label>my_extension.db:plugin.conferencelist.display.logo</label>
</numIndex>
<numIndex index="1">
<label>my_extension.db:plugin.conferencelist.display.location</label>
</numIndex>
<numIndex index="2">
<label>my_extension.db:plugin.conferencelist.display.speakers</label>
</numIndex>
<numIndex index="3">
<label>my_extension.db:plugin.conferencelist.display.date</label>
</numIndex>
</items>
<cols>3</cols>
<default>15</default>
</config>
</settings.display>
<settings.limit>
<label>my_extension.db:plugin.conferencelist.limit</label>
<displayCond>
<or>
<value1>FIELD:settings.mode:=:upcoming</value1>
<value2>FIELD:settings.mode:=:past</value2>
</or>
</displayCond>
<config>
<type>number</type>
<default>10</default>
</config>
</settings.limit>
<settings.country>
<label>my_extension.db:plugin.conferencelist.country</label>
<config>
<type>country</type>
<labelField>localizedName</labelField>
<size>4</size>
<prioritizedCountries>
<numIndex index="0">CH</numIndex>
<numIndex index="1">DE</numIndex>
<numIndex index="2">AT</numIndex>
</prioritizedCountries>
</config>
</settings.country>
<settings.timezone>
<label>my_extension.db:plugin.conferencelist.timezone</label>
<config>
<type>select</type>
<renderType>selectSingle</renderType>
<items>
<numIndex index="0">
<label></label>
<value></value>
</numIndex>
</items>
<itemsProcessors>
<numIndex index="100">
<class>MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor</class>
<parameters>
<regions>Europe</regions>
</parameters>
</numIndex>
</itemsProcessors>
</config>
</settings.timezone>
</el>
</ROOT>
</sDEF>
<sHighlights>
<ROOT>
<sheetTitle>my_extension.db:plugin.conferencelist.sheet.highlights</sheetTitle>
<sheetDescription>my_extension.db:plugin.conferencelist.sheet.highlights.description</sheetDescription>
<type>array</type>
<el>
<settings.introduction>
<label>my_extension.db:plugin.conferencelist.introduction</label>
<config>
<type>text</type>
<enableRichtext>1</enableRichtext>
</config>
</settings.introduction>
<settings.highlights>
<title>my_extension.db:plugin.conferencelist.highlights</title>
<type>array</type>
<section>1</section>
<el>
<highlight>
<title>my_extension.db:plugin.conferencelist.highlight</title>
<type>array</type>
<el>
<title>
<label>my_extension.db:plugin.conferencelist.highlight.title</label>
<config>
<type>input</type>
</config>
</title>
<link>
<label>my_extension.db:plugin.conferencelist.highlight.link</label>
<config>
<type>link</type>
</config>
</link>
</el>
</highlight>
</el>
</settings.highlights>
</el>
</ROOT>
</sHighlights>
</sheets>
</T3DataStructure>
Extended country picker example
The following example demonstrates most of the properties of the country picker TCA type. A location can only be in one of a few countries, and Switzerland, Germany, and Austria are listed first:
The country of a location
EXT:my_extension/Configuration/TCA/Overrides/410-tx_myextension_location-country.php
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
'country' => [
'label' => 'my_extension.db:location.country',
'config' => [
'type' => 'country',
'labelField' => 'localizedName',
// Listed first, before all other countries
'prioritizedCountries' => ['CH', 'DE', 'AT'],
'filter' => [
// Conferences take place in these countries only
'onlyCountries' => ['AT', 'CH', 'DE', 'FR', 'IT', 'LI'],
],
'sortItems' => [
'label' => 'asc',
],
'default' => 'CH',
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_location',
'country',
'',
'after:--palette--;;address',
);
EXT:my_extension/Configuration/FlexForms/ConferenceList.xml
<T3DataStructure>
<sheets>
<sDEF>
<ROOT>
<sheetTitle>my_extension.db:plugin.conferencelist.sheet.general</sheetTitle>
<type>array</type>
<el>
<settings.mode>
<label>my_extension.db:plugin.conferencelist.mode</label>
<onChange>reload</onChange>
<config>
<type>select</type>
<renderType>selectSingle</renderType>
<items>
<numIndex index="0">
<label>my_extension.db:plugin.conferencelist.mode.upcoming</label>
<value>upcoming</value>
</numIndex>
<numIndex index="1">
<label>my_extension.db:plugin.conferencelist.mode.past</label>
<value>past</value>
</numIndex>
<numIndex index="2">
<label>my_extension.db:plugin.conferencelist.mode.selected</label>
<value>selected</value>
</numIndex>
</items>
</config>
</settings.mode>
<settings.conferences>
<label>my_extension.db:plugin.conferencelist.conferences</label>
<displayCond>FIELD:settings.mode:=:selected</displayCond>
<config>
<type>group</type>
<allowed>tx_myextension_conference</allowed>
</config>
</settings.conferences>
<settings.categories>
<label>my_extension.db:plugin.conferencelist.categories</label>
<config>
<type>category</type>
</config>
</settings.categories>
<settings.display>
<label>my_extension.db:plugin.conferencelist.display</label>
<config>
<type>check</type>
<items>
<numIndex index="0">
<label>my_extension.db:plugin.conferencelist.display.logo</label>
</numIndex>
<numIndex index="1">
<label>my_extension.db:plugin.conferencelist.display.location</label>
</numIndex>
<numIndex index="2">
<label>my_extension.db:plugin.conferencelist.display.speakers</label>
</numIndex>
<numIndex index="3">
<label>my_extension.db:plugin.conferencelist.display.date</label>
</numIndex>
</items>
<cols>3</cols>
<default>15</default>
</config>
</settings.display>
<settings.limit>
<label>my_extension.db:plugin.conferencelist.limit</label>
<displayCond>
<or>
<value1>FIELD:settings.mode:=:upcoming</value1>
<value2>FIELD:settings.mode:=:past</value2>
</or>
</displayCond>
<config>
<type>number</type>
<default>10</default>
</config>
</settings.limit>
<settings.country>
<label>my_extension.db:plugin.conferencelist.country</label>
<config>
<type>country</type>
<labelField>localizedName</labelField>
<size>4</size>
<prioritizedCountries>
<numIndex index="0">CH</numIndex>
<numIndex index="1">DE</numIndex>
<numIndex index="2">AT</numIndex>
</prioritizedCountries>
</config>
</settings.country>
<settings.timezone>
<label>my_extension.db:plugin.conferencelist.timezone</label>
<config>
<type>select</type>
<renderType>selectSingle</renderType>
<items>
<numIndex index="0">
<label></label>
<value></value>
</numIndex>
</items>
<itemsProcessors>
<numIndex index="100">
<class>MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor</class>
<parameters>
<regions>Europe</regions>
</parameters>
</numIndex>
</itemsProcessors>
</config>
</settings.timezone>
</el>
</ROOT>
</sDEF>
<sHighlights>
<ROOT>
<sheetTitle>my_extension.db:plugin.conferencelist.sheet.highlights</sheetTitle>
<sheetDescription>my_extension.db:plugin.conferencelist.sheet.highlights.description</sheetDescription>
<type>array</type>
<el>
<settings.introduction>
<label>my_extension.db:plugin.conferencelist.introduction</label>
<config>
<type>text</type>
<enableRichtext>1</enableRichtext>
</config>
</settings.introduction>
<settings.highlights>
<title>my_extension.db:plugin.conferencelist.highlights</title>
<type>array</type>
<section>1</section>
<el>
<highlight>
<title>my_extension.db:plugin.conferencelist.highlight</title>
<type>array</type>
<el>
<title>
<label>my_extension.db:plugin.conferencelist.highlight.title</label>
<config>
<type>input</type>
</config>
</title>
<link>
<label>my_extension.db:plugin.conferencelist.highlight.link</label>
<config>
<type>link</type>
</config>
</link>
</el>
</highlight>
</el>
</settings.highlights>
</el>
</ROOT>
</sHighlights>
</sheets>
</T3DataStructure>
Additional countries can be added via the BeforeCountriesEvaluatedEvent.
Properties of TCA column type country
| Name | Type | Scope |
|---|---|---|
| string | Display / Proc. | |
| array of strings | Display | |
| array of strings | Display | |
string, one of localized, name, iso2, iso3, official, localized
|
Display | |
| array of strings | Display | |
| boolean | Display | |
| boolean | Display / Proc. | |
| integer | Display | |
string, one of asc, desc
|
Display |
-
- Type
- string
- TCA 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.
-
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']
-
- Type
- array of strings
- Default
[]- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']['onlyCountries']
- Scope
- Display
- Examples
['DE', 'AT', 'CH']
Restrict the displayed countries (ISO2 or ISO3 codes) to the ones listed.
Additional countries can be added via the BeforeCountriesEvaluatedEvent.
-
- Type
- array of strings
- Default
[]- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']['excludeCountries']
- Scope
- Display
- Examples
['DE', 'AT', 'CH']
Exclude the countries (ISO2 or ISO3 codes) in this list from being displayed in the selector.
-
- Type
- string, one of
localized,Name name,iso2,iso3,official,Name localizedOfficial Name - Default
name- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['labelField']
- Scope
- Display
-
- Type
- array of strings
- Default
[]- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['prioritizedCountries']
- Scope
- Display
- Examples
['DE', 'AT', 'CH']
Countries (ISO2 or ISO3 codes) which are listed before all others countries.
-
- Type
- boolean
- TCA 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.
-
- Type
- boolean
- Default
- false
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['required']
- Scope
- Display / Proc.
If set to true a non-empty value is required in the field. Otherwise the form cannot be saved.
-
- Type
- integer
- Default
- 1
- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['size']
- Scope
- Display
If set to 1 (default), displays a select drop-down, else a select box of given size.
A country select box with a size of 4 in the FlexForm of a plugin
EXT:my_extension/Configuration/FlexForms/ConferenceList.xml<T3DataStructure> <sheets> <sDEF> <ROOT> <sheetTitle>my_extension.db:plugin.conferencelist.sheet.general</sheetTitle> <type>array</type> <el> <settings.mode> <label>my_extension.db:plugin.conferencelist.mode</label> <onChange>reload</onChange> <config> <type>select</type> <renderType>selectSingle</renderType> <items> <numIndex index="0"> <label>my_extension.db:plugin.conferencelist.mode.upcoming</label> <value>upcoming</value> </numIndex> <numIndex index="1"> <label>my_extension.db:plugin.conferencelist.mode.past</label> <value>past</value> </numIndex> <numIndex index="2"> <label>my_extension.db:plugin.conferencelist.mode.selected</label> <value>selected</value> </numIndex> </items> </config> </settings.mode> <settings.conferences> <label>my_extension.db:plugin.conferencelist.conferences</label> <displayCond>FIELD:settings.mode:=:selected</displayCond> <config> <type>group</type> <allowed>tx_myextension_conference</allowed> </config> </settings.conferences> <settings.categories> <label>my_extension.db:plugin.conferencelist.categories</label> <config> <type>category</type> </config> </settings.categories> <settings.display> <label>my_extension.db:plugin.conferencelist.display</label> <config> <type>check</type> <items> <numIndex index="0"> <label>my_extension.db:plugin.conferencelist.display.logo</label> </numIndex> <numIndex index="1"> <label>my_extension.db:plugin.conferencelist.display.location</label> </numIndex> <numIndex index="2"> <label>my_extension.db:plugin.conferencelist.display.speakers</label> </numIndex> <numIndex index="3"> <label>my_extension.db:plugin.conferencelist.display.date</label> </numIndex> </items> <cols>3</cols> <default>15</default> </config> </settings.display> <settings.limit> <label>my_extension.db:plugin.conferencelist.limit</label> <displayCond> <or> <value1>FIELD:settings.mode:=:upcoming</value1> <value2>FIELD:settings.mode:=:past</value2> </or> </displayCond> <config> <type>number</type> <default>10</default> </config> </settings.limit> <settings.country> <label>my_extension.db:plugin.conferencelist.country</label> <config> <type>country</type> <labelField>localizedName</labelField> <size>4</size> <prioritizedCountries> <numIndex index="0">CH</numIndex> <numIndex index="1">DE</numIndex> <numIndex index="2">AT</numIndex> </prioritizedCountries> </config> </settings.country> <settings.timezone> <label>my_extension.db:plugin.conferencelist.timezone</label> <config> <type>select</type> <renderType>selectSingle</renderType> <items> <numIndex index="0"> <label></label> <value></value> </numIndex> </items> <itemsProcessors> <numIndex index="100"> <class>MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor</class> <parameters> <regions>Europe</regions> </parameters> </numIndex> </itemsProcessors> </config> </settings.timezone> </el> </ROOT> </sDEF> <sHighlights> <ROOT> <sheetTitle>my_extension.db:plugin.conferencelist.sheet.highlights</sheetTitle> <sheetDescription>my_extension.db:plugin.conferencelist.sheet.highlights.description</sheetDescription> <type>array</type> <el> <settings.introduction> <label>my_extension.db:plugin.conferencelist.introduction</label> <config> <type>text</type> <enableRichtext>1</enableRichtext> </config> </settings.introduction> <settings.highlights> <title>my_extension.db:plugin.conferencelist.highlights</title> <type>array</type> <section>1</section> <el> <highlight> <title>my_extension.db:plugin.conferencelist.highlight</title> <type>array</type> <el> <title> <label>my_extension.db:plugin.conferencelist.highlight.title</label> <config> <type>input</type> </config> </title> <link> <label>my_extension.db:plugin.conferencelist.highlight.link</label> <config> <type>link</type> </config> </link> </el> </highlight> </el> </settings.highlights> </el> </ROOT> </sHighlights> </sheets> </T3DataStructure>
-
- Type
- string, one of
asc,desc - Default
asc- TCA path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['sortItems']['label']
- Scope
- Display
Sort order of the select items in the country picker.