Merge pull request #640 from craftcms/5.3

5.3

Author: AugustMiller

_redirects

@@ -46,6 +46,7 @@
 /docs/commerce/3.x/shipping-methods.html /docs/commerce/3.x/extend/shipping-methods.html
 /docs/commerce/3.x/update-cart-addresses.html /docs/commerce/3.x/addresses.html#updating-cart-addresses
 /docs/commerce/4.x/update-cart-custom-fields.html /docs/commerce/4.x/orders-carts.html#storing-data-in-custom-fields
+/docs/5.x/reference/field-types/url.html /docs/5.x/reference/field-types/link.html
 
 /docs/nitro/2.x/services/ /docs/nitro/2.x/
 /docs/nitro/usage.html /docs/nitro/2.x/usage.html

docs/.vuepress/sets/craft-cms.js

@@ -54,6 +54,7 @@ module.exports = {
             "field-types/entries",
             "field-types/icon",
             "field-types/lightswitch",
+            "field-types/link",
             "field-types/matrix",
             "field-types/money",
             "field-types/multi-select",
@@ -63,7 +64,6 @@ module.exports = {
             "field-types/table",
             "field-types/tags",
             "field-types/time",
-            "field-types/url",
             "field-types/users",
           ],
         },

docs/5.x/extend/updating-plugins.md

@@ -341,10 +341,6 @@ Craft handles multi-instance fields for you, at the field layout level.
 
 You can explicitly opt out of multi-instance support by returning `false` from a static `isMultiInstance()` method. By default, Craft treats all field types as multi-instance unless its `dbType()` method returns `null`.
 
