Merge pull request #699 from craftcms/releases/craft-5.7

Craft 5.7

Author: AugustMiller

docs/.vuepress/components/Block.vue

@@ -1,24 +1,19 @@
+<template>
+  <div class="custom-block">
+    <div v-if="label" class="banner">
+      <span class="label">{{ label }}</span>
+    </div>
+    <div class="content">
+      <slot />
+    </div>
+  </div>
+</template>
+
 <script>
 export default {
-  functional: true,
   props: {
     label: String,
   },
-  render(h, { props, slots }) {
-    const content = [h('div', { class: 'content' }, slots().default)];
-
-    if (props.label) {
-        content.unshift(h(
-            'div',
-            {
-                class: 'banner',
-            },
-            [h('span', { class: 'label' }, props.label)]
-        ));
-    }
-
-    return h('div', { class: 'custom-block' }, content);
-  },
 };
 </script>
 

docs/.vuepress/components/Placeholder.vue

@@ -0,0 +1,24 @@
+<template>
+    <span class="placeholder" :title="help"><slot /></span>
+</template>
+
+<script>
+export default {
+    props: {
+        help: {
+            type: String,
+            required: false,
+        },
+    },
+};
+</script>
+
+
+<style lang="postcss" scoped>
+    .placeholder {
+        @apply border border-dashed px-1;
+
+        font-size: 0.95em;
+        cursor: help;
+    }
+</style>

docs/.vuepress/components/StatusLabel.vue

@@ -0,0 +1,73 @@
+<template>
+    <div :class="['status-label', getSlug()]">
+        <div class="status-label-pip" :style="{ backgroundColor: getColor() }"></div>
+        <div class="status-label-text">
+            {{ label }}
+        </div>
+    </div>
+</template>
+
+<script>
+    export default {
+        props: {
+            label: {
+                type: String,
+                default: 'live',
+            },
+            color: {
+                type: String,
+                default: null,
+            },
+        },
+        methods: {
+            getSlug() {
+                return this.label.toLowerCase().replace(/[^a-z]/, '-');
+            },
+            getColor() {
+                if (!this.color) {
+                    return null;
+                }
+
+                if (this.color.indexOf('#') !== 0) {
+                    return null;
+                }
+
+                return this.color;
+            },
+        },
+    };
+</script>
+
+<style lang="postcss" scoped>
+    .status-label {
+        align-items: center;
+        border-radius: 1em;
+        display: inline-flex;
+        height: 20px;
+        padding: 0 10px 0 5px;
+
+        &.live {
+            background-color: theme('colors.craft.green');
+        }
+
+        &.pending {
+            background-color: theme('colors.craft.orange');
+        }
+    }
+
+    .status-label-pip {
+        background-color: white;
+        border-radius: 100%;
+        height: 12px;
+        margin-right: 5px;
+        width: 12px;
+    }
+
+    .status-label-text {
+        color: white;
+        font-size: 0.7em;
+        font-weight: 600;
+        letter-spacing: 0.05em;
+        text-transform: uppercase;
+    }
+</style>

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

