, use `entry.type.original`.
+
+This can help improve the legibility of templates, wherein the generic `announcement` handle doesn’t describe how the entry type is actually used:
+
+```twig{2,8-11}
+{% for contentBlock in entry.myMatrixField %}
+
+ {% switch contentBlock.type.handle %}
+ {% case 'carousel'}
+ {# ... #}
+ {% case 'recommended'}
+ {# ... #}
+ {% case 'banner' %}
+ {# Perhaps “Banner” made more sense than “Announcement” in this context, when designing! #}
+
{{ contentBlock.title }}
+ {{ contentBlock.message|md }}
+ {% default %}
+ {{ contentBlock.render() }}
+ {% endswitch %}
+
+{% endfor %}
+```
+
### Dynamic Entry Titles
The **Default Title Format** field accepts an [object template](../../system/object-templates.md) (just like the **Entry URI Format** and preview target **URL Format** we looked, above), and is evaluated whenever entries with this type are saved _without an explicitly-set title_. A title format may be rendered multiple times, depending on the selected **Title Translation Method**.
@@ -67,7 +120,7 @@ The available translation methods are covered in the [custom fields documentatio
## Sections
-Sections organize and expose entry types for content authors. In each section you can define the following:
+Sections organize and expose [entry types](#entry-types) for content authors. In each section you can define the following:
- Whether entries in the section have URLs;
- What the entries’ URLs should look like;
@@ -80,7 +133,7 @@ If your project has multiple [sites](../../system/sites.md), your section can de
- Which sites entries in the section should target;
- Which sites entries are created in, by default;
-To create a new section, go to **Settings** → **Sections** and choose **New Section**.
+To create a new section, go to
+
+
+### Palette
+
+Each field contains a **Palette** of colors that authors can select from a dropdown menu.
+
+### Custom Colors
+
+Turn on **Allow custom colors** to display a compact input and color preview UI. When used in conjunction with a palette, an additional **Custom…** option is listed at the bottom of the dropdown menu.
+
+::: tip
+In [browsers that support ` object, or `null` if no color was selected.
+Accessing a color field returns a object, or `null` if no color was selected.
-By default, the bare field handle will return a hexadecimal representation of that color:
+Casting a `ColorData` object to a string by outputting it directly produces a hexadecimal representation of the color:
::: code
```twig
-{% if entry.myFieldHandle %}
+{% if entry.myColorField %}
{% endif %}
```
```php
-if ($entry->myFieldHandle) {
- echo $entry->myFieldHandle;
- // same thing
- echo $entry->myFieldHandle->getHex();
+if ($entry->myColorField) {
+ echo $entry->myColorField;
+ // …is equivalent to…
+ echo $entry->myColorField->getHex();
}
```
:::
-Here’s an impractical example illustrating each method:
+`ColorData` objects have a number of methods that streamline working with color values:
::: code
```twig
-{% if entry.myFieldHandle %}
- {{ entry.myFieldHandle }} {# output: #e5422b #}
- {{ entry.myFieldHandle.getHex() }} {# output: #e5422b #}
- {{ entry.myFieldHandle.getRgb() }} {# output: rgb(229,66,43) #}
- {{ entry.myFieldHandle.getHsl() }} {# output: hsl(7,81%,90%) #}
- {{ entry.myFieldHandle.getLuma() }} {# output: 0.38820862745098 #}
- {{ entry.myFieldHandle.getHue() }} {# output: 7 #}
- {{ entry.myFieldHandle.getLightness() }} {# output: 90 #}
- {{ entry.myFieldHandle.getSaturation() }} {# output: 81 #}
- {{ entry.myFieldHandle.getRed() }} {# output: 229 #}
- {{ entry.myFieldHandle.getGreen() }} {# output: 66 #}
- {{ entry.myFieldHandle.getBlue() }} {# output: 43 #}
+{% if entry.myColorField %}
+ {{ entry.myColorField }} {# output: #e5422b #}
+ {{ entry.myColorField.getHex() }} {# output: #e5422b #}
+ {{ entry.myColorField.getRgb() }} {# output: rgb(229,66,43) #}
+ {{ entry.myColorField.getHsl() }} {# output: hsl(7,81%,90%) #}
+ {{ entry.myColorField.getLuma() }} {# output: 0.38820862745098 #}
+ {{ entry.myColorField.getHue() }} {# output: 7 #}
+ {{ entry.myColorField.getLightness() }} {# output: 90 #}
+ {{ entry.myColorField.getSaturation() }} {# output: 81 #}
+ {{ entry.myColorField.getRed() }} {# output: 229 #}
+ {{ entry.myColorField.getGreen() }} {# output: 66 #}
+ {{ entry.myColorField.getBlue() }} {# output: 43 #}
{% endif %}
```
```php
-if ($entry->myFieldHandle) {
- echo $entry->myFieldHandle; // output: #e5422b
- echo $entry->myFieldHandle->getHex(); // output: #e5422b
- echo $entry->myFieldHandle->getRgb(); // output: rgb(229,66,43)
- echo $entry->myFieldHandle->getHsl(); // output: hsl(7,81%,90%)
- echo $entry->myFieldHandle->getLuma(); // output: 0.38820862745098
- echo $entry->myFieldHandle->getHue(); // output: 7
- echo $entry->myFieldHandle->getLightness(); // output: 90
- echo $entry->myFieldHandle->getSaturation(); // output: 81
- echo $entry->myFieldHandle->getRed(); // output: 229
- echo $entry->myFieldHandle->getGreen(); // output: 66
- echo $entry->myFieldHandle->getBlue(); // output: 43
+if ($entry->myColorField) {
+ echo $entry->myColorField; // output: #e5422b
+ echo $entry->myColorField->getHex(); // output: #e5422b
+ echo $entry->myColorField->getRgb(); // output: rgb(229,66,43)
+ echo $entry->myColorField->getHsl(); // output: hsl(7,81%,90%)
+ echo $entry->myColorField->getLuma(); // output: 0.38820862745098
+ echo $entry->myColorField->getHue(); // output: 7
+ echo $entry->myColorField->getLightness(); // output: 90
+ echo $entry->myColorField->getSaturation(); // output: 81
+ echo $entry->myColorField->getRed(); // output: 229
+ echo $entry->myColorField->getGreen(); // output: 66
+ echo $entry->myColorField->getBlue(); // output: 43
}
```
:::
::: tip
-The example omits the `getL()`, `getS()`, `getR()`, `getG()`, and `getB()` methods, which are abbreviated forms of `getLuma()`, `getSaturation()`, `getRed()`, `getGreen()`, and `getBlue()` respectively.
+Refer to the [`ColorData`](craft5:craft\fields\data\ColorData) class reference for a complete list of methods!
:::
+
+## Querying by Color
+
+There are no special query features for color fields; refer to the [plain text](plain-text.md) field for a list of standard string comparison syntaxes.
diff --git a/docs/5.x/reference/field-types/email.md b/docs/5.x/reference/field-types/email.md
index 31f5654ba..c68ee61ba 100644
--- a/docs/5.x/reference/field-types/email.md
+++ b/docs/5.x/reference/field-types/email.md
@@ -10,6 +10,10 @@ Email fields give you a normal text input that requires a valid email address.
+::: tip
+The new [Link field](link.md) also supports email addresses.
+:::
+
## Settings
Email fields have the following settings:
diff --git a/docs/5.x/reference/field-types/link.md b/docs/5.x/reference/field-types/link.md
index 691760dc2..65d4bf4c6 100644
--- a/docs/5.x/reference/field-types/link.md
+++ b/docs/5.x/reference/field-types/link.md
@@ -50,15 +50,26 @@ In addition to the standard field options, Link fields have the following settin
:::
- **Show the “Label” field** — Displays a dedicated field to override the default/generated link label.
-- **Show the “Open in a new tab” field** — Whether or not authors can choose to have links open in a new tab.
-- **Max Length** — The maximum number of characters the field can contain. (Defaults to `255`.)
+- **Advanced Fields** .
+
+#### Exact Matches
+
+Open-ended inputs aren’t ideal for storing enum-style data (leave that to a [dropdown field](dropdown.md)), but you can still query based on the exact text content of a field:
+
+```twig{3}
+{% set reds = craft.entries()
+ .section('swatches')
+ .colorGroupCode('RED')
+ .all() %}
+```
+
+#### Multiple Values
+
+Match against a list using comma-separated values or an array:
+
+```twig
+{# Separate values with commas... #}
+{% set sunrisePalette = craft.entries()
+ .section('swatches')
+ .colorGroupCode('PINK, RED, YELLOW, ORANGE')
+ .all() %}
+
+{# ...or use an array: #}
+{% set sunrisePalette = craft.entries()
+ .section('swatches')
+ .colorGroupCode(['PINK', 'RED', 'YELLOW', 'ORANGE'])
+ .all() %}
+```
+
+These examples are ultimately assembled into a `NOT IN (...)` SQL clause.
+
+#### Negation
+
+Exclude elements with a specific field value by preceding a value with `not`:
+
+```twig
+{% set notCool = craft.entries()
+ .section('swatches')
+ .colorGroupCode('not BLUE')
+ .all() %}
+```
+
+Multiple values can be excluded by preceding each term in a comma-separated list by a `not` (`'not BLUE, not GREEN'`), or by using `not` as the first item in an array (`['not', 'BLUE', 'GREEN']).
+
+::: warning
+The grouping of terms is important when combining ranges and negation! `not RED, YELLOW` means “Swatches with a color other than `RED`, _or_ swatches with a color of `YELLOW`.” On the other hand, `['not', 'RED', 'YELLOW']` means “Swatches with a color other than `RED` or `YELLOW`.” The former would exclude “red” swatches, but allow “yellow;” the latter would exclude both colors.
+:::
+
+#### Partial Matches
+
+You can query using partial matches by including an asterisk (`*`) at the beginning and/or end of a value:
+
+```twig
+{# All “pastel” families: #}
+{% set pastels = craft.entries()
+ .section('swatches')
+ .colorGroupCode('PASTEL-*')
+ .all() %}
+
+{# All “glossy” group variations: #}
+{% set glosses = craft.entries()
+ .section('swatches')
+ .colorGroupCode('*-GLOSS')
+ .all() %}
+```
+
+Combined with the above, a param like `'not *-MATTE'` is also valid. Queries that use asterisks are generally compiled into `LIKE` statements compatible with the database driver.
+
+#### Empty Values
+
+The special tokens `:empty:` and `:notempty:` can be used to find elements with a plain text field that is empty or populated, respectively. Both tokens are compiled into query conditions that compare against `null` _and_ empty string (`''`) values.
+
+#### Literal Symbols
+
+To use asterisks or commas in a query param, pass your value through the [`literal` Twig filter](../twig/filters.md#literal).
+
+#### Case-Sensitivity
+
+[Query values are case-sensitive](../../development/element-queries.md#case-sensitivity), by default. To make a query case-_insensitive_, use a hash with `value` and `caseInsensitive` keys:
+
+```twig{3-6}
+{% set reds = craft.entries()
+ .section('swatches')
+ .colorGroupCode({
+ value: 'red',
+ caseInsensitive: true,
+ })
+ .all() %}
+```
diff --git a/docs/5.x/reference/twig/global-variables.md b/docs/5.x/reference/twig/global-variables.md
index 5201290a4..3857cb492 100644
--- a/docs/5.x/reference/twig/global-variables.md
+++ b/docs/5.x/reference/twig/global-variables.md
@@ -43,6 +43,7 @@ Variable | Description
[loginUrl](#loginurl) | The URL to the front-end Login page.
[logoutUrl](#logouturl) | The URL to the front-end Logout page.
[now](#now) | The current date/time.
+[primarySite](#primarysite) .
+
+```twig
+{# Output the primary site’s name: #}
+We are a proud member of {{ primarySite.name }}
+
+{# Link to a page on the primary site: #}
+{{ tag('a', {
+ href: siteUrl('about/governance', siteId = primarySite.id),
+ text: 'Learn about our family of businesses',
+}) }}
+```
+
+`primarySite` will be a reference to the same object as [`currentSite`](#currentsite), when `currentSite.primary` is `true`. You can also retrieve the primary site via `craft.app.sites.primarySite`.
+
### `setPasswordUrl`
The URL to [`setPasswordRequestPath`](config5:setPasswordRequestPath) if it’s set. (This wraps the path in [`siteUrl`](#siteurl).)
diff --git a/docs/5.x/system/control-panel.md b/docs/5.x/system/control-panel.md
index 43f98e0c0..074ef4bb7 100644
--- a/docs/5.x/system/control-panel.md
+++ b/docs/5.x/system/control-panel.md
@@ -131,9 +131,9 @@ You can disable a utility for all users with the [`disabledUtilities` config set
The **Settings** screen is where you’ll configure the system and design your content model. Settings complement [configuration](../configure.md) are typically stored in [Project Config](project-config.md) so that you can easily deploy them to other environments.
::: tip
-Don’t see **Settings** in the main navigation? Make sure you have admin privileges, and that is enabled.
+Don’t see **Settings** in the main navigation? Make sure you have admin privileges, and that is enabled. In Craft 5.6 and later, administrators always have access to settings in [read-only mode](#read-only-mode).
-We recommend that this is enabled only in development environments.
+We recommend that this is enabled [only in development environments](../deploy.md#admin-changes).
:::
+
+
### Plugin Store
-The control panel provides an easy way to browse the [Plugin Store](plugins.md#the-plugin-store) and try or buy plugins with one click.
+The control panel provides an easy way to browse the [Plugin Store](plugins.md#the-plugin-store) and try or buy plugins with one click. Plugins can only be installed when [admin changes](config5:allowAdminChanges) are allowed.
## Tips + Tricks
diff --git a/docs/5.x/system/elements.md b/docs/5.x/system/elements.md
index 3caf3e3da..516eb1aef 100644
--- a/docs/5.x/system/elements.md
+++ b/docs/5.x/system/elements.md
@@ -139,7 +139,7 @@ Both chips and cards support thumbnails, but only cards allow additional custom
#### Custom Card Attributes
+
- **Name** – the label displayed for the tab when it’s visible in the editor.
- **Current User Condition** – optional rules for determining which users should see the tab in the editor. (When the tab is not displayed, its fields are hidden regardless of their individual conditions.)
@@ -130,17 +139,28 @@ A tab’s settings include its name and optional conditions that determine when
### Field Layout Elements
-Add however many fields you’d like to each tab, dragging them into your desired order. Most layouts include at least a **Title** field by default—even if it’s marked as _hidden_. Any available fields and UI elements will be available at the right edge of the layout designer, where you can drag them from the sidebar into your field layout. You can move fields back to the sidebar and out of your field layout (unless they’re _mandatory_ fields for the element type), but take care not to remove any fields already being used for important content.
+Add fields to any tab using the **+ Add** button, then dragging them into the desired order. Most layouts include at least a **Title** field by default—even if it’s marked as _hidden_. To remove a field, select **Remove** from its action
+
The field’s settings let you control how and when it’s displayed:
-- **Label** – Override the field’s default label.
+- **Label** – Override the field’s default label, or hide it entirely.
- **Handle** – Override the field’s handle.
- **Instructions** – Override the field’s default instructions.
- **Current User Condition** – Set rules for determining which users can see the field and change its value.
@@ -153,7 +173,7 @@ The field’s settings let you control how and when it’s displayed:
Only one field can be used as an element’s thumbnail at a time.
:::
-Some field layout elements’ settings are bubbled up to the layout designer, beside the field’s name:
+Some field layout elements’ settings are bubbled up to the layout designer as _indicators_, beside the field’s name:
- An _asterisk_ (
+ caption="Viewing system messages in the utilities section of the control panel. Customizing system messages is limited to Craft Pro.">
Click on any message to open a modal and edit its subject and body.
::: tip
-Running a multi-site installation? You can customize system messages on a per-site basis using the site selection menu in the upper-right corner of the message modal.
+Running a [multi-site](sites.md) installation? You can customize system messages (and [mail settings](#settings)) on a per-site basis using the site selection menu in the upper-right corner of the message editor modal.
:::
### Twig
@@ -120,8 +120,9 @@ Craft uses a single configuration for its [mailer component](craft5:craft\mail\M
:poi="{
systemAddress: [28, 14],
replyToAddress: [28, 22],
- htmlTemplate: [28, 38.5],
- transportAdapter: [20, 52],
+ htmlTemplate: [28, 39.5],
+ siteOverrides: [48, 52],
+ transportAdapter: [18, 62],
}"
caption="Email settings screen in the control panel.">
Plugin Name | `accessPlugin-[PluginHandle]`
-| Edit users | `editUsers`
-| ↳ Register users | `registerUsers`
-| ↳ Moderate users Moderation includes editing other users’ names, usernames, custom fields, and addresses. | `moderateUsers`
-| ↳ Administrate users User administration includes changing emails, sending activation and password reset emails, setting passwords, and deactivating users. This permission can be used to elevate one’s own permissions by gaining access to other administrators’ accounts! | `administrateUsers`
-| ↳ Impersonate users User impersonation allows one user to temporarily access the site as though they were another user with the same (or more restrictive) permissions. | `impersonateUsers`
-| ↳ Assign user permissions | `assignUserPermissions`
-| ↳ Assign users to this group This is not an actual permission so much as a convenience feature for automatically granting the ability to add peers to the group you are currently editing, as its handle may not be known, yet! | See note.
-| ↳ Assign users to Group Name | `assignUserGroup:[UserGroupUID]`
-| Delete users | `deleteUsers`
+| Plugin Name | `accessPlugin-[PluginHandle]`
+| View users Read-only access to user elements. In earlier versions of Craft, user management permissions were not nested within this one. Moderation includes editing other users’ names, usernames, custom fields, and addresses. | `moderateUsers`
+| User administration includes changing emails, sending activation and password reset emails, setting passwords, and deactivating users. This permission can be used to elevate one’s own permissions by gaining access to other administrators’ accounts! | `administrateUsers`
+| User impersonation allows one user to temporarily access the site as though they were another user with the same (or more restrictive) permissions. | `impersonateUsers`
+| This is not an actual permission so much as a convenience feature for automatically granting the ability to add peers to the group you are currently editing, as its handle/UUID may not be known, yet! | See note.
+| Group Name | `assignUserGroup:[UserGroupUID]`
+| Site Name Site permissions are intersected with other permissions. A user will only be able to edit something if they have access to the site and the element itself. | `editSite:[SiteUID]`
| View entries This section is repeated for each configured section. | `viewEntries:[SectionUID]`
-| ↳ Create entries | `createEntries:[SectionUID]`
-| ↳ Save entries | `saveEntries:[SectionUID]`
-| ↳ Delete entries | `deleteEntries:[SectionUID]`
-| ↳ View other users’ entries | `viewPeerEntries:[SectionUID]`
-| ↳ Save other users’ entries | `savePeerEntries:[SectionUID]`
-| ↳ Delete other users’ entries | `deletePeerEntries:[SectionUID]`
-| ↳ View other users’ drafts | `viewPeerEntryDrafts:[SectionUID]`
-| ↳ Save other users’ drafts | `savePeerEntryDrafts:[SectionUID]`
-| ↳ Delete other users’ drafts | `deletePeerEntryDrafts:[SectionUID]`
+| Global Set Name | `editGlobalSet:[GlobalSetUID]`
| View categories This section is repeated for each configured category group. | `viewCategories:[CategoryGroupUID]`
-| ↳ Save categories | `saveCategories:[CategoryGroupUID]`
-| ↳ Delete categories | `deleteCategories:[CategoryGroupUID]`
-| ↳ View other users’ drafts | `viewPeerCategoryDrafts:[CategoryGroupUID]`
-| ↳ Save other users’ drafts | `savePeerCategoryDrafts:[CategoryGroupUID]`
-| ↳ Delete other users’ drafts | `deletePeerCategoryDrafts:[CategoryGroupUID]`
+|