Merge pull request #16989 from craftcms/feature/cms-1382-default-placement-relational-field-setting

Default Placement relational field setting

Author: brandonkelly

CHANGELOG-WIP.md

@@ -36,6 +36,7 @@
 - “Template” field layout UI elements are now re-rendered on each autosave. ([#16837](https://github.com/craftcms/cms/discussions/16837))
 - Added the “SMS” link type for Link fields. ([#16850](https://github.com/craftcms/cms/discussions/16850))
 - Added the “Allow custom URL schemes” setting for Link fields with the “URL” link type enabled. ([#16850](https://github.com/craftcms/cms/discussions/16850))
+- Relational fields now have “Default [Type] Placement” settings, which control whether newly-related elements are placed before or after existing relations. ([#16989](https://github.com/craftcms/cms/pull/16989))
 - Sections’ “Max Authors” settings are now optional, allowing unlimited authors when blank. ([#16898](https://github.com/craftcms/cms/pull/16898))
 - Sections’ “Max Authors” settings can now be set to `0`, preving the “Author” field from being displayed on Edit Entry screens. ([#16898](https://github.com/craftcms/cms/pull/16898))
 - The email settings page now shows a “Test” button when `allowAdminChanges` is disabled. ([#16508](https://github.com/craftcms/cms/discussions/16508))

src/fields/BaseRelationField.php

@@ -74,6 +74,11 @@ abstract class BaseRelationField extends Field implements
      */
     public const EVENT_DEFINE_SELECTION_CRITERIA = 'defineSelectionCriteria';
 
+    /** @since 5.7.0 */
+    public const DEFAULT_PLACEMENT_BEGINNING = 'beginning';
+    /** @since 5.7.0 */
+    public const DEFAULT_PLACEMENT_END = 'end';
+
     private static bool $validatingRelatedElements = false;
 
     /**
@@ -237,6 +242,13 @@ public static function existsQueryCondition(self $field, bool $enabledOnly = tru
      */
     public ?int $branchLimit = null;
 
+    /**
+     * @var string Default placement
+     * @phpstan-var self::DEFAULT_PLACEMENT_*
+     * @since 5.7.0
+     */
+    public string $defaultPlacement = self::DEFAULT_PLACEMENT_END;
+
     /**
      * @var string|null The view mode
      */
@@ -452,6 +464,7 @@ public function settingsAttributes(): array
         $attributes[] = 'sources';
         $attributes[] = 'targetSiteId';
         $attributes[] = 'validateRelatedElements';
+        $attributes[] = 'defaultPlacement';
         $attributes[] = 'viewMode';
         $attributes[] = 'showCardsInGrid';
         $attributes[] = 'allowSelfRelations';
@@ -501,6 +514,7 @@ public function getSettingsHtml(): ?string
                     $view->namespaceInputId('branch-limit-field'),
                     $view->namespaceInputId('min-relations-field'),
                     $view->namespaceInputId('max-relations-field'),
+                    $view->namespaceInputId('default-placement-field'),
                     $view->namespaceInputId('viewMode-field'),
                 ],
         ]);
@@ -1377,6 +1391,7 @@ protected function settingsTemplateVariables(): array
 
         return [
             'field' => $this,
+            'upperElementType' => $elementType::displayName(),
             'elementType' => $elementType::lowerDisplayName(),
             'pluralElementType' => $elementType::pluralLowerDisplayName(),
             'selectionCondition' => $selectionConditionHtml ?? null,
@@ -1455,6 +1470,7 @@ protected function inputTemplateVariables(array|ElementQueryInterface $value = n
             'sourceElementId' => !empty($element->id) ? $element->id : null,
             'disabledElementIds' => $disabledElementIds,
             'limit' => $this->allowLimit ? $this->maxRelations : null,
+            'defaultPlacement' => $this->defaultPlacement,
             'viewMode' => $this->viewMode(),
             'showCardsInGrid' => $this->showCardsInGrid,
             'selectionLabel' => $this->selectionLabel ? Craft::t('site', $this->selectionLabel) : static::defaultSelectionLabel(),

src/templates/_components/fieldtypes/Assets/settings.twig

@@ -161,6 +161,7 @@
     }) }}
 
     {{ block('limitFields') }}
+    {{ block('defaultPlacementField') }}
     {{ block('viewModeField') }}
     {{ block('selectionLabelField') }}
     {{ block('validateRelatedElementsField') }}

src/templates/_components/fieldtypes/Categories/settings.twig

@@ -18,6 +18,7 @@
         }) }}
     {% endblock %}
 
+    {{ block('defaultPlacementField') }}
     {{ block('viewModeField') }}
     {{ block('selectionLabelField') }}
     {{ block('validateRelatedElementsField') }}

src/templates/_components/fieldtypes/elementfieldsettings.twig

@@ -2,6 +2,8 @@
 
 {% set sourceOptions = field.getSourceOptions() %}
 {% set elementType = elementType ?? pluralElementType %}
+{% set upperElementType = upperElementType ?? elementType|capitalize %}
+
 {% block fieldSettings %}
     {% block sourcesField %}
         {% if sourceOptions %}
@@ -91,6 +93,22 @@
         }) }}
     {% endblock %}
 
+    {% block defaultPlacementField %}
+        {{ forms.selectField({
+            label: 'Default {type} Placement'|t('app', {type: upperElementType}),
+            instructions: 'Where new {type} should be placed by default in the field.'|t('app', {type: pluralElementType}),
+            id: 'default-placement',
+            name: 'defaultPlacement',
+            options: [
+                {label: 'Before other {type}'|t('app', {type: pluralElementType}), value: 'beginning'},
+                {label: 'After other {type}'|t('app', {type: pluralElementType}), value: 'end'},
+            ],
+            value: field.defaultPlacement,
+            errors: field.getErrors('defaultPlacement'),
+            data: {'error-key': 'defaultPlacement'},
+        })}}
+    {% endblock %}
+
     {% block viewModeField %}
         {{ field.getViewModeFieldHtml()|raw }}
 

src/templates/_includes/forms/elementSelect.twig

@@ -11,6 +11,7 @@
 {% set criteria = criteria ?? null -%}
 {% set sourceElementId = sourceElementId ?? null -%}
 {% set storageKey = storageKey ?? null -%}
+{% set defaultPlacement = defaultPlacement ?? 'end' %}
 {% set viewMode = viewMode ?? 'list' %}
 {% set prevalidate = prevalidate ?? false %}
 {% set fieldId = fieldId ?? null %}
@@ -110,6 +111,7 @@
         branchLimit: branchLimit ?? null,
         sourceElementId: sourceElementId,
         disabledElementIds: disabledElementIds ?? null,
+        defaultPlacement,
         viewMode: viewMode,
         single: single,
         limit: limit,

src/translations/en/app.php

@@ -1999,6 +1999,7 @@
     'Where assets should be stored on the filesystem.' => 'Where assets should be stored on the filesystem.',
     'Where assets should be stored when they are uploaded directly to the field.' => 'Where assets should be stored when they are uploaded directly to the field.',
     'Where do you want to store user photos? Note that the subfolder path can contain variables like <code>{username}</code>.' => 'Where do you want to store user photos? Note that the subfolder path can contain variables like <code>{username}</code>.',
+    'Where new {type} should be placed by default in the field.' => 'Where new {type} should be placed by default in the field.',
     'Where new {type} should be placed by default in the structure.' => 'Where new {type} should be placed by default in the structure.',
     'Where transforms should be stored on the filesystem.' => 'Where transforms should be stored on the filesystem.',
     'Whether authors should be able to choose which time zone the time is in.' => 'Whether authors should be able to choose which time zone the time is in.',

src/web/assets/cp/dist/cp.js

@@ -987,7 +987,12 @@ Craft.BaseElementSelectInput = Garnish.Base.extend(
     },
 
     appendElement: function ($element) {
-      $('<li/>').append($element).appendTo(this.$elementsContainer);
+      const $li = $('<li/>').append($element);
+      if (this.settings.defaultPlacement === 'beginning') {
+        $li.prependTo(this.$elementsContainer);
+      } else {
+        $li.appendTo(this.$elementsContainer);
+      }
     },
 
     animateElementIntoPlace: async function ($modalElement, $inputElement) {
@@ -1124,6 +1129,7 @@ Craft.BaseElementSelectInput = Garnish.Base.extend(
       maintainHierarchy: false,
       branchLimit: null,
       limit: null,
+      defaultPlacement: 'end',
       showSiteMenu: false,
       modalStorageKey: null,
       modalSettings: {},

src/web/assets/cp/dist/cp.js.map

@@ -9,6 +9,7 @@ Craft.ElementFieldSettings = Garnish.Base.extend({
   $branchLimitField: null,
   $maxRelationsField: null,
   $minRelationsField: null,
+  $defaultPlacementField: null,
   $viewModeField: null,
 
   init: function (
@@ -18,6 +19,7 @@ Craft.ElementFieldSettings = Garnish.Base.extend({
     branchLimitFieldId,
     minRelationsFieldId,
     maxRelationsFieldId,
+    defaultPlacementFieldId,
     viewModeFieldId
   ) {
     this.allowMultipleSources = allowMultipleSources;
@@ -30,6 +32,7 @@ Craft.ElementFieldSettings = Garnish.Base.extend({
     this.$branchLimitField = $(`#${branchLimitFieldId}`);
     this.$minRelationsField = $(`#${minRelationsFieldId}`);
     this.$maxRelationsField = $(`#${maxRelationsFieldId}`);
+    this.$defaultPlacementField = $(`#${defaultPlacementFieldId}`);
     this.$viewModeField = $(`#${viewModeFieldId}`);
 
     this.updateLimitFields();
@@ -67,11 +70,13 @@ Craft.ElementFieldSettings = Garnish.Base.extend({
       this.$minRelationsField.addClass('hidden');
       this.$maxRelationsField.addClass('hidden');
       this.$branchLimitField.removeClass('hidden');
+      this.$defaultPlacementField.addClass('hidden');
       this.$viewModeField.addClass('hidden');
     } else {
       this.$branchLimitField.addClass('hidden');
       this.$minRelationsField.removeClass('hidden');
       this.$maxRelationsField.removeClass('hidden');
+      this.$defaultPlacementField.removeClass('hidden');
       this.$viewModeField.removeClass('hidden');
     }
   },