Repository: TYPO3-Documentation/TYPO3CMS-Reference-TCA
Pull request #1253: [FEATURE] New TCA type "country"
Author: login: linawolf
Created: 2025-04-18T09:23:50Z | Merged: 2025-04-18T10:41:46Z

References: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1232
Releases: main


Diff:
diff --git a/Documentation/ColumnsConfig/Type/Country/Index.rst b/Documentation/ColumnsConfig/Type/Country/Index.rst
new file mode 100644
index 000000000..903de56e5
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/Index.rst
@@ -0,0 +1,83 @@
+:navigation-title: Country
+
+..  include:: /Includes.rst.txt
+..  _columns-country:
+
+=======================
+Country picker TCA type
+=======================
+
+..  versionadded:: 14.0
+
+The TCA type :php:`country` can be used to render a country picker. Its main
+purpose is to use the
+`Country API <https://docs.typo3.org/permalink/t3coreapi:country-api>`_ to provide
+a country selection in the backend and use the stored representation in Extbase
+or TypoScript output.
+
+..  seealso::
+    *   `Country API <https://docs.typo3.org/permalink/t3coreapi:country-api>`_
+    *   `Form.countrySelect ViewHelper <f:form.countrySelect> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-countryselect>`_
+
+..  contents::
+    :caption: Table of contents
+
+..  _columns-country-example:
+
+Example: Define a basic country picker
+======================================
+
+..  figure:: /Images/ManualScreenshots/CountryBasic.png
+    :alt: 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.
+
+.. tabs::
+
+    ..  group-tab:: TCA
+
+        ..  literalinclude:: _country-basic.php
+            :caption: packages/my_extension/Configuration/TCA/tx_myextension_domain_model_address.php
+
+    ..  group-tab:: Flexform
+
+        ..  literalinclude:: _country-basic-flex.xml
+            :caption: packages/my_extension/Configuration/FlexForms/Address.xml
+
+..  _columns-country-example-extended:
+
+Extended country picker example
+===============================
+
+The following example demonstrates most of the properties of the
+country picker TCA type:
+
+.. tabs::
+
+    ..  group-tab:: TCA
+
+        ..  literalinclude:: _country-extended.php
+            :caption: packages/my_extension/Configuration/TCA/tx_myextension_domain_model_address.php
+
+    ..  group-tab:: Flexform
+
+        ..  literalinclude:: _country-extended-flex.xml
+            :caption: packages/my_extension/Configuration/FlexForms/Address.xml
+
+Additional countries can be added via the
+`BeforeCountriesEvaluatedEvent <https://docs.typo3.org/permalink/t3coreapi:beforecountriesevaluatedevent>`_.
+
+..  _columns-country-properties:
+
+Properties of TCA column type `country`
+=======================================
+
+..  confval-menu::
+    :name: country
+    :display: table
+    :type:
+    :Scope:
+
+    ..  include:: _Properties/_*.rst.txt
+        :show-buttons:
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_Default.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_Default.rst.txt
new file mode 100644
index 000000000..b68239219
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_Default.rst.txt
@@ -0,0 +1,8 @@
+..  confval:: default
+    :name: country-default
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
+    :type: string
+    :Scope: Display  / Proc.
+
+    Default value as ISO2 code set if a new record is created. If empty,
+    no country gets selected.
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_Filter.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_Filter.rst.txt
new file mode 100644
index 000000000..a43acc585
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_Filter.rst.txt
@@ -0,0 +1,28 @@
+..  confval:: filter
+    :name: country-filter
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']
+
+    ..  confval:: onlyCountries
+        :name: country-filter-onlyCountries
+        :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']['onlyCountries']
+        :type: array of strings
+        :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 <https://docs.typo3.org/permalink/t3coreapi:beforecountriesevaluatedevent>`_.
+
+    ..  confval:: excludeCountries
+        :name: country-filter-excludeCountries
+        :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['filter']['excludeCountries']
+        :type: array of strings
+        :Scope: Display
+        :Default: `[]`
+        :Example: `['DE', 'AT', 'CH']`
+
+        Exclude the countries (ISO2 or ISO3 codes) in this list from being
+        displayed in the selector.
+
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_LabelField.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_LabelField.rst.txt
new file mode 100644
index 000000000..2c05e1d73
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_LabelField.rst.txt
@@ -0,0 +1,6 @@
+..  confval:: labelField
+    :name: country-labelfield
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['labelField']
+    :type: string, one of `localizedName`, `name`, `iso2`, `iso3`, `officialName`, `localizedOfficialName`
+    :Scope: Display
+    :Default: `name`
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_PrioritizedCountries.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_PrioritizedCountries.rst.txt
new file mode 100644
index 000000000..21a6107d0
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_PrioritizedCountries.rst.txt
@@ -0,0 +1,9 @@
+..  confval:: prioritizedCountries
+    :name: country-prioritizedCountries
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['prioritizedCountries']
+    :type: array of strings
+    :Scope: Display
+    :Default: `[]`
+    :Example: `['DE', 'AT', 'CH']`
+
+    Countries (ISO2 or ISO3 codes) which are listed before all others countries.
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_ReadOnly.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_ReadOnly.rst.txt
new file mode 100644
index 000000000..84c08f8a8
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_ReadOnly.rst.txt
@@ -0,0 +1,11 @@
+..  confval:: readOnly
+    :name: country-readOnly
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
+    :type: boolean
+    :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 :ref:`DataHandler <t3coreapi:tce>`.
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_Required.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_Required.rst.txt
new file mode 100644
index 000000000..55d1d3ce9
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_Required.rst.txt
@@ -0,0 +1,9 @@
+..  confval:: required
+    :name: country-required
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: boolean
+    :Scope: Display / Proc.
+    :Default: false
+
+    If set to true a non-empty value is required in the field. Otherwise the
+    form cannot be saved.
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_Size.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_Size.rst.txt
new file mode 100644
index 000000000..393d3d14f
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_Size.rst.txt
@@ -0,0 +1,14 @@
+..  confval:: size
+    :name: country-size
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['size']
+    :type: integer
+    :Scope: Display
+    :Default: 1
+
+    If set to 1 (default), displays a select drop-down, else a
+    select box of given size.
+
+    ..  figure:: /Images/ManualScreenshots/CountrySizeBasic.png
+        :alt: A country select box
+
+
diff --git a/Documentation/ColumnsConfig/Type/Country/_Properties/_SortItems.rst.txt b/Documentation/ColumnsConfig/Type/Country/_Properties/_SortItems.rst.txt
new file mode 100644
index 000000000..3ed3df354
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_Properties/_SortItems.rst.txt
@@ -0,0 +1,8 @@
+..  confval:: sortItems.label
+    :name: country-sortItems-label
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['sortItems']['label']
+    :type: string, one of `asc`, `desc`
+    :Scope: Display
+    :Default: `asc`
+
+    Sort order of the select items in the country picker.
diff --git a/Documentation/ColumnsConfig/Type/Country/_country-basic-flex.xml b/Documentation/ColumnsConfig/Type/Country/_country-basic-flex.xml
new file mode 100644
index 000000000..88420bff4
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_country-basic-flex.xml
@@ -0,0 +1,8 @@
+<settings.country>
+    <label>Country of Receiver</label>
+    <config>
+        <type>country</type>
+        <labelField>iso2</labelField>
+        <default>CH</default>
+    </config>
+</settings.country>
diff --git a/Documentation/ColumnsConfig/Type/Country/_country-basic.php b/Documentation/ColumnsConfig/Type/Country/_country-basic.php
new file mode 100644
index 000000000..fbfc3f6d1
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_country-basic.php
@@ -0,0 +1,15 @@
+<?php
+
+return [
+    // ...
+    'columns' => [
+        'my-country' => [
+            'label' => 'Country of Receiver',
+            'config' => [
+                'type' => 'country',
+                'labelField' => 'iso2',
+                'default' => 'CH',
+            ],
+        ],
+    ],
+];
diff --git a/Documentation/ColumnsConfig/Type/Country/_country-extended-flex.xml b/Documentation/ColumnsConfig/Type/Country/_country-extended-flex.xml
new file mode 100644
index 000000000..210b266aa
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_country-extended-flex.xml
@@ -0,0 +1,33 @@
+<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>
diff --git a/Documentation/ColumnsConfig/Type/Country/_country-extended.php b/Documentation/ColumnsConfig/Type/Country/_country-extended.php
new file mode 100644
index 000000000..9c652cbeb
--- /dev/null
+++ b/Documentation/ColumnsConfig/Type/Country/_country-extended.php
@@ -0,0 +1,30 @@
+<?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,
+            ],
+        ],
+    ],
+];
diff --git a/Documentation/Images/ManualScreenshots/CountryBasic.png b/Documentation/Images/ManualScreenshots/CountryBasic.png
new file mode 100644
index 000000000..b5908a08d
Binary files /dev/null and b/Documentation/Images/ManualScreenshots/CountryBasic.png differ
diff --git a/Documentation/Images/ManualScreenshots/CountrySizeBasic.png b/Documentation/Images/ManualScreenshots/CountrySizeBasic.png
new file mode 100644
index 000000000..1823f205e
Binary files /dev/null and b/Documentation/Images/ManualScreenshots/CountrySizeBasic.png differ