-::: tip
-We will provide a console command for users to merge field definitions that are made redundant by multi-instance support.
-:::
-
 #### Presentation
 
 Field types whose content is useful in [element cards](#element-chips-cards) should implement `PreviewableFieldInterface`. In addition to determining whether the field can be displayed in element indexes, previewable fields are now eligible for inclusion in element cards when building field layouts.

docs/5.x/images/custom-source.png

@@ -96,7 +96,7 @@ Address queries support the following parameters:
 
 ## Address Repository
 
-The [commerceguys/addressing](https://github.com/commerceguys/addressing) library powers planet-friendly address handling and formatting, and its exhaustive repository of global address information is available to all Craft projects. If you need a list of countries, states, or provinces, for example, you can fetch them via Craft’s [Addresses](craft5:craft\services\Addresses) service, from Twig templates or PHP:
+The [commerceguys/addressing](repo:commerceguys/addressing) library powers planet-friendly address handling and formatting, and its exhaustive repository of global address information is available to all Craft projects. If you need a list of countries, states, or provinces, for example, you can fetch them via Craft’s [Addresses](craft5:craft\services\Addresses) service, from Twig templates or PHP:
 
 ::: code
 ```twig
@@ -107,7 +107,7 @@ $countries = Craft::$app->getAddresses()->getCountryRepository()->getAll();
 ```
 :::
 
-This returns an array of [Country](https://github.com/commerceguys/addressing/blob/master/src/Country/Country.php) objects, indexed by their two-letter code. You might use this to populate a drop-down menu:
+This returns an array of [Country](repo:commerceguys/addressing/blob/master/src/Country/Country.php) objects, indexed by their two-letter code. You might use this to populate a drop-down menu:
 
 ```twig
 <select name="myCountry">
@@ -256,7 +256,25 @@ The default formatter includes the following options:
 
 #### Country Names
 
-Only the two-letter “country code” is stored on addresses. To display the full country name (localized for the viewer), you must retrieve its definition from the [address repository](#address-repository):
+Only the two-letter “country code” is stored on addresses. To display the full country name (localized for the viewer), use the attached [`Country`](repo:commerceguys/addressing/blob/master/src/Country/Country.php) model: <Since ver="5.3.0" feature="Address.getCountry()" />
+
+```twig
+{% set country = address.country %}
+
+{{ country.name }}
+```
+
+Via the `Country` object, you also have access to the following data:
+
+- `countryCode` — Same ISO 3166-1 alpha-2 code as was stored on `address.countryCode`.
+- `name` — Name of the country, localized for the current site.
+- `threeLetterCode` — ISO 3166-1 alpha-3 code for the country.
+- `numericalCode` — ISO ISO 3166-1 numeric codes.
+- `currencyCode` — ISO 4217 currency code (not the symbol).
+- `timezones` — A list of PHP timezone identifiers for the country. This is not necessarily specific to the address!
+- `locale` — How the country’s name was localized.
+
+In earlier versions of Craft, you must directly retrieve its definition from the [address repository](#address-repository):
 
 ```twig
 {% set country = craft.app.getAddresses().getCountryRepository().get(address.countryCode) %}

docs/5.x/images/element-index-customize-sources.png

@@ -132,23 +132,23 @@ Types of content that might benefit from being defined as a structure include…
 
 Just like channels, entries in structures can be assigned [types](#entry-types). Structures offer great flexibility in presentation—in particular, the ability to collect nested content on a parent page, or alter the appearance of pages based on their hierarchical “depth” within a bundle of content.
 
-::: tip
-Structures can also make use of the **Maintain Hierarchy** setting on entries fields.
-:::
+Structures have the following additional settings:
 
-Entries belonging to a structure are discrete from [nested entries](#nested-entries) in [Matrix](../field-types/matrix.md) fields. Structure entries can be freely moved around in their hierarchy (receiving new “parent” elements in the process), whereas nested entries are always owned by the element they were created within.
+Max Levels
+:   Decide how many levels deep authors can organize entries.
 
-#### Custom Sources
+Default Entry Placement
+:   Choose where new entries are placed in the structure. This setting applies when that entry has no parent entry (before or after other “root” entries), _and_ when a parent is selected (before or after other entries with the same parent), as well as when an entry is [moved](#moving-entries-between-sections) into the section. <Since ver="5.3.0" feature="Moving entries between sections" />
 
-Special element sources based on existing Singles, Channels, and Structures by creating _custom sources_. Each custom source lists all entries by default, but can be filtered to only those that meet the specified **Entry Criteria**.
+Structures can also make use of the **Maintain Hierarchy** setting on [entries fields](../field-types/entries.md).
 
-To create a new custom source, go to **Entries** → **Customize Sources** (under the three dots in the sources sidebar), and from the bottom-left “+” menu choose **New custom source**:
+::: tip
+Entries belonging to a structure are discrete from [nested entries](#nested-entries) in [Matrix](../field-types/matrix.md) fields. Structure entries can be freely moved around in their hierarchy (receiving new “parent” elements in the process), whereas nested entries are always owned by the element they were created within.
+:::
 
-![Screenshot of a modal window with fields for a new custom source: Label, Condition Builder, and Table Columns](../../images/custom-source.png)
+#### Custom Sources
 
-::: warning
-This same interface is available in the search bar of any [element index](../../system/elements.md#indexes), but the condition builder interface will differ in subtle ways, as custom sources are stored in Project Config.
-:::
+You can supplement the automatic [sources](../../system/elements.md#sources) presented in the entries [element index](../../system/elements.md#indexes) with _custom sources_. Each custom source lists all entries by default, but can be filtered to only those that meet the specified **Entry Criteria**.
 
 ### Entry URI Formats
 
@@ -272,11 +272,23 @@ You can pass the token via either a query string parameter named after your <con
 For live preview, you should also consider [enabling iFrame Resizer](config5:useIframeResizer) so that Craft can maintain the page scroll position between page loads.
 :::
 
+### Moving Entries Between Sections <Since ver="5.3.0" feature="Transferring entries between sections" />
+
+Entries in [channel](#channels) and [structure](#structures) sections cane be moved to other sections that support the same [entry type](#entry-types). Use the **Move to…** element action from any entry element index, then select the new section. If the action is disabled, the entry has no suitable targets—you may be able to change its entry type _in-situ_, reconcile any custom field changes, then move it to a compatible section.
+
+When moving an entry, it’s important to note these behaviors:
+
+- If the new section is a structure, the entry will be placed at the root, according to its **Default Entry Placement** setting.
+- Drafts and revisions will be moved along with the entry and remain accessible, but only drafts that use an entry type that is allowed in the new section can be restored—same as if an entry type were _removed_ from a section.
+- If the new section has a lower **Max authors** setting, author data will remain intact and produce a validation error when saved.
+- Authors who don’t have access to the new section will also be removed, the next time the entry is saved. Permissions are still checked based on the section, not authorship.
+- Singles will never appear as targets for moving an entry.
+
 ## Nested Entries
 
 Entries also power the [Matrix](../field-types/matrix.md) and [CKEditor](plugin:ckeditor) fields, which means your [entry types](#entry-types) can represent entire pages, or the building blocks thereof. How you implement your content model and authoring experience is entirely up to you!
 
-Nested entries are an implementation of nested _elements_, a broader category of “owned” elements that also includes [addresses](addresses.md).
+Nested entries are an implementation of nested _elements_, a broader category of “owned” elements that includes [addresses](addresses.md) and powers Commerce’s product and variant architecture.
 
 ## Editing Entries
 

docs/5.x/images/fields-field-settings.png

@@ -12,7 +12,7 @@ related:
 
 # Users
 
-Users are Craft’s representation of people.
+A user is a special type of element that represents a person.
 
 <!-- more -->
 
@@ -90,7 +90,7 @@ By {{ collect(entry.authors).pluck('fullName').join(', ', ', and ') }}
 
 ### URLs
 
-Unlike most other element types, users do _not_ have a “URI format” setting, and are not factored into routing.
+Unlike most other element types, users do _not_ have a “URI format” setting or support slugs, and are not factored into routing.
 
 ## Querying Users
 

docs/5.x/images/fields-link-settings.png

@@ -26,7 +26,13 @@ Craft stores the field’s value as a capitalized, two-letter country code.
 {% endif %}
 ```
 
-To get more information about the country, use the [address repository](../element-types/addresses.md#address-repository) available via the address service:
+Craft actually returns a [`Country`](repo:commerceguys/addressing/blob/master/src/Country/Country.php) object, which has a few [additional features](../element-types/addresses.md#country-names), including the complete name (localized for the current site): <Since ver="5.3.0" description="{product} {ver} changed the data type for Country fields." />
+
+```twig
+<h1>Mail from {{ entry.country.name }}</h1>
+```
+
+In earlier versions of Craft, use the [address repository](../element-types/addresses.md#address-repository) available via the address service to get a `Country` model:
 
 ```twig
 {# Load all country data: #}
@@ -45,16 +51,19 @@ The `country` variable in this example is an instance of  [`CommerceGuys\Address
 
 You can query for elements based on a country field’s value in a familiar way:
 
-```twig
-
+```twig{3-4}
 {% set letters = craft.entries
     .section('letters')
     .fromCountry('FR')
     .toCountry('GB')
-    .dateSent()
+    .orderBy('dateSent DESC')
     .all() %}
 ```
 
+::: warning
+Queries against country fields currently only support two-letter codes, not complete names or other country properties.
+:::
+
 ### 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](../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:

docs/5.x/images/fields-link-ui.png

@@ -4,9 +4,13 @@ Icon fields allow the user to pick from a curated list of [FontAwesome](https://
 
 <!-- more -->
 
+## Settings
+
+To make FontAwesome Pro icons available, turn on the **Include Pro Icons** option. You may need to purchase a FontAwesome Pro license to use icons in your site’s front-end.
+
 ## Development
 
-The saved value is suitable for use in the front-end with your own FontAwesome library, or Craft’s bundled subset.
+The saved value is suitable for use in the front-end with your own FontAwesome library.
 
 ### Webfonts
 
@@ -18,6 +22,15 @@ Following the official [web fonts tutorial](https://fontawesome.com/docs/web/set
 
 Change `fa-solid` to another style identifier to suit your site’s appearance!
 
+If you added the FontAwesome files in `web/assets/fontawesome/*`, you would link to one or more style sheets like this:
+
+```twig
+{% css '/assets/fontawesome/fontawesome.css' %}
+{% css '/assets/fontawesome/solid.css' %}
+```
+
+You can add [`css` tags](../twig/tags.md#css) like this anywhere in your code and Craft will hoist them into the `<head>` of the document!
+
 ### SVG + JS
 
 The same HTML will work with the recommendations in the [SVG + JS tutorial](https://fontawesome.com/docs/web/setup/host-yourself/svg-js).

docs/5.x/images/fields-new.png

@@ -0,0 +1,107 @@
+---
+related:
+  - uri: ../../system/fields.md
+    label: Learn about content and custom fields
+---
+
+# Link Fields <Badge text="New!" />
+
+::: tip
+The link field replaced the URL field in [Craft 5.3](github:craftcms/cms/releases/5.3.0). Your existing fields will be automatically enhanced with the new UI. If you want to take advantage of the new features (like linking to assets, categories, and entries), check out the field’s edit screen.
+:::
+
+Link fields provide a flexible way to link to on- and off-site resources, including assets, categories, entries, email addresses, phone numbers, or arbitrary URLs.
+
+![Screenshot of the link field interface in the Craft control panel](../../images/fields-link-ui.png)
+
+A link field’s value (when populated) is always suitable for use as an anchor tag’s `href` attribute:
+
+```twig
+<a href="{{ supportType.action }}">{{ supportType.title }}</a>
+```
+
+<!-- more -->
+
+## Settings
+
+<BrowserShot
+  url="https://my-craft-project.ddev.site/admin/settings/fields/new"
+  :link="false"
+  :max-height="500"
+  caption="Adding a new link field via the control panel.">
+<img src="../../images/fields-link-settings.png" alt="Link field settings screen in the Craft control panel">
+</BrowserShot>
+
+In addition to the standard field options, Link fields have the following settings:
+
+- **Allowed Link Types** — The type of resource(s) that can be linked. Selecting more than one link type displays a dropdown menu for the author.
+  - **URL** — The value must be a valid URL, beginning with `http://` or `https://`.
+  - **Asset** — Select an [asset](../element-types/assets.md) element.
+  - **Category** — Select a [category](../element-types/categories.md) element.
+  - **Email** — The value is automatically prepended with `mailto:`.
+  - **Entry** — Select an [entry](../element-types/entries.md) element.
+  - **Phone** — The value is automatically prepended with `tel:`.
+- **Max Length** – The maximum number of characters the field can contain. (Defaults to `255`.)
+
+When selecting a link type that references elements, Craft will display a set of checkboxes that allow you to limit selection to specific [sources](../../system/elements.md#sources)—and in the case of assets, the allowable file kinds.
+
+## The Field
+
+Link fields have—at minimum—an input specific to the allowed type of link. If more than one link type is allowed, a dropdown menu will be shown before the field, allowing the author to switch between them and use a specialized input to define a value.
+
+## Development
+
+Outputting a link field in a template will return a normalized value suitable for use in an anchor tag’s `href` attribute:
+
+```twig
+{% if entry.myLinkFieldHandle %}
+  <h3>Link</h3>
+  {{ tag('a', {
+    text: 'Learn More',
+    href: entry.myLinkFieldHandle
+  }) }}
+{% endif %}
+```
+
+### `LinkData`
+
+The link field returns a <craft5:craft\fields\data\LinkData> object. When used as a string, its value is intelligently coerced to something URL-like—for element links, the element’s URL; for phone links, the number prefixed with `tel:`; and so on!
+
+You can check what type of link the author selected, or access a selected element, directly:
+
+```twig
+{% if entry.myLinkFieldHandle.type == 'entry' %}
+  {{ entry.myLinkFieldHandle.element.render() }}
+{% else %}
+  {{ entry.myLinkFieldHandle.link }}
+{% endif %}
+```
+
+The valid `type` values are `asset`, `category`, `email`, `entry`, `phone`, and `url`.
+
+Like elements, you can also render a complete anchor tag:
+
+```twig
+{{ entry.myLinkFieldHandle.link }}
+```
+
+Craft will figure out the best textual representation of the link—a selected element’s `title`, the URL (sans protocol), or the raw phone number, for example.
+
+### Relations
+
+When using an element in a link field, Craft makes the corresponding connections in its [relations](../../system/relations.md) system. This means that you can query for elements via link fields, just like other [relational fields](../../system/relations.md#custom-fields):
+
+```twig
+{% set backlinks = craft.entries()
+  .relatedTo({
+    targetElement: post,
+    field: 'myLinkField',
+  })
+  .all() %}
+
+{# -> Returns other entries connected to the given `post` via a specific link field. #}
+```
+
+::: warning
+It is not currently possible to [eager-load](../../development/eager-loading.md) link field relationships, as their element type is not known until the field data is loaded.
+:::