From 5306f405acbdcad3feb72c9a6908503f15093242 Mon Sep 17 00:00:00 2001
From: August Miller <hello@gusmiller.com>
Date: Mon, 8 Jan 2024 16:15:14 -0800
Subject: [PATCH] Add Country field page

---
 docs/.vuepress/sets/craft-cms.js   |  1 +
 docs/4.x/country-fields.md         | 84 ++++++++++++++++++++++++++++++
 docs/4.x/dev/controller-actions.md |  1 +
 docs/4.x/fields.md                 |  2 +-
 4 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 docs/4.x/country-fields.md

diff --git a/docs/.vuepress/sets/craft-cms.js b/docs/.vuepress/sets/craft-cms.js
index ade8b2900..5797f1901 100644
--- a/docs/.vuepress/sets/craft-cms.js
+++ b/docs/.vuepress/sets/craft-cms.js
@@ -176,6 +176,7 @@ module.exports = {
             "categories-fields",
             "checkboxes-fields",
             "color-fields",
+            "country-fields",
             "date-time-fields",
             "dropdown-fields",
             "email-fields",
diff --git a/docs/4.x/country-fields.md b/docs/4.x/country-fields.md
new file mode 100644
index 000000000..8c15625a3
--- /dev/null
+++ b/docs/4.x/country-fields.md
@@ -0,0 +1,84 @@
+---
+description: Select a country from the same database that powers address elements.
+---
+
+# Country Fields
+
+The **Country** field <Since ver="4.6.0" feature="The Country field" /> allows authors to select from a the same list of countries made available via [address](addresses.md) elements. When viewed as part of a form in the [control panel](control-panel.md), countries’ names will be localized into the user’s preferred language.
+
+## Settings
+
+This field has no configurable options.
+
+::: tip
+You can switch other text-based fields to use the Country field type. As long as your existing field’s values are valid two-letter country codes (or empty) and the existing field
+:::
+
+## Development
+
+Craft stores the field’s value as a capitalized, two-letter country code.
+
+```twig
+{% if entry.country is not empty %}
+  Country code: {{ entry.country }}
+{% endif %}
+```
+
+To get more information about the country, use the [address repository](addresses.md#address-repository) available via the address service:
+
+```twig
+{# Load all country data: #}
+{% set repo = craft.app.addresses.getCountryRepository() %}
+
+{# Get just the selected country: #}
+{% set country = repo.get(entry.country) %}
+
+{# Use properties of the country model: #}
+{{ country.name }} ({{ country.threeLetterCode }})
+```
+
+The `country` variable in this example is an instance of  [`CommerceGuys\Addressing\Country\Country`](repo:commerceguys/addressing/blob/master/src/Country/Country.php).
+
+### Querying by Country
+
+You can query for elements based on a country field’s value in a familiar way:
+
+```twig
+
+{% set letters = craft.entries
+    .section('letters')
+    .fromCountry('FR')
+    .toCountry('GB')
+    .dateSent()
+    .all() %}
+```
+
+### Front-end Forms
+
+Update the value of a country field on an element by submitting a two-letter country code to the [`entries/save-entry` action](dev/controller-actions.md#post-entries-save-entry). Supposing we are in a template used by the “Letters” section from the previous example, our form might look something like this:
+
+```twig
+{% set countries = craft.app.addresses.getCountryRepository().getAll() %}
+
+<form method="post">
+  {{ csrfInput() }}
+  {{ actionInput('entries/save-entry') }}
+  {{ hiddenInput('canonicalId', entry.id) }}
+
+  {{ input('text', 'title', entry.title) }}
+
+  <select name="fields[toCountry]">
+    {% for country in countries %}
+      {{ tag('option', {
+        text: country.name,
+        value: country.countryCode,
+        selected: country.countryCode == entry.toCountry,
+      }) }}
+    {% endfor %}
+  </select>
+
+  <button>Save</button>
+</form>
+```
+
+<See path="dev/controller-actions.md" description="Read more about using forms to submit data to Craft controllers." />
diff --git a/docs/4.x/dev/controller-actions.md b/docs/4.x/dev/controller-actions.md
index fb7ded2a6..c39b26234 100644
--- a/docs/4.x/dev/controller-actions.md
+++ b/docs/4.x/dev/controller-actions.md
@@ -1,4 +1,5 @@
 ---
+description: Craft has a powerful and secure HTTP API for interacting with accounts, content, and other features from your front-end.
 sidebarDepth: 2
 related:
   - uri: https://craftcms.com/knowledge-base/front-end-user-accounts
diff --git a/docs/4.x/fields.md b/docs/4.x/fields.md
index a1ff8e909..06311fe82 100644
--- a/docs/4.x/fields.md
+++ b/docs/4.x/fields.md
@@ -16,7 +16,6 @@ All fields share a few settings:
 - **Instructions** – Instruction text to guide authors;
 - **Field Type** – What [type](#field-types) of field it is;
 
-
 <BrowserShot url="https://my-project.tld/admin/settings/fields/new" :link="false" :max-height="500">
 <img src="./images/fields-field-settings.png">
 </BrowserShot>
@@ -37,6 +36,7 @@ Type | Description
 [Categories](categories-fields.md) | Attach category elements.
 [Checkboxes](checkboxes-fields.md) | Select any number of values from a list.
 [Color](color-fields.md) | Choose a color with the browser’s color picker UI.
+[Countries](country-fields.md) | Select from a list of countries available in [address](addresses.md) elements.
 [Date](date-time-fields.md) | Choose a date and/or time, as well as a timezone.
 [Dropdown](dropdown-fields.md) | Choose one value from a list.
 [Email](email-fields.md) | Validate text input as an email address.