Reviews:
user: login: sarahmccarthy123
body: Looks good
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-18T10:27:53Z
user: login: froemken
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-18T10:41:37Z
user: login: fe-hicking
body: Cool this looks great. I assume the frontend part goes somewhere else right? :)
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-18T12:19:32Z
user: login: linawolf
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-18T13:39:15Z

Review comments:
diff_hunk: @@ -0,0 +1,83 @@
+:navigation-title: Country
+
+..  include:: /Includes.rst.txt
+..  _columns-country:
+
+=======================
+Country picker TCA type
+=======================
+
+..  versionadded:: 14.0
+
+The TCA type :php:`country` can be used to render a country picker. Its main
+purpose is to use the
+`Country API <https://docs.typo3.org/permalink/t3coreapi:country-api>`_ to provide
+a country selection in the backend and use the stored representation in Extbase
+or TypoScript output.
+
+..  seealso::
+    *   `Country API <https://docs.typo3.org/permalink/t3coreapi:country-api>`_
+    *   `Form.countrySelect ViewHelper <f:form.countrySelect> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-countryselect>`_
+
+..  contents::
+    :caption: Table of contents
+
+..  _columns-country-example:
+
+Example: Define a basic country picker
+======================================
+
+..  figure:: /Images/ManualScreenshots/CountryBasic.png
+    :alt: 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`)
path: Documentation/ColumnsConfig/Type/Country/Index.rst
user: login: fe-hicking
body: ```suggestion
The following code displays a basic country picker with Switzerland (Iso code `CH`)
```

created_at: 2025-04-18T12:17:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,83 @@
+:navigation-title: Country
+
+..  include:: /Includes.rst.txt
+..  _columns-country:
+
+=======================
+Country picker TCA type
+=======================
+
+..  versionadded:: 14.0
+
+The TCA type :php:`country` can be used to render a country picker. Its main
+purpose is to use the
+`Country API <https://docs.typo3.org/permalink/t3coreapi:country-api>`_ to provide
+a country selection in the backend and use the stored representation in Extbase
+or TypoScript output.
+
+..  seealso::
+    *   `Country API <https://docs.typo3.org/permalink/t3coreapi:country-api>`_
+    *   `Form.countrySelect ViewHelper <f:form.countrySelect> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-countryselect>`_
+
+..  contents::
+    :caption: Table of contents
+
+..  _columns-country-example:
+
+Example: Define a basic country picker
+======================================
+
+..  figure:: /Images/ManualScreenshots/CountryBasic.png
+    :alt: 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`)
path: Documentation/ColumnsConfig/Type/Country/Index.rst
user: login: linawolf
body: Sorry, please make a follwo up
created_at: 2025-04-18T13:39:15Z
author_association: MEMBER

PR comments:
user: login: froemken
created_at: 2025-04-18T10:42:08Z
body: What a work. Thank you
author_association: CONTRIBUTOR
user: login: linawolf
created_at: 2025-04-18T13:39:04Z
body: The frontend part does not really fit into the TCA reference. Fluid part can go to the Fluid ViewHelper reference, TypoScript part not sure yet, they seems to be standard data processors. For the extbase part I am currently creating a page with possible property types because we have no place to document them yet

author_association: MEMBER