@@ -44,6 +44,7 @@ module.exports = {
           children: [
             "field-types/addresses",
             "field-types/assets",
+            "field-types/button-group",
             "field-types/categories",
             "field-types/checkboxes",
             "field-types/color",
@@ -52,6 +53,7 @@ module.exports = {
             "field-types/dropdown",
             "field-types/email",
             "field-types/entries",
+            "field-types/json",
             "field-types/icon",
             "field-types/lightswitch",
             "field-types/link",

docs/5.x/extend/element-types.md

@@ -4,7 +4,7 @@ description: Add native-feeling content types to empower content authors and adm
 
 # Element Types
 
-[Elements](../system/elements.md) underpin Craft’s flexible and extensible content modeling features. You can supplement Craft’s eight [built-in element types](../system/elements.md#element-types) with your own, from a plugin or module.
+[Elements](../system/elements.md) underpin Craft’s flexible and extensible content modeling features. You can supplement Craft’s seven [built-in element types](../system/elements.md#element-types) with your own, from a plugin or module.
 
 As you implement common element features like [titles](#titles), [sources](#sources), or [statuses](#statuses), the built-in element classes will be an invaluable resource—both as templates for basic functionality and evidence of the flexibility of elements.
 

docs/5.x/extend/field-types.md

@@ -52,8 +52,6 @@ class Plugin extends \craft\base\Plugin
 
 If you used the generator to scaffold the field type, it ought to have inserted this, automatically. You may register as many field types as you wish, from one `EVENT_REGISTER_FIELD_TYPES` event handler.
 
-### 
-
 ### Missing Fields
 
 If your field class ever goes missing (say, because a developer uninstalls your plugin or removes the package), Craft will use an instance of <craft5:craft\fields\MissingField>, and display a message in any field layouts it was present in. This ensures the control panel doesn’t become inoperable, but doesn’t prevent front-end templates from breaking.

docs/5.x/images/elements-statuses.png

@@ -42,6 +42,12 @@ For compatibility and localization, core address components (aside from the Coun
 
 You may set a default country for new addresses via the <config5:defaultCountryCode> setting.
 
+### Copying Addresses <Since ver="5.7.0" feature="Copying addresses" />
+
+Addresses can be copied and pasted between users and [addresses fields](../field-types/addresses.md).
+
+<See path="../../system/elements.md" hash="copying-elements" label="Copying Elements" description="Learn how to copy addresses and other elements between contexts." />
+
 ## Querying Addresses
 
 You can fetch addresses in your templates or PHP code using an [AddressQuery](craft5:craft\elements\db\AddressQuery).

docs/5.x/images/entries-copy-action.png

@@ -6,6 +6,7 @@ related:
     label: Introduction to Elements
   - uri: ../field-types/entries.md
     label: Entries Fields
+sidebarDepth: 2
 ---
 
 # Entries
@@ -126,8 +127,9 @@ Sections organize and expose [entry types](#entry-types) for content authors. In
 - Whether entries in the section have URLs;
 - What the entries’ URLs should look like;
 - Which template should get loaded if an entry’s URL is requested;
+- What preview targets are available to authors;
 - What [entry types](#entry-types) are available in the section;
-- How many authors can be associated with each entry;
+- How many authors can be associated with each entry (or disable authors <Since ver="5.7.0" feature="Authorless sections" />);
 
 If your project has multiple [sites](../../system/sites.md), your section can define these additional settings:
 
@@ -462,6 +464,81 @@ Notifications will appear in the bottom-left corner along with other flashes, an
 Automatic merging of changes from canonical entries is nondestructive, and non-optional. Merging occurs just before an entry’s edit screen is viewed.
 :::
 
+### Copying Entries <Since ver="5.7.0" feature="Copying entries" />
+
+Entries can be copied and pasted between sections and fields that support the given type(s).
+
+<See path="../../system/elements.md" hash="copying-elements" label="Copying Elements" description="Learn how to copy entries and other elements between contexts." />
+
+## Statuses
+
+In addition to the [base element statuses](../../system/elements.md#statuses), entries may appear in any of these states:
+
+- **Pending** (`pending`) — The **Post Date** is in the future, or not set.
+- **Expired** (`expired`) — The **Expiry Date** is set, and in the past.
+- **Live** (`live`) — The **Post Date** is in the past, and the **Expiry Date** is in the future (if set at all). This is the default status used in entry queries.
+
+::: tip
+Status pips and controls may be hidden from element edit screes, indexes, chips, and cards, if an entry’s type has the **Show the Status field** setting _off_.
+:::
+
+When [querying entries by status](../../system/elements.md#querying-by-status), keep in mind that each status identifier in the list above represents multiple conditions. Statuses and their default query conditions help make the appearance or availability of entries consistent between the control panel and front-end; for this reason, params like `.postDate()` and `.expiryDate()` introduce _additional_ constraints, rather than replacing Craft’s. If you need full control over the query constraints, call `.status(null)`.
+
+### Static Statuses <Since ver="5.7.0" feature="Static storage of entry statuses" />
+
+Craft’s powerful [events](../../extend/events.md) system allows developers to react to element updates, and connect author activity and content to other systems. Statuses, however, can be difficult to pin down—entries rely heavily on their **Post Date** and **Expiry Date** attributes to determine when an entry is returned, and what its “status” is at any given time.
+
+Take this query that fetches blog articles:
+
+```twig
+{% set posts = craft.entries()
+  .section('blog')
+  .all() %}
+```
+
+Suppose we have an article with a **Post Date** five minutes in the future. Loading the page with this query _now_ would not display the pending article; if we wait five minutes and refresh the page, the entry _does_ show up… without any intervention by the author! This is because each query compares the server’s current time with entries’ stored `postDate` and `expiryDate` columns; depending on when you look at the data, Craft considers it to be in different statuses. Therein lies the issue: nothing _happens_ when a pending entry “goes live” (or a live entry “expires”), so Craft can’t emit status-change events.
+
+The <config5:staticStatuses> config setting alters this behavior: instead of calculating statuses on-the-fly, Craft stores a static representation of an entry’s status at the time it is saved. Entry queries also use simplified conditions, matching against the stored values instead of date-based comparisons. In this mode, however, entries’ statuses only change when they are saved. The accompanying [`update-statuses` console command](../cli.md#update-statuses) provides a means of routinely checking and re-saving entries:
+
+```bash
+ddev craft update-statuses
+```
+
+::: warning
+If you opt in to static statuses, you must run this command with a tool like [cron](https://en.wikipedia.org/wiki/Cron) to ensure your content is published and expired in a reasonable amount of time.
+:::
+
+In a [private plugin](../../extend/plugin-guide.md) or [custom module](../../extend/module-guide.md), you can [listen for save events](kb:handling-entry-saves) and check whether an entry received a new status:
+
+```php
+use craft\base\Event;
+use craft\elements\Entry;
+use craft\events\ModelEvent;
+use craft\helpers\ElementHelper;
+
+Event::on(
+    Entry::class,
+    Entry::EVENT_AFTER_SAVE,
+    function (ModelEvent $event) {
+        /** @var Entry $entry */
+        $entry = $event->sender;
+
+        // Make sure we’re dealing with a canonical entry, and that there was indeed a status change:
+        if (
+            !ElementHelper::isDraftOrRevision($entry) &&
+            $entry->getStatus() !== $entry->oldStatus
+        ) {
+            if ($entry->getStatus() === Entry::STATUS_LIVE) {
+                // The entry just moved into the "live" status!
+            } elseif ($entry->oldStatus === Entry::STATUS_LIVE) {
+                // The entry *was* live, but isn’t any more!
+            }
+        }
+    });
+```
+
+Depending on your editorial process, you will need to adjust the cases here to handle different transitions. Keep in mind that this handler may also run in response to normal entry saves (during an HTTP request) so it is advisable to offload any time- or resource-intensive operations to a [queue job](../../extend/queue-jobs.md).
+
 ## Querying Entries
 
 When Craft receives a request matching an entry’s URI, it automatically makes an `entry` variable available. Everywhere else in your front-end (or PHP code), you can fetch entries using **entry queries**.

docs/5.x/images/entries-copy-notification.png

@@ -30,6 +30,8 @@ There are also **Preferences** for localization, accessibility, and debugging th
 
 All users share a [field layout](../../system/fields.md#field-layouts), which is managed via <Journey path="Settings, Users, User Profile Fields" />. Custom fields are added to the **Profile** tab of each user’s management screen, alongside native **Username**, **Email**, **Full Name**, and **Photo** fields.
 
+Fields and tabs in the user field layout can be given [conditions](../../system/fields.md#conditions) to provide special functionality based on their user group or other criteria.
+
 ::: tip
 Relate users to other elements with the [users field](../field-types/users.md).
 :::

docs/5.x/images/entries-copy-target.png

@@ -11,6 +11,8 @@ related:
 
 Craft has over 20 built-in field types that help create tightly-tailored authoring and developer experiences. The table below lists fields in the same order you’ll encounter them in the [control panel](../../system/control-panel.md); you can also browse them by the [type of data](#data-types) they store.
 
+<!-- more -->
+
 <See path="../system/fields.md" label="Fields + Content" description="Get started with fields in Craft." />
 
 ## All Fields
@@ -19,6 +21,7 @@ Craft has over 20 built-in field types that help create tightly-tailored authori
 | --- | --- |
 | [Addresses](addresses.md) | Manage nested [address](../element-types/addresses.md) elements. |
 | [Assets](assets.md) | Relate [asset](../element-types/assets.md) elements. |
+| [Button Group](button-group.md) | Choose a single item from a graphical, icon-based toolbar. |
 | [Categories](categories.md) | Relate [category](../element-types/categories.md) elements. |
 | [Checkboxes](checkboxes.md) | Choose one or more predefined options using `checkbox` inputs. |
 | [Color](color.md) | Pick a color with your platform’s native color picker—or provide a hexadecimal value. |
@@ -118,7 +121,7 @@ You can even attach fields to the elements you relate via these fields—metadat
 
 ### Media
 
-- [Assets](assets.md) — Upload and attach files anywhere.
+- [Assets](assets.md) — Upload and attach files to anything.
 
 ### Structured
 
@@ -137,6 +140,7 @@ Have a complex content model? You can nest entries as deeply as you want!
 Spruce up the authoring experience with these dedicated UIs.
 
 - [Color](color.md) — Select from a palette of colors, or choose a new one.
+- [Button Group](button-group.md) — Choose from options identified by an icon—great for layout, positioning, and scale controls
 - [Icon](icon.md) — Pick from a library of icons.
 - [Money](money.md) — Input values in a specific currency.
 - [Range](range.md) — Contextualize numeric values.

docs/5.x/images/fields-button-group-settings.png

@@ -16,6 +16,8 @@ Address fields are separate from users’ [address book](../element-types/users.
 <img src="../../images/fields-addresses.png" alt="Screenshot of addresses field with two nested address elements" />
 </BrowserShot>
 
+Addresses can be [copied](../../system/elements.md#copying-elements) between fields, and to or from users’ address books. <Since ver="5.7.0" feature="Copying-and-pasting address elements" />
+
 ## Settings
 
 Address fields can be displayed to editors as [cards](../../system/elements.md#chips-cards) or in a full [element index](../../system/elements.md#indexes). Either way, individual addresses are always displayed as cards.

docs/5.x/images/fields-button-group-ui.png

@@ -0,0 +1,40 @@
+---
+related:
+  - uri: radio-buttons.md
+    label: Radio Button fields
+  - uri: dropdown.md
+    label: Dropdown fields
+---
+
+# Button Group <Since ver="5.7.0" feature="The button group field" />
+
+Button group fields provide a compact, graphical option for selecting a single value from a list.
+
+<!-- more -->
+
+![Screenshot of the button group field interface in the Craft control panel](../../images/fields-button-group-ui.png)
+
+## Settings
+
+<BrowserShot
+  url="https://my-craft-project.ddev.site/admin/settings/fields/new"
+  :link="false"
+  :max-height="500"
+  caption="Adding a new button group field via the control panel.">
+<img src="../../images/fields-button-group-settings.png" alt="Button group field settings screen in the Craft control panel">
+</BrowserShot>
+
+Button group fields have the following settings:
+
+- **Options** — Define any number of options for authors to select from, each with…
+  - **Label** — A text description of the option. _Labels are hidden when using the **Icons only** setting._
+  - **Value** — The value stored when a given option is selected.
+  - **Icon** — Choose from the standard system icon palette.
+  - **Default?** — One option can be marked as the default.
+- **Icons only** — Hide labels in the UI, displaying only the selected icon for each option.
+
+The field works best with a limited number of visually distinct options.
+
+## Development
+
+Button group fields share the same template and query capabilities with [dropdown fields](dropdown.md).

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

@@ -37,8 +37,9 @@ Categories fields have the following settings:
 
   - **Min Relations** — The minimum number of categories that must be selected when the field is marked as “required” in a field layout. (Default is no minimum.)
   - **Max Relations** — The maximum number of categories that can be selected. (Default is no maximum.)
+  - **Default Category Placement** — Whether new selections are prepended or appended to the existing relations.
+  - **View Mode** — How the related users are displayed to authors (_List_ or _Cards_).
 
-- **View Mode** — How the related users are displayed to authors (_List_ or _Cards_).
 - **“Add” Button Label** — The label that should be used on the field’s selection button.
 - **Validate related categories** — Whether or not validation errors on the related categories will be bubbled up.